HOME > Community > Projects > ui

User Interface Specification: Window System, Final Draft

Authors: Jan Rojcek, Gabriel Tichy
Authors of visual appearance: Dusan Pavlica (Windows XP), Bruce Brown (Windows Classic), Bruce G. Lee (Metal)
Revision: $Revision: 1.38 $
Document History: available in CVS

Abstract: This document is the specification for the NetBeans windowing system. It defines basic window system elements, their behavior, appearance and interaction with user.

Table of Contents:

1 Introduction

2 User View

3 Detailed Spec - Compact Windows Mode (MDI)

3.1 Main Window

3.2 Window

3.3 Document Window

3.4 Window Area

3.5 Window Area Split Layout

3.6 Document Window Area

3.7 Document Area Split Layout

3.8 Outside Area

3.9 Window Groups

3.10 Toolbars

3.11 Work Flow

3.11.1 Documents Dialog

3.11.2 Document Quick List

3.11.3 Recent Window Switch

3.11.4 Resize Window Action

3.11.5 Move Window Action

3.12 Window Menu

3.13 Output Window

4 Detailed Spec - Separate Windows Mode (SDI)

4.1 Main Window

4.2 Window

4.3 Document Window

4.4 Window Area

4.5 Window Area Split Layout

4.6 Document Window Area

4.7 Document Area Split Layout

4.8 Native Windows

4.9 Window Groups

4.10 Toolbars

4.11 Work Flow

4.12 Window Menu

4.13 Output Window

5 Switching Between SDI and MDI

5.1 Switching from MDI to SDI

5.2 Switching from SDI to MDI

6 Switching Between Projects

7 References

1 Introduction

The window system is a visual framework of the IDE. It displays windows and allows to manage them to suit the user needs while performing a concrete task.

Attributes of the new design:

document centric - documents are the center of windowing system
simple - provides only necessary features
open - open to the user customization; allows an easy module integration to the default layout
keyboard accessible - all features are fully keyboard accessible

The new window system supports two modes - MDI and SDI. MDI is the default mode presented to the user in GUI as "Compact Windows Mode". SDI is named "Separate Windows Mode". This specification describes the MDI mode in details. The SDI mode is described only in a differences over the MDI mode.

1.1 Terminology

Terminology used in this document:

Window System - a framework controlling behavior of windows and document windows. Window system doesn't control behavior of dialog boxes, which are native windows controlled by native window manager.
Main Window - the main NetBeans window containing main menu, toolbars, status line and in MDI mode also windows and document windows. In SDI the main window doesn't contain windows, neither document windows.
Window - basic window system element, also called "IDE Window" in SDI. Note: Some images below use the old terminology and refer to Window as View.
Document Window - a special type of window with different behavior and characteristics than regular window. Document Window is part of the window system. Some images below use the old terminology and refer to Document Window as Editor.
Dialog Box - a special native window controlled by native window manager. Dialog boxes are not part on NetBeans window system, and are not covered by this spec.
Window Area - area inside the main window used for laying out Windows. Some images below use the old terminology and refer to Window Area as View Area.
Document Area - area inside the main window (surrounded by Window Area) used for laying out Document Windows. Some images below use the old terminology and refer to Document Area as Editor Area.
Status Line - a component displaying status of an action performed in IDE. This is not the status line of editor window or explorer windows. Those status lines are part of those components and this specification doesn't define their behavior. The status line is also called "Status bar".

SDI specific terminology:

IDE window - another term used for referring to window in SDI. As in SDI also native windows exist, the term "IDE window" refers to a window.
Native Window - a window used in SDI for displaying windows and document windows.

2 User View

User View document provides the foundation concepts for the window system specification.

3 Detailed Spec - Compact Windows Mode (MDI)

3.1 Main Window

Main window is a container for application menu, toolbars, status line and windows which are provided and controlled by the window system. All of the windows are always displayed inside the main window, neither user can separate them out of the main window. The windows are shown in two areas depending on a type of displayed window. The areas are a document area and window area. The document area is used for document windows, and the window area lays out all of the other windows.

Figure 1: Main Window

The main windows characteristics are following:

title - title of main window contains the application name and might contain current project name if the project module is part of IDE distribution. The title pattern is following: "<application_name> - <project_name>"
icon - icon of main window is the application icon

3.2 Window

Java Look and Feel Advanced Topic defines a window as a basic window system element used for displaying and manipulating with a user interface objects.

IDE windows can be distributed into different categories according to objects they display and their usage. Document windows are essential for this design and are specified separately. All of the other windows (supportive windows and all primary windows except document windows) are covered under the general term "window". Complete distribution of windows into categories is in the user view document.

This section specifies characteristics, interaction and appearance of the windows. The document windows are specified in the next section.

Figure 2: Window

3.2.1 Characteristics

Menu access - each window has its own item in the main menu. This means there is only one instance of each window and when the user closes a window, she is able to open it back using a menu item. Consequence of this is that a window generated from contextual action cannot be implemented as Window but should be either made Document Window or Dialog Box (e.g. Explore from Here, Properties).
Persistence - a closed window keeps the content (an expanded tree, compiler output) and displays it when it is open again. It means closing of a window doesn't dismiss a displayed object (neither output). Same should be true when the IDE is finished and started again.
Base name - a window has a short base name used for identifying the window in menus, for example "Properties" or "Projects".
Descriptive name - apart of base name a window can have a more descriptive name which describes currently displayed object, or provides other useful information, for instance "Properties of ColorPicker", or "Projects - MyProject". The descriptive name is displayed in a window's title bar.

