Overview | Package | Class | Use | Tree | Deprecated | Index | Help
| org.openide.windows 6.5.22
PREV NEXT | FRAMES NO FRAMES

# NetBeans Windows API

Redesign document.

See:
Description

Windows API
org.openide.windows | Most parts of the IDE do not manipulate windows directly, but use special top components.

Redesign document.

### What is New (see all changes)?

- Oct 31 '05 Added the `TopComponent.getHtmlDisplayName`, `TopComponent.setHtmlDisplayName` and `WindowManager.topComponentHtmlDisplayNameChanged` methods.

  The `TopComponent.getHtmlDisplayName` and `TopComponent.setHtmlDisplayName` methods was added to allow `TopComponent`s to have display name that contains html tags differentiated from regular display name. Regular display name should be used for tasks like alphabetical sorting while html display name is used for labels and titles that support html, like editor tabs. `WindowManager.topComponentHtmlDisplayNameChanged` was also added to let window system implementation know about html display name change.

- Mar 21 '05 Added the `TopComponent` ability to bring their parent `Window` to front of other windows.

  The `TopComponent` class has a new method `toFront()` that attempts to bring the parent `Window` of the TopComponent to front of other top-level windows. The method is implemented in the `WindowManager` class using AWT's `java.awt.Window#toFront()`.

- Nov 17 '04 TopComponent can request attention

  `TopComponent.requestAttention(boolean)` and `TopComponent.cancelRequestAttention` added to allow components to signal that they require user's attention or the attention is no longer required. It's up to the current TopComponent container to decide how to attract user's attention. If the user activates the attention-requiring component, the container assumes the goal was achieved and the action is cancelled. The methods are thread-safe.

  For those implementing WindowManager class, there is an incompatible change where abstract methods `topComponentCancelRequestAttention(TopComponent)` and `topComponentRequestAttention(TopComponent)` were added.

- Jan 20 '04 Allow association of Lookup with TopComponent later than in constructor.

  Adding `TopComponent.associateLookup` to allow late (in middle of constructor) association of Lookup with component. This is especially useful in `org.openide.explorer.ExplorerUtils`.

- Jan 7 '04 Method TopComponent.getPersistenceType() is added to replace usage of client property PersistenceType.

  Method to get TopComponent persistence type is added to API.

### Use Cases

General UsecasesUse cases can be read on the external page. Here is a small howto for simple things that may be found useful:

##### 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 java interfaces

Interface Name | In/Out | Stability | Specified in What Document?
Usecases | Exported | Under Development | ...//core.netbeans.org/windowsystem/changes.html Use cases
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 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 property interfaces

Interface Name | In/Out | Stability | Specified in What Document?
PersistenceType | Exported | Deprecated | Valid values are "Never", "OnlyOpened". Default is "" (empty string) and means always persistent. "Never" means that TopComponent is not persistent at all. It lives only during IDE run. "OnlyOpened" means that TopComponent is serialized only when it is opened. If it is closed instance is lost. Default behaviour is that TopComponent is serialized always regardless it is opened or closed. It is client property of TopComponent. Usage example: To disable persistence of TopComponent use `putClientProperty("PersistenceType","Never");` in initialization code of TopComponent eg. in constructor. Usage of this client property is deprecated. Use API method `TopComponent.getPersistenceType()` instead.
SlidingName | Exported | Private | Valid value is any String value representing displayable title of TopComponent in sliding mode. Title is shown on buttons on sides of main window for TopComponents that are currently hidden in sliding state. This property has no effect on regular display names of TopComponents which are shown in captions of windows/tabs in the window system. It is client property of TopComponent. Usage example: To provide different, preferably shorter and non changing name for sliding title of your TopComponent subclass, use `putClientProperty("SlidingName","your sliding title");` in initialization code of TopComponent eg. in constructor. Note that in next releases usage of this client property will be removed and replaced by API, see issue #55955 in Issuezilla on www.netbeans.org.
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.
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.windows | Exported | Private | Valid values are "mdi" and "sdi". It selects GUI mode in which window system is started. The "mdi" and "sdi" names are now obsoleted (together with the option). The "mdi" corresponds to "compact" mode and "sdi" corresponds to "selected" mode. It can be set on command line or in ide.cfg. Usage example: To start IDE in Selected mode use `-J-Dnetbeans.windows=sdi`

##### 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 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?

Declare dependency on openide module ie. add following line to manifest of your module: `OpenIDE-Module-IDE-Dependencies: IDE/1 > X.XX (it will be defined yet)` as window system is part of openide. And dependeny on implementation: `OpenIDE-Module-Module-Dependencies: org.netbeans.core.windows > X.XX`. But since the core-windows.jar does not provide any public API this should be used only in ui-declaration module (like core-ui.jar).

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

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
| org.openide.windows 6.5.22
PREV NEXT | FRAMES NO FRAMES

Built on December 7 2006. | Portions Copyright 1997-2005 Sun Microsystems, Inc. All rights reserved.