org.openide.windows

Class TopComponent

java.lang.Object

java.awt.Component

java.awt.Container

javax.swing.JComponent

org.openide.windows.TopComponent

All Implemented Interfaces:

ImageObserver, MenuContainer, Externalizable, Serializable, Accessible, HelpCtx.Provider, Lookup.Provider

Direct Known Subclasses:

CloneableTopComponent

public class TopComponent
extends JComponent
implements Externalizable, Accessible, HelpCtx.Provider, Lookup.Provider

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.

See Also:

Serialized Form

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static interface	TopComponent.Cloneable Each top component that wishes to be cloned should implement this interface, so CloneAction can check it and call the cloneComponent method.
static interface	TopComponent.Description Provides basic information about the persistence of a TopComponent.
static class	TopComponent.NodeName Deprecated. 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.
static interface	TopComponent.OpenActionRegistration Creates an action that can open the component.
static interface	TopComponent.Registration Registers TopComponent into specified location among existing window system modes.
static interface	TopComponent.Registry Registry of all top components.
static class	TopComponent.SubComponent Representation of a visual sub-component displayed in a TopComponent, for example sub-tabs in a multiview window.

Nested classes/interfaces inherited from class javax.swing.JComponent

JComponent.AccessibleJComponent

Nested classes/interfaces inherited from class java.awt.Container

Container.AccessibleAWTContainer

Nested classes/interfaces inherited from class java.awt.Component

Component.AccessibleAWTComponent, Component.BaselineResizeBehavior, Component.BltBufferStrategy, Component.FlipBufferStrategy

Field Summary

Fields

Modifier and Type	Field and Description
static int	CLOSE_EACH Deprecated. Do not use. It is redundant since workspaces are not supported anymore.
static int	CLOSE_LAST Deprecated. Do not use. It is redundant since workspaces are not supported anymore.
static int	PERSISTENCE_ALWAYS Persistence type of TopComponent instance.
static int	PERSISTENCE_NEVER Persistence type of TopComponent instance.
static int	PERSISTENCE_ONLY_OPENED Persistence type of TopComponent instance.
static String	PROP_CLOSING_DISABLED Name of TopComponent's Boolean client property which removes close button from TopComponent's header and disables its 'Close Window' action when set to Boolean.TRUE.
static String	PROP_DND_COPY_DISABLED Name of TopComponent's Boolean client property which disables 'copy' drag and drop action of this TopComponent when set to Boolean.TRUE.
static String	PROP_DRAGGING_DISABLED Name of TopComponent's Boolean client property which disables drag and drop when set to Boolean.TRUE.
static String	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.
static String	PROP_MAXIMIZATION_DISABLED Name of TopComponent's Boolean client property which disables TopComponent maximization by double-clicking its header when set to Boolean.TRUE.
static String	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.
static String	PROP_UNDOCKING_DISABLED Name of TopComponent's Boolean client property which disables TopComponent's 'Undock Window' action when set to Boolean.TRUE.

Fields inherited from class javax.swing.JComponent

listenerList, TOOL_TIP_TEXT_KEY, ui, UNDEFINED_CONDITION, WHEN_ANCESTOR_OF_FOCUSED_COMPONENT, WHEN_FOCUSED, WHEN_IN_FOCUSED_WINDOW

Fields inherited from class java.awt.Component

accessibleContext, BOTTOM_ALIGNMENT, CENTER_ALIGNMENT, LEFT_ALIGNMENT, RIGHT_ALIGNMENT, TOP_ALIGNMENT

Fields inherited from interface java.awt.image.ImageObserver

ABORT, ALLBITS, ERROR, FRAMEBITS, HEIGHT, PROPERTIES, SOMEBITS, WIDTH

Constructor Summary

Constructors

Constructor and Description
TopComponent() Create a top component.
TopComponent(Lookup lookup) Creates a top component for a provided lookup that will delegate take and synchronize activated nodes and ActionMap from a provided lookup.

Method Summary

