HOME > Community > Projects > ui

Code Navigator

Author: Gabriel Tichy, Dusan Pavlica, Jindrich Dinga
Version: Final draft
Last Update: 1/14/2005

1.Introduction

Code Navigator is a feature, which allows users easy to orientate in java source code as well as to perform some basic actions. This document describes redesign of current Code Navigator, its appearance and behavior.

2.Requirements

What Code Navigator is for in promo E

Shows the structure of java source code which is currently selected.
Allows users easier navigation and orientation inside java source code. Users can quickly jump to desired methods and fields of java source code as well as perform basic actions connected with source elements.
Code Navigator's functionality should also replace functionality of combo box in editor toolbar.

3.Design specification

General Info

Code Navigator is situated on the right side of the Editor, and this position stays. If the users want to change its position, they can do it (e.g. by using D'n'D function).

Shortcuts, which are used in Code Navigator, are:

Ctrl+7 - Open Navigator window
Enter - Open the selected item
Escape - Go back to whatever component has focus before you entered the Navigator window

Code Navigator is linked with Editor window as well as with Project window. Linking with Editor means, that putting a cursor on a line in a java source code invokes an action in Navigator window, when appropriate member, which is placed in the selected line in Editor window, is highlighted in Navigator window. On the other side, in Navigator window, if a member from the list is selected, cursor immediately jumps to the source code on the appropriate line, which is not highlighted by Caret Row in the Editor window(this behavior will be changed, see Use cases section). If a field is used in a method/methods it is displayed in orangish box - this behavior stays same (it is working for selecting a field in Editor/Navigator window/Project view). Linking with Project window means, that selecting a java class in the tree invokes an action in Navigator window, when members, which are used in the java source code, are displayed.

figure 1 - Appearance of old version of Code Navigator

Code Navigator has some basic actions, which can be invoked via the context menu. Another action, which can be performed, is Quick search. This action is useful if the user wants to find quickly some certain member in a list: just press Ctrl+7, type partial name and press Enter. In next promo, the function should be changed, see Quick search section in Open issues.

Note: In menu Window in NetBeans IDE, the Code Navigator should not be placed on the first position. It should be placed close to Properties.

In the old version of Code Navigator, there are many UI issues such as:

Icons in Code Navigator are different from icons, which are used in Project window. These icons are not aligned.

Unify these icons. The new icons, which should be used, will be provided.
These icons should be aligned.

Selected member is highlighted in gray color (instead of blue one) and letters are gray(instead of white color).

For highlighting of a member use same color (blue one for focused and orange one for unfocused member), which is used in NetBeans IDE.
The color of text will stay same(names are in black, parameters in gray color), highlighted text will be written in white color.

Parameters in methods are shorten in strange way.

Do not cut the parameters. If the row is longer then the width of Navigator window, then tool tip will be shown as well as a scrollbar appears.

Note: Abbreviation will be possible to switch on in Properties.

In case, the width of Navigator window is small and as a result of that some filters disappear, there should be some small toggle button (e.g.arrow) which will state, that icons are missing and after pressing it some menu is invoked. This menu will contain the names of missing buttons and user can check/uncheck them.

figure 2 - Appearance of new version of Code Navigator

Old version of Code navigator window contains two combo boxes: the first one is for Views and the second one is for Filters (figure 1).

Combo box in the toolbar of Editor window will be omitted (it is be replaced by Code Navigator).
If the width of the Navigator window is shorter than a description of members, then a scrollbar will appear.

The View combo box will be replaced with two dependant toggle buttons and the Filter combo box will be replaced by independent toggle buttons. These toggle buttons will be situated in the toolbar of Code Navigator.

Toggle buttons(dependent), represent View, should be:

Members - this button should display members.
Inheritance - this button should display inheritance tree.

Note: In the future it might be replaced by Combo box.

Toggle buttons(independent), represent Filter (same for Members and Inheritance view), should be:

1. Show Inherited members (non-pressed state by default)

