/src/wrappers/gtk/library/gtk_menu.e
Specman e | 570 lines | 103 code | 157 blank | 310 comment | 3 complexity | 498cb6e33b2c0edbcff2cc57ae178a91 MD5 | raw file
1indexing 2 description: "GtkMenu -- A menu widget." 3 copyright: "[ 4 Copyright (C) 2006 eiffel-libraries team, GTK+ team 5 6 This library is free software; you can redistribute it and/or 7 modify it under the terms of the GNU Lesser General Public License 8 as published by the Free Software Foundation; either version 2.1 of 9 the License, or (at your option) any later version. 10 11 This library is distributed in the hope that it will be useful, but 12 WITHOUT ANY WARRANTY; without even the implied warranty of 13 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 14 Lesser General Public License for more details. 15 16 You should have received a copy of the GNU Lesser General Public 17 License along with this library; if not, write to the Free Software 18 Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 19 02110-1301 USA 20 ]" 21 22class GTK_MENU 23 -- A GtkMenu is a GtkMenuShell that implements a drop down menu 24 -- consisting of a list of GtkMenuItem objects which can be 25 -- navigated and activated by the user to perform application 26 -- functions. 27 28 -- A GtkMenu is most commonly dropped down by activating a 29 -- GtkMenuItem in a GtkMenuBar or popped up by activating a 30 -- GtkMenuItem in another GtkMenu. 31 32 -- A GtkMenu can also be popped up by activating a 33 -- GtkOptionMenu. Other composite widgets such as the GtkNotebook 34 -- can pop up a GtkMenu as well. 35 36 -- Applications can display a GtkMenu as a popup menu by calling 37 -- the gtk_menu_popup() function. The example below shows how an 38 -- application can pop up a menu when the 3rd mouse button is 39 -- pressed. 40 41 -- TODO: Eiffelize this Example 1. Connecting the popup signal 42 -- handler. 43 44 -- /* connect our handler which will popup the menu */ 45 -- g_signal_connect_swapped (window, "button_press_event", 46 -- G_CALLBACK (my_popup_handler), menu); 47 48 -- TODO: Eiffelize this Example 2. Signal handler which 49 -- displays a popup menu. 50 51 -- static gint 52 -- my_popup_handler (GtkWidget *widget, GdkEvent *event) 53 -- { 54 -- GtkMenu *menu; 55 -- GdkEventButton *event_button; 56 57 -- g_return_val_if_fail (widget != NULL, FALSE); 58 -- g_return_val_if_fail (GTK_IS_MENU (widget), FALSE); 59 -- g_return_val_if_fail (event != NULL, FALSE); 60 61 -- /* The "widget" is the menu that was supplied when 62 -- * g_signal_connect_swapped() was called. 63 -- */ 64 -- menu = GTK_MENU (widget); 65 66 -- if (event->type == GDK_BUTTON_PRESS) 67 -- { 68 -- event_button = (GdkEventButton *) event; 69 -- if (event_button->button == 3) 70 -- { 71 -- gtk_menu_popup (menu, NULL, NULL, NULL, NULL, 72 -- event_button->button, event_button->time); 73 -- return TRUE; 74 -- } 75 -- } 76 77 -- return FALSE; 78 -- } 79 80inherit 81 GTK_MENU_SHELL redefine struct_size end 82 -- GtkMenu implements AtkImplementorIface interface. 83 84insert 85 G_OBJECT_FACTORY [GTK_WIDGET] 86 GTK_MENU_EXTERNALS 87 88creation make, from_external_pointer 89 90feature {} -- Creation 91 make is 92 -- Creates a new GtkMenu. 93 require gtk_initialized: gtk.is_initialized 94 do 95 from_external_pointer (gtk_menu_new) 96 end 97 98feature 99 -- TODO: set_screen (a_screen: GDK_SCREEN) is Sets the GdkScreen on 100 -- which the menu will be displayed. If `a_screen0 is Void it 101 -- should be determined by the widget the menu is attached to. 102 -- do 103 -- gtk_menu_set_screen (handle, a_screen.handle) 104 --end 105 106 reorder_child (a_child: GTK_WIDGET; a_new_position: INTEGER) is 107 -- Moves GtkMenuItem `a_child' to `a_new_position' within the 108 -- GtkMenu.Positions are numbered from 0 to n-1. 109 require 110 valid_child: a_child/=Void 111 do 112 gtk_menu_reorder_child (handle, a_child.handle, a_new_position) 113 end 114 115 attach (a_child: GTK_WIDGET; 116 left_attach, right_attach, top_attach, bottom_attach: INTEGER) is 117 -- Adds a new GtkMenuItem to a (table) menu. The number of 118 -- 'cells' that an item will occupy is specified by 119 -- left_attach, right_attach, top_attach and 120 -- bottom_attach. These each represent the leftmost, 121 -- rightmost, uppermost and lower column and row numbers of 122 -- the table. (Columns and rows are indexed from zero). 123 124 -- Note that this function is not related to gtk_menu_detach. 125 126 -- `left_attach': The column number to attach the left side 127 -- of the item to. 128 129 -- `right_attach': The column number to attach the right side 130 -- of the item to. 131 132 -- `top_attach' : The row number to attach the top of the 133 -- item to. 134 135 -- `bottom_attach' : The row number to attach the bottom of 136 -- the item to. 137 138 require 139 positive_left_attach: left_attach >= 0 -- since it is a guint 140 positive_right_attach: right_attach >= 0 -- since it is a guint 141 positive_top_attach: top_attach >= 0 -- since it is a guint 142 positive_bottom_attach: bottom_attach >= 0 -- since it is a guint 143 144 do 145 gtk_menu_attach (handle, a_child.handle, 146 left_attach, right_attach, 147 top_attach, bottom_attach) 148 end 149 150 -- TODO: understand then wrap popup (a_parent_shell, a_parent_item: 151 -- GTK_WIDGET; a) is do 152 153 -- void gtk_menu_popup (GtkMenu *menu, GtkWidget 154 -- *parent_menu_shell, GtkWidget *parent_menu_item, 155 -- GtkMenuPositionFunc func, gpointer data, guint button, guint32 156 -- activate_time); 157 158 -- Displays a menu and makes it available for 159 -- selection. Applications can use this function to display 160 -- context-sensitive menus, and will typically supply NULL for the 161 -- parent_menu_shell, parent_menu_item, func and data 162 -- parameters. The default menu positioning function will position 163 -- the menu at the current mouse cursor position. 164 165 -- The button parameter should be the mouse button pressed to 166 -- initiate the menu popup. If the menu popup was initiated by 167 -- something other than a mouse button press, such as a mouse 168 -- button release or a keypress, button should be 0. 169 170 -- The activate_time parameter should be the time stamp of the 171 -- event that initiated the popup. If such an event is not 172 -- available, use gtk_get_current_event_time() instead. 173 174 -- menu : a GtkMenu. 175 -- parent_menu_shell : the menu shell containing the triggering menu item, 176 -- or NULL 177 -- parent_menu_item : the menu item whose activation triggered the popup, 178 -- or NULL 179 -- func : a user supplied function used to position the menu, 180 -- or NULL 181 -- data : user supplied data to be passed to func. 182 -- button : the mouse button which was pressed to initiate the 183 -- event. 184 -- activate_time : the time at which the activation event occurred. 185 186 -- TODO: gtk_menu_set_accel_group () 187 188 -- void gtk_menu_set_accel_group (GtkMenu *menu, GtkAccelGroup 189 -- *accel_group); 190 191 -- Set the GtkAccelGroup which holds global accelerators for the 192 -- menu. This accelerator group needs to also be added to all 193 -- windows that this menu is being used in with 194 -- gtk_window_add_accel_group(), in order for those windows to 195 -- support all the accelerators contained in this group. 196 197 -- menu : a GtkMenu. 198 -- accel_group : the GtkAccelGroup to be associated with the menu. 199 200 -- ----------------------------------------------------------------------- 201 202 -- gtk_menu_get_accel_group () 203 204 -- GtkAccelGroup* gtk_menu_get_accel_group (GtkMenu *menu); 205 206 -- Gets the GtkAccelGroup which holds global accelerators for the 207 -- menu. See gtk_menu_set_accel_group(). 208 209 -- menu : a GtkMenu. 210 -- Returns : the GtkAccelGroup associated with the menu. 211 212 -- ----------------------------------------------------------------------- 213 214 -- gtk_menu_set_accel_path () 215 216 -- void gtk_menu_set_accel_path (GtkMenu *menu, const gchar 217 -- *accel_path); 218 219 -- Sets an accelerator path for this menu from which accelerator 220 -- paths for its immediate children, its menu items, can be 221 -- constructed. The main purpose of this function is to spare the 222 -- programmer the inconvenience of having to call 223 -- gtk_menu_item_set_accel_path() on each menu item that should 224 -- support runtime user changable accelerators. Instead, by just 225 -- calling gtk_menu_set_accel_path() on their parent, each menu 226 -- item of this menu, that contains a label describing its purpose, 227 -- automatically gets an accel path assigned. For example, a menu 228 -- containing menu items "New" and "Exit", will, after 229 -- gtk_menu_set_accel_path (menu, "<Gnumeric-Sheet>/File"); has 230 -- been called, assign its items the accel paths: 231 -- "<Gnumeric-Sheet>/File/New" and "<Gnumeric-Sheet>/File/Exit". 232 -- Assigning accel paths to menu items then enables the user to 233 -- change their accelerators at runtime. More details about 234 -- accelerator paths and their default setups can be found at 235 -- gtk_accel_map_add_entry(). 236 237 -- menu : a valid GtkMenu accel_path : a valid accelerator path 238 239 -- ----------------------------------------------------------------------- 240 241 set_title (a_title: STRING) is 242 -- Sets `a_title' as the title for the menu. The title is 243 -- displayed when the menu is shown as a tearoff menu. 244 require title_not_void: a_title /= Void 245 do 246 gtk_menu_set_title (handle, a_title.to_external) 247 end 248 249 title: STRING is 250 -- the title of the menu. See `set_title'. Can be Void if 251 -- the menu has no title set on it. 252 local ptr: POINTER 253 do 254 ptr := gtk_menu_get_title (handle) 255 if ptr.is_not_null then 256 -- create Result.from_external_copy (ptr) 257 create {CONST_STRING} Result.from_external (ptr) 258 end 259 end 260 261 is_torn_off: BOOLEAN is 262 -- Is the menu currently torn off. 263 do 264 Result := gtk_menu_get_tearoff_state (handle).to_boolean 265 end 266 267 popdown is 268 -- Removes the menu from the screen. 269 do 270 gtk_menu_popdown (handle) 271 end 272 273 reposition is 274 -- Repositions the menu according to its position function. 275 do 276 gtk_menu_reposition (handle) 277 end 278 279 active_item: GTK_WIDGET is 280 -- the selected menu item from the menu. This is used by the 281 -- GtkOptionMenu. If a selection has not yet been made, the 282 -- first menu item is selected. 283 do 284 Result := wrapper(gtk_menu_get_active (handle)) 285 end 286 287 set_active (an_index: INTEGER) is 288 -- Selects the specified menu item within the menu. This is 289 -- used by the GtkOptionMenu and should not be used by anyone 290 -- else. `an_index' is values are from 0 to n-1. 291 292 require natural_index: an_index >= 0 293 do 294 gtk_menu_set_active (handle, an_index) 295 end 296 297 set_tearoff is 298 -- Changes the tearoff state of the menu. A menu is normally 299 -- displayed as drop down menu which persists as long as the 300 -- menu is active. It can also be displayed as a tearoff menu 301 -- which persists until it is closed or reattached. 302 do 303 gtk_menu_set_tearoff_state (handle, 1) 304 ensure is_torn_off 305 end 306 307 unset_tearoff is 308 -- Changes the tearoff state of the menu. A menu is normally 309 -- displayed as drop down menu which persists as long as the 310 -- menu is active. It can also be displayed as a tearoff menu 311 -- which persists until it is closed or reattached. 312 do 313 gtk_menu_set_tearoff_state (handle, 0) 314 ensure not is_torn_off 315 end 316 317 318 -- TODO: wrap gtk_menu_attach_to_widget () 319 320 -- void gtk_menu_attach_to_widget (GtkMenu *menu, GtkWidget 321 -- *attach_widget, GtkMenuDetachFunc detacher); 322 323 -- Attaches the menu to the widget and provides a callback function 324 -- that will be invoked when the menu calls gtk_menu_detach() 325 -- during its destruction. 326 327 -- menu : a GtkMenu. 328 -- attach_widget : the GtkWidget that the menu will be attached to. 329 -- detacher : the user supplied callback function that will be called 330 -- when the menu calls gtk_menu_detach(), or NULL 331 332 -- TODO: wrap gtk_menu_detach () 333 334 -- void gtk_menu_detach (GtkMenu *menu); 335 336 -- Detaches the menu from the widget to which it had been 337 -- attached. This function will call the callback function, 338 -- detacher, provided when the gtk_menu_attach_to_widget() function 339 -- was called. 340 341 -- menu : a GtkMenu. 342 343 -- ----------------------------------------------------------------------- 344 345 -- TODO: wrap gtk_menu_get_attach_widget () 346 347 -- GtkWidget* gtk_menu_get_attach_widget (GtkMenu *menu); 348 349 -- Returns the GtkWidget that the menu is attached to. 350 351 -- menu : a GtkMenu. 352 -- Returns : the GtkWidget that the menu is attached to. 353 354 -- ----------------------------------------------------------------------- 355 356 -- TODO: wrap gtk_menu_get_for_attach_widget () 357 358 -- GList* gtk_menu_get_for_attach_widget (GtkWidget *widget); 359 360 -- widget : a GtkWidget * Returns a list of the menus which are attached 361 -- to this widget. This list is owned by GTK+ and must not be 362 -- modified. 363 -- Returns : the list of menus attached to his widget. 364 365 -- Since 2.6 366 367 -- ----------------------------------------------------------------------- 368 369 -- GtkMenuPositionFunc () 370 371 -- void (*GtkMenuPositionFunc) (GtkMenu *menu, 372 -- gint *x, 373 -- gint *y, 374 -- gboolean *push_in, 375 -- gpointer user_data); 376 377 -- A user function supplied when calling gtk_menu_popup() which controls 378 -- the positioning of the menu when it is displayed. The function sets the 379 -- x and y parameters to the coordinates where the menu is to be drawn. 380 381 -- menu : a GtkMenu. 382 -- x : address of the gint representing the horizontal position 383 -- where the menu shall be drawn. This is an output parameter. 384 -- y : address of the gint representing the vertical position 385 -- where the menu shall be drawn. This is an output parameter. 386 -- push_in : whether the menu should be pushed in to be completely 387 -- inside the screen instead of just clamped to the size to 388 -- the screen. 389 -- user_data : the data supplied by the user in the gtk_menu_popup() data 390 -- parameter. 391 392 -- ----------------------------------------------------------------------- 393 394 -- GtkMenuDetachFunc () 395 396 -- void (*GtkMenuDetachFunc) (GtkWidget *attach_widget, 397 -- GtkMenu *menu); 398 399 -- A user function supplied when calling gtk_menu_attach_to_widget() which 400 -- will be called when the menu is later detached from the widget. 401 402 -- attach_widget : the GtkWidget that the menu is being detached from. 403 -- menu : the GtkMenu being detached. 404 405 -- ----------------------------------------------------------------------- 406 407 -- TODO: wrap gtk_menu_set_monitor () 408 409 -- void gtk_menu_set_monitor (GtkMenu *menu, 410 -- gint monitor_num); 411 412 -- Informs GTK+ on which monitor a menu should be popped up. See 413 -- gdk_screen_get_monitor_geometry(). 414 415 -- This function should be called from a GtkMenuPositionFunc if the menu 416 -- should not appear on the same monitor as the pointer. This information 417 -- can't be reliably inferred from the coordinates returned by a 418 -- GtkMenuPositionFunc, since, for very long menus, these coordinates may 419 -- extend beyond the monitor boundaries or even the screen boundaries. 420 421 -- menu : a GtkMenu 422 -- monitor_num : the number of the monitor on which the menu should be 423 -- popped up 424 425 -- Since 2.4 426 427feature -- Properties 428 -- "tearoff-state" gboolean : Read / Write 429 -- "tearoff-title" gchararray : Read / Write 430 -- The "tearoff-state" property 431 432 -- "tearoff-state" gboolean : Read / Write 433 434 -- A boolean that indicates whether the menu is torn-off. 435 436 -- Default value: FALSE 437 438 -- Since 2.6 439 440 -- ----------------------------------------------------------------------- 441 442 -- The "tearoff-title" property 443 444 -- "tearoff-title" gchararray : Read / Write 445 446 -- A title that may be displayed by the window manager when this menu is 447 -- torn-off. 448 449 -- Default value: "" 450 451feature -- Child Properties 452 453 454 -- "bottom-attach" gint : Read / Write 455 -- "left-attach" gint : Read / Write 456 -- "right-attach" gint : Read / Write 457 -- "top-attach" gint : Read / Write 458 -- Child Property Details 459 460 -- The "bottom-attach" child property 461 462 -- "bottom-attach" gint : Read / Write 463 464 -- The row number to attach the bottom of the child to. 465 466 -- Allowed values: >= -1 467 468 -- Default value: -1 469 470 -- ----------------------------------------------------------------------- 471 472 -- The "left-attach" child property 473 474 -- "left-attach" gint : Read / Write 475 476 -- The column number to attach the left side of the child to. 477 478 -- Allowed values: >= -1 479 480 -- Default value: -1 481 482 -- ----------------------------------------------------------------------- 483 484 -- The "right-attach" child property 485 486 -- "right-attach" gint : Read / Write 487 488 -- The column number to attach the right side of the child to. 489 490 -- Allowed values: >= -1 491 492 -- Default value: -1 493 494 -- ----------------------------------------------------------------------- 495 496 -- The "top-attach" child property 497 498 -- "top-attach" gint : Read / Write 499 500 -- The row number to attach the top of the child to. 501 502 -- Allowed values: >= -1 503 504 -- Default value: -1 505 506feature -- Style Properties 507 -- "horizontal-offset" gint : Read 508 -- "vertical-offset" gint : Read 509 -- "vertical-padding" gint : Read 510 511 -- Style Property Details 512 513 -- The "horizontal-offset" style property 514 515 -- "horizontal-offset" gint : Read 516 517 -- When the menu is a submenu, position it this number of pixels offset 518 -- horizontally. 519 520 -- Default value: -2 521 522 -- ----------------------------------------------------------------------- 523 524 -- The "vertical-offset" style property 525 526 -- "vertical-offset" gint : Read 527 528 -- When the menu is a submenu, position it this number of pixels offset 529 -- vertically. 530 531 -- Default value: 0 532 533 -- ----------------------------------------------------------------------- 534 535 -- The "vertical-padding" style property 536 537 -- "vertical-padding" gint : Read 538 539 -- Extra space at the top and bottom of the menu. 540 541 -- Allowed values: >= 0 542 543 -- Default value: 1 544 -- Signals 545 546 547 -- "move-scroll" 548 -- void user_function (GtkMenu *menu, 549 -- GtkScrollType *arg1, 550 -- gpointer user_data) : Run last / Action 551 552 553feature -- Signal Details 554 555 -- The "move-scroll" signal 556 557 -- void user_function (GtkMenu *menu, 558 -- GtkScrollType *arg1, 559 -- gpointer user_data) : Run last / Action 560 561 -- menu : the object which received the signal. 562 -- arg1 : 563 -- user_data : user data set when the signal handler was connected. 564feature -- size 565 struct_size: INTEGER is 566 external "C inline use <gtk/gtk.h>" 567 alias "sizeof(GtkMenu)" 568 end 569 570end