This site has been retired. For up to date information, see handbook.gnome.org or gitlab.gnome.org.


[Home] [TitleIndex] [WordIndex

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

EditableList-AddRemoveOnly.png

EditableList-AllButtons.png

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.

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

Specifications

Layout

EditableList-AllButtons.png

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

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

Tooltips for toolbar buttons:

Interaction

Adding and Removing Items

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

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:

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:

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

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:

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:

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

cc-background-3.0.1.PNG

cc-network-3.0.1.PNG

Discussion

Comments

Change Log

2011-07-10

Calum Benson

Update to latest pattern template

2010-08-03

Calum Benson

Add screenshots and (rough) .ui file.

2010-07-27

Calum Benson

First draft.


2024-10-23 11:03