## Keyboard Accelerators Keyboard Accelerators — Utilities for accelerators |

## Functions

gboolean | gtk_accelerator_valid ()
gboolean | gtk_accelerator_parse ()
gchar * | gtk_accelerator_name ()
gchar * | gtk_accelerator_get_label ()
gboolean | gtk_accelerator_parse_with_keycode ()
gchar * | gtk_accelerator_name_with_keycode ()
gchar * | gtk_accelerator_get_label_with_keycode ()
GdkModifierType | gtk_accelerator_get_default_mod_mask ()

## Includes

    #include <gtk/gtk.h>

## Description

We have various utility functions to parse and generate textual representations of keyboard accelerators.

If you want to set up keyboard accelerators for widgets, GtkShortcutTrigger is probably more convenient than the functions in this section.

## Functions

### 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_KEY_a keyval plus GDK_CONTROL_MASK is valid - this is a “Ctrl+a” accelerator. But, you can't, for instance, use the GDK_KEY_Control_L keyval as an accelerator.

#### Parameters

keyval | a GDK keyval |
modifiers | modifier mask |

#### Returns

`TRUE` if the accelerator is valid

### gtk_accelerator_parse ()

    gboolean
    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”.

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, or `NULL`. | [out][allow-none]
accelerator_mods | return location for accelerator modifier mask, `NULL`. | [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_KEY_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.

### gtk_accelerator_parse_with_keycode ()

    gboolean
    gtk_accelerator_parse_with_keycode (const gchar *accelerator,
                                        GdkDisplay *display,
                                        guint *accelerator_key,
                                        guint **accelerator_codes,
                                        GdkModifierType *accelerator_mods);

Parses a string representing an accelerator, similarly to `gtk_accelerator_parse()` but handles keycodes as well. This is only useful for system-level components, applications should use `gtk_accelerator_parse()` instead.

If `accelerator_codes` is given and the result stored in it is non-`NULL`, the result must be freed with `g_free()`.

If a keycode is present in the accelerator and no `accelerator_codes` is given, the parse will fail.

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

#### Parameters

accelerator | string representing an accelerator |
display | the GdkDisplay to look up `accelerator_codes` in. | [allow-none]
accelerator_key | return location for accelerator keyval, or `NULL`. | [out][allow-none]
accelerator_codes | return location for accelerator keycodes, or `NULL`. | [out][array zero-terminated=1][transfer full][allow-none]
accelerator_mods | return location for accelerator modifier mask, `NULL`. | [out][allow-none]

#### Returns

`TRUE` if parsing succeeded

### gtk_accelerator_name_with_keycode ()

    gchar *
    gtk_accelerator_name_with_keycode (GdkDisplay *display,
                                       guint accelerator_key,
                                       guint keycode,
                                       GdkModifierType accelerator_mods);

Converts an accelerator keyval and modifier mask into a string parseable by `gtk_accelerator_parse_with_keycode()`, similarly to `gtk_accelerator_name()` but handling keycodes. This is only useful for system-level components, applications should use `gtk_accelerator_parse()` instead.

#### Parameters

display | a GdkDisplay or `NULL` to use the default display. | [allow-none]
accelerator_key | accelerator keyval |
keycode | accelerator keycode |
accelerator_mods | accelerator modifier mask |

#### Returns

a newly allocated accelerator name.

### gtk_accelerator_get_label_with_keycode ()

    gchar *
    gtk_accelerator_get_label_with_keycode
                                   (GdkDisplay *display,
                                    guint accelerator_key,
                                    guint keycode,
                                    GdkModifierType accelerator_mods);

Converts an accelerator keyval and modifier mask into a (possibly translated) string that can be displayed to a user, similarly to `gtk_accelerator_get_label()`, but handling keycodes.

This is only useful for system-level components, applications should use `gtk_accelerator_parse()` instead.

#### Parameters

display | a GdkDisplay or `NULL` to use the default display. | [allow-none]
accelerator_key | accelerator keyval |
keycode | accelerator keycode |
accelerator_mods | accelerator modifier mask |

#### Returns

a newly-allocated string representing the accelerator.

### gtk_accelerator_get_default_mod_mask ()

    GdkModifierType
    gtk_accelerator_get_default_mod_mask (void);

Gets the modifier mask.

The modifier mask determines which modifiers are considered significant for keyboard accelerators. This includes all keyboard modifiers except for `GDK_LOCK_MASK`.

#### Returns

the modifier mask for accelerators