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

  <info>

  <title type="text">TreeView with ListStore (JavaScript)</title>

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

    <link type="seealso" xref="GtkApplicationWindow.js"/>

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

    <link type="seealso" xref="label.js"/>

    <revision version="0.1" date="2012-07-04" status="draft"/>

    <credit type="author copyright">

      <name>Taryn Fox</name>

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

      <years>2012</years>

    </credit>

    <desc>Un élément graphique qui affiche une liste séparée d'éléments</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>TreeView avec ListStore</title>

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

  
Un TreeView est une fenêtre affichant le contenu soit d'un ListStore, soit d'un TreeStore. Un ListStore peut être comparé à une feuille de calcul : une liste « plate », en deux dimensions, contenant des données réparties sur des lignes et dans des colonnes. Alors qu'un TreeStore peut déployer ses branches dans différentes directions, à la manière d'un arbre. Dans cet exemple, nous créons un TreeView qui affiche le contenu d'un ListStore contenant des noms et des numéros de téléphone (fictifs) et nous le paramétrons pour que l'<link xref="label.js">étiquette</link> en bas de la fenêtre affiche plus d'informations sur le nom qui a été cliqué.

  
Un TreeView n'est pas qu'un simple élément graphique, il contient aussi un certain nombre d'autres plus petits :

  <list>

    <item>
Les éléments graphiques TreeViewColumn affichent chaque colonne d'informations contenue dans le ListStore. Chacune d'elle a un nom qui peut être affiché dans l'en-tête de la colonne, comme montré dans la capture d'écran.
</item>

    <item>
Les éléments graphiques CellRenderer sont « empilés » dans chaque TreeViewColumn et contiennent les instructions sur la manière d'afficher chaque « cellule » individuelle ou chaque élément du ListStore. Il en existe beaucoup de types différents, y compris le CellRendererText utilisé ici et le CellRendererPixbuf qui affiche une image « pixel buffer ».
</item>

  </list>

  
Pour finir, nous allons utiliser un objet nommé TreeIter, qui n'est pas à proprement parler un élément graphique, mais plutôt un curseur invisible qui pointe vers une ligne horizontale du ListStore. Si vous cliquez par exemple sur un nom de la liste téléphonique, cela génère un TreeIter qui pointe vers la ligne sélectionnée et qui sert à indiquer au ListStore quelles informations supplémentaires l'étiquette doit afficher.

  <note>
Le TreeView est probablement l'élément graphique Gtk le plus compliqué, de par le nombre d'éléments qu'il contient et à cause de la façon dont ils sont imbriqués pour travailler ensemble. Prenez le temps d'apprendre et son fonctionnement en faisant des essais, ou alors essayez de commencer par quelque chose de plus facile si vous n'y arrivez pas.
</note>

    <links type="section"/>

  <section id="imports">

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

#!/usr/bin/gjs

const GObject = imports.gi.GObject;

const Gtk = imports.gi.Gtk;

const Lang = imports.lang;

const Pango = imports.gi.Pango;

]]>

    
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 TreeViewExample = new Lang.Class({

    Name: 'TreeView Example with Simple ListStore',

    // Create the application itself

    _init: function() {

        this.application = new Gtk.Application({

            application_id: 'org.example.jstreeviewsimpleliststore'

        });

    // 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 utilisé pour cet exemple va dans la classe TreeViewExample. 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,

            default_height: 250,

            default_width: 100,

            border_width: 20,

            title: "My Phone Book"});

]]>

    
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="liststore">

    <title>Création du ListStore</title>

        // Create the underlying liststore for the phonebook

        this._listStore = new Gtk.ListStore ();

        this._listStore.set_column_types ([

            GObject.TYPE_STRING,

            GObject.TYPE_STRING,

            GObject.TYPE_STRING,

            GObject.TYPE_STRING]);

]]>

    
Créons en premier le ListStore comme nous l'aurions fait pour n'importe quel élément graphique. Appelons ensuite sa méthode set_column_types et passons lui un tableau de types de données GObject (nous aurions pu placer tous les types sur une seule et même ligne, mais pour faciliter la lecture, nous les séparons).

    
Les types de données GObject que vous pouvez utiliser incluent :

    <list>

      <item>
<file>GObject.TYPE_BOOLEAN</file> -- true ou false
</item>

      <item>
<file>GObject.TYPE_FLOAT</file> -- un nombre à virgule flottante
</item>

      <item>
<file>GObject.TYPE_STRING</file> -- une chaîne de caractères (lettres ou chiffres)
</item>

      <item>
<file>gtk.gdk.Pixbuf</file> -- une image
</item>

    </list>

    
Dans ce cas, nous créons un ListStore de quatre colonnes contenant chacune des valeurs de type chaînes de caractères.

    <note>
