<?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="toolbar_builder.py" xml:lang="fr">
  <info>
    <title type="text">Toolbar created using Glade (Python)</title>
    <link type="guide" xref="beginner.py#menu-combo-toolbar"/>
    <link type="seealso" xref="toolbar.py"/>
    <link type="seealso" xref="grid.py"/>
    <link type="next" xref="menubar.py"/>
    <revision version="0.1" date="2012-07-17" status="draft"/>

    <credit type="author copyright">
      <name>Tiffany Antopolski</name>
      <email its:translate="no">tiffany.antopolski@gmail.com</email>
      <years>2012</years>
    </credit>

    <credit type="author copyright edit">
      <name>Marta Maria Casetti</name>
      <email its:translate="no">mmcasetti@gmail.com</email>
      <years>2012</years>
    </credit>

    <credit type="author copyright">
      <name>Sebastian Pölsterl</name>
      <email its:translate="no">sebp@k-d-w.org</email>
      <years>2011</years>
    </credit>

    <desc>Une barre de boutons et autres éléments graphiques</desc>
  </info>

  <title>Barre d'outils créée avec Glade</title>

  <media type="image" mime="image/png" src="media/toolbar.png"/>
  <p>Cet exemple est identique à <link xref="toolbar.py"/>, sauf que nous utilisons Glade pour créer la barre d'outils dans un fichier XML .ui.</p>

<links type="sections"/>

<section id="glade">
<title>Création de la barre d'outils avec Glade</title>
  <p>Pour créer la barre d'outils avec <link href="http://glade.gnome.org/">Glade</link> :</p>
  <steps>
    <item><p>ouvrez Glade et enregistrez le fichier sous <file>toolbar_builder.ui</file></p>
          <p><media type="image" src="media/glade_ui.png" width="900">
              Screenshot of Glade ui
           </media></p>
    </item>

    <item><p>Au-dessous de <gui>Conteneurs</gui>, dans la partie gauche, faites un clic droit sur une icône de la barre d'outils et sélectionnez <gui>Ajouter un widget comme premier niveau</gui>.</p>
          <p><media type="image" src="media/glade_select_toolbar.png">
           Screenshot of toolbar icon in Glade ui
          </media></p>
    </item>

    <item><p>Dans l'onglet <gui>Général</gui>, dans la partie inférieure droite, modifiez le <gui>Nom</gui> en <input>toolbar</input> et mettez l'option <gui>Afficher la flèche</gui> à <gui>Non</gui>.</p>
          <p><media type="image" src="media/glade_toolbar_general.png">
             Screenshot of General tab
          </media></p>
    </item>

    <item><p>Dans l'onglet <gui>Commun</gui>, définissez <gui>Extension horizontale</gui>à <gui>Oui</gui>.</p>
         <p><media type="image" src="media/glade_toolbar_common.png">
              Screenshot of Common tab
          </media></p>
     </item>

     <item><p>Faites un clic droit sur « toolbar » dans la partie en haut à droite et sélectionnez <gui>Éditer</gui>. La boîte de dialogue <gui>Éditeur de barre d'outils</gui> s'affiche.</p>
         <p><media type="image" src="media/glade_toolbar_edit.png">
             Screenshot of where to right click to edit toolbar.
          </media></p>
   </item>

   <item><p>Nous voulons ajouter 5 ToolButtons (boutons) : « Nouveau », « Ouvrir », « Mode plein écran » et « Quitter le mode plein écran ». Ajoutons d'abord le ToolButton « Nouveau ».</p>
     <steps>
       <item><p>Dans l'onglet <gui>Hiérarchie</gui>, cliquez sur <gui>Ajouter</gui>.</p></item>
       <item><p>Modifiez le nom de l'élément outil (ToolItem) en <input>new_button</input>.</p></item>
       <item><p>Faites défiler vers le bas et définissez <gui>Est important</gui> à <gui>Oui</gui>. Ceci provoque l'affichage de l'étiquette du ToolButton quand vous affichez la barre d'outils.</p></item>
       <item><p>Saisissez le <gui>nom de l'action</gui> : <input>app.new</input>.</p></item>
       <item><p>Modifiez le champ <gui>Étiquette</gui> en <input>New</input> (Nouveau).</p></item>
       <item><p>Dans le menu déroulant « ID prédéfini », sélectionnez <gui>Nouveau</gui>, ou saisissez <input>gtk-new</input>.</p></item>
     </steps>
     <p>Répétez les étapes ci-dessus pour tous les autres ToolButtons en leur attribuant les propriétés suivantes :</p>
  <table frame="all" rules="rows">
    <thead>
      <tr>
        <td><p>Nom</p></td>
        <td><p>Est important</p></td>
        <td><p>Nom de l'action</p></td>
        <td><p>Étiquette</p></td>
        <td><p>ID prédéfini</p></td>
      </tr>
    </thead>
    <tbody>
    <tr>
      <td><p>open_button</p></td>
      <td><p>Oui</p></td>
      <td><p>app.open</p></td>
      <td><p>Open (Ouvrir)</p></td>
      <td><p>gtk-open</p></td>
    </tr>
    <tr>
      <td><p>undo_button</p></td>
      <td><p>Oui</p></td>
      <td><p>win.undo</p></td>
      <td><p>Undo (Annuler)</p></td>
      <td><p>gtk-undo</p></td>
    </tr>
    <tr>
      <td><p>fullscreen_button</p></td>
      <td><p>Oui</p></td>
      <td><p>win.fullscreen</p></td>
      <td><p>Fullscreen (Mode plein écran)</p></td>
      <td><p>gtk-fullscreen</p></td>
    </tr>
    <tr>
      <td><p>leave_fullscreen_button</p></td>
      <td><p>Oui</p></td>
      <td><p>win.fullscreen</p></td>
      <td><p>Leave Fullscreen (Quitter le mode plein écran)</p></td>
      <td><p>gtk-leave-fullscreen</p></td>
    </tr>
    </tbody>
