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