3.2.2 Interaction

3.2.2.1 Open

The user opens a window through the Window menu. Each window has a menu item in the window menu. Invoking an item either opens and activates a window or selects and activates already open window.

Figure 3: Window menu - a window items

| Window | ---------- Window 1 Window 2 Window 3 ... Window n Window A1 Window Category A > Window A2 Window Category B > ... Window Category n > -------------------- ...

Figure 4: Window menu example

3.2.2.2 Close

To close a window, the user either clicks the close button in the window header, or uses the "Close Window" menu item in the main menu or contextual menu.

3.2.2.3 Maximize and Restore

A window can be maximized. The user can achieve that by invoking the main or contextual menu item "Maximize Window". If a window is maximized the user can restore it to the previous state by invoking the "Restore Window" menu item. The maximize menu item changes to the restore menu item is a window is maximized. Both menu items have the same shortcut.

A window can be maximized also by double-clicking its title bar. If a window is already maximized then double-clicking restores the window to its previous state.

3.2.2.4 Contextual menu

The contextual menu of window is open when the user right-clicks on the window header. It contains following menu items:

Close Window - closes the window
Maximize Window - maximizes the window.
Restore Window - restores the maximized window to a previous position.

Figure 5: Window contextual menu

-------------------------
Close Window    [Ctrl-F4]
Maximize Window [Shift-ESC]
-------------------------

Figure 6: Window contextual menu (in maximized state)

-------------------------
Close Window    [Ctrl-F4]
Restore Window  [Shift-ESC]
-------------------------

3.2.3 Appearance

Icon - window doesn't show an icon in the window header. Icons are displayed only in the Window menu to make a visual connection between windows and their icons in Recent Window Switch.
Tooltip - tooltip always displays the name of the window.
Windows XP L&F
Windows Classic L&F
Metal L&F

3.3 Document Window

A Document window is a special kind of window. It displays a user object that is part of user project, or serves the role of primary window for other kind of objects, for instance the web browser for internet viewing, or the javadoc browser for javadoc viewing.

Some of the objects may have more than one associated document window, for example a form object can be viewed by source editor, form editor, and also by cvs viewers (annotate, diff, ...). One of the multiple document windows of an object is always a base document window of the object. All other document windows of that object are extending document windows. For instance, in case of form object, the source editor is the base document window, and form editor, cvs viewers are the extending document windows.

Figure 7: Document Window

3.3.1 Characteristics

Name of base document window - name of the base document window corresponds to a name of object it displays, e.g. "ColorPicker". Name of the base document window doesn't contain other information than the name of the object to make the document header as short as possible. An exception to this rule is a modified status, which is currently displayed as an asterisk in the document header. If the explorer objects (in Filesystems or Project windows) display the file name extensions, then also the document window name shows the file name extensions.
Name of extending document window - name of the extending document window also corresponds to a name of object it displays, e.g. "ColorPicker". However, the name of the window contains also a suffix identifying the type of editor/viewer contained in the document window. The name pattern is following: "<object name> [<editor/viewer type>]". An example is "ColorPicker [Form]", "ColorPicker [VCS Annotate]", "ColorPicker [VCS Log]".
Description - description provides important information about the object displayed in the document window, or other useful info. An example is VCS status and read only attribute. Description is displayed in a tooltip over the document header.
Icon of base document window - each document window has an icon. The icon is the same as the icon of object viewed by the document window. It means the icon is the same as icon of object displayed in the explorer. The icon badges from the explorer are also displayed on the base document window icon.
Icon of extending document window - icon of extending document window doesn't represent displayed object, but the editor or viewer type contained in the extending document window. For example, a form editor would have a special icon, all VCS viewers would have a special icon (not a special icon for each VCS command, but the same icon for all VCS type viewers).
Cloneable - document windows can be cloneable.

3.3.2 Interaction

The user can save, close and activate the open document windows with a documents dialog.

3.3.2.1 Open

The user opens a document window using a contextual action of associated object. Default document windows are open with the open action, opening of other document windows depend on a type of contained editor or viewer, e.g. CVS views are open with CVS contextual actions. Default document windows are a windows which are needed for complete object editing. For example the source editor and form editor of a form object should be open at once (source editor focused). If the object is already open it is selected and activated.

Some of the document windows can be open from the main menu. Such windows are a single instance viewer of miscellaneous objects, like web browser or javadoc browser.

3.3.2.2 Close

The user closes a document window using the close button in the window header or "Close Window" menu item from the main or contextual menu.

3.3.2.3 Save

The user can save a modified document contained in the document window by using the "Save" action from the main (File|Save) or contextual menu. The Save action is disabled if the document hasn't been modified.

3.3.2.4 Clone

A clonable documents can be cloned using "Clone Document" menu item from the main or contextual menu. Invoking the clone action creates a new document window containing the clone of original document. This action is disabled if the document is not clonable.

3.3.2.5 Maximize and Restore

A document window can be maximized. The user achieves that by invoking the main or contextual menu item "Maximize Window". If a window is maximized the user can restore it to the previous state by invoking the "Restore Window" menu item. The maximize menu item changes to the restore menu item is a window is maximized. Both menu items have the same shortcut.

A document window can be maximized also by double-clicking its title bar. If a window is already maximized then double-clicking restores the document window to its previous state.

3.3.2.6 Contextual menu

The contextual menu of document window is open when the user right-clicks on the window header. It contains following menu items:

