Overview (Window System API)

Window System API
Package	Description
org.openide.windows	Most parts of NetBeans do not manipulate windows directly, but use special top components.

What is New (see all changes)?

Apr 17 '13 Added methods getLookup() and isShowing() in TopComponent.SubComponent.

The new methods can be used in conjunction with split multiview window, where e.g. the pallette needs to know which two of the available subcomponents are showing and query their lookup.
Aug 31 '12 Allow TopComponent's header to be permanently highlighted to draw user's attention.

New method setAttentionHighlight(boolean) in TopComponent class can be used to permanently highlight TopComponent's tab until user activates it.
Jul 4 '12 New API to check/modify the floating and minimize state of a TopComponent.

New methods in WindowManager class:
isTopComponentMinimized()
setTopComponentMinimized()
isTopComponentFloating()
setTopComponentFloating()
Mar 31 '12 Easy to use replacement for invokeWhenUIReady

In case you want to execute a code as soon as main window is visible, consider using OnShowing annotation.
Mar 21 '12 New branding property to disable Ctrl+Tab window switching.

There's a new branding property WinSys.CtrlTabSwitching.In.JTable.Enabled to disable Ctrl+Tab window switching when JTable or JTabbedPane has input focus.

Use Cases

General Usecases

General usecases can be read on the external page.

How to create a '.settings' file for a TopComponent?

Either write it by hand (not that hard if you copy other file and tweak it to match your TC), or start the IDE, instantiate the TC somehow (You have a "Window->Show My TC", right? ), copy the file that gets created in $userdir/config/Windows2Local/Component and cleanup the serialdata section - replace it with proper "<instance class='..." /> tag.

How to make a TopComponentGroup?

Q: I'm trying to make a TopComponentGroup. I've just read http://ui.netbeans.org/docs/ui/ws/ws_spec.html#3.9 I want to make a group that uses the first invocation strategy. That is, I want the group to open/close when I activate a certain subclass of TopComponent. Say, for example, I have a FooTopComponent, and when it's active, I want to open a FooPropertySheetComponent, docked in a mode on the right-hand side. I know I have to:

declare the group in the layer file (Windows2/Groups)
have code for opening the group
have code for closing the group

I think I do #2 in FooTopComponent.componentActivated() and #3 in FooTopComponent.componentDeactivated(). Is that right?

A:Yes it is correct way. You can check simple test module. First you must get TopComponentGroup instance using find method then call TopComponentGroup.open()/close(). Here is the code in your componentDeactivated method:

   protected void componentDeactivated ()
   {
       // close window group containing propsheet, but only if we're
       // selecting a different kind of TC in the same mode
       boolean closeGroup = true;
       Mode curMode = WindowManager.getDefault().findMode(this);
       TopComponent selected = curMode.getSelectedTopComponent();
       if (selected != null && selected instanceof FooTopComponent)
           closeGroup = false;
             if (closeGroup)
       {
           TopComponentGroup group = WindowManager.getDefault().findTopComponentGroup(TC_GROUP);
           if (group != null)
           {
               group.close();
           }
       }
   }

Exported Interfaces

This table lists all of the module exported APIs with defined stability classifications. It is generated based on answers to questions about the architecture of the module. Read them all...

Group of layer interfaces

Interface Name	In/Out	Stability	Specified in What Document?
NewConfigurationData	Exported	Under Development	...//core.netbeans.org/windowsystem/changes.html new configuration data
OldConfigurationData	Exported	Deprecated	...//core.netbeans.org/windowsystem/changes.html old configuration data
ModuleDataStructure	Exported	Private	...//core.netbeans.org/windowsystem/changes.html Module folder structure under Windows2 directory
LocalDataStructure	Exported	Private	...//core.netbeans.org/windowsystem/changes.html Local folder structure under Windows2Local directory

Group of java interfaces

