GMenu Markup

GMenu Markup — parsing and printing GMenuModel XML

Synopsis

GHashTable *        g_menu_markup_parser_end            (GMarkupParseContext *context);
GMenu *             g_menu_markup_parser_end_menu       (GMarkupParseContext *context);
void                g_menu_markup_parser_start          (GMarkupParseContext *context,
                                                         const gchar *domain,
                                                         GHashTable *objects);
void                g_menu_markup_parser_start_menu     (GMarkupParseContext *context,
                                                         const gchar *domain,
                                                         GHashTable *objects);
void                g_menu_markup_print_stderr          (GMenuModel *model);
GString *           g_menu_markup_print_string          (GString *string,
                                                         GMenuModel *model,
                                                         gint indent,
                                                         gint tabstop);

Description

The functions here allow to instantiate GMenuModels by parsing fragments of an XML document. * The XML format for GMenuModel consists of a toplevel <menu> element, which contains one or more <item> elements. Each <item> element contains <attribute> and <link> elements with a mandatory name attribute. <link> elements have the same content model as <menu>.

Here is the XML for Figure 2, “An example menu”:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
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>

The parser also understands a somewhat less verbose format, in which attributes are encoded as actual XML attributes of <item> elements, and <link> elements are replaced by <section> and <submenu> elements.

Here is how the example looks in this format:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
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>

The parser can obtaing translations for attribute values using gettext. To make use of this, the <menu> element must have a domain attribute which specifies the gettext domain to use, and <attribute> elements can be marked for translation with a translatable="yes" 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:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
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 >

To serialize a GMenuModel into an XML fragment, use g_menu_markup_print_string().

Details

g_menu_markup_parser_end ()

GHashTable *        g_menu_markup_parser_end            (GMarkupParseContext *context);

Stop the parsing of a set of menus and return the GHashTable.

The GHashTable maps strings to GObject instances. The parser only adds GMenu instances to the table, but it may contain other types if a table was provided to g_menu_markup_parser_start().

This call should be matched with g_menu_markup_parser_start(). See that function for more information

context :

a GMarkupParseContext

Returns :

the GHashTable containing the objects. [transfer full]

Since 2.32


g_menu_markup_parser_end_menu ()

GMenu *             g_menu_markup_parser_end_menu       (GMarkupParseContext *context);

Stop the parsing of a menu and return the newly-created GMenu.

This call should be matched with g_menu_markup_parser_start_menu(). See that function for more information

context :

a GMarkupParseContext

Returns :

the newly-created GMenu. [transfer full]

Since 2.32


g_menu_markup_parser_start ()

void                g_menu_markup_parser_start          (GMarkupParseContext *context,
                                                         const gchar *domain,
                                                         GHashTable *objects);

Begin parsing a group of menus in XML form.

If domain is not NULL, it will be used to translate attributes that are marked as translatable, using gettext().

If objects is specified then it must be a GHashTable that was created using g_hash_table_new_full() with g_str_hash(), g_str_equal(), g_free() and g_object_unref(). Any named menus (ie: those with an id='' attribute) that are encountered while parsing will be added to this table. Each toplevel menu must be named.

If objects is NULL then an empty hash table will be created.

This function should be called from the start_element function for the element representing the group containing the menus. In other words, the content inside of this element is expected to be a list of menus.

context :

a GMarkupParseContext

domain :

translation domain for labels, or NULL. [allow-none]

objects :

a GHashTable for the objects, or NULL. [allow-none]

Since 2.32


g_menu_markup_parser_start_menu ()

void                g_menu_markup_parser_start_menu     (GMarkupParseContext *context,
                                                         const gchar *domain,
                                                         GHashTable *objects);

Begin parsing the XML definition of a menu.

This function should be called from the start_element function for the element representing the menu itself. In other words, the content inside of this element is expected to be a list of items.

If domain is not NULL, it will be used to translate attributes that are marked as translatable, using gettext().

If objects is specified then it must be a GHashTable that was created using g_hash_table_new_full() with g_str_hash(), g_str_equal(), g_free() and g_object_unref(). Any named menus (ie: those with an * id='' attribute) that are encountered while parsing will be added to this table.

If objects is NULL then named menus will not be supported.

You should call g_menu_markup_parser_end_menu() from the corresponding end_element function in order to collect the newly parsed menu.

context :

a GMarkupParseContext

domain :

translation domain for labels, or NULL. [allow-none]

objects :

a GHashTable for the objects, or NULL. [allow-none]

Since 2.32


g_menu_markup_print_stderr ()

void                g_menu_markup_print_stderr          (GMenuModel *model);

Print model to stderr for debugging purposes.

This debugging function will be removed in the future.

model :

a GMenuModel

g_menu_markup_print_string ()

GString *           g_menu_markup_print_string          (GString *string,
                                                         GMenuModel *model,
                                                         gint indent,
                                                         gint tabstop);

Print the contents of model to string. Note that you have to provide the containing <menu> element yourself.

string :

a GString

model :

the GMenuModel to print

indent :

the intentation level to start at

tabstop :

how much to indent each level

Returns :

string

Since 2.32