Bindings

Bindings — Key bindings for individual widgets

Synopsis

#include <gtk/gtk.h>

                    GtkBindingSet;
                    GtkBindingEntry;
                    GtkBindingSignal;
                    GtkBindingArg;
#define             gtk_binding_entry_add
void                gtk_binding_entry_add_signall       (GtkBindingSet *binding_set,
                                                         guint keyval,
                                                         GdkModifierType modifiers,
                                                         const gchar *signal_name,
                                                         GSList *binding_args);
void                gtk_binding_entry_clear             (GtkBindingSet *binding_set,
                                                         guint keyval,
                                                         GdkModifierType modifiers);
guint               gtk_binding_parse_binding           (GScanner *scanner);
GtkBindingSet*      gtk_binding_set_new                 (const gchar *set_name);
GtkBindingSet*      gtk_binding_set_by_class            (gpointer object_class);
GtkBindingSet*      gtk_binding_set_find                (const gchar *set_name);
gboolean            gtk_bindings_activate               (GtkObject *object,
                                                         guint keyval,
                                                         GdkModifierType modifiers);
gboolean            gtk_bindings_activate_event         (GtkObject *object,
                                                         GdkEventKey *event);
gboolean            gtk_binding_set_activate            (GtkBindingSet *binding_set,
                                                         guint keyval,
                                                         GdkModifierType modifiers,
                                                         GtkObject *object);
void                gtk_binding_entry_add_signal        (GtkBindingSet *binding_set,
                                                         guint keyval,
                                                         GdkModifierType modifiers,
                                                         const gchar *signal_name,
                                                         guint n_args,
                                                         ...);
void                gtk_binding_entry_skip              (GtkBindingSet *binding_set,
                                                         guint keyval,
                                                         GdkModifierType modifiers);
void                gtk_binding_entry_remove            (GtkBindingSet *binding_set,
                                                         guint keyval,
                                                         GdkModifierType modifiers);
void                gtk_binding_set_add_path            (GtkBindingSet *binding_set,
                                                         GtkPathType path_type,
                                                         const gchar *path_pattern,
                                                         GtkPathPriorityType priority);

Description

GtkBinding provides a mechanism for configuring GTK+ key bindings through RC files. This eases key binding adjustments for application developers as well as users and provides GTK+ users or administrators with high key binding configurability which requires no application or toolkit side changes.

Installing a key binding

A resource file binding consists of a 'binding' definition and a match statement to apply the binding to specific widget types. Details on the matching mechanism are described under Pathnames and patterns. Inside the binding definition, key combinations are bound to specific signal emissions on the target widget. Key combinations are strings consisting of an optional GdkModifierType name and key names such as those defined in <gdk/gdkkeysyms.h> or returned from gdk_keyval_name(), they have to be parsable by gtk_accelerator_parse(). Specifications of signal emissions consist of a string identifying the signal name, and a list of signal specific arguments in parenthesis.

For example for binding Control and the left or right cursor keys of a GtkEntry widget to the "move-cursor" signal, so movement occurs in 3 letter steps, the following binding can be used:

1
2
3
4
5
6
7
8
9
binding "MoveCursor3" {
  bind "<Control>Right" {
    "move-cursor" (visual-positions, 3, 0)
  }
  bind "<Control>Left" {
    "move-cursor" (visual-positions, -3, 0)
  }
}
class "GtkEntry" binding "MoveCursor3"

GTK+ already defines a number of useful bindings for the widgets it provides. Because custom bindings set up in RC files take precedence over the default bindings shipped with GTK+, overriding existing bindings as demonstrated in Installing a key binding works as expected. The same mechanism can not be used to "unbind" existing bindings, however.

1
2
3
4
5
binding "MoveCursor3" {
  bind "<Control>Right" { }
  bind "<Control>Left" { }
}
class "GtkEntry" binding "MoveCursor3"

The above example will not have the desired effect of causing "<Control>Right" and "<Control>Left" key presses to be ignored by GTK+. Instead, it just causes any existing bindings from the bindings set "MoveCursor3" to be deleted, so when "<Control>Right" or "<Control>Left" are pressed, no binding for these keys is found in binding set "MoveCursor3". GTK+ will thus continue to search for matching key bindings, and will eventually lookup and find the default GTK+ bindings for entries which implement word movement. To keep GTK+ from activating its default bindings, the "unbind" keyword can be used like this:

1
2
3
4
5
binding "MoveCursor3" {
  unbind "<Control>Right"
  unbind "<Control>Left"
}
class "GtkEntry" binding "MoveCursor3"

