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.
Question (arch-overall):
Describe the overall architecture.
Answer:
Redesign documents.
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
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();
}
}
}
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!
Question (arch-where):
Where one can find sources for your module?
WARNING: Question with id="arch-where" 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:
The default answer to this question is:
These modules are required in project.xml:
-
org.openide.awt
-
The module is needed for compilation.
The module is used during runtime.
Specification version
6.2
is required.
-
NodesAPI
-
The module is needed for compilation.
The module is used during runtime.
Specification version
6.2
is required.
-
UtilitiesAPI
-
The module is needed for compilation.
The module is used during runtime.
Specification version
7.15
is required.
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,
in addition to or instead of the normal module dependency declaration
(e.g. tokens to require)?
Answer:
You might use OpenIDE-Module-Requires: org.openide.windows.WindowManager
but it is not generally done.
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
Question (compat-deprecation):
How the introduction of your project influences functionality
provided by previous version of the product?
WARNING: Question with id="compat-deprecation" has not been answered!
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.
Question (resources-preferences):
Does your module uses preferences via Preferences API? Does your module use NbPreferences or
or regular JDK Preferences ? Does it read, write or both ?
Does it share preferences with other modules ? If so, then why ?
WARNING: Question with id="resources-preferences" has not been answered!
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?
On a similar note, is there something interesting that you
pass to java.util.logging.Logger
? Or do you observe
what others log?
Answer:
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) 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
-
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.winsys.no_help_in_dialogs
-
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
netbeans.windows
-
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.
org.openide.windows.DummyWindowManager.VISIBLE
-
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.
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.
A bit different than property but still important is the
structured logging produced by this module:
org.netbeans.ui.actions.UI_ACTION_KEY_PRESS
-
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.
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.
KeepNonPersistentTCInModelWhenClosed
-
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
-
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
-
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
-
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.
OpenIDE-Transmodal-Action
-
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.
org.netbeans.core.windows.TopComponent.DragAndDrop.Enabled
-
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
-
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
-
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
-
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
-
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
-
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
-
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
-
Name of resource bundle property which forces splitter to ingore 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.
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? How the
project behaves with respect to threading?
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.
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 DataFlavor
S for pure internal usage for DnD of TopComponent
S.
They are constructed using MIME Types constructed following way:
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.