Interface Name	In/Out	Stability	Specified in What Document?
WindowSystemAPI	Exported	Official	.../org/openide/windows/doc-files/api.html
WindowSystemImplementationAPI	Exported	Friend
DataFlavorDnDTopComponent	Exported	Private	DataFlavor.javaJVMLocalObjectMimeType + "; class=org.openide.windows.TopComponent"
DataFlavorDnDTopComponent.Cloneable	Exported	Private	DataFlavor.javaJVMLocalObjectMimeType + "; class=org.openide.windows.TopComponent$Cloneable"
DataFlavorDnDTopComponentArray	Exported	Private	DataFlavor.javaJVMLocalObjectMimeType + "; class=org.netbeans.core.windows.dnd.TopComponentDragSupport$TopComponentArray"

Group of property interfaces

Interface Name	In/Out	Stability	Specified in What Document?
KeepNonPersistentTCInModelWhenClosed	Exported	Private	Client property "KeepNonPersistentTCInModelWhenClosed" of TopComponent controls behavior of winsys when TopComponent with persistence type "Never" or "OnlyOpened" is closed. As some TopComponent wants to keep their position in winsys ie. be able to reopen at the same place and some TopComponent wants to be removed from winsys model. If property is not set nonpersistent TopComponent is removed from model when closed - it is original behavior before fix of issue #101700. If property is set (to Boolean.TRUE) then TopComponent is kept in model. It means that client must explicitly set this client property to get behavior requested by issue #101700.
netbeans.winsys.tc.activate_at_startup	Exported	Private	Name of TopComponent's Boolean client property which instructs the window system to activate the given TopComponent at startup time regardless which TopComponent was active at shutdown time. So it's usuable for welcome screen-like behavior. If more than one TopComponent has this property set to Boolean.TRUE then an arbitrary one will be selected and activated.
TopComponentAllowDockAnywhere	Exported	Private	Name of client property (of Boolean type) which says whether the TopComponent is allowed to be docked anywhere (even crossing view-editor border).
netbeans.winsys.tc.keep_preferred_size_when_slided_in	Exported	Stable	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.
netbeans.winsys.tc.closing_disabled	Exported	Stable	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.
netbeans.winsys.tc.sliding_disabled	Exported	Stable	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.
netbeans.winsys.tc.undocking_disabled	Exported	Stable	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.
netbeans.winsys.tc.dragging_disabled	Exported	Stable	Name of TopComponent's Boolean client property which disables drag and drop when set to Boolean.TRUE.
netbeans.winsys.tc.maximization_disabled	Exported	Stable	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.
netbeans.winsys.tc.draganddrop_copy_disabled	Exported	Stable	Name of TopComponent's Boolean client property which disables 'copy' drag and drop action of a TopComponent when set to Boolean.TRUE.
OpenIDE-Transmodal-Action	Exported	Friend	An `Action` with the property `OpenIDE-Transmodal-Action` set to `Boolean.TRUE` should function on all focused components. This includes the Main Window, dialogs, popup menus, etc. Otherwise only the Main Window and `TopComponent`s will receive the keystroke.
NbMainWindow.showCustomBackground	Exported	Stable	Name of boolean property in `javax.swing.UIManager`. When the property value is `TRUE` then the window system will turn off opacity for most of the main window components - menu bar, toolbars, status bar, sliding bars and the main desktop area component. That means that the main window background will be showing through these components. The property value must be set before the window system loads.
netbeans.windows	Exported	Private	This property was deleted and has no effect now, as sdi support was dropped and replaced by individual seperate windows. Please don't use, it's useless.

Group of branding interfaces

