<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.js" xml:lang="fr">

  <info>

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

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

    <revision version="0.1" date="2012-06-20" status="draft"/>

    <credit type="author copyright">

      <name>Taryn Fox</name>

      <email its:translate="no">jewelfox@fursona.net</email>

      <years>2012</years>

    </credit>

    <desc>Une glissière qui correspond à une valeur numérique</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/scalepenguins.png"/>

  
Une échelle est une glissière horizontale ou verticale représentant une valeur comprise dans une fourchette numérique. Pour créer une échelle, vous devez définir sa position par défaut, son étendue numérique et le pas auquel elle avance ou recule. Au lieu d'être obligé de tout recommencer à chaque fois que vous créez une nouvelle échelle, vous pouvez inclure toutes ces données dans un objet nommé Adjustment et qui garde en mémoire tous les paramètres. Ensuite, à chaque création d'une nouvelle échelle, il suffit de lui indiquer de prendre ces réglages.

  
Cette échelle est un simple élément graphique permettant d'ajuster la taille d'un iceberg sur lequel vivent des pingouins. Le nombre de pingouins sur l'iceberg est le produit des valeurs des deux glissières. Faites des essais en modifiant les valeurs et observez le résultat.

    <links type="section"/>

  <section id="imports">

    <title>Bibliothèques à importer</title>

#!/usr/bin/gjs

const Gio = imports.gi.Gio;

const Gtk = imports.gi.Gtk;

const Lang = imports.lang;

]]>

    
Ce sont les bibliothèques que nous devons importer pour faire fonctionner cette application. N'oubliez pas que la ligne qui informe GNOME que nous allons utiliser Gjs doit toujours se trouver au début.

    </section>

  <section id="applicationwindow">

    <title>Création de la fenêtre de l'application</title>

