Window System API
Official

Redesign documents.

See:
Description

Window System API

org.openide.windows

Most parts of NetBeans do not manipulate windows directly, but use special top components.

Redesign documents.

What is New (see all changes)?

• Nov 12 '11 Added a client property to turn copy drag and drop of clonable TopComponents off.

  Added a new boolean client property PROP_DND_COPY_DISABLED. When set to Boolean.TRUE on a CloneableTopComponent then it is not possible to perform copy drag and drop operation with it.

• Oct 19 '11 Added optional role parameter to TopComponent Registration annotation.

  Since the window system now supports multiple window layouts - roles - the annotation for TopComponent registration needs an optional parameter to specify one or more roles the window should belong to. If no roles are specified, the TopComponent is registered in the default layout.

• Jun 7 '11 Added more attributes to Mode DTD to support new winsys features.

  New window system features - sliding bar for minimized windows at the top of the main window, drag and drop of the whole window group and minimization of the whole window group - require small additions to Mode DTD.

• Jun 6 '11 Support multiple window system layouts.

  It is possible to define multiple window system layouts and switch between them either at startup or at runtime.

• Feb 15 '11 Allow custom painted background in the main IDE window.

  There's a new Boolean property NbMainWindow.showCustomBackground 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. It can be used to paint some watermark or logo or gradient on the main window background, especially when using custom main window implementation, see change id reuse.existing.frame.as.the.main.window

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:

1. declare the group in the layer file (Windows2/Groups)
2. have code for opening the group
3. 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 TopComponents 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.

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) TopComponentS 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.