GTK+ Reference Manual
<<< Previous Page | Home | Up | Next Page >>>

# Keyboard Accelerator Groups

## Name

Keyboard Accelerator Groups -- Groups of global keyboard accelerators for an entire GtkWindow

## Synopsis

    #include <gtk/gtk.h>

    struct      GtkAccelGroup;
    GtkAccelGroup* gtk_accel_group_new          (void);
    #define     gtk_accel_group_ref
    #define     gtk_accel_group_unref
    void        gtk_accel_group_connect         (GtkAccelGroup *accel_group,
                                                 guint accel_key,
                                                 GdkModifierType accel_mods,
                                                 GtkAccelFlags accel_flags,
                                                 GClosure *closure);
    void        gtk_accel_group_connect_by_path (GtkAccelGroup *accel_group,
                                                 const gchar *accel_path,
                                                 GClosure *closure);
    gboolean    (*GtkAccelGroupActivate)        (GtkAccelGroup *accel_group,
                                                 GObject *acceleratable,
                                                 guint keyval,
                                                 GdkModifierType modifier);
    gboolean    gtk_accel_group_disconnect      (GtkAccelGroup *accel_group,
                                                 GClosure *closure);
    gboolean    gtk_accel_group_disconnect_key  (GtkAccelGroup *accel_group,
                                                 guint accel_key,
                                                 GdkModifierType accel_mods);
    GtkAccelGroupEntry* gtk_accel_group_query   (GtkAccelGroup *accel_group,
                                                 guint accel_key,
                                                 GdkModifierType accel_mods,
                                                 guint *n_entries);
    void        gtk_accel_group_lock            (GtkAccelGroup *accel_group);
    void        gtk_accel_group_unlock          (GtkAccelGroup *accel_group);
    GtkAccelGroup* gtk_accel_group_from_accel_closure
                                                (GClosure *closure);
    gboolean    gtk_accel_groups_activate       (GObject *object,
                                                 guint accel_key,
                                                 GdkModifierType accel_mods);
    GSList*     gtk_accel_groups_from_object    (GObject *object);
    GtkAccelKey* gtk_accel_group_find           (GtkAccelGroup *accel_group,
                                                 gboolean (*find_func) (GtkAccelKey *key,GClosure    *closure,gpointer     data),
                                                 gpointer data);
    struct      GtkAccelKey;
    gboolean    gtk_accelerator_valid           (guint keyval,
                                                 GdkModifierType modifiers);
    void        gtk_accelerator_parse           (const gchar *accelerator,
                                                 guint *accelerator_key,
                                                 GdkModifierType *accelerator_mods);
    gchar*      gtk_accelerator_name            (guint accelerator_key,
                                                 GdkModifierType accelerator_mods);
    void        gtk_accelerator_set_default_mod_mask
                                                (GdkModifierType default_mod_mask);
    guint       gtk_accelerator_get_default_mod_mask
                                                (void);

## Object Hierarchy

      GObject
       +----GtkAccelGroup

## Signal Prototypes

    "accel-activate"
                gboolean    user_function      (GtkAccelGroup *accelgroup,
                                                GObject *arg1,
                                                guint arg2,
                                                GdkModifierType arg3,
                                                gpointer user_data);
    "accel-changed"
                void        user_function      (GtkAccelGroup *accelgroup,
                                                guint arg1,
                                                GdkModifierType arg2,
                                                GClosure arg3,
                                                gpointer user_data);

## Description

A GtkAccelGroup represents a group of keyboard accelerators, typically attached to a toplevel GtkWindow (with gtk_window_add_accel_group()). Usually you won't need to create a GtkAccelGroup directly; instead, when using GtkItemFactory, GTK+ automatically sets up the accelerators for your menus in the item factory's GtkAccelGroup.

Note that accelerators are different from mnemonics. Accelerators are shortcuts for activating a menu item; they appear alongside the menu item they're a shortcut for. For example "Ctrl+Q" might appear alongside the "Quit" menu item. Mnemonics are shortcuts for GUI elements such as text entries or buttons; they appear as underlined characters. See gtk_label_new_with_mnemonic(). Menu items can have both accelerators and mnemonics, of course.

## Details

### struct GtkAccelGroup

    struct GtkAccelGroup;

An object representing and maintaining a group of accelerators.

### gtk_accel_group_new ()

    GtkAccelGroup* gtk_accel_group_new          (void);

Creates a new GtkAccelGroup.

Returns : | a new GtkAccelGroup object

### gtk_accel_group_ref

    #define	gtk_accel_group_ref	g_object_ref

Warning
`gtk_accel_group_ref` is deprecated and should not be used in newly-written code.

Deprecated equivalent of g_object_ref().

Returns : |

### gtk_accel_group_unref

    #define	gtk_accel_group_unref	g_object_unref

Warning
`gtk_accel_group_unref` is deprecated and should not be used in newly-written code.