const ScaleExample = new Lang.Class({

    Name: 'Scale Example',

    // Create the application itself

    _init: function() {

        this.application = new Gtk.Application({

            application_id: 'org.example.jsscale'

        });

    // Connect 'activate' and 'startup' signals to the callback functions

    this.application.connect('activate', Lang.bind(this, this._onActivate));

    this.application.connect('startup', Lang.bind(this, this._onStartup));

    },

    // Callback function for 'activate' signal presents window when active

    _onActivate: function() {

        this._window.present();

    },

    // Callback function for 'startup' signal builds the UI

    _onStartup: function() {

        this._buildUI ();

    },

]]>

    
Tout le code de cet exemple va dans la classe ScaleExemple. Le code ci-dessus crée une <link href="http://www.roojs.com/seed/gir-1.2-gtk-3.0/gjs/Gtk.Application.html">Gtk.Application</link> pour nos éléments graphiques et la fenêtre qui les contient.

    // Build the application's UI

    _buildUI: function() {

        // Create the application window

        this._window = new Gtk.ApplicationWindow({

            application: this.application,

            window_position: Gtk.WindowPosition.CENTER,

            border_width: 20,

            title: "Birds on a Floe"});

]]>

    
La fonction _buildUI est l'endroit où nous mettons tout le code nécessaire à la création de l'interface utilisateur de l'application. La première étape consiste à créer une <link xref="GtkApplicationWindow.js">Gtk.ApplicationWindow</link> pour y mettre tous nos éléments graphiques.

  </section>

  <section id="button">

    <title>Création des échelles</title>

        // Create the horizontal scale

        this._hScale = Gtk.Scale.new_with_range (Gtk.Orientation.HORIZONTAL, 0.0, 100.0, 5.0);

        this._hScale.set_valign (Gtk.Align.START);

        this._hScale.set_value (50);

        this._hScale.set_digits (0);

        // this._hScale.set_draw_value (false);

]]>

    
La méthode new_with_range est l'un des moyens pour créer un nouvel élément graphique échelle. Les paramètres qu'elle utilise sont <link href="http://www.roojs.org/seed/gir-1.2-gtk-3.0/gjs/Gtk.Orientation.html">Gtk.Orientation</link>, la valeur minimum et l'incrément pour une seule graduation. Ensuite, nous utilisons les méthodes de l'échelle pour définir sa valeur de départ et en combien de fractions décimales la diviser. Dans ce cas, il nous faut aussi définir son alignement vertical pour la placer dans la fenêtre.

    
Nous pouvons aussi lui indiquer s'il faut afficher ou non le nombre à côté de la glissière avec la méthode set_draw_value. Les explications se trouvent dans cet exemple.

        // Create a master adjustment to use for the vertical (or any other) scale

        this._adjustment = new Gtk.Adjustment ({

            value: 95,

            lower: 0,

            upper: 100,

            step_increment: 5,

            page_increment: 10 });

]]>

    
Un Adjustment est un objet permettant de simplifier la procédure de création d'une nouvelle échelle. La propriété « valeur » de l'Adjustment est la valeur par défaut de l'échelle alors que les valeurs « superieure » et « inferieure » en représentent le début et la fin. Entre les deux, les valeurs de l'incrément définissent le pas auquel l'échelle se déplace lorsque vous cliquez dessus.

        // Create a vertical scale using the adjustment we just made

        this._vScale = new Gtk.Scale ({

            orientation: Gtk.Orientation.VERTICAL,

            adjustment: this._adjustment,

            digits: 0,

            // draw_value: false,

            margin_left: 10 });

]]>

    
Ici, nous créons un nouvel objet échelle en utilisant _adjustment comme étant sa propriété d'« ajustement ». Cela est un raccourci important. Cependant, il nous faut encore lui indiquer comment arrondir les décimales. Notez que nous y expliquons aussi la propriété draw_value : comment lui indiquer de ne pas afficher le nombre à côté de l'échelle lorsque vous décidez cette façon de faire.

        // Create the label that shows the product of the two values

        this._product = (this._hScale.get_value() * this._vScale.get_value());

        this._label = new Gtk.Label ({

            label: (String(this._product) + " penguins on the iceberg."),

            height_request: 200,

            width_request: 200,

            wrap: true});

        // Connect the two scales to functions which recalculate the label

        this._hScale.connect ("value-changed", Lang.bind (this, this._recalc));

        this._vScale.connect ("value-changed", Lang.bind (this, this._recalc));

]]>

    
La méthode get_value permet de trouver la valeur numérique à laquelle une échelle est définie. Ensuite, nous pouvons en faire ce que nous voulons, y compris multiplier les valeurs des deux échelles et obtenir une <link xref="label.js">étiquette</link> affichant le produit. Paramétrons le texte avec retour à la ligne, car nous avons aussi un message stupide à afficher.

    
Ensuite, connectons les deux signaux « value-changed » à la fonction _recalc, qui recalcule le nombre de pingouins sur l'iceberg et affiche un nouveau message.

        // Create a grid to arrange things in

        this._UIGrid = new Gtk.Grid ({

            halign: Gtk.Align.CENTER,

            valign: Gtk.Align.CENTER,

            margin_top: 20,

            margin_left: 20});

        // Attach everything to the grid

        this._UIGrid.attach (this._label, 0, 0, 1, 1);

        this._UIGrid.attach (this._hScale, 0, 1, 1, 1);

        this._UIGrid.attach (this._vScale, 1, 0, 1, 1);

]]>

    
Ici, nous créons une <link xref="grid.js">grille</link> pour tout y mettre et nous lui lions tous nos éléments graphiques. Notez que cette fois (et pour quelques éléments graphiques) nous utilisons des marges pour espacer proprement les éléments.

        // Add the grid to the window

        this._window.add (this._UIGrid);

        // Show the window and all child widgets

        this._window.show_all();

    },

]]>

    
Enfin, nous ajoutons la grille à la fenêtre et indiquons à celle-ci de s'afficher toute seule avec tout son contenu.

    </section>

    <section id="scales-handler">

    <title>Fonction prenant en charge les modifications de valeurs de l'échelle</title>

    _recalc: function() {

        // Figure out what the product of the two scales' values is

        var product = (this._hScale.get_value() * this._vScale.get_value());

        // Create a blank comment line in case there isn't a silly comment to make

        var comment = "";

        // Make a silly comment based on the number of penguins

        if (product > 9000) {

            comment = "It's over 9000!";

        }

        else if (product < 1000 && product > 0) {

            comment = "They're getting lonely.";

        }

        else if (product == 0) {

            comment = "They're all gone ...";

        }

        else comment = "";

        // Set ._label's new text

        this._label.set_label (String (product) + " penguins on the iceberg. " + comment);

    }

});

]]>

    
Souvenez-vous, nous pouvons obtenir la valeur d'une échelle avec la méthode get_value. Ici, nous ne faisons que recalculer le produit des deux valeurs après qu'une des deux échelles a bougé, ajouter un message stupide en fonction du nombre de pingouins restant et modifier le texte de l'étiquette avec le nouveau nombre et le message.

// Run the application

let app = new ScaleExample ();

app.application.run (ARGV);

]]>

    
Enfin, nous créons un nouvel exemple de la classe ScaleExemple et démarrons l'application.

  </section>

  <section id="complete">

    <title>Exemple complet de code</title>

#!/usr/bin/gjs

imports.gi.versions.Gtk = '3.0';

