GtkAda Reference Manual - Package Gtk.Menu

[Contents] [Back] [Prev] [Up] [Next] [Forward]

# Package Gtk.Menu

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 section Package 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 <backspace> 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.

- Gtk.Menu Widget Hierarchy
- Gtk.Menu Types
- Gtk.Menu Subprograms
- Gtk.Menu Example

## Widget Hierarchy

    GObject                       (see section Package Glib.Object)
    Gtk_Object                    (see section Package Gtk.Object)
       \___ Gtk_Widget            (see section Package Gtk.Widget)
          \___ Gtk_Container      (see section Package Gtk.Container)
             \___ Gtk_Menu_Shell  (see section Package Gtk.Menu_Shell)
                \___ Gtk_Menu     (see section Package Gtk.Menu)

## Types

    type Gtk_Menu_Detach_Func is access procedure
    type Gtk_Menu_Position_Func is access procedure

## Subprograms

### Creating a menu
    procedure Gtk_New
      (Widget             : out    Gtk_Menu);
| Create a new empty menu.
    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);
| Select a specified item in the menu. You will almost never need this function, it is used internally by Gtk_Option_Menu. Note that the item is not considered as being pressed by the user, and thus no callback is called as a result.
    function Get_Active
      (Menu               : access Gtk_Menu_Record)
       return Gtk.Menu_Item.Gtk_Menu_Item;
| Get the active menu item. In a Gtk_Option_Menu, this is the item that is currently shown in the button.
    procedure Set_Tearoff_State
      (Menu               : access Gtk_Menu_Record;
       Torn_Off           :        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.
    function Get_Tearoff_State
      (Menu               : access Gtk_Menu_Record)
       return Boolean;
| Return the tearoff status of the menu.
    procedure Set_Title
      (Menu               : access Gtk_Menu_Record;
       Title              :        UTF8_String);
| Set the title of the menu. Title is displayed when the menu is displayed as a tearoff menu in an independent window.
    function Get_Title
      (Menu               : access Gtk_Menu_Record)
       return UTF8_String;
| Return the tiel of the menu.
    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.
### 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.
### Modifying the accelerators
    procedure Set_Accel_Group
      (Menu               : access Gtk_Menu_Record;
       Accel              :        Accel_Group.Gtk_Accel_Group);
| Set the Accel_Group that holds the global accelerators and key bindings for the menu.
    function Get_Accel_Group
      (Menu               : access Gtk_Menu_Record)
       return Accel_Group.Gtk_Accel_Group;
| Get the accelerator group used to set the key bindings in 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, "<Gnumeric-Sheet>/File"); has been called, assign its items the accel paths: "<Gnumeric-Sheet>/File/New" and "<Gnumeric-Sheet>/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 Detached 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.

## 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;

[Contents] [Back] [Prev] [Up] [Next] [Forward]