Bindings
<!-- ##### SECTION Short_Description ##### -->
-
+Key bindings for individual widgets
<!-- ##### SECTION Long_Description ##### -->
<para>
+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.
+</para>
+
+<refsect2>
+<anchor id="gtk-bindings-install"/>
+<title>Installing a key binding</title>
+
+<para>
+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
+<link linkend="gtkrc-pathnames-and-patterns">Pathnames and patterns</link>.
+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
+<link linkend="gdk-Keyboard-Handling">key names</link> such as those defined
+in <filename><gdk/gdkkeysyms.h></filename> 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.
+</para>
+<para>
+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:
+
+<informalexample><programlisting>
+binding "MoveCursor3" {
+ bind "<Control>Right" {
+ "move-cursor" (visual-positions, 3, 0)
+ }
+ bind "<Control>Left" {
+ "move-cursor" (visual-positions, -3, 0)
+ }
+}
+class "GtkEntry" binding "MoveCursor3"
+</programlisting></informalexample>
+</para>
+
+<anchor id="gtk-bindings-unbind"/>
+<title>Unbinding existing key bindings</title>
+<para>
+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
+<link linkend="gtk-bindings-install">Installing a key binding</link>
+works as expected. The same mechanism can not be used to "unbind" existing
+bindings, however.
+
+<informalexample><programlisting>
+binding "MoveCursor3" {
+ bind "<Control>Right" { }
+ bind "<Control>Left" { }
+}
+class "GtkEntry" binding "MoveCursor3"
+</programlisting></informalexample>
+
+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:
+
+<informalexample><programlisting>
+binding "MoveCursor3" {
+ unbind "<Control>Right"
+ unbind "<Control>Left"
+}
+class "GtkEntry" binding "MoveCursor3"
+</programlisting></informalexample>
+
+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.
</para>
+<para>
+The "unbind" functionality has been introduced in GTK+ 2.12.
+</para>
+
+</refsect2>
+
<!-- ##### SECTION See_Also ##### -->
<para>
+<variablelist>
+
+<varlistentry>
+<term><link linkend="gtk-keyboard-accelerators">Keyboard Accelerators</link>
+</term>
+<listitem><para>installing and using keyboard short-cuts.</para></listitem>
+</varlistentry>
+<varlistentry>
+<term><link linkend="Resource-Files">Resource Files</link>
+</term>
+<listitem><para>GTK+ Resource Files - behavior and style definitions.</para></listitem>
+</varlistentry>
+
+</variablelist>
</para>
+<!-- ##### SECTION Stability_Level ##### -->
+
+
+<!-- ##### SECTION Image ##### -->
+
+
<!-- ##### STRUCT GtkBindingSet ##### -->
<para>
-
+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.
</para>
-@set_name:
-@priority:
-@widget_path_pspecs:
-@widget_class_pspecs:
-@class_branch_pspecs:
-@entries:
-@current:
+@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
<!-- ##### STRUCT GtkBindingEntry ##### -->
<para>
-
+Each key binding element of a binding sets binding list is represented by
+a #GtkBindingEntry.
</para>
-@keyval:
-@modifiers:
-@binding_set:
-@destroyed:
-@in_emission:
-@set_next:
-@hash_next:
-@signals:
+@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
<!-- ##### STRUCT GtkBindingSignal ##### -->
+<anchor id="keybinding-signals"/>
<para>
-
+A #GtkBindingSignal stores the necessary information to activate a widget
+in response to a key press via a signal emission.
</para>
-@next:
-@signal_name:
-@n_args:
-@args:
+@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
<!-- ##### STRUCT GtkBindingArg ##### -->
<para>
+A #GtkBindingArg holds the data associated with an argument for a
+key binding signal emission as stored in #GtkBindingSignal.
+</para>
+
+@arg_type: implementation detail
+
+<!-- ##### FUNCTION gtk_binding_entry_add_signall ##### -->
+<para>
</para>
-@arg_type:
+@binding_set:
+@keyval:
+@modifiers:
+@signal_name:
+@binding_args:
+
<!-- ##### FUNCTION gtk_binding_set_new ##### -->
<para>
@Returns:
-<!-- ##### FUNCTION gtk_binding_set_activate ##### -->
+<!-- ##### FUNCTION gtk_bindings_activate_event ##### -->
<para>
</para>
-@binding_set:
-@keyval:
-@modifiers:
@object:
+@event:
@Returns:
-<!-- ##### MACRO gtk_binding_entry_add ##### -->
-<para>
-
-</para>
-
-
-
-<!-- ##### FUNCTION gtk_binding_entry_clear ##### -->
+<!-- ##### FUNCTION gtk_binding_set_activate ##### -->
<para>
</para>
@binding_set:
@keyval:
@modifiers:
+@object:
+@Returns:
<!-- ##### FUNCTION gtk_binding_entry_add_signal ##### -->
@Varargs:
-<!-- ##### FUNCTION gtk_binding_set_add_path ##### -->
-<para>
-
-</para>
-
-@binding_set:
-@path_type:
-@path_pattern:
-@priority:
-
-
-<!-- ##### FUNCTION gtk_binding_entry_remove ##### -->
+<!-- ##### FUNCTION gtk_binding_entry_skip ##### -->
<para>
</para>
@modifiers:
-<!-- ##### FUNCTION gtk_binding_entry_add_signall ##### -->
+<!-- ##### FUNCTION gtk_binding_entry_remove ##### -->
<para>
</para>
@binding_set:
@keyval:
@modifiers:
-@signal_name:
-@binding_args:
-<!-- ##### FUNCTION gtk_binding_parse_binding ##### -->
+<!-- ##### FUNCTION gtk_binding_set_add_path ##### -->
<para>
</para>
-@scanner:
-@Returns:
+@binding_set:
+@path_type:
+@path_pattern:
+@priority:
projects / ~andy / gtk / blobdiff