Interface Name	In/Out	Stability	Specified in What Document?
org.netbeans.core.windows.TopComponent.DragAndDrop.Enabled	Exported	Stable	Name of resource bundle property which disables the drag and drop of window TopComponents when its value is set to `false`, the default value is `true`. The property value can be adjusted by branding of `org.netbeans.core.windows` module.
org.netbeans.core.windows.TopComponent.Undocking.Enabled	Exported	Stable	Name of resource bundle property which disables undocking of window TopComponents when its value is set to `false`, the default value is `true`. When this feature is disabled then there is no 'Undock' item in TopComponent popup menu and 'Undock Window' action the main menu is disabled. The property value can be adjusted by branding of `org.netbeans.core.windows` module.
org.netbeans.core.windows.TopComponent.Sliding.Enabled	Exported	Stable	Name of resource bundle property which disables sliding of window TopComponents when its value is set to `false`, the default value is `true`. When this feature is disabled then there is no 'Minimize Window' item in TopComponent popup menu and also the Minimize button in TopComponent's header is hidden. The property value can be adjusted by branding of `org.netbeans.core.windows` module.
org.netbeans.core.windows.TopComponent.Resizing.Enabled	Exported	Stable	Name of resource bundle property which disables resizing of window TopComponents when its value is set to `false`, the default value is `true`. When this feature is disabled then it is not possible to drag splitter bars to change the size of TopComponents. The property value can be adjusted by branding of `org.netbeans.core.windows` module.
org.netbeans.core.windows.View.TopComponent.Closing.Enabled	Exported	Stable	Name of resource bundle property which disables closing of view TopComponents (non-editor windows) when its value is set to `false`, the default value is `true`. When this feature is disabled then there is no 'Close Window' item in view's popup menu, there is no close button in TopComponent's header and also 'Close Window' action in the main menu is disabled when a view TopComponent is activated. The property value can be adjusted by branding of `org.netbeans.core.windows` module.
org.netbeans.core.windows.Editor.TopComponent.Closing.Enabled	Exported	Stable	Name of resource bundle property which disables closing of editor TopComponents (document windows) when its value is set to `false`, the default value is `true`. When this feature is disabled then there are no 'Close Window', 'Close All Documents' and 'Close Other Documents' items in editor's popup menu, there is no close button in editor's header and also Close actions in the main menu are disabled when an editor TopComponent is activated. The property value can be adjusted by branding of `org.netbeans.core.windows` module.
org.netbeans.core.windows.TopComponent.Maximization.Enabled	Exported	Stable	Name of resource bundle property which disables maximization of TopComponents when its value is set to `false`, the default value is `true`. When this feature is disabled then there is no 'Maximize Window' item in TopComponent's popup menu and also 'Maximize Window' action in the main menu is disabled. The property value can be adjusted by branding of `org.netbeans.core.windows` module.
org.netbeans.core.windows.Splitter.Respect.MinimumSize.Enabled	Exported	Stable	Name of resource bundle property which forces splitter to ignore TopComponent minimum size when resizing when its value is set to `false`, the default value is `true`. When this feature is enabled then the splitter bars will not move beyond the minimum size of its TopComponents. The property value can be adjusted by branding of `org.netbeans.core.windows` module.
org.netbeans.core.windows.Mode.View.DragAndDrop.Enabled	Exported	Stable	Name of resource bundle property which allows to drag and drop the whole group of non-document windows when its value is set to `true`, which is also the default value. The property value can be adjusted by branding of `org.netbeans.core.windows` module.
org.netbeans.core.windows.Mode.Editor.DragAndDrop.Enabled	Exported	Stable	Name of resource bundle property which allows to drag and drop the whole group of document windows when its value is set to `true`, which is also the default value. The property value can be adjusted by branding of `org.netbeans.core.windows` module.
org.netbeans.core.windows.Mode.View.Undocking.Enabled	Exported	Stable	Name of resource bundle property which allows to float the whole group of non-document windows when its value is set to `true`, which is also the default value. The property value can be adjusted by branding of `org.netbeans.core.windows` module.
org.netbeans.core.windows.Mode.Editor.Undocking.Enabled	Exported	Stable	Name of resource bundle property which allows to float the whole group of document windows when its value is set to `true`, which is also the default value. The property value can be adjusted by branding of `org.netbeans.core.windows` module.
org.netbeans.core.windows.Mode.Sliding.Enabled	Exported	Stable	Name of resource bundle property which allows to minimize (slide-out) the whole group of non-document windows when its value is set to `true`, which is also the default value. The property value can be adjusted by branding of `org.netbeans.core.windows` module.
org.netbeans.core.windows.TopComponent.Auto.Slide.In.Minimized.Mode.Enabled	Exported	Stable	Name of resource bundle property which controls the opening of windows in a minimized (slided-out) group of non-document windows. When set to true (the default value) then a window which should open in a minimized group (Mode) will open also minimized (slided-out). When set to false a window will open docked even though the whole group (Mode) has been minimized. The property value can be adjusted by branding of `org.netbeans.core.windows` module.
org.netbeans.core.windows.Mode.Closing.Enabled	Exported	Stable	Name of resource bundle property which allows to close the whole group of non-document windows when its value is set to `true`, which is also the default value. The property value can be adjusted by branding of `org.netbeans.core.windows` module.
WinSys.Show.Hide.MainWindow.While.Switching.Role	Exported	Stable	Name of resource bundle property which controls whether the main IDE window may hide temporarily (`true`) when switching window layout role or whether the main window should stay visible when switching roles (`false`). The default value is `false`. The property value can be adjusted by branding of `org.netbeans.core.windows` module.
WinSys.Open.New.Editors.Docked	Exported	Stable	Name of resource bundle property which when set to `true` will force opening of new editor windows docked into the main IDE window. When set to `false` new editor windows will open tabbed with the last active editor window (which may be floating). The default value is `false`. The property value can be adjusted by branding of `org.netbeans.core.windows` module.
WinSys.DragAndDrop.Sliding.Enabled	Exported	Stable	Name of resource bundle property which enables/disables drag and drop of TopComponents into sliding Modes. When set to `true` then user can drag a TopComponent and drop it into a sliding bar to minimize it. The default value is `false`. The property value can be adjusted by branding of `org.netbeans.core.windows` module.
WinSys.TabControl.SimpleTabs.Enabled	Exported	Stable	Name of resource bundle property which allows replacing the custom TabbedContainer with plain Swing JTabbedPane implementation when the property value is `true`. The default value is `false`. The property value can be adjusted by branding of `org.netbeans.core.windows` module.
WinSys.TabControl.SimpleTabs.Placement	Exported	Stable	Name of resource bundle property which defines the placement of window tabs. The possible values are `top` (default), `bottom`, `left`, `right`. Branding of this property has no effect when `WinSys.TabControl.SimpleTabs.Enabled` is set to false. The property value can be adjusted by branding of `org.netbeans.core.windows` module.
WinSys.TabControl.SimpleTabs.MultiRow	Exported	Stable	Name of resource bundle property which defines the tab layout when JTabbedPane implementation of tab control is being used. When set to `true` window tabs will be organized into multiple rows, when set to `false` the tab displayer will have scroll buttons. Branding of this property has no effect when `WinSys.TabControl.SimpleTabs.Enabled` is set to false. The property value can be adjusted by branding of `org.netbeans.core.windows` module.
WinSys.CtrlTabSwitching.In.JTable.Enabled	Exported	Stable	Name of resource bundle property which can disable window switching when the input focus is in JTable or JTabbedPane. Ctrl+Tab and Ctrl+Shift+Tab key strokes are hard-coded to switch between opened TopComponents. However the same keys are also used in some Containers (e.g. JTable and JTabbedPane) to transfer input focus to next Component. When this property is set to `true` (default value) and input focus is in JTable or JTabbedPane then the window system will consume Ctrl+Tab and Ctrl+Shift+Tab key strokes and show window switcher popup. When this property is set to `false` then KeyboardFocusManager will consume Ctrl+Tab and Ctrl+Shift+Tab key strokes to transfer focus out of JTable or out of JTabbedPane. The property value can be adjusted by branding of `org.netbeans.core.windows` module.