</table>
          <media type="image" src="media/glade_toolbar_editor.png">

          </media>
    </item>

    <item><p>Fermez l'<gui>Éditeur de barre d'outils</gui>.</p>
   </item>

   <item><p>Au lancement du programme, nous ne voulons pas que le ToolButton <gui>Quitter le mode plein écran</gui> s'affiche, car nous ne sommes pas en mode plein écran. Dans l'onglet <gui>Commun</gui>, définissez la propriété <gui>Visible</gui> sur <gui>Non</gui>. Le ToolButton sera toujours présent dans le concepteur d'interface, mais se comportera comme souhaité quand le fichier sera chargé dans le code de votre programme. Notez que la méthode <code>show_all()</code> ne prend pas en compte ce réglage, de sorte qu'il nous faut utiliser <code>show()</code> séparément pour chaque élément.</p>
          <p><media type="image" src="media/glade_visible_no.png">
                 Setting the visible property to No
          </media></p>
   </item>

    <item><p>Enregistrez votre travail et quittez Glade.</p>
   </item>

   <item><p>Vous pouvez voir le fichier XML créé par Glade ci-dessous. C'est la description de la barre d'outils. Au moment de la rédaction de ces lignes, l'option pour ajouter la classe Gtk.STYLE_CLASS_PRIMARY_TOOLBAR dans l'interface de Glade n'existait pas. Mais nous pouvons le faire manuellement. Pour cela, ajoutez le code XML suivant à la ligne 9 du fichier <file>toolbar_builder.ui</file> :</p>
   <code><![CDATA[
  <style>
     <class name="primary-toolbar"/>
  </style>
  ]]></code>
  <p>Le programme fonctionnera malgré tout correctement si vous ne l'ajoutez pas, mais la barre d'outils que vous obtiendrez sera légèrement différente de celle de la capture d'écran en haut de cette page.</p>
   </item>
