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

  <info>

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

    <link type="guide" xref="beginner.js#menu-combo-toolbar"/>

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

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

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

    <credit type="author copyright">

      <name>Taryn Fox</name>

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

      <years>2012</years>

    </credit>

    <desc>Un menu déroulant pour texte uniquement</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>ComboBoxText</title>

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

  
Une ComboBox est un menu déroulant. La différence entre une <link xref="combobox.js">ComboBox</link> et une ComboBoxText est que cette dernière ne possède que des options texte de base, alors que la ComboBox utilise un ListStore ou un TreeStore (qui sont en gros des feuilles de calcul) pour afficher des éléments arborescents ou des images à côté de chaque choix.

  <note>
À moins que vous n'ayez besoin des fonctions supplémentaires d'une ComboBox, ou si vous vous sentez à l'aise dans la manipulation des ListStore et TreeStore, il est préférable d'utiliser la simplicité d'une ComboBoxText chaque fois que possible.
</note>

    <links type="section"/>

  <section id="imports">

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

#!/usr/bin/gjs

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

    Name: 'ComboBoxText Example',

    // Create the application itself

    _init: function () {

        this.application = new Gtk.Application ({

            application_id: 'org.example.jscomboboxtext'});

        // 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 windows 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 MessageDialogExample. 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 composants 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,

            title: "Welcome to GNOME",

            default_width: 200,

            border_width: 10 });

]]>

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

    <title>Création de la ComboBoxText</title>

        // Create the combobox

        this._comboBoxText = new Gtk.ComboBoxText();

        // Populate the combobox

        let distros = ["Select distribution", "Fedora", "Mint", "Suse"];

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

            this._comboBoxText.append_text (distros[i]);

        this._comboBoxText.set_active (0);

        // Connect the combobox's 'changed' signal to our callback function

        this._comboBoxText.connect ('changed', Lang.bind (this, this._onComboChanged));

]]>

    
Après avoir créé la ComboBoxText, utilisons la méthode <file>append_text</file> pour lui ajouter des chaînes de texte. Comme les entrées d'un tableau, les chaînes ont chacune un nombre comme identifiant, en commençant par 0. Pour simplifier les choses, créons un tableau pour les entrées de la ComboBoxText et utilisons une boucle pour les ajouter dans l'ordre, comme ici.

    
Après avoir garni la ComboBoxText, définissons sa première entrée pour qu'elle devienne active, nous pouvons ainsi voir la ligne « Select distribution » avant de cliquer dessus. Connectons ensuite son signal <file>changed</file> à la fonction _onComboChanged, pour qu'elle soit appelée à chaque fois que vous faites une nouvelle sélection dans le menu déroulant.

    <note>
Pour ajouter une entrée dans une ComboBoxText, utilisez la méthode <file>insert_text</file>. Pour utiliser une chaîne texte plutôt qu'un identifiant pour chaque entrée se référant à un nombre seul, utilisez les méthodes <file>append</file> et <file>insert</file>. Reportez-vous aux liens au bas de ce tutoriel pour de plus amples informations sur leur utilisation.
</note>

        // Add the combobox to the window

        this._window.add (this._comboBoxText);

        // Show the window and all child widgets

        this._window.show_all();

    },

]]>

    
Enfin, ajoutons la ComboBoxText à la fenêtre et indiquons à la fenêtre de s'afficher avec ses éléments graphiques à l'intérieur.

  </section>

  <section id="function">

    <title>Fonction prenant en charge votre sélection</title>

    _onComboChanged: function () {

        // The responses we'll use for our messagedialog

        let responses = ["",

            "Fedora is a community distro sponsored by Red Hat.",

            "Mint is a popular distro based on Ubuntu.",

            "SUSE is a name shared by two separate distros."];

]]>

    
Nous allons créer une <link xref="messagedialog.js">MessageDialog</link> qui affiche un message en fonction de la distribution sélectionnée. Créons d'abord le tableau des réponses à utiliser. Comme la première chaîne de notre ComboBoxText est justement le message « Select distribution », laissons celle-ci vide.

        // Which combobox item is active?

        let activeItem = this._comboBoxText.get_active();

        // No messagedialog if you chose "Select distribution"

        if (activeItem != 0) {

            this._popUp = new Gtk.MessageDialog ({

                transient_for: this._window,

                modal: true,

                buttons: Gtk.ButtonsType.OK,

                message_type: Gtk.MessageType.INFO,

                text: responses[activeItem]});

            // Connect the OK button to a handler function

            this._popUp.connect ('response', Lang.bind (this, this._onDialogResponse));

            // Show the messagedialog

            this._popUp.show();

        }

    },

]]>

    
Avant d'afficher une MessageDialog, vérifions d'abord que vous n'avez pas choisi le message « Select distribution ». Ensuite, définissons son texte comme étant l'entrée dans le tableau qui correspond à l'entrée active de notre ComboBoxText. Cela se fait avec la méthode <file>get_active</file>, qui renvoie l'identifiant numérique de votre sélection.

    <note>