Allows to display members used in java source code as well as inherited members (see figure 3). If the Members view is sorted by name, then inherited members will be sorted by name as well. In case Members view is sorted by code order, inherited members are sorted in that way as well. For recognizing which member is local and which is inherited, the icon of inherited member should be lighter (Alpha channel 75).

figure 3 - Hide Inherited members

Tool tip above the inherited members should state that members are inherited from which classes etc. This tool tip should be there every time, even the Navigator window is big enough.
Icon, for toggle button, will be provided.

2. Show fields (pressed state by default)

This function should hide/display fields in the Navigator window.
Icon, for toggle button, will be provided.

3. Show static fields and methods (pressed state by default)

This function should hide/display static fields and methods in the Navigator window.
Icon, for toggle button, will be provided.

4. Show non-public members (pressed state by default)

This function should hide/display non-public members.
Icon, for toggle button, will be provided.

Note: In the future, filters might be replaced by Combo box with predefined filters (at first it is necessary to do some investigation , what kind of filters developers use, etc.), probably placed on the same place like in the old version of Code Navigator (on the bottom).
Toggle buttons have mouse over effect.

The new Code Navigator should also be linked with Project view. Linking with Project window means, that selecting a java class in the tree invokes an action in Navigator window, when members, which are used in the java source code, are displayed.

The new Code Navigator icon should replaced the old one.

Use cases

Five use cases can happen, when user invokes Navigator window from different modes :

Mode of Code Navigator		Action	Solution
docked state		mouse	By clicking on a member, the Caret Row is moved to the appropriate line, which contains the chosen member. The Caret Row is displayed on the 5th line from the top of the Editor window. On double click, the cursor jumps at the end of the member on the appropriate line in the Editor window and user can edit the java code source.
docked state		keyboard	By pressing Ctrl+Shift+5, the Navigator window gets focus and by pressing up or down arrow, user can easily choose a member. If the member is chosen, the Caret Row is moved to the appropriate line, which contains the chosen member. The Caret Row is displayed on the 5th line from the top of the Editor window. There should be some delay between moving and showing the Caret Row in the Editor window. By pressing Enter, the cursor jumps at the end of the appropriate line in the Editor window and user can edit the java code source.
sliding mode	mouse press effect	mouse	By clicking on the Navigator window in sliding mode, Navigator is invoked. Then the same situation happens: By clicking on a member, the Caret Row is moved to the appropriate line, which contains the chosen member. The Caret Row is displayed on the 5th line from the top of the Editor window. On double click, the cursor jumps at the end of the member on the appropriate line in the Editor window and user can edit the java code source. Navigator window goes back to the edge bar.
	mouse roll over effect	mouse	By moving mouse over the Navigator window, Navigator is invoked. This mode is used only for quick look inside the Navigator window. No action can be invoked unless, it is not clicked inside the Navigator (than same solution appears: By clicking on a member, the Caret Row is moved to the appropriate line, which contains the chosen member. The Caret Row is displayed on the 5th line from the top of the Editor window. On double click, the cursor jumps at the end of the member on the appropriate line in the Editor window and user can edit the java code source. Navigator window goes back to the edge bar.). Moving mouse off the Navigator window, Navigator window goes back to the edge bar.
		keyboard	By pressing Ctrl+Shift+5, the Navigator window gets focus and by pressing up or down arrow, user can easily choose a member. If the member is chosen, the Caret Row is moved to the appropriate line, which contains the chosen member. The Caret Row is displayed on the 5th line from the top of the Editor window. There should be some delay between moving and showing the Caret Row in the Editor window. By pressing Enter, the cursor jumps at the end of the appropriate line in the Editor window and user can edit the java code source. Navigator window goes back to the edge bar.

