## Documentation

Table of Contents
Class Inheritance Tree
Widget Screenshots
Package groups

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.     -----------------------------------------------------------------------

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>

188.     with Glib.ErrorTo API docTo specTo body;

189.     with Glib.ObjectTo API docTo specTo body;

190.     with Glib.PropertiesTo API docTo specTo body;

191.     with Gtk.Accel_GroupTo API docTo specTo body;

192.     with Gtk.ActionTo API docTo specTo body;

193.     with Gtk.Action_GroupTo API docTo specTo body;

194.     with Gtk.WidgetTo API docTo specTo body;

196.     package Gtk.UI_ManagerTo API docTo specTo body is

198.        type Gtk_UI_Manager_Record is new Glib.Object.GObject_RecordTo API docTo specTo body with

199.          null record;

200.        type Gtk_UI_Manager is access all Gtk_UI_Manager_RecordTo API docTo spec'Class;

202.        type Manager_Item_Type is mod 2 ** 16;

203.        Manager_Auto        : constant Manager_Item_TypeTo API docTo spec := 2 ** 0;

204.        Manager_Menubar     : constant Manager_Item_TypeTo API docTo spec := 2 ** 1;

205.        Manager_Menu        : constant Manager_Item_TypeTo API docTo spec := 2 ** 2;

206.        Manager_Toolbar     : constant Manager_Item_TypeTo API docTo spec := 2 ** 3;

207.        Manager_Placeholder : constant Manager_Item_TypeTo API docTo spec := 2 ** 4;

208.        Manager_Popup       : constant Manager_Item_TypeTo API docTo spec := 2 ** 5;

209.        Manager_Menuitem    : constant Manager_Item_TypeTo API docTo spec := 2 ** 6;

210.        Manager_Toolitem    : constant Manager_Item_TypeTo API docTo spec := 2 ** 7;

211.        Manager_Separator   : constant Manager_Item_TypeTo API docTo spec := 2 ** 8;

212.        Manager_Accelerator : constant Manager_Item_TypeTo API docTo spec := 2 ** 9;

213.        --  These enumeration values are used by Add_UI to determine what UI element

214.        --  to create.

216.        --------------

217.        -- Creation --

218.        --------------

220.        procedure Gtk_NewTo API docTo body    (UI : out Gtk_UI_ManagerTo API docTo spec);

