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

      type="topic"

      id="check-boxes">

  <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/check-boxes.svg"/>

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

  </info>

<title>Check boxes</title>

Check boxes are used to show or change a setting. Its two states, set and unset, are shown by the presence or absence of a checkmark in the labeled box.

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

<section id="guidelines">

<title>Guidelines</title>

<list>

<item>
Clicking a check box should not affect the values of any other controls. It may sensitize, insensitize, hide or show other controls, however.
</item>

<item>
If toggling a check box affects the sensitivity of other controls, place the check box immediately above or to the left of the controls that it affects. This helps to indicate that the controls are dependent on the state of the check box.
</item>

<item>
Use <link xref="writing-style#capitalization">sentence capitalization</link> for check box labels, for example <gui>Use custom font</gui>.
</item>

<item>
Label check boxes to clearly indicate the effects of both their checked and unchecked states, for example, <gui>Show icons in menus</gui>. If the two states of a check box cannot be clearly communicated, consider using two radio buttons instead so both states can be given labels.
</item>

<item>
Avoid negative check box labels, as this can be confusing and hard to understand. <gui>Play alert sound</gui> is better than <gui>Disable alert sound</gui>, for example.
</item>

<item>
Provide an <link xref="keyboard-input#access-keys">access key</link> in all check box labels that allows the user to set or unset the check box directly from the keyboard.
</item>

<item>
If the check box represents a setting in a multiple selection that is set for some objects in the selection and unset for others, show the check box in its mixed state. When a check box is in its mixed state:

<list>

<item>
Clicking the box once should check the box, applying that setting (when confirmed) to all the selected objects.
</item>

<item>
Clicking the box a second time should uncheck the box, removing that setting (when confirmed) to all the selected objects.
</item>

<item>
Clicking the box a third time should return the box to its mixed state, restoring each selected object’s original value for that setting (when confirmed).
</item>

</list></item>

<item>
Label a group of check boxes with a descriptive heading above or to the left of the group.
</item>

<item>
Do not place more than about eight check boxes under the same group heading. If you need more than eight, try to use blank space or heading labels to divide them into smaller groups. Otherwise, consider using a check box list instead— but you probably also need to think about how to simplify your user interface.
</item>

<item>
Try to align groups of check boxes vertically rather than horizontally, as this makes them easier to scan visually. Use horizontal or rectangular alignments only if they greatly improve the layout of the window.
</item>

</list>

</section>

<section id="api-reference">

<title>API reference</title>

<list>

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

</list>

</section>

</page>