Modifier and Type	Method and Description
void	addNotify()
protected void	associateLookup(Lookup lookup) Associates the provided lookup with the component.
List<Mode>	availableModes(List<Mode> modes) Allows top component to specify list of modes into which can be docked by end user.
void	cancelRequestAttention() Cause this TopComponent's tab to stop flashing if it was flashing.
boolean	canClose() This method is called when this TopComponent is about to close.
boolean	canClose(Workspace workspace, boolean last) Deprecated. Do not use anymore. Use canClose() instead. Both parameters are redundant since workspaces are not supported anymore.
boolean	close() Closes this TopComponent.
boolean	close(Workspace workspace) Deprecated. Use close() instead.
protected void	closeNotify() Deprecated. Use componentClosed() instead.
protected void	componentActivated() Called when this component is activated.
protected void	componentClosed() Called only when top component was closed so that now it is closed on all workspaces in the system.
protected void	componentDeactivated() Called when this component is deactivated.
protected void	componentHidden() Called when TopComponent was hidden.
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.
protected void	componentShowing() Called when TopComponent is about to be shown.
AccessibleContext	getAccessibleContext()
Action[]	getActions() Gets the actions which will appear in the popup menu of this component.
Node[]	getActivatedNodes() Get the set of activated nodes in this component.
int	getCloseOperation() Deprecated. Do not use. It is redundant since workspaces are not supported anymore.
String	getDisplayName() Gets localized display name of this TopComponent.
HelpCtx	getHelpCtx() Get the help context for this component.
String	getHtmlDisplayName() Gets localized display name of this TopComponent with added html tags for text coloring and/or font style.
Image	getIcon() Rather than overriding this method, consider using TopComponent.Description.
Lookup	getLookup() Gets a lookup which represents the "selection" of this component.
int	getPersistenceType() Rather than overriding this method, consider using TopComponent.Description.
static TopComponent.Registry	getRegistry() Getter for class that allows obtaining of information about components.
String	getShortName() Short version of TopComponent's name that doesn't include the name of activated Node.
TopComponent.SubComponent[]	getSubComponents() Retrieves sub-components this TopComponent contains.
SystemAction[]	getSystemActions() Deprecated. Use getActions() instead.
int	getTabPosition() Gives position index of opened TopComponent in the mode.
UndoRedo	getUndoRedo() Get the undo/redo support for this component.
boolean	isOpened() Indicates whether this TopComponent is opened.
boolean	isOpened(Workspace workspace) Deprecated. Use isOpened() instead.
void	makeBusy(boolean busy) Notify the user that some (possibly lengthy) process is being run in this window.
void	open() Shows this TopComponent.
void	open(Workspace workspace) Deprecated. Use open() instead.
static Action	openAction(TopComponent component, String displayName, String iconBase, boolean noIconInMenu) Creates an action that opens and activates given TopComponent, when invoked.
void	openAtTabPosition(int position) Opens TopComponent at given position in the mode.
protected void	openNotify() Deprecated. Use componentOpened() instead.
protected String	preferredID() Rather than overriding this method, consider using TopComponent.Description.
protected boolean	processKeyBinding(KeyStroke ks, KeyEvent e, int condition, boolean pressed) Overrides superclass method, adds possible additional handling of global keystrokes in case this TopComoponent is ancestor of focused component.
void	readExternal(ObjectInput in) Deserialize this top component.
void	requestActive() Activates this TopComponent if it is opened.
void	requestAttention(boolean brief) Cause this TopComponent's tab to flash or otherwise draw attention to itself.
void	requestFocus() Request focus for the window holding this top component.
boolean	requestFocusInWindow() Request focus for the top component inside focused window.
void	requestVisible() Selects this TopComponent, if it is opened, but does not activate it unless it is in active mode already.
void	setActivatedNodes(Node[] activatedNodes) Set the set of activated nodes in this component.
void	setAttentionHighlight(boolean highlight) Permanently highlights this TopComponent's tab until user activates it.
void	setCloseOperation(int closeOperation) Deprecated. Do not use. It is redundant since workspaces are not supported anymore.
void	setDisplayName(String displayName) Sets localized display name of this TopComponent.
void	setHtmlDisplayName(String htmlDisplayName) Sets localized html display name of this TopComponent.
void	setIcon(Image icon) Set the icon of this top component.
void	setName(String name) Set the name of this top component.
void	setToolTipText(String toolTip) Sets toolTip for this TopComponent, adds notification about the change to its WindowManager.TopComponentManager.
void	toFront() Attempts to bring the parent Window or Frame of this TopComponent to front of other windows.
void	writeExternal(ObjectOutput out) Serialize this top component.
protected Object	writeReplace() Delegates instance of replacer class to be serialized instead of top component itself.

