Accelerator Groups: GTK+ 2 Reference Manual

## Accelerator Groups Accelerator Groups — Groups of global keyboard accelerators for an entire GtkWindow |

## Functions

GtkAccelGroup * | gtk_accel_group_new ()
void | gtk_accel_group_connect ()
void | gtk_accel_group_connect_by_path ()
gboolean | (*GtkAccelGroupActivate) ()
gboolean | (*GtkAccelGroupFindFunc) ()
gboolean | gtk_accel_group_disconnect ()
gboolean | gtk_accel_group_disconnect_key ()
GtkAccelGroupEntry * | gtk_accel_group_query ()
gboolean | gtk_accel_group_activate ()
void | gtk_accel_group_lock ()
void | gtk_accel_group_unlock ()
gboolean | gtk_accel_group_get_is_locked ()
GtkAccelGroup * | gtk_accel_group_from_accel_closure ()
GdkModifierType | gtk_accel_group_get_modifier_mask ()
gboolean | gtk_accel_groups_activate ()
GSList * | gtk_accel_groups_from_object ()
GtkAccelKey * | gtk_accel_group_find ()
gboolean | gtk_accelerator_valid ()
void | gtk_accelerator_parse ()
gchar * | gtk_accelerator_name ()
gchar * | gtk_accelerator_get_label ()
void | gtk_accelerator_set_default_mod_mask ()
guint | gtk_accelerator_get_default_mod_mask ()

## Properties

gboolean | is-locked | Read
GdkModifierType | modifier-mask | Read

## Signals

gboolean | accel-activate | Has Details
void | accel-changed | Has Details

## Types and Values

struct | GtkAccelGroup
#define | gtk_accel_group_ref
#define | gtk_accel_group_unref
struct | GtkAccelKey

## Object Hierarchy

        GObject
        ╰── GtkAccelGroup

## Includes

    #include <gtk/gtk.h>

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

## Functions

### gtk_accel_group_new ()

    GtkAccelGroup *
    gtk_accel_group_new (void);

Creates a new GtkAccelGroup.

#### Parameters

returns | a new GtkAccelGroup object |

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

#### Parameters

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.

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_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);

### GtkAccelGroupFindFunc ()

    gboolean
    (*GtkAccelGroupFindFunc) (GtkAccelKey *key,
                              GClosure *closure,
                              gpointer data);

Since: 2.2

### gtk_accel_group_disconnect ()

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

Removes an accelerator previously installed through `gtk_accel_group_connect()`.

Since 2.20 `closure` can be `NULL`.

#### Parameters

accel_group | the accelerator group to remove an accelerator from |
closure | the closure to remove from this accelerator group, or `NULL` to remove all closures. | [allow-none]
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()`.

#### Parameters

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

#### Parameters

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`. | [allow-none]
returns | an array of `n_entries` GtkAccelGroupEntry elements, or `NULL`. The array is owned by GTK+ and must not be freed. | [allow-none]

### gtk_accel_group_activate ()

    gboolean
    gtk_accel_group_activate (GtkAccelGroup *accel_group,
                              GQuark accel_quark,
                              GObject *acceleratable,
                              guint accel_key,
                              GdkModifierType accel_mods);

Finds the first accelerator in `accel_group` that matches `accel_key` and `accel_mods` , and activates it.

#### Parameters

accel_group | a GtkAccelGroup |
accel_quark | the quark for the accelerator name |
acceleratable | 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 an accelerator was activated and handled this keypress

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

#### Parameters

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

#### Parameters

accel_group | a GtkAccelGroup |

### gtk_accel_group_get_is_locked ()

    gboolean
    gtk_accel_group_get_is_locked (GtkAccelGroup *accel_group);

Locks are added and removed using `gtk_accel_group_lock()` and `gtk_accel_group_unlock()`.

#### Parameters

accel_group | a GtkAccelGroup |

#### Returns

`TRUE` if there are 1 or more locks on the `accel_group` , `FALSE` otherwise.

Since: 2.14

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

#### Parameters

closure | a GClosure |
returns | the GtkAccelGroup to which `closure` is connected, or `NULL`. | [transfer none]

### gtk_accel_group_get_modifier_mask ()

    GdkModifierType
    gtk_accel_group_get_modifier_mask (GtkAccelGroup *accel_group);

Gets a GdkModifierType representing the mask for this `accel_group` . For example, GDK_CONTROL_MASK, GDK_SHIFT_MASK, etc.

#### Parameters

accel_group | a GtkAccelGroup |

