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

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

<title>Spin boxes</title>

<p>A spin box is a text box that accepts a range of values. It incorporates two buttons that allow the user to increase or decrease the value by a fixed amount.</p>

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

<section id="when-to-use">
<title>When to use</title>

<p>Use spin boxes to allow users to select numeric values, but only when those values are meaningful or useful for users to know. If they aren't, a <link xref="sliders">slider</link> might be a better choice.</p>

<p>Use spin boxes for numerical input only. For non-numeric sets of options, a <link xref="lists">list</link> or <link xref="drop-down-lists">drop-down list</link> can be used instead.</p>

</section>

<section id="sliders">
<title>Sliders</title>

<p>In some cases, it is appropriate to link a spin button with a slider. This combination allows both approximate control and the entry of specific values. However, it is only useful if you want to cater to people who may know a specific value that they want to use. Use a slider when:</p>

<list>
<item><p>Immediate feedback for changes in the spin box’s value is possible (such as in the case of image editing).</p></item>
<item><p>It is useful for the user to control the rate of change of the value in real time. For example, to monitor the effects of a color change in a live preview window as they drag the RGB sliders.</p></item>
</list>

</section>

<section id="general-guidelines">
<title>General guidelines</title>

<list>
<item><p>Label the spin box with a text label above it or to its left, using sentence capitalization. Provide an access key in the label that allows the user to give focus directly to the spin box.</p></item>
<item><p>Right-justify the contents of spin boxes, unless the convention in the user’s locale demands otherwise. This is useful in windows where the user might want to compare two numerical values in the same column of controls. In this case, ensure the right edges of the relevant controls are also aligned.</p></item>
</list>

</section>

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

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

</section>

</page>