Methods inherited from class javax.swing.JComponent

addAncestorListener, addVetoableChangeListener, computeVisibleRect, contains, createToolTip, disable, enable, firePropertyChange, firePropertyChange, firePropertyChange, fireVetoableChange, getActionForKeyStroke, getActionMap, getAlignmentX, getAlignmentY, getAncestorListeners, getAutoscrolls, getBaseline, getBaselineResizeBehavior, getBorder, getBounds, getClientProperty, getComponentGraphics, getComponentPopupMenu, getConditionForKeyStroke, getDebugGraphicsOptions, getDefaultLocale, getFontMetrics, getGraphics, getHeight, getInheritsPopupMenu, getInputMap, getInputMap, getInputVerifier, getInsets, getInsets, getListeners, getLocation, getMaximumSize, getMinimumSize, getNextFocusableComponent, getPopupLocation, getPreferredSize, getRegisteredKeyStrokes, getRootPane, getSize, getToolTipLocation, getToolTipText, getToolTipText, getTopLevelAncestor, getTransferHandler, getUIClassID, getVerifyInputWhenFocusTarget, getVetoableChangeListeners, getVisibleRect, getWidth, getX, getY, grabFocus, hide, isDoubleBuffered, isLightweightComponent, isManagingFocus, isOpaque, isOptimizedDrawingEnabled, isPaintingForPrint, isPaintingOrigin, isPaintingTile, isRequestFocusEnabled, isValidateRoot, paint, paintBorder, paintChildren, paintComponent, paintImmediately, paintImmediately, paramString, print, printAll, printBorder, printChildren, printComponent, processComponentKeyEvent, processKeyEvent, processMouseEvent, processMouseMotionEvent, putClientProperty, registerKeyboardAction, registerKeyboardAction, removeAncestorListener, removeNotify, removeVetoableChangeListener, repaint, repaint, requestDefaultFocus, requestFocus, requestFocusInWindow, resetKeyboardActions, reshape, revalidate, scrollRectToVisible, setActionMap, setAlignmentX, setAlignmentY, setAutoscrolls, setBackground, setBorder, setComponentPopupMenu, setDebugGraphicsOptions, setDefaultLocale, setDoubleBuffered, setEnabled, setFocusTraversalKeys, setFont, setForeground, setInheritsPopupMenu, setInputMap, setInputVerifier, setMaximumSize, setMinimumSize, setNextFocusableComponent, setOpaque, setPreferredSize, setRequestFocusEnabled, setTransferHandler, setUI, setVerifyInputWhenFocusTarget, setVisible, unregisterKeyboardAction, update, updateUI

Methods inherited from class java.awt.Container

add, add, add, add, add, addContainerListener, addImpl, addPropertyChangeListener, addPropertyChangeListener, applyComponentOrientation, areFocusTraversalKeysSet, countComponents, deliverEvent, doLayout, findComponentAt, findComponentAt, getComponent, getComponentAt, getComponentAt, getComponentCount, getComponents, getComponentZOrder, getContainerListeners, getFocusTraversalKeys, getFocusTraversalPolicy, getLayout, getMousePosition, insets, invalidate, isAncestorOf, isFocusCycleRoot, isFocusCycleRoot, isFocusTraversalPolicyProvider, isFocusTraversalPolicySet, layout, list, list, locate, minimumSize, paintComponents, preferredSize, printComponents, processContainerEvent, processEvent, remove, remove, removeAll, removeContainerListener, setComponentZOrder, setFocusCycleRoot, setFocusTraversalPolicy, setFocusTraversalPolicyProvider, setLayout, transferFocusDownCycle, validate, validateTree

