<?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="gmenu.py" xml:lang="fr">
  <info>
    <title type="text">GMenu (Python)</title>
    <link type="guide" xref="beginner.py#menu-combo-toolbar"/>
    <link type="seealso" xref="signals-callbacks.py"/>
    <link type="next" xref="menubutton.py"/>
    <revision version="0.1" date="2012-04-28" 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">
      <name>Marta Maria Casetti</name>
      <email its:translate="no">mmcasetti@gmail.com</email>
      <years>2012</years>
    </credit>

    <desc>Une implémentation simple de GMenu</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>GMenu</title>
  <media type="image" mime="image/png" src="media/gmenu.py.png"/>
  <p>Une application Gtk avec un GMenu de base et des SimpleActions</p>

  <links type="section"/>

  <section id="code">
    <title>Code utilisé pour générer cet exemple</title>
    <code mime="text/x-python" style="numbered">
    from gi.repository import Gtk
from gi.repository import Gio
import sys


class MyWindow(Gtk.ApplicationWindow):

    def __init__(self, app):
        Gtk.Window.__init__(self, title="GMenu Example", application=app)


class MyApplication(Gtk.Application):

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

    def do_activate(self):
        win = MyWindow(self)
        win.show_all()

    def do_startup(self):
        # start the application
        Gtk.Application.do_startup(self)

        # create a menu
        menu = Gio.Menu()
        # append to the menu three options
        menu.append("New", "app.new")
        menu.append("About", "app.about")
        menu.append("Quit", "app.quit")
        # set the menu as menu of the application
        self.set_app_menu(menu)

        # create an action for the option "new" of the menu
        new_action = Gio.SimpleAction.new("new", None)
        # connect it to the callback function new_cb
        new_action.connect("activate", self.new_cb)
        # add the action to the application
        self.add_action(new_action)

        # option "about"
        about_action = Gio.SimpleAction.new("about", None)
        about_action.connect("activate", self.about_cb)
        self.add_action(about_action)

        # option "quit"
        quit_action = Gio.SimpleAction.new("quit", None)
        quit_action.connect("activate", self.quit_cb)
        self.add_action(quit_action)

    # callback function for "new"
    def new_cb(self, action, parameter):
        print("This does nothing. It is only a demonstration.")

    # callback function for "about"
    def about_cb(self, action, parameter):
        print("No AboutDialog for you. This is only a demonstration.")

    # callback function for "quit"
    def quit_cb(self, action, parameter):
        print("You have quit.")
        self.quit()

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

  <section id="methods">
    <title>Méthodes utiles pour GSimpleAction et GMenu</title>

    <p>In line 33 the signal <code>"activate"</code> from the action <code>new_action</code> (not the menu!) is connected to the callback function <code>new_cb()</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>

    <p>Méthodes utiles pour GSimpleAction :</p>
    <list>
      <item><p>Pour créer une nouvelle action qui est <em>stateless</em>, c-à-d. une action qui ne retient ni ne dépend d'un état définit par l'action elle-même, utilisez</p>
      <code>
action = Gio.SimpleAction.new(« nom », parameter_type)</code>
      <p>où <code>« nom »</code> est le nom de l'action et <code>parameter_type</code> est le type de paramètre que l'action reçoit quand elle est activée. Ce peut être <code>None</code>, ou <code>GLib.VariantType.new('s')</code> si le paramètre est du type <code>str</code>, ou au lieu de <code>'s'</code>, un caractère tel que décrit <link href="http://developer.gnome.org/glib/unstable/glib-GVariantType.html">ici</link>.</p>
      <code>
action = Gio.SimpleAction.new_stateful(« nom », parameter_type, initial_state)</code>
      <p>where <code>initial_state</code> is defined as a GVariant - for instance <code>Glib.Variant.new_string('start')</code>; for a list of possibilities see <link href="http://developer.gnome.org/glib/unstable/glib-GVariant.html">here</link>.</p></item>
      <item><p>La méthode <code>set_enabled(True)</code> définit l'action à enabled ; une action doit être en position enabled pour pouvoir être activée ou pour voir son état modifié par des appels extérieurs. La fonction ne peut être appelée que par l'implémenteur de l'action. Les utilisateurs de l'action ne doivent pas tenter de modifier son drapeau enabled.</p></item>
      <item><p>La fonction <code>set_state(state)</code>, où <code>state</code> est une GVariant, définit l'état de l'action en mettant à jour la propriété « state » à la valeur donnée. Elle ne peut être appelée que par l'implémenteur de l'action ; par contre, les utilisateurs peuvent appeler <code>change_state(state)</code> (où <code>state</code> est une GVariant) pour demander le changement d'état.</p></item>
    </list>

    <p>Méthodes utiles pour un GMenu :</p>
    <list>
      <item><p>Pour insérer un élément dans le menu à la <code>position</code>, utilisez la méthode <code>insert(position, label, detailed_action)</code>, où <code>label</code> est l'étiquette qui s'affiche dans le menu et <code>detailed_action</code> est une chaîne de caractères composée du nom de l'action à laquelle vous ajoutez le préfixe <code>app.</code>. Pour de plus amples détails, consultez <link xref="menubar.py#win-app"/>.</p>
      <p>Pour joindre ou ajouter un élément dans le menu, utilisez respectivement les méthodes <code>append(label, detailed_action)</code> et <code>prepend(label, detailed_action)</code>.</p></item>
      <item><p>Une autre méthode pour ajouter des éléments au menu est de les créer comme des éléments <code>GMenuItem</code> et d'utiliser l'une des fonctions <code>insert_item(position, item)</code>, <code>append_item(item)</code>, ou <code>prepend_item(item)</code> ; par exemple :</p>
      <code>
about = Gio.MenuItem.new("About", "app.about")
menu.append_item(about)</code>
      </item>
      <item><p>Nous pouvons aussi ajouter une sous-section entière dans un menu avec <code>insert_section(position, label, section)</code>, <code>append_section(label, section)</code>, ou <code>prepend_section(label, section)</code>, où <code>label</code> est le titre de la sous-section.</p></item>
      <item><p>Pour ajouter un sous-menu qui va s'étendre et se contracter, utilisez l'une des méthodes <code>insert_submenu(position, label, section)</code>, <code>append_submenu(label, section)</code>, ou bien <code>prepend_submenu(label, section)</code>, où <code>label</code> est le titre du sous-menu.</p></item>
      <item><p>To remove an item from the menu, use <code>remove(position)</code>.</p></item>
      <item><p>Pour définir une étiquette pour le menu, utilisez la méthode <code>set_label(label)</code>.</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/gio/unstable/GMenu.html">GMenu</link></p></item>
      <item><p><link href="http://developer.gnome.org/gio/stable/GSimpleAction.html">GSimpleAction</link></p></item>
      <item><p><link href="http://developer.gnome.org/glib/unstable/glib-GVariantType.html">GVariantType</link></p></item>
      <item><p><link href="http://developer.gnome.org/glib/unstable/glib-GVariant.html">GVariant</link></p></item>
    </list>
  </section>
</page>