<p>Now let’s analyze the menu above. There are two types of object.</p>
<ul>
<li>“File”, “Edit”, “View”, “Cut”, “Copy”, “Paste” and “Select All”. They are called “menu item” or simply “item”. When the user clicks one of these items, then something will happen.</li>
<li>Menubar, submenu referenced by “Edit” item and two sections. They are called “menu”. Menu is an ordered list of items. They are similar to arrays.</li>
<p>Because GMenuModel is an abstract object, it isn’t instantiatable. Therefore, it doesn’t have any functions to create its instance. If you want to create a menu, use <code>g_menu_new</code> to create a GMenu instance. GMenu inherits all the functions of GMenuModel because of the child object.</p>
<p>GMenuItem is an object directly derived from GObject. GMenuItem and Gmenu (or GMenuModel) don’t have a parent-child relationship.</p>
<pre><code>GObject -- GMenuModel -- GMenu
GObject -- GMenuItem</code></pre>
<p>GMenuItem has attributes. One of the attributes is label. For example, there is a menu item which has “Edit” label in the first diagram in this section. “Cut”, “Copy”, “Paste” and “Select All” are also the labels of the menu items. Other attributes will be explained later.</p>
<p>Some menu items have a link to another GMenu. There are two types of links, submenu and section.</p>
<p>GMenuItem can be inserted, appended or prepended to GMenu. When it is inserted, all of the attributes and link values of the item are copied and used to form a new item within the menu. The GMenuItem itself is not really inserted. Therefore, after the insertion, GMenuItem is useless and it should be freed. The same goes for appending or prepending.</p>
<p>The following code shows how to append GMenuItem to GMenu.</p>
<p>One of the attributes of menu items is an action. This attribute points an action object.</p>
<p>There are two action objects, GSimpleAction and GPropertyAction. GSimpleAction is often used. And it is used with a menu item. Only GSimpleAction is described in this section.</p>
<p>An action corresponds to a menu item will be activated when the menu item is clicked. Then the action emits an activate signal.</p>
<li><code>menu_item_quit</code> is a menu item. It has a label “Quit” and is connected to an action “app.quit”. “app” is a prefix and “quit” is a name of the action. The prefix “app” means that the action belongs to a GtkApplication instance. If the menu is clicked, then the corresponding action “quit” which belongs to the GtkApplication will be activated.</li>
<li><code>act_quit</code> is an action. It has a name “quit”. The function <code>g_simple_action_new</code> creates a stateless action. So, <code>act_quit</code> is stateless. The meaning of stateless will be explained later. The argument <code>NULL</code> means that the action doesn’t have an parameter. Most of the actions are stateless and have no parameter.</li>
<li>The action <code>act_quit</code> is added to the GtkApplication instance with <code>g_action_map_add_action</code>. When <code>act_quit</code> is activated, it will emit “activate” signal.</li>
<li>“activate” signal of the action is connected to the handler <code>quit_activated</code>. So, if the action is activated, the handler will be invoked.</li>
</ol>
<h2id="simple-example">Simple example</h2>
<p>The following is a simple example of menus and actions.</p>
<divclass="sourceCode"id="cb5"><preclass="sourceCode numberSource C numberLines"><codeclass="sourceCode c"><spanid="cb5-1"><ahref="#cb5-1"></a><spanclass="pp">#include </span><spanclass="im"><gtk/gtk.h></span></span>
<li>3-8: <code>quit_activated</code> is a handler of the “activate” signal on the action <code>act_quit</code>. Handlers of the “activate” signal have three parameters.
<oltype="1">
<li>The action instance on which the signal is emitted.</li>
<li>Parameter. In this example it is <code>NULL</code> because the second argument of <code>g_simple_action_new</code> (line 15) is <code>NULL</code>. You don’ t need to care about it.</li>
<li>User data. It is the fourth parameter in the <code>g_signal_connect</code> (line 18) that connects the action and the handler.</li>
</ol></li>
<li>7: A function <code>g_application_quit</code> immediately quits the application.</li>
<li>10-34: <code>app_activate</code> is a handler of “activate” signal on the GtkApplication instance.</li>
<li>12-14: Creates a GtkApplicationWindow <code>win</code>. And sets the title and the default size.</li>
<li>16: Creates GSimpleAction <code>act_quit</code>. It is stateless. The first argument of <code>g_simple_action_new</code> is a name of the action and the second argument is a parameter. If you don’t need the parameter, pass <code>NULL</code>. Therefore, <code>act_quit</code> has a name “quit” and no parameter.</li>
<li>17: Adds the action to GtkApplication <code>app</code>. GtkApplication implements an interface GActionMap and GActionGroup. GtkApplication (GActionMap) can have a group of actions and the actions are added with the function <code>g_action_map_add_action</code>. This function is described in <ahref="https://docs.gtk.org/gio/method.ActionMap.add_action.html">Gio API Reference, g_action_map_add_action</a>.</li>
<li>18: Connects “activate” signal of the action and the handler <code>quit_activated</code>.</li>
<li>20-23: Creates GMenu and GMenuItem instances. <code>menubar</code> and <code>menu</code> are GMenu. <code>menu_item_menu</code> and <code>menu_item_quit</code> are GMenuItem. <code>menu_item_menu</code> has a label “Menu” and no action. <code>menu_item_quit</code> has a label “Quit” and an action “app.quit”. The action “app.quit” is a combination of “app” and “quit”. “app” is a prefix and it means that the action belongs to GtkApplication. “quit” is the name of the action. Therefore, “app.quit” points the action which belongs to the GtkApplication instance and is named “quit”.</li>
<li>24-25: Appends <code>menu_item_quit</code> to <code>menu</code>. As I mentioned before, all the attributes and links are copied and used to form a new item in <code>menu</code>. Therefore after the appending, <code>menu_item_quit</code> is no longer needed. It is freed by <code>g_object_unref</code>.</li>
<li>26: Sets the submenu link in <code>menu_item_menu</code> to point <code>menu</code>.</li>
<li>27-28: Appends <code>menu_item_menu</code> to <code>menubar</code>. Then frees <code>menu_item_menu</code>. GMenu and GMenuItem are connected and finally a menu is made up. The structure of the menu is shown in the diagram below.</li>
<li>30: The menu is inserted to GtkApplication.</li>
<li>31: Sets GtkApplicationWindow to show the menubar.</li>
