Accelerator Maps

Accelerator Maps

Functions

Signals

void changed Has Details

Types and Values

Object Hierarchy

    GObject
    ╰── GtkAccelMap

Includes

#include <gtk/gtk.h>

Description

Functions

GtkAccelMapForeach ()

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

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(). 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...".

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().

Parameters

accel_path

valid accelerator path

 

accel_key

the accelerator key

 

accel_mods

the accelerator modifiers

 

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 .

Parameters

accel_path

a valid accelerator path

 

key

the accelerator key to be filled in (optional)

 

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().

Parameters

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

 

returns

TRUE if the accelerator could be changed, FALSE otherwise

 

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

Parameters

data

data to be passed into foreach_func

 

foreach_func

function to be executed for each accel map entry which is not filtered out

 

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.

Parameters

fd

a valid readable file descriptor

 

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.

Parameters

fd

a valid writable file descriptor

 

gtk_accel_map_load_scanner ()

void
gtk_accel_map_load_scanner (GScanner *scanner);

GScanner variant of gtk_accel_map_load().

Parameters

scanner

a GScanner which has already been provided with an input file

 

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.

Parameters

filter_pattern

a pattern (see GPatternSpec)

 

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

Parameters

data

data to be passed into foreach_func

 

foreach_func

function to be executed for each accel map entry

 

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.

Returns

the global GtkAccelMap object

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.

Parameters

accel_path

a valid accelerator path

 

Since: 2.4


gtk_accel_map_unlock_path ()

void
gtk_accel_map_unlock_path (const gchar *accel_path);

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.

Parameters

accel_path

a valid accelerator path

 

Since: 2.4

Types and Values

GtkAccelMap

typedef struct _GtkAccelMap GtkAccelMap;

gtk_accel_map_load

#define gtk_accel_map_load gtk_accel_map_load_utf8

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

Parameters

file_name

a file containing accelerator specifications, in the GLib file name encoding

 

gtk_accel_map_save

#define gtk_accel_map_save gtk_accel_map_save_utf8

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().

Parameters

file_name

the name of the file to contain accelerator specifications, in the GLib file name encoding

 

Signal Details

The “changed” signal

void
user_function (GtkAccelMap    *object,
               char           *accel_path,
               guint           accel_key,
               GdkModifierType 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.

Parameters

object

the global accel map object

 

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

 

user_data

user data set when the signal handler was connected.

 

Flags: Has Details

Since: 2.4