Description
Accelerator maps are used to define runtime configurable accelerators.
Functions for manipulating them are are usually used by higher level
convenience mechanisms like GtkUIManager 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 GtkAccelMap that can
be obtained using gtk_accel_map_get(). See
Monitoring changes for additional
details.
Monitoring changes
GtkAccelMap object is only useful for monitoring changes of
accelerators. By connecting to “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 “changed” signal.
Functions
gtk_accel_map_add_entry ()
void
gtk_accel_map_add_entry (const gchar *accel_path,
guint accel_key,
GdkModifierType accel_mods);
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 GQuark. Therefore, if you
pass a static string, you can save some memory by interning it first with
g_intern_static_string().
gtk_accel_map_lookup_entry ()
gboolean
gtk_accel_map_lookup_entry (const gchar *accel_path,
GtkAccelKey *key);
Looks up the accelerator entry for accel_path
and fills in key
.
Returns
TRUE if accel_path
is known, FALSE otherwise
gtk_accel_map_change_entry ()
gboolean
gtk_accel_map_change_entry (const gchar *accel_path,
guint accel_key,
GdkModifierType accel_mods,
gboolean replace);
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 GQuark. Therefore, if you
pass a static string, you can save some memory by interning it first with
g_intern_static_string().
Returns
TRUE if the accelerator could be changed, FALSE otherwise
gtk_accel_map_load ()
void
gtk_accel_map_load (const gchar *file_name);
Parses a file previously saved with gtk_accel_map_save() for
accelerator specifications, and propagates them accordingly.
gtk_accel_map_save ()
void
gtk_accel_map_save (const gchar *file_name);
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().
gtk_accel_map_foreach ()
void
gtk_accel_map_foreach (gpointer data,
GtkAccelMapForeach foreach_func);
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 GtkAccelMapForeach, the changed
parameter indicates whether
this accelerator was changed during runtime (thus, would need
saving during an accelerator map dump).
gtk_accel_map_load_fd ()
void
gtk_accel_map_load_fd (gint fd);
Filedescriptor variant of gtk_accel_map_load().
Note that the file descriptor will not be closed by this function.
gtk_accel_map_save_fd ()
void
gtk_accel_map_save_fd (gint fd);
Filedescriptor variant of gtk_accel_map_save().
Note that the file descriptor will not be closed by this function.
gtk_accel_map_add_filter ()
void
gtk_accel_map_add_filter (const gchar *filter_pattern);
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.
gtk_accel_map_foreach_unfiltered ()
void
gtk_accel_map_foreach_unfiltered (gpointer data,
GtkAccelMapForeach foreach_func);
Loops over all entries in the accelerator map, and execute
foreach_func
on each. The signature of foreach_func
is that of
GtkAccelMapForeach, the changed
parameter indicates whether
this accelerator was changed during runtime (thus, would need
saving during an accelerator map dump).
gtk_accel_map_get ()
GtkAccelMap *
gtk_accel_map_get (void);
Gets the singleton global GtkAccelMap 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: 2.4
gtk_accel_map_lock_path ()
void
gtk_accel_map_lock_path (const gchar *accel_path);
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 GtkAccelGroup containing them. For runtime accelerator
changes to be possible, both the accelerator path and its GtkAccelGroup
have to be unlocked.
Since: 2.4