## Accelerator Maps

Accelerator Maps — Loadable keyboard accelerator specifications

## Synopsis

    #include <gtk/gtk.h>

    void        (*GtkAccelMapForeach)           (gpointer data,
                                                 const gchar *accel_path,
                                                 guint accel_key,
                                                 GdkModifierType accel_mods,
                                                 gboolean changed);
    void        gtk_accel_map_add_entry         (const gchar *accel_path,
                                                 guint accel_key,
                                                 GdkModifierType accel_mods);
    gboolean    gtk_accel_map_lookup_entry      (const gchar *accel_path,
                                                 GtkAccelKey *key);
    gboolean    gtk_accel_map_change_entry      (const gchar *accel_path,
                                                 guint accel_key,
                                                 GdkModifierType accel_mods,
                                                 gboolean replace);
    void        gtk_accel_map_load              (const gchar *file_name);
    void        gtk_accel_map_save              (const gchar *file_name);
    void        gtk_accel_map_foreach           (gpointer data,
                                                 GtkAccelMapForeach foreach_func);
    void        gtk_accel_map_load_fd           (gint fd);
    void        gtk_accel_map_save_fd           (gint fd);
    void        gtk_accel_map_load_scanner      (GScanner *scanner);
    void        gtk_accel_map_add_filter        (const gchar *filter_pattern);
    void        gtk_accel_map_foreach_unfiltered
                                                (gpointer data,
                                                 GtkAccelMapForeach foreach_func);

## Description

## Details

### GtkAccelMapForeach ()

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

`data` : |
`accel_path` : |
`accel_key` : |
`accel_mods` : |
`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...".

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

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

`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_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.

`file_name` : | a file containing accelerator specifications

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

`file_name` : | the file to contain accelerator specifications

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

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

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

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

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

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

`data` : | data to be passed into `foreach_func`
`foreach_func` : | function to be executed for each accel map entry