</steps>
  <code mime="application/xml" style="numbered">&lt;?xml version="1.0" encoding="UTF-8"?&gt;
&lt;interface&gt;
  &lt;!-- interface-requires gtk+ 3.0 --&gt;
  &lt;object class="GtkToolbar" id="toolbar"&gt;
    &lt;property name="visible"&gt;True&lt;/property&gt;
    &lt;property name="can_focus"&gt;False&lt;/property&gt;
    &lt;property name="hexpand"&gt;True&lt;/property&gt;
    &lt;property name="show_arrow"&gt;False&lt;/property&gt;
    &lt;child&gt;
      &lt;object class="GtkToolButton" id="new_button"&gt;
        &lt;property name="use_action_appearance"&gt;False&lt;/property&gt;
        &lt;property name="visible"&gt;True&lt;/property&gt;
        &lt;property name="can_focus"&gt;False&lt;/property&gt;
        &lt;property name="use_action_appearance"&gt;False&lt;/property&gt;
        &lt;property name="is_important"&gt;True&lt;/property&gt;
        &lt;property name="action_name"&gt;app.new&lt;/property&gt;
        &lt;property name="label" translatable="yes"&gt;New&lt;/property&gt;
        &lt;property name="use_underline"&gt;True&lt;/property&gt;
        &lt;property name="stock_id"&gt;gtk-new&lt;/property&gt;
      &lt;/object&gt;
      &lt;packing&gt;
        &lt;property name="expand"&gt;False&lt;/property&gt;
        &lt;property name="homogeneous"&gt;True&lt;/property&gt;
      &lt;/packing&gt;
    &lt;/child&gt;
    &lt;child&gt;
      &lt;object class="GtkToolButton" id="open_button"&gt;
        &lt;property name="use_action_appearance"&gt;False&lt;/property&gt;
        &lt;property name="visible"&gt;True&lt;/property&gt;
        &lt;property name="can_focus"&gt;False&lt;/property&gt;
        &lt;property name="use_action_appearance"&gt;False&lt;/property&gt;
        &lt;property name="is_important"&gt;True&lt;/property&gt;
        &lt;property name="action_name"&gt;app.open&lt;/property&gt;
        &lt;property name="label" translatable="yes"&gt;Open&lt;/property&gt;
        &lt;property name="use_underline"&gt;True&lt;/property&gt;
        &lt;property name="stock_id"&gt;gtk-open&lt;/property&gt;
      &lt;/object&gt;
      &lt;packing&gt;
        &lt;property name="expand"&gt;False&lt;/property&gt;
        &lt;property name="homogeneous"&gt;True&lt;/property&gt;
      &lt;/packing&gt;
    &lt;/child&gt;
    &lt;child&gt;
      &lt;object class="GtkToolButton" id="undo_button"&gt;
        &lt;property name="use_action_appearance"&gt;False&lt;/property&gt;
        &lt;property name="visible"&gt;True&lt;/property&gt;
        &lt;property name="can_focus"&gt;False&lt;/property&gt;
        &lt;property name="use_action_appearance"&gt;False&lt;/property&gt;
        &lt;property name="is_important"&gt;True&lt;/property&gt;
        &lt;property name="action_name"&gt;win.undo&lt;/property&gt;
        &lt;property name="label" translatable="yes"&gt;Undo&lt;/property&gt;
        &lt;property name="use_underline"&gt;True&lt;/property&gt;
        &lt;property name="stock_id"&gt;gtk-undo&lt;/property&gt;
      &lt;/object&gt;
      &lt;packing&gt;
        &lt;property name="expand"&gt;False&lt;/property&gt;
        &lt;property name="homogeneous"&gt;True&lt;/property&gt;
      &lt;/packing&gt;
    &lt;/child&gt;
    &lt;child&gt;
      &lt;object class="GtkToolButton" id="fullscreen_button"&gt;
        &lt;property name="use_action_appearance"&gt;False&lt;/property&gt;
        &lt;property name="visible"&gt;True&lt;/property&gt;
        &lt;property name="can_focus"&gt;False&lt;/property&gt;
        &lt;property name="use_action_appearance"&gt;False&lt;/property&gt;
        &lt;property name="is_important"&gt;True&lt;/property&gt;
        &lt;property name="action_name"&gt;win.fullscreen&lt;/property&gt;
        &lt;property name="label" translatable="yes"&gt;Fullscreen&lt;/property&gt;
        &lt;property name="use_underline"&gt;True&lt;/property&gt;
        &lt;property name="stock_id"&gt;gtk-fullscreen&lt;/property&gt;
      &lt;/object&gt;
      &lt;packing&gt;
        &lt;property name="expand"&gt;False&lt;/property&gt;
        &lt;property name="homogeneous"&gt;True&lt;/property&gt;
      &lt;/packing&gt;
    &lt;/child&gt;
    &lt;child&gt;
      &lt;object class="GtkToolButton" id="leave_fullscreen_button"&gt;
        &lt;property name="use_action_appearance"&gt;False&lt;/property&gt;
        &lt;property name="can_focus"&gt;False&lt;/property&gt;
        &lt;property name="use_action_appearance"&gt;False&lt;/property&gt;
        &lt;property name="is_important"&gt;True&lt;/property&gt;
        &lt;property name="action_name"&gt;win.fullscreen&lt;/property&gt;
        &lt;property name="label" translatable="yes"&gt;Leave Fullscreen&lt;/property&gt;
        &lt;property name="use_underline"&gt;True&lt;/property&gt;
        &lt;property name="stock_id"&gt;gtk-leave-fullscreen&lt;/property&gt;
      &lt;/object&gt;
      &lt;packing&gt;
        &lt;property name="expand"&gt;False&lt;/property&gt;
        &lt;property name="homogeneous"&gt;True&lt;/property&gt;
      &lt;/packing&gt;
    &lt;/child&gt;
  &lt;/object&gt;