Group of systemproperty interfaces

Interface Name	In/Out	Stability	Specified in What Document?
netbeans.winsys.imageSource	Exported	Private	Valid values are path to image in NB like "org/netbeans/core/resources/splash.gir". It puts the specified image into the the emptied documents area. it is experimental now. `-J-Dnetbeans.winsys.imageSource=org/netbeans/core/resources/splash.gif`
netbeans.winsys.dndfade.on	Exported	Private	Valid values are "true" and "false". Default is "false". If it is "true" it paint faded feedback during DnD of windows. Keep in mind it makes some performance impact on DnD. It is experimental now. `-J-Dnetbeans.winsys.fade.on=true`
netbeans.winsys.disable_dnd	Exported	Private	Valid values are "true" and "false". Default is "false". If it is "true" it disables DnD of windows. `-J-Dnetbeans.winsys.disable_dnd=true`
netbeans.winsys.allow.dock.anywhere	Exported	Private	Valid values are "true" and "false". Default is "false". It allows user to move (e.g. using DnD) `TopComponent`S between editor(document) and view which is restricte otherwise. It is experimental now. `-J-Dnetbeans.winsys.allow.dock.anywhere=true`
netbeans.winsys.hideEmptyDocArea	Exported	Private	Valid values are "true" and "false". Default is "false". If it is "true" it doesn't show empty documents area. `-J-Dnetbeans.winsys.hideEmptyDocArea=true`
netbeans.winsys.statusLine.in.menuBar	Exported	Private	Valid values are "true" and "false". Default is "false". If it is "true" it shows status line at the and of menu bar instead of the bottom of documents are (or main window). `-J-Dnetbeans.winsys.statusLine.in.menuBar=true`
netbeans.winsys.no_toolbars	Exported	Private	Valid values are "true" and "false". Default is "false". If it is "true" it hides all toolbars. `-J-Dnetbeans.winsys.no_toolbars=true`
netbeans.winsys.menu_bar.path	Exported	Private	If this property is set its value must point to a file on the system file system that provides instance of type `org.openide.awt.MenuBar`. This alternative menu bar will be used instead of the default one. `-J-Dnetbeans.winsys.menu_bar.path=foo/bar.instance`
netbeans.winsys.status_line.path	Exported	Private	If this property is set its value must point to a file on the system file system that provides instance of type `javax.swing.JComponent`. This alternative status line will be used instead of the default one. `-J-Dnetbeans.winsys.status_line.path=foo/bar.instance`
netbeans.winsys.no_help_in_dialogs	Exported	Private	Valid values are "true" and "false". Default is "false". If set to "true" the modal dialogs will be shown without the help button. `-J-Dnetbeans.winsys.no_help_in_dialogs=true`
org.openide.windows.DummyWindowManager.VISIBLE	Exported	Private	If set to `false`, windows opened (e.g. `TopComponent.open`) using the dummy fallback window manager will not really be set to be visible. Useful for unit tests which must incidentally use the Window System API but for which actual display of windows is undesirable.

