Embeddable visual component to be displayed in NetBeans.
This is the basic unit of display--windows should not be
created directly, but rather use this class.
A top component may correspond to a single window, but may also
be a tab (e.g.) in a window. It may be docked or undocked,
have selected nodes, supply actions, etc.
Important serialization note: Serialization of this TopComponent is designed
in a way that it's not desired to override writeReplace method. If you would
like to resolve to something, please implement readResolve() method directly
on your top component.

Please do not use. This support class does nothing much
useful. If you need to synchronize display name of your TopComponent
with some Node's display name, we recommend you to do it manually in
your client's code.

Field Detail

CLOSE_EACH

Deprecated.Do not use. It is redundant since workspaces are not supported anymore.

Behavior in which a top component closed (by the user) in one workspace
will be removed from every workspace.
Also, close() is called.
This is appropriate for top components such as Editor panes which
the user expects to really close (and prompt to save) when closed
in any

CLOSE_LAST

Deprecated.Do not use. It is redundant since workspaces are not supported anymore.

Behavior in which a top component closed (by the user) in one workspace
may be left in other workspaces.
Only when the last remaining manifestation in any workspace is closed
will the object be deleted using close().
Appropriate for components containing no user data, for which closing
the component is only likely to result from the user's wanting to remove
it from active view (on the current workspace).

PROP_KEEP_PREFERRED_SIZE_WHEN_SLIDED_IN

Name of TopComponent's Boolean client property which forces the window system
to respect TopComponent's preferred size when it is slided-in from left/right/bottom
sliding bar when set to Boolean.TRUE. Otherwise the slided-in TopComponent
will fill the entire width/length of the IDE window (the default behavior).
This switch is intended for tools/palette windows like e.g. color chooser,
tool picker etc.

PROP_SLIDING_DISABLED

Name of TopComponent's Boolean client property which removes 'minimized' button
from TopComponent's header and disables its 'Minimize Window' action when
set to Boolean.TRUE. TopComponents which are already slided-out and have this
property set to Boolean.TRUE will have 'pin' button removed from their header
and their 'Minimize Window' action will be disabled.

PROP_UNDOCKING_DISABLED

Name of TopComponent's Boolean client property which disables TopComponent's
'Undock Window' action when set to Boolean.TRUE. TopComponents which are already
floating and have this property set to Boolean.TRUE will have their 'Dock Window' action disabled.

PROP_MAXIMIZATION_DISABLED

Name of TopComponent's Boolean client property which disables TopComponent
maximization by double-clicking its header when set to Boolean.TRUE. TopComponent's
'Maximize Window' action will be also disabled.

Constructor Detail

TopComponent

TopComponent

Creates a top component for a provided lookup that will delegate
take and synchronize activated nodes and ActionMap from a provided
lookup. The lookup will also be returned from getLookup() method,
if not overriden.

setActivatedNodes

getPersistenceType

public int getPersistenceType()

Rather than overriding this method, consider using TopComponent.Description.
Overwrite when you want to change default persistence type. Default
persistence type is PERSISTENCE_ALWAYS.
Return value should be constant over a given TC's lifetime.

openNotify

Called only when top component was closed on all workspaces before and
now is opened for the first time on some workspace. The intent is to
provide subclasses information about TopComponent's life cycle across
all existing workspaces.
Subclasses will usually perform initializing tasks here.

closeNotify

Called only when top component was closed so that now it is closed
on all workspaces in the system. The intent is to provide subclasses
information about TopComponent's life cycle across workspaces.
Subclasses will usually perform cleaning tasks here.

getActions

Gets the actions which will appear in the popup menu of this component.

Subclasses are encouraged to override this method to specify
their own sets of actions.

Remember to call the super method when overriding and add your actions
to the superclass' ones (in some order),
because the default implementation provides support for standard
component actions like save, close, and clone.

preferredID

Rather than overriding this method, consider using TopComponent.Description.
Subclasses are encouraged to override this method to provide preferred value
for unique TopComponent ID returned by WindowManager.findTopComponentID(org.openide.windows.TopComponent).
Returned value should be a String, preferably describing semantics of
TopComponent subclass, such as "PieChartViewer" or "HtmlEditor" etc.
Value is then used by window system as prefix value for creating unique
TopComponent ID.
Returned String value should be preferably unique, but need not be.

Since:

4.13

componentOpened

protected void componentOpened()

Called only when top component was closed on all workspaces before and
now is opened for the first time on some workspace. The intent is to
provide subclasses information about TopComponent's life cycle across
all existing workspaces.
Subclasses will usually perform initializing tasks here.

Since:

2.18

componentClosed

protected void componentClosed()

Called only when top component was closed so that now it is closed
on all workspaces in the system. The intent is to provide subclasses
information about TopComponent's life cycle across workspaces.
Subclasses will usually perform cleaning tasks here.

Since:

2.18

componentShowing

