User Interface Specification: Select Document Node in Explorer

Author: Jan Rojcek
$Revision: 1.5 $
Document History: available in CVS

Abstract: This document defines behavior of an action which allows the user to select the node in explorer corresponding to a document open in the document area.

Table of Contents:

1 Introduction

2 References

3 Detailed Spec

3.1 Behavior

3.2 Menu

3.3 Error Message

1 Introduction

Being able to select the node (in explorer) of currently edited file is the feature that has often been asked for. The user needs to select an explorer node of a file open in the editor to access the context of currently edited file. What package the class belongs to? What are the other classes in that package? After selecting a node in explorer the user can invoke contextual actions on this node.

As there can be more explorer windows which provide for access to objects that can be open in the document area, the action should allow the user to select the target explorer. The "Select Document Node in Explorer" feature would allow the user to move the keyboard focus from a document window to the explorer window chosen by user. It would also expand the explorer tree to the node representing the object shown in document window.

The NetBeans IDE provides four explorer windows that can be used for this action - Projects, Files, Favorites, Versioning.

2 References

No references.

3 Detailed Spec

3.1 Behavior

The flow of the action would be:

• The user invokes the action targeting a concrete explorer window from the main menu or shortcut.
• The targeted explorer window is activated and a node corresponding to the current document window is expanded and selected in the targeted explorer.

3.2 Menu

The menu characteristics are following:

• name of the menu is "Select Document in"
• mnemonic is 'n'
• shows in Window menu
• always enabled

Figure 1: Location of menu in the Window menu

...
Switch to Document
Select Document in    (n) >
---------------------------
Close Window
...

3.2.1 Menu Items

The concrete menu items invoking the select in explorer action are shown as a submenu.

Figure 2: Menu Items

...
Switch to Document
Select Document in      (n) > Projects        [Ctrl+Shift-1]
---------------------------   Files           [Ctrl+Shift-2]
Close Window                  Favorites       [Ctrl+Shift-3] 
...                           Versioning      [Ctrl+Shift-8] 

The menu contains a submenu of available explorers. Only applicable explorer windows for currently selected document are enabled. An explorer is applicable for a document if the corresponding document node is in the explorer (and it is possible to find and select it using this action).

3.3 Error Message

If for some reason the document node can not be found after invoking the the action, the closest parent that could be found on a path to the node is selected and a message "The document node couldn't be located." is shown in the status line.