Methods inherited from class java.awt.Component

action, add, addComponentListener, addFocusListener, addHierarchyBoundsListener, addHierarchyListener, addInputMethodListener, addKeyListener, addMouseListener, addMouseMotionListener, addMouseWheelListener, bounds, checkImage, checkImage, coalesceEvents, contains, createImage, createImage, createVolatileImage, createVolatileImage, disableEvents, dispatchEvent, enable, enableEvents, enableInputMethods, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, getBackground, getBounds, getColorModel, getComponentListeners, getComponentOrientation, getCursor, getDropTarget, getFocusCycleRootAncestor, getFocusListeners, getFocusTraversalKeysEnabled, getFont, getForeground, getGraphicsConfiguration, getHierarchyBoundsListeners, getHierarchyListeners, getIgnoreRepaint, getInputContext, getInputMethodListeners, getInputMethodRequests, getKeyListeners, getLocale, getLocation, getLocationOnScreen, getMouseListeners, getMouseMotionListeners, getMousePosition, getMouseWheelListeners, getName, getParent, getPeer, getPropertyChangeListeners, getPropertyChangeListeners, getSize, getToolkit, getTreeLock, gotFocus, handleEvent, hasFocus, imageUpdate, inside, isBackgroundSet, isCursorSet, isDisplayable, isEnabled, isFocusable, isFocusOwner, isFocusTraversable, isFontSet, isForegroundSet, isLightweight, isMaximumSizeSet, isMinimumSizeSet, isPreferredSizeSet, isShowing, isValid, isVisible, keyDown, keyUp, list, list, list, location, lostFocus, mouseDown, mouseDrag, mouseEnter, mouseExit, mouseMove, mouseUp, move, nextFocus, paintAll, postEvent, prepareImage, prepareImage, processComponentEvent, processFocusEvent, processHierarchyBoundsEvent, processHierarchyEvent, processInputMethodEvent, processMouseWheelEvent, remove, removeComponentListener, removeFocusListener, removeHierarchyBoundsListener, removeHierarchyListener, removeInputMethodListener, removeKeyListener, removeMouseListener, removeMouseMotionListener, removeMouseWheelListener, removePropertyChangeListener, removePropertyChangeListener, repaint, repaint, repaint, resize, resize, setBounds, setBounds, setComponentOrientation, setCursor, setDropTarget, setFocusable, setFocusTraversalKeysEnabled, setIgnoreRepaint, setLocale, setLocation, setLocation, setSize, setSize, show, show, size, toString, transferFocus, transferFocusBackward, transferFocusUpCycle

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

CLOSE_EACH

@Deprecated
public static final int 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

See Also:

Constant Field Values

CLOSE_LAST

@Deprecated
public static final int 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).

See Also:

Constant Field Values

PERSISTENCE_ALWAYS

public static final int PERSISTENCE_ALWAYS

Persistence type of TopComponent instance. TopComponent is persistent.

See Also:

Constant Field Values

PERSISTENCE_ONLY_OPENED

public static final int PERSISTENCE_ONLY_OPENED

Persistence type of TopComponent instance. TopComponent is persistent only when it is opened in Mode.

See Also:

Constant Field Values

PERSISTENCE_NEVER

public static final int PERSISTENCE_NEVER

Persistence type of TopComponent instance. TopComponent is not persistent.

See Also:

Constant Field Values

PROP_KEEP_PREFERRED_SIZE_WHEN_SLIDED_IN

public static final String 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.

Since:

6.26

See Also:

Constant Field Values

PROP_CLOSING_DISABLED

public static final String PROP_CLOSING_DISABLED

Name of TopComponent's Boolean client property which removes close button from TopComponent's header and disables its 'Close Window' action when set to Boolean.TRUE.

Since:

6.26

See Also:

Constant Field Values

PROP_SLIDING_DISABLED

