Chapter 3. Windows

Table of Contents

Parts of Windows and System Interaction
Borders and Window Commands
Primary Windows
Window Commands
Relation between Documents and Windows
Utility Windows
Instant apply and explicit apply
Default Buttons
Property Windows
Preferences Windows
Alert Text
Alert Buttons
Spacing and Positioning Inside Alerts
Information Alerts
Error Alerts
Confirmation Alerts
Authentication Alerts
Dialog Boxes
Additional Buttons
Common Dialogs
Introductory Page
Content Pages
Last Page

Parts of Windows and System Interaction


Figure 3.1. Example of a window title

Screenshot showing a window title bar with title "blah.abw Properties"

Give every window a title (with the exception of alerts and toolboxes). A good window title contains information that is relevant to the user, and distinguishes a particular window from other open windows. Omit information that does not assist in this selection, for example the application's version number or vendor name.

See the description of each particular window type for title formats.

Borders and Window Commands

Most windows have borders, except certain shaped windows and some torn-off windows. Do not attempt to draw your own window borders, but instead provide hints to the window manager for the desired border type.

Different window commands are appropriate to different types of window. See the description of each particular window type for a list of appropriate window commands. These are the possible window commands:

  • Close. Closes the window. Always draw this as a button on the window border when available.

  • Maximize. Causes the window to use all unused screen space.

  • Minimize. Causes the window to be temporarily hidden. It will continue to appear on the desktop window list.

  • Roll-up/Unroll. Shows only the title bar of the window, as if it has been "rolled up".


A non-modal window does not restrict the user's interaction with other open windows on the desktop in any way. Using non-modal windows gives the user maximum flexibility to perform tasks within your application in any order and by whichever means they choose.

A modal window, while it is open, prevents the user from interacting with other windows in the same application (application modal), or in all applications, including the desktop itself (system modal).


  • Use an application modal window only if allowing interaction with other parts of the application while the window is open could cause data loss or some other serious problem. Provide a clear way of leaving the modal window, such as a Cancel button in an alert.

  • Do not use system modal windows.


Focus is the means by which the user designates which window should receive data from the keyboard, mouse or other input device. If using a screen reader or similar assistive technology, focus may also designate the window that the user wants to receive information about. The focused window is considered the window the user is currently "working with".

Ensure your application functions properly with the three different mechanisms by which windows can receive focus in GNOME:

  • Click-to-focus. A window is focused by clicking in it.

  • Point-to-focus. A window is focused by moving the mouse pointer into it. Sometimes known as "sloppy focus".

  • Keyboard focus. A window is focused by using a keyboard shortcut such as Alt-Tab.

Special restrictions for point to focus

Note that point-to-focus places a number of restrictions on GNOME applications that are not present in environments such as MacOS or Windows. For example, utility windows shared between multiple document windows, like the toolbox in the GIMP Image Editor, cannot be context-sensitive— that is, they cannot initiate an action such as Save on the current document. This is because while moving the mouse from the current document to the utility window, the user could inadvertantly pass the pointer over a different document window, thus changing the focus and possibly saving the wrong document.

Primary Windows

Figure 3.2. A typical primary window (gedit)

A typical primary window: the gedit document view

A primary window usually presents a view of the user's data, such as a text document in a word processor application, an image in a drawing program, or calculations in a calculator or spreadsheet application. It may also be a view of something more abstract, like a game. A single instance of an application may have more than one primary window, and more than one kind of primary window.

A primary application window normally has a border, a menubar and a statusbar, and may also contain one or more toolbars.


For document-based applications, use Document Name as the window title.

Example 3.1. Using document names as window titles

ApplicationExample window title
AbiWordMy Report.abw
Music playerU2 - Better Than the Real Thing

While document names are most pertinent to users, we understand that application developers may want to increase recognition of their application. If you plan to include your application's name in the title of a primary window, use the following format: Document Name - Application Name. This will ensure that the document name appears in limited space situations such as the system window list. Note that including the application name is not recommended, however.

For other types of application, use Application Name as the window title.

Example 3.2. Using application names as window titles

ApplicationWindow title

Do not place version numbers, company names, or other information that is of no immediate use to the user in the window title. These consume space, making titles in limited spaces such as the system window list less useful, and add more text the user has to scan to find useful information. In a "beta" product, where version numbers are critical for bug information, placing version numbers can be useful, but remove them from stable releases. Place version information in the about box instead.

Window Commands

Close, Maximize/Restore, Minimize, Roll-up/Unroll

Relation between Documents and Windows

Single Document Interface (SDI)

Figure 3.3. A typical SDI application (Eye of GNOME)

A typical SDI application: Eye of GNOME being used to inspect an icon

A single document interface places each document in its own primary window. Toolboxes and other utility windows may be shared between multiple SDI documents, but closing them should have no effect on the document windows. Use SDI for your GNOME application unless there is a compelling reason not to.

Controlled Single Document Interface (CSDI)

Figure 3.4. A typical controlled SDI application (The GIMP)

Screenshot of The GIMP image editor with six images open for editing

CSDI is reserved for applications where the extra overhead of a toolbar or menu per primary window is considered unacceptable. This is rarely the case, as most documents require enough display space that the toolbar and menu add relatively little overhead. The primary exception to this is an application that must handle large numbers of small images well. Complex drawing applications, such as The GIMP, currently present this kind of interface. The main toolbox of The GIMP is the control window.

Multiple Document Interface (MDI)

Figure 3.5. A typical MDI application (gedit) showing three open documents on tabbed pages

A typical MDI application: gedit with three open documents in the same window

