xmlns:its="http://www.w3.org/2005/11/its"

      xmlns:xi="http://www.w3.org/2001/XInclude"

      type="guide" style="task"

      id="scale.py">

  <info>

    <title type="text">Scale (Python)</title>

    <link type="guide" xref="beginner.py#entry"/>

    <link type="seealso" xref="grid.py"/>

    <link type="next" xref="textview.py" />

    <revision version="0.2" date="2012-06-23" status="draft"/>

    <credit type="author copyright">

      <name>Marta Maria Casetti</name>

      <email its:translate="no">mmcasetti@gmail.com</email>

      <years>2012</years>

    </credit>

    <desc>A slider widget for selecting a value from a range</desc>

  </info>

  <title>Scale</title>

  <media type="image" mime="image/png" src="media/scale.png"/>

  
Slide the scales!

  <links type="section" />

  <section id="code">

    <title>Code used to generate this example</title>

    <xi:include href="samples/scale.py" parse="text"><xi:fallback/></xi:include>

  </section>

  <section id="methods">

    <title>Useful methods for a Scale widget</title>

    
A Gtk.Adjustment is needed to construct the Gtk.Scale. This is the representation of a value with a lower and upper bound, together with step and page increments, and a page size, and it is constructed as Gtk.Adjustment(value, lower, upper, step_increment, page_increment, page_size) where the fields are of type float; step_increment is the increment/decrement that is obtained by using the cursor keys, page_increment the one that is obtained clicking on the scale itself. Note that page_size is not used in this case, it should be set to 0.

    
In line 28 the signal "value-changed" is connected to the callback function scale_moved() using widget.connect(signal, callback function). See <link xref="signals-callbacks.py"/> for a more detailed explanation.

    <list>

      <item>
get_value() retrieves the current value of the scale; set_value(value) sets it (if the value, of type float, is outside the minimum or maximum range, it will be clamped to fit inside them). These are methods of the class Gtk.Range.
</item>

      <item>
Use set_draw_value(False) to avoid displaying the current value as a string next to the slider.
</item>

      <item>
To highlight the part of the scale between the origin and the current value:

self.h_scale.set_restrict_to_fill_level(False)

self.h_scale.set_fill_level(self.h_scale.get_value())

self.h_scale.set_show_fill_level(True)

        
in the callback function of the "value-changed" signal, so to have the new filling every time the value is changed. These are methods of the class Gtk.Range.

      </item>

      <item>
add_mark(value, position, markup) adds a mark at the value (float or int if that is the precision of the scale), in position (Gtk.PositionType.LEFT, Gtk.PositionType.RIGHT, Gtk.PositionType.TOP, Gtk.PositionType.BOTTOM) with text Null or markup in the Pango Markup Language. To clear marks, clear_marks().
</item>

      <item>
set_digits(digits) sets the precision of the scale at digits digits.
</item>

    </list>

  </section>

  <section id="references">

    <title>API References</title>

    
In this sample we used the following:

    <list>

      <item>
<link href="http://developer.gnome.org/gtk3/unstable/GtkScale.html">GtkScale</link>
</item>

      <item>
<link href="http://developer.gnome.org/gtk3/unstable/GtkAdjustment.html">GtkAdjustment</link>
</item>

      <item>
<link href="http://developer.gnome.org/gtk3/unstable/gtk3-Standard-Enumerations.html">Standard Enumerations</link>
</item>

    </list>

  </section>

</page>