Close All Documents - closes all open document windows
Close Other Documents - closes all open document windows except the selected document window
Save Document - saves the document
Clone Document - clones the document
Close Window - closes the window
Maximize Window - maximizes the window.
Restore Window - restores the maximized window to a previous position.

Figure 8: Document Window contextual menu

------------------------------------
Close All Documents  [Ctrl+Shift-F4]
Close Other Documents                
------------------------------------
Save Document        [Ctrl+S]
Clone Document       [N/A]
------------------------------------
Close Window         [Ctrl+F4]
Maximize Window      [Shift-ESC]
------------------------------------

Figure 9: Document Window contextual menu in maximized state

------------------------------------
Close All Documents  [Ctrl+Shift-F4]
Close Other Documents                
------------------------------------
Save Document        [Ctrl+S]
Clone Document       [N/A]
------------------------------------
Close Window         [Ctrl+F4]
Restore Window       [Shift-ESC]
------------------------------------

3.3.3 Appearance

3.4 Window Area

A window area is a window system area used for laying out windows around a document area which contains document windows.

The Window area is bounded by two bounds. Outer bound is identical to the main window's left, right and bottom bound, and top bound is the same as bottom bound of toolbar area. Inner bound is identical to the document window area bound. The window area lays out windows using a split cell layout.

Figure 10: Window area

Figure 11: Windows in Window area

3.4.1 More Windows in a Split Cell

The split cell layout allows to open more than one window in a one split cell at the same time. In such case the topmost window overlaps windows beneath, and window tabs are used for showing the overlapped windows and allow the user to select them. Selecting a tab moves a window to front and actives it.

Figure 12: Window tabs

3.4.2 Maximized Split Cell

A split cell can be maximized, then it overlaps the whole window area, hiding other open windows and document windows. When a maximized window is restored, the window area and document area are shown.

3.4.3 Interaction

3.4.3.1 Maximization

Maximization of a split cell is presented to the user as maximization of window. An appropriate window menu item is "Maximize Window" for maximization. If a window is maximized then the menu item changes name to "Restore Window". Double-clicking a title bar invokes the same maximize/restore action. If any window that is not part of maximized split cell gets activated, then the split cell is restored to the previous state.

3.4.4 Appearance

3.5 Window Area Split Layout

The split layout is based on chains of split cells. The chain can be horizontal or vertical. A vertical chain contains vertically divided cells, and horizontal chain contains horizontally divided cells. Each cell in a chain contains one or more windows, document area, or another chain of split cells following this constrain: a cell from a vertical chain of split cells can contain horizontal chain of split cells, and likewise, a cell in horizontal chain can contain a vertical chain. So the layout is a tree hierarchy of nested horizontal and vertical chains of split cells.

Figure 13: Chain of vertical split cells

Figure 14: Chain of horizontal split cells inside vertical split cell

3.5.1 Resizing Split Cell

The resizing behavior of split cell is not completely proportional. The document window area is a component with the maximum resize weight. When a split cell is resized and the document window area is part of split cell's structure (inside split cell's tree), then all split cells on the path to the document window area have a resize weight of 1 and other cells have a weight of 0. This means that only the document window area is resized and other cells either do not resize or modify their size according to the document window area. If the document window area is not in the resized cell's tree, then all cells in the tree have a resize weight of 0.5, meaning that they change size proportionally.

Figure 15: Before resizing of split cell

Figure 16: After resizing of split cell

3.5.2 Adding and Removing Split Cell

When a window is added to the window area the layout have to accommodate that. If a window is added to an existing split cell (some window is already open there) then the layout does not change. Otherwise the split chain the window is added into is resized according to the same rules as when resizing a split cell. The value how it should change depends on the last (default) width of window if it is added into a vertical split chain, and height if added into a horizontal chain. Other cells (depends on position of the document window area) shrink their size and the window can be added into the split chain.

Figure 17: Before adding a window to window area

Figure 18: After adding a window to window area

When a last window from a split cell is removed from the window area the layout is changed too. It is the opposite action to opening a window. The cells in the split chain that the window is apart of increase their width/height (vertical/horizontal chain) according to the size of closing window.

3.5.3 Interaction

The user can modify the windows layout by:

resizing split cells
attaching of windows

3.5.3.1 Resizing

Split cells are divided by splitters that can be resized by the user. Dragging with the mouse moves the splitter and releasing the mouse button resizes neighbor split cells (divided by splitters). It is not possible to drag a splitter over neighbor splitters in a split chain. Layout inside cells changes according to description above.

3.5.3.2 Attaching

Attaching of windows is performed by DnD. The user can drag a window and drop it:

to a side of different window (top, left, bottom, right)
to a side of window area (top, left, bottom, right)
to a side of document area (top, left, bottom, right)
on a window (adds a window to the same split cell)
on a splitter (adds a window between split cells)

Attaching is the method of creating chains of split cells. Attaching to the left or right side of a cell in vertical chain adds a new cell to the chain. Attaching to the top or bottom of cell in vertical chain creates a horizontal split chain in the cell. Originally the window area only contains the document window area. The first attachment of a cell creates the first chain, either vertical or horizontal. When a cell is attached to the left side of document window area, the document window area shrinks and a splitter is created between the window and document window area. The window area contains one vertical split chain.

Figure 19: Window attached to left of document window area

Attaching to bottom of another window shrinks the window and creates split between the windows.

Figure 20: Window attached to bottom of another window

Attaching to left of the document window area shrinks the document window area and creates split between the window and the document window area.

Figure 21: Window attached to left of document window area

