diff --git a/docs/reference/ChangeLog b/docs/reference/ChangeLog index 3af517dddc..9caa396e7f 100644 --- a/docs/reference/ChangeLog +++ b/docs/reference/ChangeLog @@ -1,3 +1,7 @@ +Tue Oct 10 15:29:15 2006 Tim Janik + + * gtk/tmpl/gtkbindings.sgml: documented GtkBinding*, #358329. + 2006-09-22 Matthias Clasen * gtk/tmpl/gtkpagesetup.sgml: Apply a patch diff --git a/docs/reference/gdk/tmpl/pango_interaction.sgml b/docs/reference/gdk/tmpl/pango_interaction.sgml index 11853dd4b6..a736659c88 100644 --- a/docs/reference/gdk/tmpl/pango_interaction.sgml +++ b/docs/reference/gdk/tmpl/pango_interaction.sgml @@ -249,6 +249,15 @@ rendering the text. @attr: the #PangoAttribute. @stipple: the stipple bitmap. + + + + + +@color: +@Returns: + + diff --git a/docs/reference/gdk/tmpl/windows.sgml b/docs/reference/gdk/tmpl/windows.sgml index 05647b6160..3d79c6c5fc 100644 --- a/docs/reference/gdk/tmpl/windows.sgml +++ b/docs/reference/gdk/tmpl/windows.sgml @@ -638,6 +638,14 @@ Registers a window as a potential drop destination. @new_height: + + + + + +@window: + + diff --git a/docs/reference/gtk/tmpl/gtkarrow.sgml b/docs/reference/gtk/tmpl/gtkarrow.sgml index 3e2e2713cd..8e3a146aab 100644 --- a/docs/reference/gtk/tmpl/gtkarrow.sgml +++ b/docs/reference/gtk/tmpl/gtkarrow.sgml @@ -55,6 +55,11 @@ an application.) + + + + + Creates a new arrow widget. diff --git a/docs/reference/gtk/tmpl/gtkbindings.sgml b/docs/reference/gtk/tmpl/gtkbindings.sgml index a96b0b543a..e1f08faa8e 100644 --- a/docs/reference/gtk/tmpl/gtkbindings.sgml +++ b/docs/reference/gtk/tmpl/gtkbindings.sgml @@ -6,12 +6,108 @@ Key bindings for individual widgets +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. + + + + +Installing a key binding + + +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 Pathnames and patterns. +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 key names such as those defined in +<gdk/gdkkeysyms.h> 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: + + +binding "MoveCursor3" { + bind "<Control>Right" { + "move-cursor" (visual-positions, 3, 0) + } + bind "<Control>Left" { + "move-cursor" (visual-positions, -3, 0) + } +} +class "GtkEntry" binding "MoveCursor3" + + + + + +Unbinding existing key bindings + +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 +Installing a key binding +works as expected. The same mechanism can not be used to "unbind" existing bindings, +however. + + +binding "MoveCursor3" { + bind "<Control>Right" { } + bind "<Control>Left" { } +} +class "GtkEntry" binding "MoveCursor3" + + +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 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: + + +binding "MoveCursor3" { + unbind "<Control>Right" + unbind "<Control>Left" +} +class "GtkEntry" binding "MoveCursor3" + + +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 entries parent widget, +is now possible. + + + + +Keyboard Accelerators + +installing and using keyboard short-cuts. + + + +Resource Files + +Gtk+ Resource Files - behavior and style definitions. + + + @@ -19,90 +115,101 @@ Key bindings for individual widgets - +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. -@set_name: -@priority: -@widget_path_pspecs: -@widget_class_pspecs: -@class_branch_pspecs: -@entries: -@current: -@parsed: +@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 - +Each key binding element of a binding sets binding list is represented by a #GtkBindingEntry. -@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 +@set_next: linked list of entries maintained by binding set +@hash_next: implementation detail +@signals: action signals of this entry - +A #GtkBindingSignal stores the necessary information to activate a widget +in response to a key press via a signal emission. -@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 - +A #GtkBindingArg holds the data associated with an argument for a +key binding signal emission as stored in #GtkBindingSignal. -@arg_type: +@arg_type: implementation detail - +Gtk+ maintains a global list of binding sets. Each binding set has a unique name +which needs to be specified upon creation. -@set_name: -@Returns: +@set_name: unique name of this binding set +@Returns: new binding set - +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. -@object_class: -@Returns: +@object_class: a valid #GtkObject class +@Returns: the binding set corresponding to @object_class - +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(). -@set_name: -@Returns: +@set_name: unique binding set name +@Returns: %NULL or the specified binding set - +Find a key binding matching @keyval and @modifiers and activate the binding +on @object. -@object: -@keyval: -@modifiers: -@Returns: +@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 - + @object: @@ -112,26 +219,27 @@ Key bindings for individual widgets - +Find a key binding matching @keyval and @modifiers within @binding_set + and activate the binding on @object. -@binding_set: -@keyval: -@modifiers: -@object: -@Returns: +@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 - +Deprecated. - +Deprecated as public API, used only internally. @binding_set: @@ -141,56 +249,58 @@ Key bindings for individual widgets - +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. -@binding_set: -@keyval: -@modifiers: -@signal_name: -@n_args: -@Varargs: +@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 - +This function is used internally by the GtkRC parsing mechanism to assign match +patterns to #GtkBindingSet structures. -@binding_set: -@path_type: -@path_pattern: -@priority: +@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 - +Remove a binding previously installed via gtk_binding_entry_add_signal() on +@binding_set. -@binding_set: -@keyval: -@modifiers: +@binding_set: @binding_set to remove an entry of +@keyval: key value of binding to remove +@modifiers: key modifier of binding to remove - +Deprecated. -@binding_set: -@keyval: -@modifiers: -@signal_name: -@binding_args: +@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 - +Deprecated as public API, used only internally. -@scanner: -@Returns: - - +@scanner: GtkRC scanner +@Returns: expected token upon errors diff --git a/docs/reference/gtk/tmpl/gtkcellrenderertext.sgml b/docs/reference/gtk/tmpl/gtkcellrenderertext.sgml index 026d9db5cc..42125e4e25 100644 --- a/docs/reference/gtk/tmpl/gtkcellrenderertext.sgml +++ b/docs/reference/gtk/tmpl/gtkcellrenderertext.sgml @@ -40,6 +40,11 @@ the #GtkCellRendererText allows to edit its text using an entry. @arg1: @arg2: + + + + + diff --git a/docs/reference/gtk/tmpl/gtkprogressbar.sgml b/docs/reference/gtk/tmpl/gtkprogressbar.sgml index df16163c4d..5040afa4f2 100644 --- a/docs/reference/gtk/tmpl/gtkprogressbar.sgml +++ b/docs/reference/gtk/tmpl/gtkprogressbar.sgml @@ -116,6 +116,16 @@ and should be accessed using the functions below. + + + + + + + + + + Creates a new #GtkProgressBar. diff --git a/docs/reference/gtk/tmpl/gtkrc.sgml b/docs/reference/gtk/tmpl/gtkrc.sgml index 2de798ecc3..24009cd509 100644 --- a/docs/reference/gtk/tmpl/gtkrc.sgml +++ b/docs/reference/gtk/tmpl/gtkrc.sgml @@ -45,6 +45,7 @@ and parses the first of those that exists. Pathnames and patterns + A resource file defines a number of styles and key bindings and attaches them to particular widgets. The attachment is done diff --git a/docs/reference/gtk/tmpl/gtksettings.sgml b/docs/reference/gtk/tmpl/gtksettings.sgml index a929e36ce6..37726044ae 100644 --- a/docs/reference/gtk/tmpl/gtksettings.sgml +++ b/docs/reference/gtk/tmpl/gtksettings.sgml @@ -63,6 +63,11 @@ Sharing settings between applications + + + + +