Status: Pending Review. This pattern has not yet been reviewed by the GNOME design team.

Description

To allow people to add, remove, edit, or re-order items in a single or multi-column list.

Solution

A list control with compact action buttons below. In many cases, Add and Remove buttons will be sufficient (left), but other buttons such as Duplicate, Edit, Move Up and Move Down may also be provided (right).

Usage

Use where people are allowed to add, remove from, edit or arrange arbitrary items in a list. The list may have more than one column.

Do not use if there is not enough vertical space to display at least six rows, or enough horizontal space to display items of typical length without truncation. If space is limited, consider using an <a href="#">Editable Dropdown Menu (TBD)</a> instead.

Do not use where a person needs to create one list from another list of available items. Use the <a href="#">Add/Remove List pattern (TBD)</a> instead.

Rationale

This pattern is more compact than the typical GNOME 2 method of showing full-sized action buttons such as "Add" and "Remove" alongside the list, but retains the same button icons for familiarity (until GNOME 2 stopped showing icons on buttons by default). This pattern also has precedent in Mac OS X.

Related Patterns

Links to similar patterns, or other patterns commonly used with this one

Specifications

Layout

A GtkTreeView is packed into a GtkVbox with a GtkToolbar. Key properties are:

• GtkVbox Spacing: 0

• Toolbar Icons: list-add-symbolic, list-remove-symbolic, edit-copy-symbolic, gtk-edit (TBD: No symbolic version of this one), go-up-symbolic, go-down-symbolic
• Toolbar Class: inline-toolbar
• Toolbar Style: Icons Only
• Toolbar Show Arrow: False
• Toolbar Icon Size: 1

The Duplicate, Edit, Move Up and Move Down buttons are optional, but if they are used, should be provided in the order shown.

Labels for toolbar buttons (not shown, but used for accelerator and screenreader access):

• _Add
• _Remove
• Du_plicate
• _Edit
• Move _Up
• Move _Down

Tooltips for toolbar buttons:

• Add
• Remove
• Duplicate
• Edit
• Move up
• Move down

Interaction

Adding and Removing Items

To add an item to the list, do one of the following:

• (mouse) click the Add button
• (mouse) double-click anywhere in any empty row
• (kb)navigate to the Add button, then press Space
• (kb) navigate to the list control, then press the accelerator for the Add button (Alt+A in English locales)

An inline editing control or a popup window will appear, in which you enter the name of the new item.

If an inline editing control is used, then after entering the required information, either:

• press Tab or Enter to confirm the edit and move focus to the next empty row, where an additional item may be entered, or
• press Esc to cancel the edit

If you cancel the addition while adding the first (or only) column of a row, that row is removed again. Focus then returns to the previous entry in the list.

To remove an item from the list, do one of the following:

• (mouse) click the row to be removed to highlight it, then click the Remove button
• (kb) select the item to remove, then press Delete or the accelerator for the Remove button (Alt+R in English locales)
• (kb) select the item to remove, then navigate to the Remove button, then press Space

(TBD: If/when to ask for confirmation -- depends what sort of Undo/Reset mechanisms we decide should be standard within dialogs.)

The Remove button is disabled when the list is empty.

All buttons except Add are disabled when no items in the list are selected.

Editing Items

To edit an item, do one of the following:

• (mouse) select the row to be edited, then click the Edit button
• (kb) select the item to edit, then press the accelerator for the Edit button (Alt+E in English locales)
• (kb) select the item to edit, then navigate to the Edit button, then press Space

Double-clicking a list item may perform some direct action with the list item, for example, applying a color from the list to an object selected on a drawing canvas. If this is <em>not</em> the case, however, you can also edit the list by doing one of the following:

• (mouse) double-clicking the row to be edited
• (kb) selecting the item to edit, then press Space

However you edit the item, an inline editing control or a popup window will appear for you to make the required changes.

If an inline editing control is used, then after making the required changes, either:

• press Tab or Enter to confirm the edit and move focus to the next editable column or row, or</li>

• press Esc to cancel the edit.</li>

If you cancel the edit while adding the first (or only) column of a row, that row is removed again. Focus then returns to the previous entry in the list.

Source Code

GtkBuilder (.ui) file

Current Usage

Discussion

Comments

Change Log