------------------------------------------------------------------------------
-- --
-- Copyright (C) 1998-2000 E. Briot, J. Brobecker and A. Charlet --
-- Copyright (C) 2000-2014, AdaCore --
-- --
-- This library is free software; you can redistribute it and/or modify it --
-- under terms of the GNU General Public License as published by the Free --
-- Software Foundation; either version 3, 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 MERCHAN- --
-- TABILITY or FITNESS FOR A PARTICULAR PURPOSE. --
-- --
-- As a special exception under Section 7 of GPL version 3, you are granted --
-- additional permissions described in the GCC Runtime Library Exception, --
-- version 3.1, as published by the Free Software Foundation. --
-- --
-- You should have received a copy of the GNU General Public License and --
-- a copy of the GCC Runtime Library Exception along with this program; --
-- see the files COPYING3 and COPYING.RUNTIME respectively. If not, see --
-- <http://www.gnu.org/licenses/>. --
-- --
------------------------------------------------------------------------------
-- <description>
-- Accelerator maps are used to define runtime configurable accelerators.
-- Functions for manipulating them are are usually used by higher level
-- convenience mechanisms like Gtk.UI_Manager.Gtk_UI_Manager and are thus
-- considered "low-level". You'll want to use them if you're manually creating
-- menus that should have user-configurable accelerators.
--
-- Accelerator is uniquely defined by:
--
--
--
-- * accelerator path
--
-- * accelerator key
--
-- * accelerator modifiers
--
-- The accelerator path must consist of
-- "<WINDOWTYPE>/Category1/Category2/.../Action", where WINDOWTYPE should be a
-- unique application-specific identifier that corresponds to the kind of
-- window the accelerator is being used in, e.g. "Gimp-Image",
-- "Abiword-Document" or "Gnumeric-Settings". The "Category1/.../Action"
-- portion is most appropriately chosen by the action the accelerator
-- triggers, i.e. for accelerators on menu items, choose the item's menu path,
-- e.g. "File/Save As", "Image/View/Zoom" or "Edit/Select All". So a full
-- valid accelerator path may look like: "<Gimp-Toolbox>/File/Dialogs/Tool
-- Options...".
--
-- All accelerators are stored inside one global Gtk.Accel_Map.Gtk_Accel_Map
-- that can be obtained using Gtk.Accel_Map.Get. See <link
-- linkend="monitoring-changes">Monitoring changes</link> for additional
-- details.
--
-- == Manipulating accelerators ==
--
-- New accelerators can be added using Gtk.Accel_Map.Add_Entry. To search for
-- specific accelerator, use Gtk.Accel_Map.Lookup_Entry. Modifications of
-- existing accelerators should be done using Gtk.Accel_Map.Change_Entry.
--
-- In order to avoid having some accelerators changed, they can be locked
-- using Gtk.Accel_Map.Lock_Path. Unlocking is done using
-- Gtk.Accel_Map.Unlock_Path.
--
-- == Saving and loading accelerator maps ==
--
-- Accelerator maps can be saved to and loaded from some external resource.
-- For simple saving and loading from file, Gtk.Accel_Map.Save and
-- Gtk.Accel_Map.Load are provided. Saving and loading can also be done by
-- providing file descriptor to Gtk.Accel_Map.Save_Fd and
-- Gtk.Accel_Map.Load_Fd.
--
-- == Monitoring changes ==
--
-- Gtk.Accel_Map.Gtk_Accel_Map object is only useful for monitoring changes
-- of accelerators. By connecting to Gtk.Accel_Map.Gtk_Accel_Map::changed
-- signal, one can monitor changes of all accelerators. It is also possible to
-- monitor only single accelerator path by using it as a detail of the
-- Gtk.Accel_Map.Gtk_Accel_Map::changed signal.
--
--
-- </description>
pragma Ada_2005;
pragma Warnings (Off, "*is already use-visible*");
with Gdk.Types; use Gdk.Types;
with Glib; use Glib;
with Glib.Object; use Glib.Object;
with Gtk.Accel_Group; use Gtk.Accel_Group;
package Gtk.Accel_Map is
type Gtk_Accel_Map_Record is new GObject_Record with null record;
type Gtk_Accel_Map is access all Gtk_Accel_Map_Record'Class;
---------------
-- Callbacks --
---------------
type Gtk_Accel_Map_Foreach is access procedure
(Accel_Path : UTF8_String;
Accel_Key : Gdk.Types.Gdk_Key_Type;
Accel_Mods : Gdk.Types.Gdk_Modifier_Type;
Changed : Boolean);
-- "accel_path": Accel path of the current accelerator
-- "accel_key": Key of the current accelerator
-- "accel_mods": Modifiers of the current accelerator
-- "changed": Changed flag of the accelerator (if True, accelerator has
-- changed during runtime and would need to be saved during an accelerator
-- dump)
------------------
-- Constructors --
------------------
function Get_Type return Glib.GType;
pragma Import (C, Get_Type, "gtk_accel_map_get_type");
-------------
-- Methods --
-------------
procedure Foreach (Foreach_Func : Gtk_Accel_Map_Foreach);
-- Loops over the entries in the accelerator map whose accel path doesn't
-- match any of the filters added with Gtk.Accel_Map.Add_Filter, and
-- execute Foreach_Func on each. The signature of Foreach_Func is that of
-- Gtk_Accel_Map_Foreach, the Changed parameter indicates whether this
-- accelerator was changed during runtime (thus, would need saving during
-- an accelerator map dump).
-- "foreach_func": function to be executed for each accel map entry which
-- is not filtered out
generic
type User_Data_Type (<>) is private;
with procedure Destroy (Data : in out User_Data_Type) is null;
package Foreach_User_Data is
type Gtk_Accel_Map_Foreach is access procedure
(Data : User_Data_Type;
Accel_Path : UTF8_String;
Accel_Key : Gdk.Types.Gdk_Key_Type;
Accel_Mods : Gdk.Types.Gdk_Modifier_Type;
Changed : Boolean);
-- "data": User data passed to Gtk.Accel_Map.Foreach or
-- gtk_accel_map_foreach_unfiltered
-- "accel_path": Accel path of the current accelerator
-- "accel_key": Key of the current accelerator
-- "accel_mods": Modifiers of the current accelerator
-- "changed": Changed flag of the accelerator (if True, accelerator has
-- changed during runtime and would need to be saved during an accelerator
-- dump)
procedure Foreach
(Data : User_Data_Type;
Foreach_Func : Gtk_Accel_Map_Foreach);
-- Loops over the entries in the accelerator map whose accel path
-- doesn't match any of the filters added with Gtk.Accel_Map.Add_Filter,
-- and execute Foreach_Func on each. The signature of Foreach_Func is
-- that of Gtk_Accel_Map_Foreach, the Changed parameter indicates
-- whether this accelerator was changed during runtime (thus, would need
-- saving during an accelerator map dump).
-- "data": data to be passed into Foreach_Func
-- "foreach_func": function to be executed for each accel map entry
-- which is not filtered out
end Foreach_User_Data;
procedure Foreach_Unfiltered (Foreach_Func : Gtk_Accel_Map_Foreach);
-- Loops over all entries in the accelerator map, and execute Foreach_Func
-- on each. The signature of Foreach_Func is that of Gtk_Accel_Map_Foreach,
-- the Changed parameter indicates whether this accelerator was changed
-- during runtime (thus, would need saving during an accelerator map dump).
-- "foreach_func": function to be executed for each accel map entry
generic
type User_Data_Type (<>) is private;
with procedure Destroy (Data : in out User_Data_Type) is null;
package Foreach_Unfiltered_User_Data is
type Gtk_Accel_Map_Foreach is access procedure
(Data : User_Data_Type;
Accel_Path : UTF8_String;
Accel_Key : Gdk.Types.Gdk_Key_Type;
Accel_Mods : Gdk.Types.Gdk_Modifier_Type;
Changed : Boolean);
-- "data": User data passed to Gtk.Accel_Map.Foreach or
-- Gtk.Accel_Map.Foreach_Unfiltered
-- "accel_path": Accel path of the current accelerator
-- "accel_key": Key of the current accelerator
-- "accel_mods": Modifiers of the current accelerator
-- "changed": Changed flag of the accelerator (if True, accelerator has
-- changed during runtime and would need to be saved during an accelerator
-- dump)
procedure Foreach_Unfiltered
(Data : User_Data_Type;
Foreach_Func : Gtk_Accel_Map_Foreach);
-- Loops over all entries in the accelerator map, and execute
-- Foreach_Func on each. The signature of Foreach_Func is that of
-- Gtk_Accel_Map_Foreach, the Changed parameter indicates whether this
-- accelerator was changed during runtime (thus, would need saving
-- during an accelerator map dump).
-- "data": data to be passed into Foreach_Func
-- "foreach_func": function to be executed for each accel map entry
end Foreach_Unfiltered_User_Data;
---------------
-- Functions --
---------------
procedure Add_Entry
(Accel_Path : UTF8_String;
Accel_Key : Gdk.Types.Gdk_Key_Type;
Accel_Mods : Gdk.Types.Gdk_Modifier_Type);
-- Registers a new accelerator with the global accelerator map. This
-- function should only be called once per Accel_Path with the canonical
-- Accel_Key and Accel_Mods for this path. To change the accelerator during
-- runtime programatically, use Gtk.Accel_Map.Change_Entry.
-- Set Accel_Key and Accel_Mods to 0 to request a removal of the
-- accelerator.
-- Note that Accel_Path string will be stored in a Glib.GQuark. Therefore,
-- if you pass a static string, you can save some memory by interning it
-- first with g_intern_static_string.
-- "accel_path": valid accelerator path
-- "accel_key": the accelerator key
-- "accel_mods": the accelerator modifiers
procedure Add_Filter (Filter_Pattern : UTF8_String);
-- Adds a filter to the global list of accel path filters.
-- Accel map entries whose accel path matches one of the filters are
-- skipped by Gtk.Accel_Map.Foreach.
-- This function is intended for GTK+ modules that create their own menus,
-- but don't want them to be saved into the applications accelerator map
-- dump.
-- "filter_pattern": a pattern (see Gpattern.Spec.Gpattern_Spec)
function Change_Entry
(Accel_Path : UTF8_String;
Accel_Key : Gdk.Types.Gdk_Key_Type;
Accel_Mods : Gdk.Types.Gdk_Modifier_Type;
Replace : Boolean) return Boolean;
-- Changes the Accel_Key and Accel_Mods currently associated with
-- Accel_Path. Due to conflicts with other accelerators, a change may not
-- always be possible, Replace indicates whether other accelerators may be
-- deleted to resolve such conflicts. A change will only occur if all
-- conflicts could be resolved (which might not be the case if conflicting
-- accelerators are locked). Successful changes are indicated by a True
-- return value.
-- Note that Accel_Path string will be stored in a Glib.GQuark. Therefore,
-- if you pass a static string, you can save some memory by interning it
-- first with g_intern_static_string.
-- "accel_path": a valid accelerator path
-- "accel_key": the new accelerator key
-- "accel_mods": the new accelerator modifiers
-- "replace": True if other accelerators may be deleted upon conflicts
function Get return Gtk_Accel_Map;
-- Gets the singleton global Gtk.Accel_Map.Gtk_Accel_Map object. This
-- object is useful only for notification of changes to the accelerator map
-- via the ::changed signal; it isn't a parameter to the other accelerator
-- map functions.
-- Since: gtk+ 2.4
procedure Load (File_Name : UTF8_String);
-- Parses a file previously saved with Gtk.Accel_Map.Save for accelerator
-- specifications, and propagates them accordingly.
-- "file_name": a file containing accelerator specifications, in the GLib
-- file name encoding
procedure Load_Fd (Fd : Gint);
-- Filedescriptor variant of Gtk.Accel_Map.Load.
-- Note that the file descriptor will not be closed by this function.
-- "fd": a valid readable file descriptor
procedure Lock_Path (Accel_Path : UTF8_String);
-- Locks the given accelerator path. If the accelerator map doesn't yet
-- contain an entry for Accel_Path, a new one is created.
-- Locking an accelerator path prevents its accelerator from being changed
-- during runtime. A locked accelerator path can be unlocked by
-- Gtk.Accel_Map.Unlock_Path. Refer to Gtk.Accel_Map.Change_Entry for
-- information about runtime accelerator changes.
-- If called more than once, Accel_Path remains locked until
-- Gtk.Accel_Map.Unlock_Path has been called an equivalent number of times.
-- Note that locking of individual accelerator paths is independent from
-- locking the Gtk.Accel_Group.Gtk_Accel_Group containing them. For runtime
-- accelerator changes to be possible, both the accelerator path and its
-- Gtk.Accel_Group.Gtk_Accel_Group have to be unlocked.
-- Since: gtk+ 2.4
-- "accel_path": a valid accelerator path
procedure Lookup_Entry
(Accel_Path : UTF8_String;
Key : out Gtk.Accel_Group.Gtk_Accel_Key;
Found : out Boolean);
-- Looks up the accelerator entry for Accel_Path and fills in Key.
-- "accel_path": a valid accelerator path
-- "key": the accelerator key to be filled in (optional)
procedure Save (File_Name : UTF8_String);
-- Saves current accelerator specifications (accelerator path, key and
-- modifiers) to File_Name. The file is written in a format suitable to be
-- read back in by Gtk.Accel_Map.Load.
-- "file_name": the name of the file to contain accelerator
-- specifications, in the GLib file name encoding
procedure Save_Fd (Fd : Gint);
-- Filedescriptor variant of Gtk.Accel_Map.Save.
-- Note that the file descriptor will not be closed by this function.
-- "fd": a valid writable file descriptor
procedure Unlock_Path (Accel_Path : UTF8_String);
-- Undoes the last call to Gtk.Accel_Map.Lock_Path on this Accel_Path.
-- Refer to Gtk.Accel_Map.Lock_Path for information about accelerator path
-- locking.
-- Since: gtk+ 2.4
-- "accel_path": a valid accelerator path
-------------
-- Signals --
-------------
type Cb_Gtk_Accel_Map_UTF8_String_Gdk_Key_Type_Gdk_Modifier_Type_Void is not null access procedure
(Self : access Gtk_Accel_Map_Record'Class;
Accel_Path : UTF8_String;
Accel_Key : Gdk.Types.Gdk_Key_Type;
Accel_Mods : Gdk.Types.Gdk_Modifier_Type);
type Cb_GObject_UTF8_String_Gdk_Key_Type_Gdk_Modifier_Type_Void is not null access procedure
(Self : access Glib.Object.GObject_Record'Class;
Accel_Path : UTF8_String;
Accel_Key : Gdk.Types.Gdk_Key_Type;
Accel_Mods : Gdk.Types.Gdk_Modifier_Type);
Signal_Changed : constant Glib.Signal_Name := "changed";
procedure On_Changed
(Self : not null access Gtk_Accel_Map_Record;
Call : Cb_Gtk_Accel_Map_UTF8_String_Gdk_Key_Type_Gdk_Modifier_Type_Void;
After : Boolean := False);
procedure On_Changed
(Self : not null access Gtk_Accel_Map_Record;
Call : Cb_GObject_UTF8_String_Gdk_Key_Type_Gdk_Modifier_Type_Void;
Slot : not null access Glib.Object.GObject_Record'Class;
After : Boolean := False);
-- Notifies of a change in the global accelerator map. The path is also
-- used as the detail for the signal, so it is possible to connect to
-- changed::<replaceable>accel_path</replaceable>.
--
-- Callback parameters:
-- -- "accel_path": the path of the accelerator that changed
-- -- "accel_key": the key value for the new accelerator
-- -- "accel_mods": the modifier mask for the new accelerator
end Gtk.Accel_Map;