Il existe d'autres méthodes alternatives : <file>get_active_id</file>, qui renvoie l'identifiant texte assigné par <file>append</file>, et <file>get_active_text</file>, qui renvoie le texte complet de la chaîne sélectionnée.
</note>

    
Une fois la MessageDialog terminée, connectons son signal de retour à la fonction _onDialogResponse et indiquons lui de s'afficher toute seule.

    _onDialogResponse: function () {

        this._popUp.destroy ();

    }

});

]]>

    
Comme le seul bouton de la MessageDialog est le bouton OK, il n'est pas nécessaire de vérifier son response_id pour savoir quel bouton a été cliqué. Tout ce que nous faisons ici est détruire le message surgissant.

// Run the application

let app = new ComboBoxTextExample ();

app.application.run (ARGV);

]]>

    
Enfin, nous créons un nouvel exemple de la classe ComboBoxTextExample terminée 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 Gtk = imports.gi.Gtk;

class ComboBoxTextExample {

    // Create the application itself

    constructor() {

        this.application = new Gtk.Application ({

            application_id: 'org.example.jscomboboxtext'});

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

            title: "Welcome to GNOME",

            default_width: 200,

            border_width: 10 });

        // Create the combobox

        this._comboBoxText = new Gtk.ComboBoxText();

        // Populate the combobox

        let distros = ["Select distribution", "Fedora", "Mint", "Suse"];

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

            this._comboBoxText.append_text (distros[i]);

        this._comboBoxText.set_active (0);

        // Connect the combobox's 'changed' signal to our callback function

        this._comboBoxText.connect ('changed', this._onComboChanged.bind(this));

        // Add the combobox to the window

        this._window.add (this._comboBoxText);

        // Show the window and all child widgets

        this._window.show_all();

    }

    _onComboChanged() {

        // The responses we'll use for our messagedialog

        let responses = ["",

            "Fedora is a community distro sponsored by Red Hat.",

            "Mint is a popular distro based on Ubuntu.",

            "SUSE is a name shared by two separate distros."];

        // Which combobox item is active?

        let activeItem = this._comboBoxText.get_active();

        // No messagedialog if you chose "Select distribution"

        if (activeItem != 0) {

            this._popUp = new Gtk.MessageDialog ({

                transient_for: this._window,

                modal: true,

                buttons: Gtk.ButtonsType.OK,

                message_type: Gtk.MessageType.INFO,

                text: responses[activeItem]});

            // Connect the OK button to a handler function

            this._popUp.connect ('response', this._onDialogResponse.bind(this));

            // Show the messagedialog

            this._popUp.show();

        }

    }

    _onDialogResponse() {

        this._popUp.destroy ();

    }

};

// Run the application

let app = new ComboBoxTextExample ();

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

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

</list>

  </section>

</page>