public static final String 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.

Since:

6.26

See Also:

Constant Field Values

PROP_UNDOCKING_DISABLED

public static final String 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.

Since:

6.26

See Also:

Constant Field Values

PROP_DRAGGING_DISABLED

public static final String PROP_DRAGGING_DISABLED

Name of TopComponent's Boolean client property which disables drag and drop when set to Boolean.TRUE.

Since:

6.26

See Also:

Constant Field Values

PROP_MAXIMIZATION_DISABLED

public static final String 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.

Since:

6.26

See Also:

Constant Field Values

PROP_DND_COPY_DISABLED

public static final String PROP_DND_COPY_DISABLED

Name of TopComponent's Boolean client property which disables 'copy' drag and drop action of this TopComponent when set to Boolean.TRUE.

Since:

6.48

See Also:

Constant Field Values

Constructor Detail

TopComponent

public TopComponent()

Create a top component.

TopComponent

public TopComponent(Lookup lookup)

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.

Parameters:

lookup - the lookup to associate with

Since:

4.19

Method Detail

addNotify

public void addNotify()

Overrides:

addNotify in class JComponent

getRegistry

public static final TopComponent.Registry getRegistry()

Getter for class that allows obtaining of information about components. It allows to find out which component is selected, which nodes are currently or has been activated and list of all components.

Returns:

the registry of components

getActivatedNodes

public final Node[] getActivatedNodes()

Get the set of activated nodes in this component.

Returns:

the activated nodes for this component or null, null means such component does not change TopComponent.Registry.getActivatedNodes() just TopComponent.Registry.getCurrentNodes() when this component gets activated

setActivatedNodes

public final void setActivatedNodes(Node[] activatedNodes)

Set the set of activated nodes in this component.

Parameters:

activatedNodes - activated nodes for this component

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.

Returns:

one of P_X constants

Since:

4.20

getUndoRedo

public UndoRedo getUndoRedo()

Get the undo/redo support for this component. The default implementation returns a dummy support that cannot undo anything.

Returns:

undoable edit for this component

open

public void open()

Shows this TopComponent. Note: This method only makes it visible, but does not activates it.

See Also:

requestActive()

open

@Deprecated
public void open(Workspace workspace)

Deprecated. Use open() instead.

Shows this TopComponent in current workspace. Node: Currently workspaces are not supported. The method has the same effect like open().

openAtTabPosition

public final void openAtTabPosition(int position)

Opens TopComponent at given position in the mode. TopComponent is inserted at given position, positions of already opened TopComponents in the same mode are incremented.

• Does no operation if this TopComponent is already opened.
• For position value less then 0, TopComponent is opened at position 0, the very first one.
• For position value greater then count of opened TopComponents in the mode, TopComponent is opened at last position

Parameters:

position - Index of the requested position.

Since:

6.15

getTabPosition

public final int getTabPosition()

Gives position index of opened TopComponent in the mode. For closed TopComponents, position value less then zero is returned.

Returns:

Index of position.

Since:

6.15

isOpened

public final boolean isOpened()

Indicates whether this TopComponent is opened.

Returns:

true if given top component is opened, false otherwise

isOpened

@Deprecated
public final boolean isOpened(Workspace workspace)

Deprecated. Use isOpened() instead.

Indicates whether this TopComponent is opened in current workspace. Node: Currently workspaces are not supported. The method has the same effect like isOpened().

close

public final boolean close()

Closes this TopComponent.

Returns:

true if top component was succesfully closed, false if top component for some reason refused to close.

close

@Deprecated
public final boolean close(Workspace workspace)

Deprecated. Use close() instead.

Closes this TopComponent in current workspace. Node: Currently workspaces are not supported. The method has the same effect like close().

canClose

public boolean canClose()

This method is called when this TopComponent is about to close. Allows subclasses to decide if TopComponent is ready to close.

Since:

4.13

canClose

@Deprecated
public boolean canClose(Workspace workspace,
                                    boolean last)

Deprecated. Do not use anymore. Use canClose() instead. Both parameters are redundant since workspaces are not supported anymore.

