-----------------------------------------------------------------------
-- GtkAda - Ada95 binding for Gtk+/Gnome --
-- --
-- Copyright (C) 2006-2007 AdaCore --
-- --
-- This library is free software; you can redistribute it and/or --
-- modify it under the terms of the GNU General Public --
-- License as published by the Free Software Foundation; either --
-- version 2 of the License, or (at your option) any later version. --
-- --
-- This library is distributed in the hope that it will be useful, --
-- but WITHOUT ANY WARRANTY; without even the implied warranty of --
-- MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU --
-- General Public License for more details. --
-- --
-- You should have received a copy of the GNU General Public --
-- License along with this library; if not, write to the --
-- Free Software Foundation, Inc., 59 Temple Place - Suite 330, --
-- Boston, MA 02111-1307, USA. --
-- --
-- As a special exception, if other files instantiate generics from --
-- this unit, or you link this unit with other files to produce an --
-- executable, this unit does not by itself cause the resulting --
-- executable to be covered by the GNU General Public License. This --
-- exception does not however invalidate any other reasons why the --
-- executable file might be covered by the GNU Public License. --
-----------------------------------------------------------------------
-- <description>
-- A Gtk_UI_Manager constructs a user interface (menus and toolbars) from one
-- or more UI definitions, which reference actions from one or more action
-- groups.
--
---------------------
-- UI Definitions --
---------------------
--
-- The UI definitions are specified in an XML format which can be roughly
-- described by the following DTD.
-- - <!ELEMENT ui (menubar|toolbar|popup|accelerator)* >
-- - <!ELEMENT menubar (menuitem|separator|placeholder|menu)* >
-- - <!ELEMENT menu (menuitem|separator|placeholder|menu)* >
-- - <!ELEMENT popup (menuitem|separator|placeholder|menu)* >
-- - <!ELEMENT toolbar (toolitem|separator|placeholder)* >
-- - <!ELEMENT placeholder (menuitem|toolitem|separator|placeholder|menu)* >
-- - <!ELEMENT menuitem EMPTY >
-- - <!ELEMENT toolitem (menu?) >
-- - <!ELEMENT separator EMPTY >
-- - <!ELEMENT accelerator EMPTY >
-- - <!ATTLIST menubar name #IMPLIED
-- - action #IMPLIED >
-- - <!ATTLIST toolbar name #IMPLIED
-- - action #IMPLIED >
-- - <!ATTLIST popup name #IMPLIED
-- - action #IMPLIED >
-- - <!ATTLIST placeholder name #IMPLIED
-- - action #IMPLIED >
-- - <!ATTLIST separator name #IMPLIED
-- - action #IMPLIED
-- - expand (true|false) #IMPLIED >
-- - <!ATTLIST menu name #IMPLIED
-- - action #REQUIRED
-- - position (top|bot) #IMPLIED >
-- - <!ATTLIST menuitem name #IMPLIED
-- - action #REQUIRED
-- - position (top|bot) #IMPLIED >
-- - <!ATTLIST toolitem name #IMPLIED
-- - action #REQUIRED
-- - position (top|bot) #IMPLIED >
-- - <!ATTLIST accelerator name #IMPLIED
-- - action #REQUIRED >
--
-- There are some additional restrictions beyond those specified in the DTD,
-- e.g. every toolitem must have a toolbar in its ancestry and every menuitem
-- must have a menubar or popup in its ancestry. Since a GMarkup parser is
-- used to parse the UI description, it must not only be valid XML, but valid
-- GMarkup.
--
-- If a name is not specified, it defaults to the action. If an action is not
-- specified either, the element name is used. The name and action attributes
-- must not contain '/' characters after parsing (since that would mess up
-- path lookup) and must be usable as XML attributes when enclosed in
-- doublequotes, thus they must not '"' characters or references to the "
-- entity.
--
-- Here is an example:
-- <example>
-- <ui>
-- <menubar>
-- <menu name="FileMenu" action="FileMenuAction">
-- <menuitem name="New" action="New2Action" />
-- <placeholder name="FileMenuAdditions" />
-- </menu>
-- <menu name="JustifyMenu" action="JustifyMenuAction">
-- <menuitem name="Left" action="justify-left"/>
-- <menuitem name="Centre" action="justify-center"/>
-- <menuitem name="Right" action="justify-right"/>
-- <menuitem name="Fill" action="justify-fill"/>
-- </menu>
-- </menubar>
-- <toolbar action="toolbar1">
-- <placeholder name="JustifyToolItems">
-- <separator/>
-- <toolitem name="Left" action="justify-left"/>
-- <toolitem name="Centre" action="justify-center"/>
-- <toolitem name="Right" action="justify-right"/>
-- <toolitem name="Fill" action="justify-fill"/>
-- <separator/>
-- </placeholder>
-- </toolbar>
-- </ui>
-- </example>
--
-- The constructed widget hierarchy is very similar to the element tree of the
-- XML, with the exception that placeholders are merged into their parents.
-- The correspondence of XML elements to widgets should be almost obvious:
--
-- - menubar : a Gtk_Menu_Bar
-- - toolbar : a Gtk_Toolbar
-- - popup : a toplevel Gtk_Menu
-- - menu : a Gtk_Menu attached to a menuitem
-- - menuitem : a Gtk_Menu_Item subclass, the exact type depends on the action
-- - toolitem : a Gtk_Tool_Item subclass, exact type depends on the action.
-- This may contain a menu element only if the associated action
-- specifies a Gtk_Menu_Tool_Button as proxy
-- - separator : a Gtk_Separator_Menu_Item or Gtk_Separator_Tool_Item
-- - accelerator : a keyboard accelerator
--
-- The "position" attribute determines where a constructed widget is
-- positioned wrt. to its siblings in the partially constructed tree. If it is
-- "top", the widget is prepended, otherwise it is appended.
--
-----------------
-- UI Merging --
-----------------
--
-- The most remarkable feature of Gtk_UI_Manager is that it can overlay a set
-- of menuitems and toolitems over another one, and demerge them later.
--
-- Merging is done based on the names of the XML elements. Each element is
-- identified by a path which consists of the names of its anchestors,
-- separated by slashes. For example, the menuitem named "Left" in the example
-- above has the path /ui/menubar/JustifyMenu/Left and the toolitem with the
-- same name has path /ui/toolbar1/JustifyToolItems/Left.
--
-------------------
-- Accelerators --
-------------------
--
-- Every action has an accelerator path. Accelerators are installed together
-- with menuitem proxies, but they can also be explicitly added with
-- <accelerator> elements in the UI definition. This makes it possible to have
-- accelerators for actions even if they have no visible proxies.
--
-----------------------
-- Smart Separators --
-----------------------
--
-- The separators created by Gtk_UI_Manager are "smart", i.e. they do not show
-- up in the UI unless they end up between two visible menu or tool items.
-- Separators which are located at the very beginning or end of the menu or
-- toolbar containing them, or multiple separators next to each other, are
-- hidden. This is a useful feature, since the merging of UI elements from
-- multiple sources can make it hard or impossible to determine in advance
-- whether a separator will end up in such an unfortunate position.
--
-- For separators in toolbars, you can set expand="true" to turn them from a
-- small, visible separator to an expanding, invisible one. Toolitems
-- following an expanding separator are effectively right-aligned.
--
------------------
-- Empty Menus --
------------------
--
-- Submenus pose similar problems to separators inconnection with merging. It
-- is impossible to know in advance whether they will end up empty after
-- merging. Gtk_UI_Manager offers two ways to treat empty submenus:
--
-- - make them disappear by hiding the menu item they're attached to
-- - add an insensitive "Empty" item
--
-- The behaviour is chosen based on the "hide_if_empty" property of the action
-- to which the submenu is associated.
-- </description>
-- <c_version>2.8.17</c_version>
-- <group>Action-based menus</group>
with Glib.Error;
with Glib.Object;
with Glib.Properties;
with Gtk.Accel_Group;
with Gtk.Action;
with Gtk.Action_Group;
with Gtk.Widget;
package Gtk.UI_Manager is
type Gtk_UI_Manager_Record is new Glib.Object.GObject_Record with
null record;
type Gtk_UI_Manager is access all Gtk_UI_Manager_Record'Class;
type Manager_Item_Type is mod 2 ** 16;
Manager_Auto : constant Manager_Item_Type := 2 ** 0;
Manager_Menubar : constant Manager_Item_Type := 2 ** 1;
Manager_Menu : constant Manager_Item_Type := 2 ** 2;
Manager_Toolbar : constant Manager_Item_Type := 2 ** 3;
Manager_Placeholder : constant Manager_Item_Type := 2 ** 4;
Manager_Popup : constant Manager_Item_Type := 2 ** 5;
Manager_Menuitem : constant Manager_Item_Type := 2 ** 6;
Manager_Toolitem : constant Manager_Item_Type := 2 ** 7;
Manager_Separator : constant Manager_Item_Type := 2 ** 8;
Manager_Accelerator : constant Manager_Item_Type := 2 ** 9;
-- These enumeration values are used by Add_UI to determine what UI element
-- to create.
--------------
-- Creation --
--------------
procedure Gtk_New (UI : out Gtk_UI_Manager);
procedure Initialize (UI : access Gtk_UI_Manager_Record'Class);
-- Creates a new ui manager object.
function Get_Type return GType;
-- Return the internal value associated with a Gtk_UI_Manager.
function New_Merge_Id
(Self : access Gtk_UI_Manager_Record) return Guint;
-- Returns an unused merge id, suitable for use with Add_UI.
procedure Ensure_Update (Self : access Gtk_UI_Manager_Record);
-- Makes sure that all pending updates to the UI have been completed.
-- This may occasionally be necessary, since Gtk_UI_Manager updates the
-- UI in an idle function. A typical example where this function is
-- useful is to enforce that the menubar and toolbar have been added to
-- the main window before showing it:
-- Add (Window, Vbox);
-- Connect (Merge, "add_widget", Add_Widget'Access, Vbox);
-- Add_UI_From_File (Merge, "my-menus");
-- Add_UI_From_File (Merge, "my-toolbars");
-- Ensure_Update (Merge);
-- Show (Window);
----------------------
-- Merging contents --
----------------------
procedure Add_UI
(Self : access Gtk_UI_Manager_Record;
Merge_Id : Guint;
Path : String;
Name : String;
Action : String := "";
Typ : Manager_Item_Type := Manager_Auto;
Top : Boolean := False);
procedure Remove_UI
(Self : access Gtk_UI_Manager_Record;
Merge_Id : Guint);
-- Adds a UI element to the current contents of Self.
--
-- If Typ is Manager_Auto, GTK+ inserts a menuitem, toolitem or separator
-- if such an element can be inserted at the place determined by Path.
-- Otherwise Typ must indicate an element that can be inserted at the place
-- determined by Path.
--
-- If Path points to a menuitem or toolitem, the new element will be
-- inserted before or after this item, depending on Top.
--
-- Merge_Id: see New_Merge_Id.
-- Action should be the empty string for a separator.
function Add_UI_From_File
(Self : access Gtk_UI_Manager_Record;
Filename : String;
Error : Glib.Error.GError_Access := null) return Guint;
-- Parses a file containing a UI definition and merges it with the current
-- contents of Self.
-- Return value: The merge id for the merged UI. The merge id can be used
-- to unmerge the UI with Remove_UI. If an error occurred, the return value
-- is 0, and if Error was specified it is set to the error message.
function Add_UI_From_String
(Self : access Gtk_UI_Manager_Record;
Buffer : String;
Error : Glib.Error.GError_Access := null) return Guint;
-- Parses a string containing a UI definition and merges it with the
-- current contents of Self. An enclosing <ui> element is added if it is
-- missing.
-- Return value: The merge id for the merged UI. The merge id can be used
-- to unmerge the UI with Remove_UI. If an error occurred, the return value
-- is 0, and if Error was specified it is set to the error message.
procedure Insert_Action_Group
(Self : access Gtk_UI_Manager_Record;
Action_Group : access Gtk.Action_Group.Gtk_Action_Group_Record'Class;
Pos : Gint);
procedure Remove_Action_Group
(Self : access Gtk_UI_Manager_Record;
Action_Group : access Gtk.Action_Group.Gtk_Action_Group_Record'Class);
-- Inserts an action group into the list of action groups associated
-- with Self. Actions in earlier groups hide actions with the same
-- name in later groups.
-- with Self.
-----------------------
-- Querying contents --
-----------------------
function Get_Accel_Group
(Self : access Gtk_UI_Manager_Record)
return Gtk.Accel_Group.Gtk_Accel_Group;
-- Returns the Gtk_Accel_Group associated with Self.
function Get_Action
(Self : access Gtk_UI_Manager_Record; Path : String)
return Gtk.Action.Gtk_Action;
-- Looks up an action by following a path. See Get_Widget for more
-- information about paths.
-- Returns the action whose proxy widget is found by following the path,
-- or null if no widget was found.
function Get_Action_Groups
(Self : access Gtk_UI_Manager_Record)
return Glib.Object.Object_Simple_List.Glist;
-- Returns the list of action groups associated with Self. The returned
-- list should not be modified.
procedure Set_Add_Tearoffs
(Self : access Gtk_UI_Manager_Record;
Add_Tearoffs : Boolean);
function Get_Add_Tearoffs
(Self : access Gtk_UI_Manager_Record) return Boolean;
-- Sets the "add_tearoffs" property, which controls whether menus
-- generated by this Gtk_UI_Manager will have tearoff menu items.
-- Note that this only affects regular menus. Generated popup
-- menus never have tearoff menu items.
function Get_Toplevels
(Self : access Gtk_UI_Manager_Record;
Types : Manager_Item_Type)
return Gtk.Widget.Widget_SList.GSlist;
-- Obtains a list of all toplevel widgets of the requested types.
-- Types may contain Manager_Menubar, Manager_Toolbar or Manager_Popup.
-- The returned list must be freed by the caller.
function Get_UI (Self : access Gtk_UI_Manager_Record) return String;
-- Create a UI definition of the merged UI
function Get_Widget
(Self : access Gtk_UI_Manager_Record;
Path : String)
return Gtk.Widget.Gtk_Widget;
-- Looks up a widget by following a path.
-- The path consists of the names specified in the XML description of the
-- UI. separated by '/'. Elements which don't have a name or action
-- attribute in the XML (e.g. <popup>) can be addressed by their XML
-- element name (e.g. "popup"). The root element ("/ui") can be omitted in
-- the path.
--
-- Note that the widget found by following a path that ends in a
-- <menu>; element is the menuitem to which the menu is attached, not
-- the menu itself.
--
-- Also note that the widgets constructed by a ui manager are not tied to
-- the lifecycle of the ui manager. If you add the widgets returned by this
-- function to some container or explicitly ref them, they will survive the
-- destruction of the ui manager.
----------------
-- Properties --
----------------
-- <properties>
-- The following properties are defined for this widget. See
-- Glib.Properties for more information on properties.
--
-- Name: Add_Tearoffs_Property
-- Type: Boolean
-- Descr: Whether tearoff menu items should be added to menus
--
-- Name: Ui_Property
-- Type: String
-- Descr: An XML string describing the merged UI
--
-- </properties>
Add_Tearoffs_Property : constant Glib.Properties.Property_Boolean;
UI_Property : constant Glib.Properties.Property_String;
-------------
-- Signals --
-------------
-- <signals>
-- The following new signals are defined for this widget:
--
-- - "actions_changed"
-- procedure Handler (UI : access Gtk_UI_Manager_Record'Class);
-- This signal is emitted whenever the set of actions changes.
--
-- - "add_widget"
-- procedure Handler
-- (UI : access Gtk_UI_Manager_Record'Class;
-- Widget : access Gtk_Widget_Record'Class);
-- The add_widget signal is emitted for each generated menubar and
-- toolbar. It is not emitted for generated popup menus, which can be
-- obtained by Get_Widget.
--
-- - "connect_proxy"
-- procedure Handler
-- (UI : access Gtk_UI_Manager_Record'Class;
-- Action : access Gtk_Action_Record'Class;
-- Proxy : access Gtk_Widget_Record'Class);
-- This signal is emitted after connecting a proxy to an action in the
-- group.
-- This is intended for simple customizations for which a custom action
-- class would be too clumsy, e.g. showing tooltips for menuitems in the
-- statusbar.
--
-- - "disconnect_proxy"
-- procedure Handler
-- (UI : access Gtk_UI_Manager_Record'Class;
-- Action : access Gtk_Action_Record'Class;
-- Proxy : access Gtk_Widget_Record'Class);
-- The disconnect_proxy signal is emitted after disconnecting a proxy
-- from an action in the group.
--
-- - "post_activate"
-- procedure Handler
-- (UI : access Gtk_UI_Manager_Record'Class;
-- Action : access Gtk_Action_Record'Class);
-- The post_activate signal is emitted just after the action is
-- activated. This is intended for applications to get notification just
-- after any action is activated.
--
-- - "pre_activate"
-- procedure Handler
-- (UI : access Gtk_UI_Manager_Record'Class;
-- Action : access Gtk_Action_Record'Class);
-- The pre_activate signal is emitted just before the action is
-- activated. This is intended for applications to get notification just
-- before any action is activated.
-- </signals>
Signal_Actions_Changed : constant Glib.Signal_Name := "actions_changed";
Signal_Add_Widget : constant Glib.Signal_Name := "add_widget";
Signal_Connect_Proxy : constant Glib.Signal_Name := "connect_proxy";
Signal_Disconnect_Proxy : constant Glib.Signal_Name := "disconnect_proxy";
Signal_Post_Activate : constant Glib.Signal_Name := "post_activate";
Signal_Pre_Activate : constant Glib.Signal_Name := "pre_activate";
private
Add_Tearoffs_Property : constant Glib.Properties.Property_Boolean :=
Glib.Properties.Build ("add-tearoffs");
Ui_Property : constant Glib.Properties.Property_String :=
Glib.Properties.Build ("ui");
pragma Import (C, Get_Type, "gtk_ui_manager_get_type");
end Gtk.UI_Manager;