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