<?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.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"/>
<p>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.</p>
<p>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.</p>
<links type="section"/>
<section id="imports">
<title>Bibliothèques à importer</title>
<code mime="application/javascript"><![CDATA[
#!/usr/bin/gjs
const Gio = imports.gi.Gio;
const Gtk = imports.gi.Gtk;
const Lang = imports.lang;
]]></code>
<p>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.</p>
</section>
<section id="applicationwindow">
<title>Création de la fenêtre de l'application</title>
<code mime="application/javascript"><![CDATA[
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 ();
},
]]></code>
<p>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.</p>
<code mime="application/javascript"><![CDATA[
// 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"});
]]></code>
<p>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.</p>
</section>
<section id="button">
<title>Création des échelles</title>
<code mime="application/javascript"><![CDATA[
// 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);
]]></code>
<p>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.</p>
<p>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.</p>
<code mime="application/javascript"><![CDATA[
// 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 });
]]></code>
<p>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.</p>
<code mime="application/javascript"><![CDATA[
// 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 });
]]></code>
<p>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.</p>
<code mime="application/javascript"><![CDATA[
// 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));
]]></code>
<p>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.</p>
<p>Ensuite, connectons les deux signaux « value-changed » à la fonction _recalc, qui recalcule le nombre de pingouins sur l'iceberg et affiche un nouveau message.</p>
<code mime="application/javascript"><![CDATA[
// 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);
]]></code>
<p>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.</p>
<code mime="application/javascript"><![CDATA[
// Add the grid to the window
this._window.add (this._UIGrid);
// Show the window and all child widgets
this._window.show_all();
},
]]></code>
<p>Enfin, nous ajoutons la grille à la fenêtre et indiquons à celle-ci de s'afficher toute seule avec tout son contenu.</p>
</section>
<section id="scales-handler">
<title>Fonction prenant en charge les modifications de valeurs de l'échelle</title>
<code mime="application/javascript"><![CDATA[
_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);
}
});
]]></code>
<p>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.</p>
<code mime="application/javascript"><![CDATA[
// Run the application
let app = new ScaleExample ();
app.application.run (ARGV);
]]></code>
<p>Enfin, nous créons un nouvel exemple de la classe ScaleExemple et démarrons l'application.</p>
</section>
<section id="complete">
<title>Exemple complet de code</title>
<code mime="application/javascript" style="numbered">#!/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);
</code>
</section>
<section id="in-depth">
<title>Documentation approfondie</title>
<list>
<item><p><link href="http://www.roojs.org/seed/gir-1.2-gtk-3.0/gjs/Gtk.Adjustment.html">Gtk.Adjustment</link></p></item>
<item><p><link href="http://www.roojs.com/seed/gir-1.2-gtk-3.0/gjs/Gtk.Application.html">Gtk.Application</link></p></item>
<item><p><link href="http://developer.gnome.org/gtk3/stable/GtkApplicationWindow.html">Gtk.ApplicationWindow</link></p></item>
<item><p><link href="http://www.roojs.org/seed/gir-1.2-gtk-3.0/gjs/Gtk.Grid.html">Gtk.Grid</link></p></item>
<item><p><link href="http://www.roojs.org/seed/gir-1.2-gtk-3.0/gjs/Gtk.Label.html">Gtk.Label</link></p></item>
<item><p><link href="http://www.roojs.org/seed/gir-1.2-gtk-3.0/gjs/Gtk.Scale.html">Gtk.Scale</link></p></item>
</list>
</section>
</page>