1. ------------------------------------------------------------------------------ 
  2. --                                                                          -- 
  3. --      Copyright (C) 1998-2000 E. Briot, J. Brobecker and A. Charlet       -- 
  4. --                     Copyright (C) 2000-2014, AdaCore                     -- 
  5. --                                                                          -- 
  6. -- This library is free software;  you can redistribute it and/or modify it -- 
  7. -- under terms of the  GNU General Public License  as published by the Free -- 
  8. -- Software  Foundation;  either version 3,  or (at your  option) any later -- 
  9. -- version. This library is distributed in the hope that it will be useful, -- 
  10. -- but WITHOUT ANY WARRANTY;  without even the implied warranty of MERCHAN- -- 
  11. -- TABILITY or FITNESS FOR A PARTICULAR PURPOSE.                            -- 
  12. --                                                                          -- 
  13. -- As a special exception under Section 7 of GPL version 3, you are granted -- 
  14. -- additional permissions described in the GCC Runtime Library Exception,   -- 
  15. -- version 3.1, as published by the Free Software Foundation.               -- 
  16. --                                                                          -- 
  17. -- You should have received a copy of the GNU General Public License and    -- 
  18. -- a copy of the GCC Runtime Library Exception along with this program;     -- 
  19. -- see the files COPYING3 and COPYING.RUNTIME respectively.  If not, see    -- 
  20. -- <http://www.gnu.org/licenses/>.                                          -- 
  21. --                                                                          -- 
  22. ------------------------------------------------------------------------------ 
  23.  
  24. --  <description> 
  25. --  A Gtk.Menu_Shell.Gtk_Menu_Shell is the abstract base class used to derive 
  26. --  the Gtk.Menu.Gtk_Menu and Gtk.Menu_Bar.Gtk_Menu_Bar subclasses. 
  27. -- 
  28. --  A Gtk.Menu_Shell.Gtk_Menu_Shell is a container of 
  29. --  Gtk.Menu_Item.Gtk_Menu_Item objects arranged in a list which can be 
  30. --  navigated, selected, and activated by the user to perform application 
  31. --  functions. A Gtk.Menu_Item.Gtk_Menu_Item can have a submenu associated with 
  32. --  it, allowing for nested hierarchical menus. 
  33. -- 
  34. --  </description> 
  35. pragma Ada_2005; 
  36.  
  37. pragma Warnings (Off, "*is already use-visible*"); 
  38. with Glib;            use Glib; 
  39. with Glib.Menu_Model; use Glib.Menu_Model; 
  40. with Glib.Object;     use Glib.Object; 
  41. with Glib.Properties; use Glib.Properties; 
  42. with Glib.Types;      use Glib.Types; 
  43. with Gtk.Buildable;   use Gtk.Buildable; 
  44. with Gtk.Container;   use Gtk.Container; 
  45. with Gtk.Enums;       use Gtk.Enums; 
  46. with Gtk.Widget;      use Gtk.Widget; 
  47.  
  48. package Gtk.Menu_Shell is 
  49.  
  50.    type Gtk_Menu_Shell_Record is new Gtk_Container_Record with null record; 
  51.    type Gtk_Menu_Shell is access all Gtk_Menu_Shell_Record'Class; 
  52.  
  53.    ------------------ 
  54.    -- Constructors -- 
  55.    ------------------ 
  56.  
  57.    function Get_Type return Glib.GType; 
  58.    pragma Import (C, Get_Type, "gtk_menu_shell_get_type"); 
  59.  
  60.    ------------- 
  61.    -- Methods -- 
  62.    ------------- 
  63.  
  64.    procedure Activate_Item 
  65.       (Menu_Shell       : not null access Gtk_Menu_Shell_Record; 
  66.        Menu_Item        : not null access Gtk.Widget.Gtk_Widget_Record'Class; 
  67.        Force_Deactivate : Boolean); 
  68.    --  Activates the menu item within the menu shell. 
  69.    --  "menu_item": the Gtk.Menu_Item.Gtk_Menu_Item to activate 
  70.    --  "force_deactivate": if True, force the deactivation of the menu shell 
  71.    --  after the menu item is activated 
  72.  
  73.    procedure Append 
  74.       (Menu_Shell : not null access Gtk_Menu_Shell_Record; 
  75.        Child      : not null access Gtk.Widget.Gtk_Widget_Record'Class); 
  76.    --  Adds a new Gtk.Menu_Item.Gtk_Menu_Item to the end of the menu shell's 
  77.    --  item list. 
  78.    --  "child": The Gtk.Menu_Item.Gtk_Menu_Item to add 
  79.  
  80.    procedure Bind_Model 
  81.       (Menu_Shell       : not null access Gtk_Menu_Shell_Record; 
  82.        Model            : access Glib.Menu_Model.Gmenu_Model_Record'Class; 
  83.        Action_Namespace : UTF8_String := ""; 
  84.        With_Separators  : Boolean); 
  85.    --  Establishes a binding between a Gtk.Menu_Shell.Gtk_Menu_Shell and a 
  86.    --  Glib.Menu_Model.Gmenu_Model. 
  87.    --  The contents of Shell are removed and then refilled with menu items 
  88.    --  according to Model. When Model changes, Shell is updated. Calling this 
  89.    --  function twice on Shell with different Model will cause the first 
  90.    --  binding to be replaced with a binding to the new model. If Model is null 
  91.    --  then any previous binding is undone and all children are removed. 
  92.    --  With_Separators determines if toplevel items (eg: sections) have 
  93.    --  separators inserted between them. This is typically desired for menus 
  94.    --  but doesn't make sense for menubars. 
  95.    --  If Action_Namespace is non-null then the effect is as if all actions 
  96.    --  mentioned in the Model have their names prefixed with the namespace, 
  97.    --  plus a dot. For example, if the action "quit" is mentioned and 
  98.    --  Action_Namespace is "app" then the effective action name is "app.quit". 
  99.    --  For most cases you are probably better off using 
  100.    --  Gtk.Menu.Gtk_New_From_Model or Gtk.Menu_Bar.Gtk_New_From_Model or just 
  101.    --  directly passing the Glib.Menu_Model.Gmenu_Model to 
  102.    --  Gtk.Application.Set_App_Menu or gtk_application_set_menu_bar. 
  103.    --  Since: gtk+ 3.6 
  104.    --  "model": the Glib.Menu_Model.Gmenu_Model to bind to or null to remove 
  105.    --  binding 
  106.    --  "action_namespace": the namespace for actions in Model 
  107.    --  "with_separators": True if toplevel items in Shell should have 
  108.    --  separators between them 
  109.  
  110.    procedure Cancel (Menu_Shell : not null access Gtk_Menu_Shell_Record); 
  111.    --  Cancels the selection within the menu shell. 
  112.    --  Since: gtk+ 2.4 
  113.  
  114.    procedure Deactivate (Menu_Shell : not null access Gtk_Menu_Shell_Record); 
  115.    --  Deactivates the menu shell. 
  116.    --  Typically this results in the menu shell being erased from the screen. 
  117.  
  118.    procedure Deselect (Menu_Shell : not null access Gtk_Menu_Shell_Record); 
  119.    --  Deselects the currently selected item from the menu shell, if any. 
  120.  
  121.    function Get_Parent_Shell 
  122.       (Menu_Shell : not null access Gtk_Menu_Shell_Record) 
  123.        return Gtk.Widget.Gtk_Widget; 
  124.    --  Gets the parent menu shell. 
  125.    --  The parent menu shell of a submenu is the Gtk.Menu.Gtk_Menu or 
  126.    --  Gtk.Menu_Bar.Gtk_Menu_Bar from which it was opened up. 
  127.    --  Since: gtk+ 3.0 
  128.  
  129.    function Get_Selected_Item 
  130.       (Menu_Shell : not null access Gtk_Menu_Shell_Record) 
  131.        return Gtk.Widget.Gtk_Widget; 
  132.    --  Gets the currently selected item. 
  133.    --  Since: gtk+ 3.0 
  134.  
  135.    function Get_Take_Focus 
  136.       (Menu_Shell : not null access Gtk_Menu_Shell_Record) return Boolean; 
  137.    --  Returns True if the menu shell will take the keyboard focus on popup. 
  138.    --  Since: gtk+ 2.8 
  139.  
  140.    procedure Set_Take_Focus 
  141.       (Menu_Shell : not null access Gtk_Menu_Shell_Record; 
  142.        Take_Focus : Boolean); 
  143.    --  If Take_Focus is True (the default) the menu shell will take the 
  144.    --  keyboard focus so that it will receive all keyboard events which is 
  145.    --  needed to enable keyboard navigation in menus. 
  146.    --  Setting Take_Focus to False is useful only for special applications 
  147.    --  like virtual keyboard implementations which should not take keyboard 
  148.    --  focus. 
  149.    --  The Take_Focus state of a menu or menu bar is automatically propagated 
  150.    --  to submenus whenever a submenu is popped up, so you don't have to worry 
  151.    --  about recursively setting it for your entire menu hierarchy. Only when 
  152.    --  programmatically picking a submenu and popping it up manually, the 
  153.    --  Take_Focus property of the submenu needs to be set explicitely. 
  154.    --  Note that setting it to False has side-effects: 
  155.    --  If the focus is in some other app, it keeps the focus and keynav in the 
  156.    --  menu doesn't work. Consequently, keynav on the menu will only work if 
  157.    --  the focus is on some toplevel owned by the onscreen keyboard. 
  158.    --  To avoid confusing the user, menus with Take_Focus set to False should 
  159.    --  not display mnemonics or accelerators, since it cannot be guaranteed 
  160.    --  that they will work. 
  161.    --  See also gdk_keyboard_grab 
  162.    --  Since: gtk+ 2.8 
  163.    --  "take_focus": True if the menu shell should take the keyboard focus on 
  164.    --  popup 
  165.  
  166.    procedure Insert 
  167.       (Menu_Shell : not null access Gtk_Menu_Shell_Record; 
  168.        Child      : not null access Gtk.Widget.Gtk_Widget_Record'Class; 
  169.        Position   : Gint); 
  170.    --  Adds a new Gtk.Menu_Item.Gtk_Menu_Item to the menu shell's item list at 
  171.    --  the position indicated by Position. 
  172.    --  "child": The Gtk.Menu_Item.Gtk_Menu_Item to add 
  173.    --  "position": The position in the item list where Child is added. 
  174.    --  Positions are numbered from 0 to n-1 
  175.  
  176.    procedure Prepend 
  177.       (Menu_Shell : not null access Gtk_Menu_Shell_Record; 
  178.        Child      : not null access Gtk.Widget.Gtk_Widget_Record'Class); 
  179.    --  Adds a new Gtk.Menu_Item.Gtk_Menu_Item to the beginning of the menu 
  180.    --  shell's item list. 
  181.    --  "child": The Gtk.Menu_Item.Gtk_Menu_Item to add 
  182.  
  183.    procedure Select_First 
  184.       (Menu_Shell       : not null access Gtk_Menu_Shell_Record; 
  185.        Search_Sensitive : Boolean); 
  186.    --  Select the first visible or selectable child of the menu shell; don't 
  187.    --  select tearoff items unless the only item is a tearoff item. 
  188.    --  Since: gtk+ 2.2 
  189.    --  "search_sensitive": if True, search for the first selectable menu item, 
  190.    --  otherwise select nothing if the first item isn't sensitive. This should 
  191.    --  be False if the menu is being popped up initially. 
  192.  
  193.    procedure Select_Item 
  194.       (Menu_Shell : not null access Gtk_Menu_Shell_Record; 
  195.        Menu_Item  : not null access Gtk.Widget.Gtk_Widget_Record'Class); 
  196.    --  Selects the menu item from the menu shell. 
  197.    --  "menu_item": The Gtk.Menu_Item.Gtk_Menu_Item to select 
  198.  
  199.    ---------------- 
  200.    -- Properties -- 
  201.    ---------------- 
  202.    --  The following properties are defined for this widget. See 
  203.    --  Glib.Properties for more information on properties) 
  204.  
  205.    Take_Focus_Property : constant Glib.Properties.Property_Boolean; 
  206.    --  A boolean that determines whether the menu and its submenus grab the 
  207.    --  keyboard focus. See Gtk.Menu_Shell.Set_Take_Focus and 
  208.    --  Gtk.Menu_Shell.Get_Take_Focus. 
  209.  
  210.    ------------- 
  211.    -- Signals -- 
  212.    ------------- 
  213.  
  214.    type Cb_Gtk_Menu_Shell_Boolean_Void is not null access procedure 
  215.      (Self       : access Gtk_Menu_Shell_Record'Class; 
  216.       Force_Hide : Boolean); 
  217.  
  218.    type Cb_GObject_Boolean_Void is not null access procedure 
  219.      (Self       : access Glib.Object.GObject_Record'Class; 
  220.       Force_Hide : Boolean); 
  221.  
  222.    Signal_Activate_Current : constant Glib.Signal_Name := "activate-current"; 
  223.    procedure On_Activate_Current 
  224.       (Self  : not null access Gtk_Menu_Shell_Record; 
  225.        Call  : Cb_Gtk_Menu_Shell_Boolean_Void; 
  226.        After : Boolean := False); 
  227.    procedure On_Activate_Current 
  228.       (Self  : not null access Gtk_Menu_Shell_Record; 
  229.        Call  : Cb_GObject_Boolean_Void; 
  230.        Slot  : not null access Glib.Object.GObject_Record'Class; 
  231.        After : Boolean := False); 
  232.    --  An action signal that activates the current menu item within the menu 
  233.    --  shell. 
  234.  
  235.    type Cb_Gtk_Menu_Shell_Void is not null access procedure (Self : access Gtk_Menu_Shell_Record'Class); 
  236.  
  237.    type Cb_GObject_Void is not null access procedure 
  238.      (Self : access Glib.Object.GObject_Record'Class); 
  239.  
  240.    Signal_Cancel : constant Glib.Signal_Name := "cancel"; 
  241.    procedure On_Cancel 
  242.       (Self  : not null access Gtk_Menu_Shell_Record; 
  243.        Call  : Cb_Gtk_Menu_Shell_Void; 
  244.        After : Boolean := False); 
  245.    procedure On_Cancel 
  246.       (Self  : not null access Gtk_Menu_Shell_Record; 
  247.        Call  : Cb_GObject_Void; 
  248.        Slot  : not null access Glib.Object.GObject_Record'Class; 
  249.        After : Boolean := False); 
  250.    --  An action signal which cancels the selection within the menu shell. 
  251.    --  Causes the Gtk.Menu_Shell.Gtk_Menu_Shell::selection-done signal to be 
  252.    --  emitted. 
  253.  
  254.    type Cb_Gtk_Menu_Shell_Gtk_Direction_Type_Void is not null access procedure 
  255.      (Self      : access Gtk_Menu_Shell_Record'Class; 
  256.       Direction : Gtk.Enums.Gtk_Direction_Type); 
  257.  
  258.    type Cb_GObject_Gtk_Direction_Type_Void is not null access procedure 
  259.      (Self      : access Glib.Object.GObject_Record'Class; 
  260.       Direction : Gtk.Enums.Gtk_Direction_Type); 
  261.  
  262.    Signal_Cycle_Focus : constant Glib.Signal_Name := "cycle-focus"; 
  263.    procedure On_Cycle_Focus 
  264.       (Self  : not null access Gtk_Menu_Shell_Record; 
  265.        Call  : Cb_Gtk_Menu_Shell_Gtk_Direction_Type_Void; 
  266.        After : Boolean := False); 
  267.    procedure On_Cycle_Focus 
  268.       (Self  : not null access Gtk_Menu_Shell_Record; 
  269.        Call  : Cb_GObject_Gtk_Direction_Type_Void; 
  270.        Slot  : not null access Glib.Object.GObject_Record'Class; 
  271.        After : Boolean := False); 
  272.    --  A keybinding signal which moves the focus in the given Direction. 
  273.  
  274.    Signal_Deactivate : constant Glib.Signal_Name := "deactivate"; 
  275.    procedure On_Deactivate 
  276.       (Self  : not null access Gtk_Menu_Shell_Record; 
  277.        Call  : Cb_Gtk_Menu_Shell_Void; 
  278.        After : Boolean := False); 
  279.    procedure On_Deactivate 
  280.       (Self  : not null access Gtk_Menu_Shell_Record; 
  281.        Call  : Cb_GObject_Void; 
  282.        Slot  : not null access Glib.Object.GObject_Record'Class; 
  283.        After : Boolean := False); 
  284.    --  This signal is emitted when a menu shell is deactivated. 
  285.  
  286.    type Cb_Gtk_Menu_Shell_Gtk_Widget_Gint_Void is not null access procedure 
  287.      (Self     : access Gtk_Menu_Shell_Record'Class; 
  288.       Child    : not null access Gtk.Widget.Gtk_Widget_Record'Class; 
  289.       Position : Gint); 
  290.  
  291.    type Cb_GObject_Gtk_Widget_Gint_Void is not null access procedure 
  292.      (Self     : access Glib.Object.GObject_Record'Class; 
  293.       Child    : not null access Gtk.Widget.Gtk_Widget_Record'Class; 
  294.       Position : Gint); 
  295.  
  296.    Signal_Insert : constant Glib.Signal_Name := "insert"; 
  297.    procedure On_Insert 
  298.       (Self  : not null access Gtk_Menu_Shell_Record; 
  299.        Call  : Cb_Gtk_Menu_Shell_Gtk_Widget_Gint_Void; 
  300.        After : Boolean := False); 
  301.    procedure On_Insert 
  302.       (Self  : not null access Gtk_Menu_Shell_Record; 
  303.        Call  : Cb_GObject_Gtk_Widget_Gint_Void; 
  304.        Slot  : not null access Glib.Object.GObject_Record'Class; 
  305.        After : Boolean := False); 
  306.    --  The ::insert signal is emitted when a new Gtk.Menu_Item.Gtk_Menu_Item 
  307.    --  is added to a Gtk.Menu_Shell.Gtk_Menu_Shell. A separate signal is used 
  308.    --  instead of GtkContainer::add because of the need for an additional 
  309.    --  position parameter. 
  310.    -- 
  311.    --  The inverse of this signal is the GtkContainer::removed signal. 
  312.    --  
  313.    --  Callback parameters: 
  314.    --    --  "child": the Gtk.Menu_Item.Gtk_Menu_Item that is being inserted 
  315.    --    --  "position": the position at which the insert occurs 
  316.  
  317.    type Cb_Gtk_Menu_Shell_Gtk_Menu_Direction_Type_Void is not null access procedure 
  318.      (Self      : access Gtk_Menu_Shell_Record'Class; 
  319.       Direction : Gtk.Enums.Gtk_Menu_Direction_Type); 
  320.  
  321.    type Cb_GObject_Gtk_Menu_Direction_Type_Void is not null access procedure 
  322.      (Self      : access Glib.Object.GObject_Record'Class; 
  323.       Direction : Gtk.Enums.Gtk_Menu_Direction_Type); 
  324.  
  325.    Signal_Move_Current : constant Glib.Signal_Name := "move-current"; 
  326.    procedure On_Move_Current 
  327.       (Self  : not null access Gtk_Menu_Shell_Record; 
  328.        Call  : Cb_Gtk_Menu_Shell_Gtk_Menu_Direction_Type_Void; 
  329.        After : Boolean := False); 
  330.    procedure On_Move_Current 
  331.       (Self  : not null access Gtk_Menu_Shell_Record; 
  332.        Call  : Cb_GObject_Gtk_Menu_Direction_Type_Void; 
  333.        Slot  : not null access Glib.Object.GObject_Record'Class; 
  334.        After : Boolean := False); 
  335.    --  An keybinding signal which moves the current menu item in the direction 
  336.    --  specified by Direction. 
  337.  
  338.    type Cb_Gtk_Menu_Shell_Gint_Boolean is not null access function 
  339.      (Self     : access Gtk_Menu_Shell_Record'Class; 
  340.       Distance : Gint) return Boolean; 
  341.  
  342.    type Cb_GObject_Gint_Boolean is not null access function 
  343.      (Self     : access Glib.Object.GObject_Record'Class; 
  344.       Distance : Gint) return Boolean; 
  345.  
  346.    Signal_Move_Selected : constant Glib.Signal_Name := "move-selected"; 
  347.    procedure On_Move_Selected 
  348.       (Self  : not null access Gtk_Menu_Shell_Record; 
  349.        Call  : Cb_Gtk_Menu_Shell_Gint_Boolean; 
  350.        After : Boolean := False); 
  351.    procedure On_Move_Selected 
  352.       (Self  : not null access Gtk_Menu_Shell_Record; 
  353.        Call  : Cb_GObject_Gint_Boolean; 
  354.        Slot  : not null access Glib.Object.GObject_Record'Class; 
  355.        After : Boolean := False); 
  356.    --  The ::move-selected signal is emitted to move the selection to another 
  357.    --  item. 
  358.    --  
  359.    --  Callback parameters: 
  360.    --    --  "distance": +1 to move to the next item, -1 to move to the previous 
  361.    --    --  Returns True to stop the signal emission, False to continue 
  362.  
  363.    Signal_Selection_Done : constant Glib.Signal_Name := "selection-done"; 
  364.    procedure On_Selection_Done 
  365.       (Self  : not null access Gtk_Menu_Shell_Record; 
  366.        Call  : Cb_Gtk_Menu_Shell_Void; 
  367.        After : Boolean := False); 
  368.    procedure On_Selection_Done 
  369.       (Self  : not null access Gtk_Menu_Shell_Record; 
  370.        Call  : Cb_GObject_Void; 
  371.        Slot  : not null access Glib.Object.GObject_Record'Class; 
  372.        After : Boolean := False); 
  373.    --  This signal is emitted when a selection has been completed within a 
  374.    --  menu shell. 
  375.  
  376.    ---------------- 
  377.    -- Interfaces -- 
  378.    ---------------- 
  379.    --  This class implements several interfaces. See Glib.Types 
  380.    -- 
  381.    --  - "Buildable" 
  382.  
  383.    package Implements_Gtk_Buildable is new Glib.Types.Implements 
  384.      (Gtk.Buildable.Gtk_Buildable, Gtk_Menu_Shell_Record, Gtk_Menu_Shell); 
  385.    function "+" 
  386.      (Widget : access Gtk_Menu_Shell_Record'Class) 
  387.    return Gtk.Buildable.Gtk_Buildable 
  388.    renames Implements_Gtk_Buildable.To_Interface; 
  389.    function "-" 
  390.      (Interf : Gtk.Buildable.Gtk_Buildable) 
  391.    return Gtk_Menu_Shell 
  392.    renames Implements_Gtk_Buildable.To_Object; 
  393.  
  394. private 
  395.    Take_Focus_Property : constant Glib.Properties.Property_Boolean := 
  396.      Glib.Properties.Build ("take-focus"); 
  397. end Gtk.Menu_Shell;