3.5.3.3 Drag & Drop

Drag and Drop is a convenient way for modifying the layout. DnD is performed by dragging a window by a drag source and dropping the window on a possible drop target.

First, we define the drag source where the dragging starts. In case of a window it is the window header. When the dragging starts, the window stays at the same position, only a drop feedback is appearing while the drop is not completed.

Figure 22: Drag source - Window

The drop feedback displays border that represents exact position and size of dragged window after DnD completion. If a window is added into tabbed windows, then the drop feedback also draws a tab on a new position (position between existing tabs, not precise location) in the tabs. When the window is dropped, it changes its position and the window area layout accommodates the change.

3.5.3.3.1 Drop Target - Window

A drop target can be "Top", "Left", "Bottom", "Right" or "Center" area of window. Dropping to these targets is the same as performing the corresponding attaching action. "Center" creates a tab for the window and adds the window to the cell. The position of mouse cursor in the center target determines position of new tab in existing tab order. This way, the user is able to change order of tabs by DnD.

Figure 23: Drop target - Window

3.5.3.3.2 Drop Target - Document Area and Main Window

A Drop target in the document window area's "Top", "Left", "Bottom", "Right" part corresponds to the attaching to documents area action. The center part of document window area is not allowed drop target. The drop target can also be the outer "Top", "Left", "Bottom", "Right" border of the window area. In such cases it attaches to the top level split cell resulting either in creation of a new top level chain of split cells containing the dragged window and the whole content of window area or addition of a new cell to top level chain. Window can not be dropped outside of the main window area.

Figure 24: Drop target - Document window area

3.5.3.3.3 Drop Target - Splitter

A drop target can be also a splitter dividing split cells. In this case the dragged window is added to the chain of split cells that the splitter belongs to, between the split cells.

Figure 25: Drop target - splitter

If user changes the layout it is remembered. Therefore, when the user closes a window and opens it back to the window area, then the window is open at the same position. Also order of windows in a same cell is persisted. So the windows are open always in the same tab order.

3.6 Document Window Area

Document window area is a window system area that keeps all the open document windows. Windows in the document window area are laid out into chains of split cells similarly to how windows are laid out in the window area. Therefore more document windows can be visible at the same time.

Resizing and opening of new document windows and closing the document windows behaves same way as in the window area except that in the document window area the resizing is proportional. It means all split cell have the same resize weight.

Opening and closing a document window doesn't affect the size of the document window area. When the last document window is closed, document window area stays empty at the same size.

Document windows and windows open always on the same place in the document window area - the virtual center of document window area.

3.6.1 Document Windows Tabs

More documents in a split cell are displayed in a tabbed pane. A document header actually is a tab. The tabs of tabbed pane are scrollable (read a separate specification describing scrollable tabs behavior).

If a new document window is open it is inserted into the tabbed pane as the last tab. This doesn't apply for cloning of a document window. New document window created by cloning is inserted next to the tab of original window.

3.6.2 Maximized Split Cell

A document window is maximizable. When a document window is maximized the cell containing the window is maximized, so it overlaps the whole window area.

3.6.3 Interaction

3.6.3.1 Maximization

Maximization of a split cell is the same as in the window area and is presented to the user as maximization of document window. An appropriate window menu item is "Maximize Window" for maximization. If a window is maximized then the menu item changes name to "Restore Window". Double-clicking a title bar invokes the same maximize/restore action. If any window that is not part of maximized split cell gets activated, then the split cell is restored to the previous state.

3.6.4 Appearance

3.7 Document Area Split Layout

The document area split layout works on the same principles as the split layout in window area. Adding, removing and resizing of split cells work the same way.

Figure 26: Document window opened in the center of document window area

3.7.1 Interaction

Resizing of a split cell is achieved be dragging the splitters.

3.7.1.1 Attaching

Attaching a document window to the bottom of another document window shrinks the document window and creates a splitter between them.

Figure 27: Document window attached to bottom of another document window

Attaching to right part of another document window shrinks the document windows and creates a splitter between them.

Figure 28: Document window attached to right of document window area

3.7.1.2 Drag & Drop

Drag and drop is preferred method of modifying the layout of the document window area. The user can drag a document window by its header (tab). When a dragging starts it displays a rectangle with tab showing the position of window where a document window will be placed and position of tab in a tabbed pane. The position and size of the rectangle is the same as the position and size of the document window after DnD completion.

Figure 29: Drag source - Document window

3.7.1.2.1 Drop Target - Document Window

The drop target can be "Top", "Left", "Bottom", "Right" and "Center" part of a document window. Dropping performs the appropriate attaching action. "Center" creates a tab for the window and adds the window it to the cell. Position of mouse cursor in the center target determines position of new tab in existing tab order. Therefor, the user is able to change order of tabs by DnD.

Figure 30: Drop target - Document window

3.7.1.2.2 Drop Target - Document Window Area

It is also possible to drop a document window to a document window area bound (Top, Left, Bottom, Right). In this case, either a new top level chain of split cells is created (dropping Top/Bottom to vertical chain, or Left/Right to horizontal, or any part if only one document window tabs is there), or the document window is added to the top level chain (dropping Top/Bottom to horizontal chain, or Left/Right to vertical).

Figure 31: Drop target - Document window area

If the mouse cursor is not over a possible drop target, the drop feedback rectangle is hidden and the cursor notifies the user about the forbidden operation.

3.8 Outside area

Outside area in MDI is no longer used. All windows are open inside the main window. Only secondary windows (dialog boxes) can be open as separate windows and are implemented as modal or non-modal dialogs.