Deprecated equivalent of g_object_unref().

### gtk_accel_group_connect ()

    void        gtk_accel_group_connect         (GtkAccelGroup *accel_group,
                                                 guint accel_key,
                                                 GdkModifierType accel_mods,
                                                 GtkAccelFlags accel_flags,
                                                 GClosure *closure);

Installs an accelerator in this group. When `accel_group` is being activated in response to a call to gtk_accel_groups_activate(), `closure` will be invoked if the `accel_key` and `accel_mods` from gtk_accel_groups_activate() match those of this connection.

The signature used for the `closure` is that of GtkAccelGroupActivate.

Note that, due to implementation details, a single closure can only be connected to one accelerator group.

`accel_group` : | the accelerator group to install an accelerator in
`accel_key` : | key value of the accelerator
`accel_mods` : | modifier combination of the accelerator
`accel_flags` : | a flag mask to configure this accelerator
`closure` : | closure to be executed upon accelerator activation

### gtk_accel_group_connect_by_path ()

    void        gtk_accel_group_connect_by_path (GtkAccelGroup *accel_group,
                                                 const gchar *accel_path,
                                                 GClosure *closure);

Installs an accelerator in this group, using an accelerator path to look up the appropriate key and modifiers (see gtk_accel_map_add_entry()). When `accel_group` is being activated in response to a call to gtk_accel_groups_activate(), `closure` will be invoked if the `accel_key` and `accel_mods` from gtk_accel_groups_activate() match the key and modifiers for the path.

The signature used for the `closure` is that of GtkAccelGroupActivate.

`accel_group` : | the accelerator group to install an accelerator in
`accel_path` : | path used for determining key and modifiers.
`closure` : | closure to be executed upon accelerator activation

### GtkAccelGroupActivate ()

    gboolean    (*GtkAccelGroupActivate)        (GtkAccelGroup *accel_group,
                                                 GObject *acceleratable,
                                                 guint keyval,
                                                 GdkModifierType modifier);

`accel_group` : |
`acceleratable` : |
`keyval` : |
`modifier` : |
Returns : |

### gtk_accel_group_disconnect ()

    gboolean    gtk_accel_group_disconnect      (GtkAccelGroup *accel_group,
                                                 GClosure *closure);

Removes an accelerator previously installed through gtk_accel_group_connect().

`accel_group` : | the accelerator group to remove an accelerator from
`closure` : | the closure to remove from this accelerator group
Returns : | `TRUE` if the closure was found and got disconnected

### gtk_accel_group_disconnect_key ()

    gboolean    gtk_accel_group_disconnect_key  (GtkAccelGroup *accel_group,
                                                 guint accel_key,
                                                 GdkModifierType accel_mods);

Removes an accelerator previously installed through gtk_accel_group_connect().

`accel_group` : | the accelerator group to install an accelerator in
`accel_key` : | key value of the accelerator
`accel_mods` : | modifier combination of the accelerator
Returns : | `TRUE` if there was an accelerator which could be removed, `FALSE` otherwise

### gtk_accel_group_query ()

    GtkAccelGroupEntry* gtk_accel_group_query   (GtkAccelGroup *accel_group,
                                                 guint accel_key,
                                                 GdkModifierType accel_mods,
                                                 guint *n_entries);

Queries an accelerator group for all entries matching `accel_key` and `accel_mods`.

`accel_group` : | the accelerator group to query
`accel_key` : | key value of the accelerator
`accel_mods` : | modifier combination of the accelerator
`n_entries` : | location to return the number of entries found, or `NULL`
Returns : | an array of `n_entries` GtkAccelGroupEntry elements, or `NULL`. The array is owned by GTK+ and must not be freed.

### gtk_accel_group_lock ()

    void        gtk_accel_group_lock            (GtkAccelGroup *accel_group);

Locks the given accelerator group.

Locking an acelerator group prevents the accelerators contained within it to be changed during runtime. Refer to gtk_accel_map_change_entry() about runtime accelerator changes.

If called more than once, `accel_group` remains locked until gtk_accel_group_unlock() has been called an equivalent number of times.

`accel_group` : | a GtkAccelGroup

### gtk_accel_group_unlock ()

    void        gtk_accel_group_unlock          (GtkAccelGroup *accel_group);

Undoes the last call to gtk_accel_group_lock() on this `accel_group`.

`accel_group` : | a GtkAccelGroup

### gtk_accel_group_from_accel_closure ()

    GtkAccelGroup* gtk_accel_group_from_accel_closure
                                                (GClosure *closure);

Finds the GtkAccelGroup to which `closure` is connected; see gtk_accel_group_connect().

`closure` : | a GClosure
Returns : | the GtkAccelGroup to which `closure` is connected, or `NULL`.

### gtk_accel_groups_activate ()

    gboolean    gtk_accel_groups_activate       (GObject *object,
                                                 guint accel_key,
                                                 GdkModifierType accel_mods);

