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