3.9 Window Groups

A Window group is a replacement of workspace. It is a group of windows which is used during a concrete task. For example GUI Editing group of windows consists of the component palette, component inspector (just a components hierarchy) and properties window. Debugging group consists of all debugger windows (local variables, watches, call stack, etc.).

A Windows from a window group are open when the group is opened. But not all windows from a group have to be open. Only those that are defined to open by default, or those which the user wants to open. When a group is opened the user may open or close windows contained in the window group. Then, when the group is closed, the open windows from the window group are remembered and are open when the group is opened again. Closing a window group means closing windows from the window group. An example is the debugger window group, the user may prefer to use the local variables window over the watches, so closes the watches during debugging and opens the local variables, next time when starts the debugger, the watches are open and local variables are not.

Some of windows are not affected by the user customization and are open always (even if the user closed them before). Such windows are considered necessary for a concrete task, thus are open automatically, always. For example, compiler output associated to compile action.

Windows from a window group should be closed automatically when a group is closed. A group is closed when the user finishes an associated task. Only those windows should be closed, which are not relevant for the task after the task completion. It means they do not provide any useful data, or actions that might by used even after the task finish. An example of windows which should be closed are the component palette, and component inspector. The output window is an example of window which provides useful data even after the completion of executed process (= task), thus should not be closed after finishing the executed process.

Only windows which were open by the group or open by the user during the group has been opened are closed when the group is closed. As more window groups can be opened at the same time, it is important to not close a window which belongs to another open group.

3.9.1 Window Group Invocation

A Window groups are always opened and closed automatically. The user doesn't explicitly control the groups. There are two ways how to open a window group. The group is opened by following either selected document windows, or an invoked action. Example of former approach is to open GUI Editing group by selecting a the form editor window. The later is illustrated by opening the debugging group by starting the debugger.

The group is closed accordingly to how it was opened. In case of opening by an action, the group is closed when the process executed by the action finishes. An example is debugger group, which is closed after the finish of the debugger. In other case, the group was opened by selecting a document window, therefor it is closed when the last document window is deselected. For instance, the source editor is selected results in deselecting the form editor what closes the GUI Editing group.

Window groups opened by selected (last one active) document window are exclusive groups, as there is always only one document window selected. Important point is that if one user action results in closing and opening window groups, then for the user it should look like atomic action. The window area, should not be repainted twice. This is mostly important for switching between document window tabs.

Figure 32: Window base layout

When the user starts a task that requires the window group A, the window group is opened and windows are open. After finishing the task, the group is closed.

Figure 33: Window Group A is opened

The same happens when the user starts the window group B. After finishing the task, the group is closed.

Figure 34: Window Group B is opened

If the group B is opened and the user starts the task that requires the group A, it is opened too. Then depending on which of the tasks is finished first, that group is closed and the layout accommodated.

Figure 35: Window Groups A and B are opened

3.9.2 Interaction

When a window group is opened, the user can define which of the windows are open in the group, it means which of the windows would open next time the group is opened. For instance, the user starts the debugger and some of the debugger windows are shown. But the user decides that she prefers using Watches instead of Local variables window. So she opens the Watches window and closes the Locals window. That also means the user defined that the watches window will open and the locals will not open, when next time the debugger group is opened.

3.10 Toolbars

There is only one active configuration of main toolbars for the whole IDE. It doesn't change automatically, only the user is able switch the configurations. The user is also able to customize the toolbar configurations.

Each document window should have its own toolbar for document (editor/viewer) specific actions. This toolbar is part of document window. An examples of document windows containing a toolbar are "Java Editor", "Form Editor", "Web Browser", "Javadoc Index Search".

3.11 Work Flow

For speeding up the user performance following features are provided:

3.11.1 Documents Dialog

The user can manage open document windows with a documents dialog. The documents dialog is a non-modal dialog which displays an alphabetically ordered list of all open document windows, and allows the user to activate a document window, close document windows, and save documents.

Figure 36: Documents dialog

The main dialog components are:

"Documents" list - Every item in the list contains icon, and name of document window as displayed in document window headers, it means also with asterisk in case a document has been modified. The list is alphabetically ordered and allows a multi-selection.
"Search for" popup - For a fast keyboard navigation in the list the user can navigate to an item by typing its name. If the list is focused and the user starts pressing character keys, a "Search for" popup is displayed showing typed characters, and the list moves selection to the matching item in the list. If non of the items matches typed characters, then the selection stays at the last item. The backspace key allows the user to delete the last character. The "Search for" popup is closed if the user hits Enter, Esc, or the arrow keys. The search is keyboard insensitive.
"Description" text area contains information that should help user to identify documents with equal names and icons. It should contain path to the document and should be the same as description of document window as shown in tooltips over the document window tab.

The list buttons:

"Switch to Document" button activates a selected document window and closes the dialog. The button is disabled if no item or more than one item in the list is selected. This is the default button.
"Close Document(s)" button closes the selected document window and removes its items from the list. If the item represents a modified (unsaved) document, then a confirmation dialog for closing unsaved document is shown. The button is enabled if at least one item in the list is selected. This button doesn't close the dialog.
"Save Document(s)" button saves selected unsaved items. The button is enabled only if at least one item from the selected items is unsaved. This button doesn't close the dialog.

The dialog buttons:

"Close" button dismisses the dialog.

The dialog characteristics are:

title is "Documents".
default size is 540x400.

3.11.2 Document Quick List

