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

   1 <!-- ##### SECTION Title ##### -->
   2 GtkMenu
   3
   4 <!-- ##### SECTION Short_Description ##### -->
   5 A 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     g_signal_connect_swapped (window, "button_press_event",
  36         G_CALLBACK (my_popup_handler), 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    * g_signal_connect_swapped() 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 <!-- ##### SECTION Stability_Level ##### -->
  80
  81
  82 <!-- ##### STRUCT GtkMenu ##### -->
  83 <para>
  84 The #GtkMenu struct contains private data only, and
  85 should be accessed using the functions below.
  86 </para>
  87
  88
  89 <!-- ##### SIGNAL GtkMenu::move-scroll ##### -->
  90 <para>
  91
  92 </para>
  93
  94 @menu: the object which received the signal.
  95 @arg1:
  96
  97 <!-- ##### ARG GtkMenu:tearoff-state ##### -->
  98 <para>
  99
 100 </para>
 101
 102 <!-- ##### ARG GtkMenu:tearoff-title ##### -->
 103 <para>
 104
 105 </para>
 106
 107 <!-- ##### ARG GtkMenu:bottom-attach ##### -->
 108 <para>
 109
 110 </para>
 111
 112 <!-- ##### ARG GtkMenu:left-attach ##### -->
 113 <para>
 114
 115 </para>
 116
 117 <!-- ##### ARG GtkMenu:right-attach ##### -->
 118 <para>
 119
 120 </para>
 121
 122 <!-- ##### ARG GtkMenu:top-attach ##### -->
 123 <para>
 124
 125 </para>
 126
 127 <!-- ##### ARG GtkMenu:double-arrows ##### -->
 128 <para>
 129
 130 </para>
 131
 132 <!-- ##### ARG GtkMenu:horizontal-offset ##### -->
 133 <para>
 134
 135 </para>
 136
 137 <!-- ##### ARG GtkMenu:horizontal-padding ##### -->
 138 <para>
 139
 140 </para>
 141
 142 <!-- ##### ARG GtkMenu:vertical-offset ##### -->
 143 <para>
 144
 145 </para>
 146
 147 <!-- ##### ARG GtkMenu:vertical-padding ##### -->
 148 <para>
 149
 150 </para>
 151
 152 <!-- ##### FUNCTION gtk_menu_new ##### -->
 153 <para>
 154 Creates a new #GtkMenu.
 155 </para>
 156
 157 @Returns: a new #GtkMenu.
 158
 159
 160 <!-- ##### FUNCTION gtk_menu_set_screen ##### -->
 161 <para>
 162
 163 </para>
 164
 165 @menu:
 166 @screen:
 167
 168
 169 <!-- ##### MACRO gtk_menu_append ##### -->
 170 <para>
 171 Adds a new #GtkMenuItem to the end of the menu's item list.
 172 </para>
 173
 174 @menu: a #GtkMenu.
 175 @child: The #GtkMenuItem to add.
 176 @Deprecated: Use gtk_menu_shell_append() instead.
 177
 178
 179 <!-- ##### MACRO gtk_menu_prepend ##### -->
 180 <para>
 181 Adds a new #GtkMenuItem to the beginning of the menu's item list.
 182 </para>
 183
 184 @menu: a #GtkMenu.
 185 @child: The #GtkMenuItem to add.
 186 @Deprecated: Use gtk_menu_shell_prepend() instead.
 187
 188
 189 <!-- ##### MACRO gtk_menu_insert ##### -->
 190 <para>
 191 Adds a new #GtkMenuItem to the menu's item list at the position
 192 indicated by @position.
 193 </para>
 194
 195 @menu: a #GtkMenu.
 196 @child: The #GtkMenuItem to add.
 197 @pos: The position in the item list where @child is added.
 198       Positions are numbered from 0 to n-1.
 199 @Deprecated: Use gtk_menu_shell_insert() instead.
 200
 201
 202 <!-- ##### FUNCTION gtk_menu_reorder_child ##### -->
 203 <para>
 204 Moves a #GtkMenuItem to a new position within the #GtkMenu.
 205 </para>
 206
 207 @menu: a #GtkMenu.
 208 @child: the #GtkMenuItem to move.
 209 @position: the new position to place @child.  Positions are numbered from
 210 0 to n-1.
 211
 212
 213 <!-- ##### FUNCTION gtk_menu_attach ##### -->
 214 <para>
 215
 216 </para>
 217
 218 @menu:
 219 @child:
 220 @left_attach:
 221 @right_attach:
 222 @top_attach:
 223 @bottom_attach:
 224
 225
 226 <!-- ##### FUNCTION gtk_menu_popup ##### -->
 227
 228
 229 @menu:
 230 @parent_menu_shell:
 231 @parent_menu_item:
 232 @func:
 233 @data:
 234 @button:
 235 @activate_time:
 236
 237
 238 <!-- ##### FUNCTION gtk_menu_set_accel_group ##### -->
 239 <para>
 240 Set the #GtkAccelGroup which holds global accelerators for the menu.
 241 This accelerator group needs to also be added to all windows that
 242 this menu is being used in with gtk_window_add_accel_group(), in order
 243 for those windows to support all the accelerators contained in this group.
 244 </para>
 245
 246 @menu: a #GtkMenu.
 247 @accel_group: the #GtkAccelGroup to be associated with the menu.
 248
 249
 250 <!-- ##### FUNCTION gtk_menu_get_accel_group ##### -->
 251 <para>
 252 Gets the #GtkAccelGroup which holds global accelerators for the menu.
 253 See gtk_menu_set_accel_group().
 254 </para>
 255
 256 @menu: a #GtkMenu.
 257 @Returns: the #GtkAccelGroup associated with the menu.
 258
 259
 260 <!-- ##### FUNCTION gtk_menu_set_accel_path ##### -->
 261 <para>
 262
 263 </para>
 264
 265 @menu:
 266 @accel_path:
 267
 268
 269 <!-- ##### FUNCTION gtk_menu_set_title ##### -->
 270 <para>
 271 </para>
 272
 273 @menu:
 274 @title:
 275
 276
 277 <!-- ##### FUNCTION gtk_menu_get_tearoff_state ##### -->
 278 <para>
 279
 280 </para>
 281
 282 @menu:
 283 @Returns:
 284
 285
 286 <!-- ##### FUNCTION gtk_menu_get_title ##### -->
 287 <para>
 288
 289 </para>
 290
 291 @menu:
 292 @Returns:
 293
 294
 295 <!-- ##### FUNCTION gtk_menu_popdown ##### -->
 296 <para>
 297 Removes the menu from the screen.
 298 </para>
 299
 300 @menu: a #GtkMenu.
 301
 302
 303 <!-- ##### FUNCTION gtk_menu_reposition ##### -->
 304 <para>
 305 Repositions the menu according to its position function.
 306 </para>
 307
 308 @menu: a #GtkMenu.
 309
 310
 311 <!-- ##### FUNCTION gtk_menu_get_active ##### -->
 312 <para>
 313 Returns the selected menu item from the menu.  This is used by the
 314 #GtkOptionMenu.
 315 </para>
 316
 317 @menu: a #GtkMenu.
 318 @Returns: the #GtkMenuItem that was last selected in the menu.  If a
 319 selection has not yet been made, the first menu item is selected.
 320
 321
 322 <!-- ##### FUNCTION gtk_menu_set_active ##### -->
 323 <para>
 324 Selects the specified menu item within the menu.  This is used by the
 325 #GtkOptionMenu and should not be used by anyone else.
 326 </para>
 327
 328 @menu: a #GtkMenu.
 329 @index_: the index of the menu item to select.  Index values are from
 330 0 to n-1.
 331
 332
 333 <!-- ##### FUNCTION gtk_menu_set_tearoff_state ##### -->
 334 <para>
 335 Changes the tearoff state of the menu.  A menu is normally displayed
 336 as drop down menu which persists as long as the menu is active.  It can
 337 also be displayed as a tearoff menu which persists until it is closed
 338 or reattached.
 339 </para>
 340
 341 @menu: a #GtkMenu.
 342 @torn_off: If %TRUE, menu is displayed as a tearoff menu.
 343
 344
 345 <!-- ##### FUNCTION gtk_menu_attach_to_widget ##### -->
 346 <para>
 347 Attaches the menu to the widget and provides a callback function that will
 348 be invoked when the menu calls gtk_menu_detach() during its destruction.
 349 </para>
 350
 351 @menu: a #GtkMenu.
 352 @attach_widget: the #GtkWidget that the menu will be attached to.
 353 @detacher: the user supplied callback function that will be called when
 354 the menu calls gtk_menu_detach().
 355
 356
 357 <!-- ##### FUNCTION gtk_menu_detach ##### -->
 358 <para>
 359 Detaches the menu from the widget to which it had been attached.
 360 This function will call the callback function, @detacher, provided
 361 when the gtk_menu_attach_to_widget() function was called.
 362 </para>
 363
 364 @menu: a #GtkMenu.
 365
 366
 367 <!-- ##### FUNCTION gtk_menu_get_attach_widget ##### -->
 368 <para>
 369 Returns the #GtkWidget that the menu is attached to.
 370 </para>
 371
 372 @menu: a #GtkMenu.
 373 @Returns: the #GtkWidget that the menu is attached to.
 374
 375
 376 <!-- ##### FUNCTION gtk_menu_get_for_attach_widget ##### -->
 377 <para>
 378
 379 </para>
 380
 381 @widget:
 382 @Returns:
 383
 384
 385 <!-- ##### USER_FUNCTION GtkMenuPositionFunc ##### -->
 386 <para>
 387 A user function supplied when calling gtk_menu_popup() which controls the
 388 positioning of the menu when it is displayed.  The function sets the @x
 389 and @y parameters to the coordinates where the menu is to be drawn.
 390 </para>
 391
 392 @menu: a #GtkMenu.
 393 @x: address of the #gint representing the horizontal position where the
 394 menu shall be drawn.  This is an output parameter.
 395 @y: address of the #gint representing the vertical position where the
 396 menu shall be drawn.  This is an output parameter.
 397 @push_in: whether the first menu item should be offset (pushed in) to be
 398           aligned with the menu popup position (only useful for GtkOptionMenu).
 399 @user_data: the data supplied by the user in the gtk_menu_popup() @data
 400 parameter.
 401
 402
 403 <!-- ##### USER_FUNCTION GtkMenuDetachFunc ##### -->
 404 <para>
 405 A user function supplied when calling gtk_menu_attach_to_widget() which
 406 will be called when the menu is later detached from the widget.
 407 </para>
 408
 409 @attach_widget: the #GtkWidget that the menu is being detached from.
 410 @menu: the #GtkMenu being detached.
 411
 412
 413 <!-- ##### FUNCTION gtk_menu_set_monitor ##### -->
 414 <para>
 415
 416 </para>
 417
 418 @menu:
 419 @monitor_num:
 420
 421