1 <!-- ##### SECTION Title ##### -->
4 <!-- ##### SECTION Short_Description ##### -->
5 Key bindings for individual widgets
7 <!-- ##### SECTION Long_Description ##### -->
9 GtkBinding provides a mechanism for configuring GTK+ key bindings through
10 RC files. This eases key binding adjustments for application developers as
11 well as users and provides GTK+ users or administrators with high key
12 binding configurability which requires no application or toolkit side changes.
16 <anchor id="gtk-bindings-install"/>
17 <title>Installing a key binding</title>
20 A resource file binding consists of a 'binding' definition and a match
21 statement to apply the binding to specific widget types. Details on the
22 matching mechanism are described under
23 <link linkend="gtkrc-pathnames-and-patterns">Pathnames and patterns</link>.
24 Inside the binding definition, key combinations are bound to specific signal
25 emissions on the target widget. Key combinations are strings consisting of
26 an optional #GdkModifierType name and
27 <link linkend="gdk-Keyboard-Handling">key names</link> such as those defined
28 in <filename><gdk/gdkkeysyms.h></filename> or returned from
29 gdk_keyval_name(), they have to be parsable by gtk_accelerator_parse().
30 Specifications of signal emissions consist of a string identifying the signal
31 name, and a list of signal specific arguments in parenthesis.
34 For example for binding Control and the left or right cursor keys of a
35 #GtkEntry widget to the #GtkEntry::move-cursor signal, so movement occurs
36 in 3 letter steps, the following binding can be used:
38 <informalexample><programlisting>
39 binding "MoveCursor3" {
40 bind "<Control>Right" {
41 "move-cursor" (visual-positions, 3, 0)
43 bind "<Control>Left" {
44 "move-cursor" (visual-positions, -3, 0)
47 class "GtkEntry" binding "MoveCursor3"
48 </programlisting></informalexample>
52 <anchor id="gtk-bindings-unbind"/>
53 <title>Unbinding existing key bindings</title>
55 GTK+ already defines a number of useful bindings for the widgets it provides.
56 Because custom bindings set up in RC files take precedence over the default
57 bindings shipped with GTK+, overriding existing bindings as demonstrated in
58 <link linkend="gtk-bindings-install">Installing a key binding</link>
59 works as expected. The same mechanism can not be used to "unbind" existing
62 <informalexample><programlisting>
63 binding "MoveCursor3" {
64 bind "<Control>Right" { }
65 bind "<Control>Left" { }
67 class "GtkEntry" binding "MoveCursor3"
68 </programlisting></informalexample>
70 The above example will not have the desired effect of causing
71 "<Control>Right" and "<Control>Left" key presses to be ignored
72 by GTK+. Instead, it just causes any existing bindings from the bindings
73 set "MoveCursor3" to be deleted, so when "<Control>Right" or
74 "<Control>Left" are pressed, no binding for these keys is found in
75 binding set "MoveCursor3". GTK+ will thus continue to search for matching
76 key bindings, and will eventually lookup and find the default GTK+ bindings
77 for entries which implement word movement. To keep GTK+ from activating its
78 default bindings, the "unbind" keyword can be used like this:
80 <informalexample><programlisting>
81 binding "MoveCursor3" {
82 unbind "<Control>Right"
83 unbind "<Control>Left"
85 class "GtkEntry" binding "MoveCursor3"
86 </programlisting></informalexample>
88 Now, GTK+ will find a match when looking up "<Control>Right" and
89 "<Control>Left" key presses before it resorts to its default
90 bindings, and the match instructs it to abort ("unbind") the search, so
91 the key presses are not consumed by this widget. As usual, further processing
92 of the key presses, e.g. by an entry's parent widget, is now possible.
96 The "unbind" functionality has been introduced in GTK+ 2.12.
101 <!-- ##### SECTION See_Also ##### -->
106 <term><link linkend="gtk-keyboard-accelerators">Keyboard Accelerators</link>
108 <listitem><para>installing and using keyboard short-cuts.</para></listitem>
112 <term><link linkend="Resource-Files">Resource Files</link>
114 <listitem><para>GTK+ Resource Files - behavior and style definitions.</para></listitem>
120 <!-- ##### SECTION Stability_Level ##### -->
123 <!-- ##### STRUCT GtkBindingSet ##### -->
125 A binding set maintains a list of activatable key bindings.
126 A single binding set can match multiple types of widgets.
127 Similar to styles, widgets can be mapped by widget name paths, widget
128 class paths or widget class types. When a binding within a set is
129 matched upon activation, an action signal is emitted on the target
130 widget to carry out the actual activation.
133 @set_name: unique binding set name
135 @widget_path_pspecs: widgets matched by path that this binding set applies to
136 @widget_class_pspecs: widgets matched by class path that this binding set applies to
137 @class_branch_pspecs: widgets matched by class that this binding set applies to
138 @entries: the key binding entries in this binding set
139 @current: implementation detail
140 @parsed: whether this binding set stems from an RC file and is reset upon theme changes
142 <!-- ##### STRUCT GtkBindingEntry ##### -->
144 Each key binding element of a binding sets binding list is represented by
148 @keyval: key value to match
149 @modifiers: key modifier to match
150 @binding_set: binding set this entry belongs to
151 @destroyed: implementation detail
152 @in_emission: implementation detail
153 @marks_unbound: implementation detail
154 @set_next: linked list of entries maintained by binding set
155 @hash_next: implementation detail
156 @signals: action signals of this entry
158 <!-- ##### STRUCT GtkBindingSignal ##### -->
160 A #GtkBindingSignal stores the necessary information to activate a widget
161 in response to a key press via a signal emission.
164 @next: implementation detail
165 @signal_name: the action signal to be emitted
166 @n_args: number of arguments specified for the signal
167 @args: the arguments specified for the signal
169 <!-- ##### STRUCT GtkBindingArg ##### -->
171 A #GtkBindingArg holds the data associated with an argument for a
172 key binding signal emission as stored in #GtkBindingSignal.
175 @arg_type: implementation detail
177 <!-- ##### MACRO gtk_binding_entry_add ##### -->
184 <!-- ##### FUNCTION gtk_binding_entry_add_signall ##### -->
196 <!-- ##### FUNCTION gtk_binding_entry_clear ##### -->
206 <!-- ##### FUNCTION gtk_binding_parse_binding ##### -->
215 <!-- ##### FUNCTION gtk_binding_set_new ##### -->
224 <!-- ##### FUNCTION gtk_binding_set_by_class ##### -->
233 <!-- ##### FUNCTION gtk_binding_set_find ##### -->
242 <!-- ##### FUNCTION gtk_bindings_activate ##### -->
253 <!-- ##### FUNCTION gtk_bindings_activate_event ##### -->
263 <!-- ##### FUNCTION gtk_binding_set_activate ##### -->
275 <!-- ##### FUNCTION gtk_binding_entry_add_signal ##### -->
288 <!-- ##### FUNCTION gtk_binding_entry_skip ##### -->
298 <!-- ##### FUNCTION gtk_binding_entry_remove ##### -->
308 <!-- ##### FUNCTION gtk_binding_set_add_path ##### -->