nbui_styleguide

7/31/2019 nbui_styleguide

1/7

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 theJava 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, notethat 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 havewhen first displayed (default size).Maximum Default Width 1024 pixels
http://java.sun.com/products/jlf/dg/index.htmhttp://java.sun.com/products/jlf/dg/higl.htm#41511http://java.sun.com/products/jlf/dg/higl.htm#41511http://java.sun.com/products/jlf/dg/higg.htm#55417http://java.sun.com/products/jlf/dg/higg.htm#55417http://java.sun.com/products/jlf/dg/higl.htm#41511http://java.sun.com/products/jlf/dg/index.htm


2/7

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


3/7


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 applications 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
http://java.sun.com/products/jlf/updates/windowtitle.htmlhttp://java.sun.com/products/jlf/updates/windowtitle.htmlhttp://java.sun.com/products/jlf/dg/higi.htm#37077http://java.sun.com/products/jlf/dg/higi.htm#37077http://java.sun.com/products/jlf/updates/windowtitle.htmlhttp://java.sun.com/products/jlf/updates/windowtitle.html


4/7


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 items mnemonic. Menu items located on submenus are chosen in a similar manner--pressing the mnemonic

for the submenu posts the submenu, pressing the menu items mnemonic within the submenu will choose the item.

1. Every menu title and menu item musthave 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.
http://java.sun.com/products/jlf/dg/higi.htm#35796http://java.sun.com/products/jlf/dg/higi.htm#35796http://java.sun.com/products/jlf/dg/higi.htm#35796http://java.sun.com/products/jlf/dg/higi.htm#35796


5/7


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

[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 notuse 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 userwill 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.
http://java.sun.com/products/jlf/dg/higi.htm#35746http://java.sun.com/products/jlf/dg/higi.htm#35746http://java.sun.com/products/jlf/dg/higl.htm#50834http://java.sun.com/products/jlf/dg/higi.htm#35746http://java.sun.com/products/jlf/dg/higl.htm#50834http://java.sun.com/products/jlf/dg/higi.htm#35746


6/7


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, its contents should be preset with either

the actual value (if known), or .

There should be a default value for each text field on a dialog box. In particular, if the user does not have to typeinto 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 users 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 unselectedand 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.


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

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
http://java.sun.com/products/jlf/dg/higg.htmhttp://java.sun.com/products/jlf/dg/higg.htm#63760http://java.sun.com/products/jlf/dg/higg.htm#63760http://java.sun.com/products/jlf/dg/higg.htm

Documents

nbui_styleguide