221.        procedure InitializeTo API docTo body (UI : access Gtk_UI_Manager_RecordTo API docTo spec'Class);

222.        --  Creates a new ui manager object.

224.        function Get_TypeTo API docTo body return GTypeTo API docTo spec;

225.        --  Return the internal value associated with a Gtk_UI_Manager.

227.        function New_Merge_IdTo API docTo body

228.          (Self : access Gtk_UI_Manager_RecordTo API docTo spec) return GuintTo API docTo spec;

229.        --  Returns an unused merge id, suitable for use with Add_UI.

231.        procedure Ensure_UpdateTo API docTo body (Self : access Gtk_UI_Manager_RecordTo API docTo spec);

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

244.        ----------------------

245.        -- Merging contents --

246.        ----------------------

248.        procedure Add_UITo API docTo body

249.          (Self     : access Gtk_UI_Manager_RecordTo API docTo spec;

250.           Merge_Id : GuintTo API docTo spec;

251.           Path     : String;

252.           Name     : String;

253.           Action   : String := "";

254.           Typ      : Manager_Item_TypeTo API docTo spec := Manager_AutoTo API docTo spec;

255.           Top      : Boolean := False);

256.        procedure Remove_UITo API docTo body

257.          (Self     : access Gtk_UI_Manager_RecordTo API docTo spec;

258.           Merge_Id : GuintTo API docTo spec);

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.

272.        function Add_UI_From_FileTo API docTo body

273.          (Self     : access Gtk_UI_Manager_RecordTo API docTo spec;

274.           Filename : String;

275.           Error    : Glib.Error.GError_AccessTo API docTo spec := null) return GuintTo API docTo spec;

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.

282.        function Add_UI_From_StringTo API docTo body

283.          (Self   : access Gtk_UI_Manager_RecordTo API docTo spec;

284.           Buffer : String;

285.           Error  : Glib.Error.GError_AccessTo API docTo spec := null) return GuintTo API docTo spec;

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.

293.        procedure Insert_Action_GroupTo API docTo body

294.          (Self         : access Gtk_UI_Manager_RecordTo API docTo spec;

295.           Action_Group : access Gtk.Action_Group.Gtk_Action_Group_RecordTo API docTo spec'Class;

296.           Pos          : GintTo API docTo spec);

297.        procedure Remove_Action_GroupTo API docTo body

298.          (Self         : access Gtk_UI_Manager_RecordTo API docTo spec;

299.           Action_Group : access Gtk.Action_Group.Gtk_Action_Group_RecordTo API docTo spec'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.

305.        -----------------------

306.        -- Querying contents --

307.        -----------------------

309.        function Get_Accel_GroupTo API docTo body

310.          (Self : access Gtk_UI_Manager_RecordTo API docTo spec)

311.           return Gtk.Accel_Group.Gtk_Accel_GroupTo API docTo spec;

312.        --  Returns the Gtk_Accel_Group associated with Self.

314.        function Get_ActionTo API docTo body

315.          (Self : access Gtk_UI_Manager_RecordTo API docTo spec; Path : String)

316.           return Gtk.Action.Gtk_ActionTo API docTo spec;

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.

322.        function Get_Action_GroupsTo API docTo body

323.          (Self : access Gtk_UI_Manager_RecordTo API docTo spec)

324.          return Glib.Object.Object_Simple_List.GlistTo API docTo specTo body;

325.        --  Returns the list of action groups associated with Self. The returned

326.        --  list should not be modified.

328.        procedure Set_Add_TearoffsTo API docTo body

329.          (Self         : access Gtk_UI_Manager_RecordTo API docTo spec;

330.           Add_Tearoffs : Boolean);

331.        function Get_Add_TearoffsTo API docTo body

332.          (Self : access Gtk_UI_Manager_RecordTo API docTo spec) 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.

338.        function Get_ToplevelsTo API docTo body

339.          (Self  : access Gtk_UI_Manager_RecordTo API docTo spec;

340.           Types : Manager_Item_TypeTo API docTo spec)

341.           return Gtk.Widget.Widget_SList.GSlistTo API docTo specTo body;

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.

346.        function Get_UITo API docTo body (Self : access Gtk_UI_Manager_RecordTo API docTo spec) return String;

347.        --  Create a UI definition of the merged UI

349.        function Get_WidgetTo API docTo body

350.          (Self : access Gtk_UI_Manager_RecordTo API docTo spec;

351.           Path : String)

352.           return Gtk.Widget.Gtk_WidgetTo API docTo spec;

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.

369.        ----------------

370.        -- Properties --

371.        ----------------

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>

387.        Add_Tearoffs_Property : constant Glib.Properties.Property_BooleanTo API docTo spec;

388.        UI_Property           : constant Glib.Properties.Property_StringTo API docTo spec;

390.        -------------

391.        -- Signals --

392.        -------------

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>

445.        Signal_Actions_Changed  : constant Glib.Signal_NameTo API docTo spec := "actions_changed";

446.        Signal_Add_Widget       : constant Glib.Signal_NameTo API docTo spec := "add_widget";

447.        Signal_Connect_Proxy    : constant Glib.Signal_NameTo API docTo spec := "connect_proxy";

448.        Signal_Disconnect_Proxy : constant Glib.Signal_NameTo API docTo spec := "disconnect_proxy";

449.        Signal_Post_Activate    : constant Glib.Signal_NameTo API docTo spec := "post_activate";

450.        Signal_Pre_Activate     : constant Glib.Signal_NameTo API docTo spec := "pre_activate";

452.     private

453.        Add_Tearoffs_PropertyTo API docTo spec : constant Glib.Properties.Property_BooleanTo API docTo spec :=

454.          Glib.Properties.BuildTo API docTo specTo body ("add-tearoffs");

455.        Ui_PropertyTo API docTo spec : constant Glib.Properties.Property_StringTo API docTo spec :=

456.          Glib.Properties.BuildTo API docTo specTo body ("ui");

458.        pragma Import (C, Get_TypeTo API docTo spec, "gtk_ui_manager_get_type");

460.     end Gtk.UI_ManagerTo API docTo specTo body;