[gnome-devel-docs] tutorials python: GMenu (also: MenuBar updated)

[Marta Maria Casetti <mmcasetti src gnome org>]

commit 1334656b941c4f235596da934c47e9ca464552c2
Author: Marta Maria Casetti <mmcasetti gmail com>
Date:   Sun Aug 5 16:29:44 2012 +0100

    tutorials python: GMenu (also: MenuBar updated)

 platform-demos/C/gmenu.py.page    |   68 +++++++++++++++++++++++++++++++-----
 platform-demos/C/menubar.py.page  |    4 +-
 platform-demos/C/samples/gmenu.py |   58 +++++++++++++++++++------------
 3 files changed, 95 insertions(+), 35 deletions(-)
---
diff --git a/platform-demos/C/gmenu.py.page b/platform-demos/C/gmenu.py.page
index b3d5a4a..e9e7820 100644
--- a/platform-demos/C/gmenu.py.page
+++ b/platform-demos/C/gmenu.py.page
@@ -13,7 +13,13 @@
       <years>2012</years>
     </credit>
 
-    <desc>A simple implementation of GMenuModel</desc>
+    <credit type="author copyright">
+      <name>Marta Maria Casetti</name>
+      <email>mmcasetti gmail com</email>
+      <years>2012</years>
+    </credit>
+
+    <desc>A simple implementation of GMenu</desc>
   </info>
 
   <title>GMenu</title>
@@ -21,13 +27,55 @@
   <p>A GtkApplication with a simple GMenu and SimpleActions</p>
   <note><p><em style="bold">You need to be running Gtk3.4 or later for this to work</em></p></note>
 
