Next: , Previous: GtkComboBoxEntry, Up: Top

56 GtkMenu

A menu widget

56.1 Overview

A <gtk-menu> is a <gtk-menu-shell> that implements a drop down menu consisting of a list of <gtk-menu-item> objects which can be navigated and activated by the user to perform application functions.

A <gtk-menu> is most commonly dropped down by activating a <gtk-menu-item> in a <gtk-menu-bar> or popped up by activating a <gtk-menu-item> in another <gtk-menu>.

A <gtk-menu> can also be popped up by activating a <gtk-option-menu>. Other composite widgets such as the <gtk-notebook> can pop up a <gtk-menu> as well.

Applications can display a <gtk-menu> as a popup menu by calling the gtk-menu-popup function. The example below shows how an application can pop up a menu when the 3rd mouse button is pressed. 

     
         /* connect our handler which will popup the menu */
         g_signal_connect_swapped (window, "button_press_event",
     	G_CALLBACK (my_popup_handler), menu);

     
     static gint
     my_popup_handler (GtkWidget *widget, GdkEvent *event)
     {
       GtkMenu *menu;
       GdkEventButton *event_button;
     
       g_return_val_if_fail (widget != NULL, FALSE);
       g_return_val_if_fail (GTK_IS_MENU (widget), FALSE);
       g_return_val_if_fail (event != NULL, FALSE);
     
       /* The "widget" is the menu that was supplied when
        * g_signal_connect_swapped() was called.
        */
       menu = GTK_MENU (widget);
     
       if (event->type == GDK_BUTTON_PRESS)
         {
           event_button = (GdkEventButton *) event;
           if (event_button->button == 3)
     	{
     	  gtk_menu_popup (menu, NULL, NULL, NULL, NULL,
     			  event_button->button, event_button->time);
     	  return TRUE;
     	}
         }
     
       return FALSE;
     }

56.2 Usage

— Class: <gtk-menu>

Derives from <gtk-menu-shell>.

This class defines the following slots:

tearoff-state
A boolean that indicates whether the menu is torn-off
tearoff-title
A title that may be displayed by the window manager when this menu is torn-off
— Signal on <gtk-menu>: move-scroll (arg0 <gtk-scroll-type>)
— Function: gtk-menu-new ⇒  (ret <gtk-widget>)

Creates a new <gtk-menu>.

ret
a new <gtk-menu>.
— Function: gtk-menu-set-screen (self <gtk-menu>) (screen <gdk-screen>)
— Method: set-screen

Sets the <gdk-screen> on which the menu will be displayed.

menu
a <gtk-menu>.
screen
a <gdk-screen>, or ‘#f’ if the screen should be determined by the widget the menu is attached to.

Since 2.2

— Function: gtk-menu-reorder-child (self <gtk-menu>) (child <gtk-widget>) (position int)
— Method: reorder-child

Moves a <gtk-menu-item> to a new position within the <gtk-menu>.

menu
a <gtk-menu>.
child
the <gtk-menu-item> to move.
position
the new position to place child. Positions are numbered from 0 to n-1.
— Function: gtk-menu-attach (self <gtk-menu>) (child <gtk-widget>) (left_attach unsigned-int) (right_attach unsigned-int) (top_attach unsigned-int) (bottom_attach unsigned-int)
— Method: attach

Adds a new <gtk-menu-item> to a (table) menu. The number of 'cells' that an item will occupy is specified by left-attach, right-attach, top-attach and bottom-attach. These each represent the leftmost, rightmost, uppermost and lower column and row numbers of the table. (Columns and rows are indexed from zero).

Note that this function is not related to gtk-menu-detach.

menu
a <gtk-menu>.
child
a <gtk-menu-item>.
left-attach
The column number to attach the left side of the item to.
right-attach
The column number to attach the right side of the item to.
top-attach
The row number to attach the top of the item to.
bottom-attach
The row number to attach the bottom of the item to.

Since 2.4

— Function: gtk-menu-popup (self <gtk-menu>) (parent_menu_shell <gtk-widget>) (parent_menu_item <gtk-widget>) (menu_position_func scm) (button unsigned-int) (activate_time unsigned-int32)
— Method: popup

Displays a menu and makes it available for selection. Applications can use this function to display context-sensitive menus, and will typically supply ‘#f’ for the parent-menu-shell, parent-menu-item, func and data parameters. The default menu positioning function will position the menu at the current mouse cursor position.

The button parameter should be the mouse button pressed to initiate the menu popup. If the menu popup was initiated by something other than a mouse button press, such as a mouse button release or a keypress, button should be 0.

The activate-time parameter should be the time stamp of the event that initiated the popup. If such an event is not available, use gtk-get-current-event-time instead.

menu
a <gtk-menu>.
parent-menu-shell
the menu shell containing the triggering menu item, or ‘#f’
parent-menu-item
the menu item whose activation triggered the popup, or ‘#f’
func
a user supplied function used to position the menu, or ‘#f’
data
user supplied data to be passed to func.
button
the mouse button which was pressed to initiate the event.
activate-time
the time at which the activation event occurred.
— Function: gtk-menu-set-accel-group (self <gtk-menu>) (accel_group <gtk-accel-group>)
— Method: set-accel-group

Set the <gtk-accel-group> which holds global accelerators for the menu. This accelerator group needs to also be added to all windows that this menu is being used in with gtk-window-add-accel-group, in order for those windows to support all the accelerators contained in this group.