This method is called when top component is about to close. Allows subclasses to decide if top component is ready for closing or not.
Default implementation always return true.

Parameters:

workspace - the workspace on which we are about to close or null which means that component will be closed on all workspaces where it is opened (CLOSE_EACH mode)

last - true if this is last workspace where top component is opened, false otherwise. If close operation is set to CLOSE_EACH, then this param is always true

Returns:

true if top component is ready to close, false otherwise.

openNotify

@Deprecated
protected void openNotify()

Deprecated. Use componentOpened() instead.

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

@Deprecated
protected void closeNotify()

Deprecated. Use componentClosed() instead.

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.

getSystemActions

@Deprecated
public SystemAction[] getSystemActions()

Deprecated. Use getActions() instead.

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

Returns:

array of system actions for this component

getActions

public Action[] 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.

Returns:

array of actions for this component

Since:

3.32

openAction

public static Action openAction(TopComponent component,
                                String displayName,
                                String iconBase,
                                boolean noIconInMenu)

Creates an action that opens and activates given TopComponent, when invoked. This method can also be used from XML Layer directly by following XML definition:

 <file name="your-pkg-action-id.instance">
   <attr name="instanceCreate" methodvalue="org.openide.windows.TopComponent.openAction"/>
   <attr name="component" methodvalue="your.pkg.YourComponent.factoryMethod"/>
   <attr name="displayName" bundlevalue="your.pkg.Bundle#key"/>
   <attr name="iconBase" stringvalue="your/pkg/YourComponent.png"/>
   <!-- if desired: <attr name="noIconInMenu" boolvalue="false"/> -->
   <!-- if desired: <attr name="preferredID" stringvalue="id.of.your.tc"/> -->
 </file>
 

The preferredID attribute is supported since version 6.37. If specified the action first seeks for existing preferredID component and if found, it opens and activates it.

Rather than doing all this in XML, consider using TopComponent.OpenActionRegistration.

Parameters:

component - the component to open

displayName - the display name of the action

image - the image to associated with the action

noIconInMenu - true if this icon shall not have an item in menu

Since:

6.24

See Also:

TopComponent.OpenActionRegistration

setCloseOperation

@Deprecated
public final void setCloseOperation(int closeOperation)

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

Set the close mode for the component.

Parameters:

closeOperation - one of CLOSE_EACH or CLOSE_LAST

Throws:

IllegalArgumentException - if an unrecognized close mode was supplied

See Also:

close()

getCloseOperation

@Deprecated
public final int getCloseOperation()

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

Get the current close mode for this component.

Returns:

one of CLOSE_EACH or CLOSE_LAST

preferredID

protected String 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).

Overrides:

requestFocus in class JComponent

requestFocusInWindow

public boolean 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).

Overrides:

requestFocusInWindow in class JComponent

requestActive

public void requestActive()

Activates this TopComponent if it is opened.

Since:

4.13

toFront

public void 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.

Parameters:

True - to start 'busy' notification, 'false' to stop it.

Since:

6.51

See Also:

WindowManager.topComponentMakeBusy(org.openide.windows.TopComponent, boolean)

cancelRequestAttention

public final void cancelRequestAttention()

Cause this TopComponent's tab to stop flashing if it was flashing.

Since:

5.1

setAttentionHighlight

public final void setAttentionHighlight(boolean highlight)

Permanently highlights this TopComponent's tab until user activates it.

Parameters:

highlight - True to highlight the tab, false to switch the highlight off.

Since:

6.58

See Also:

requestAttention(boolean)

setName

public void setName(String name)

Set the name of this top component. The default implementation just notifies the window manager.

Overrides:

setName in class Component

Parameters:

name - the new display name

setDisplayName

public void setDisplayName(String displayName)

Sets localized display name of this TopComponent.

Parameters:

displayName - localized display name which is set

Since:

4.13

getDisplayName

public String getDisplayName()

Gets localized display name of this TopComponent.

Returns:

localized display name or null if there is none

Since:

4.13

getShortName

