gio:menu-item-new-section (label section)

label -- a string with the section label, or nil
section -- a g:menu-model object with the menu items of the section

The new g:menu-item object.

Creates a new g:menu-item object representing a section. This is a convenience API around the g:menu-item-new and g:menu-item-set-section functions.

The effect of having one menu appear as a section of another is exactly as it sounds: the items from section become a direct part of the menu that the items are added to.

Visual separation is typically displayed between two non-empty sections. If label is not nil then it will be encorporated into this visual indication. This allows for labeled subsections of a menu. As a simple example, consider a typical "Edit" menu from a simple program. It probably contains an "Undo" and "Redo" item, followed by a separator, followed by "Cut", "Copy" and "Paste".

This would be accomplished by creating three g:menu objects. The first would be populated with the "Undo" and "Redo" items, and the second with the "Cut", "Copy" and "Paste" items. The first and second menus would then be added as submenus of the third. In XML format, this would look something like the following:

<menu id='edit-menu'>
  <section>
    <item label='Undo'/>
    <item label='Redo'/>
  </section>
  <section>
    <item label='Cut'/>
    <item label='Copy'/>
    <item label='Paste'/>
  </section>
</menu>    

The following example is exactly equivalent. It is more illustrative of the exact relationship between the menus and items, keeping in mind that the link element defines a new menu that is linked to the containing one. The style of the second example is more verbose and difficult to read, and therefore not recommended except for the purpose of understanding what is really going on.

<menu id='edit-menu'>
  <item>
    <link name='section'>
      <item label='Undo'/>
      <item label='Redo'/>
    </link>
  </item>
  <item>
    <link name='section'>
      <item label='Cut'/>
      <item label='Copy'/>
      <item label='Paste'/>
    </link>
  </item>
</menu>