Toc Gallery Index Tree Gtk.Menu

Hierarchy

Description

This widget implements a drop-down menu. This is basically a simple box that contains a series of Gtk_Menu_Item widgets, on which the user can click to perform actions.

Such a menu is usually part of a Gtk_Menu_Bar (at the top of the window), or activated by clicking on an item in another Gtk_Menu. See Gtk.Option_Menu for another way of displaying menus.

All the menus in GtkAda can be "Tear off" menus, i.e you can detach them from their parent (either a menu bar or another menu) to keep them visible on the screen at all times).

It is worth noting that by default, the user of your application will be able to dynamically modify the shortcuts associated with each menu item. For instance, selecting a menu item and pressing a key will assign this new shortcut to the item, possibly removing the shortcut from any other item it was associated with.

Note that pressing will simply remove the shortcut.

This default behavior, somewhat unexpected, can be canceled. There are two ways to control this behavior: you can lock a specific menu item by calling Gtk.Widget.Lock_Accelerators on it. But you can also lock all the menu items at once by calling Gtk.Accel_Group.Lock for all the accelerator groups that were used (the GUI builder gate generally creates a single one), as well as on the group returned by Gtk.Accel_Group.Get_Default, which is the one used for items that don't initially have a shortcut.

Types

  • type Gtk_Menu is access all Gtk_Menu_Record'Class;
  • type Gtk_Menu_Detach_Func is access procedure (Attach_Widget : access Gtk.Widget.Gtk_Widget_Record'Class; Menu : access Gtk_Menu_Record'Class);
    Function called when a menu previously attached to a widget is detached. An access to this function is given in Attach_To_Widget.
  • type Gtk_Menu_Position_Func is access procedure (Menu : access Gtk_Menu_Record'Class; X : out Gint; Y : out Gint);
    This function is called when displaying a popup menu on the screen. It should return the (X, Y) coordinates of the menu. Note that you might want to attach the menu to a widget first if you want to display the menu relative to its attached widget.

    Note that there is a second version of this function (with added user data in the package User_Menu_Popup below

  • type Gtk_Menu_Record is new Gtk.Menu_Shell.Gtk_Menu_Shell_Record with private;

Subprograms

    Creating a menu

  • procedure Gtk_New (Widget : out Gtk_Menu);
    Create a new empty menu.
  • procedure Initialize (Widget : access Gtk_Menu_Record'Class);
    Internal initialization function. See the section "Creating your own widgets" in the documentation.
  • function Get_Type return Gtk.Gtk_Type;
    Return the internal value associated with a Gtk_Menu.
  • procedure Set_Active (Menu : access Gtk_Menu_Record; Index : Guint);
    function Get_Active (Menu : access Gtk_Menu_Record) return Gtk.Menu_Item.Gtk_Menu_Item;
    Select a specified item in the menu. You will almost never need this function, it is used internally by Gtk_Option_Menu, for which it is the item that is currently selected. Note that the item is not considered as being pressed by the user when you call Set_Active, and thus no callback is called as a result.
  • procedure Set_Tearoff_State (Menu : access Gtk_Menu_Record; Torn_Off : Boolean);
    function Get_Tearoff_State (Menu : access Gtk_Menu_Record) return Boolean;
    Modify the tearoff status of the menu. If Torn_Off is False, the menu is displayed as a drop down menu which disappears when the menu is not active. If Torn_Off is True, the menu persists until it is closed or reattached. Note that you can give the user access to this functionality by inserting a Gtk_Tearoff_Menu_Item in the menu.
  • procedure Set_Title (Menu : access Gtk_Menu_Record; Title : UTF8_String);
    function Get_Title (Menu : access Gtk_Menu_Record) return UTF8_String;
    Set the title of the menu. Title is displayed when the menu is displayed as a tearoff menu in an independent window.
  • procedure Reorder_Child (Menu : access Gtk_Menu_Record; Child : access Gtk.Widget.Gtk_Widget_Record'Class; Position : Gint);
    Move an existing menu_item within the menu. Its new position is given by Position, 0 being the first item in the menu. If Child does not exist in the menu, nothing is done.
  • procedure Attach (Menu : access Gtk_Menu_Record; Child : access Gtk.Menu_Item.Gtk_Menu_Item_Record'Class; Left_Attach : Guint; Right_Attach : Guint; Top_Attach : Guint; Bottom_Attach : Guint);
    Adds a new #GtkMenuItem to a (table) menu. The number of 'cells' that an item will occupy is specified by left_attach, right_attach, top_attach and bottom_attach. These each represent the leftmost, rightmost, uppermost and lower column and row numbers of the table. (Columns and rows are indexed from zero).

    Note that this function is not related to Detach().

    Adding items to a standard menu is simply done by calling Add().

  • Displaying a menu

  • procedure Popup (Menu : access Gtk_Menu_Record; Parent_Menu_Shell : in Gtk.Menu_Shell.Gtk_Menu_Shell := null; Parent_Menu_Item : in Gtk.Menu_Item.Gtk_Menu_Item := null; Func : in Gtk_Menu_Position_Func := null; Button : in Guint := 1; Activate_Time : in Guint32 := 0);
    Display a menu on the screen. This is the function to use to create contextual menus. Most of the time, the parameters can have a null value. Parent_Menu_Shell is the Gtk_Menu_Shell that contains Parent_Menu_Item, i.e. the widget that triggered the display of the menu. Func is a function that returns the coordinates for the menu. If it is null, then a default function that positions the menu at the pointer location is used. Button is the mouse button that was pressed to initiate the event. Activate_Time is the time at which the event occurred (you can get it directly from the Gdk_Event structure).

    Note that a variant of this function is given in the generic package User_Menu_Popup.

  • procedure Popup (Menu : access Gtk_Menu_Record; Data : access Data_Type; Parent_Menu_Shell : in Gtk.Menu_Shell.Gtk_Menu_Shell := null; Parent_Menu_Item : in Gtk.Menu_Item.Gtk_Menu_Item := null; Func : in Gtk_Menu_Position_Func := null; Button : in Guint := 1; Activate_Time : in Guint32 := 0);
    Same as the Popup function above. Note that Data is not duplicated, thus you should take care of the memory allocation/deallocation yourself.
  • procedure Popdown (Menu : access Gtk_Menu_Record);
    Remove the menu from the screen
  • procedure Reposition (Menu : access Gtk_Menu_Record);
    Reposition a menu according to its position function. This function is set when Popup is called.
  • procedure Set_Monitor (Menu : access Gtk_Menu_Record; Monitor_Num : Gint);
    Informs GTK+ on which monitor a menu should be popped up. See gdk_screen_get_monitor_geometry().

    This function should be called from a Gtk_Menu_Position_Func if the menu should not appear on the same monitor as the pointer. This information can't be reliably inferred from the coordinates returned by a Gtk_Menu_Position_Func, since, for very long menus, these coordinates may extend beyond the monitor boundaries or even the screen boundaries.

  • Modifying the accelerators

  • procedure Set_Accel_Group (Menu : access Gtk_Menu_Record; Accel : Accel_Group.Gtk_Accel_Group);
    function Get_Accel_Group (Menu : access Gtk_Menu_Record) return Accel_Group.Gtk_Accel_Group;
    Set the Accel_Group that holds the global accelerators and key bindings for the menu.
  • procedure Set_Accel_Path (Menu : access Gtk_Menu_Record; Accel_Path : UTF8_String);
    Set an accelerator path for this menu from which accelerator paths for its immediate children, its menu items, can be constructed. The main purpose of this function is to spare the programmer the inconvenience of having to call Gtk.Menu_Item.Set_Accel_Path on each menu item that should support runtime user changable accelerators. Instead, by just calling Gtk.Menu.Set_Accel_Path on their parent, each menu item of this menu, that contains a label describing its purpose, automatically gets an accel path assigned. For example, a menu containing menu items "New" and "Exit", will, after Set_Accel_Path (menu, "/File"); has been called, assign its items the accel paths: "/File/New" and "/File/Exit". Assigning accel paths to menu items then enables the user to change their accelerators at runtime.
  • Attaching a menu to a widget

  • procedure Attach_To_Widget (Menu : access Gtk_Menu_Record; Attach_Widget : access Gtk.Widget.Gtk_Widget_Record'Class; Detacher : Gtk_Menu_Detach_Func);
    Attach a menu to the widget. When the menu is detached from the widget (for instance when it is destroyed), the procedure Detacher will be called. You will almost never need to use this function, unless you specifically want a call back when a widget becomes unavailable. If Attach_Widget is a menu_item with a single label in it, the name of the window created when Menu is teared-off will be the label in the menu_item.
  • procedure Detach (Menu : access Gtk_Menu_Record);
    Detach the menu from its widget, and call the Detacher set in Attach_To_Widget.
  • function Get_Attach_Widget (Menu : access Gtk_Menu_Record) return Gtk.Widget.Gtk_Widget;
    Return the widget to which the menu was attached. If the menu was not attached, this function returns null.
  • function Get_For_Attach_Widget (Widget : access Gtk.Widget.Gtk_Widget_Record'Class) return Gtk.Widget.Widget_List.Glist;
    Returns a list of the menus which are attached to this widget. This list is owned by GTK+ and must not be modified.

Signals

  • move_scroll
    procedure Handler (Menu : access Gtk_Menu_Record'Class; Typ : Gtk_Scroll_Type);
    Requests that another part of the menu be made visible. Menus that display lots of items might not fit on the screen. When this is the case, gtk+ will insert some scrolling arrows on both ends of the menus and emitting this signal will behave as if the user had clicked on one of these arrows. This signal is mostly useful as a keybinding

Properties

  • Tearoff_State_Property
    Boolean
    A boolean that indicates whether the menu is torn-off
  • Tearoff_Title_Property
    String
    A title that may be displayed by the window manager when this

Child Properties

  • Bottom_Attach_Property
    Int
    The row number to attach the bottom of the child to
  • Left_Attach_Property
    Int
    The column number to attach the left side of the child to
  • Right_Attach_Property
    Int
    The column number to attach the right side of the child to
  • Top_Attach_Property
    Int
    The row number to attach the top of the child to

Style Properties

  • Horizontal_Offset_Property
    Int
    When the menu is a submenu, position it this number of pixels
  • Vertical_Offset_Property
    Int
    When the menu is a submenu, position it this number of pixels
  • Vertical_Padding_Property
    Int
    Extra space at the top and bottom of the menu

Example

This example shows how you create contextual menus with the third mouse button. with Gtk.Handlers; use Gtk.Handlers; with Gtk.Menu; use Gtk.Menu; with Gdk.Event; use Gdk.Event; with Glib; use Glib; with Gtk.Window; use Gtk.Window; with Gtk.Menu_Item; use Gtk.Menu_Item; with Gtk.Enums; use Gtk.Enums; with Gtk.Main; use Gtk.Main; procedure Contextual is package Menu_Cb is new Gtk.Handlers.Return_Callback (Widget_Type => Gtk_Menu_Record, Return_Type => Boolean); function Popup_Menu_Handler (Menu : access Gtk_Menu_Record'Class; Event : Gdk.Event.Gdk_Event) return Boolean is begin if Gdk.Event.Get_Event_Type (Event) = Button_Press and then Gdk.Event.Get_Button (Event) = 3 then Popup (Menu, Button => Gdk.Event.Get_Button (Event), Activate_Time => Gdk.Event.Get_Time (Event)); end if; return False; end Popup_Menu_Handler; Menu : Gtk_Menu; Win : Gtk_Window; Item : Gtk_Menu_Item; begin Gtk.Main.Init; create the menu as usual Gtk_New (Menu); Gtk_New (Item, "Item1"); Append (Menu, Item); Show (Item); create the widget on which you want a contextual menu Prepares it to receive button_press events Gtk_New (Win, Window_Toplevel); Set_Events (Win, Button_Press_Mask); Finally, connect both: Menu_Cb.Object_Connect (Win, "button_press_event", Menu_Cb.To_Marshaller (Popup_Menu_Handler'Access), Slot_Object => Menu); Show_All (Win); Gtk.Main.Main; end Contextual;

Testgtk source code

This code is part of testgtk, a demo application packaged with GtkAda. Testgtk demonstrates the various widgets of GtkAda
----------------------------------------------------------------------- -- GtkAda - Ada95 binding for the Gimp Toolkit -- -- -- -- Copyright (C) 1998-1999 -- -- Emmanuel Briot, Joel Brobecker and Arnaud Charlet -- -- -- -- This library is free software; you can redistribute it and/or -- -- modify it under the terms of the GNU General Public -- -- License as published by the Free Software Foundation; either -- -- version 2 of the License, or (at your option) any later version. -- -- -- -- This library is distributed in the hope that it will be useful, -- -- but WITHOUT ANY WARRANTY; without even the implied warranty of -- -- MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU -- -- General Public License for more details. -- -- -- -- You should have received a copy of the GNU General Public -- -- License along with this library; if not, write to the -- -- Free Software Foundation, Inc., 59 Temple Place - Suite 330, -- -- Boston, MA 02111-1307, USA. -- -- -- -- -- -- -- -- -- -- ----------------------------------------------------------------------- with Gtk.Box; use Gtk.Box; with Gtk.Menu; use Gtk.Menu; with Gtk.Menu_Bar; use Gtk.Menu_Bar; with Gtk.Menu_Item; use Gtk.Menu_Item; with Gtk.Option_Menu; use Gtk.Option_Menu; with Gtk.Radio_Menu_Item; use Gtk.Radio_Menu_Item; with Gtk.Tearoff_Menu_Item; use Gtk.Tearoff_Menu_Item; with Gtk.Widget; use Gtk.Widget; with Gtk; use Gtk; package body Create_Menu is function Help return String is begin return "There are several widgets involved in displaying menus. The" & " @bGtk_Menu_Bar@B widget is a horizontal menu bar, which normally" & " appears at the top of an application. The @bGtk_Menu@B widget is" & " the actual menu that pops up. Both @bGtk_Menu_Bar@B and" & " @bGtk_Menu@B are subclasses of @bGtk_Menu_Shell@B; a" & " @bGtk_Menu_Shell@B contains menu items (@bGtk_Menu_Item@B)." & " Each menu item contains text and/or images and can be selected" & " by the user." & ASCII.LF & "This demo shows how to create a @bGtk_Menu_Bar@B, with multiple" & " @bGtk_Menu@Bs. Each of this submenu is actually a @btearoff@B menu" & ", which means by that clicking on the dashed line, you can simply" & " glue the submenu to another place on your desktop, and keep it" & " around. To hide it, simply click on the dashed line again." & ASCII.LF & "There are several kinds of menu item, including plain" & " @bGtk_Menu_Item@B, @bGtk_Check_Menu_Item@B which can be" & " checked/unchecked, @bGtk_Radio_Menu_Item@B which is a check menu" & " item that's in a mutually exclusive group," & " @bGtk_Separator_Menu_Item@B which is a separator bar," & " @bGtk_Tearoff_Menu_Item@B which allows a @bGtk_Menu@B to be torn" & " off, and @bGtk_Image_Menu_Item@B which can place a @bGtk_Image@B" & " or other widget next to the menu text. A @bGtk_Menu_Item can have" & " a submenu, which is simply a @bGtk_Menu@B to pop up when the menu" & " item is selected. Typically, all menu items in a menu bar have" & " submenus." & ASCII.LF & "The @bGtk_Option_Menu@B widget is a button that pops up a" & " @bGtk_Menu@B when clicked. It's used inside dialogs and such." & " This is different from the @bGtk_Combo_Box@B that you can see" & " in the @bEntry@B demo, since a @bGtk_Option_Menu@B does not have" & " any editable entry associated with it."; end Help; function Create_Menu (Depth : Integer; Tearoff : Boolean) return Gtk_Menu is Menu : Gtk_Menu; Group : Widget_SList.GSlist; Menu_Item : Gtk_Radio_Menu_Item; begin Gtk_New (Menu); if Tearoff then declare Tear_Menu : Gtk_Tearoff_Menu_Item; begin Gtk_New (Tear_Menu); Append (Menu, Tear_Menu); Show (Tear_Menu); end; end if; for J in 0 .. 5 loop Gtk_New (Menu_Item, Group, "Item" & Integer'Image (Depth) & " -" & Integer'Image (J + 1)); Group := Gtk.Radio_Menu_Item.Get_Group (Menu_Item); Append (Menu, Menu_Item); Show (Menu_Item); if J = 3 then Set_Sensitive (Menu_Item, False); end if; if Depth > 1 then Set_Submenu (Menu_Item, Create_Menu (Depth - 1, Tearoff)); end if; end loop; return Menu; end Create_Menu; procedure Run (Frame : access Gtk.Frame.Gtk_Frame_Record'Class) is Box1 : Gtk_Box; Box2 : Gtk_Box; Menu_Bar : Gtk_Menu_Bar; Menu : Gtk_Menu; Menu_Item : Gtk_Menu_Item; Option_Menu : Gtk_Option_Menu; begin Set_Label (Frame, "Menus"); Gtk_New_Vbox (Box1, False, 0); Add (Frame, Box1); Gtk_New (Menu_Bar); Pack_Start (Box1, Menu_Bar, False, False, 0); Menu := Create_Menu (2, True); Gtk_New (Menu_Item, "test" & ASCII.LF & "line2"); Set_Submenu (Menu_Item, Menu); Append (Menu_Bar, Menu_Item); Gtk_New (Menu_Item, "foo"); Set_Submenu (Menu_Item, Create_Menu (3, True)); Append (Menu_Bar, Menu_Item); Gtk_New (Menu_Item, "bar"); Set_Submenu (Menu_Item, Create_Menu (4, True)); Set_Right_Justified (Menu_Item, True); Append (Menu_Bar, Menu_Item); Gtk_New_Vbox (Box2, False, 10); Set_Border_Width (Box2, 10); Pack_Start (Box1, Box2, False, False, 0); Gtk_New (Option_Menu); Set_Menu (Option_Menu, Create_Menu (1, False)); Set_History (Option_Menu, 3); Pack_Start (Box2, Option_Menu, False, False, 0); Show_All (Frame); end Run; end Create_Menu;

Alphabetical Index