GNOME.org
 

[glib/wip/menus-rebase2] More docs

commit fd054fc21acf8758ead19274ad532524f64db596
Author: Matthias Clasen <mclasen redhat com>
Date:   Sat Nov 26 01:37:59 2011 -0500

    More docs
    
    Expand the conceptual overview of GMenuModel, and document
    the markup format.

 docs/reference/gio/Makefile.am      |    4 +-
 docs/reference/gio/gio-sections.txt |    1 +
 docs/reference/gio/menu-example.png |  Bin 0 -> 31470 bytes
 docs/reference/gio/menu-model.png   |  Bin 0 -> 20647 bytes
 gio/Makefile.am                     |    3 +
 gio/gmenu.c                         |    1 -
 gio/gmenumarkup.c                   |   46 ++++++++++++++++--
 gio/gmenumodel.c                    |   90 ++++++++++++++++++++++++----------
 gio/menumarkup.dtd                  |   29 +++++++++++
 gio/menumarkup.xml                  |   26 ++++++++++
 gio/menumarkup2.xml                 |   75 +++++++++++++++++++++++++++++
 11 files changed, 242 insertions(+), 33 deletions(-)
---
diff --git a/docs/reference/gio/Makefile.am b/docs/reference/gio/Makefile.am
index 5e4ded8..fc66a52 100644
--- a/docs/reference/gio/Makefile.am
+++ b/docs/reference/gio/Makefile.am
@@ -97,7 +97,9 @@ MKDB_OPTIONS = --output-format=xml --sgml-mode --name-space=g \
 
 # Images to copy into HTML directory
 HTML_IMAGES =			\
-	gvfs-overview.png
+	gvfs-overview.png	\
+	menu-example.png	\
+	menu-model.png
 
 content_files =			\
 	version.xml		\
diff --git a/docs/reference/gio/gio-sections.txt b/docs/reference/gio/gio-sections.txt
index 05eb950..c668270 100644
--- a/docs/reference/gio/gio-sections.txt
+++ b/docs/reference/gio/gio-sections.txt
@@ -3717,4 +3717,5 @@ g_menu_markup_parser_end_menu
 g_menu_markup_parser_start
 g_menu_markup_parser_start_menu
 g_menu_markup_print_stderr
+g_menu_markup_print_string
 </SECTION>
diff --git a/docs/reference/gio/menu-example.png b/docs/reference/gio/menu-example.png
new file mode 100644
index 0000000..91aeccf
Binary files /dev/null and b/docs/reference/gio/menu-example.png differ
diff --git a/docs/reference/gio/menu-model.png b/docs/reference/gio/menu-model.png
new file mode 100644
index 0000000..a4d9f11
Binary files /dev/null and b/docs/reference/gio/menu-model.png differ
diff --git a/gio/Makefile.am b/gio/Makefile.am
index f89cb77..9311f4a 100644
--- a/gio/Makefile.am
+++ b/gio/Makefile.am
@@ -596,6 +596,9 @@ EXTRA_DIST += 			\
 	abicheck.sh		\
 	gio.rc.in		\
 	gschema.dtd		\
+	menumarkup.xml		\
+	menumarkup2.xml		\
+	menumarkup.dtd		\
 	$(NULL)
 
 BUILT_EXTRA_DIST = 		\
diff --git a/gio/gmenu.c b/gio/gmenu.c
index 151162f..d11f7a3 100644
--- a/gio/gmenu.c
+++ b/gio/gmenu.c
@@ -31,7 +31,6 @@
  * @short_description: A simple implementation of GMenuModel
  *
  * #GMenu is a simple implementation of #GMenuModel.
- *
  * You populate a #GMenu by adding #GMenuItem instances to it.
  *
  * There are some convenience functions to allow you to directly
diff --git a/gio/gmenumarkup.c b/gio/gmenumarkup.c
index d198b37..0704b2c 100644
--- a/gio/gmenumarkup.c
+++ b/gio/gmenumarkup.c
@@ -30,12 +30,35 @@
  *
  * The functions here allow to instantiate #GMenuModels by parsing
  * fragments of an XML document.
+ * * The XML format for #GMenuModel consists of a toplevel
+ * <tag class="starttag">menu</tag> element, which contains one or more
+ * <tag class="starttag">item</tag> elements. Each <tag class="starttag">item</tag>
+ * element contains <tag class="starttag">attribute</tag> and <tag class="starttag">link</tag>
+ * elements with a mandatory name attribute.
+ * <tag class="starttag">link</tag> elements have the same content
+ * model as <tag class="starttag">menu</tag>.
  *
