xmlns:uix="http://projectmallard.org/experimental/ui/"

      type="topic"

      id="buttons">

  <info>

    <credit type="author">

      <name>Allan Day</name>

      <email>aday@gnome.org</email>

    </credit>

    <credit>

      <name>Calum Benson</name>

    </credit>

    <credit>

      <name>Adam Elman</name>

    </credit>

    <credit>

      <name>Seth Nickell</name>

    </credit>

    <credit>

      <name>Colin Robertson</name>

    </credit>

    <link type="guide" xref="ui-elements"/>

    <uix:thumb mime="image/svg" src="figures/ui-elements/buttons.svg"/>

    <include href="legal.xml" xmlns="http://www.w3.org/2001/XInclude"/>

  </info>

<title>Buttons</title>

Buttons are one of the most common and basic user interface elements. Buttons can be used to perform actions, toggle settings or views, activate tools, or to display dialogs, popovers, or other user interface elements.

<media type="image" mime="image/svg" src="figures/ui-elements/buttons.svg"/>

<section id="general-guidelines">

<title>General Guidelines</title>

<list>

<item>
A button can contain an icon, button, or - more unusually - an image. Follow the icons and artwork guidelines when deciding which to use.
</item>

<item>
After pressing a button, the user should expect to see the result of their action within 1 second.
</item>

<item>
Do not use more than one or two different widths of button in the same window, and make all of them the same height. This will help give a pleasing uniform visual appearance to your window that makes it easier to use.
</item>

<item>
Do not assign actions to double-clicking or right-clicking a button. Users are unlikely to discover these actions, and if they do, it will distort their expectations of other buttons on the desktop.
</item>

<item>
Make invalid buttons insensitive, rather than popping up an error message when the user clicks them.
</item>

<item>
When several buttons are placed next to each other, ensure that they have the same width. This is particularly important for pairs of Cancel and OK buttons.
</item>

<item>
In a dialog, one button may be made the default button, which is shown with a different border and is activated by pressing Return. Often this will be the OK or equivalent button. However, if pressing this button by mistake could cause a loss of data, do not set a default button for the window.
</item>

</list>

</section>

<section id="text-buttons">

<title>Text buttons</title>

<list>

<item>
Label all buttons with imperative verbs, using <link xref="writing-style#capitalization">header capitalization</link>. For example, <gui>Save</gui>, <gui>Sort</gui> or <gui>Update Now</gui>.
</item>

<item>
Use <link xref="writing-style#ellipses">ellipses</link> when a button requires further input from the user to complete an action.
</item>

<item>
Provide an <link xref="keyboard-input#access-keys">access key</link> in the label that allows the user to directly activate the button from the keyboard.
</item>

<item>
Keep labels short, so they don't cause a button to use too much space. It is also important to consider how labels will change length when localized.
</item>

</list>

</section>

<section id="toggle-buttons">

<title>Toggle buttons</title>

Toggle buttons look the same as regular buttons, but are used to show or change a state rather than initiate an action. A toggle button’s two states, set and unset, are shown by its appearing “pushed in” or “popped out” respectively.

</section>

<section id="linked-buttons">

<title>Linked buttons</title>

Groups of buttons with a similar function can be grouped. This helps to communicate their similarity. Linking is a common technique for sets of toggle buttons.

</section>

<section id="suggested-and-destructive">

<title>Suggested and destructive actions</title>

In cases where a button has a particularly important affirmative role, it can be given a suggested style. This highlights the button, and helps to distinguish it from other visible controls.

Buttons which have a destructive consequence, such as removing or deleting a content item, can be given a destructive style. This highlights the button by coloring it, and acts as a warning to the user.

Each view should only include a single suggested or destructive button.

</section>

<section id="api-reference">

<title>API reference</title>

<list>

<item>
<link href="https://developer.gnome.org/gtk3/stable/GtkButton.html">GtkButton</link>
</item>

<item>
<link href="https://developer.gnome.org/gtk3/stable/GtkToggleButton.html">GtkToggleButton</link>
</item>

</list>

</section>

</page>