1 <!-- ##### SECTION Title ##### -->
4 <!-- ##### SECTION Short_Description ##### -->
5 a drop down menu widget.
7 <!-- ##### SECTION Long_Description ##### -->
9 A #GtkMenu is a #GtkMenuShell that implements a drop down menu consisting of
10 a list of #GtkMenuItem objects which can be navigated and activated by the
11 user to perform application functions.
15 A #GtkMenu is most commonly dropped down by activating a #GtkMenuItem in a
16 #GtkMenuBar or popped up by activating a #GtkMenuItem in another #GtkMenu.
20 A #GtkMenu can also be popped up by activating a #GtkOptionMenu.
21 Other composite widgets such as the #GtkNotebook can pop up a #GtkMenu
26 Applications can display a #GtkMenu as a popup menu by calling the
27 gtk_menu_popup() function. The example below shows how an application
28 can pop up a menu when the 3rd mouse button is pressed.
32 <title>Connecting the popup signal handler.</title>
34 /* connect our handler which will popup the menu */
35 gtk_signal_connect_object(GTK_OBJECT(window), "button_press_event",
36 GTK_SIGNAL_FUNC (my_popup_handler), GTK_OBJECT(menu));
41 <title>Signal handler which displays a popup menu.</title>
44 my_popup_handler(GtkWidget *widget, GdkEvent *event)
47 GdkEventButton *event_button;
49 g_return_val_if_fail (widget != NULL, FALSE);
50 g_return_val_if_fail (GTK_IS_MENU (widget), FALSE);
51 g_return_val_if_fail (event != NULL, FALSE);
53 /* The "widget" is the menu that was supplied when
54 * gtk_signal_connect_object was called.
56 menu = GTK_MENU (widget);
58 if (event->type == GDK_BUTTON_PRESS)
60 event_button = (GdkEventButton *) event;
61 if (event_button->button == 3)
63 gtk_menu_popup (menu, NULL, NULL, NULL, NULL,
64 event_button->button, event_button->time);
74 <!-- ##### SECTION See_Also ##### -->
79 <!-- ##### STRUCT GtkMenu ##### -->
81 The #GtkMenu-struct struct contains private data only, and
82 should be accessed using the functions below.
86 <!-- ##### FUNCTION gtk_menu_new ##### -->
88 Creates a new #GtkMenu.
91 @Returns: a new #GtkMenu.
94 <!-- ##### MACRO gtk_menu_append ##### -->
96 Adds a new #GtkMenuItem to the end of the menu's item list.
100 @child: The #GtkMenuItem to add.
101 <!-- # Unused Parameters # -->
106 <!-- ##### MACRO gtk_menu_prepend ##### -->
108 Adds a new #GtkMenuItem to the beginning of the menu's item list.
112 <!-- # Unused Parameters # -->
116 @child: The #GtkMenuItem to add.
119 <!-- ##### MACRO gtk_menu_insert ##### -->
121 Adds a new #GtkMenuItem to the menu's item list at the position
122 indicated by @position.
126 @child: The #GtkMenuItem to add.
128 <!-- # Unused Parameters # -->
129 @position: The position in the item list where @child is added.
130 Positions are numbered from 0 to n-1.
133 <!-- ##### FUNCTION gtk_menu_reorder_child ##### -->
135 Moves a #GtkMenuItem to a new position within the #GtkMenu.
139 @child: the #GtkMenuItem to move.
140 @position: the new position to place @child. Positions are numbered from
144 <!-- ##### FUNCTION gtk_menu_popup ##### -->
146 Displays a menu and makes it available for selection. Applications can use
147 this function to display context-sensitive menus, and will typically supply
148 NULL for the @parent_menu_shell, @parent_menu_item, @func and @data
149 parameters. The default menu positioning function will position the menu
150 at the current pointer position.
154 @parent_menu_shell: the menu shell containing the triggering menu item.
155 @parent_menu_item: the menu item whose activation triggered the popup.
156 @func: a user supplied function used to position the menu.
157 @data: user supplied data to be passed to @func.
158 @button: the button which was pressed to initiate the event.
159 @activate_time: the time at which the activation event occurred.
162 <!-- ##### FUNCTION gtk_menu_set_accel_group ##### -->
164 Set the #GtkAccelGroup which holds global accelerators for the menu.
168 @accel_group: the #GtkAccelGroup to be associated with the menu.
171 <!-- ##### FUNCTION gtk_menu_get_accel_group ##### -->
180 <!-- ##### FUNCTION gtk_menu_set_title ##### -->
182 Sets the title string for the menu. The title is displayed when the menu
183 is shown as a tearoff menu.
187 @title: a string containing the title for the menu.
190 <!-- ##### FUNCTION gtk_menu_popdown ##### -->
192 Removes the menu from the screen.
198 <!-- ##### FUNCTION gtk_menu_reposition ##### -->
200 Repositions the menu according to its position function.
206 <!-- ##### FUNCTION gtk_menu_get_active ##### -->
208 Returns the selected menu item from the menu. This is used by the
213 @Returns: the #GtkMenuItem that was last selected in the menu. If a
214 selection has not yet been made, the first menu item is selected.
217 <!-- ##### FUNCTION gtk_menu_set_active ##### -->
219 Selects the specified menu item within the menu. This is used by the
224 @index: the index of the menu item to select. Index values are from
228 <!-- ##### FUNCTION gtk_menu_set_tearoff_state ##### -->
230 Changes the tearoff state of the menu. A menu is normally displayed
231 as drop down menu which persists as long as the menu is active. It can
232 also be displayed as a tearoff menu which persists until it is closed
237 @torn_off: If TRUE, menu is displayed as a tearoff menu.
240 <!-- ##### FUNCTION gtk_menu_attach_to_widget ##### -->
242 Attaches the menu to the widget and provides a callback function that will
243 be invoked when the menu calls gtk_menu_detach() during its destruction.
247 @attach_widget: the #GtkWidget that the menu will be attached to.
248 @detacher: the user supplied callback function that will be called when
249 the menu calls gtk_menu_detach().
252 <!-- ##### FUNCTION gtk_menu_detach ##### -->
254 Detaches the menu from the widget to which it had been attached.
255 This function will call the callback function, @detacher, provided
256 when the gtk_menu_attach_to_widget() function was called.
262 <!-- ##### FUNCTION gtk_menu_get_attach_widget ##### -->
264 Returns the #GtkWidget that the menu is attached to.
268 @Returns: the #GtkWidget that the menu is attached to.
271 <!-- ##### USER_FUNCTION GtkMenuPositionFunc ##### -->
273 A user function supplied when calling gtk_menu_popup() which controls the
274 positioning of the menu when it is displayed. The function sets the @x
275 and @y parameters to the coordinates where the menu is to be drawn.
279 @x: address of the #gint representing the horizontal position where the
280 menu shall be drawn. This is an output parameter.
281 @y: address of the #gint representing the vertical position where the
282 menu shall be drawn. This is an output parameter.
284 @user_data: the data supplied by the user in the gtk_menu_popup() @data
288 <!-- ##### USER_FUNCTION GtkMenuDetachFunc ##### -->
290 A user function supplied when calling gtk_menu_attach_to_widget() which
291 will be called when the menu is later detached from the widget.
294 @attach_widget: the #GtkWidget that the menu is being detached from.
295 @menu: the #GtkMenu being detached.
298 <!-- ##### ARG GtkMenu:tearoff-title ##### -->