13 Menu Widget

There are two ways to create menus: there's the easy way, and there's the hard way. Both have their uses, but you can usually use the Itemfactory (the easy way). The hard way is to create all the menus using the calls directly. The easy way is to use the gtk_item_factory() calls. This is much simpler, but there are advantages and disadvantages to each approach.

The Itemfactory is much easier to use, and to add new menus to, although writing a few wrapper functions to create menus using the manual method could go a long way towards usability. With the Itemfactory, it is not possible to add images or the character '/' to the menus.

13.1 Manual Menu Creation

In the true tradition of teaching, we'll show you the hard way first. There are three widgets that go into making a menubar and submenus:

This is slightly complicated by the fact that menu item widgets are used for two different things. They are both the widgets that are packed into the menu, and the widget that is packed into the menubar, which, when selected, activates the menu. Let's look at the functions that are used to create menus and menubars. This first function is used to create a new menubar.

This rather self explanatory function creates a new menubar. You use gtk_container_add() to pack this into a window, or the box_pack functions to pack it into a box - the same as buttons.

This function returns a pointer to a new menu; it is never actually shown (with gtk_widget_show()), it is just a container for the menu items. I hope this will become more clear when you look at the example below.

The next two calls are used to create menu items that are packed into the menu (and menubar).

These calls are used to create the menu items that are to be displayed. Remember to differentiate between a "menu" as created with gtk_menu_new() and a menu item as created by the gtk_menu_item_new() functions. The menu item will be an actual button with an associated action, whereas a menu will be a container holding menu items.

The gtk_menu_new_with_label() and gtk_menu_new() functions are just as you'd expect after reading about the buttons. One creates a new menu item with a label already packed into it, and the other just creates a blank menu item.

Once you've created a menu item you have to put it into a menu. This is done using the function gtk_menu_append(). In order to capture when the item is selected by the user, we need to connect to the activate signal in the usual way. So, if we wanted to create a standard File menu, with the options Open, Save, and Quit, the code would look something like:

At this point we have our menu. Now we need to create a menubar and a menu item for the File entry, to which we add our menu. The code looks like this:

Now we need to associate the menu with file_item. This is done with the function

So, our example would continue with

All that is left to do is to add the menu to the menubar, which is accomplished using the procedure:

which in our case looks like this:

If we wanted the menu right justified on the menubar, such as help menus often are, we can use the following procedure (again on file_item in the current example) before attaching it to the menubar.

Here is a summary of the steps needed to create a menu bar with menus attached:

• Create a new menu using gtk_menu_new().
• Use multiple calls to gtk_menu_item_new() for each item you wish to have on your menu.
• Use gtk_menu_append() to put each of these new items on to the menu.
• Create a menu item using gtk_menu_item_new(). This will be the root of the menu, the text appearing here will be on the menubar itself.
• Use gtk_menu_item_set_submenu() to attach the menu to the root menu item (the one created in the above step).
• Create a new menubar using gtk_menu_bar_new(). This step only needs to be done once when creating a series of menus on one menu bar.
• Use gtk_menu_bar_append() to put the root menu onto the menubar.

Creating a popup menu is nearly the same. The difference is that the menu is not posted automatically by a menubar, but explicitly by calling the function gtk_menu_popup() from a button-press event, for example. Take these steps:

• Create an event handling function. It needs to have the prototype
      FUNCTION handler( widget : pGtkWidget ; event : pGdkEvent ; data : gpointer ) : gint; cdecl;
  and it will use the event to find out where to pop up the menu.
• In the event handler, if the event is a mouse button press, treat event as a button event (which it is) and use it as shown in the sample code to pass information to gtk_menu_popup().
• Bind that event handler to a widget with
      gtk_signal_connect(GTK_OBJECT(widget), 'event',
          GTK_SIGNAL_FUNC(@handler), menu);
  where widget is the widget you are binding to, handler is the handling function, and menu is a menu created with gtk_menu_new(). This can be a menu which is also posted by a menu bar, as shown in the sample code.

13.2 Manual Menu Example

The following example should help to clarify the descriptions of the previous section. This little screen-shot admittedly doesn't look that exciting, but all the basics are covered (including reacting to a right-click of the mouse). Compile and run the program yourself in order to see more of what it does.

You may also set a menu item to be insensitive and, using an accelerator table, bind keys to menu functions.

13.3 Using ItemFactory

Now that we've shown you creation of menus the hard way, here's how you do it using the gtk_item_factory() calls.

13.4 Item Factory Example

Here is an example using the GTK item factory.