protected void componentShowing()

Called when TopComponent is about to be shown.
Shown here means the component is selected or resides in it own cell
in container in its Mode. The container is visible and not minimized.

Note: component
is considered to be shown, even its container window
is overlapped by another window.

Since:

2.18

componentHidden

protected void componentHidden()

Called when TopComponent was hidden. Nore:

Note: Beside typical situations when component is hidden,
it is considered to be hidden even in that case
the component is in Mode container hierarchy,
the cointainer is visible, not minimized,
but the component is neither selected nor in its own cell,
i.e. it has it's own tab, but is not the selected one.

Since:

2.18

componentActivated

protected void componentActivated()

Called when this component is activated.
This happens when the parent window of this component gets focus
(and this component is the preferred one in it), or when
this component is selected in its window (and its window was already focussed).
Remember to call the super method.
The default implementation does nothing.

componentDeactivated

protected void componentDeactivated()

Called when this component is deactivated.
This happens when the parent window of this component loses focus
(and this component is the preferred one in the parent),
or when this component loses preference in the parent window
(and the parent window is focussed).
Remember to call the super method.
The default implementation does nothing.

requestFocus

public void requestFocus()

Request focus for the window holding this top component.
Also makes the component preferred in that window.
The component will not be automatically opened first
if it is not already.

Subclasses should override this method to transfer focus to desired
focusable component. TopComponent itself is not focusable.
See for example text.CloneableEditor.

Note: Use requestActive() instead to make TopComponent active
in the window system (not only focused). This method should be considered deprecated
for calling from outside; but it may be overridden (inside of which you may call super).

requestFocusInWindow

Request focus for the top component inside focused window.
Also makes the component preferred in that window.
The component will not be automatically opened first
if it is not already.

Subclasses should override this method to transfer focus to desired
focusable component. TopComponent itself is not focusable.
See for example text.CloneableEditor.

Note: Use requestActive() instead to make TopComponent active
in the window system (not only focused). This method should be considered deprecated
for calling from outside; but it may be overridden (inside of which you may call super).

requestActive

toFront

Attempts to bring the parent Window or Frame
of this TopComponent to front of other windows.

Since:

5.8

requestVisible

public void requestVisible()

Selects this TopComponent, if it is opened, but does not activate it
unless it is in active mode already.

requestAttention

public final void requestAttention(boolean brief)

Cause this TopComponent's tab to flash or otherwise draw attention to
itself. This method is thread-safe.

It will remain flashing until either cancelRequestAttention
is called, the component becomes selected or its activated state changes,
unless the brief argument is true, in which case it will stop
after a few second.

Parameters:

brief - True if the tab should blink a few times and stop

Since:

5.1

makeBusy

public final void makeBusy(boolean busy)

Notify the user that some (possibly lengthy) process is being run in this
window.
It is safe to call this method outside EDT.

modes - list of Mode which represent all modes of current
workspace, can contain nulls. Items are structured in logical groups
separated by null entries.

Input array also contains special constant modes for docking
into newly created frames. Their names are "SingleNewMode",
"MultiNewMode", "SplitNewMode", can be used for their
recognition. Please note that names and existence of special modes
can change in future releases.

writeReplace

Delegates instance of replacer class to be serialized instead
of top component itself. Replacer class calls writeExternal and
constructor, readExternal and readResolve methods properly, so
8 any top component can behave like any other externalizable object.
Subclasses can override this method to perform their
serialization differentrly

getLookup

By default the lookup includes all nodes from getActivatedNodes(),
all objects from those nodes' own lookups (excepting the nodes themselves),
and also the component's ActionMap.
This is useful for components with explorer views.

The default implementation also has a special behavior when you look up
Node.class: if getActivatedNodes() is null (as opposed to
an empty array), the result will contain an extra item whose
Lookup.Item.getId() is none
and whose Lookup.Item.getInstance() is null.
This can be used by (say) node-sensitive actions to differentiate
between a component with an explorer view that currently happens to have no
selected nodes (zero-length array so no Lookup.Item<Node>),
vs. a component with no explorer view that would never have a node selection
(null so one dummy Lookup.Item<Node>);
in either case Lookup.Result.allInstances()
would return an empty collection.
In particular, NodeAction relies on this behavior to avoid disabling
an action just because focus is transferred from a component with a (potential)
node selection to a component that does not have node selections.

If you override the method in your subclass, the default activatedNodeslookup synchronization
will not be performed. That can influence functionality that relies on activated Nodes being present
in the TopComponent's lookup. If you want to preserve the synchronization, use associateLookup(org.openide.util.Lookup)
instead.

associateLookup

Associates the provided lookup with the component. So it will
be returned from getLookup() method. When used, make sure
the provided Lookup contains objects needed by other subsystems.
For example, if callback actions
are about to search their actions in this TopComponent,
it is good idea to include this.getActionMap() in
the lookup.