&lt;/interface&gt;
</code>

</section>

<section id="code">
<title>Code utilisé pour générer cet exemple</title>

  <p>Le code ci-dessous ajoute la barre d'outils du fichier que nous venons de finir.</p>
<code mime="text/x-python" style="numbered">from gi.repository import Gtk
from gi.repository import Gdk
from gi.repository import Gio
import sys


class MyWindow(Gtk.ApplicationWindow):

    def __init__(self, app):
        Gtk.Window.__init__(self, title="Toolbar Example", application=app)
        self.set_default_size(400, 200)

        # a grid to attach the toolbar (see below)
        grid = Gtk.Grid()
        self.add(grid)
        # we have to show the grid (and therefore the toolbar) with show(),
        # as show_all() would show also the buttons in the toolbar that we want to
        # be hidden (such as the leave_fullscreen button)
        grid.show()

        # a builder to add the UI designed with Glade to the grid:
        builder = Gtk.Builder()
        # get the file (if it is there)
        try:
            builder.add_from_file("toolbar_builder.ui")
        except:
            print "file not found"
            sys.exit()
        # and attach it to the grid
        grid.attach(builder.get_object("toolbar"), 0, 0, 1, 1)

        # two buttons that will be used later in a method
        self.fullscreen_button = builder.get_object("fullscreen_button")
        self.leave_fullscreen_button = builder.get_object(
            "leave_fullscreen_button")

        # create the actions that control the window, connect their signal to a
        # callback method (see below), add the action to the window:

        # undo
        undo_action = Gio.SimpleAction.new("undo", None)
        undo_action.connect("activate", self.undo_callback)
        self.add_action(undo_action)

        # and fullscreen
        fullscreen_action = Gio.SimpleAction.new("fullscreen", None)
        fullscreen_action.connect("activate", self.fullscreen_callback)
        self.add_action(fullscreen_action)

    # callback for undo
    def undo_callback(self, action, parameter):
        print "You clicked \"Undo\"."

    # callback for fullscreen
    def fullscreen_callback(self, action, parameter):
        # check if the state is the same as Gdk.WindowState.FULLSCREEN, which
        # is a bit flag
        is_fullscreen = self.get_window().get_state(
        ) &amp; Gdk.WindowState.FULLSCREEN != 0
        if is_fullscreen:
            self.unfullscreen()
            self.leave_fullscreen_button.hide()
            self.fullscreen_button.show()
        else:
            self.fullscreen()
            self.fullscreen_button.hide()
            self.leave_fullscreen_button.show()