Notice: Highlighting of the Caret Row can be set up in Tools/Options/Editor settings/Java Editor and check "Highlight Caret Row". We recommend set Highlight Caret Row on by default(#DFDFFF).

Members View

    Tool tip for Members toggle button should display: "Switch to Members view".

    In the old version of Code Navigator, members can be sort by name or by code order. These ordering can be set on only in the context menu. Sort by Code Order means, that user sees members sorted in the same way like they are written in java source code (to know more about this possibility, go to the section Sort by Order/Name). Sort by Name means, that members are alphabetical ordered, first are methods, constructors, fields, bean patterns and inner classes. In the future this switching might be represented by combo box.
    Distinguishing between inner classes is done only by coloring the name of inner classes and only up to one level (Xxx.displayXXXInfo). If a field is selected and used in certain methods, then these methods are highlighted in orange color in Code Navigator. In the new version of Code Navigator, if there are more, then one level of inner classes, then every inner class is displayed in gray field. Highlighting methods, which fields are used in, in orange color will be changed to color #FFEFC8.


figure 4a - Appearance of inner classes (old version)	figure 4b - Appearance of inner classes (new version)

In the new version of Code Navigator in Members view, in "ordering by Name" members will be sorted in this way: alphabetical order of Methods, Fields, Constructors and Bean Patterns, then inner classes. The name of inner class is highlighted in gray color(same like in Property sheet) and then the members are sorted in the same way like in class. If a user put an inner class(2) inside another inner class(1), then all members(in 2) will be sorted alphabetically with members(in 1) and user can distinguish between them by Tool tip (Inner Class has #770000 color).

Inheritance View

Tool tip for Inheritance toggle button should display: "Switch to Inheritance view".

In the old version of Code Navigator, Inheritance is displayed only up to one level in the tree and user can see which members are inherited from which classes. The new version of Code Navigator stays same, however it will be possible to see inheritance in more levels(figure 5). In the future, there will be another view, which will display the same problem but in reverse. Switching between these two views can be done in combo box. In the Code Navigator, there should be a possibility to show members/inherited members in the Navigator window as well.

figure 5 - Inheritance view in new version of Code Navigator

There are no filters for Inheritance view.

Context menu

Context menu should be invoked by right mouse click or by Shift+F10 shortcut and is available in every view.

Note: Invoking of context menu should not work only on selected nodes, it should work also inside area of Navigator window. Then some actions(go to source, create Javadoc) will be disabled.

Members view

In the old version of Code Navigator, there is a context menu, which is available only in the members view and can be invoked only by shortcut. This context menu offers these items (see figure 6).

figure 6- context menu in old version of Code Navigator

Go to source - switches from Navigator window to java source code
Create Javadoc - creates Javadoc, if is it possible
Override - overrides methods
Sort by Source/Name - sorts by source in java source code or by alphabetical order (in the new version of Code Navigator it is also represented by radio buttons menu item - figure 8)

Alphabetical order (sort by Name) sorts members in alphabetical order, first are methods, constructors, fields, bean patterns and inner classes (see figure 7a). This order will be set on by default.
In the Code order user see members sorted in the same way like they are written in java source code(see figure 7b). There is possible to move a member to different place by D'n'D function. Then the member in java source code is moved to the new position as well. In the old version of Code Navigator, the D'n'D function is used only in Code order view and it will stay same. The difference is, that in the old version dragged member has white color and user can not see it. The D'n'D function should have same behavior as D'n'D function in Project View.


figure 7a - Alphabetical order	figure 7b - Code order

The context menu of old version of Navigator stays and some items will be added(figure 8):

Filter - allows user to enable/disable some filters

figure 8 - context menu in Members view in the new version of Code Navigator

In Code Order View and Alphabetical Order View, the context menu will have actions mentioned above as well as contain same actions which Project view has:


figure 9a - Context menu	figure 9b - Context menu Refactor	figure 9c - Context menu Tools

Apart from these actions, the context menu should also offer Copy, Cut, Paste and Delete functions

Copy (Ctrl+C) - copies a selected member to the Navigator window as well as to the Editor window. The copied member has same name and number (copied_member_1)

Cut (Ctrl+X) - cuts a selected member and puts it to the clipboard.

Paste (Ctrl+V) - pastes a selected member to the Navigator window as well as to the Editor window.

Delete (Delete) - deletes a selected member.

Inheritance view

In this view, the context menu will be also available by Shortcut (Shift+F10) or by right mouse click. (figure 10):

figure 10 - context menu in Inheritance view in the new version of Code Navigator

In the next promo, the users will be able to do action Find usages, etc.

Tool tips

The problem in the old version of Code Navigator is, that tool tip is placed far away from selected member and the text inside of tool tip is colored. In the tool tip in the new version of Code Navigator, the name of the member and its parameters will be written in the same color like they are written in Javadoc. The tool tip will be displayed every time, when user moves a mouse over a member, and if the width of the Navigator window is shorter then the description of members, a scrollbar will also appear.

Tool tip will be placed in Editor window next to the selected member. If the Navigator window is docked on the left side of the Editor window, then see figure 11b. If the Navigator is docked on the right side of the Editor window, then see figure 11a.

figure 11a - Navigator docked on the right side

figure 11b - Navigator docked on the left side

If the member has a javadoc, then tool tip will be placed in Editor window next to that member. Colors and types of letters used in Javadoc must be unified with colors and types of letters used in Code Completion. For Navigator window, placed on the left side, see figure 12a. Otherwise see figure 12b. If the javadoc is longer than tool tip window then tool tip will contain a scrollbar.

figure 12a - Navigator docked on the left side - Tool tip with JavaDoc

figure 12b - Navigator docked on the right side - Tool tip with JavaDoc

Tool tip should be written in black color. Only the name of the member and its parameters will be written with Bold type.

Tool tips has every member in the inner class as well as inherited members.


figure 13a - simple tool tip	figure 13b - Inner Class tool tip	figure 13c - Two Inner Classes

Another problem with tool tip in previous version of Code Navigator is, that tool tip disappears after a while.

This tool tip should stay there, till user moves a mouse off the member (maxint delay). This feature is important in case a member has javadoc.
When a user clicks on a member which has displayed tool tip, this tool tip should disappear and the member should be selected.

D'n'D

Drag&Drop function must be used only in Members view in Code order view. In the same way, it is used in old version of Code Navigator. However, this function must have same behavior as D'n'D function in Project view. After selecting a member (highlighted in blue field, letters are white), which will be dragged, the cursor must show the position, where the dragged member is placed (figure 14). Then the members in Navigator window will be rearranged as well as in java source code.

figure 14 - D'n'D function

No java class selected, Empty class, No views available

If a user selects a document, which is unsupported in this promo (e.g. XML, HTML, properties, EJB, etc.), there should be a message which states that <No java class selected> (figure 15a). Similar message should appear, if the class is empty (for Members view) (figure 15b). If a user is focused on a differenet node, than Data object node is, the message should state <No views available>. The text is placed in the middle of the width of Navigator window.


figure 15a - No java class selected	figure 15b - Empty class	figure 15c - No views available

Some important pieces from document

General
Must have	1. Code Navigator shortcut must be changed to Ctrl+7. 2. The cursor must not jump to the java source code on the single click, just on double click. 3. Code Navigator must have the Quick search function as the old version of Code Navigator. 4. Icons in Navigator window must be aligned and unified with icons in Project view. 5. Selected member, in Navigator window, must be highlighted in the blue field and highlighted text must be written in the white color.(same case like in Project view). 6. In Navigator window, if the length of a member is longer than the width of Navigator window, the member must not be cut, and the scroll bar must be added. 7. The Navigator must have two toggle buttons instead of View combo box. 8. The Navigator window must not have Filter combo box. 9. In the Editor, combo box must be omitted. It is replaced by Code Navigator window. 10. The Navigator must have four toggle buttons(filters) as specified. 11. The Code Navigator must be linked with Editor as the old version of Code Navigator (selecting a member in the java source code invokes an action in Navigator window and same is valid for selecting a member in Navigator window). 12. The code Navigator must be linked with Project view as the old version of Code Navigator (selecting a class in Project view invokes an action, when the members from that class are displayed in the Navigator window).
Should have	1. The line, which contain chosen member, should be highlighted by Caret Row.
Nice to have	1. It would be nice, if on single click on a member in Navigator window, java source code will scroll on the appropriate line. 2. It would be nice, in case the length of the toolbar is longer than the width of Navigator window and some filters disappear, to have some small toggle button (e.g. arrow) which will state, that these filters are missing and after pressing it a menu will be invoked. This menu should contain the names of missing buttons and user can check/uncheck them. 3. It would be nice, if in members view, there is possible to move members with D'n'D function (same case like in Project view). 4. It would be nice if methods, which a field is used in, stay colorish (the color is #FFEFC8 and for the appearance see pictures above).
Members View
Must have	1. Members must be sortable in Alphabetical order and in Code order. Alphabetical order is set on by default. 2. Every sub-class must be displayed in gray field.
Inheritance View
Should have	1. Inheritance view must display classes and their members which were inherited from.
Nice to have	1. It would be nice, if the Inheritance view offers "Find usages" action (from which classes the local class inherits).
Context menu
Must have	1. Context menu must be invokable with right mouse click and with Shift+F10 shortcut. 2. Context menu must be available in both views (Members and Inheritance). 3. Context menu must have item : "Switch to Members/Inheritance view". 4. Context menu must contain radio button menu items "Sort by Source " and "Sort by Name".
Should have	1. Context menu should have items "Filter", in which be possible to check/uncheck the appropriate filter. 2. Context menu should have Copy (Ctrl+C), Cut (Ctrl+X), Paste (Ctrl+V), Delete(Delete) actions. These actions will be compulsory when the Code Navigator will replace the Project view.
Nice to have	1. In Code Order View and Alphabetical Order View, there would be nice if the context menu contains Refactoring actions.
Tool tips
Must have	1. Tool tip must stay on the screen, untill the user moves the mouse off the selected member (maxint delay). 2. Tool tip must be displayed next to selected member (see pictures in tool tip section). 3. Tool tip must appear every time on every member. 4. Tool tip must be written in black color, parameters in gray color Colors and types of letters in Javadoc must be unified with Colors and types of letters used in Code Completion. 5. Tool tip must be displayed on the toggle buttons (Members and Inheritance).
D'n'D
Nice to have	1. It would be nice, if D'n'D is available in Members view in Code order only.
Unsupported docs or empty classes
Must have	1. Unsupported documents and classes without local/inherited members must display the appropriate message in Navigator window.

Note: Code Navigator should be initially opened only when at least one project exists and contains at least one class, otherwise should be closed by default.

4. Open issues

Quick search

In the current version of Code Navigator, if a user writes a first letter of a member "g", then Quick search will find a member, which starts with "g" letter. All other members stay in the Navigator window. The function of Quick search will stay same, however it would display only members theirs name starts with "g" letter. If the user add another letter "e" (now "ge"), the list of members will be reduced to members starting with "ge" letters. Same iteration will appear, after adding another letter. If there is no such a member, there should be displayed a message, which will state that.

5. Accepted differences between UI spec and implementation for promo E

Toggle buttons vs Combo box

In upper toolbar, toggle buttons are replaced by Combo box, which contains "Members view" and "Inheritance view" items. The Combo box does not contain any icon.

Filters

Filters, which are represented by toggle buttons are situated on the bottom of Navigator window. The title "Filters:" will be positioned on the left.

Note: Toolbar and bottom bar (Filters) contain slide activator - after pressing, these bars will be hidden. This action can also be invoked by shortcut Ctrl-T.

figure 16 - Appearance of filters

Combo box in the toolbar of Source Editor vs Code Navigator

Nowadays, we are not sure, if there is Code Navigator in promo E. Because of this, there are two options.

Code Navigator is implemented in promo E - Combo box in Source Editor toolbar is omitted
Code Navigator is not implemented in promo E - Combo box in Source Editor toolbar stays