Group of javax.swing.UIManager interfaces

Interface Name	In/Out	Stability	Specified in What Document?
tab_focus_fill_dark	Exported	Private	One of colors used in own tabs UI implementation. Usage example: To get color, call `javax.swing.UIManager.get("tab_focus_fill_dark")`
tab_focus_fill_bright	Exported	Private	One of colors used in own tabs UI implementation. Usage example: To get color, call `javax.swing.UIManager.get("tab_focus_fill_bright")`
tab_unsel_fill_dark	Exported	Private	One of colors used in own tabs UI implementation. Usage example: To get color, call `javax.swing.UIManager.get("tab_unsel_fill_dark")`
tab_unsel_fill_bright	Exported	Private	One of colors used in own tabs UI implementation. Usage example: To get color, call `javax.swing.UIManager.get("tab_unsel_fill_bright")`
tab_sel_fill	Exported	Private	One of colors used in own tabs UI implementation. Usage example: To get color, call `javax.swing.UIManager.get("tab_sel_fill")`
tab_sel_fill_bright	Exported	Private	One of colors used in own tabs UI implementation. Usage example: To get color, call `javax.swing.UIManager.get("tab_sel_fill_bright")`
tab_sel_fill_dark	Exported	Private	One of colors used in own tabs UI implementation. Usage example: To get color, call `javax.swing.UIManager.get("tab_sel_fill_dark")`
tab_border	Exported	Private	One of colors used in own tabs UI implementation. Usage example: To get color, call `javax.swing.UIManager.get("tab_border")`
tab_bottom_border	Exported	Private	One of colors used in own tabs UI implementation. Usage example: To get color, call `javax.swing.UIManager.get("tab_bottom_border")`
tab_sel_border	Exported	Private	One of colors used in own tabs UI implementation. Usage example: To get color, call `javax.swing.UIManager.get("tab_sel_border")`
workplace_fill	Exported	Private	One of colors used in own tabs UI implementation. Usage example: To get color, call `javax.swing.UIManager.get("workplace_fill")`
tab_highlight_header	Exported	Private	One of colors used in own tabs UI implementation. Usage example: To get color, call `javax.swing.UIManager.get("tab_highlight_header")`
tab_highlight_header_fill	Exported	Private	One of colors used in own tabs UI implementation. Usage example: To get color, call `javax.swing.UIManager.get("tab_highlight_header_fill")`
standard_border	Exported	Private	One of colors used in own tabs UI implementation. Usage example: To get color, call `javax.swing.UIManager.get("standard_border")`
org.netbeans.core.windows.view.ui.tabcontrol.BorderProvider	Exported	Private	Custom border management for tabbed containers can be achieved by implementing interface `org.netbeans.core.windows.view.ui.tabcontrol.BorderProvider` and putting instance into Swing's UIManager table under key with the same name as interface has. Usage example: Provide BorderProviderImpl implementation and put it in table `javax.swing.UIManager.put("org.netbeans.core.windows.view.ui.tabcontrol.BorderProvider", borderProviderImpl)` during startup, before main window is shown.

