NetBeans Architecture Answers for Window System module

General Information

Question (arch-what): What is this project good for?
Answer: Window System API is used to display and control application GUI: Main window, frames, components. There is a UI specification document.
Question (arch-overall): Describe the overall architecture.
Answer: Redesign document.
Question (arch-usecases): Describe the main use cases of the new API. Who will use it under what circumstances? What kind of code would typically need to be written to use the module?
Answer: General Usecases - Use 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();
           }
       }
   }     
    

Question (arch-time): What are the time estimates of the work?
Answer: November 15 2003.
Question (arch-quality): How will the quality of your code be tested and how are future regressions going to be prevented?
WARNING: Question with id="arch-quality" has not been answered!

Project and platform dependencies

Question (dep-nb): What other NetBeans projects and modules does this one depend on?
Answer: Module uses following API's:
• NodesAPI
• ActionsAPI
• ModulesAPI
• FilesystemsAPI
• LoadersAPI
• UtilitiesAPI
• SettingsAPI
Question (dep-non-nb): What other projects outside NetBeans does this one depend on?
Answer: SAX parser is used to parse settings files.
Question (dep-platform): On which platforms does your module run? Does it run in the same way on each?
Answer: 100% pure Java. Runs anywhere. Swing is used for GUI display.
Question (dep-jre): Which version of JRE do you need (1.2, 1.3, 1.4, etc.)?
Answer: It runs on JRE 1.4.
Question (dep-jrejdk): Do you require the JDK or is the JRE enough?
Answer: JRE is enough.

Deployment

Question (deploy-jar): Do you deploy just module JAR file(s) or other files as well?
Answer: Module API is part of openide.jar, implementation is mostly in core-windows.jar. Module API also contains dummy implementation usable for tests.
Question (deploy-nbm): Can you deploy an NBM via the Update Center?
Answer: Whole openide.jar and core-windows.jar can be deployed via AU center.
Question (deploy-shared): Do you need to be installed in the shared location only, or in the user directory only, or can your module be installed anywhere?
Answer: openide.jar and core-windows.jar needs to be in the system directory.
Question (deploy-packages): Are packages of your module made inaccessible by not declaring them public?
Answer: No. Window System API contains WindowSystemAPI. Some parts of core can use semi-private API WindowSystemImplementationAPI.
Question (deploy-dependencies): What do other modules need to do to declare a dependency on this one?
Answer: 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).

Compatibility with environment

Question (compat-i18n): Is your module correctly internationalized?
Answer: Yes.
Question (compat-standards): Does the module implement or define any standards? Is the implementation exact or does it deviate somehow?
Answer: It follows JLF standard for the custom UI components provided by core implementation.
Question (compat-version): Can your module coexist with earlier and future versions of itself? Can you correctly read all old settings? Will future versions be able to read your current settings? Can you read or politely ignore settings stored by a future version?
Answer: Yes. Module stores its own versioned settings as XML files. In addition components are stored in settings file format of core/settings module. For description of current (version 2.0) configuration data folders see NewConfigurationData - new configuration data here For description of old (version < 2.0) configuration data folders and how they are imported to new desktop layout see OldConfigurationData - old configuration data

Access to resources

Question (resources-file): Does your module use java.io.File directly?
Answer: No.
Question (resources-layer): Does your module provide own layer? Does it create any files or folders in it? What it is trying to communicate by that and with which components?
Answer: Yes. Default window system layout is in module layer. Other modules can define their own winsys elements (mode, group, component) in their module layer.
Question (resources-read): Does your module read any resources from layers? For what purpose?
Answer: Module reads its own configuration from its layer and eventualy from other module layers if provided. Data have following folder structure. It contains ModuleDataStructure - Module folder structure under Windows2 directory and LocalDataStructure - Local folder structure under Windows2Local directory.
Question (resources-mask): Does your module mask/hide/override any resources provided by other modules in their layers?
Answer: No.

Lookup of components

Question (lookup-lookup): Does your module use org.openide.util.Lookup or any similar technology to find any components to communicate with? Which ones?
Answer: Window Manager implementation (from core) registers itself and lookup is used from API part to get the instance and return as WindowManager.getDefault () and also WindowManager.componentRegistry(). gets the registered instance of TopComponent.Registry. Also there are provided implementations of DialogDisplayer.getDefault() and NodeOperation.getDefault() services.
There is also provided service which implements NbTopManager.WindowSystem - org.netbeans.core.NbTopManager$WindowSystem interface, which is used in core module. It is used for starting window system (loading and show) in startup sequence and finishiing of window system (hiding and saving) during exit sequence. The reason of this is that module API is not sufficient fot window system module, since it needs to provide its loading after all module layers are loaded etc.
Question (lookup-register): Do you register anything into lookup for other code to find?
Answer: WindowManager and TopComponent.Registry are registered. Used to find sinleton instance by singleton accessor.
Question (lookup-remove): Do you remove entries of other modules from lookup?
Answer: Yes. It removes implementation of NodeOperation.getDefault() service provided by openide-explorer module.

Execution Environment