const Gio = imports.gi.Gio;

const Gtk = imports.gi.Gtk;

class ScaleExample {

    // Create the application itself

    constructor() {

        this.application = new Gtk.Application({

            application_id: 'org.example.jsscale'

        });

        // Connect 'activate' and 'startup' signals to the callback functions

        this.application.connect('activate', this._onActivate.bind(this));

        this.application.connect('startup', this._onStartup.bind(this));

    }

    // Callback function for 'activate' signal presents window when active

    _onActivate() {

        this._window.present();

    }

    // Callback function for 'startup' signal builds the UI

    _onStartup() {

        this._buildUI();

    }

    // Build the application's UI

    _buildUI() {

        // Create the application window

        this._window = new Gtk.ApplicationWindow({

            application: this.application,

            window_position: Gtk.WindowPosition.CENTER,

            border_width: 20,

            title: "Birds on a Floe"});

        // Create the horizontal scale

        this._hScale = Gtk.Scale.new_with_range (Gtk.Orientation.HORIZONTAL, 0.0, 100.0, 5.0);

        this._hScale.set_valign (Gtk.Align.START);

        this._hScale.set_value (50);

        this._hScale.set_digits (0);

        // this._hScale.set_draw_value (false);

        // Create a master adjustment to use for the vertical (or any other) scale

        this._adjustment = new Gtk.Adjustment ({

            value: 95,

            lower: 0,

            upper: 100,

            step_increment: 5,

            page_increment: 10 });

        // Create a vertical scale using the adjustment we just made

        this._vScale = new Gtk.Scale ({

            orientation: Gtk.Orientation.VERTICAL,

            adjustment: this._adjustment,

            digits: 0,

            // draw_value: false,

            margin_left: 10 });

        // Create the label that shows the product of the two values

        this._product = (this._hScale.get_value() * this._vScale.get_value());

        this._label = new Gtk.Label ({

            label: (String(this._product) + " penguins on the iceberg."),

            height_request: 200,

            width_request: 200,

            wrap: true});

        // Connect the two scales to functions which recalculate the label

        this._hScale.connect ("value-changed", this._recalc.bind(this));

        this._vScale.connect ("value-changed", this._recalc.bind(this));

        // Create a grid to arrange things in

        this._UIGrid = new Gtk.Grid ({

            halign: Gtk.Align.CENTER,

            valign: Gtk.Align.CENTER,

            margin_top: 20,

            margin_left: 20});

        // Attach everything to the grid

        this._UIGrid.attach (this._label, 0, 0, 1, 1);

        this._UIGrid.attach (this._hScale, 0, 1, 1, 1);

        this._UIGrid.attach (this._vScale, 1, 0, 1, 1);

        // Add the grid to the window

        this._window.add (this._UIGrid);

        // Show the window and all child widgets

        this._window.show_all();

    }

    _recalc() {

        // Figure out what the product of the two scales' values is

        var product = (this._hScale.get_value() * this._vScale.get_value());

        // Create a blank comment line in case there isn't a silly comment to make

        var comment = "";

        // Make a silly comment based on the number of penguins

        if (product > 9000) {

            comment = "It's over 9000!";

        }

        else if (product < 1000 && product > 0) {

            comment = "They're getting lonely.";

        }

        else if (product == 0) {

            comment = "They're all gone ...";

        }

        else comment = "";

        // Set ._label's new text

        this._label.set_label (String (product) + " penguins on the iceberg. " + comment);

    }

};

// Run the application

let app = new ScaleExample ();

app.application.run (ARGV);

  </section>

  <section id="in-depth">

    <title>Documentation approfondie</title>

<list>

  <item>
<link href="http://www.roojs.org/seed/gir-1.2-gtk-3.0/gjs/Gtk.Adjustment.html">Gtk.Adjustment</link>
</item>

  <item>
<link href="http://www.roojs.com/seed/gir-1.2-gtk-3.0/gjs/Gtk.Application.html">Gtk.Application</link>
</item>

  <item>
<link href="http://developer.gnome.org/gtk3/stable/GtkApplicationWindow.html">Gtk.ApplicationWindow</link>
</item>

  <item>
<link href="http://www.roojs.org/seed/gir-1.2-gtk-3.0/gjs/Gtk.Grid.html">Gtk.Grid</link>
</item>

  <item>
<link href="http://www.roojs.org/seed/gir-1.2-gtk-3.0/gjs/Gtk.Label.html">Gtk.Label</link>
</item>

  <item>
<link href="http://www.roojs.org/seed/gir-1.2-gtk-3.0/gjs/Gtk.Scale.html">Gtk.Scale</link>
</item>

</list>

  </section>

</page>