Pour pouvoir utiliser les types GObject, vous devez placer la ligne <file>const GObject = imports.gi.GObject;</file> au début du code de votre application, comme nous l'avons fait dans cet exemple.
</note>

        // Data to go in the phonebook

        this.phonebook =

        let phonebook =

            [{ name: "Jurg", surname: "Billeter", phone: "555-0123",

                description: "A friendly person."},

             { name: "Johannes", surname: "Schmid", phone: "555-1234",

                description: "Easy phone number to remember."},

             { name: "Julita", surname: "Inca", phone: "555-2345",

                description: "Another friendly person."},

             { name: "Javier", surname: "Jardon", phone: "555-3456",

                description: "Bring fish for his penguins."},

             { name: "Jason", surname: "Clinton", phone: "555-4567",

                description: "His cake's not a lie."},

             { name: "Random J.", surname: "Hacker", phone: "555-5678",

                description: "Very random!"}];

]]>

    
Voici les informations contenues dans le ListStore. C'est un assortiment d'objets, chacun correspondant à une entrée de notre répertoire téléphonique.

    
Notez que le TreeView de la capture d'écran n'affiche pas pour l'instant les données des propriétés « description ». Elles s'afficheront dans l'étiquette du dessous à chaque clic sur une ligne. C'est parce qu'un TreeView et un ListStore sont deux choses bien distinctes et qu'un TreeView peut afficher tout ou une partie du contenu d'un ListStore de différentes façons. Vous pouvez même posséder plusieurs éléments graphiques affichant des éléments d'un même ListStore, comme l'étiquette de notre exemple ou bien encore un second TreeView.

        for (i = 0; i < phonebook.length; i++ ) {

            let contact = phonebook [i];

            this._listStore.set (this._listStore.append(), [0, 1, 2, 3],

                [contact.name, contact.surname, contact.phone, contact.description]);

        }

]]>

    
Cette boucle <file>for</file> place les chaînes de caractères de notre répertoire téléphonique dans notre ListStore dans l'ordre. Pour ce faire, nous passons à la méthode set du ListStore le curseur qui pointe vers la bonne ligne, un tableau qui indique quelles colonnes nous voulons définir et un tableau qui contient les données que nous voulons y mettre.

    
La méthode <file>append</file> du ListStore ajoute une ligne horizontale à celui-ci (au début, il n'y en a pas) et renvoie un TreeIter pointant vers cette ligne comme un curseur. Donc, en transmettant <file>this._listStore.append()</file> au ListStore comme propriété, nous créons une nouvelle ligne en indiquant en même temps à la méthode <file>set</file> à quelle ligne elle doit attribuer les données.

  </section>

  <section id="treeview">

    <title>Création du TreeView</title>

        // Create the treeview

        this._treeView = new Gtk.TreeView ({

            expand: true,

            model: this._listStore });

]]>

    
Ici, nous créons un élément graphique TreeView de base, qui s'étend à la fois horizontalement et verticalement pour utiliser autant d'espace que nécessaire. Nous le paramétrons pour utiliser le ListStore que nous avons créé comme étant son « modèle » et d'où proviendront les éléments qu'il affichera.

        // Create the columns for the address book

        let firstName = new Gtk.TreeViewColumn ({ title: "First Name" });

        let lastName = new Gtk.TreeViewColumn ({ title: "Last Name" });

        let phone = new Gtk.TreeViewColumn ({ title: "Phone Number" });

]]>

    
Nous créons maintenant chacun des TreeViewColumns vertical qui s'afficheront dans notre TreeView. Comme le montre la capture d'écran, chaque titre se situe respectivement en haut de sa colonne.

        // Create a cell renderer for when bold text is needed

        let bold = new Gtk.CellRendererText ({

            weight: Pango.Weight.BOLD });

        // Create a cell renderer for normal text

        let normal = new Gtk.CellRendererText ();

        // Pack the cell renderers into the columns

        firstName.pack_start (bold, true);

        lastName.pack_start (normal, true);

        phone.pack_start (normal, true);

]]>

    
Ici, nous créons les CellRenderers que nous allons utiliser pour afficher le texte contenu dans notre ListStore et nous les positionnons dans les TreeViewColumns. Chaque CellRendererText est utilisé pour toutes les entrées de cette colonne. Notre CellRendererText normal (normal) ne génère que du texte brut, alors que celui en gras (bold) utilise du texte plus gras. Nous le mettons dans la première en-tête de colonne et nous indiquons aux deux autres d'utiliser des copies du normal. L'argument « true » utilisé comme second paramètre de la méthode <file>pack_start</file> lui indique d'agrandir les cellules quand cela est possible, au lieu de les laisser compactes.

    <note>