The scrollable tabs in the document area complicate access to the tabs, especially when many document windows are open. To speed up switching between the document window tabs for mouse users the windowing system provides a quick list of open document windows.

The quick list is a popup window allowing a mouse user to quickly activate a document window. The popup window is invoked by clicking on the quick list button, which is placed next to scroll tab buttons. The quick list window shows an alphabetically ordered list of all open document windows in the tabbed pane. Each item in the list displays an icon and name of document window. The user activates a document window by clicking on its item in the quick list popup window.

Overall behavior and appearance is the same as of a combobox popup window. The only difference is that if there is not enough space on the screen to fit all items in one column then the list is organized into multiple columns. The number of columns depends on how many columns are needed to fit all items on the screen.

Sometimes multiple files have a same name, thus the user wouldn't be able choose between them in the list if only the document name was shown. Therefor if the user moves selection in the list, the full path of the selected document is shown in the status line.

Quick list characteristics:

Alphabetically ordered - the list is alphabetically ordered, if there are multiple columns, the first item is in the leftmost column.

Figure 37: The document windows quick list

3.11.2.1 Appearance

Icon and name - every item in the list shows an icon and name exactly the same as it appears in the document tab. If it doesn't have an icon in the document tab, then no icon is shown in the quick list.
Active document - the currently active document is shown in bold font.
Multiple columns - if there is not enough screen space (not the main window space!) to show all items in one column then the list is organized into multiple columns.
Same column width - if there are multiple columns they all have the same width of the widest column.
Maximum column width - the maximum column width is 250 pixels. If an item is wider, then it is shortened a standard way using ellipsis, e.g. instead of "SelectionAndScrollPostitionManager.java" show "SelectionAndScrollPositionManager.j..."
Windows XP L&F
Windows Classic L&F
Metal L&F

3.11.3 Recent Window Switch

A recent window switch is used for cycling between recently activated windows. Pressing the action shortcut keys (Ctrl-Tab or alternatively Ctrl-`) and releasing the keys in shorter time than 200ms switches to the recently used (activated) window without showing a popup window.

If the user presses the action shortcut keys (Ctrl-Tab) and still holds the modifier key (Ctrl) key down for longer than 200ms then a popup window listing the window icons in the most recently used (activated) order is shown. The first item in the list is currently active window. The second item in the list is selected when the popup shows up.

The popup is closed when the user releases the modifier key (Ctrl) and the selected window in the list is activated. Pressing Tab key, while still holding the modifier key (Ctrl) down, moves the selection to the next item in the list. When the selection reaches the end of the list, it starts from the beginning. Holding the Shift key together with the modifier key (Ctrl) and pressing the Tab key moves the selection to the opposite direction. In such case, if the selection reaches the beginning of the list it starts from the end of the list.

The recent window switch allows to switch between recently used document windows, so it ignores activation of regular windows and doesn't show them in the recent list.

The action shortcut is customizable.

3.11.3.1 Appearance

The popup list of recent window switch has the same appearance and multiple column behavior as Document Quick List. The only difference is that the recent window switch shows up centered on the screen.

3.11.4 Resize Window Action

The Resize action allows the user to change size of window using the keyboard. The menu item has a submenu with four items labeled "Top", "Left", "Bottom", "Right", corresponding to splitters around the window in the layout. If there is no corresponding splitter around the window, then the item is disabled. Invoking an item draws the black line feedback over the splitter, same as in DnD. The user then uses arrow keys to move the splitter, and confirms new position of the splitter with Enter, or cancels operation with Esc. Mouse can be used for changing the position of splitter too. It works the same way as in DnD, only the user doesn't have to hold down the mouse button. Pressing the mouse button actually confirms the new position of splitter.

3.11.5 Move Window Action

The Move action is a keyboard alternative to Drag & Drop. It would allow the user to perform attaching of windows by moving a window directly in the layout by arrow keys. When the user invokes the menu item, move feedback is displayed in the layout, similar to DnD feedback (black rectangle of moved window). When the user hits an arrow key, the rectangle is moved in the direction of the arrow key on a new position of the window. The move action is canceled when the user press' Esc button, and confirmed with Enter button. The window rectangle can be also moved by mouse, same way as in DnD, except the user doesn't have to hold mouse button down. Pressing the mouse button confirms the new position of window.

3.12 Window Menu

The window menu is used for manipulation with open windows and document windows. The menu has also a section for opening the windows.

The window menu contains an item for each window in the window system. These items are used for opening and activating a window. If the user invokes an item of a window which is not open, then it is open on the last (or default) position. If the window is already open, then it is activated. If it is open but its tab is not selected, then the tab is selected and the window is activated. The menu items are always enabled.

A manipulation window menu items are following:

Switch to Recent Window - if invoked by keyboard shortcut then opens the recent window switch. If invoked from main menu then activates the recent window, without showing the recent window switch. This action would be used mostly via the keyboard shortcut, it is in the menu for making the action and shortcut visible to the user. This menu item is enabled only if there is more than one window or document window open.
Switch to Document - activates the recently selected document window. The action is enabled only if a non-document window is active, and there is at least one document window open.
Select Document in - shows the submenu of explorer windows the user can navigate to from the selected document window. The whole action is specified at: Select Document Node in Explorer UI Spec.
Close Window - closes the currently active window or document window. Enabled only if any window is active.
Maximize Window - maximizes a window. Enabled only if any window is active.
Restore Window - if a window or document window is maximized, then the name of the action is restore. It restores the maximized window to a previous non-maximized state. Enabled only if any window is active.
Clone Document - clones the currently active document window. Enabled only if a document window is active and it is clonable.
Close All Documents - closes all document windows in the document window area. Enabled only if at least one document window is open.
Close Other Documents - closes all document windows in the document window area except the selected document window. Enabled only if at least two document windows are open.
Documents... - opens the documents dialog. Enabled only if at least one document window is open.

Figure 38: Window menu - with mnemonics and shortcuts

| Window |
----------
 Window 1
 Window 2
 Window 3
 ...
 Window n                                                Window A1 
 Window Category A                                     > Window A2 
 Window Category B                                     >
 ...
 Window Category n                                     >
 -------------------------------------------------------
 Switch to Recent Window  (W) [Ctrl-`]
 Switch to Document       (S) [Ctrl-0]
 Select Document in       (n)                          >
 -------------------------------------------------------
 Close Window             (C) [Ctrl-F4]
 Maximize Window          (M / s for Restore) [Shift-ESC]
 -------------------------------------------------------
 Clone Document           (l) [N/A]
 Close All Documents      (A) [Ctrl+Shift-F4]
 Close Other Documents    (e)                 
 Documents...             (D) [Shift+F4]
 -------------------------------------------------------

