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_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_action ()

void
gtk_binding_entry_add_action (GtkBindingSet *binding_set,
                              guint keyval,
                              GdkModifierType modifiers,
                              const char *action_name,
                              const char *format_string,
                              ...);

Override or install a new key binding for keyval with modifiers on binding_set . When the binding is activated, action_name will be activated on the target widget, with arguments read according to format_string .

Parameters

binding_set

a GtkBindingSet to install an entry for

 

keyval

key value of binding to install

 

modifiers

key modifier of binding to install

 

action_name

signal to execute upon activation

 

format_string

GVariant format string for arguments or NULL for no arguments

 

...

arguments, as given by format string

 

gtk_binding_entry_add_action_variant ()

void
gtk_binding_entry_add_action_variant (GtkBindingSet *binding_set,
                                      guint keyval,
                                      GdkModifierType modifiers,
                                      const char *action_name,
                                      GVariant *args);

Override or install a new key binding for keyval with modifiers on binding_set . When the binding is activated, action_name will be activated on the target widget, with args used as arguments.

Parameters

binding_set

a GtkBindingSet to install an entry for

 

keyval

key value of binding to install

 

modifiers

key modifier of binding to install

 

action_name

signal to execute upon activation

 

args

GVariant of the arguments or NULL if none

 

GtkBindingCallback ()

void
(*GtkBindingCallback) (GtkWidget *widget,
                       GVariant *args,
                       gpointer user_data);

Prototype of the callback function registered with gtk_binding_entry_add_callback.

Parameters

widget

The object to invoke the callback on

 

args

The arguments or NULL if none.

[allow-none]

user_data

The user data passed when registering the callback

 

gtk_binding_entry_add_callback ()

void
gtk_binding_entry_add_callback (GtkBindingSet *binding_set,
                                guint keyval,
                                GdkModifierType modifiers,
                                GtkBindingCallback callback,
                                GVariant *args,
                                gpointer user_data,
                                GDestroyNotify user_destroy);

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

 

See Also

Keyboard Accelerators, Mnemonics, GtkCssProvider