<?xml version="1.0" encoding="utf-8"?>
<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="fr">
  <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 élément graphique glissière pour choisir une valeur dans un intervalle</desc>
  
    <mal:credit xmlns:mal="http://projectmallard.org/1.0/" type="translator copyright">
      <mal:name>Luc Rebert,</mal:name>
      <mal:email>traduc@rebert.name</mal:email>
      <mal:years>2011</mal:years>
    </mal:credit>
  
    <mal:credit xmlns:mal="http://projectmallard.org/1.0/" type="translator copyright">
      <mal:name>Alain Lojewski,</mal:name>
      <mal:email>allomervan@gmail.com</mal:email>
      <mal:years>2011-2012</mal:years>
    </mal:credit>
  
    <mal:credit xmlns:mal="http://projectmallard.org/1.0/" type="translator copyright">
      <mal:name>Luc Pionchon</mal:name>
      <mal:email>pionchon.luc@gmail.com</mal:email>
      <mal:years>2011</mal:years>
    </mal:credit>
  
    <mal:credit xmlns:mal="http://projectmallard.org/1.0/" type="translator copyright">
      <mal:name>Bruno Brouard</mal:name>
      <mal:email>annoa.b@gmail.com</mal:email>
      <mal:years>2011-12</mal:years>
    </mal:credit>
  
    <mal:credit xmlns:mal="http://projectmallard.org/1.0/" type="translator copyright">
      <mal:name>Luis Menina</mal:name>
      <mal:email>liberforce@freeside.fr</mal:email>
      <mal:years>2014</mal:years>
    </mal:credit>
  </info>

  <title>Échelle</title>
  <media type="image" mime="image/png" src="media/scale.png"/>
  <p>Faites glisser les échelles !</p>

  <links type="section"/>

  <section id="code">
    <title>Code utilisé pour générer cet exemple</title>
    <code mime="text/x-python" style="numbered">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)
</code>
  </section>

  <section id="methods">
    <title>Méthodes utiles pour un élément graphique échelle</title>
    <p>Pour construire une échelle Gtk.Scale, il faut un Gtk.Adjustment. C'est la représentation d'une valeur avec une limite inférieure et supérieure, des incréments d'étape et de page, d'une taille de page et est construite sous la forme <code>Gtk.Adjustment(valeur, inferieure, superieure, step_increment, page_increment, page_size)</code>, où les champs sont du type flottant <code>float</code> ; <code>step_increment</code> est l'incrément ou décrément obtenu par l'utilisation des touches fléchées et <code>page_increment</code> est celui obtenu en cliquant sur l'échelle elle-même. Notez que la taille <code>page_size</code> n'est pas utilisée dans notre exemple et que sa valeur doit être définie à <code>0</code>.</p>
    <p>In line 28 the signal <code>"value-changed"</code> is connected to the callback function <code>scale_moved()</code> using <code><var>widget</var>.connect(<var>signal</var>, <var>callback function</var>)</code>. See <link xref="signals-callbacks.py"/> for a more detailed explanation.</p>
    <list>
      <item><p>La méthode <code>get_value()</code> récupère la valeur actuelle de l'échelle ; <code>set_value(valeur)</code> la définit (si la <code>valeur</code>, du type <code>float</code>, est en dehors des limites inférieure ou supérieure, elle sera rétrécie pour tenir à l'intérieur). Ce sont les méthodes de la classe Gtk.Range.</p></item>
      <item><p>Utilisez <code>set_draw_value(faux)</code> pour éviter d'afficher la valeur actuelle sous forme d'une chaîne à côté de la glissière.</p></item>
      <item><p>Pour surligner la partie d'échelle située entre l'origine et la valeur actuelle :</p>
        <code mime="text/x-python">
self.h_scale.set_restrict_to_fill_level(faux)
self.h_scale.set_fill_level(self.h_scale.get_value())
self.h_scale.set_show_fill_level(vrai)</code>
        <p>dans la fonction de rappel du signal « value-changed », pour avoir le nouveau remplissage chaque fois que la valeur est modifiée. Ce sont les méthodes de la classe Gtk.Range.</p>
      </item>
      <item><p>La méthode <code>add_mark(valeur, position, marqueur)</code> ajoute un marqueur à la <code>valeur</code> (<code>float</code> ou <code>int</code> selon la précision de l'échelle) dans <code>position</code> (<code>Gtk.PositionType.LEFT, Gtk.PositionType.RIGHT, Gtk.PositionType.TOP, Gtk.PositionType.BOTTOM</code>) avec le texte <code>Null</code> ou <code>marqueur</code> en langage Pango Markup. La fonction <code>clear_marks()</code> supprime les marqueurs.</p></item>
      <item><p>La méthode <code>set_digits(digits)</code> définit la précision de l'échelle aux caractères <code>digits</code>.</p></item>
    </list>
  </section>

  <section id="references">
    <title>Références API</title>
    <p>Dans cet exemple, les éléments suivants sont utilisés :</p>
    <list>
      <item><p><link href="http://developer.gnome.org/gtk3/unstable/GtkScale.html">GtkScale</link></p></item>
      <item><p><link href="http://developer.gnome.org/gtk3/unstable/GtkAdjustment.html">GtkAdjustment</link></p></item>
      <item><p><link href="http://developer.gnome.org/gtk3/unstable/gtk3-Standard-Enumerations.html">Standard Enumerations</link></p></item>
    </list>
  </section>
</page>