>

>

>Menu Widget

>

NAME="GENERATOR"

CONTENT="Modular DocBook HTML Stylesheet Version 1.79">

REL="HOME"

TITLE="GTK+ 2.0 Tutorial"

HREF="book1.html">

REL="PREVIOUS"

TITLE="Notebooks"

HREF="x1450.html">

REL="NEXT"

TITLE="Manual Menu Example"

HREF="x1577.html">

>

CLASS="CHAPTER"

BGCOLOR="#FFFFFF"

TEXT="#000000"

LINK="#0000FF"

VLINK="#840084"

ALINK="#0000FF"

>

CLASS="NAVHEADER"

>

SUMMARY="Header navigation table"

WIDTH="100%"

BORDER="0"

CELLPADDING="0"

CELLSPACING="0"

>

>

COLSPAN="3"

ALIGN="center"

>GTK+ 2.0 Tutorial

>

>

>

WIDTH="10%"

ALIGN="left"

VALIGN="bottom"

>

HREF="x1450.html"

ACCESSKEY="P"

><<< Previous

>

>

WIDTH="80%"

ALIGN="center"

VALIGN="bottom"

>

>

WIDTH="10%"

ALIGN="right"

VALIGN="bottom"

>

HREF="x1577.html"

ACCESSKEY="N"

>Next >>>

>

>

>

>

ALIGN="LEFT"

WIDTH="100%">

>

CLASS="CHAPTER"

>

>

NAME="CH-MENUWIDGET"

>

>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.

>

CLASS="SECT1"

>

CLASS="SECT1"

>

NAME="SEC-MANUALMENUCREATION"

>Manual Menu Creation

>

>

>In the true tradition of teaching, we'll show you the hard way

first. 

CLASS="LITERAL"

>:)

>

>

>There are three widgets that go into making a menubar and submenus:

>

>

>

>

>

>a menu item, which is what the user wants to select, e.g.,

"Save"

>

>

>

>a menu, which acts as a container for the menu items, and

>

>

>

>a menubar, which is a container for each of the individual

menus.

>

>

>

>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.

>

BORDER="0"

BGCOLOR="#E0E0E0"

WIDTH="100%"

>

>

>

CLASS="PROGRAMLISTING"

>GtkWidget *gtk_menu_bar_new( void );

>

>

>

>

>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.

>

BORDER="0"

BGCOLOR="#E0E0E0"

WIDTH="100%"

>

>

>

CLASS="PROGRAMLISTING"

>GtkWidget *gtk_menu_new( void );

>

>

>

>

>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 three calls are used to create menu items that are packed into

the menu (and menubar).

>

BORDER="0"

BGCOLOR="#E0E0E0"

WIDTH="100%"

>

>

>

CLASS="PROGRAMLISTING"

>GtkWidget *gtk_menu_item_new( void );

GtkWidget *gtk_menu_item_new_with_label( const char *label );

GtkWidget *gtk_menu_item_new_with_mnemonic( const char *label );

>

>

>

>

>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_item_new_with_label() and gtk_menu_item_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_shelll_append. In order to capture when

the item is selected by the user, we need to connect to the

CLASS="LITERAL"

>activate

> signal in the usual way. So, if we wanted to create a

standard 

CLASS="LITERAL"

>File

> menu, with the options 

CLASS="LITERAL"

>Open

>, 

CLASS="LITERAL"

>Save

>, and

CLASS="LITERAL"

>Quit

>, the code would look something like:

>

BORDER="0"

BGCOLOR="#E0E0E0"

WIDTH="100%"

>

>

>

CLASS="PROGRAMLISTING"

>    file_menu = gtk_menu_new ();    /* Don't need to show menus */

    /* Create the menu items */

    open_item = gtk_menu_item_new_with_label ("Open");

    save_item = gtk_menu_item_new_with_label ("Save");

    quit_item = gtk_menu_item_new_with_label ("Quit");

    /* Add them to the menu */

    gtk_menu_shell_append (GTK_MENU_SHELL (file_menu), open_item);

    gtk_menu_shell_append (GTK_MENU_SHELL (file_menu), save_item);

    gtk_menu_shell_append (GTK_MENU_SHELL (file_menu), quit_item);

    /* Attach the callback functions to the activate signal */

    g_signal_connect_swapped (open_item, "activate",

                              G_CALLBACK (menuitem_response),

                              (gpointer) "file.open");

    g_signal_connect_swapped (save_item, "activate",

                              G_CALLBACK (menuitem_response),

                              (gpointer) "file.save");

    /* We can attach the Quit menu item to our exit function */

    g_signal_connect_swapped (quit_item, "activate",

                              G_CALLBACK (destroy),

                              (gpointer) "file.quit");

    /* We do need to show menu items */

    gtk_widget_show (open_item);

    gtk_widget_show (save_item);

    gtk_widget_show (quit_item);