#### Returns

the modifier mask for this accel group.

Since: 2.14

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

#### Parameters

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 an accelerator was activated and handled this keypress

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

#### Parameters

object | a GObject, usually a GtkWindow |

#### Returns

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

[element-type GtkAccelGroup][transfer none]

### gtk_accel_group_find ()

    GtkAccelKey *
    gtk_accel_group_find (GtkAccelGroup *accel_group,
                          GtkAccelGroupFindFunc find_func,
                          gpointer data);

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

#### Parameters

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. | [transfer none]

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

#### Parameters

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>". Key names are parsed using `gdk_keyval_from_name()`. For character keys the name is not the symbol, but the lowercase name, e.g. one would use "<Ctrl>minus" instead of "<Ctrl>-".

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

#### Parameters

accelerator | string representing an accelerator |
accelerator_key | return location for accelerator keyval. | [out][allow-none]
accelerator_mods | return location for accelerator modifier mask. | [out][allow-none]

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

If you need to display accelerators in the user interface, see `gtk_accelerator_get_label()`.

#### Parameters

accelerator_key | accelerator keyval |
accelerator_mods | accelerator modifier mask |

#### Returns

a newly-allocated accelerator name

### gtk_accelerator_get_label ()

    gchar *
    gtk_accelerator_get_label (guint accelerator_key,
                               GdkModifierType accelerator_mods);

Converts an accelerator keyval and modifier mask into a string which can be used to represent the accelerator to the user.

#### Parameters

accelerator_key | accelerator keyval |
accelerator_mods | accelerator modifier mask |

#### Returns

a newly-allocated string representing the accelerator.

Since: 2.6

### 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 | GDK_SUPER_MASK | GDK_HYPER_MASK | GDK_META_MASK, that is, Control, Shift, Alt, Super, Hyper and Meta. Other modifiers will by default be ignored by GtkAccelGroup. You must include at least the three modifiers Control, Shift and Alt in any value you pass to this function.

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

#### Parameters

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

#### Parameters

returns | the default accelerator modifier mask |

## Types and Values

### struct GtkAccelGroup

    struct GtkAccelGroup;

An object representing and maintaining a group of accelerators.

### gtk_accel_group_ref

    #define gtk_accel_group_ref g_object_ref

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

Deprecated equivalent of `g_object_ref()`.

#### Returns

the accel group that was passed in

### gtk_accel_group_unref

    #define gtk_accel_group_unref g_object_unref

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

Deprecated equivalent of `g_object_unref()`.

### struct GtkAccelKey

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

## Property Details

### The `“is-locked”` property

      “is-locked”                gboolean

Is the accel group locked.

Owner: GtkAccelGroup

Flags: Read

Default value: FALSE

### The `“modifier-mask”` property

      “modifier-mask”            GdkModifierType

Modifier Mask.

Owner: GtkAccelGroup

Flags: Read

Default value: GDK_SHIFT_MASK | GDK_CONTROL_MASK | GDK_MOD1_MASK | GDK_SUPER_MASK | GDK_HYPER_MASK | GDK_META_MASK

## Signal Details

### The `“accel-activate”` signal

    gboolean
    user_function (GtkAccelGroup  *accel_group,
                   GObject        *acceleratable,
                   guint           keyval,
                   GdkModifierType modifier,
                   gpointer        user_data)

The accel-activate signal is an implementation detail of GtkAccelGroup and not meant to be used by applications.

#### Parameters

accel_group | the GtkAccelGroup which received the signal |
acceleratable | the object on which the accelerator was activated |
keyval | the accelerator keyval |
modifier | the modifier combination of the accelerator |
user_data | user data set when the signal handler was connected. |

#### Returns

`TRUE` if the accelerator was activated

Flags: Has Details

### The `“accel-changed”` signal

    void
    user_function (GtkAccelGroup  *accel_group,
                   guint           keyval,
                   GdkModifierType modifier,
                   GClosure       *accel_closure,
                   gpointer        user_data)

The accel-changed signal is emitted when a GtkAccelGroupEntry is added to or removed from the accel group.

Widgets like GtkAccelLabel which display an associated accelerator should connect to this signal, and rebuild their visual representation if the `accel_closure` is theirs.

#### Parameters

accel_group | the GtkAccelGroup which received the signal |
keyval | the accelerator keyval |
modifier | the modifier combination of the accelerator |
accel_closure | the GClosure of the accelerator |
user_data | user data set when the signal handler was connected. |

Flags: Has Details

## See Also

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