Manipulating accelerators

New accelerators can be added using ctk_accel_map_add_entry(). To search for specific accelerator, use ctk_accel_map_lookup_entry(). Modifications of existing accelerators should be done using ctk_accel_map_change_entry().

In order to avoid having some accelerators changed, they can be locked using ctk_accel_map_lock_path(). Unlocking is done using ctk_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, ctk_accel_map_save() and ctk_accel_map_load() are provided. Saving and loading can also be done by providing file descriptor to ctk_accel_map_save_fd() and ctk_accel_map_load_fd().

Monitoring changes

CtkAccelMap 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.

CtkAccelMapForeach ()

void
(*CtkAccelMapForeach) (gpointer data,
                       const gchar *accel_path,
                       guint accel_key,
                       CdkModifierType accel_mods,
                       gboolean changed);

ctk_accel_map_add_entry ()

void
ctk_accel_map_add_entry (const gchar *accel_path,
                         guint accel_key,
                         CdkModifierType 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 ctk_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().

ctk_accel_map_lookup_entry ()

gboolean
ctk_accel_map_lookup_entry (const gchar *accel_path,
                            CtkAccelKey *key);

Looks up the accelerator entry for accel_path and fills in key .

ctk_accel_map_change_entry ()

gboolean
ctk_accel_map_change_entry (const gchar *accel_path,
                            guint accel_key,
                            CdkModifierType 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().

ctk_accel_map_load ()

void
ctk_accel_map_load (const gchar *file_name);

Parses a file previously saved with ctk_accel_map_save() for accelerator specifications, and propagates them accordingly.

ctk_accel_map_save ()

void
ctk_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 ctk_accel_map_load().

ctk_accel_map_foreach ()

void
ctk_accel_map_foreach (gpointer data,
                       CtkAccelMapForeach foreach_func);

Loops over the entries in the accelerator map whose accel path doesn’t match any of the filters added with ctk_accel_map_add_filter(), and execute foreach_func on each. The signature of foreach_func is that of CtkAccelMapForeach, the changed parameter indicates whether this accelerator was changed during runtime (thus, would need saving during an accelerator map dump).

ctk_accel_map_load_fd ()

void
ctk_accel_map_load_fd (gint fd);

Filedescriptor variant of ctk_accel_map_load().

Note that the file descriptor will not be closed by this function.

ctk_accel_map_save_fd ()

void
ctk_accel_map_save_fd (gint fd);

Filedescriptor variant of ctk_accel_map_save().

Note that the file descriptor will not be closed by this function.

ctk_accel_map_load_scanner ()

void
ctk_accel_map_load_scanner (GScanner *scanner);

GScanner variant of ctk_accel_map_load().

ctk_accel_map_add_filter ()

void
ctk_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 ctk_accel_map_foreach().

This function is intended for CTK+ modules that create their own menus, but don’t want them to be saved into the applications accelerator map dump.

ctk_accel_map_foreach_unfiltered ()

void
ctk_accel_map_foreach_unfiltered (gpointer data,
                                  CtkAccelMapForeach foreach_func);

Loops over all entries in the accelerator map, and execute foreach_func on each. The signature of foreach_func is that of CtkAccelMapForeach, the changed parameter indicates whether this accelerator was changed during runtime (thus, would need saving during an accelerator map dump).

ctk_accel_map_get ()

CtkAccelMap *
ctk_accel_map_get (void);

Gets the singleton global CtkAccelMap 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

ctk_accel_map_lock_path ()

void
ctk_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 ctk_accel_map_unlock_path(). Refer to ctk_accel_map_change_entry() for information about runtime accelerator changes.

If called more than once, accel_path remains locked until ctk_accel_map_unlock_path() has been called an equivalent number of times.

Note that locking of individual accelerator paths is independent from locking the CtkAccelGroup containing them. For runtime accelerator changes to be possible, both the accelerator path and its CtkAccelGroup have to be unlocked.

Since: 2.4

ctk_accel_map_unlock_path ()

void
ctk_accel_map_unlock_path (const gchar *accel_path);

Undoes the last call to ctk_accel_map_lock_path() on this accel_path . Refer to ctk_accel_map_lock_path() for information about accelerator path locking.

Since: 2.4

CtkAccelMap

typedef struct _CtkAccelMap CtkAccelMap;

The “changed” signal

void
user_function (CtkAccelMap    *object,
               char           *accel_path,
               guint           accel_key,
               CdkModifierType accel_mods,
               gpointer        user_data)

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.

Flags: Has Details

Since: 2.4