Pileus Git - ~andy/gtk/blob - docs/reference/gtk/tmpl/gtkbindings.sgml

   1 <!-- ##### SECTION Title ##### -->
   2 Bindings
   3
   4 <!-- ##### SECTION Short_Description ##### -->
   5 Key bindings for individual widgets
   6
   7 <!-- ##### SECTION Long_Description ##### -->
   8 <para>
   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.
  13 </para>
  14
  15 <refsect2>
  16 <anchor id="gtk-bindings-install"/>
  17 <title>Installing a key binding</title>
  18
  19 <para>
  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>&lt;gdk/gdkkeysyms.h&gt;</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.
  32 </para>
  33 <para>
  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:
  37
  38 <informalexample><programlisting>
  39 binding "MoveCursor3" {
  40   bind "&lt;Control&gt;Right" {
  41     "move-cursor" (visual-positions, 3, 0)
  42   }
  43   bind "&lt;Control&gt;Left" {
  44     "move-cursor" (visual-positions, -3, 0)
  45   }
  46 }
  47 class "GtkEntry" binding "MoveCursor3"
  48 </programlisting></informalexample>
  49 </para>
  50
  51
  52 <anchor id="gtk-bindings-unbind"/>
  53 <title>Unbinding existing key bindings</title>
  54 <para>
  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
  60 bindings, however.
  61
  62 <informalexample><programlisting>
  63 binding "MoveCursor3" {
  64   bind "&lt;Control&gt;Right" { }
  65   bind "&lt;Control&gt;Left" { }
  66 }
  67 class "GtkEntry" binding "MoveCursor3"
  68 </programlisting></informalexample>
  69
  70 The above example will not have the desired effect of causing
  71 "&lt;Control&gt;Right" and "&lt;Control&gt;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 "&lt;Control&gt;Right" or
  74 "&lt;Control&gt;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:
  79
  80 <informalexample><programlisting>
  81 binding "MoveCursor3" {
  82   unbind "&lt;Control&gt;Right"
  83   unbind "&lt;Control&gt;Left"
  84 }
  85 class "GtkEntry" binding "MoveCursor3"
  86 </programlisting></informalexample>
  87
  88 Now, GTK+ will find a match when looking up "&lt;Control&gt;Right" and
  89 "&lt;Control&gt;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.
  93 </para>
  94
  95 <para>
  96 The "unbind" functionality has been introduced in GTK+ 2.12.
  97 </para>
  98
  99 </refsect2>
 100
 101 <!-- ##### SECTION See_Also ##### -->
 102 <para>
 103 <variablelist>
 104
 105 <varlistentry>
 106 <term><link linkend="gtk-keyboard-accelerators">Keyboard Accelerators</link>
 107 </term>
 108 <listitem><para>installing and using keyboard short-cuts.</para></listitem>
 109 </varlistentry>
 110
 111 <varlistentry>
 112 <term><link linkend="Resource-Files">Resource Files</link>
 113 </term>
 114 <listitem><para>GTK+ Resource Files - behavior and style definitions.</para></listitem>
 115 </varlistentry>
 116
 117 </variablelist>
 118 </para>
 119
 120 <!-- ##### SECTION Stability_Level ##### -->
 121
 122
 123 <!-- ##### SECTION Image ##### -->
 124
 125
 126 <!-- ##### STRUCT GtkBindingSet ##### -->
 127 <para>
 128 A binding set maintains a list of activatable key bindings.
 129 A single binding set can match multiple types of widgets.
 130 Similar to styles, widgets can be mapped by widget name paths, widget
 131 class paths or widget class types.  When a binding within a set is
 132 matched upon activation, an action signal is emitted on the target
 133 widget to carry out the actual activation.
 134 </para>
 135
 136 @set_name:              unique binding set name
 137 @priority:              unused
 138 @widget_path_pspecs:    widgets matched by path that this binding set applies to
 139 @widget_class_pspecs:   widgets matched by class path that this binding set applies to
 140 @class_branch_pspecs:   widgets matched by class that this binding set applies to
 141 @entries:               the key binding entries in this binding set
 142 @current:               implementation detail
 143 @parsed:                whether this binding set stems from an RC file and is reset upon theme changes
 144
 145 <!-- ##### STRUCT GtkBindingEntry ##### -->
 146 <para>
 147 Each key binding element of a binding sets binding list is represented by
 148 a #GtkBindingEntry.
 149 </para>
 150
 151 @keyval:        key value to match
 152 @modifiers:     key modifier to match
 153 @binding_set:   binding set this entry belongs to
 154 @destroyed:     implementation detail
 155 @in_emission:   implementation detail
 156 @marks_unbound: implementation detail
 157 @set_next:      linked list of entries maintained by binding set
 158 @hash_next:     implementation detail
 159 @signals:       action signals of this entry
 160
 161 <!-- ##### STRUCT GtkBindingSignal ##### -->
 162 <anchor id="keybinding-signals"/>
 163 <para>
 164 A #GtkBindingSignal stores the necessary information to activate a widget
 165 in response to a key press via a signal emission.
 166 </para>
 167
 168 @next:          implementation detail
 169 @signal_name:   the action signal to be emitted
 170 @n_args:        number of arguments specified for the signal
 171 @args:          the arguments specified for the signal
 172
 173 <!-- ##### STRUCT GtkBindingArg ##### -->
 174 <para>
 175 A #GtkBindingArg holds the data associated with an argument for a
 176 key binding signal emission as stored in #GtkBindingSignal.
 177 </para>
 178
 179 @arg_type: implementation detail
 180
 181 <!-- ##### FUNCTION gtk_binding_entry_add_signall ##### -->
 182 <para>
 183
 184 </para>
 185
 186 @binding_set:
 187 @keyval:
 188 @modifiers:
 189 @signal_name:
 190 @binding_args:
 191
 192
 193 <!-- ##### FUNCTION gtk_binding_set_new ##### -->
 194 <para>
 195
 196 </para>
 197
 198 @set_name:
 199 @Returns:
 200
 201
 202 <!-- ##### FUNCTION gtk_binding_set_by_class ##### -->
 203 <para>
 204
 205 </para>
 206
 207 @object_class:
 208 @Returns:
 209
 210
 211 <!-- ##### FUNCTION gtk_binding_set_find ##### -->
 212 <para>
 213
 214 </para>
 215
 216 @set_name:
 217 @Returns:
 218
 219
 220 <!-- ##### FUNCTION gtk_bindings_activate ##### -->
 221 <para>
 222
 223 </para>
 224
 225 @object:
 226 @keyval:
 227 @modifiers:
 228 @Returns:
 229
 230
 231 <!-- ##### FUNCTION gtk_bindings_activate_event ##### -->
 232 <para>
 233
 234 </para>
 235
 236 @object:
 237 @event:
 238 @Returns:
 239
 240
 241 <!-- ##### FUNCTION gtk_binding_set_activate ##### -->
 242 <para>
 243
 244 </para>
 245
 246 @binding_set:
 247 @keyval:
 248 @modifiers:
 249 @object:
 250 @Returns:
 251
 252
 253 <!-- ##### FUNCTION gtk_binding_entry_add_signal ##### -->
 254 <para>
 255
 256 </para>
 257
 258 @binding_set:
 259 @keyval:
 260 @modifiers:
 261 @signal_name:
 262 @n_args:
 263 @Varargs:
 264
 265
 266 <!-- ##### FUNCTION gtk_binding_entry_skip ##### -->
 267 <para>
 268
 269 </para>
 270
 271 @binding_set:
 272 @keyval:
 273 @modifiers:
 274
 275
 276 <!-- ##### FUNCTION gtk_binding_entry_remove ##### -->
 277 <para>
 278
 279 </para>
 280
 281 @binding_set:
 282 @keyval:
 283 @modifiers:
 284
 285
 286 <!-- ##### FUNCTION gtk_binding_set_add_path ##### -->
 287 <para>
 288
 289 </para>
 290
 291 @binding_set:
 292 @path_type:
 293 @path_pattern:
 294 @priority:
 295
 296