3.13 Output Window

The output window is a container window containing the outputs of processes running in the IDE. As more processes in the IDE can be executed at the same time, the output window should display more outputs at once. The tabs are used to achieve that. Each executed processes adds a tab to the output window.

3.13.1 Characteristics

Name - the name is "Output"
Output tab name - each output tab displays the name of output.

3.13.2 Interaction

The user discards output tabs manually using "Discard Output Tab" or "Discard All Output Tabs" contextual menu items. "Discard Output Tab" discards the selected output tab. "Discard All Output Tabs" discards all output instances leaving the output window empty. The contextual menu items appear over the output tabs and over the output tab contents.

4 Detailed Specification - Separate Windows Mode (SDI)

The old NetBeans windowing system had two modes - MDI and SDI. Also the new windowing system has two modes. The above sections describe mostly the "Compact Windows" mode which is replacement of MDI mode. The old SDI mode is replaced by "Separate Windows" mode, and this section describes the basic characteristics of this mode.

The Separate Windows (SDI) mode is based on the Compact Windows (MDI) mode, therefor it has most of its characteristics. The main difference is that windows in SDI mode can live also outside of the main window in separate native windows. It basically means that it is possible to take one elementary split cell from the window area and put it into a separate native window.

Another difference is that the main window doesn't contain the window area and document area. These areas are displayed in a separate singleton native window named Editor. It means that the SDI mode has two singleton native windows - Main window, Editor window. It can also have multiple other native windows used for displaying windows not contained in window area.

Each native window has a name which corresponds to the name of selected window inside the native window. The native windows (except the editor window) can not be split. It means the user can put more windows into a native window, but these windows will be tabbed.

As the Editor native window represents the whole window and document area, it can be split the same way as the window and document areas in MDI.

The Window Groups and Drag & Drop work also in SDI, with the same characteristics and constraints if they are applicable.

4.1 Main Window

Main window in SDI is a container for main menu, toolbar and status line. All IDE windows are displayed in separate native windows. The document windows are shown inside a special native window named "Editor" and non-document windows are displayed either in Editor window or in native windows named according to the currently selected IDE window inside the native window.

The native windows in SDI mode:

Main Window - the application window displaying the main menu, toolbars and status line.
Editor Window - a singleton native window containing window and document areas.
Native Windows - special native windows containing IDE windows. It contains a window or multiple tabbed windows.

4.2 IDE Window

The characteristics, interaction and appearance of window in SDI is the same as of window in MDI.

4.3 Document Window

The characteristics, interaction and appearance of document window in SDI is the same as of window in MDI.

4.4 Window Area

The characteristics and behavior of window area in SDI are the same as characteristics of window area in MDI. The only difference is in DnD behavior.

4.4.1 Interaction

4.4.1.1 DnD

In SDI, the document area, main window, native windows and an area outside of all native windows are possible drop targets:

document area - creates a separate native window
main window - creates a separate native window
native window - adds the window into tabbed windows inside the native window
outside area - creates a separate native window

4.5 Window Area Split Layout

The window area split layout works the same way in SDI as window area split layout in MDI.

4.6 Document Area

The document area in SDI is contained inside a native window named Editor. The behavior, interaction and appearance of document area in SDI is the same as in MDI.

4.7 Document Area Split Layout

The document area split layout works the same way in SDI as document area split layout in MDI.

4.8 Outside Area - Native Windows

Native windows are containers for IDE windows. Their characteristics are following:

title - title of native window shows the name of currently selected IDE window inside the native window.
icon - icon of native window is the same as icon of main window. It means the application icon.

4.8.1 More Windows in Native Window

Multiple windows in native window are shown the same way as multiple windows in an elementary split cell in MDI. It means they are tabbed.

4.8.2 Maximized Native Window

A window can be maximized. This really means that the native window is maximized. When a maximized window is restored, the native window is restored. It means the IDE window maximize/restore actions are only delegated to native window maximize/restore actions.

4.8.3 Resizing Native Window

If a native window is resized, also the IDE windows (one or multiple tabbed windows) inside the native window are resized. The IDE windows inside the native window fill the whole native window real estate.

4.8.4 Opening and Closing Native Window

A native window is open if one or multiple IDE windows contained in native window are open. The native window is closed automatically if the last IDE window contained inside the native window is closed. The user can close the native window using the native window's close button. This would close the contained IDE windows as well.