- * There is a standard XML format for #GMenuModel that will be
- * documented here.
+ * Here is the XML for <xref linkend="menu-example"/>:
+ * |[<xi:include xmlns:xi="http://www.w3.org/2001/XInclude"; parse="text" href="../../../../gio/menumarkup2.xml"><xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback></xi:include>]|
  *
- * To serialize a #GMenuModel into an XML fragment, use
- * g_menu_model_print_string()
+ * The parser also understands a somewhat less verbose format, in which
+ * attributes are encoded as actual XML attributes of <tag class="starttag">item</tag>
+ * elements, and <tag class="starttag">link</tag> elements are replaced by
+ * <tag class="starttag">section</tag> and <tag class="starttag">submenu</tag> elements.
+ *
+ * Here is how the example looks in this format:
+ * |[<xi:include xmlns:xi="http://www.w3.org/2001/XInclude"; parse="text" href="../../../../gio/menumarkup.xml"><xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback></xi:include>]|
+ *
+ * The parser can obtaing translations for attribute values using gettext.
+ * To make use of this, the <tag class="starttag">menu</tag> element must
+ * have a domain attribute which specifies the gettext domain to use, and
+ * <tag class="starttag">attribute</tag> elements can be marked for translation
+ * with a <literal>translatable="yes"</literal> attribute. It is also possible
+ * to specify message context and translator comments, using the context
+ * and comments attributes.
+ *
+ * The following DTD describes the XML format approximately:
+ * |[<xi:include xmlns:xi="http://www.w3.org/2001/XInclude"; parse="text" href="../../../../gio/menumarkup.dtd"><xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback></xi:include>]|
  *
  * To serialize a #GMenuModel into an XML fragment, use
  * g_menu_markup_print_string().
@@ -567,6 +590,21 @@ indent_string (GString *string,
     g_string_append_c (string, ' ');
 }
 
