<page xmlns="http://projectmallard.org/1.0/"
      xmlns:uix="http://projectmallard.org/experimental/ui/"
      type="topic"
      id="sliders">

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

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

<title>Sliders</title>

<p>A slider allows the user to quickly select a value from a range.</p>

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

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

<p>Sliders can be used to either change a value, or for navigation within a content item, such as video, audio or even documents. Common uses include seeking through audio or video, changing a zoom or volume level, or setting values in image editors.</p>

<p>Use a slider when:</p>

<list>
<item><p>The range of values is fixed and ordered, and when adjusting the value relative to its current value is more important than choosing an absolute value.</p></item>
<item><p>It is useful for the user to control the rate of change of the value in real time.</p></item>
</list>

<p>If the range of values does not have a fixed maximum and/or minimum, a <link xref="spin-boxes">spin box</link> can be used.</p>

</section>

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

<list>
<item><p>Ensure that real time feedback is provided, in order to enable the user to make live adjustments. Examples of this include sound from speakers, indicating volume changes, or live feedback in an image editor.</p></item>
<item><p>Take care to ensure that the purpose of a slider is clearly identified.</p>
<list>
<item><p>In cases where it is common to use a slider, follow placement conventions. For example, in video players, it is common to situate a horizontal seek bar along the bottom of the window. Simply placing a slider in this position is enough to identify it.</p></item>
<item><p>In other cases, label the slider with a text label above it or to its left, using <link xref="writing-style#capitalization">sentence capitalization</link>. Provide an <link xref="keyboard-input#access-keys">access key</link> in the label that allows the user to give focus directly to the slider.</p></item>
</list></item>
<item><p>Mark significant values along the length of the slider with text or tick marks. For example the left, right and center points on an audio balance control.</p></item>
<item><p>For large ranges of integers (more than about 20), and for ranges of floating point numbers, consider providing a <link xref="text-fields">text box</link> or <link xref="spin-boxes">spin box</link> that is linked to the slider’s value. This allows the user to quickly set or fine-tune the setting more easily than they could with the slider control alone.</p></item>
</list>

</section>

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

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

</section>

</page>