class MyApplication(Gtk.Application):

    def __init__(self):
        Gtk.Application.__init__(self)

    def do_activate(self):
        win = MyWindow(self)
        # show the window - with show() not show_all() because that would show also
        # the leave_fullscreen button
        win.show()

    def do_startup(self):
        Gtk.Application.do_startup(self)

        # actions that control the application: create, connect their signal to a
        # callback method (see below), add the action to the application

        # new
        new_action = Gio.SimpleAction.new("new", None)
        new_action.connect("activate", self.new_callback)
        app.add_action(new_action)

        # open
        open_action = Gio.SimpleAction.new("open", None)
        open_action.connect("activate", self.open_callback)
        app.add_action(open_action)

    # callback for new
    def new_callback(self, action, parameter):
        print "You clicked \"New\"."

    # callback for open
    def open_callback(self, action, parameter):
        print "You clicked \"Open\"."

app = MyApplication()
exit_status = app.run(sys.argv)
sys.exit(exit_status)
</code>

</section>

<section id="methods">
<title>Méthodes utiles pour Gtk.Builder</title>
<p>Consultez <link xref="toolbar.py"/> pour connaître les méthodes utiles à un élément graphique de barre d'outils</p>

<p>Gtk.Builder construit une interface à partir d'une définition XML d'une interface utilisateur.</p>

<list>
<item><p>La méthode <code>add_from_file(nomdufichier)</code> charge et analyse le fichier donné et le fusionne avec le contenu actuel de Gtk.Builder.</p></item>
<item><p>La méthode <code>add_from_string(chaîne)</code> charge et analyse la chaîne de caractères donnée et la fusionne avec le contenu actuel de Gtk.Builder.</p></item>
<item><p>La méthode <code>add_objects_from_file(nomdufichier, object_ids)</code> est identique à <code>add_from_file()</code>, mais elle ne charge que les objets qui possèdent les identifiants donnés par la liste <code>object_id</code>.</p></item>
<item><p>La méthode <code>add_objects_from_string(nomdufichier, object_ids)</code> est identique à <code>add_from_string()</code>, mais elle ne charge que les objets avec les identifiants donnés par la liste <code>object_id</code>.</p></item>
<item><p>La méthode <code>get_object(object_id)</code> récupère l'élément graphique possédant l'identifiant <code>object_id</code> à partir des objets chargés dans le constructeur.</p></item>
<item><p>La méthode <code>get_objects()</code> renvoie tous les objets chargés.</p></item>
<item><p><code>connect_signals(handler_object)</code> connects the signals to the methods given in the <code>handler_object</code>. This can be any object which contains keys or attributes that are called like the signal handler names given in the interface description, e.g. a class or a dict. In line 39 the signal <code>"activate"</code> from the action <code>undo_action</code> is connected to the callback function <code>undo_callback()</code> using <code><var>action</var>.connect(<var>signal</var>, <var>callback function</var>)</code>. See <link xref="signals-callbacks.py"/> for a more detailed explanation.</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/GtkGrid.html">GtkGrid</link></p></item>
  <item><p><link href="http://developer.gnome.org/gtk3/unstable/GtkBuilder.html">GtkBuilder</link></p></item>
  <item><p><link href="http://developer.gnome.org/gtk3/unstable/GtkWidget.html">GtkWidget</link></p></item>
  <item><p><link href="http://developer.gnome.org/gdk3/unstable/gdk3-Event-Structures.html#GdkEventWindowState">Event Structures</link></p></item>
</list>

</section>

</page>
