<page xmlns="http://projectmallard.org/1.0/"
      xmlns:uix="http://projectmallard.org/experimental/ui/"
      type="topic"
      id="radio-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/radio-buttons.svg"/>

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

<title>Radio buttons</title>

<p>Radio buttons are used in groups to select from a mutually exclusive set of options. Only one radio button within a group may be set at any one time. As with check boxes, do not use radio buttons to initiate actions.</p>

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

<section id="guidelines">
<title>Guidelines</title>

<list>
<item><p>Only use radio buttons in groups of at least two, never use a single radio button on its own. To represent a single setting, use a check box or two radio buttons, one for each state.</p></item>
<item><p>Exactly one radio button should be set in the group at all times. The only exception is when the group is showing the properties of a multiple selection, when one or more of the buttons may be in their mixed state.</p></item>
<item><p>Clicking a radio button should not affect the values of any other controls. It may sensitize, insensitize, hide or show other controls, however.</p></item>
<item><p>If toggling a radio button affects the sensitivity of other controls, place the radio button immediately to the left of the controls that it affects. This helps to indicate that the controls are dependent on the state of the radio button.</p></item>
<item><p>Use <link xref="writing-style#capitalization">sentence capitalization</link> for radio button labels, for example <gui>Switched movement</gui>. Provide an <link xref="keyboard-input#access-keys">access key</link> in the label that allows the user to set the radio button directly from the keyboard.</p></item>
<item><p>If the radio button represents a setting in a multiple selection that is set for some objects in the selection and unset for others, show the radio button in its mixed state.</p></item>
<item><p>Do not place more than about eight radio buttons under the same group heading. If you need more than eight, consider using a single-selection list instead— but you probably also need to think about how to simplify your user interface.</p></item>
<item><p>Try to align groups of radio buttons 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.</p></item>
</list>

</section>

<section id="api-reference">
<title>API reference</title>

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

</section>
</page>
