NetBeans UI

General  

Definitions

• Component: a top component such as our explorer (navigator), coordinate viewer, messages window, etc. 
• Mode: Defines a region of the application's split desktop which can contain a component. 
  • Mode type: Can be editor (AKA document), or view. 
    • modes inside document/editor area are of type "editor"; modes outside are of type "view" 
    • document/editor and view can't be mixed in same modes 
    • document/editor is the main thing (in OpenSim the 3D view is in the document/editor mode by default) and views are just helper windows 
  • Sliding mode: a mode in which the component is minimized and a tab is placed either on the right side, left side, or bottom of the desktop. 
  • See this for more on sliding modes
  • See this for information on creating a new mode
• User settings directory:
  • When running from netbeans it's in build/testuserdir
  • When running installed version, it's under Documents and Settings/<username>/Application Data/.opensim

Notes

• Netbeans uses various xml file to defines settings for the application.
• When the netbeans application is compiled (or maybe when it's run for the first time) netbeans merges the xml files from the different active modules as well as its own internal xml files. Because netbeans defines lots of things by default in its own internal xml files, you sometimes get unexpected results (e.g. in window layout) even though you thought you set the correct values in the local xml files.
• So we get around this by:
  • Hiding (suppressing) default netbeans things that we don't want to show up in our application. e.g. hiding menu categories or menu entries that we don't want.
  • Using our own modes for components rather than the built in ones. This way we know that netbeans won't merge with any internal settings and we can be sure that we get what we expect.

layer.xml

• Each module has a layer.xml file with various settings defining the actions, menu entries, default modes for components, etc.
• We currently specify most of the core settings in the view module's layer.xml file.
• As discussed above, we want to hide (suppress) default netbeans elements. Also the order in which things appear in the application is undefined, so you need to explicitly specify an ordering.
• Hiding: Things are suppressed/hidden by adding an entry for them with the name suffixed with "_hidden".
  • e.g. to hide the View menu that netbeans wants to create by default we use <file name="View_hidden"/> in the view module's layer.xml file.
• Specifying an order: The general format is <attr name="<NAME1>/<NAME2>" boolvalue="true"/>.
  • e.g. to specify that the Edit menu should appear after (to the right of) the File menu, we use{{<attr name="File/Edit" boolvalue="true"/>}} in the view module's layer.xml file.

Defining Menu Item

• Everything is under <folder name="Menu">
• To define a menu entry based on an action:
  • e.g. <file name="org-opensim-view-FileOpenOsimModelAction.instance"/> is under <folder name="Action"><folder name="Edit">
  • presumebly the org-opensim-view-FileOpenOsimModelAction part refers to the class' fully qualified name.
  • then under <folder name="Menu"><folder name="File"> we have <file name="org-opensim-view-OpenOsimModel.shadow">
    <attr name="originalFile" stringvalue="Actions/Edit/org-opensim-view-FileOpenOsimModelAction.instance"/>
    </file>where "shadow" refers to the fact that this is just a reference to an existing (shared) action object. Note that the shadowed name is arbitrary (in fact it says OpenOsimModel not FileOpenOsimModel, and didn't need the fully qualified org-opensim-view part).
  • The ordering of this entry in the menu is defined by <attr name="org-opensim-view-OpenOsimModel.shadow/org-opensim-motionviewer-FileLoadMotionAction.shadow" boolvalue="true"/>
    saying that it comes before the load motion entry. Usually you'd have two of these attr, to define what comes both 'before' and 'after' this entry... but in this case it's the first entry in the menu.

Specifying Custom Layout

• The window layout of the OpenSim application is defined in a file called WindowManager.wswmgr. In order to be able to define the default layout ourselves, we create this file in the source directory (src/org/opensim/view) and tell netbeans to copy that file over to the user's directory on startup.

WindowManager.wswmgr file

• The default window size (currently 1024x768) is specified under width= and height= under joined-properties and/or separated-properties(probably the former is the more relevant since we're running in non-separated mode)
• Under <constraints> we use horizontal and vertical splits to define the location of the "editor" region of the application. (In our case, the 3D view will occupy this editor region). Currently we have <constraints>
  <path orientation="horizontal" number="1" weight="0.7" />
  <path orientation="vertical" number="0" weight="0.8" />
  </constraints>
  Basically this says that first there we split horizontally (using a vertical split bar) and we choose the second (going from left to right) of the resulting split regions. (We will use the first split region for the navigator/coordinate viewer). The weights are used to specify the relative size of the regions. Having selected the second horizontal split region, we split it vertically (using a horizontal split bar) and select the first (top most) region. (We will use the bottom one for the messages component). It is this selected region (you can think of it as the top-right region) that we will use for the editor mode)
• See this for more information on how the desktop layout is defined (by recursively splitting the desktop horizontally and vertically).

Referencing wswmgr in layer.xml

• Tell netbeans to copy the wswmgr file by adding <file name="WindowManager.wswmgr" url="WindowManager.wswmgr"/>under <folder name="Windows2Local">.

Defining Custom Modes

• These are used to define (custom) modes.
• Similar to the way we used horizontal and vertical splits to define the location of the editor region in the WindowManager.wswmgr file, the wsmode files use these to define the region for the mode.
• Note: If the user resizes the component in the desktop, then that mode is still the same mode but its split region geometry changes (the{{<constraints>}} section of the corresponding xml files will be updated when you exit the application). However, if the user drags the component to dock it in a different part of the desktop then the component is now considered to be in a different mode. If it was not moved into an existing mode (a region of the desktop that already had some component or was already defined) then a new mode (an anonymous mode) is created for that component to be in.
• Also note: while we can avoid using netbeans own primary modes by suppressing them and using our own, we can't prevent components from getting minimized by the user into the left/right/bottom sliding modes.

wsmode file

• To get some sense of desired values for the mode, you may want to run the application, arrange the windows as desired, exit, and then take a look at the resulting wsmode in the user's settings directory. But usually it'll be cluttered with various other things so you should only use it for reference rather than copy it as is.
• Example of osimExplorerMode.wsmode:<?xml version="1.0" encoding="UTF-8"?>

<mode version="2.1">
<module name="org.netbeans.core.ui/1" spec="1.2" />
<name unique="osimExplorerMode" />
<kind type="view" />
<state type="joined" />
<constraints>
<path orientation="horizontal" number="0" weight="0.3"/>
<path orientation="vertical" number="0" weight="0.7"/>
</constraints>
<bounds x="168" y="223" width="537" height="508" />
<frame state="0"/>
<active-tc id="ExplorerTopComponent"/>
<empty-behavior permanent="true"/>
</mode>

• The thing that you need to set:
  • Set the name
  • Set the constraints. This is similar to what was done in WindowManager.wswmgr where you define the location of the mode in the split desktop by specifying the path (e.g. for this mode, first we split horizontally and select the left most region, then we split that vertically and select the top-most region)
  • Not sure how bounds was set...
  • The active-tc specifies which of the top components in this mode is active (maybe the same as "in focus", or in foreground)

Referencing wsmode in layer.xml

• Under <folder name="Windows2"><folder name="Modes">:
  • Tell Netbeans to copy the wsmode into the user's directory on startup using e.g. <file name="osimExplorerMode.wsmode" url="osimExplorerMode.wsmode"/>
  • Create a folder for the mode and define which components start up in that mode. e.g. <folder name="osimExplorerMode">
    <file name="ExplorerTopComponent.wstcref" url="ExplorerTopComponentWstcref.xml"/>
• Note that we suppress the netbeans modes, e.g. <file name="explorer.wsmode_hidden"/>

Component .settings and .wstcref files

• I think these are created automatically.
• Named e.g. ExplorerTopComponentSettings.xml and ExplorerTopComponentWstcref.xml by default.
• In the layer.xml file, we copy these into the appropriate folders (and appropriate names) using:
  • Copy the settings into <folder name="Components"> using <file name="ExplorerTopComponent.settings" url="ExplorerTopComponentSettings.xml"/>
  • As for the wstcref, as already mentioned earlier we copy it into the folder corresponding to the mode in which you want the component to start by default using e.g. <folder name="osimExplorerMode">
    <file name="ExplorerTopComponent.wstcref" url="ExplorerTopComponentWstcref.xml"/>

Links

• See this to understand a bit more about layer.xml contents.
• Window system API
• User interface specification