Move GtkBindings docs inline
This commit is contained in:
Matthias Clasen
1
docs/reference/gtk/tmpl/.gitignore
vendored
1
docs/reference/gtk/tmpl/.gitignore
vendored
@ -3,6 +3,7 @@ gtkactiongroup.sgml
|
||||
gtkaboutdialog.sgml
|
||||
gtkadjustment.sgml
|
||||
gtkbbox.sgml
|
||||
gtkbindings.sgml
|
||||
gtkbox.sgml
|
||||
gtkbuilder.sgml
|
||||
gtkbutton.sgml
|
||||
|
||||
@ -1,296 +0,0 @@
|
||||
<!-- ##### SECTION Title ##### -->
|
||||
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: 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
|
||||
@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: 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>
|
||||
|
||||
@binding_set:
|
||||
@keyval:
|
||||
@modifiers:
|
||||
@signal_name:
|
||||
@binding_args:
|
||||
|
||||
|
||||
<!-- ##### FUNCTION gtk_binding_set_new ##### -->
|
||||
<para>
|
||||
|
||||
</para>
|
||||
|
||||
@set_name:
|
||||
@Returns:
|
||||
|
||||
|
||||
<!-- ##### FUNCTION gtk_binding_set_by_class ##### -->
|
||||
<para>
|
||||
|
||||
</para>
|
||||
|
||||
@object_class:
|
||||
@Returns:
|
||||
|
||||
|
||||
<!-- ##### FUNCTION gtk_binding_set_find ##### -->
|
||||
<para>
|
||||
|
||||
</para>
|
||||
|
||||
@set_name:
|
||||
@Returns:
|
||||
|
||||
|
||||
<!-- ##### FUNCTION gtk_bindings_activate ##### -->
|
||||
<para>
|
||||
|
||||
</para>
|
||||
|
||||
@object:
|
||||
@keyval:
|
||||
@modifiers:
|
||||
@Returns:
|
||||
|
||||
|
||||
<!-- ##### FUNCTION gtk_bindings_activate_event ##### -->
|
||||
<para>
|
||||
|
||||
</para>
|
||||
|
||||
@object:
|
||||
@event:
|
||||
@Returns:
|
||||
|
||||
|
||||
<!-- ##### FUNCTION gtk_binding_set_activate ##### -->
|
||||
<para>
|
||||
|
||||
</para>
|
||||
|
||||
@binding_set:
|
||||
@keyval:
|
||||
@modifiers:
|
||||
@object:
|
||||
@Returns:
|
||||
|
||||
|
||||
<!-- ##### FUNCTION gtk_binding_entry_add_signal ##### -->
|
||||
<para>
|
||||
|
||||
</para>
|
||||
|
||||
@binding_set:
|
||||
@keyval:
|
||||
@modifiers:
|
||||
@signal_name:
|
||||
@n_args:
|
||||
@Varargs:
|
||||
|
||||
|
||||
<!-- ##### FUNCTION gtk_binding_entry_skip ##### -->
|
||||
<para>
|
||||
|
||||
</para>
|
||||
|
||||
@binding_set:
|
||||
@keyval:
|
||||
@modifiers:
|
||||
|
||||
|
||||
<!-- ##### FUNCTION gtk_binding_entry_remove ##### -->
|
||||
<para>
|
||||
|
||||
</para>
|
||||
|
||||
@binding_set:
|
||||
@keyval:
|
||||
@modifiers:
|
||||
|
||||
|
||||
<!-- ##### FUNCTION gtk_binding_set_add_path ##### -->
|
||||
<para>
|
||||
|
||||
</para>
|
||||
|
||||
@binding_set:
|
||||
@path_type:
|
||||
@path_pattern:
|
||||
@priority:
|
||||
|
||||
|
||||
Reference in New Issue
Block a user