GMenu Markup

## 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: `<menu>`, `<submenu>`, `<section>` or `<link>` elements 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: `<submenu>`, `<section>` or `<link>` elements with an id='' attribute) that are encountered while parsing will be added to this table. Note that toplevel `<menu>` is not added to the hash table, even if it has an id attribute.

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