<link href="http://www.pygtk.org/docs/pygtk/pango-constants.html">Voici iciune liste</link> d'autres propriétés de texte que vous pouvez utiliser. Pour pouvoir utiliser les constantes Pango, assurez-vous d'ajouter la ligne <file>const Pango = imports.gi.Pango;</file> au début de votre code comme nous l'avons fait.
</note>

        firstName.add_attribute (bold, "text", 0);

        lastName.add_attribute (normal, "text", 1);

        phone.add_attribute (normal, "text", 2);

        // Insert the columns into the treeview

        this._treeView.insert_column (firstName, 0);

        this._treeView.insert_column (lastName, 1);

        this._treeView.insert_column (phone, 2);

]]>

    
Après avoir placé les CellRenderers dans les TreeViewColumns, nous utilisons la méthode <file>add_attribute</file> pour indiquer à chaque colonne d'extraire du modèle le texte pour lequel notre TreeView est programmée ; dans ce cas, le ListStore contenant le répertoire téléphonique.

    <list>

      <item>
Le premier paramètre indique quel CellRenderer nous allons utiliser pour restituer ce que nous extrayons.
</item>

      <item>
Le second paramètre indique le type d'information que nous voulons extraire. Dans ce cas, nous lui indiquons que nous voulons du texte.
</item>

      <item>
Le troisième paramètre indique de quelle colonne du ListStore nous voulons extraire cette information.
</item>

    </list>

    
Après avoir paramétré ceci, nous utilisons la méthode <file>insert_column</file> pour trier le contenu de nos TreeViewColumns. Notre TreeView est à présent terminée.

    <note>
Normalement, vous devriez utiliser une boucle pour initialiser votre TreeView, mais dans cet exemple, nous avons détaillé étape par étape ce qui ce passe afin de mieux comprendre.
</note>

  </section>

  <section id="ui">

    <title>Construction du reste de l'interface utilisateur</title>

        // Create the label that shows details for the name you select

        this._label = new Gtk.Label ({ label: "" });

        // Get which item is selected

        this.selection = this._treeView.get_selection();

        // When something new is selected, call _on_changed

        this.selection.connect ('changed', Lang.bind (this, this._onSelectionChanged));

]]>

    
La méthode <file>get_selection</file> du TreeView retourne un objet appelé un TreeSelection. Un TreeSelection est comme un TreeIter, tout simplement un curseur qui pointe vers une ligne particulière, à la différence que celui-ci pointe vers la ligne qui est marqué visuellement comme sélectionnée.

    
Une fois obtenu le TreeSelection qui va avec notre TreeView, nous lui demandons de nous indiquer vers quelle ligne il pointe quand il est modifié. Nous obtenons cela en connectant le signal <file>changed</file> à la fonction _onSelectionChanged que nous avons programmée. Cette fonction modifie le texte affiché par l'étiquette que nous venons de créer.

        // Create a grid to organize everything in

        this._grid = new Gtk.Grid;

        // Attach the treeview and label to the grid

        this._grid.attach (this._treeView, 0, 0, 1, 1);

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

        // Add the grid to the window

        this._window.add (this._grid);

        // Show the window and all child widgets

        this._window.show_all();

    },

]]>

    
Ceci fait, nous créons une <link xref="grid.js">grille (grid)</link> pour y placer le tout, puis nous l'ajoutons à notre fenêtre et demandons à cette fenêtre de s'afficher avec son contenu.

  </section>

  <section id="function">

    <title>Fonction prenant en charge la modification de la sélection</title>

    _onSelectionChanged: function () {

        // Grab a treeiter pointing to the current selection

        let [ isSelected, model, iter ] = this.selection.get_selected();

        // Set the label to read off the values stored in the current selection

        this._label.set_label ("\n" +

            this._listStore.get_value (iter, 0) + " " +

            this._listStore.get_value (iter, 1) + " " +

            this._listStore.get_value (iter, 2) + "\n" +

            this._listStore.get_value (iter, 3));

    }

});

]]>

    
La ligne de code utilisant l'instruction « let » est quelque peu compliquée, mais c'est néanmoins la meilleure façon d'obtenir un TreeIter qui pointe vers la même ligne que notre TreeSelection. Elle doit créer quelques autres références d'objets, mais le seul qui nous intéresse est l'<file>iter</file>.

    
Ceci fait, nous appelons la fonction <file>set_label</file> de l'étiquette et nous utilisons la fonction <file>get_value</file> du ListStore autant de fois que nécessaire pour la remplir de toutes les données que nous souhaitons y mettre. Ses paramètres sont un TreeIter pointant vers la ligne dont nous voulons extraire les données et la colonne.

    
Ici, nous voulons obtenir les données des quatre colonnes, y compris celles qui sont « masquées » et qui ne font pas partie du TreeView. De cette façon, nous pouvons utiliser notre étiquette pour afficher les chaînes de caractères qui sont trop longues pour tenir dans le TreeView et que nous n'avons pas besoin de voir au premier coup d'œil.

