1. Introduction
This document has been created for user interface developers on the NetBeans project. It presents information that is based on the Java Look & Feel Design Guidelines (JLFDG). It is intended to help you follow NetBeans standard look and feel. Additional details of the JLF are provided in the book and are not covered here.

The JLFDG website can be accessed at http://java.sun.com/products/jlf/dg/ . You may also download a PDF version of the NetBeans User Interface Style Guidelines. (out of date)

2. Overview
Most windows provided by NetBeans modules are of the types outlined in Window Types below. For each of your windows, identify what type it is and then follow the guidelines below.

Topic	Top Level Window	Dialog Box Window	Wizard
Purpose	High level functionality (e.g., editing, debugging, exploring).	Enable an action that a user may perform on one or more objects and then dismiss.	Combine a sequence of steps that is used to perform a complex action.
Window Controls	Has a full set (maximize, minimize and close).	Never minimizable, has close and maximize.	Has a full set.
Menus/Toolbars	Does not have a menu bar, may have a toolbar.	Does not have a menu bar or toolbar.	Does not have a menu bar or toolbar.
Command Buttons	Does not have any command buttons.	Has a set of command buttons along the bottom (see section on Dialog Box Buttons).	Has a set of navigation buttons along the bottom.
Access to Help	Through a help button, context sensitive help or F1 key.	A help button as the rightmost command button, should also support F1 key.	May or may not have a help button (depending on the complexity of the steps), may support F1 key.

General Guidelines for Windows :

1. Should be resizable.
2. Should be non-modal, for details see JLFDG pg. 112 .
3. The F1 key should bring up help for the active window.
4. Tool tips should be provided for buttons, especially those with no associated text (for example, buttons on a toolbar).

3. Window Sizes
Windows should be designed so that their default size does not force any truncated text labels. Text fields, list boxes, labels (and the like) should grow or shrink depending on the window size: .

Minimum Height	100 pixels	Smallest size that a window can have.
Minimum Width	100 pixels
Maximum Default Height	723 pixels	Largest size that a window can have when first displayed (default size).
Maximum Default Width	1024 pixels

4. Spacing of Controls
The following images show the desired spacing among controls in JLF windows. In general, the visual spacing among items is a multiple of 6 pixels (JLFDG p. 47-52, 115, 152-156) . When figuring the multiple of 6, note that the white highlighting along the edge of each component is considered part of the background and should not be included in your calculation.

Use the default Swing spacing for radio buttons and checkboxes. Although the JLF specifies a visual spacing of 6 pixels, this distance causes the focus indicator (a box with a one pixel thick line) to be cut off on the top and bottom of the control, therefore the default spacing is preferred for now.

In Dialog Box Spacing and Layout below, general spacing guidelines among groups of controls (one group contains the Find label and entry field and the second group contains the checkboxes and radio buttons) and the border of a dialog is shown. Note that the command buttons at the bottom are spaced 17 pixels below the other control groups, and are right aligned.

If you include a panel within a dialog box, then it should be spaced as shown in Spacing for Panel Borders and Between Groups of Controls below. Note that the minimum spacing between a label and a control should be 12 pixels. In Spacing for Panel Borders and Between Groups of Controls below, the 12 pixel space is between the longest label ("Radio Buttons") and the column of checkbox and radio button controls.

Note
The JLFDG specifies that the buttons in the group should all be the size of the largest button. The largest button should have an interior padding of 12 pixels. By default, Swing provides a 15 pixel padding and this is currently acceptable.

5. Title Bars
The general rule for title bars is to include the following information, where appropriate:

1. contents of the window (e.g., the name of the object currently displayed),
2. type of view that is displayed in the window (typically represents the function of the window, e.g., Editor, Object Browser),
3. type of action that is being performed (typically the name of the action from the menu item,
4. application name.

The following table summarizes the types of windows typically contained in a NetBeans module, along with some examples of their title bars.

Window Type	Rule	Examples
Action dialog box	Show the object that you are acting on (if available) and the name of the command that was used to bring it up.	foo - Find - NetBeans Find - NetBeans  Open File - NetBeans
Customizer dialog box	Show the object and view names.	foo - Customizer - NetBeans
Wizard	Show the wizard name.	Create JSP from Database - NetBeans
Question or Warning box	Show the severity of the message and the object or action to which it applies (if applicable).	Question - NetBeans Warning - Generate Bean - NetBeans
Progress Indicator	Show the verb that provides the action in progress. If the object name is not shown within the window, then it must be in the title bar.	Generate Bean in Progress - NetBeans foo - Generate Bean in Progress - NetBeans

Guidelines:

1. When displaying a file name, show only the base name of the file, not the full path.
2. The application name should be appended to the end of the title in all windows (see JLFDG, online HI note on window titles). In NetBeans, the main window (containing the application's menu bar, toolbar and status bar) has only the application name as its title.
3. Dialog box titles should use the same words as the menu item used to show them.

6. Keyboard Navigation
The user should be able to perform all actions within a window using only the keyboard (JLFDG p. 83, 114) .

6.1 Tab Key
All controls within a dialog box must be reachable using the Tab key.

Guidelines :

1. Upon entering a dialog box, the top-leftmost control should have the focus (unless there is a good reason to default to some other location).
2. Pressing the Tab key moves the focus to the next field, following a left to right, top to bottom sequence, as illustrated in Tab Sequence in a Dialog Box below.
3. Pressing the Shift+Tab key combination moves the focus backwards.

6.2 Mnemonics for Menus and Dialog Boxes
A mnemonic is a character indicated by an underscore in a menu title or dialog box field label and is used to:

• post a menu on the menu bar (Alt+F will open the File menu)
• choose a menu item on a posted menu (N will create a new file when the File menu is open)
• move keyboard focus to the labelled field (in the figure above, Alt+U will move focus to the Ruler Units field).

Mnemonics are not case sensitive.

General Guidelines (JLFDG p. 88) :

1. Use the first character of the item name as the mnemonic. If that is not possible, try the following:
• first character of another word in the item,
• a distinctive consonant of the word,
• last character of a word,
• start from left to right, and go with the first unique character you find.
2. Make mnemonics unique within the entire context of the menu or dialog box. For example, dialog box controls should not use the same mnemonics as the titles of any active menus.
3. Mnemonic characters must be visible since they are shown to the user with an underscore. If for some reason you cannot use a character in the item name, add the character you are using in parentheses at the end of the name.

Menus:
A menu is posted by pressing Alt and the menu title mnemonic. A particular menu item is chosen by pressing the menu item's mnemonic. Menu items located on submenus are chosen in a similar manner--pressing the mnemonic for the submenu posts the submenu, pressing the menu item's mnemonic within the submenu will choose the item.

1. Every menu title and menu item must have a mnemonic.
2. For consistency, menu mnemonics should be used consistently across the NetBeans project.
3. JLFDG defines some standard menu item mnemonics (see p 90 for the complete list).

Note
The Tools menu and popup menus may not adhere to these guidelines since they are generated on the fly. Currently, Swing only allows the user to access the first item with a given mnemonic if there are multiple items using the same mnemonic. For menus, the user may use the arrow keys for keyboard access to subsequent items with the same mnemonic.

Dialog Boxes:

1. All controls in dialog boxes should have mnemonics.
2. Controls that do not have a label of their own (text fields, list boxes) should have a JLabel associated with them, and this label should have a mnemonic.
3. The default command button is invoked by the Return or Enter key, and the Cancel button is invoked with the Esc key. So neither of these buttons requires an explicit mnemonic.

6.3 Keyboard Shortcuts
Menu items that provide actions that many users will want to access quickly via the keyboard should have shortcuts (JLFDG p. 87, 88) . Unlike mnemonics, keyboard shortcuts are unique within an application. Not all commmands, therefore, will require a shortcut.

1. The modifier keys for shortcuts are Ctrl and Shift. The Alt key is reserved for mnemonics.
2. The same function should have the same keyboard shortcuts across the entire NetBeans applications. See the JLFDG, page 88 for a list of standard keyboard shortcuts.
3. Each menu on the main menu bar has an area set aside for additional module related menu items. These menu items should not have keyboard shortcuts by default. The user can specify a shortcut using the "Keyboard Shortcuts" menu item.

7. Dialog Box Buttons

General Guidelines

1. Different types of dialog boxes have standard names that are used for the command buttons along the bottom. These buttons are summarized below (also see JLFDG p. 115-118) .
2. The expected action should be a default button unless that operation may result in data loss (such as Delete or Remove), in which case the dialog box should not have a default button.
3. "OK" is always spelled with both letters capitalized.
4. "OK" means to apply then close.
5. "Cancel" means to reset (to the original contents of the dialog when it was displayed) then close.
6. "[ ]" means optional.
7. Use "Browse..." as the Button text when a list of choices is available (for example: JfileChooser). Use ellipse ("...") as the Button text when clicking the button leads to a property box or if space is cramped (e.g., you're working in a property sheet or table with inline editors).
8. Optional dialog boxes should use the text "Do Not Show This Dialog Box Next Time" (rather than the positive "Show Dialog Box X ......")

    

Dialog Box Buttons

Dialog Box Type	Buttons	Description
Customizer	[Close] [Help]	A Customizer can be provided in addition to the property inspector view (the "Properties" window) for displaying or editing properties in a manner specific to a particular bean or node. It should not be a wizard.
Information and Error	Close [Help]	The Close button dismisses the window and returns focus to the previously active window.
Question and Warning	<affirmative> <negative> [Cancel] [Help]	The affirmative answer should use a verb that indicates what will happen when the button is pressed (e.g., Save, then Continue). Same for the negative answer (e.g.., Continue without Saving). Do not use Yes or No, as they almost always have some ambiguity in their meaning. Cancel is used if both the affirmative and negative actions do something, and it is possible to provide a way for the user to back out entirely.
Progress	Close [Stop]	Close will close the progress dialog box, but will continue the process. Stop will terminate the process. If the user will not be returned to their initial state after clicking the Stop button (some objects have been processed and the action cannot be undone), then the progress dialog box should note this.
Action	Combine Action with Close: OK Cancel [Help]	Used once and then dismissed. Whenever possible, use more specific verbs than OK and Cancel, such as Save.
	Apply Action: Apply Close [Help]	Allows the user to go back and forth between the dialog box and the main window. Whenever possible, use more specific verb than Apply, such as Save or Print.

8. Text Fields

8.1 Default Entries
There are two types of default entries:

1. the actual text that will be passed to the application
2. a placeholder when the actual text cannot be precomputed. Placeholders should be enclosed in <>s.
3. For example, if a text field labeled Value will use a default value, it's contents should be preset with either the actual value (if known), or <default>.

There should be a default value for each text field on a dialog box. In particular, if the user does not have to type into this text field, the dialog should show the value that will be used.

Note
If a field contains a placeholder, the code that determines if the default value should be passed to the application must assume that the entire placeholder string (including the "<>"s) can be changed for localization.

8.2 Behavior
If it is likely that the user will replace the text in a field, then the entire contents of this field should be automatically selected when the field receives focus as a result of the window being displayed or by using the keyboard. This will enable the user's text to simply replace the current contents of the field. If the user clicks directly on a field, no automatic selection occurs and the insertion point is placed within the text at the point where the user clicked.

Text fields that contain the following information should automatically select the contents:

• variable names
• target names
• numbers

Text fields that contain the following information should come up with the default contents unselected and the insertion point at the end:

• path names
• package names

If the visible text in a field appears truncated, then the field properties must be set so that the correct end of the text shows when the full text cannot be seen. Make sure that the rightmost end of the text is shown for directory, package or file names and the leftmost end is shown for other kinds of information.

8.3 Path/Package Names
Text fields that are used to show/enter pathnames, directories or package names should be at least 30 characters long (set the "Columns" property on the text field to a value of at least 30).

8.4 Choosers
NetBeans has a grouping that consists of a text field on the left and a button on the right that has an ellipsis ("...") graphic. This grouping gives the user the choice of typing a value into the text field or selecting from an appropriate chooser. The "..." button brings up a chooser dialog box for the field. Some examples of chooser dialog boxes include: file chooser, color chooser, font chooser and target chooser. The button has a specific graphic and it should be used for all chooser buttons. This graphic is in objectbrowser/resources/details.gif in the NetBeans source tree.

Any partial value entered into the text field should be used, if possible, as an initial value in the chooser dialog box (it could be used to position the chooser at a particular value in a list, or as an initial directory).

 Use "Browse..." as the Button text when a list of choices is available (for example: JfileChooser). Use ellipse ("...") as the Button text when clicking the button leads to a property box or if space is cramped (e.g., you're working in a property sheet or table with inline editors).

9. Text Styles
In general, the default font sizes, styles and colors used by Swing controls are correct. Use the following table as a guideline when choosing text color (JLFDG, p. 39-43):

Description	JLF Color	Swatch	RGB Value
User entered text and control text (including menu titles, menu items, shortcut text in a highlighted menu item, text in non-editable fields, text in tabs, title of a internal frame, button text)	Black		0-0-0
Background for user entered text areas	White		255-255-255
Label (and other system) text	Primary 1		102-102-153
Shortcut description in menu items, background highlighting for a selected menu item	Primary 2		153-153-204
Selected text background	Primary 3		204-204-255
<not used for text>	Secondary 1		102-102-102
Dim or grayed out text (like inactive menu items or labels)	Secondary 2		153-153-153
Canvas color, Background for uneditable text (including table cells)	Secondary 3		204-204-204

Text can appear using one of two forms of capitalization rules (see JLFDG pg. 46, 47):

1. Headline capitalization for text that appears in checkbox text, combo box labels, command button text, icon names, group labels, menu items, menu titles.
2. Sentence capitalization for text that forms a complete sentence. Some examples are dialog box text, error or help messages, labels that indicate changes in status (progress indicator information). Avoid using long phrases that are not sentences.

10. Scrollbars

10.1 Vertical scrollbar
Should be available for controls like listboxes, tree views, tables, etc. They should appear when necessary, that is, when the control contains more information than can be displayed.

10.2 Horizontal scrollbar
Should typically be used in two-dimensional contexts, such as drawing areas. In those cases they should always be visible.

In general, text should be formatted that the entire width of the text is visible (or it should wrap, if appropriate) in order to avoid horizontal scrollbars. In cases where this is not possible, then it is appropriate to display horizontal scrollbars as needed. If it is common that the contents being shown will need the scroll bars, then they should always be visible. If the need for scrollbars is rare, then they can be displayed when necessary.

11. Feedback
Whenever an action produces error messages or informational messages, these messages should go into the status area provided by the main window or into the output window (or both).

It is typically not sufficient to get only a message in the status area or output window as feedback for an action. Some other feedback (either auditory or visual) should be provided to indicate that an action has completed.

Examples of appropriate user feedback include:

1. Opening a window
2. Adding a node to the explorer window, selecting it and scrolling to it so that it is visible
3. Displaying an informational dialog box
4. Making a sound (beep)
5. Temoporarily change the mouse cursor

11.1 Cursor Change
When an action or UI update is slow to manifest itself a mouse cursor change is recommended to indicate that the IDE has recognized and is working on the action. To help determine when the cursor should be changed follow these three general rules (from useit.org):

1. 0.1 second is about the limit for having the user feel that the system is reacting instantaneously, meaning that no special feedback is necessary except to display the result.
   
2. 1.0 second is about the limit for the user's flow of thought to stay uninterrupted, even though the user will notice the delay. Normally, no special feedback is necessary during delays of more than 0.1 but less than 1.0 second, but the user does lose the feeling of operating directly on the data.
   
3. 10 seconds is about the limit for keeping the user's attention focused on the dialogue. For longer delays, users will want to perform other tasks while waiting for the computer to finish, so they should be given feedback indicating when the computer expects to be done. Feedback during the delay is especially important if the response time is likely to be highly variable, since users will then not know what to expect.

public static final Cursor createProgressCursor(Component component)

  /**
  * Returns a cursor with an arrow and an hourglass (or stop watch)badge,
  * to be used when a component is busy but UI stil responses to theuser.
  *
  * Similar to the predefined WAIT_CURSOR, but has an arrow to signalize
  * still responsive UI.
  *
  * Typical usage to set the ProgressCursor, then reset back to thedefault cursor:
  * try {
  *theCurrentFrame.setCursor(Utilities.createProgressCursor(theCurrentFrame));
  * // perform some work in other then event dispatch thread(=don't block UI)
  * } finally {
  * theCurrentFrame.setCursor(null);
  * }
  *
  * @param component The Component that will use the ProgressCursor.
  * Throws IllegalAccessException if component is null.
  * @return One of three types of ProgressCursors (Unix, Windows orMac).
  * For all Unixes the same Progress Cursor is returned,
  * regardless of window manager. *
  * @since 3.23
  */