4.8.5 Attaching

4.8.6 Interaction

4.8.6.1 Maximization

Maximization of window is performed the same way as maximization of window in MDI.

4.8.6.2 Resizing

The resizing of native window is controlled by native window manager.

4.8.6.3 Attaching

An IDE window can be moved to an existing or new native window. If moved to an existing native window, it is added as another tab between IDE windows inside the native window. This doesn't result in changing the size or position of native window. If moved to a new native window (a new window is created to contain the IDE window) the native window is created at the same size as was the size of previous native window the IDE window was in.

4.8.6.4 Drag & Drop

In addition to drop targets in window area, which work the same way in SDI as in MDI, the user can drag a window and drop it to:

a window inside a native window - the window is added as another tab into the native window.
an outside area - a new native window is created.

4.8.6.4.1 Drop Target - Window

The difference between window, which is contained in native window, and a window which is contained in window area as a drop target is that inside the native window the user can drop only into the center part of window. The center drop area inside a window works the same way in SDI as in MDI.

4.8.6.4.1 Drop Target - Outside Area

In SDI, it is possible to drop a window also to an outside area. The outside area is an area of monitor screen that is not above any NetBeans window (main window, editor, native windows). If a window is dropped in outside area a new native window is created in place, containing the dragged IDE window. The new native window size is the same as the native window the IDE window has been contained in. The position of native window right left corner of new window appears at the mouse cursor position. This is not supported in MDI.

4.9 Window Groups

The window groups in SDI work the same way as window groups in MDI.

4.10 Toolbars

Toolbars in SDI work the same way as toolbars in MDI.

4.11 Work Flow

In SDI, all workflow features from MDI are used and work the same way.

4.12 Window Menu

The window menu in SDI is the same as window menu in MDI.

4.12 Output Window

The output window in SDI behaves the same way as output window in MDI.

5 Switching Between MDI and SDI

The user can change the window system mode using the Setup Wizard. During switching of modes a transformation of windows is performed due to existence of native windows in SDI mode.

A window container is a term used for explaining the switching between MDI and SDI modes. A window container is an abstract container containing a window or tabbed windows without any splits. It can be in two states:

elementary split cell - a split cell of window area containing only windows without any nested split cells.
native window - a native window containing IDE window or multiple tabbed IDE windows.

Important note is that DnD moves between window containers, it never transforms the state of window container. It means if user drags a window from a native window into window area, it removes this window from one window container (native window) into another window container (elementary split cell).

The fact that a window belongs to a specific window container is shared between SDI and MDI. It means if user drags a window from window container A to window container B, it appears in window container B in other window system mode when modes are switched.

A window container can be in different state in SDI and in MDI. Also the default states can be different. So for example an "Explorer" window container, can be in elementary split cell state in MDI by default, and in native window state in SDI by default.

The window container is in implementation represented by "Mode".

5.1 Switching from MDI to SDI

The following transformation is performed when the SDI mode is used by default (this is possible only when using a special switch):

Main window is open at the default SDI position and size.
Editor native window is open at the default position and size.
Only windows that should be open by default are open.
Windows would open in window area or in a native window depending on a default state of their window container.

The following transformation is performed if the MDI mode is the default mode and it is switched to SDI for the first time:

Main window is open at the default SDI position and size.
Editor native window is open at the default position and size.
Windows that were open in MDI are open in SDI.
Window containers that have a separate default state defined for SDI open their windows in this state. It means if the default state is native window its windows would open in native window. If the default state is elementary split cell, its windows would open in window area.
Window containers in native window state are open at the default position.
Window containers in elementary split cell state are open at the same position as they were open in MDI.
A newly introduced window containers in MDI (have to be in elementary split cell state) are open in elementary split cell state in SDI at the same position as they were open in MDI.

The following transformation is performed if switching from MDI mode to SDI each next time:

Main window is open at the last SDI position and size.
Editor native window is open at the last SDI position and size.
Windows that were currently open in MDI are open in SDI.
Window containers that were in native window state the last time in SDI are open at the last size and position.
Window containers in that were in elementary split cell state the last time in SDI are open at the same position as they were open in MDI.
A newly introduced window containers in MDI (have to be in elementary split cell state) are open in elementary split cell state in SDI at the same position as they were open in MDI.

5.2 Switching from SDI to MDI

The following is performed when the MDI mode is used by default:

Main window is open at the default MDI position and size.
Only windows that should be open by default are open.
All windows would open in window area.

The following transformation is performed if the SDI mode is the default mode and it is switched to MDI for the first time:

Main window is open at the default MDI position and size.
Windows that were open in SDI are open in MDI.
All windows would open in window area.
Window containers that were open in SDI in elementary split cell state would open at the same position as they were open in SDI.
A newly introduced window containers in SDI that were in native window state would be transformed into elementary split cell state in MDI and would open attached to the editor from the right.

The following transformation is performed if switching from SDI mode to MDI each next time:

Main window is open at the last MDI position and size.
Windows that were open in SDI are open in MDI.
All windows would open in window area.
Window containers that were open in SDI in elementary split cell state would open at the same position as they were open in SDI.
A newly introduced window containers in SDI that were in native window state would be transformed into elementary split cell state in MDI and would open attached to the editor from the right.

6 Switching Between Projects

The window system layout is stored into a project. It means when projects are switched from project A to project B the actual layout is stored into project A and the layout from project B is loaded. If project B is a new project than the default layout is loaded.

Switching of projects would happen in following steps: