Bindings
Key bindings for individual widgets
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 #GtkEntry::move-cursor signal, so movement occurs
in 3 letter steps, the following binding can be used:
binding "MoveCursor3" {
bind "<Control>Right" {
"move-cursor" (visual-positions, 3, 0)
}
bind "<Control>Left" {
"move-cursor" (visual-positions, -3, 0)
}
}
class "GtkEntry" binding "MoveCursor3"
Unbinding existing key bindings
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.
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:
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.
Keyboard Accelerators
installing and using keyboard short-cuts.Resource Files
GTK+ Resource Files - behavior and style definitions.
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.
@set_name: unique binding set name
@priority: unused
@widget_path_pspecs: widgets matched by path that this binding set applies to
@widget_class_pspecs: widgets matched by class path that this binding set applies to
@class_branch_pspecs: widgets matched by class that this binding set applies to
@entries: the key binding entries in this binding set
@current: implementation detail
@parsed: whether this binding set stems from an RC file and is reset upon theme changes
Each key binding element of a binding sets binding list is represented by
a #GtkBindingEntry.
@keyval: key value to match
@modifiers: key modifier to match
@binding_set: binding set this entry belongs to
@destroyed: implementation detail
@in_emission: implementation detail
@marks_unbound: implementation detail
@set_next: linked list of entries maintained by binding set
@hash_next: implementation detail
@signals: action signals of this entry
A #GtkBindingSignal stores the necessary information to activate a widget
in response to a key press via a signal emission.
@next: implementation detail
@signal_name: the action signal to be emitted
@n_args: number of arguments specified for the signal
@args: the arguments specified for the signal
A #GtkBindingArg holds the data associated with an argument for a
key binding signal emission as stored in #GtkBindingSignal.
@arg_type: implementation detail
@binding_set:
@keyval:
@modifiers:
@signal_name:
@binding_args:
@binding_set:
@keyval:
@modifiers:
@scanner:
@Returns:
@set_name:
@Returns:
@object_class:
@Returns:
@set_name:
@Returns:
@object:
@keyval:
@modifiers:
@Returns:
@object:
@event:
@Returns:
@binding_set:
@keyval:
@modifiers:
@object:
@Returns:
@binding_set:
@keyval:
@modifiers:
@signal_name:
@n_args:
@...:
@binding_set:
@keyval:
@modifiers:
@binding_set:
@keyval:
@modifiers:
@binding_set:
@path_type:
@path_pattern:
@priority: