Pileus Git - ~andy/gtk/blob - docs/reference/gtk/tmpl/gtkmenu.sgml

   1 <!-- ##### SECTION Title ##### -->
   2 GtkMenu
   3
   4 <!-- ##### SECTION Short_Description ##### -->
   5 a drop down menu widget.
   6
   7 <!-- ##### SECTION Long_Description ##### -->
   8 <para>
   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.
  12 </para>
  13
  14 <para>
  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.
  17 </para>
  18
  19 <para>
  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
  22 as well.
  23 </para>
  24
  25 <para>
  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.
  29 </para>
  30
  31 <example>
  32 <title>Connecting the popup signal handler.</title>
  33 <programlisting>
  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));
  37 </programlisting>
  38 </example>
  39
  40 <example>
  41 <title>Signal handler which displays a popup menu.</title>
  42 <programlisting>
  43 static gint
  44 my_popup_handler(GtkWidget *widget, GdkEvent *event)
  45 {
  46   GtkMenu *menu;
  47   GdkEventButton *event_button;
  48
  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);
  52
  53   /* The "widget" is the menu that was supplied when
  54    * gtk_signal_connect_object was called.
  55    */
  56   menu = GTK_MENU (widget);
  57
  58   if (event->type == GDK_BUTTON_PRESS)
  59     {
  60       event_button = (GdkEventButton *) event;
  61       if (event_button->button == 3)
  62         {
  63           gtk_menu_popup (menu, NULL, NULL, NULL, NULL,
  64                           event_button->button, event_button->time);
  65           return TRUE;
  66         }
  67     }
  68
  69   return FALSE;
  70 }
  71 </programlisting>
  72 </example>
  73
  74 <!-- ##### SECTION See_Also ##### -->
  75 <para>
  76
  77 </para>
  78
  79 <!-- ##### STRUCT GtkMenu ##### -->
  80 <para>
  81 The #GtkMenu-struct struct contains private data only, and
  82 should be accessed using the functions below.
  83 </para>
  84
  85
  86 <!-- ##### FUNCTION gtk_menu_new ##### -->
  87 <para>
  88 Creates a new #GtkMenu.
  89 </para>
  90
  91 @Returns: a new #GtkMenu.
  92
  93
  94 <!-- ##### MACRO gtk_menu_append ##### -->
  95 <para>
  96 Adds a new #GtkMenuItem to the end of the menu's item list.
  97 </para>
  98
  99 <!-- # Unused Parameters # -->
 100 @menu: a #GtkMenu.
 101 @child: The #GtkMenuItem to add.
 102 @m:
 103 @c:
 104
 105
 106 <!-- ##### MACRO gtk_menu_prepend ##### -->
 107 <para>
 108 Adds a new #GtkMenuItem to the beginning of the menu's item list.
 109 </para>
 110
 111 <!-- # Unused Parameters # -->
 112 @menu: a #GtkMenu.
 113 @child: The #GtkMenuItem to add.
 114 @menu_child:
 115 @m:
 116 @c:
 117
 118
 119 <!-- ##### MACRO gtk_menu_insert ##### -->
 120 <para>
 121 Adds a new #GtkMenuItem to the menu's item list at the position
 122 indicated by @position.
 123 </para>
 124
 125 <!-- # Unused Parameters # -->
 126 @menu: a #GtkMenu.
 127 @child: The #GtkMenuItem to add.
 128 @pos:
 129 @position: The position in the item list where @child is added.
 130 Positions are numbered from 0 to n-1.
 131
 132
 133 <!-- ##### FUNCTION gtk_menu_reorder_child ##### -->
 134 <para>
 135 Moves a #GtkMenuItem to a new position within the #GtkMenu.
 136 </para>
 137
 138 @menu: a #GtkMenu.
 139 @child: the #GtkMenuItem to move.
 140 @position: the new position to place @child.  Positions are numbered from
 141 0 to n-1.
 142
 143
 144 <!-- ##### FUNCTION gtk_menu_popup ##### -->
 145 <para>
 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.
 151 </para>
 152
 153 @menu: a #GtkMenu.
 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.
 160
 161
 162 <!-- ##### FUNCTION gtk_menu_set_accel_group ##### -->
 163 <para>
 164 Set the #GtkAccelGroup which holds global accelerators for the menu.
 165 This accelerator group needs to also be added to all windows that
 166 this menu is being used in with gtk_window_add_accel_group(), in order
 167 for those windows to support all the accelerators contained in this group.
 168 </para>
 169
 170 @menu: a #GtkMenu.
 171 @accel_group: the #GtkAccelGroup to be associated with the menu.
 172
 173
 174 <!-- ##### FUNCTION gtk_menu_get_accel_group ##### -->
 175 <para>
 176 Gets the #GtkAccelGroup which holds global accelerators for the menu.
 177 See gtk_menu_set_accel_group().
 178 </para>
 179
 180 @menu: a #GtkMenu.
 181 @Returns: the #GtkAccelGroup associated with the menu.
 182
 183
 184 <!-- ##### FUNCTION gtk_menu_set_accel_path ##### -->
 185 <para>
 186
 187 </para>
 188
 189 @menu:
 190 @accel_path:
 191
 192
 193 <!-- ##### FUNCTION gtk_menu_set_title ##### -->
 194 <para>
 195 Sets the title string for the menu.  The title is displayed when the menu
 196 is shown as a tearoff menu.
 197 </para>
 198
 199 @menu: a #GtkMenu.
 200 @title: a string containing the title for the menu.
 201
 202
 203 <!-- ##### FUNCTION gtk_menu_get_tearoff_state ##### -->
 204 <para>
 205
 206 </para>
 207
 208 @menu:
 209 @Returns:
 210
 211
 212 <!-- ##### FUNCTION gtk_menu_get_title ##### -->
 213 <para>
 214
 215 </para>
 216
 217 @menu:
 218 @Returns:
 219
 220
 221 <!-- ##### FUNCTION gtk_menu_popdown ##### -->
 222 <para>
 223 Removes the menu from the screen.
 224 </para>
 225
 226 @menu: a #GtkMenu.
 227
 228
 229 <!-- ##### FUNCTION gtk_menu_reposition ##### -->
 230 <para>
 231 Repositions the menu according to its position function.
 232 </para>
 233
 234 @menu: a #GtkMenu.
 235
 236
 237 <!-- ##### FUNCTION gtk_menu_get_active ##### -->
 238 <para>
 239 Returns the selected menu item from the menu.  This is used by the
 240 #GtkOptionMenu.
 241 </para>
 242
 243 @menu: a #GtkMenu.
 244 @Returns: the #GtkMenuItem that was last selected in the menu.  If a
 245 selection has not yet been made, the first menu item is selected.
 246
 247
 248 <!-- ##### FUNCTION gtk_menu_set_active ##### -->
 249 <para>
 250 Selects the specified menu item within the menu.  This is used by the
 251 #GtkOptionMenu.
 252 </para>
 253
 254 @menu: a #GtkMenu.
 255 @index: the index of the menu item to select.  Index values are from
 256 0 to n-1.
 257
 258
 259 <!-- ##### FUNCTION gtk_menu_set_tearoff_state ##### -->
 260 <para>
 261 Changes the tearoff state of the menu.  A menu is normally displayed
 262 as drop down menu which persists as long as the menu is active.  It can
 263 also be displayed as a tearoff menu which persists until it is closed
 264 or reattached.
 265 </para>
 266
 267 @menu: a #GtkMenu.
 268 @torn_off: If TRUE, menu is displayed as a tearoff menu.
 269
 270
 271 <!-- ##### FUNCTION gtk_menu_attach_to_widget ##### -->
 272 <para>
 273 Attaches the menu to the widget and provides a callback function that will
 274 be invoked when the menu calls gtk_menu_detach() during its destruction.
 275 </para>
 276
 277 @menu: a #GtkMenu.
 278 @attach_widget: the #GtkWidget that the menu will be attached to.
 279 @detacher: the user supplied callback function that will be called when
 280 the menu calls gtk_menu_detach().
 281
 282
 283 <!-- ##### FUNCTION gtk_menu_detach ##### -->
 284 <para>
 285 Detaches the menu from the widget to which it had been attached.
 286 This function will call the callback function, @detacher, provided
 287 when the gtk_menu_attach_to_widget() function was called.
 288 </para>
 289
 290 @menu: a #GtkMenu.
 291
 292
 293 <!-- ##### FUNCTION gtk_menu_get_attach_widget ##### -->
 294 <para>
 295 Returns the #GtkWidget that the menu is attached to.
 296 </para>
 297
 298 @menu: a #GtkMenu.
 299 @Returns: the #GtkWidget that the menu is attached to.
 300
 301
 302 <!-- ##### USER_FUNCTION GtkMenuPositionFunc ##### -->
 303 <para>
 304 A user function supplied when calling gtk_menu_popup() which controls the
 305 positioning of the menu when it is displayed.  The function sets the @x
 306 and @y parameters to the coordinates where the menu is to be drawn.
 307 </para>
 308
 309 @menu: a #GtkMenu.
 310 @x: address of the #gint representing the horizontal position where the
 311 menu shall be drawn.  This is an output parameter.
 312 @y: address of the #gint representing the vertical position where the
 313 menu shall be drawn.  This is an output parameter.
 314 @push_in:
 315 @user_data: the data supplied by the user in the gtk_menu_popup() @data
 316 parameter.
 317
 318
 319 <!-- ##### USER_FUNCTION GtkMenuDetachFunc ##### -->
 320 <para>
 321 A user function supplied when calling gtk_menu_attach_to_widget() which
 322 will be called when the menu is later detached from the widget.
 323 </para>
 324
 325 @attach_widget: the #GtkWidget that the menu is being detached from.
 326 @menu: the #GtkMenu being detached.
 327
 328
 329 <!-- ##### ARG GtkMenu:tearoff-title ##### -->
 330 <para>
 331
 332 </para>
 333