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.

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: .

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.

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.

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 ......")

    

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.

For the NetBeans IDE, any delay longer than 1 second should be accompanied by a mouse cursor change. The NetBeans convention of displaying 'Please Wait...' text in the explorer needs to be augmented with a wait cursor -anytime 'Please Wait...' is displayed the wait cursor needs to be used. Additional places where a cursor change are desirable include:

• Invoking context menus
• Main Menu Navigation
• Expanding nodes in the Explorer
• Opening and closing files
• Navigation in the Component Inspector (Form Editor)
• Window focus change
• Opening new dialogs or wizards
• Debugger actions (start, step, finish)

Since most every action in the IDE is not modal the cursor should indicate that the action is being carried out and that the user may continue to interact with the IDE. Please use the following mouse cursor for the above cases:

	progress cursor for Machintosh
	progress cursor for Motif
	progress cursor for Windows

Each module must test and recognize the trouble places and add the cursor change directly in the module code, please use the following method in org.openide.util.Utilities:

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
  */ 

12. Alerts
Java provides four types of alerts: Error, Warning, Question, and Informational. An alert is used to communicate something unexpected, or at least not immediately requested by the user.

12.1 Error Alert
An error alert is used to tell the user about an error, whether the error is caused by the system or by the user. The distinction between an error alert and a warning alert is that when the system cannot continue, or cannot follow the user's instruction.

An error alert may be used:

• When the user enters a value that is not allowed (such as a class name containing a space).
• When the system encounters a fault (such as an exception).

12.2 Warning Alert
A warning alert is used to tell the user that there is some risk, but that the system can continue. The user is given the choice of continuing despite the risk, or to cancel the operation. This type of alert warns users about the possible consequences of an action and asks the users for a response

A warning alert may be used:

• When the change the user is making cannot be undone.
• When the user enters information that might cause problems later.
• When the user closes a file, a warning alert can tell the user that a file is not saved, and offer the action of saving before closing, closing without saving, or cancelling the close action.

12.3 Question Alert
A question alert is used when nothing is wrong (unlike a warning or error alert) but some information is required from the user. Since this is an alert, it should only be used when it is unexpected, or not immediately requested by the user. For instance, if the user issues a "logon" command, it would be incorrect to use a question alert to request the user's password. Instead, an action dialog box should be used.

A question alert may be used:

• If the user must logon in order to complete a user-requested action. For instance, the user may issue a "commit" command, and a question alert may be used to request the password from the user.
• To get permission from the user to automate some process. In the debugger, the user issues a "Fix" command, which causes the modified code to be sent to the VM. As it happens, the call stack has a reference to the old class, so the IDE asks the user "should I automatically pop the old call for you?" This isn't an indication that something is wrong, isn't a necessary byproduct of the user's action (they can do a fix when the class isn't being used at all), and is a question.

12.4 Information Alert
An information alert is used to communicate general information. The difference between information and question alert is that the primary purpose of an information alert is to communicate to the user, while the primary purpose of the question alert is to get information from the user. An information alert is only used when nothing is wrong. If there is something wrong, use an error alert.

An information alert may be used:

• To tell the user that a scheduled meeting is about to occur. It could include a "snooze" feature, allowing the user to ask to be re-reminded after a certain time. Allowing the user to enter information does mean it must be a question alert. It should be an information alert as long as the main purpose is to give information, and a response is not required.
• To tell the user that a server has shut down.
• To tell the user that the IDE has not been updated in 6 months.