Keyboard Accelerators

Keyboard Accelerators — Utilities for accelerators

Functions

Includes

#include <gtk/gtk.h>

Description

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

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” 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, 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_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 depends on the GDK backend in use, but will typically include GDK_CONTROL_MASK | GDK_SHIFT_MASK | GDK_MOD1_MASK | GDK_SUPER_MASK | GDK_HYPER_MASK | GDK_META_MASK. In other words, 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 ()

GdkModifierType
gtk_accelerator_get_default_mod_mask (void);

Gets the modifier mask.

The modifier mask determines which modifiers are considered significant for keyboard accelerators. See gtk_accelerator_set_default_mod_mask().

Returns

the default accelerator modifier mask