Bindings

Bindings — Key bindings for individual widgets

Functions

Types and Values

Includes

#include <gtk/gtk.h>

Description

GtkBindingSet 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.

In order for bindings to work in a custom widget implementation, the widget’s “can-focus” and “has-focus” properties must both be true. For example, by calling gtk_widget_set_can_focus() in the widget’s initialisation function; and by calling gtk_widget_grab_focus() when the widget is clicked.

Functions

gtk_binding_entry_add_signall ()

void
gtk_binding_entry_add_signall (GtkBindingSet *binding_set,
                               guint keyval,
                               GdkModifierType modifiers,
                               const gchar *signal_name,
                               GSList *binding_args);

Override or install a new key binding for keyval with modifiers on binding_set .

Parameters

binding_set

a GtkBindingSet 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.

[transfer none][element-type GtkBindingArg]

gtk_binding_set_new ()

GtkBindingSet *
gtk_binding_set_new (const gchar *set_name);

GTK+ maintains a global list of binding sets. Each binding set has a unique name which needs to be specified upon creation.

[skip]

Parameters

set_name

unique name of this binding set

 

Returns

new binding set.

[transfer none]

gtk_binding_set_by_class ()

GtkBindingSet *
gtk_binding_set_by_class (gpointer object_class);

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.

[skip]

Parameters

object_class

a valid GObject class

 

Returns

the binding set corresponding to object_class .

[transfer none]

gtk_binding_set_find ()

GtkBindingSet *
gtk_binding_set_find (const gchar *set_name);

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().

Parameters

set_name

unique binding set name

 

Returns

NULL or the specified binding set.

[nullable][transfer none]

gtk_bindings_activate ()

gboolean
gtk_bindings_activate (GObject *object,
                       guint keyval,
                       GdkModifierType modifiers);

Find a key binding matching keyval and modifiers and activate the binding on object .

Parameters

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

gtk_bindings_activate_event ()

gboolean
gtk_bindings_activate_event (GObject *object,
                             GdkEventKey *event);

Looks up key bindings for object to find one matching event , and if one was found, activate it.

Parameters

object

a GObject (generally must be a widget)

 

event

a GdkEventKey

 

Returns

TRUE if a matching key binding was found

gtk_binding_set_activate ()

gboolean
gtk_binding_set_activate (GtkBindingSet *binding_set,
                          guint keyval,
                          GdkModifierType modifiers,
                          GObject *object);

Find a key binding matching keyval and modifiers within binding_set and activate the binding on object .

Parameters

binding_set

a GtkBindingSet set to activate

 

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

gtk_binding_entry_add_signal ()

void
gtk_binding_entry_add_signal (GtkBindingSet *binding_set,
                              guint keyval,
                              GdkModifierType modifiers,
                              const gchar *signal_name,
                              guint n_args,
                              ...);

Override or install a 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.

Each argument to the signal must be passed as a pair of varargs: the GType of the argument, followed by the argument value (which must be of the given type). There must be n_args pairs in total.

Adding a Key Binding

1
2
3
4
5
6
7
8
9
10
GtkBindingSet *binding_set;
GdkModifierType modmask = GDK_CONTROL_MASK;
int count = 1;
gtk_binding_entry_add_signal (binding_set,
                              GDK_KEY_space,
                              modmask,
                              "move-cursor", 2,
                              GTK_TYPE_MOVEMENT_STEP, GTK_MOVEMENT_PAGES,
                              G_TYPE_INT, count,
                              G_TYPE_BOOLEAN, FALSE);

Parameters

binding_set

a GtkBindingSet 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

 

...

arguments to signal_name

 

gtk_binding_entry_add_signal_from_string ()

GTokenType
gtk_binding_entry_add_signal_from_string
                               (GtkBindingSet *binding_set,
                                const gchar *signal_desc);

Parses a signal description from signal_desc and incorporates it into binding_set .

Signal descriptions may either bind a key combination to one or more signals:

1
2
3
4
bind "key" {
  "signalname" (param, ...)
  ...
}

