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.
An 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 [Monitoring changes][monitoring-changes] 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.
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.
valid accelerator path
the accelerator key
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.
a pattern (see Gpattern.Spec.Gpattern_Spec)
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);
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);
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.
a valid accelerator path
the new accelerator key
the new accelerator modifiers
True if other accelerators may be deleted upon conflicts
True if the accelerator could be changed, False otherwise
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).
function to be executed for each accel map entry which is not filtered out
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).
function to be executed for each accel map entry
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
the global Gtk.Accel_Map.Gtk_Accel_Map object
function Get_Type return Glib.GType
type Gtk_Accel_Map is access all Gtk_Accel_Map_Record'Class;
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 of the current accelerator
Key of the current accelerator
Modifiers of the current accelerator
Changed flag of the accelerator (if True, accelerator has changed during runtime and would need to be saved during an accelerator dump)
type Gtk_Accel_Map_Record is new GObject_Record with null record;
procedure Load (File_Name : UTF8_String)
Parses a file previously saved with Gtk.Accel_Map.Save for accelerator specifications, and propagates them accordingly.
a file containing accelerator specifications, in the GLib file name encoding
procedure Load_Fd (Fd : Glib.Gint)
Filedescriptor variant of Gtk.Accel_Map.Load. Note that the file descriptor will not be closed by this function.
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
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.
a valid accelerator path
the accelerator key to be filled in (optional) @return True if Accel_Path is known, False otherwise
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::accel_path.
Callback parameters: -- @param Accel_Path the path of the accelerator that changed -- @param Accel_Key the key value for the new accelerator -- @param Accel_Mods the modifier mask for the new accelerator
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)
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::accel_path.
Callback parameters: -- @param Accel_Path the path of the accelerator that changed -- @param Accel_Key the key value for the new accelerator -- @param Accel_Mods the modifier mask for the new accelerator
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.
the name of the file to contain accelerator specifications, in the GLib file name encoding
procedure Save_Fd (Fd : Glib.Gint)
Filedescriptor variant of Gtk.Accel_Map.Save. Note that the file descriptor will not be closed by this function.
a valid writable file descriptor
Signal_Changed : constant Glib.Signal_Name := "changed";
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::accel_path.
Callback parameters: -- @param Accel_Path the path of the accelerator that changed -- @param Accel_Key the key value for the new accelerator -- @param Accel_Mods the modifier mask for the new accelerator
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
a valid accelerator path