<page xmlns="http://projectmallard.org/1.0/" xmlns:its="http://www.w3.org/2005/11/its" xmlns:xi="http://www.w3.org/2001/XInclude" type="guide" style="task" id="scale.py" xml:lang="gl">

  <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>Un widget de desprazamento para seleccionar un valor dun rango</desc>

    <mal:credit xmlns:mal="http://projectmallard.org/1.0/" type="translator copyright">

      <mal:name>Fran Dieguez</mal:name>

      <mal:email>frandieguez@gnome.org</mal:email>

      <mal:years>2012-2013.</mal:years>

    </mal:credit>

  </info>

  <title>Escala</title>

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

  
Desprazar as escalas!

  <links type="section"/>

  <section id="code">

    <title>Código usado para xerar este exemplo</title>

    from gi.repository import Gtk

import sys

class MyWindow(Gtk.ApplicationWindow):

    def __init__(self, app):

        Gtk.Window.__init__(self, title="Scale Example", application=app)

        self.set_default_size(400, 300)

        self.set_border_width(5)

        # two adjustments (initial value, min value, max value,

        # step increment - press cursor keys to see!,

        # page increment - click around the handle to see!,

        # page size - not used here)

        ad1 = Gtk.Adjustment(0, 0, 100, 5, 10, 0)

        ad2 = Gtk.Adjustment(50, 0, 100, 5, 10, 0)

        # an horizontal scale

        self.h_scale = Gtk.Scale(

            orientation=Gtk.Orientation.HORIZONTAL, adjustment=ad1)

        # of integers (no digits)

        self.h_scale.set_digits(0)

        # that can expand horizontally if there is space in the grid (see

        # below)

        self.h_scale.set_hexpand(True)

        # that is aligned at the top of the space allowed in the grid (see

        # below)

        self.h_scale.set_valign(Gtk.Align.START)

        # we connect the signal "value-changed" emitted by the scale with the callback

        # function scale_moved

        self.h_scale.connect("value-changed", self.scale_moved)

        # a vertical scale

        self.v_scale = Gtk.Scale(

            orientation=Gtk.Orientation.VERTICAL, adjustment=ad2)

        # that can expand vertically if there is space in the grid (see below)

        self.v_scale.set_vexpand(True)

        # we connect the signal "value-changed" emitted by the scale with the callback

        # function scale_moved

        self.v_scale.connect("value-changed", self.scale_moved)

        # a label

        self.label = Gtk.Label()

        self.label.set_text("Move the scale handles...")

        # a grid to attach the widgets

        grid = Gtk.Grid()

        grid.set_column_spacing(10)

        grid.set_column_homogeneous(True)

        grid.attach(self.h_scale, 0, 0, 1, 1)

        grid.attach_next_to(

            self.v_scale, self.h_scale, Gtk.PositionType.RIGHT, 1, 1)

        grid.attach(self.label, 0, 1, 2, 1)

        self.add(grid)

    # any signal from the scales is signaled to the label the text of which is

    # changed

    def scale_moved(self, event):

        self.label.set_text("Horizontal scale is " + str(int(self.h_scale.get_value())) +

                            "; vertical scale is " + str(self.v_scale.get_value()) + ".")

class MyApplication(Gtk.Application):

    def __init__(self):

        Gtk.Application.__init__(self)

    def do_activate(self):

        win = MyWindow(self)

        win.show_all()

    def do_startup(self):

        Gtk.Application.do_startup(self)

app = MyApplication()

exit_status = app.run(sys.argv)

sys.exit(exit_status)

  </section>

  <section id="methods">

    <title>Métodos útiles para o widget Scale</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>

    
Neste exemplo empregaremos o seguinte:

    <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>