Or they may also unbind a key combination:

1
unbind "key"

Key combinations must be in a format that can be parsed by gtk_accelerator_parse().

Parameters

binding_set

a GtkBindingSet

 

signal_desc

a signal description

 

Returns

G_TOKEN_NONE if the signal was successfully parsed and added, the expected token otherwise

gtk_binding_entry_skip ()

void
gtk_binding_entry_skip (GtkBindingSet *binding_set,
                        guint keyval,
                        GdkModifierType modifiers);

Install a binding on binding_set which causes key lookups to be aborted, to prevent bindings from lower priority sets to be activated.

Parameters

binding_set

a GtkBindingSet to skip an entry of

 

keyval

key value of binding to skip

 

modifiers

key modifier of binding to skip

 

gtk_binding_entry_remove ()

void
gtk_binding_entry_remove (GtkBindingSet *binding_set,
                          guint keyval,
                          GdkModifierType modifiers);

Remove a binding previously installed via gtk_binding_entry_add_signal() on binding_set .

Parameters

binding_set

a GtkBindingSet to remove an entry of

 

keyval

key value of binding to remove

 

modifiers

key modifier of binding to remove

 

Types and Values

struct GtkBindingSet

struct GtkBindingSet {
  gchar           *set_name;
  gint             priority;
  GSList          *widget_path_pspecs;
  GSList          *widget_class_pspecs;
  GSList          *class_branch_pspecs;
  GtkBindingEntry *entries;
  GtkBindingEntry *current;
  guint            parsed : 1;
};

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.

Members

gchar *set_name;

unique name of this binding set

 

gint priority;

unused

 

GSList *widget_path_pspecs;

unused

 

GSList *widget_class_pspecs;

unused

 

GSList *class_branch_pspecs;

unused

 

GtkBindingEntry *entries;

the key binding entries in this binding set

 

GtkBindingEntry *current;

implementation detail

 

guint parsed : 1;

whether this binding set stems from a CSS file and is reset upon theme changes

 

struct GtkBindingEntry

struct GtkBindingEntry {
  /* key portion */
  guint             keyval;
  GdkModifierType   modifiers;

  GtkBindingSet    *binding_set;
  guint             destroyed     : 1;
  guint             in_emission   : 1;
  guint             marks_unbound : 1;
  GtkBindingEntry  *set_next;
  GtkBindingEntry  *hash_next;
  GtkBindingSignal *signals;
};

Each key binding element of a binding sets binding list is represented by a GtkBindingEntry.

Members

guint keyval;

key value to match

 

GdkModifierType modifiers;

key modifiers to match

 

GtkBindingSet *binding_set;

binding set this entry belongs to

 

guint destroyed : 1;

implementation detail

 

guint in_emission : 1;

implementation detail

 

guint marks_unbound : 1;

implementation detail

 

GtkBindingEntry *set_next;

linked list of entries maintained by binding set

 

GtkBindingEntry *hash_next;

implementation detail

 

GtkBindingSignal *signals;

action signals of this entry

 

struct GtkBindingSignal

struct GtkBindingSignal {
  GtkBindingSignal *next;
  gchar            *signal_name;
  guint             n_args;
  GtkBindingArg    *args;
};

A GtkBindingSignal stores the necessary information to activate a widget in response to a key press via a signal emission.

Members

GtkBindingSignal *next;

implementation detail

 

gchar *signal_name;

the action signal to be emitted

 

guint n_args;

number of arguments specified for the signal

 

GtkBindingArg *args;

the arguments specified for the signal.

[array length=n_args]

struct GtkBindingArg

struct GtkBindingArg {
  GType      arg_type;
  union {
    glong    long_data;
    gdouble  double_data;
    gchar   *string_data;
  } d;
};

A GtkBindingArg holds the data associated with an argument for a key binding signal emission as stored in GtkBindingSignal.

Members

GType arg_type;

implementation detail

 

See Also

Keyboard Accelerators, Mnemonics, GtkCssProvider