Group of logger interfaces

Interface Name In/Out Stability Specified in What Document?

org.netbeans.ui.actions.UI_ACTION_KEY_PRESS

Exported

Friend

There is a special support for notifying when an action is invoked by the TopComponent's key event handling code. The support is using Logger.getLogger("org.netbeans.ui.actions") and sents a LogRecord with message UI_ACTION_KEY_PRESS, FINER level and paramerters:

{0} instance of the KeyStroke
{1} toString of the KeyStroke
{2} instance of the action
{3} class of the action
{4} display name of the action

whenever such action is invoked. This message can then be consumed by enhanced UI logger that track what the user is going.

Group of dtd interfaces

Interface Name	In/Out	Stability	Specified in What Document?
windowmanager-properties2_0.dtd	Exported	Under Development	.../dtds/windowmanager-properties2_0.dtd `-//NetBeans//DTD Window Manager Properties 2.01//EN`
mode-properties2_0.dtd	Exported	Under Development	.../dtds/mode-properties2_0.dtd `-//NetBeans//DTD Mode Properties 2.0//EN`
tc_ref2_0.dtd	Exported	Under Development	...//www.netbeans.org/dtds/tc_ref2_0.dtd `-//NetBeans//DTD Top Component in Mode Properties 2.0//EN`
group-properties2_0.dtd	Exported	Under Development	.../dtds/group-properties2_0.dtd `-//NetBeans//DTD Group Properties 2.0//EN`
tc_group2_0.dtd	Exported	Under Development	...//www.netbeans.org/dtds/tc_group2_0.dtd `-//NetBeans//DTD Top Component in Group Properties 2.0//EN`
sessionsettings-1_0.dtd	Exported	Under Development	.../dtds/sessionsettings-1_0.dtd `-//NetBeans//DTD Session settings 1.0//EN`

Implementation Details

What do other modules need to do to declare a dependency on this one, in addition to or instead of a plain module dependency?

You might use OpenIDE-Module-Requires: org.openide.windows.WindowManager but it is not generally done.

Read more about the implementation in the answers to architecture questions.

Window System APIOfficial