+/**
+ * g_menu_markup_print_string:
+ * @string: a #GString
+ * @model: the #GMenuModel to print
+ * @indent: the intentation level to start at
+ * @tabstop: how much to indent each level
+ *
+ * Print the contents of @model to @string.
+ * Note that you have to provide the containing
+ * <tag class="starttag">menu</tag> element yourself.
+ *
+ * Returns: @string
+ *
+ * Since: 2.32
+ */
 GString *
 g_menu_markup_print_string (GString    *string,
                             GMenuModel *model,
diff --git a/gio/gmenumodel.c b/gio/gmenumodel.c
index 9fa187e..6e75756 100644
--- a/gio/gmenumodel.c
+++ b/gio/gmenumodel.c
@@ -28,24 +28,64 @@
  * @see_also: #GActionGroup
  *
  * #GMenuModel represents the contents of a menu -- an ordered list of
- * menu items. The items represent actions which can be activated.
- *
- * The conceptual model of menus that #GMenuModel uses is hierarchical.
- * Menus contain items which can be grouped in sections. Items may
+ * menu items. The items are associated with actions, which can be
+ * activated through them. Items can be grouped in sections, and may
  * have submenus associated with them. Both items and sections usually
- * have some representation data associated with them, such as labels
- * or icons. Items also have an associated action. The type of the action
- * (ie whether it is stateful, and what kind of state it has) can
- * influence the representation of the item.
- *
- * FIXME: add a picture here
- *
- * The motivation for having such an abstract representation of an
- * applications controls is that modern user interfaces have a tendency
- * to make them available outside the application. Examples of this
- * include global menus, jumplists, dash boards, etc. To support such
- * uses, it is necessary to 'export' information about actions and their
- * representation in menus, which is exactly what the
+ * have some representation data, such as labels or icons. The type of
+ * the associated action (ie whether it is stateful, and what kind of
+ * state it has) can influence the representation of the item.
+ *
+ * The conceptual model of menus in #GMenuModel is hierarchical:
+ * sections and submenus are again represented by #GMenuModels.
+ * Menus themselves do not define their own roles. Rather, the role
+ * of a particular #GMenuModel is defined by the item that references
+ * it (or, in the case of the 'root' menu, is defined by the context
+ * in which it is used).
+ *
+ * As an example, consider the visible portions of the menu in
+ * <xref linkend="menu-example"/>.
+ *
+ * <figure id="menu-example">
+ *   <title>An example menu</title>
+ *   <graphic fileref="menu-example.png" format="PNG"></graphic>
+ * </figure>
+ *
+ * There are 8 "menus" visible in the screenshot: one menubar, two
+ * submenus and 5 sections:
+ * <itemizedlist>
+ * <listitem>the toplevel menubar (containing 4 items)</listitem>
+ * <listitem>the View submenu (containing 3 sections)</listitem>
+ * <listitem>the first section of the View submenu (containing 2 items)</listitem>
+ * <listitem>the second section of the View submenu (containing 1 item)</listitem>
+ * <listitem>the final section of the View submenu (containing 1 item)</listitem>
+ * <listitem>the Highlight Mode submenu (containing 2 sections)</listitem>
+ * <listitem>the Sources section (containing 2 items)</listitem>
+ * <listitem>the Markup section (containing 2 items)</listitem>
+ * </itemizedlist>
+ *
+ * <xref linkend="menu-model"/> illustrates the conceptual connection between
+ * these 8 menus. Each large block in the figure represents a menu and the
+ * smaller blocks within the large block represent items in that menu. Some
+ * items contain references to other menus.
+ *
+ * <figure id="menu-model">
+ *   <title>A menu model</title>
+ *   <graphic fileref="menu-model.png" format="PNG"></graphic>
+ * </figure>
+ *
+ * Notice that the separators visible in <xref linkend="menu-example"/>
+ * appear nowhere in <xref linkend="menu-model"/>. This is because
+ * separators are not explicitly represented in the menu model. Instead,
+ * a separator is inserted between any two non-empty sections of a menu.
+ * Section items can have labels just like any other item. In that case,
+ * a display system may show a section header instead of a separator.
+ *
+ * The motivation for this abstract model of application controls is
+ * that modern user interfaces tend to make these controls available
+ * outside the application. Examples include global menus, jumplists,
+ * dash boards, etc. To support such uses, it is necessary to 'export'
+ * information about actions and their representation in menus, which
+ * is exactly what the
  * <link linkend="gio-GActionGroup-exporter">GActionGroup exporter</link>
  * and the
  * <link linkend="gio-GMenuModel-exporter">GMenuModel exporter</link>
@@ -53,16 +93,12 @@
  * to make use of the exported information are #GDBusActionGroup and
  * #GMenuProxy.
  *
- * The concrete representation of #GMenuModel is a list of items,
- * see g_menu_model_get_n_items(). Each
- * item has attributes and links, see g_menu_model_iterate_item_attributes()
- * and g_menu_model_iterate_item_links(). Among the attributes are
- * representation data such as a user-visible label, but also the name
- * of the associated action, see #G_MENU_ATTRIBUTE_LABEL and
- * #G_MENU_ATTRIBUTE_ACTION. The links are used to connect an item with
- * another menu model, which can represent either a section or a submenu,
- * see #G_MENU_LINK_SECTION and #G_MENU_LINK_SUBMENU. To get the #GMenuModel
- * that a link points to, use g_menu_link_iter_get_value().
+ * The API of #GMenuModel is very generic, with iterators for the
+ * attributes and links of an item, see g_menu_model_iterate_item_attributes()
+ * and g_menu_model_iterate_item_links(). The 'standard' attributes and
+ * link types have predefined names: %G_MENU_ATTRIBUTE_LABEL,
+ * %G_MENU_ATTRIBUTE_ACTION, %G_MENU_ATTRIBUTE_TARGET, %G_MENU_LINK_SECTION
+ * and %G_MENU_LINK_SUBMENU.
  *
  * FIXME: explain how items are associated with actions.
  *
@@ -390,8 +426,8 @@ g_menu_model_class_init (GMenuModelClass *class)
  *
  * Queries if @model is mutable.
  *
- * An immutable #GMenuModel will never emit the "items-changed" signal.
- * Consumers of the model may make optimisations accordingly.
+ * An immutable #GMenuModel will never emit the #GMenuModel::items-changed
+ * signal. Consumers of the model may make optimisations accordingly.
  *
  * Returns: %TRUE if the model is mutable (ie: "items-changed" may be
  *          emitted).
diff --git a/gio/menumarkup.dtd b/gio/menumarkup.dtd
new file mode 100644
index 0000000..a554910
--- /dev/null
+++ b/gio/menumarkup.dtd
@@ -0,0 +1,29 @@
+<!ELEMENT menu (item|submenu|section)* >
+<!ATTLIST menu id     CDATA #REQUIRED
+               domain #IMPLIED >
+
+<!ELEMENT item (attribute|link)* >
+<!ATTLIST item label CDATA #IMPLIED
+               action CDATA #IMPLIED
+               target CDATA #IMPLIED >
+
+<!ELEMENT attribute (#PCDATA) >
+<!ATTLIST attribute name         CDATA #REQUIRED
+                    type         CDATA #IMPLIED
+                    translatable (yes|no) #IMPLIED
+                    context      CDATA #IMPLIED
+                    comments     CDATA #IMPLIED >
+
+<!ELEMENT link (item*) >
+<!ATTLIST link name CDATA #REQUIRED
+               id   CDATA #IMPLIED >
+
+<!ELEMENT submenu (item|submenu|section)* >
+<!ATTLIST submenu label CDATA #IMPLIED
+                  action CDATA #IMPLIED
+                  target CDATA #IMPLIED >
+
+<!ELEMENT section (item|submenu|section)* >
+<!ATTLIST section label CDATA #IMPLIED
+                  action CDATA #IMPLIED
+                  target CDATA #IMPLIED >
diff --git a/gio/menumarkup.xml b/gio/menumarkup.xml
new file mode 100644
index 0000000..8c0ef30
--- /dev/null
+++ b/gio/menumarkup.xml
@@ -0,0 +1,26 @@
+<menu id='menubar'>
+  <submenu label='File'></submenu>
+  <submenu label='Edit'></submenu>
+  <submenu label='View'>
+    <section>
+      <item label='Toolbar' action='toolbar'/>
+      <item label='Statusbar' action='statusbar'/>
+    </section>
+    <section>
+      <item label='Fullscreen' action='fullscreen'/>
+    </section>
+    <section>
+      <submenu label='Highlight Mode'>
+        <section label='Sources'>
+           <item label='Vala' action='sources' target='vala'/>
+           <item label='Python' action='sources' target='python'/>
+        </section>
+        <section label='Markup'>
+           <item label='asciidoc' action='markup' target='asciidoc'/>
+           <item label='HTML' action='markup' target='html'/>
+        </section>
+      </submenu>
+    </section>
+  </submenu>
+  <submenu label='Help'></submenu>
+</menu>
diff --git a/gio/menumarkup2.xml b/gio/menumarkup2.xml
new file mode 100644
index 0000000..a505e88
--- /dev/null
+++ b/gio/menumarkup2.xml
@@ -0,0 +1,75 @@
+<menu id='menubar'>
+  <item>
+    <attribute name='label'>File</attribute>
+  </item>
+  <item>
+    <attribute name='label'>Edit</attribute>
+  </item>
+  <item>
+    <attribute name='label'>View</attribute>
+    <link name='submenu'>
+      <item>
+        <link name='section'>
+          <item>
+            <attribute name='label'>Toolbar</attribute>
+            <attribute name='action'>toolbar</attribute>
+          </item>
+          <item>
+            <attribute name='label'>Statusbar</attribute>
+            <attribute name='action'>statusbar</attribute>
+          </item>
+        </link>
+      </item>
+      <item>
+        <link name='section'>
+          <item>
+            <attribute name='label'>Fullscreen</attribute>
+            <attribute name='action'>fullscreen</attribute>
+          </item>
+        </link>
+      </item>
+      <item>
+        <link name='section'>
+          <item>
+            <attribute name='label'>Highlight Mode</attribute>
+            <link name='submenu'>
+              <item>
+                <attribute name='label'>Sources</attribute>
+                <link name='section'>
+                  <item>
+                    <attribute name='label'>Vala</attribute>
+                    <attribute name='action'>sources</attribute>
+                    <attribute name='target'>vala</attribute>
+                  </item>
+                  <item>
+                    <attribute name='label'>Python</attribute>
+                    <attribute name='action'>sources</attribute>
+                    <attribute name='target'>python</attribute>
+                  </item>
+                </link>
+              </item>
+              <item>
+                <attribute name='label'>Markup</attribute>
+                <link name='section'>
+                  <item>
+                    <attribute name='label'>asciidoc</attribute>
+                    <attribute name='action'>markup</attribute>
+                    <attribute name='target'>asciidoc</attribute>
+                  </item>
+                  <item>
+                    <attribute name='label'>HTML</attribute>
+                    <attribute name='action'>markup</attribute>
+                    <attribute name='target'>html</attribute>
+                  </item>
+                </link>
+              </item>
+            </link>
+          </item>
+        </link>
+      </item>
+    </link>
+  </item>
+  <item>
+    <attribute name='label'>Help</attribute>
+  </item>
+</menu>
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]