// Run the application

let app = new TreeViewExample ();

app.application.run (ARGV);

]]>

    
Enfin, nous créons une nouvelle instance de la classe TreeViewExample qui est terminée et nous démarrons l'application.

  </section>

  <section id="complete">

    <title>Exemple complet de code</title>

#!/usr/bin/gjs

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

const GObject = imports.gi.GObject;

const Gtk = imports.gi.Gtk;

const Pango = imports.gi.Pango;

class TreeViewExample {

    // Create the application itself

    constructor() {

        this.application = new Gtk.Application({

            application_id: 'org.example.jstreeviewsimpleliststore'

        });

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

            default_height: 250,

            default_width: 100,

            border_width: 20,

            title: "My Phone Book"});

        // Create the underlying liststore for the phonebook

        this._listStore = new Gtk.ListStore ();

        this._listStore.set_column_types ([

            GObject.TYPE_STRING,

            GObject.TYPE_STRING,

            GObject.TYPE_STRING,

            GObject.TYPE_STRING]);

        // Data to go in the phonebook

        let phonebook =

            [{ name: "Jurg", surname: "Billeter", phone: "555-0123",

                description: "A friendly person."},

             { name: "Johannes", surname: "Schmid", phone: "555-1234",

                description: "Easy phone number to remember."},

             { name: "Julita", surname: "Inca", phone: "555-2345",

                description: "Another friendly person."},

             { name: "Javier", surname: "Jardon", phone: "555-3456",

                description: "Bring fish for his penguins."},

             { name: "Jason", surname: "Clinton", phone: "555-4567",

                description: "His cake's not a lie."},

             { name: "Random J.", surname: "Hacker", phone: "555-5678",

                description: "Very random!"}];

        // Put the data in the phonebook

        for (let i = 0; i < phonebook.length; i++ ) {

            let contact = phonebook [i];

            this._listStore.set (this._listStore.append(), [0, 1, 2, 3],

                [contact.name, contact.surname, contact.phone, contact.description]);

        }

        // Create the treeview

        this._treeView = new Gtk.TreeView ({

            expand: true,

            model: this._listStore });

        // Create the columns for the address book

        let firstName = new Gtk.TreeViewColumn ({ title: "First Name" });

        let lastName = new Gtk.TreeViewColumn ({ title: "Last Name" });

        let phone = new Gtk.TreeViewColumn ({ title: "Phone Number" });

        // Create a cell renderer for when bold text is needed

        let bold = new Gtk.CellRendererText ({

            weight: Pango.Weight.BOLD });

        // Create a cell renderer for normal text

        let normal = new Gtk.CellRendererText ();

        // Pack the cell renderers into the columns

        firstName.pack_start (bold, true);

        lastName.pack_start (normal, true);

        phone.pack_start (normal, true);

        // Set each column to pull text from the TreeView's model

        firstName.add_attribute (bold, "text", 0);

        lastName.add_attribute (normal, "text", 1);

        phone.add_attribute (normal, "text", 2);

        // Insert the columns into the treeview

        this._treeView.insert_column (firstName, 0);

        this._treeView.insert_column (lastName, 1);

        this._treeView.insert_column (phone, 2);

        // Create the label that shows details for the name you select

        this._label = new Gtk.Label ({ label: "" });

        // Get which item is selected

        this.selection = this._treeView.get_selection();

        // When something new is selected, call _on_changed

        this.selection.connect ('changed', this._onSelectionChanged.bind(this));

        // Create a grid to organize everything in

        this._grid = new Gtk.Grid;

        // Attach the treeview and label to the grid

        this._grid.attach (this._treeView, 0, 0, 1, 1);

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

        // Add the grid to the window

        this._window.add (this._grid);

        // Show the window and all child widgets

        this._window.show_all();

    }

    _onSelectionChanged() {

        // Grab a treeiter pointing to the current selection

        let [ isSelected, model, iter ] = this.selection.get_selected();

        // Set the label to read off the values stored in the current selection

        this._label.set_label ("\n" +

            this._listStore.get_value (iter, 0) + " " +

            this._listStore.get_value (iter, 1) + " " +

            this._listStore.get_value (iter, 2) + "\n" +

            this._listStore.get_value (iter, 3)

        );

    }

};

// Run the application

let app = new TreeViewExample ();

app.application.run (ARGV);

  </section>

  <section id="in-depth">

    <title>Documentation approfondie</title>

Dans cet exemple, les éléments suivants sont utilisés :

<list>

  <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.CellRendererText.html">Gtk.CellRendererText</link>
</item>

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

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

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

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

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

</list>

  </section>

</page>