1. ----------------------------------------------------------------------- 
  2. --              GtkAda - Ada95 binding for Gtk+/Gnome                -- 
  3. --                                                                   -- 
  4. --                Copyright (C) 2006-2007 AdaCore                    -- 
  5. --                                                                   -- 
  6. -- This library is free software; you can redistribute it and/or     -- 
  7. -- modify it under the terms of the GNU General Public               -- 
  8. -- License as published by the Free Software Foundation; either      -- 
  9. -- version 2 of the License, or (at your option) any later version.  -- 
  10. --                                                                   -- 
  11. -- This library is distributed in the hope that it will be useful,   -- 
  12. -- but WITHOUT ANY WARRANTY; without even the implied warranty of    -- 
  13. -- MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU -- 
  14. -- General Public License for more details.                          -- 
  15. --                                                                   -- 
  16. -- You should have received a copy of the GNU General Public         -- 
  17. -- License along with this library; if not, write to the             -- 
  18. -- Free Software Foundation, Inc., 59 Temple Place - Suite 330,      -- 
  19. -- Boston, MA 02111-1307, USA.                                       -- 
  20. --                                                                   -- 
  21. -- As a special exception, if other files instantiate generics from  -- 
  22. -- this unit, or you link this unit with other files to produce an   -- 
  23. -- executable, this  unit  does not  by itself cause  the resulting  -- 
  24. -- executable to be covered by the GNU General Public License. This  -- 
  25. -- exception does not however invalidate any other reasons why the   -- 
  26. -- executable file  might be covered by the  GNU Public License.     -- 
  27. ----------------------------------------------------------------------- 
  28.  
  29. --  <description> 
  30. --  A Gtk_UI_Manager constructs a user interface (menus and toolbars) from one 
  31. --  or more UI definitions, which reference actions from one or more action 
  32. --  groups. 
  33. -- 
  34. --------------------- 
  35. --  UI Definitions -- 
  36. --------------------- 
  37. -- 
  38. --  The UI definitions are specified in an XML format which can be roughly 
  39. --  described by the following DTD. 
  40. --    - <!ELEMENT ui          (menubar|toolbar|popup|accelerator)* > 
  41. --    - <!ELEMENT menubar     (menuitem|separator|placeholder|menu)* > 
  42. --    - <!ELEMENT menu        (menuitem|separator|placeholder|menu)* > 
  43. --    - <!ELEMENT popup       (menuitem|separator|placeholder|menu)* > 
  44. --    - <!ELEMENT toolbar     (toolitem|separator|placeholder)* > 
  45. --    - <!ELEMENT placeholder (menuitem|toolitem|separator|placeholder|menu)* > 
  46. --    - <!ELEMENT menuitem     EMPTY > 
  47. --    - <!ELEMENT toolitem     (menu?) > 
  48. --    - <!ELEMENT separator    EMPTY > 
  49. --    - <!ELEMENT accelerator  EMPTY > 
  50. --    - <!ATTLIST menubar      name                  #IMPLIED 
  51. --    -                        action                #IMPLIED > 
  52. --    - <!ATTLIST toolbar      name                  #IMPLIED 
  53. --    -                        action                #IMPLIED > 
  54. --    - <!ATTLIST popup        name                  #IMPLIED 
  55. --    -                        action                #IMPLIED > 
  56. --    - <!ATTLIST placeholder  name                  #IMPLIED 
  57. --    -                        action                #IMPLIED > 
  58. --    - <!ATTLIST separator    name                  #IMPLIED 
  59. --    -                        action                #IMPLIED 
  60. --    -                        expand   (true|false) #IMPLIED > 
  61. --    - <!ATTLIST menu         name                  #IMPLIED 
  62. --    -                        action                #REQUIRED 
  63. --    -                        position (top|bot)    #IMPLIED > 
  64. --    - <!ATTLIST menuitem     name                  #IMPLIED 
  65. --    -                        action                #REQUIRED 
  66. --    -                        position (top|bot)    #IMPLIED > 
  67. --    - <!ATTLIST toolitem     name                  #IMPLIED 
  68. --    -                        action                #REQUIRED 
  69. --    -                        position (top|bot)    #IMPLIED > 
  70. --    - <!ATTLIST accelerator  name                  #IMPLIED 
  71. --    -                        action                #REQUIRED > 
  72. -- 
  73. --  There are some additional restrictions beyond those specified in the DTD, 
  74. --  e.g. every toolitem must have a toolbar in its ancestry and every menuitem 
  75. --  must have a menubar or popup in its ancestry. Since a GMarkup parser is 
  76. --  used to parse the UI description, it must not only be valid XML, but valid 
  77. --  GMarkup. 
  78. -- 
  79. --  If a name is not specified, it defaults to the action. If an action is not 
  80. --  specified either, the element name is used. The name and action attributes 
  81. --  must not contain '/' characters after parsing (since that would mess up 
  82. --  path lookup) and must be usable as XML attributes when enclosed in 
  83. --  doublequotes, thus they must not '"' characters or references to the &quot; 
  84. --  entity. 
  85. -- 
  86. --  Here is an example: 
  87. --  <example> 
  88. --  <ui> 
  89. --     <menubar> 
  90. --       <menu name="FileMenu" action="FileMenuAction"> 
  91. --         <menuitem name="New" action="New2Action" /> 
  92. --         <placeholder name="FileMenuAdditions" /> 
  93. --       </menu> 
  94. --       <menu name="JustifyMenu" action="JustifyMenuAction"> 
  95. --         <menuitem name="Left" action="justify-left"/> 
  96. --         <menuitem name="Centre" action="justify-center"/> 
  97. --         <menuitem name="Right" action="justify-right"/> 
  98. --         <menuitem name="Fill" action="justify-fill"/> 
  99. --       </menu> 
  100. --     </menubar> 
  101. --     <toolbar action="toolbar1"> 
  102. --       <placeholder name="JustifyToolItems"> 
  103. --       <separator/> 
  104. --       <toolitem name="Left" action="justify-left"/> 
  105. --       <toolitem name="Centre" action="justify-center"/> 
  106. --       <toolitem name="Right" action="justify-right"/> 
  107. --       <toolitem name="Fill" action="justify-fill"/> 
  108. --       <separator/> 
  109. --     </placeholder> 
  110. --    </toolbar> 
  111. --  </ui> 
  112. --  </example> 
  113. -- 
  114. --  The constructed widget hierarchy is very similar to the element tree of the 
  115. --  XML, with the exception that placeholders are merged into their parents. 
  116. --  The correspondence of XML elements to widgets should be almost obvious: 
  117. -- 
  118. --  - menubar  : a Gtk_Menu_Bar 
  119. --  - toolbar  : a Gtk_Toolbar 
  120. --  - popup    : a toplevel Gtk_Menu 
  121. --  - menu     : a Gtk_Menu attached to a menuitem 
  122. --  - menuitem : a Gtk_Menu_Item subclass, the exact type depends on the action 
  123. --  - toolitem : a Gtk_Tool_Item subclass, exact type depends on the action. 
  124. --               This may contain a menu element only if the associated action 
  125. --               specifies a Gtk_Menu_Tool_Button as proxy 
  126. --  - separator   : a Gtk_Separator_Menu_Item or Gtk_Separator_Tool_Item 
  127. --  - accelerator : a keyboard accelerator 
  128. -- 
  129. --  The "position" attribute determines where a constructed widget is 
  130. --  positioned wrt. to its siblings in the partially constructed tree. If it is 
  131. --  "top", the widget is prepended, otherwise it is appended. 
  132. -- 
  133. ----------------- 
  134. --  UI Merging -- 
  135. ----------------- 
  136. -- 
  137. --  The most remarkable feature of Gtk_UI_Manager is that it can overlay a set 
  138. --  of menuitems and toolitems over another one, and demerge them later. 
  139. -- 
  140. --  Merging is done based on the names of the XML elements. Each element is 
  141. --  identified by a path which consists of the names of its anchestors, 
  142. --  separated by slashes. For example, the menuitem named "Left" in the example 
  143. --  above has the path /ui/menubar/JustifyMenu/Left and the toolitem with the 
  144. --  same name has path /ui/toolbar1/JustifyToolItems/Left. 
  145. -- 
  146. ------------------- 
  147. --  Accelerators -- 
  148. ------------------- 
  149. -- 
  150. --  Every action has an accelerator path. Accelerators are installed together 
  151. --  with menuitem proxies, but they can also be explicitly added with 
  152. --  <accelerator> elements in the UI definition. This makes it possible to have 
  153. --  accelerators for actions even if they have no visible proxies. 
  154. -- 
  155. ----------------------- 
  156. --  Smart Separators -- 
  157. ----------------------- 
  158. -- 
  159. --  The separators created by Gtk_UI_Manager are "smart", i.e. they do not show 
  160. --  up in the UI unless they end up between two visible menu or tool items. 
  161. --  Separators which are located at the very beginning or end of the menu or 
  162. --  toolbar containing them, or multiple separators next to each other, are 
  163. --  hidden. This is a useful feature, since the merging of UI elements from 
  164. --  multiple sources can make it hard or impossible to determine in advance 
  165. --  whether a separator will end up in such an unfortunate position. 
  166. -- 
  167. --  For separators in toolbars, you can set expand="true" to turn them from a 
  168. --  small, visible separator to an expanding, invisible one. Toolitems 
  169. --  following an expanding separator are effectively right-aligned. 
  170. -- 
  171. ------------------ 
  172. --  Empty Menus -- 
  173. ------------------ 
  174. -- 
  175. --  Submenus pose similar problems to separators inconnection with merging. It 
  176. --  is impossible to know in advance whether they will end up empty after 
  177. --  merging. Gtk_UI_Manager offers two ways to treat empty submenus: 
  178. -- 
  179. --    - make them disappear by hiding the menu item they're attached to 
  180. --    - add an insensitive "Empty" item 
  181. -- 
  182. --  The behaviour is chosen based on the "hide_if_empty" property of the action 
  183. --  to which the submenu is associated. 
  184. --  </description> 
  185. --  <c_version>2.8.17</c_version> 
  186. --  <group>Action-based menus</group> 
  187.  
  188. with Glib.Error; 
  189. with Glib.Object; 
  190. with Glib.Properties; 
  191. with Gtk.Accel_Group; 
  192. with Gtk.Action; 
  193. with Gtk.Action_Group; 
  194. with Gtk.Widget; 
  195.  
  196. package Gtk.UI_Manager is 
  197.  
  198.    type Gtk_UI_Manager_Record is new Glib.Object.GObject_Record with 
  199.      null record; 
  200.    type Gtk_UI_Manager is access all Gtk_UI_Manager_Record'Class; 
  201.  
  202.    type Manager_Item_Type is mod 2 ** 16; 
  203.    Manager_Auto        : constant Manager_Item_Type := 2 ** 0; 
  204.    Manager_Menubar     : constant Manager_Item_Type := 2 ** 1; 
  205.    Manager_Menu        : constant Manager_Item_Type := 2 ** 2; 
  206.    Manager_Toolbar     : constant Manager_Item_Type := 2 ** 3; 
  207.    Manager_Placeholder : constant Manager_Item_Type := 2 ** 4; 
  208.    Manager_Popup       : constant Manager_Item_Type := 2 ** 5; 
  209.    Manager_Menuitem    : constant Manager_Item_Type := 2 ** 6; 
  210.    Manager_Toolitem    : constant Manager_Item_Type := 2 ** 7; 
  211.    Manager_Separator   : constant Manager_Item_Type := 2 ** 8; 
  212.    Manager_Accelerator : constant Manager_Item_Type := 2 ** 9; 
  213.    --  These enumeration values are used by Add_UI to determine what UI element 
  214.    --  to create. 
  215.  
  216.    -------------- 
  217.    -- Creation -- 
  218.    -------------- 
  219.  
  220.    procedure Gtk_New    (UI : out Gtk_UI_Manager); 
  221.    procedure Initialize (UI : access Gtk_UI_Manager_Record'Class); 
  222.    --  Creates a new ui manager object. 
  223.  
  224.    function Get_Type return GType; 
  225.    --  Return the internal value associated with a Gtk_UI_Manager. 
  226.  
  227.    function New_Merge_Id 
  228.      (Self : access Gtk_UI_Manager_Record) return Guint; 
  229.    --  Returns an unused merge id, suitable for use with Add_UI. 
  230.  
  231.    procedure Ensure_Update (Self : access Gtk_UI_Manager_Record); 
  232.    --  Makes sure that all pending updates to the UI have been completed. 
  233.    --  This may occasionally be necessary, since Gtk_UI_Manager updates the 
  234.    --  UI in an idle function. A typical example where this function is 
  235.    --  useful is to enforce that the menubar and toolbar have been added to 
  236.    --  the main window before showing it: 
  237.    --      Add (Window, Vbox); 
  238.    --      Connect (Merge, "add_widget", Add_Widget'Access, Vbox); 
  239.    --      Add_UI_From_File (Merge, "my-menus"); 
  240.    --      Add_UI_From_File (Merge, "my-toolbars"); 
  241.    --      Ensure_Update (Merge); 
  242.    --      Show (Window); 
  243.  
  244.    ---------------------- 
  245.    -- Merging contents -- 
  246.    ---------------------- 
  247.  
  248.    procedure Add_UI 
  249.      (Self     : access Gtk_UI_Manager_Record; 
  250.       Merge_Id : Guint; 
  251.       Path     : String; 
  252.       Name     : String; 
  253.       Action   : String := ""; 
  254.       Typ      : Manager_Item_Type := Manager_Auto; 
  255.       Top      : Boolean := False); 
  256.    procedure Remove_UI 
  257.      (Self     : access Gtk_UI_Manager_Record; 
  258.       Merge_Id : Guint); 
  259.    --  Adds a UI element to the current contents of Self. 
  260.    -- 
  261.    --  If Typ is Manager_Auto, GTK+ inserts a menuitem, toolitem or separator 
  262.    --  if such an element can be inserted at the place determined by Path. 
  263.    --  Otherwise Typ must indicate an element that can be inserted at the place 
  264.    --  determined by Path. 
  265.    -- 
  266.    --  If Path points to a menuitem or toolitem, the new element will be 
  267.    --  inserted before or after this item, depending on Top. 
  268.    -- 
  269.    --  Merge_Id: see New_Merge_Id. 
  270.    --  Action should be the empty string for a separator. 
  271.  
  272.    function Add_UI_From_File 
  273.      (Self     : access Gtk_UI_Manager_Record; 
  274.       Filename : String; 
  275.       Error    : Glib.Error.GError_Access := null) return Guint; 
  276.    --  Parses a file containing a UI definition and merges it with the current 
  277.    --  contents of Self. 
  278.    --  Return value: The merge id for the merged UI. The merge id can be used 
  279.    --  to unmerge the UI with Remove_UI. If an error occurred, the return value 
  280.    --  is 0, and if Error was specified it is set to the error message. 
  281.  
  282.    function Add_UI_From_String 
  283.      (Self   : access Gtk_UI_Manager_Record; 
  284.       Buffer : String; 
  285.       Error  : Glib.Error.GError_Access := null) return Guint; 
  286.    --  Parses a string containing a UI definition and merges it with the 
  287.    --  current contents of Self. An enclosing <ui> element is added if it is 
  288.    --  missing. 
  289.    --  Return value: The merge id for the merged UI. The merge id can be used 
  290.    --  to unmerge the UI with Remove_UI. If an error occurred, the return value 
  291.    --  is 0, and if Error was specified it is set to the error message. 
  292.  
  293.    procedure Insert_Action_Group 
  294.      (Self         : access Gtk_UI_Manager_Record; 
  295.       Action_Group : access Gtk.Action_Group.Gtk_Action_Group_Record'Class; 
  296.       Pos          : Gint); 
  297.    procedure Remove_Action_Group 
  298.      (Self         : access Gtk_UI_Manager_Record; 
  299.       Action_Group : access Gtk.Action_Group.Gtk_Action_Group_Record'Class); 
  300.    --  Inserts an action group into the list of action groups associated 
  301.    --  with Self. Actions in earlier groups hide actions with the same 
  302.    --  name in later groups. 
  303.    --  with Self. 
  304.  
  305.    ----------------------- 
  306.    -- Querying contents -- 
  307.    ----------------------- 
  308.  
  309.    function Get_Accel_Group 
  310.      (Self : access Gtk_UI_Manager_Record) 
  311.       return Gtk.Accel_Group.Gtk_Accel_Group; 
  312.    --  Returns the Gtk_Accel_Group associated with Self. 
  313.  
  314.    function Get_Action 
  315.      (Self : access Gtk_UI_Manager_Record; Path : String) 
  316.       return Gtk.Action.Gtk_Action; 
  317.    --  Looks up an action by following a path. See Get_Widget for more 
  318.    --  information about paths. 
  319.    --  Returns the action whose proxy widget is found by following the path, 
  320.    --  or null if no widget was found. 
  321.  
  322.    function Get_Action_Groups 
  323.      (Self : access Gtk_UI_Manager_Record) 
  324.      return Glib.Object.Object_Simple_List.Glist; 
  325.    --  Returns the list of action groups associated with Self. The returned 
  326.    --  list should not be modified. 
  327.  
  328.    procedure Set_Add_Tearoffs 
  329.      (Self         : access Gtk_UI_Manager_Record; 
  330.       Add_Tearoffs : Boolean); 
  331.    function Get_Add_Tearoffs 
  332.      (Self : access Gtk_UI_Manager_Record) return Boolean; 
  333.    --  Sets the "add_tearoffs" property, which controls whether menus 
  334.    --  generated by this Gtk_UI_Manager will have tearoff menu items. 
  335.    --  Note that this only affects regular menus. Generated popup 
  336.    --  menus never have tearoff menu items. 
  337.  
  338.    function Get_Toplevels 
  339.      (Self  : access Gtk_UI_Manager_Record; 
  340.       Types : Manager_Item_Type) 
  341.       return Gtk.Widget.Widget_SList.GSlist; 
  342.    --  Obtains a list of all toplevel widgets of the requested types. 
  343.    --  Types may contain Manager_Menubar, Manager_Toolbar or Manager_Popup. 
  344.    --  The returned list must be freed by the caller. 
  345.  
  346.    function Get_UI (Self : access Gtk_UI_Manager_Record) return String; 
  347.    --  Create a UI definition of the merged UI 
  348.  
  349.    function Get_Widget 
  350.      (Self : access Gtk_UI_Manager_Record; 
  351.       Path : String) 
  352.       return Gtk.Widget.Gtk_Widget; 
  353.    --  Looks up a widget by following a path. 
  354.    --  The path consists of the names specified in the XML description of the 
  355.    --  UI. separated by '/'. Elements which don't have a name or action 
  356.    --  attribute in the XML (e.g. &lt;popup&gt;) can be addressed by their XML 
  357.    --  element name (e.g. "popup"). The root element ("/ui") can be omitted in 
  358.    --  the path. 
  359.    -- 
  360.    --  Note that the widget found by following a path that ends in a 
  361.    --  <menu>; element is the menuitem to which the menu is attached, not 
  362.    --  the menu itself. 
  363.    -- 
  364.    --  Also note that the widgets constructed by a ui manager are not tied to 
  365.    --  the lifecycle of the ui manager. If you add the widgets returned by this 
  366.    --  function to some container or explicitly ref them, they will survive the 
  367.    --  destruction of the ui manager. 
  368.  
  369.    ---------------- 
  370.    -- Properties -- 
  371.    ---------------- 
  372.  
  373.    --  <properties> 
  374.    --  The following properties are defined for this widget. See 
  375.    --  Glib.Properties for more information on properties. 
  376.    -- 
  377.    --  Name:  Add_Tearoffs_Property 
  378.    --  Type:  Boolean 
  379.    --  Descr: Whether tearoff menu items should be added to menus 
  380.    -- 
  381.    --  Name:  Ui_Property 
  382.    --  Type:  String 
  383.    --  Descr: An XML string describing the merged UI 
  384.    -- 
  385.    --  </properties> 
  386.  
  387.    Add_Tearoffs_Property : constant Glib.Properties.Property_Boolean; 
  388.    UI_Property           : constant Glib.Properties.Property_String; 
  389.  
  390.    ------------- 
  391.    -- Signals -- 
  392.    ------------- 
  393.  
  394.    --  <signals> 
  395.    --  The following new signals are defined for this widget: 
  396.    -- 
  397.    --  - "actions_changed" 
  398.    --    procedure Handler (UI : access Gtk_UI_Manager_Record'Class); 
  399.    --    This signal is emitted whenever the set of actions changes. 
  400.    -- 
  401.    --  - "add_widget" 
  402.    --    procedure Handler 
  403.    --       (UI     : access Gtk_UI_Manager_Record'Class; 
  404.    --        Widget : access Gtk_Widget_Record'Class); 
  405.    --    The add_widget signal is emitted for each generated menubar and 
  406.    --    toolbar. It is not emitted for generated popup menus, which can be 
  407.    --    obtained by Get_Widget. 
  408.    -- 
  409.    --  - "connect_proxy" 
  410.    --    procedure Handler 
  411.    --       (UI     : access Gtk_UI_Manager_Record'Class; 
  412.    --        Action : access Gtk_Action_Record'Class; 
  413.    --        Proxy  : access Gtk_Widget_Record'Class); 
  414.    --    This signal is emitted after connecting a proxy to an action in the 
  415.    --    group. 
  416.    --    This is intended for simple customizations for which a custom action 
  417.    --    class would be too clumsy, e.g. showing tooltips for menuitems in the 
  418.    --    statusbar. 
  419.    -- 
  420.    --  - "disconnect_proxy" 
  421.    --    procedure Handler 
  422.    --       (UI     : access Gtk_UI_Manager_Record'Class; 
  423.    --        Action : access Gtk_Action_Record'Class; 
  424.    --        Proxy  : access Gtk_Widget_Record'Class); 
  425.    --    The disconnect_proxy signal is emitted after disconnecting a proxy 
  426.    --    from an action in the group. 
  427.    -- 
  428.    --  - "post_activate" 
  429.    --    procedure Handler 
  430.    --       (UI     : access Gtk_UI_Manager_Record'Class; 
  431.    --        Action : access Gtk_Action_Record'Class); 
  432.    --    The post_activate signal is emitted just after the action is 
  433.    --    activated. This is intended for applications to get notification just 
  434.    --    after any action is activated. 
  435.    -- 
  436.    --  - "pre_activate" 
  437.    --    procedure Handler 
  438.    --       (UI     : access Gtk_UI_Manager_Record'Class; 
  439.    --        Action : access Gtk_Action_Record'Class); 
  440.    --    The pre_activate signal is emitted just before the action is 
  441.    --    activated. This is intended for applications to get notification just 
  442.    --    before any action is activated. 
  443.    --  </signals> 
  444.  
  445.    Signal_Actions_Changed  : constant Glib.Signal_Name := "actions_changed"; 
  446.    Signal_Add_Widget       : constant Glib.Signal_Name := "add_widget"; 
  447.    Signal_Connect_Proxy    : constant Glib.Signal_Name := "connect_proxy"; 
  448.    Signal_Disconnect_Proxy : constant Glib.Signal_Name := "disconnect_proxy"; 
  449.    Signal_Post_Activate    : constant Glib.Signal_Name := "post_activate"; 
  450.    Signal_Pre_Activate     : constant Glib.Signal_Name := "pre_activate"; 
  451.  
  452. private 
  453.    Add_Tearoffs_Property : constant Glib.Properties.Property_Boolean := 
  454.      Glib.Properties.Build ("add-tearoffs"); 
  455.    Ui_Property : constant Glib.Properties.Property_String := 
  456.      Glib.Properties.Build ("ui"); 
  457.  
  458.    pragma Import (C, Get_Type, "gtk_ui_manager_get_type"); 
  459.  
  460. end Gtk.UI_Manager;