callisto-debian/gtk3
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Move GtkBindings docs inline

Browse Source
This commit is contained in:
Matthias Clasen
2011-01-30 22:37:30 -05:00
parent dcf3430e17
commit b448bb81ce
4 changed files with 225 additions and 369 deletions
Download Patch File Download Diff File Expand all files Collapse all files

1
docs/reference/gtk/tmpl/.gitignore vendored
View File

@ -3,6 +3,7 @@ gtkactiongroup.sgml
gtkaboutdialog.sgml gtkaboutdialog.sgml
gtkadjustment.sgml gtkadjustment.sgml
gtkbbox.sgml gtkbbox.sgml
gtkbindings.sgml
gtkbox.sgml gtkbox.sgml
gtkbuilder.sgml gtkbuilder.sgml
gtkbutton.sgml gtkbutton.sgml

296
docs/reference/gtk/tmpl/gtkbindings.sgml
View File

@ -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>&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.
</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 "&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 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 "&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 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:

126
gtk/gtkbindings.c
View File

@ -37,6 +37,103 @@
#include "gtkrc.h" #include "gtkrc.h"
#include "gtkintl.h" #include "gtkintl.h"
/**
* SECTION:gtkbindings
* @Title: GtkBindings
* @Short_description: Key bindings for individual widgets
* @See_also: <link linkend="gtk-keyboard-accelerators">Keyboard Accelerators</link>, #GtkCssProvider
*
* GtkBinding provides a mechanism for configuring GTK+ key bindings
* through CSS 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.
*
* <refsect2 id="gtk-bindings-install">
* <title>Installing a key binding</title>
* <para>
* A CSS file binding consists of a 'binding-set' definition and a match
* statement to apply the binding set to specific widget types. Details
* on the matching mechanism are described under
* <link linkend="gtkcssprovider-selectors">Selectors</link>
* in the #GtkCssProvider documentation. Inside the binding-set definition,
* key combinations are bound to one or more 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.
* </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-character steps), the following binding can be used:
* <informalexample><programlisting>
* @binding-set "MoveCursor3"
* {
* bind "&lt;Control&gt;Right" { "move-cursor" (visual-positions, 3, 0) };
* bind "&lt;Control&gt;Left" { "move-cursor" (visual-positions, -3, 0) };
* };
* GtkEntry
* {
* gtk-key-bindings: MoveCursor3
* }
* </programlisting></informalexample>
* </para>
* </refsect2>
* <refsect2 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 CSS 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-set "MoveCursor3"
* {
* bind "&lt;Control&gt;Right" { };
* bind "&lt;Control&gt;Left" { };
* };
* GtkEntry
* {
* gtk-key-bindings: 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 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-set "MoveCursor3"
* {
* unbind "&lt;Control&gt;Right";
* unbind "&lt;Control&gt;Left";
* };
* GtkEntry
* {
* gtk-key-bindings: 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 entry's parent widget, is
* now possible.
* </para>
* </refsect2>
*/
/* --- defines --- */ /* --- defines --- */
#define BINDING_MOD_MASK() (gtk_accelerator_get_default_mod_mask () | GDK_RELEASE_MASK) #define BINDING_MOD_MASK() (gtk_accelerator_get_default_mod_mask () | GDK_RELEASE_MASK)
@ -651,9 +748,10 @@ gtk_binding_set_by_class (gpointer object_class)
* gtk_binding_set_find: * gtk_binding_set_find:
* @set_name: unique binding set name * @set_name: unique binding set name
* *
* Find a binding set by its globally unique name. The @set_name can * Find a binding set by its globally unique name.
* either be a name used for gtk_binding_set_new() or the type name of *
* a class used in gtk_binding_set_by_class(). * 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().
* *
* Return value: (transfer none): %NULL or the specified binding set * Return value: (transfer none): %NULL or the specified binding set
*/ */
@ -1255,7 +1353,7 @@ create_signal_scanner (void)
* it into @binding_set. * it into @binding_set.
* *
* signal descriptions may either bind a key combination to * signal descriptions may either bind a key combination to
* a signal: * one or more signals:
* <informalexample><programlisting> * <informalexample><programlisting>
* bind <replaceable>key</replaceable> { * bind <replaceable>key</replaceable> {
* <replaceable>signalname</replaceable> (<replaceable>param</replaceable>, ...) * <replaceable>signalname</replaceable> (<replaceable>param</replaceable>, ...)
@ -1302,10 +1400,10 @@ gtk_binding_entry_add_signal_from_string (GtkBindingSet *binding_set,
/** /**
* gtk_binding_set_add_path: * gtk_binding_set_add_path:
* @binding_set: a #GtkBindingSet to add a path to * @binding_set: a #GtkBindingSet to add a path to
* @path_type: path type the pattern applies to * @path_type: path type the pattern applies to
* @path_pattern: the actual match pattern * @path_pattern: the actual match pattern
* @priority: binding priority * @priority: binding priority
* *
* This function is used internally by the GtkRC parsing mechanism to * This function is used internally by the GtkRC parsing mechanism to
* assign match patterns to #GtkBindingSet structures. * assign match patterns to #GtkBindingSet structures.
@ -1313,10 +1411,10 @@ gtk_binding_entry_add_signal_from_string (GtkBindingSet *binding_set,
* Deprecated: 3.0 * Deprecated: 3.0
*/ */
void void
gtk_binding_set_add_path (GtkBindingSet *binding_set, gtk_binding_set_add_path (GtkBindingSet *binding_set,
GtkPathType path_type, GtkPathType path_type,
const gchar *path_pattern, const gchar *path_pattern,
GtkPathPriorityType priority) GtkPathPriorityType priority)
{ {
PatternSpec *pspec; PatternSpec *pspec;
GSList **slist_p, *slist; GSList **slist_p, *slist;
@ -1425,9 +1523,9 @@ binding_activate (GtkBindingSet *binding_set,
} }
static gboolean static gboolean
gtk_bindings_activate_list (GObject *object, gtk_bindings_activate_list (GObject *object,
GSList *entries, GSList *entries,
gboolean is_release) gboolean is_release)
{ {
GtkStyleContext *context; GtkStyleContext *context;
GtkBindingSet *binding_set; GtkBindingSet *binding_set;

53
gtk/gtkbindings.h
View File

@ -45,6 +45,24 @@ typedef struct _GtkBindingEntry GtkBindingEntry;
typedef struct _GtkBindingSignal GtkBindingSignal; typedef struct _GtkBindingSignal GtkBindingSignal;
typedef struct _GtkBindingArg GtkBindingArg; typedef struct _GtkBindingArg GtkBindingArg;
/**
* GtkBindingSet:
* @set_name: unique name of this binding set
* @priority: unused
* @widget_path_pspecs: unused
* @widget_class_pspecs: unused
* @class_branch_pspecs: unused
* @entries: the key binding entries in this binding set
* @current: implementation detail
* @parsed: whether this binding set stems from a CSS file and is reset upon theme changes
*
* A binding set maintains a list of activatable key bindings.
* A single binding set can match multiple types of widgets.
* Similar to style contexts, can be matched by any information contained
* in a widgets #GtkWidgetPath. 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.
*/
struct _GtkBindingSet struct _GtkBindingSet
{ {
gchar *set_name; gchar *set_name;
@ -57,6 +75,21 @@ struct _GtkBindingSet
guint parsed : 1; guint parsed : 1;
}; };
/**
* GtkBindingEntry:
* @keyval: key value to match
* @modifiers: key modifiers 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
*
* Each key binding element of a binding sets binding list is
* represented by a GtkBindingEntry.
*/
struct _GtkBindingEntry struct _GtkBindingEntry
{ {
/* key portion */ /* key portion */
@ -72,6 +105,14 @@ struct _GtkBindingEntry
GtkBindingSignal *signals; GtkBindingSignal *signals;
}; };
/**
* GtkBindingArg:
* @arg_type: implementation detail
*
* A #GtkBindingArg holds the data associated with
* an argument for a key binding signal emission as
* stored in #GtkBindingSignal.
*/
struct _GtkBindingArg struct _GtkBindingArg
{ {
GType arg_type; GType arg_type;
@ -82,6 +123,18 @@ struct _GtkBindingArg
} d; } d;
}; };
/**
* GtkBindingSignal:
* @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
*
* <anchor id="keybinding-signals"/>
* A GtkBindingSignal stores the necessary information to
* activate a widget in response to a key press via a signal
* emission.
*/
struct _GtkBindingSignal struct _GtkBindingSignal
{ {
GtkBindingSignal *next; GtkBindingSignal *next;