gtk2/docs/reference/gtk/tmpl/gtkbindings.sgml

<!-- ##### SECTION Title ##### -->
Bindings

<!-- ##### SECTION Short_Description ##### -->
Key bindings for individual widgets

<!-- ##### SECTION Long_Description ##### -->
<para>
GtkBinding provide 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
require 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>&lt;gdk/gdkkeysyms.h&gt;</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.

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 "&lt;Control&gt;Right" {
    "move-cursor" (visual-positions, 3, 0)
  }
  bind "&lt;Control&gt;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 "&lt;Control&gt;Right" { }
  bind "&lt;Control&gt;Left" { }
}
class "GtkEntry" binding "MoveCursor3"
</programlisting></informalexample>

The above example will not have the desired effect of causing "&lt;Control&gt;Right"
and "&lt;Control&gt;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
"&lt;Control&gt;Right" or "&lt;Control&gt;Left" are pressed, no binding for these keys
is found in binding set "MoveCursor3". Gtk+ will thusly 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 "&lt;Control&gt;Right"
  unbind "&lt;Control&gt;Left"
}
class "GtkEntry" binding "MoveCursor3"
</programlisting></informalexample>

Now, Gtk+ will find a match when looking up "&lt;Control&gt;Right" and "&lt;Control&gt;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 entries parent widget,
is now possible.

</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 ##### -->


<!-- ##### 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: 		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: 	key value to match
@modifiers: 	key modifier to match
@binding_set: 	binding set this entry belongs to
@destroyed:  	implementation detail
@in_emission: 	implementation detail
@set_next: 	linked list of entries maintained by binding set
@hash_next:	implementation detail
@signals: 	action signals of this entry

<!-- ##### STRUCT GtkBindingSignal ##### -->
<para>
A #GtkBindingSignal stores the necessary information to activate a widget
in response to a key press via a signal emission.
</para>

@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_set_new ##### -->
<para>
Gtk+ maintains a global list of binding sets. Each binding set has a unique name
which needs to be specified upon creation.
</para>

@set_name: unique name of this binding set
@Returns:  new binding set


<!-- ##### FUNCTION gtk_binding_set_by_class ##### -->
<para>
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.
</para>

@object_class: a valid #GtkObject class
@Returns:      the binding set corresponding to @object_class


<!-- ##### FUNCTION gtk_binding_set_find ##### -->
<para>
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().
</para>

@set_name: unique binding set name
@Returns:  %NULL or the specified binding set


<!-- ##### FUNCTION gtk_bindings_activate ##### -->
<para>
Find a key binding matching @keyval and @modifiers and activate the binding
on @object.
</para>

@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


<!-- ##### FUNCTION gtk_bindings_activate_event ##### -->
<para>
<!-- documented inline -->
</para>

@object: 
@event: 
@Returns: 


<!-- ##### FUNCTION gtk_binding_set_activate ##### -->
<para>
Find a key binding matching @keyval and @modifiers within @binding_set
 and activate the binding on @object.
</para>

@binding_set: the binding set to constrain the search to
@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


<!-- ##### MACRO gtk_binding_entry_add ##### -->
<para>
Deprecated.
</para>



<!-- ##### FUNCTION gtk_binding_entry_clear ##### -->
<para>
Deprecated as public API, used only internally.
</para>

@binding_set: 
@keyval: 
@modifiers: 


<!-- ##### FUNCTION gtk_binding_entry_add_signal ##### -->
<para>
Override or install 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.
</para>

@binding_set: 	@binding_set 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
@Varargs: 	arguments to @signal_name


<!-- ##### FUNCTION gtk_binding_set_add_path ##### -->
<para>
This function is used internally by the GtkRC parsing mechanism to assign match
patterns to #GtkBindingSet structures.
</para>

@binding_set:  binding set to add a path to
@path_type:    path type the pattern applies to
@path_pattern: the actual match pattern
@priority:     binding priority


<!-- ##### FUNCTION gtk_binding_entry_remove ##### -->
<para>
Remove a binding previously installed via gtk_binding_entry_add_signal() on
@binding_set.
</para>

@binding_set: 	@binding_set to remove an entry of
@keyval: 	key value of binding to remove
@modifiers: 	key modifier of binding to remove


<!-- ##### FUNCTION gtk_binding_entry_add_signall ##### -->
<para>
Deprecated.
</para>

@binding_set:  binding set 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


<!-- ##### FUNCTION gtk_binding_parse_binding ##### -->
<para>
Deprecated as public API, used only internally.
</para>

@scanner: GtkRC scanner
@Returns: expected token upon errors