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

  <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>A simple implementation of GMenu</desc>

    <mal:credit xmlns:mal="http://projectmallard.org/1.0/" type="translator copyright">

      <mal:name>Mario Blättermann</mal:name>

      <mal:email>mario.blaettermann@gmail.com</mal:email>

      <mal:years>2011, 2013</mal:years>

    </mal:credit>

  </info>

  <title>GMenu</title>

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

  
A GtkApplication with a simple GMenu and SimpleActions

  <links type="section"/>

  <section id="code">

    <title>Code used to generate this example</title>

    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)

  </section>

  <section id="methods">

    <title>Useful methods for a GSimpleAction and a GMenu</title>

    
In line 33 the signal "activate" from the action new_action (not the menu!) is connected to the callback function new_cb() using action.connect(signal, callback function). See <link xref="signals-callbacks.py"/> for a more detailed explanation.

    
Useful methods for a GSimpleAction:

    <list>

      <item>
To create a new action that is stateless, that is, an action that do not retain or depend on a state given by the action itself, use

action = Gio.SimpleAction.new("name", parameter_type)

      
where "name" is the name of the action and parameter_type is the type of the parameters that the action receives when being activated. This can be None, or GLib.VariantType.new('s') if the parameter is of type str, or instead of 's' a character as described <link href="http://developer.gnome.org/glib/unstable/glib-GVariantType.html">here</link>. To create a new stateful (i.e. not stateless) action, use

action = Gio.SimpleAction.new_stateful("name", parameter_type, initial_state)

      
where initial_state is defined as a GVariant - for instance Glib.Variant.new_string('start'); for a list of possibilities see <link href="http://developer.gnome.org/glib/unstable/glib-GVariant.html">here</link>.
</item>

      <item>
set_enabled(True)  sets the action as enabled; an action must be enabled in order to be activated or in order to have its state changed from outside callers. This should only be called by the implementor of the action. Users of the action should not attempt to modify its enabled flag.
</item>

      <item>
set_state(state), where state is a GVariant, sets the state of the action, updating the 'state' property to the given value. This should only be called by the implementor of the action; users of the action should instead call change_state(state) (where state is as above) to request the change.
</item>

    </list>

    
Useful methods for a GMenu:

    <list>

      <item>
To insert an item in the menu in position position, use insert(position, label, detailed_action), where label is the label that will appear in the menu and detailed_action is a string composed of the name of the action to which we prepend the prefix app.. A more detailed discussion of this can be found in <link xref="menubar.py#win-app"/>.

      
To append or prepend an item in the menu use respectively append(label, detailed_action) and prepend(label, detailed_action).
</item>

      <item>
Another way of adding items to the menu is to create them as GMenuItems and use insert_item(position, item), append_item(item), or prepend_item(item); so for instance we might have:

about = Gio.MenuItem.new("About", "app.about")

menu.append_item(about)

      </item>

      <item>
We can also add a whole subsection in a menu using insert_section(position, label, section), append_section(label, section), or prepend_section(label, section), where label is the title of the subsection.
</item>

      <item>
To add a submenu that will expand and collapse, use insert_submenu(position, label, section), append_submenu(label, section), or prepend_submenu(label, section), where label is the title of the subsection.
</item>

      <item>
To remove an item from the menu, use remove(position).
</item>

      <item>
To set a label for the menu, use set_label(label).
</item>

    </list>

  </section>

  <section id="references">

    <title>API-Referenzen</title>

    
In this sample we used the following:

    <list>

      <item>
<link href="http://developer.gnome.org/gio/unstable/GMenu.html">GMenu</link>
</item>

      <item>
<link href="http://developer.gnome.org/gio/stable/GSimpleAction.html">GSimpleAction</link>
</item>

      <item>
<link href="http://developer.gnome.org/glib/unstable/glib-GVariantType.html">GVariantType</link>
</item>

      <item>
<link href="http://developer.gnome.org/glib/unstable/glib-GVariant.html">GVariant</link>
</item>

    </list>

  </section>

</page>