public String getShortName()

Short version of TopComponent's name that doesn't include the name of activated Node.

Returns:

Short version of TopComponent's display name. The default implementation returns null.

Since:

6.52

setHtmlDisplayName

public void setHtmlDisplayName(String htmlDisplayName)

Sets localized html display name of this TopComponent. Hmtl name usually contains basic html tags for text coloring and style. Html name may be null if not needed. Must apparently begin with <html>.

Parameters:

htmlDisplayName - localized html display name which is set

Since:

6.4

getHtmlDisplayName

public String getHtmlDisplayName()

Gets localized display name of this TopComponent with added html tags for text coloring and/or font style. May return null. Must apparently begin with <html>.

Returns:

localized html display name or null if there is none

Since:

6.4

setToolTipText

public void setToolTipText(String toolTip)

Sets toolTip for this TopComponent, adds notification about the change to its WindowManager.TopComponentManager.

Overrides:

setToolTipText in class JComponent

setIcon

public void setIcon(Image icon)

Set the icon of this top component. The icon will be used for the component's representation on the screen, e.g. in a multiwindow's tab. The default implementation just notifies the window manager.

Parameters:

icon - New components' icon.

getIcon

public Image getIcon()

Rather than overriding this method, consider using TopComponent.Description.

Returns:

The icon of the top component

getHelpCtx

public HelpCtx getHelpCtx()

Get the help context for this component. Subclasses should generally override this to return specific help.

Specified by:

getHelpCtx in interface HelpCtx.Provider

Returns:

the help context

availableModes

public List<Mode> availableModes(List<Mode> modes)

Allows top component to specify list of modes into which can be docked by end user. Subclasses should override this method if they want to alter docking policy of top component.

So for example, by returning empty list, top component refuses to be docked anywhere.

Default implementation allows docking anywhere by returning input list unchanged.

Parameters:

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.

Returns:

list of Mode which are available for dock, can contain nulls

Since:

2.14

processKeyBinding

protected boolean processKeyBinding(KeyStroke ks,
                                    KeyEvent e,
                                    int condition,
                                    boolean pressed)

Overrides superclass method, adds possible additional handling of global keystrokes in case this TopComoponent is ancestor of focused component.

Overrides:

processKeyBinding in class JComponent

writeExternal

public void writeExternal(ObjectOutput out)
                   throws IOException

Serialize this top component. Subclasses wishing to store state must call the super method, then write to the stream.

Specified by:

writeExternal in interface Externalizable

Parameters:

out - the stream to serialize to

Throws:

IOException

readExternal

public void readExternal(ObjectInput in)
                  throws IOException,
                         ClassNotFoundException

Deserialize this top component. Subclasses wishing to store state must call the super method, then read from the stream.

Specified by:

readExternal in interface Externalizable

Parameters:

in - the stream to deserialize from

Throws:

IOException

ClassNotFoundException

writeReplace

protected Object writeReplace()
                       throws ObjectStreamException

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

Throws:

ObjectStreamException

getAccessibleContext

public AccessibleContext getAccessibleContext()

Specified by:

getAccessibleContext in interface Accessible

Overrides:

getAccessibleContext in class Component

getLookup

public Lookup getLookup()

Gets a lookup which represents the "selection" of this component.

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 activatedNodes<->lookup 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.

Specified by:

getLookup in interface Lookup.Provider

Returns:

a lookup with designates context of this component

Since:

3.29

See Also:

ContextAwareAction, Utilities.actionsToPopup(Action[], Lookup)

associateLookup

protected final void associateLookup(Lookup lookup)

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.

Parameters:

lookup - the lookup to associate

Throws:

IllegalStateException - if there already is a lookup registered with this component

Since:

4.23

getSubComponents

public TopComponent.SubComponent[] getSubComponents()

Retrieves sub-components this TopComponent contains. The resulting array is a snapshot valid at the time of the call and shouldn't be held for too long. This method can be called from EDT only.

Returns:

Array of internal sub-components or an empty array if the TopComponent has no internal sub-components.

Since:

6.52