Question (exec-property): Is execution of your code influenced by any environment or Java system (System.getProperty) property?
Answer: There are some, will put later here. Yes. netbeans.winsys.imageSource - 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 - 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 - 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 - 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 - 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 - 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 - 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 - 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 - 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 - 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 tab_focus_fill_dark - 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 - 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 - 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 - 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 - 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 - 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 - 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 - One of colors used in own tabs UI implementation. Usage example: To get color, call javax.swing.UIManager.get("tab_border") tab_bottom_border - 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 - One of colors used in own tabs UI implementation. Usage example: To get color, call javax.swing.UIManager.get("tab_sel_border") workplace_fill - One of colors used in own tabs UI implementation. Usage example: To get color, call javax.swing.UIManager.get("workplace_fill") tab_highlight_header - 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 - 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 - 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 - 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.
Question (exec-component): Is execution of your code influenced by any (string) property of any of your components?
Answer: Yes. Component can control its persistence and way how they are displayed in container. PersistenceType - 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 - 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.
Question (exec-ant-tasks): Do you define or register any ant tasks that other can use?
WARNING: Question with id="exec-ant-tasks" has not been answered!
Question (exec-classloader): Does your code create its own class loader(s)?
Answer: No.
Question (exec-reflection): Does your code use Java Reflection to execute other code?
Answer: No.
Question (exec-privateaccess): Are you aware of any other parts of the system calling some of your methods by reflection?
Answer: No. Now is the window persistence independent from projects.
Question (exec-process): Do you execute an external process from your module? How do you ensure that the result is the same on different platforms? Do you parse output? Do you depend on result code?
Answer: No.
Question (exec-introspection): Does your module use any kind of runtime type information (instanceof, work with java.lang.Class, etc.)?
Answer: No.
Question (exec-threading): What threading models, if any, does your module adhere to?
WARNING: Question with id="exec-threading" has not been answered!
Question (security-policy): Does your functionality require modifications to the standard policy file?
WARNING: Question with id="security-policy" has not been answered!
Question (security-grant): Does your code grant additional rights to some other code?
WARNING: Question with id="security-grant" has not been answered!

Format of files and protocols

Question (format-types): Which protocols and file formats (if any) does your module read or write on disk, or transmit or receive over the network? Do you generate an ant build script? Can it be edited and modified?
Answer: Module configuration is stored in XML files.
• windowmanager-properties2_0.dtd - -//NetBeans//DTD Window Manager Properties 2.01//EN
• mode-properties2_0.dtd - -//NetBeans//DTD Mode Properties 2.0//EN
• tc_ref2_0.dtd - -//NetBeans//DTD Top Component in Mode Properties 2.0//EN
• group-properties2_0.dtd - -//NetBeans//DTD Group Properties 2.0//EN
• tc_group2_0.dtd - -//NetBeans//DTD Top Component in Group Properties 2.0//EN
• sessionsettings-1_0.dtd - -//NetBeans//DTD Session settings 1.0//EN
Question (format-dnd): Which protocols (if any) does your code understand during Drag & Drop?
Answer: Window system DnD: Module uses standard AWT DragDrop protocol. TopComponent instances are transfered. Experimental, not enabled by default. Explorer DnD: It is also possible to DnD nodes in Explorer in such case instances of Workspace, Mode and TopComponent are transfered.
Question (format-clipboard): Which data flavors (if any) does your code read from or insert to the clipboard (by access to clipboard on means calling methods on java.awt.datatransfer.Transferable?
Answer: Module uses the same standard protocol as actions module. In case of Copy-n-Paste instances of Workspace, Mode and TopComponent are passed to clipboard.
There are defined three kinds of DataFlavorS for pure internal usage for DnD of TopComponentS. They are constructed using MIME Types constructed following way:
• DataFlavorDnDTopComponent - DataFlavor.javaJVMLocalObjectMimeType + "; class=org.openide.windows.TopComponent"
• DataFlavorDnDTopComponent.Cloneable - DataFlavor.javaJVMLocalObjectMimeType + "; class=org.openide.windows.TopComponent$Cloneable"
• DataFlavorDnDTopComponentArray - DataFlavor.javaJVMLocalObjectMimeType + "; class=org.netbeans.core.windows.dnd.TopComponentDragSupport$TopComponentArray"

Performance and Scalability

Question (perf-startup): Does your module run any code on startup?
Answer: Yes. The window system configuration is loaded and shown the result on screen.
Question (perf-exit): Does your module run any code on exit?
Answer: Module configuration is saved on exit.
Question (perf-scale): Which external criteria influence the performance of your program (size of file in editor, number of files in menu, in source directory, etc.) and how well your code scales?
Answer: The performance of window system can influence meny externals quite heavily. Cases which can singificantly influence window system responsiveness are:
• Long running client task performed in AWT thead
• Any sublcass of TopComponnet with slow internal responsiveness, e.g. with slow painting routines, validating, bad UI management etc.
Depends on number of displayed frames, components. Currently it is linear though some part of components initialization is done only when necessary (eg. when component is in JTabbedPane it is not necessary to initialize component ui when component is not visible.
Question (perf-limit): Are there any hard-coded or practical limits in the number or size of elements your code can handle?
Answer: Yes. Of course it is size of memory. The other limits were not set yet.
Question (perf-mem): How much memory does your component consume? Estimate with a relation to the number of windows, etc.
Answer:
Question (perf-wakeup): Does any piece of your code wake up periodically and do something even when the system is otherwise idle (no user interaction)?
Answer: No.
Question (perf-progress): Does your module execute any long-running tasks?
Answer: It executes long running tasks at startup and exit of IDE, i.e. loading and saving of window system configurations.
Question (perf-huge_dialogs): Does your module contain any dialogs or wizards with a large number of GUI controls such as combo boxes, lists, trees, or text areas?
Answer: No.
Question (perf-menus): Does your module use dynamically updated context menus, or context-sensitive actions with complicated and slow enablement logic?
Answer: No.
Question (perf-spi): How the performance of the plugged in code will be enforced?
Answer: There cannot be enforced the performance quality of TopComponent implementation, just could be provided performance test which could indicate some specific TopComponent instance doesn't fullfil certain performance criteria.