Now, GTK+ will find a match when looking up "<Control>Right" and "<Control>Left" key presses before it resorts to its default bindings, and the match instructs it to abort ("unbind") the search, so the key presses are not consumed by this widget. As usual, further processing of the key presses, e.g. by an entry's parent widget, is now possible.

The "unbind" functionality has been introduced in GTK+ 2.12.

Details

GtkBindingSet

typedef struct {
  gchar			*set_name;
  gint			 priority;
  GSList		*widget_path_pspecs;
  GSList		*widget_class_pspecs;
  GSList		*class_branch_pspecs;
  GtkBindingEntry *entries;
  GtkBindingEntry *current;
  guint                  parsed : 1; /* From RC content */
} GtkBindingSet;

A binding set maintains a list of activatable key bindings. A single binding set can match multiple types of widgets. Similar to styles, widgets can be mapped by widget name paths, widget class paths or widget class types. When a binding within a set is matched upon activation, an action signal is emitted on the target widget to carry out the actual activation.

gchar *set_name;

unique binding set name

gint priority;

unused

GSList *widget_path_pspecs;

widgets matched by path that this binding set applies to

GSList *widget_class_pspecs;

widgets matched by class path that this binding set applies to

GSList *class_branch_pspecs;

widgets matched by class that this binding set applies to

GtkBindingEntry *entries;

the key binding entries in this binding set

GtkBindingEntry *current;

implementation detail

guint parsed : 1;

whether this binding set stems from an RC file and is reset upon theme changes

GtkBindingEntry

typedef struct {
  /* key portion
   */
  guint			 keyval;
  GdkModifierType	 modifiers;
  
  GtkBindingSet		*binding_set;
  guint			destroyed : 1;
  guint			in_emission : 1;
  guint                 marks_unbound : 1;
  GtkBindingEntry *set_next;
  GtkBindingEntry *hash_next;
  GtkBindingSignal *signals;
} GtkBindingEntry;

Each key binding element of a binding sets binding list is represented by a GtkBindingEntry.

guint keyval;

key value to match

GdkModifierType modifiers;

key modifier to match

GtkBindingSet *binding_set;

binding set this entry belongs to

guint destroyed : 1;

implementation detail

guint in_emission : 1;

implementation detail

guint marks_unbound : 1;

implementation detail

GtkBindingEntry *set_next;

linked list of entries maintained by binding set

GtkBindingEntry *hash_next;

implementation detail

GtkBindingSignal *signals;

action signals of this entry

GtkBindingSignal

typedef struct {
  GtkBindingSignal *next;
  gchar 		*signal_name;
  guint			 n_args;
  GtkBindingArg		*args;
} GtkBindingSignal;

A GtkBindingSignal stores the necessary information to activate a widget in response to a key press via a signal emission.

GtkBindingSignal *next;

implementation detail

gchar *signal_name;

the action signal to be emitted

guint n_args;

number of arguments specified for the signal

GtkBindingArg *args;

the arguments specified for the signal

GtkBindingArg

typedef struct {
  GType		 arg_type;
  union {
    glong	 long_data;
    gdouble	 double_data;
    gchar *string_data;
  } d;
} GtkBindingArg;

A GtkBindingArg holds the data associated with an argument for a key binding signal emission as stored in GtkBindingSignal.

GType arg_type;

implementation detail

gtk_binding_entry_add

#define	 gtk_binding_entry_add		gtk_binding_entry_clear

Warning

gtk_binding_entry_add has been deprecated since version 2.12 and should not be used in newly-written code. Use gtk_binding_entry_add_signal() instead.

Adds a binding entry.

binding_set :

#a GtkBindingSet to clear an entry of

keyval :

key value of binding to clear

modifiers :

key modifier of binding to clear

gtk_binding_entry_add_signall ()

void                gtk_binding_entry_add_signall       (GtkBindingSet *binding_set,
                                                         guint keyval,
                                                         GdkModifierType modifiers,
                                                         const gchar *signal_name,
                                                         GSList *binding_args);

Override or install a new key binding for keyval with modifiers on binding_set.

binding_set :

a GtkBindingSet to add a signal to

keyval :

key value

modifiers :

key modifier

signal_name :

signal name to be bound

binding_args :

list of GtkBindingArg signal arguments

gtk_binding_entry_clear ()

void                gtk_binding_entry_clear             (GtkBindingSet *binding_set,
                                                         guint keyval,
                                                         GdkModifierType modifiers);

Warning

gtk_binding_entry_clear has been deprecated since version 2.12 and should not be used in newly-written code. Use gtk_binding_entry_remove() instead.

Clears a binding entry.

binding_set :

binding set to clear an entry of

keyval :

key value of binding to clear

modifiers :

key modifier of binding to clear

gtk_binding_parse_binding ()

guint               gtk_binding_parse_binding           (GScanner *scanner);

Warning

gtk_binding_parse_binding has been deprecated since version 2.12 and should not be used in newly-written code. There should be no need to call this function outside GTK+.

Parse a binding entry from a gtkrc file.

scanner :

GtkRC scanner

Returns :

expected token upon errors, G_TOKEN_NONE on success.

gtk_binding_set_new ()

GtkBindingSet*      gtk_binding_set_new                 (const gchar *set_name);

GTK+ maintains a global list of binding sets. Each binding set has a unique name which needs to be specified upon creation.

set_name :

unique name of this binding set

Returns :

new binding set

gtk_binding_set_by_class ()

GtkBindingSet*      gtk_binding_set_by_class            (gpointer object_class);

This function returns the binding set named after the type name of the passed in class structure. New binding sets are created on demand by this function.

object_class :

a valid GtkObject class

Returns :

the binding set corresponding to object_class

gtk_binding_set_find ()

GtkBindingSet*      gtk_binding_set_find                (const gchar *set_name);

Find a binding set by its globally unique name. The set_name can either be a name used for gtk_binding_set_new() or the type name of a class used in gtk_binding_set_by_class().

set_name :

unique binding set name

Returns :

NULL or the specified binding set

gtk_bindings_activate ()

gboolean            gtk_bindings_activate               (GtkObject *object,
                                                         guint keyval,
                                                         GdkModifierType modifiers);

Find a key binding matching keyval and modifiers and activate the binding on object.

object :

object to activate when binding found

keyval :

key value of the binding

modifiers :

key modifier of the binding

Returns :

TRUE if a binding was found and activated

gtk_bindings_activate_event ()

gboolean            gtk_bindings_activate_event         (GtkObject *object,
                                                         GdkEventKey *event);

Looks up key bindings for object to find one matching event, and if one was found, activate it.

object :

a GtkObject (generally must be a widget)

event :

a GdkEventKey

Returns :

TRUE if a matching key binding was found

Since 2.4


gtk_binding_set_activate ()

gboolean            gtk_binding_set_activate            (GtkBindingSet *binding_set,
                                                         guint keyval,
                                                         GdkModifierType modifiers,
                                                         GtkObject *object);

Find a key binding matching keyval and modifiers within binding_set and activate the binding on object.

binding_set :

a GtkBindingSet set to activate

keyval :

key value of the binding

modifiers :

key modifier of the binding

object :

object to activate when binding found

Returns :

TRUE if a binding was found and activated

gtk_binding_entry_add_signal ()

void                gtk_binding_entry_add_signal        (GtkBindingSet *binding_set,
                                                         guint keyval,
                                                         GdkModifierType modifiers,
                                                         const gchar *signal_name,
                                                         guint n_args,
                                                         ...);

Override or install a new key binding for keyval with modifiers on binding_set. When the binding is activated, signal_name will be emitted on the target widget, with n_args Varargs used as arguments.

binding_set :

a GtkBindingSet to install an entry for

keyval :

key value of binding to install

modifiers :

key modifier of binding to install

signal_name :

signal to execute upon activation

n_args :

number of arguments to signal_name

... :

arguments to signal_name

gtk_binding_entry_skip ()

void                gtk_binding_entry_skip              (GtkBindingSet *binding_set,
                                                         guint keyval,
                                                         GdkModifierType modifiers);

Install a binding on binding_set which causes key lookups to be aborted, to prevent bindings from lower priority sets to be activated.

binding_set :

a GtkBindingSet to skip an entry of

keyval :

key value of binding to skip

modifiers :

key modifier of binding to skip

Since 2.12


gtk_binding_entry_remove ()

void                gtk_binding_entry_remove            (GtkBindingSet *binding_set,
                                                         guint keyval,
                                                         GdkModifierType modifiers);

Remove a binding previously installed via gtk_binding_entry_add_signal() on binding_set.

binding_set :

a GtkBindingSet to remove an entry of

keyval :

key value of binding to remove

modifiers :

key modifier of binding to remove

gtk_binding_set_add_path ()

void                gtk_binding_set_add_path            (GtkBindingSet *binding_set,
                                                         GtkPathType path_type,
                                                         const gchar *path_pattern,
                                                         GtkPathPriorityType priority);

This function is used internally by the GtkRC parsing mechanism to assign match patterns to GtkBindingSet structures.

binding_set :

a GtkBindingSet to add a path to

path_type :

path type the pattern applies to

path_pattern :

the actual match pattern

priority :

binding priority

See Also

Keyboard Accelerators

installing and using keyboard short-cuts.

Resource Files

GTK+ Resource Files - behavior and style definitions.