NetBeans UI Style Guidelines

adorableautomaticSoftware and s/w Development

Aug 15, 2012 (5 years and 8 days ago)

490 views

NetBeans UI Style Guidelines
6/29/00 Page 1
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 using the following URL:
http://java.sun.com/products/jlf/dg/
2.Overview
Most windows provided by NetBeans modules are of the types outlined in Table 1 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.
Table 1: Window Types
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.
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
6/29/00 NetBeans UI Style Guidelines Page 2
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 Figure 1 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.
Figure 1: Dialog Box Spacing and Layout
If you include a panel within a dialog box, then it should be spaced as shown in Figure 2 below. Note that the
minimum spacing between a label and a control should be 12 pixels. In Figure 2 below, the 12 pixel space is
between the longest label ("Radio Buttons") and the column of checkbox and radio button controls.
Figure 2: Spacing for Panel Borders and Between Groups of Controls
Figure 3: Spacing among Command Buttons
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.
6/29/00 NetBeans UI Style Guidelines Page 3
Figure 4: Spacing among Toolbar Buttons
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 below:
Table 2: 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
6/29/00 NetBeans UI Style Guidelines Page 4
Figure 5: Tab Sequence in a Dialog Box
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.
6/29/00 NetBeans UI Style Guidelines Page 5
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.
Table 3: 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.
6/29/00 NetBeans UI Style Guidelines Page 6
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.
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).
Figure 6: Chooser Browse Button Graphic.
6/29/00 NetBeans UI Style Guidelines Page 7
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
)
:
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.1Vertical 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.2Horizontal 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)
Table 4: Use of JLF Colors for Text in UI Windows
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