menu
a <gtk-menu>.
accel-group
the <gtk-accel-group> to be associated with the menu.
— Function: gtk-menu-get-accel-group (self <gtk-menu>) ⇒  (ret <gtk-accel-group>)
— Method: get-accel-group

Gets the <gtk-accel-group> which holds global accelerators for the menu. See gtk-menu-set-accel-group.

menu
a <gtk-menu>.
ret
the <gtk-accel-group> associated with the menu.
— Function: gtk-menu-set-accel-path (self <gtk-menu>) (accel_path mchars)
— Method: set-accel-path

Sets an accelerator path for this menu from which accelerator paths for its immediate children, its menu items, can be constructed. The main purpose of this function is to spare the programmer the inconvenience of having to call gtk-menu-item-set-accel-path on each menu item that should support runtime user changable accelerators. Instead, by just calling gtk-menu-set-accel-path on their parent, each menu item of this menu, that contains a label describing its purpose, automatically gets an accel path assigned. For example, a menu containing menu items "New" and "Exit", will, after ‘gtk_menu_set_accel_path (menu, "<Gnumeric-Sheet>/File");’ has been called, assign its items the accel paths: ‘"<Gnumeric-Sheet>/File/New"’ and ‘"<Gnumeric-Sheet>/File/Exit"’. Assigning accel paths to menu items then enables the user to change their accelerators at runtime. More details about accelerator paths and their default setups can be found at gtk-accel-map-add-entry.

menu
a valid <gtk-menu>
accel-path
a valid accelerator path
— Function: gtk-menu-set-title (self <gtk-menu>) (title mchars)
— Method: set-title

Sets the title string for the menu. The title is displayed when the menu is shown as a tearoff menu. If title is ‘#f’, the menu will see if it is attached to a parent menu item, and if so it will try to use the same text as that menu item's label.

menu
a <gtk-menu>
title
a string containing the title for the menu.
— Function: gtk-menu-get-tearoff-state (self <gtk-menu>) ⇒  (ret bool)
— Method: get-tearoff-state

Returns whether the menu is torn off. See gtk-menu-set-tearoff-state.

menu
a <gtk-menu>
ret
‘#t’ if the menu is currently torn off.
— Function: gtk-menu-get-title (self <gtk-menu>) ⇒  (ret mchars)
— Method: get-title

Returns the title of the menu. See gtk-menu-set-title.

menu
a <gtk-menu>
ret
the title of the menu, or ‘#f’ if the menu has no title set on it. This string is owned by the widget and should not be modified or freed.
— Function: gtk-menu-popdown (self <gtk-menu>)
— Method: popdown

Removes the menu from the screen.

menu
a <gtk-menu>.
— Function: gtk-menu-reposition (self <gtk-menu>)
— Method: reposition

Repositions the menu according to its position function.

menu
a <gtk-menu>.
— Function: gtk-menu-get-active (self <gtk-menu>) ⇒  (ret <gtk-widget>)
— Method: get-active

Returns the selected menu item from the menu. This is used by the <gtk-option-menu>.

menu
a <gtk-menu>.
ret
the <gtk-menu-item> that was last selected in the menu. If a selection has not yet been made, the first menu item is selected.
— Function: gtk-menu-set-active (self <gtk-menu>) (index unsigned-int)
— Method: set-active

Selects the specified menu item within the menu. This is used by the <gtk-option-menu> and should not be used by anyone else.

menu
a <gtk-menu>.
index
the index of the menu item to select. Index values are from 0 to n-1.
— Function: gtk-menu-set-tearoff-state (self <gtk-menu>) (torn_off bool)
— Method: set-tearoff-state

Changes the tearoff state of the menu. A menu is normally displayed as drop down menu which persists as long as the menu is active. It can also be displayed as a tearoff menu which persists until it is closed or reattached.

menu
a <gtk-menu>.
torn-off
If ‘#t’, menu is displayed as a tearoff menu.
— Function: gtk-menu-detach (self <gtk-menu>)
— Method: detach

Detaches the menu from the widget to which it had been attached. This function will call the callback function, detacher, provided when the gtk-menu-attach-to-widget function was called.

menu
a <gtk-menu>.
— Function: gtk-menu-get-attach-widget (self <gtk-menu>) ⇒  (ret <gtk-widget>)
— Method: get-attach-widget

Returns the <gtk-widget> that the menu is attached to.

menu
a <gtk-menu>.
ret
the <gtk-widget> that the menu is attached to.
— Function: gtk-menu-get-for-attach-widget (widget <gtk-widget>) ⇒  (ret glist-of)

Returns a list of the menus which are attached to this widget. This list is owned by GTK+ and must not be modified.

widget
a <gtk-widget>
ret
the list of menus attached to his widget.

Since 2.6

— Function: gtk-menu-set-monitor (self <gtk-menu>) (monitor_num int)
— Method: set-monitor

Informs GTK+ on which monitor a menu should be popped up. See gdk-screen-get-monitor-geometry.

This function should be called from a <gtk-menu-position-func> if the menu should not appear on the same monitor as the pointer. This information can't be reliably inferred from the coordinates returned by a <gtk-menu-position-func>, since, for very long menus, these coordinates may extend beyond the monitor boundaries or even the screen boundaries.

menu
a <gtk-menu>
monitor-num
the number of the monitor on which the menu should be popped up

Since 2.4