A multiple document interface presents a paned, tabbed or similar presentation of two documents within a single window. MDI has several inherent usability problems, so its use is not encouraged in new GNOME applications. It is better to open each document in a new primary window, with its own menubar, toolbars and statusbar, or allow multiple instances of your application to be run simultaneously. In either case, this leaves it for the window manager (acting on the user's preferences) rather than your application to decide how to group and present document windows from the same application.

Utility Windows

Utility windows, such as palettes and toolboxes, normally have borders. They do not contain a menu bar, a toolbar, or a statusbar.

Instant apply and explicit apply

For windows that allow the user to change values or settings, such as property and preference windows, update those values or settings immediately to reflect the changes made in the window. This is known as "instant apply". Do not make the user press an OK or Apply button to make the changes happen, unless either:

  • the change will take more than about one second to apply, in which case applying the change immediately could make the system feel slow or unresponsive, or

  • the changes in the window have to be applied simultaneously to prevent the system entering a potentially unstable state. For example, the hostname and proxy fields in a network properties window.

If either these conditions affect only a few of the controls in your window, arrange those controls together into one or more groups, each with its own Apply button. Leave the rest of the controls as instant apply.

Applying changes in text fields

Do not attempt to validate or apply changes caused by editing a text field control until the user has moved focus to a different control in the window. Validating after each keypress is usually annoying and unnecessary.

If most of the controls in your window are not suitable for instant apply, consider making the whole window "explicit apply". An explicit apply window has these three buttons in its button box, plus an optional Help button:

  • Apply. Applies all the settings in the window, but does not close the window in case the user wishes to change their mind.

  • Cancel. Resets all settings in the window to those that were in force when the window was opened. Note: this must undo the effects of all applications of the Try since the window was opened, not just the most recent one.

  • OK. Applies all settings in the window, and closes the window.

Figure 3.6. Buttons in an explicit apply window

Screenshot showing correct positions for Help, Apply, Cancel and OK buttons in a dialog

Default Buttons

When designing a dialog or utility window, you can assign the Return key to activate a particular button in the window. GNOME indicates this button to the user by drawing a different border around it. For example, the OK button in Figure 3.6.

Choose the default button to be the most likely action, such as a confirmation action or an action that applies changes in a utility window. Do not make a button the default if its action is irreversible, destructive or otherwise inconvenient to the user. If there is no appropriate button in your window, to designate as the default button, do not set one.

In particular, it is currently not recommended to make the Close button the default in an instant apply window, as this can lead to users closing the window accidentally before they have finished using it.

Property Windows

Figure 3.7. Example of a property window

Screenshot showing the "file properties" window from Nautilus

Property windows allow the user to view and change the characteristics of an object such as a document, file, drawing, or application launcher.

Title Format: Object Name Properties

Window Commands: Close, Minimize, Roll-up/Unroll

Buttons: Place a Close button in the lower right corner.

Preferences Windows

Figure 3.8. Example of a preferences window

Screenshot showing the Gnibbles preferences window

Preferences windows allow the user to change the way an application looks or behaves.

Title Format: Application Name Preferences

Window Commands: Close, Minimize, Roll-up/Unroll

Buttons: Place a Close button in the lower right corner.


Figure 3.9. An example of a toolbox

A screenshot of a toolbox with eight buttons arranged into two rows

A toolbox provides convenient access to a set of actions and toggles through a set of small toolbar-like buttons. Toolboxes can be used to provide a specialized group of tools to augment a toolbar containing more universal items such as Save and open. A single toolbox can be shared between multiple documents to save screen space.

Title Format: Toolboxes have no title

Window Commands: Close, Roll-up/Unroll

Buttons: Toolboxes have no buttons

Resizing: Make toolboxes resizable, but only resize by discrete toolbox item widths. In other words, the user can resize the toolbox to be one item wide, two items wide, three items wide, etc. but not one and a half items wide.


  • Only place buttons in a toolbox that do not open another window.

  • Toolboxes are best used for modal toggle buttons that affect the operation of the mouse on the document, such as a set of buttons for choosing between paintbrush, eraser, and fill modes in a drawing application. Buttons that initiate actions upon clicking (such as a save button) are better placed in toolbars.

  • Ensure that closing a toolbox does not close or otherwise alter any primary window with which it is associated, unless your application uses the controlled SDI model.

  • Do not place toolboxes in the system window list, unless your application uses the controlled SDI model. Toolboxes should always remain above all primary windows with which they are associated.

  • If all primary windows associated with a toolbox are closed or minimized, hide the toolbox as well. Show the toolbox again when one of the primary windows is opened or restored.

  • Make a toolbox two items wide by default, unless it is broken into categories. Make categorized toolboxes four items wide by default.

Toolbox Categories

Figure 3.10. A large toolbox broken into categories

Break toolboxes with more than sixteen items into categories. The best size for a category is between four and ten items. Give each category a label and a collapsing arrow. Clicking the label or the arrow toggles the category between a collapsed and uncollapsed state.

While categories may not be as visually appealing as a toolbox homogenously filled with beautiful icons, they make an unwieldy large toolbox more managable. Picking a small icon from more than fifteen other items is a difficult task. Additionally, categories allow users to hide sets of tool items that are not relevant to their current task.


Figure 3.11. An example of an alert

An example of an alert, showing the text "You have an appointment with George Wells in 15 minutes", and with an OK button to dismiss the window.

An alert provides information about the state of the application system, or asks for essential information about how to proceed with a particular task. It is distinct from other types of window in that it is not directly requested by the user, and usually contains a message or a question rather than editable controls. Since alerts are an unwelcome intrusion into the user's work, do not use them except where necessary to avoid potential data loss or other serious problems.

An alert has a border similar to that of a dialog, and is object modal.

Title Format. Alert windows have no titles, as the title would usually unnecessarily duplicate the alert's primary text. This way, users can read and respond to alerts more quickly as there is less visual noise and confounding text.

Resizing. Alert windows are not resizable. If the user needs to resize your alert, the text is probably not concise enough.

Alerts do not appear in the system window list. Consequently, take care to ensure that alerts stay above their parent window.

Alert Text

Figure 3.12. Primary and Secondary Text Placement

Screenshot of an alert showing example of primary text in bold,  and secondary text in a smaller font underneath.

Primary Text. The primary text provides the user with a one sentence summary of the information or suggested action. This summary should concisely contain the essential details of the problem or suggestion. Every alert has primary text, displayed in a bold font slightly larger than the default.

Denote primary text with the pango markup:

<span weight="bold" size="larger">Primary Text</span>

Secondary Text. Secondary text provides a more in-depth description of the problem and suggested action, including possible side effects. Secondary text can also provide information that may be helpful in allowing the user to make an informed decision. In most situations the user should only need the primary text to make a quick decision, but they may read the secondary text if they are unsure of the proper course of action, or require extra details. Secondary text is optional, but if used, place it one text line height beneath the primary text using the default font size and weight.

Alert Buttons

Figure 3.13. Button ordering and placement for alerts

Screenshot showing ordering and placement of alert buttons: Help button in bottom left, and Alternate, Cancel and Affirmative buttons in bottom right.

Give all alerts an affirmative button that dismisses the alert and performs the action suggested in the primary text. Provide a Cancel button for all alerts displayed in response to a user actions, such as Quit. If the alert warns of a technical problem or other situation that could result in data loss, provide a Help button that provides more information on the particular situation and explains the user's options. You may also provide buttons to perform alternate actions that provide another possible solution, fix potential problems, or launch related dialogs or programs.

Button Phrasing. Write button labels as imperative verbs, for example Save, Print. This allows users to select an action with less hesitation. An active phrase also fits best with the button's role in initiating actions, as contrasted with a more passive phrase. For example Find and Log In are better buttons than than Yes and OK.

  • Affirmative Button. Place the affirmative button in the lower right corner of the alert. The affirmative button accepts the action proposed by the alert, or simply dismisses the alert if no action is suggested (as is the case with an information alert).

  • Cancel Button. If the alert was produced in response to a user action, place a Cancel button immediately to the left of the affirmative button. This provides an escape route for users to stop an action in response to new information, or just if they clicked accidentally. Clicking the Cancel button reverts the application to its state prior to the user action.

  • Help Button. A Help button may be used to clarify alerts that present potentially destructive options. Place the Help button in the lower left corner of the alert. When clicked, launch a help window clarifying the situation, detailing the actions performed by the other buttons, and explaining any side-effects that each action may have.

  • Alternate Buttons. Extra buttons may be used to provide alternates to the primary action proposed by the alert text. Place these buttons to the left of the Cancel button, or the affirmative button if Cancel is not present. An example of a common alternate action would be a Quit without Saving button in a save confirmation alert. This is an alternative to the primary suggested action Save and the Cancel button.

Spacing and Positioning Inside Alerts

Figure 3.14. Spacing inside an alert

Diagram showing correct spacing to use between controls and buttons in an alert window.  This is detailed in the guidelines below.


  • The border around all edges of the alert, and the space between the icon and the text, is 12 pixels.

  • The horizontal spacing between the buttons is 6 pixels.

  • The space below both the primary and secondary text is one line break at the standard font size, or 24 pixels if you are using Glade.

  • The top of the icon aligns with the top of the primary text.

  • The text is left-aligned, in western locales.

Technical Details for Proper Layout

Create a new GtkDialog window specifying the number of buttons you wish the alert to contain (and a help button if appropriate). The GtkDialog will contain a GtkVBox with an empty upper row, and a lower row containing a GtkButtonBox with buttons in it. In the empty upper row, place a new GtkHBox. In the left column of the GtkHBox place a GtkImage. In the right column of the GtkHBox place a GtkLabel. Inside the GtkLabel place Primary Text first (using the appropriate Pango markup, see the section called “Alert Text”), then put two linebreaks (return), then place Secondary Text. Now change the properties for each control according to these tables:

Table 3.1. Properties for the GtkDialog

Border Width6
Has SeperatorNo

Table 3.2. Properties for the GtkVBox (included in the dialog by default)


Table 3.3. Properties for the GtkHBox

Border Width6

Table 3.4. Properties for the GtkImage

Y Align0.00

Table 3.5. Properties for the GtkLabel

Use MarkupYes
Wrap TextYes
Y Align0.00

Information Alerts

Figure 3.15. An information alert

Use an information alert when the user must know the information presented before continuing, or has specifically requested the information. Present less important information by other means such as a status bar message.

An information alert...

  • uses the stock information icon.

  • presents a selectable message and an OK button. The button is placed in the bottom right corner of the alert. Pressing Enter or Escape dismisses the alert.

  • may present a convenience button to give access to a relevant object. For example, a Details button in an appointment reminder alert that opens the appointment's property window. Place this button to the left of the affirmative button.

Window Commands: Roll-up/Unroll, Minimize (if the alert has no parent window), Close

Error Alerts

Figure 3.16. An error alert

Display an error alert when a user-requested operation cannot be sucessfully completed. Present errors caused by operations not requested by the user by another means, unless the error could result in data loss or other serious problems. For example, an error encountered during an email check initiated by the user clicking a toolbar button should present an error alert. However, an error encountered in an automated periodic email check would more appropriately report failure with a status bar message.

An error alert...

  • uses the stock error icon.

  • presents a selectable message and an OK button. The button is placed in the bottom-right corner of the alert. Pressing Enter may dismiss the error alert.

  • may present a convenience button to allow immediate handling of the error. For example, a Format... button in a "This disk is not formatted" alert. Place this button to the left of the affirmative button.

Window Commands: Roll-up/Unroll

Confirmation Alerts

Figure 3.17. A confirmation alert

Present a confirmation alert when the user's command may destroy their data, create a security risk, or take more than 30 seconds of user effort to recover from if it was selected in error.

A confirmation alert...

  • uses the stock warning icon.

  • presents a button labelled with a verb or verb phrase describing the action to be confirmed, or labelled OK if such a phrase would be longer than three words. This button is placed in the bottom right corner of the alert.

  • presents a Cancel button that will prevent execution of the user's command. This button is placed to the immediate left of the OK or equivalent button.

  • may present an alternate action button or a convenience button. Place this button to the left of the Cancel button.

Window Commands: Roll-up/Unroll

Save Confirmation Alerts

Figure 3.18. A save confirmation alert

Save confirmation alert: "[ Close without Saving] [ Cancel ] [[ Save ]] "

Save confirmation alerts help ensure that users do not lose document changes when they close applications. This makes closing applications a less dangerous operation.

Primary Text. Save changes to document Document Name before closing?

You may replace “document” with a more appropriate description, for example “image” or “diagram” if the document in question is not primarily text.

Secondary Text. If you close without saving, changes from the last Time Period will be discarded

The secondary text provides the user with some context about the number of changes that might be unsaved.

Buttons. Close without Saving, Cancel, Save

Authentication Alerts

Figure 3.19. An authentication alert

Authentication alerts prompt the user for information necessary to gain access to protected resources, such as their username or password. Authentication alerts are a special kind of alert because they are both routine and largely unavoidable. Every attempt should be made to retain information entered into an authentication alert as long as is possible within security constraints.

An authentication alert:

  • uses the stock authentication icon

  • presents labelled fields for the user to fill with the data needed for authentication. Suggested fields are Username and Password (in that order) where appropriate.

  • may find it secure to retain username data longer than the password, in which case, pre-fill the username field and give the password field the default focus when the alert is displyed.

  • will present a button labelled with a verb or verb phrase describing the action authenticated, or OK if such a phrase would be longer than three words. Place this button in the bottom right corner of the alert.

  • will present a Cancel button that will prevent authentication. Place this button to the immediate left of the OK or equivalent button.

  • does not enable the OK or equivalent button until all fields have been filled by the user.

  • may present an alternative action button or convenience button. Place this button to the left of the Cancel button.

When the user presses Return, move focus to the next field instead of activating the default button, unless the field is the last one. In that case, activate the default button.

Window Commands: Roll-up/Unroll

Dialog Boxes

Figure 3.20. An example of a dialog box

An example of a dialog box: the Glade project options dialog

A dialog box provides an exchange of information, or dialog, between the user and the application. Use a dialog box to obtain additional information from the user that is needed to carry out a particular command or task.

Title Format: Name of command that opened the dialog (without any trailing ellipsis)

Window Commands: Minimize, Roll-up/Unroll

Buttons: Follow the guidelines for Alert buttons, see the section called “Alert Buttons”.

Your dialog may specify a default button, that is activated when the user presses the Return key. See the section called “Default Buttons” for guidance on choosing an appropriate default button.

Additional Buttons

You can include other buttons in a dialog's main button area in addition to the affirmative button and Cancel, but any more than one or two such buttons will make the dialog appear complicated and difficult to use. As with any other button, keep the labels as concise as possible to minimize this effect.


  • Place buttons that apply to the dialog box as a whole in the main button area row at the bottom of the dialog box, to the left of the Cancel button.

  • Place buttons that apply to one or a few controls next to their associated controls. For instance, place a Browse... button at the trailing edge of the text field it fills in.


Arrange controls in your dialog in the direction that people read. In western locales, this is generally left-to-right, top-to-bottom. Position the main controls with which the user will interact as close to the upper left corner as possible. Follow similar guidelines for arranging controls within groups in the dialog, and for specifying the order in which controls are traversed using the Tab key.

When opening a dialog, provide initial keyboard focus to the component that you expect users to operate first. This focus is especially important for users who must use a keyboard to navigate your application.

Provide and show sensible default values for as many of the controls in your dialog as possible when it is opened, so the user does not have to generate the information from scratch. These defaults may come from system settings (for example, hostname or IP address), or from information that the user has previously entered in this or another application (for example, email address or network proxy).

See Chapter 8 for more detailed information on arranging controls in dialogs.

See the section called “Tabbed Notebooks” for information on using tabbed notebook controls in dialogs.

Common Dialogs

The gtk and GNOME libraries provide standard dialogs for many common tasks, including opening and saving files, choosing fonts and colors, and printing. Always use these when the user is performing one of these tasks. You may modify the dialogs to reflect the needs of your particular application (for example, adding preview Play and Stop buttons to the Open File dialog in an audio application), but do not change or remove features so much as to make them unrecognizable.


An assistant is a secondary window that guides the user through an operation by breaking it into sequential steps. Assistants are useful for making complex operations less intimidating, as they restrict the information visible to the user at any given moment.

Because assistants provide a relatively small number of controls on the screen at any given time, they have sufficient space for inline documentation. Therefore, do not include a Help button in an assistant window. If you cannot make an operation sufficiently clear in an assistant without resorting to a Help button, you need to simplify it further.

Window Commands: Close, Minimize/Unminimize, Roll-up/Unroll

Introductory Page

The first page provides the user with the "big picture". Place the title of the assistant in the window's title bar and the assistant's title area, along with an optional picture. Beneath this, state the goal of the assistant, and, if it is not obvious, where the user can find the information the assistant will be asking for.

Title Format: Assistant Title

Buttons: Cancel, Next

Figure 3.21. Example of the first page of an assistant

Screenshot showing the first page of an assistant for creating a new email account

Content Pages

Content pages contain the actual settings of the assistant. Summarize the type of setting present on each content page in its title area. For example, Mail Server.

Title Format: Assistant Title - (Current Page of Total Pages)

Buttons: Cancel, Back, Next

Figure 3.22. Example of a middle page of an assistant

Screenshot showing the third page of an email account assistant, asking for mail server information

Last Page

The last page should summarize the settings that will be changed by the assistant, and how the user can modify them later.

Title Format: Finish Assistant Title

Buttons: Cancel, Back, Finish