Keyboard Accelerators

Name

Keyboard Accelerators -- global keyboard accelerators (for an entire GtkWindow)

Synopsis


#include <gtk/gtk.h>


struct      GtkAccelGroup;
GtkAccelGroup* gtk_accel_group_new          (void);
GtkAccelGroup* gtk_accel_group_get_default  (void);
GtkAccelGroup* gtk_accel_group_ref          (GtkAccelGroup *accel_group);
void        gtk_accel_group_unref           (GtkAccelGroup *accel_group);
gboolean    gtk_accel_group_activate        (GtkAccelGroup *accel_group,
                                             guint accel_key,
                                             GdkModifierType accel_mods);
gboolean    gtk_accel_groups_activate       (GObject *object,
                                             guint accel_key,
                                             GdkModifierType accel_mods);
void        gtk_accel_group_attach          (GtkAccelGroup *accel_group,
                                             GObject *object);
void        gtk_accel_group_detach          (GtkAccelGroup *accel_group,
                                             GObject *object);
void        gtk_accel_group_add             (GtkAccelGroup *accel_group,
                                             guint accel_key,
                                             GdkModifierType accel_mods,
                                             GtkAccelFlags accel_flags,
                                             GObject *object,
                                             const gchar *accel_signal);
void        gtk_accel_group_remove          (GtkAccelGroup *accel_group,
                                             guint accel_key,
                                             GdkModifierType accel_mods,
                                             GObject *object);
void        gtk_accel_group_lock            (GtkAccelGroup *accel_group);
void        gtk_accel_group_unlock          (GtkAccelGroup *accel_group);
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);


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.

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;

On opaque data type representing a group of accelerators.


gtk_accel_group_new ()

GtkAccelGroup* gtk_accel_group_new          (void);

Creates a new GtkAccelGroup.

Returns : a new GtkAccelGroup


gtk_accel_group_get_default ()

GtkAccelGroup* gtk_accel_group_get_default  (void);

Gets the global default accelerator group; this is a fallback used for all objects when gtk_accel_groups_activate() is called on them. As such it's probably not appropriate for most uses. (Accelerators are normally specific to a document window or the like, rather than global to an application.)

The returned value does not have its reference count incremented, and should not be unreferenced.

Returns : the default accelerator group


gtk_accel_group_ref ()

GtkAccelGroup* gtk_accel_group_ref          (GtkAccelGroup *accel_group);

This is simply equivalent to g_object_ref (G_OBJECT (accel_group)), and exists for historical reasons only.

accel_group : a GtkAccelGroup
Returns : accel_group


gtk_accel_group_unref ()

void        gtk_accel_group_unref           (GtkAccelGroup *accel_group);

This is simply equivalent to g_object_unref (G_OBJECT (accel_group)), and exists for historical reasons only.

accel_group : a GtkAccelGroup


gtk_accel_group_activate ()

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

Checks whether a key event matches an accelerator in accel_group; if so, activates the accelerator, and returns TRUE. Returns FALSE if no match.

gtk_accel_groups_activate() should normally be used instead of this function.

accel_group : a GtkAccelGroup
accel_key : keyval from a key event
accel_mods : modifier mask from a key event
Returns : TRUE if an accelerator was activated


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 no accelerators are found in groups attached to object, this function also tries the default GtkAccelGroup (see gtk_accel_group_get_default()). If an accelerator is activated, returns TRUE, otherwise FALSE.

object : a GObject
accel_key : accelerator keyval from a key event
accel_mods : keyboard state mask from a key event
Returns : TRUE if an accelerator was activated


gtk_accel_group_attach ()

void        gtk_accel_group_attach          (GtkAccelGroup *accel_group,
                                             GObject *object);

Associate accel_group with object, such that calling gtk_accel_groups_activate() on object will activate accelerators in accel_group.

After calling this function, you still own a reference to both accel_group and object; gtk_accel_group_attach() will not "adopt" a reference to either one.

accel_group : a GtkAccelGroup
object : object to attach accelerators to


gtk_accel_group_detach ()

void        gtk_accel_group_detach          (GtkAccelGroup *accel_group,
                                             GObject *object);

Reverses the effects of gtk_accel_group_attach().

accel_group : a GtkAccelGroup
object : a GObject


gtk_accel_group_add ()

void        gtk_accel_group_add             (GtkAccelGroup *accel_group,
                                             guint accel_key,
                                             GdkModifierType accel_mods,
                                             GtkAccelFlags accel_flags,
                                             GObject *object,
                                             const gchar *accel_signal);

Adds an accelerator to accel_group. When the accelerator is activated, the accel_signal signal will be emitted on object.

So for example, to click a button when Ctrl+a is pressed, you would write: gtk_accel_group_add (accel_group, GDK_a, GDK_CONTROL_MASK, 0, G_OBJECT (button), "clicked").

accel_flags is not particularly useful, always pass 0 for normal applications.

object must be an object that specifically supports accelerators, such as GtkWidget.

accel_group : a GtkAccelGroup
accel_key : accelerator keyval
accel_mods : accelerator modifiers
accel_flags : accelerator flags
object : object that accel_signal will be emitted on
accel_signal : name of a G_SIGNAL_ACTION signal to emit


gtk_accel_group_remove ()

void        gtk_accel_group_remove          (GtkAccelGroup *accel_group,
                                             guint accel_key,
                                             GdkModifierType accel_mods,
                                             GObject *object);

Removes an accelerator. The accel_key, accel_mods, and object arguments are the same ones used to add the accelerator with gtk_accel_group_add().

accel_group : a GtkAccelGroup
accel_key : accelerator keyval
accel_mods : accelerator modifiers
object : object the accelerator activates


gtk_accel_group_lock ()

void        gtk_accel_group_lock            (GtkAccelGroup *accel_group);

Prevents the addition of new accelerators to accel_group. Primarily used to avoid the "dynamic accelerator editing" feature of GtkMenu.

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

Allows the addition of new accelerators to accel_group. Primarily used to enable the "dynamic accelerator editing" feature of GtkMenu.

accel_group : a GtkAccelGroup


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 use the NumLock key 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 mod 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 return value.

accelerator_key : an accelerator keyval
accelerator_mods : modifier mask
Returns : the new 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 be ignored by GtkAccelGroup.

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

default_mod_mask : a 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 modifier mask.

See Also

gtk_label_new_with_mnemonic(), gtk_window_add_accel_group()