Finds the first accelerator in any GtkAccelGroup attached to `object` that matches `accel_key` and `accel_mods`, and activates that accelerator. If an accelerator was activated and handled this keypress, `TRUE` is returned.

`object` : | the GObject, usually a GtkWindow, on which to activate the accelerator.
`accel_key` : | accelerator keyval from a key event
`accel_mods` : | keyboard state mask from a key event
Returns : | `TRUE` if the accelerator was handled, `FALSE` otherwise

### gtk_accel_groups_from_object ()

    GSList*     gtk_accel_groups_from_object    (GObject *object);

Gets a list of all accel groups which are attached to `object`.

`object` : | a GObject, usually a GtkWindow
Returns : | a list of all accel groups which are attached to `object`

### gtk_accel_group_find ()

    GtkAccelKey* gtk_accel_group_find           (GtkAccelGroup *accel_group,
                                                 gboolean (*find_func) (GtkAccelKey *key,GClosure    *closure,gpointer     data),
                                                 gpointer data);

Finds the first entry in an accelerator group for which `find_func` returns `TRUE` and returns its GtkAccelKey.

`accel_group` : | a GtkAccelGroup
`find_func` : | a function to filter the entries of `accel_group` with
`data` : | data to pass to `find_func`
Returns : | the key of the first entry passing `find_func`. The key is owned by GTK+ and must not be freed.

### struct GtkAccelKey

    struct GtkAccelKey
    {
      guint           accel_key;
      GdkModifierType accel_mods;
      guint           accel_flags : 16;
    };

### gtk_accelerator_valid ()

    gboolean    gtk_accelerator_valid           (guint keyval,
                                                 GdkModifierType modifiers);

Determines whether a given keyval and modifier mask constitute a valid keyboard accelerator. For example, the GDK_a keyval plus GDK_CONTROL_MASK is valid - this is a "Ctrl+a" accelerator. But, you can't, for instance, use the GDK_Control_L keyval as an accelerator.

`keyval` : | a GDK keyval
`modifiers` : | modifier mask
Returns : | `TRUE` if the accelerator is valid

### gtk_accelerator_parse ()

    void        gtk_accelerator_parse           (const gchar *accelerator,
                                                 guint *accelerator_key,
                                                 GdkModifierType *accelerator_mods);

Parses a string representing an accelerator. The format looks like "<Control>a" or "<Shift><Alt>F1" or "<Release>z" (the last one is for key release). The parser is fairly liberal and allows lower or upper case, and also abbreviations such as "<Ctl>" and "<Ctrl>".

If the parse fails, `accelerator_key` and `accelerator_mods` will be set to 0 (zero).

`accelerator` : | string representing an accelerator
`accelerator_key` : | return location for accelerator keyval
`accelerator_mods` : | return location for accelerator modifier mask

### gtk_accelerator_name ()

    gchar*      gtk_accelerator_name            (guint accelerator_key,
                                                 GdkModifierType accelerator_mods);

Converts an accelerator keyval and modifier mask into a string parseable by gtk_accelerator_parse(). For example, if you pass in GDK_q and GDK_CONTROL_MASK, this function returns "<Control>q".

The caller of this function must free the returned string.

`accelerator_key` : | accelerator keyval
`accelerator_mods` : | accelerator modifier mask
Returns : | a newly-allocated accelerator name

### gtk_accelerator_set_default_mod_mask ()

    void        gtk_accelerator_set_default_mod_mask
                                                (GdkModifierType default_mod_mask);

Sets the modifiers that will be considered significant for keyboard accelerators. The default mod mask is GDK_CONTROL_MASK | GDK_SHIFT_MASK | GDK_MOD1_MASK, that is, Control, Shift, and Alt. Other modifiers will by default be ignored by GtkAccelGroup. You must include at least the three default modifiers in any value you pass to this function.

The default mod mask should be changed on application startup, before using any accelerator groups.

`default_mod_mask` : | accelerator modifier mask

### gtk_accelerator_get_default_mod_mask ()

    guint       gtk_accelerator_get_default_mod_mask
                                                (void);

Gets the value set by gtk_accelerator_set_default_mod_mask().

Returns : | the default accelerator modifier mask

## Signals

### The "accel-activate" signal

    gboolean    user_function                  (GtkAccelGroup *accelgroup,
                                                GObject *arg1,
                                                guint arg2,
                                                GdkModifierType arg3,
                                                gpointer user_data);

### The "accel-changed" signal

    void        user_function                  (GtkAccelGroup *accelgroup,
                                                guint arg1,
                                                GdkModifierType arg2,
                                                GClosure arg3,
                                                gpointer user_data);

## See Also

gtk_window_add_accel_group(), gtk_accel_map_change_entry(), gtk_item_factory_new(), gtk_label_new_with_mnemonic()

<<< Previous Page | Home | Up | Next Page >>>
Main loop and Events | Accelerator Maps