-<code mime="text/x-python" style="numbered">
-<xi:include href="samples/gmenu.py" parse="text"><xi:fallback/></xi:include></code>
-<p>
-  In this sample we used the following:
-</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>
-</list>
+  <links type="section" />
+
+  <section id="code">
+    <title>Code used to generate this example</title>
+    <code mime="text/x-python" style="numbered">
+    <xi:include href="samples/gmenu.py" parse="text"><xi:fallback/></xi:include></code>
+  </section>
+
+  <section id="methods">
+    <title>Useful methods for a GSimpleAction and a GMenu</title>
+
+    <p>Useful methods for a GSimpleAction:</p>
+    <list>
+      <item><p>To create a new action that is <em>stateless</em>, that is, an action that do not retain or depend on a state given by the action itself, use</p>
+      <code>
+action = Gio.SimpleAction.new("name", parameter_type)</code>
+      <p>where <code>"name"</code> is the name of the action and <code>parameter_type</code> is the type of the parameters that the action receives when being activated. This can be <code>None</code>, or <code>GLib.VariantType.new('s')</code> if the parameter is of type <code>str</code>, or instead of <code>'s'</code> a character as described <link href="http://developer.gnome.org/glib/unstable/glib-GVariantType.html";>here</link>. To create a new <em>stateful</em> (i.e. not stateless) action, use</p>
+      <code>
+action = Gio.SimpleAction.new_stateful("name", 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 possiblities see <link href="http://developer.gnome.org/glib/unstable/glib-GVariant.html";>here</link>.</p></item>
+      <item><p><code>set_enabled(True)</code>  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.</p></item>
+      <item><p><code>set_state(state)</code>, where <code>state</code> 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 <code>change_state(state)</code> (where <code>state</code> is as above) to request the change.</p></item>
+    </list>
+
+    <p>Useful methods for a GMenu:</p>
+    <list>
+      <item><p>To insert an item in the menu in position <code>position</code>, use <code>insert(position, label, detailed_action)</code>, where <code>label</code> is the label that will appear in the menu and <code>detailed_action</code> is a string composed of the name of the action to which we prepend the prefix <code>app.</code>. A more detailed discussion of this can be found in <link xref="menubar.py#win-app" />.</p>
+      <p>To append or prepend an item in the menu use respectively <code>append(label, detailed_action)</code> and <code>prepend(label, detailed_action)</code>.</p></item>
+      <item><p>Another way of adding items to the menu is to create them as <code>GMenuItem</code>s and use <code>insert_item(position, item)</code>, <code>append_item(item)</code>, or <code>prepend_item(item)</code>; so for instance we might have:</p>
+      <code>
+about = Gio.MenuItem.new("About", "app.about")
+menu.append_item(about)</code>
+      </item>
+      <item><p>We can also add a whole subsection in a menu using <code>insert_section(position, label, section)</code>, <code>append_section(label, section)</code>, or <code>prepend_section(label, section)</code>, where <code>label</code> is the title of the subsection.</p></item>
+      <item><p>To add a submenu that will expand and collapse, use <code>insert_submenu(position, label, section)</code>, <code>append_submenu(label, section)</code>, or <code>prepend_submenu(label, section)</code>, where <code>label</code> is the title of the subsection.</p></item>
+      <item><p>To remove an item from the menu, use <code>remove(postion)</code>.</p></item>
+      <item><p>To set a label for the menu, use <code>set_label(label)</code>.</p></item>
+    </list>
+
+  </section>
+
+  <section id="references">
+    <title>API References</title>
+    <p>In this sample we used the following:</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>
diff --git a/platform-demos/C/menubar.py.page b/platform-demos/C/menubar.py.page
index a4a2bba..19bea1c 100644
--- a/platform-demos/C/menubar.py.page
+++ b/platform-demos/C/menubar.py.page
@@ -124,11 +124,11 @@ self.add_action(new_action)</code>
     <media type="image" mime="image/png" src="media/menubar_choices.png"/>
     <p>Lines 30 to 80 inclusive of the <link xref="menubar.py#xml-code" /> demonstrate the XML code used to create the UI for <gui>Choices</gui> menu.</p>
 
-    <p>The actions created so far are stateless, that is they do not retain or depend on a state given by the action itself. The actions we need to create for the Choices submenu, on the other hand, are stateful. An example of creation of a stateful action is:</p>
+    <p>The actions created so far are <em>stateless</em>, that is they do not retain or depend on a state given by the action itself. The actions we need to create for the Choices submenu, on the other hand, are <em>stateful</em>. An example of creation of a stateful action is:</p>
     <code>
 shape_action = Gio.SimpleAction.new_stateful("shape", GLib.VariantType.new('s'), GLib.Variant.new_string('line'))</code>
 
-    <p>where the variables of the method are: name, parameter type (in this case, a string), initial state (in this case, 'line')</p>
+    <p>where the variables of the method are: name, parameter type (in this case, a string - see <link href="http://developer.gnome.org/glib/unstable/glib-GVariantType.html";>here</link> for a complete list of character meanings), initial state (in this case, 'line' - in case of a <code>True</code> boolean value it should be <code>Glib.Variant.new_boolean(True)</code>, and so on, see <link href="http://developer.gnome.org/glib/unstable/glib-GVariant.html";>here</link> for a complete list)</p>
 
     <p>After creating the stateful SimpleAction we connect it to the callback function and we add it to the window (or the application, if it is the case), as before:</p>
 
diff --git a/platform-demos/C/samples/gmenu.py b/platform-demos/C/samples/gmenu.py
index 21005ae..c0dc578 100644
--- a/platform-demos/C/samples/gmenu.py
+++ b/platform-demos/C/samples/gmenu.py
@@ -1,4 +1,3 @@
-from gi.repository import GLib
 from gi.repository import Gtk
 from gi.repository import Gio
 import sys
@@ -9,41 +8,54 @@ class MyWindow(Gtk.ApplicationWindow):
 
 class MyApplication(Gtk.Application):
     def __init__(self):
-        Gtk.Application.__init__(self, application_id="org.gtk.example.grid")
+        Gtk.Application.__init__(self)
 
     def do_activate(self):
         win = MyWindow(self)
         win.show_all()
 
-    def new_cb(self, action, parameter):
-        print "This does nothing. It is only a demonstration."
-
-    def about_cb(self, action, parameter):
-        print "No AboutDialog for you. This is only a demonstration"
-
-    def quit_cb(self, action, parameter):
-        self.quit()
-
     def do_startup (self):
-        Gtk.Application.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("About", "app.about")
         menu.append("Quit", "app.quit")
-        self.set_app_menu (menu)
+        # 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)
 
-        new_action = Gio.SimpleAction.new ("new", None)
-        new_action.connect ("activate", self.new_cb)
-        self.add_action (new_action)
+    # callback function for "new"
+    def new_cb(self, action, parameter):
+        print "This does nothing. It is only a demonstration."
 
-        about_action = Gio.SimpleAction.new ("about", None)
-        about_action.connect ("activate", self.about_cb)
-        self.add_action (about_action)
+    # callback function for "about"
+    def about_cb(self, action, parameter):
+        print "No AboutDialog for you. This is only a demonstration."
 
-        quit_action = Gio.SimpleAction.new("quit", None)
-        quit_action.connect("activate", self.quit_cb)
-        self.add_action (quit_action)
+    # callback function for "quit"
+    def quit_cb(self, action, parameter):
+        print "You have quit."
+        self.quit()
 
 app = MyApplication()
 exit_status = app.run(sys.argv)