>

>

>

>

>At this point we have our menu. Now we need to create a menubar and a

menu item for the 

CLASS="LITERAL"

>File

> entry, to which we add our menu. The code

looks like this:

>

BORDER="0"

BGCOLOR="#E0E0E0"

WIDTH="100%"

>

>

>

CLASS="PROGRAMLISTING"

>    menu_bar = gtk_menu_bar_new ();

    gtk_container_add (GTK_CONTAINER (window), menu_bar);

    gtk_widget_show (menu_bar);

    file_item = gtk_menu_item_new_with_label ("File");

    gtk_widget_show (file_item);

>

>

>

>

>Now we need to associate the menu with 

CLASS="LITERAL"

>file_item

>. This is done

with the function

>

BORDER="0"

BGCOLOR="#E0E0E0"

WIDTH="100%"

>

>

>

CLASS="PROGRAMLISTING"

>void gtk_menu_item_set_submenu( GtkMenuItem *menu_item,

                                GtkWidget   *submenu );

>

>

>

>

>So, our example would continue with

>

BORDER="0"

BGCOLOR="#E0E0E0"

WIDTH="100%"

>

>

>

CLASS="PROGRAMLISTING"

>    gtk_menu_item_set_submenu (GTK_MENU_ITEM (file_item), file_menu);

>

>

>

>

>All that is left to do is to add the menu to the menubar, which is

accomplished using the function

>

BORDER="0"

BGCOLOR="#E0E0E0"

WIDTH="100%"

>

>

>

CLASS="PROGRAMLISTING"

>void gtk_menu_bar_append( GtkMenuBar *menu_bar,

                          GtkWidget  *menu_item );

>

>

>

>

>which in our case looks like this:

>

BORDER="0"

BGCOLOR="#E0E0E0"

WIDTH="100%"

>

>

>

CLASS="PROGRAMLISTING"

>    gtk_menu_bar_append (GTK_MENU_BAR (menu_bar), file_item);

>

>

>

>

>If we wanted the menu right justified on the menubar, such as help

menus often are, we can use the following function (again on

CLASS="LITERAL"

>file_item

> in the current example) before attaching it to the

menubar.

>

BORDER="0"

BGCOLOR="#E0E0E0"

WIDTH="100%"

>

>

>

CLASS="PROGRAMLISTING"

>void gtk_menu_item_right_justify( GtkMenuItem *menu_item );

>

>

>

>

>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. And use gtk_menu_shell_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

>

BORDER="0"

BGCOLOR="#E0E0E0"

WIDTH="90%"

>

>

>

CLASS="PROGRAMLISTING"

>static gboolean handler( GtkWidget *widget,

                         GdkEvent  *event );

>

>

>

>

>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 

CLASS="LITERAL"

>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

>

BORDER="0"

BGCOLOR="#E0E0E0"

WIDTH="90%"

>

>

>

CLASS="PROGRAMLISTING"

>    g_signal_connect_swapped (widget, "event",

                              G_CALLBACK (handler),

                              menu);

>

>

>

>

>where 

CLASS="LITERAL"

>widget

> is the widget you are binding to,

CLASS="LITERAL"

>handler

> is the handling function, and 

CLASS="LITERAL"

>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.

>

>

>

>

>

CLASS="NAVFOOTER"

>

ALIGN="LEFT"

WIDTH="100%">

SUMMARY="Footer navigation table"

WIDTH="100%"

BORDER="0"

CELLPADDING="0"

CELLSPACING="0"

>

>

WIDTH="33%"

ALIGN="left"

VALIGN="top"

>

HREF="x1450.html"

ACCESSKEY="P"

><<< Previous

>

>

WIDTH="34%"

ALIGN="center"

VALIGN="top"

>

HREF="book1.html"

ACCESSKEY="H"

>Home

>

>

WIDTH="33%"

ALIGN="right"

VALIGN="top"

>

HREF="x1577.html"

ACCESSKEY="N"

>Next >>>

>

>

>

>

WIDTH="33%"

ALIGN="left"

VALIGN="top"

>Notebooks

>

WIDTH="34%"

ALIGN="center"

VALIGN="top"

> 

>

WIDTH="33%"

ALIGN="right"

VALIGN="top"

>Manual Menu Example

>

>

>

>

>

>