BindingSet

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.

Installing a key binding

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 Selectors 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 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 "move-cursor" signal (so movement occurs in 3-character steps), the following binding can be used:

<hr>

Unbinding existing key bindings

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 Installing a key binding works as expected. The same mechanism can not be used to "unbind" existing bindings, however.

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:

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.

class BindingSet {

protected

GtkBindingSet* gtkBindingSet;

GtkBindingSet* getBindingSetStruct();

void* getStruct();

this(GtkBindingSet* gtkBindingSet);

void entryAddSignall(uint keyval, GdkModifierType modifiers, string signalName, ListSG bindingArgs);

this(string setName);

static BindingSet byClass(void* objectClass);

static BindingSet find(string setName);

static int activate(ObjectG object, uint keyval, GdkModifierType modifiers);

static int activateEvent(ObjectG object, GdkEventKey* event);

int activate(uint keyval, GdkModifierType modifiers, ObjectG object);

GTokenType entryAddSignalFromString(string signalDesc);

void entrySkip(uint keyval, GdkModifierType modifiers);

void entryRemove(uint keyval, GdkModifierType modifiers);

void addPath(GtkPathType pathType, string pathPattern, GtkPathPriorityType priority);

}

Constructors

this this(GtkBindingSet* gtkBindingSet): Sets our main struct and passes it to the parent class
this this(string setName): GTK+ maintains a global list of binding sets. Each binding set has a unique name which needs to be specified upon creation.

Members

Functions

activate int activate(uint keyval, GdkModifierType modifiers, ObjectG object): Find a key binding matching keyval and modifiers within binding_set and activate the binding on object.
addPath void addPath(GtkPathType pathType, string pathPattern, GtkPathPriorityType priority): Warning gtk_binding_set_add_path is deprecated and should not be used in newly-written code. 3.0 This function was used internally by the GtkRC parsing mechanism to assign match patterns to GtkBindingSet structures. In GTK+ 3, these match patterns are unused.
entryAddSignalFromString GTokenType entryAddSignalFromString(string signalDesc): Parses a signal description from signal_desc and incorporates it into binding_set. Signal descriptions may either bind a key combination to
entryAddSignall void entryAddSignall(uint keyval, GdkModifierType modifiers, string signalName, ListSG bindingArgs): Override or install a new key binding for keyval with modifiers on binding_set.
entryRemove void entryRemove(uint keyval, GdkModifierType modifiers): Remove a binding previously installed via gtk_binding_entry_add_signal() on binding_set.
entrySkip void entrySkip(uint 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. Since 2.12
getBindingSetStruct GtkBindingSet* getBindingSetStruct(): Undocumented in source. Be warned that the author may not have intended to support it.
getStruct void* getStruct(): the main Gtk struct as a void*

Static functions

activate int activate(ObjectG object, uint keyval, GdkModifierType modifiers): Find a key binding matching keyval and modifiers and activate the binding on object.
activateEvent int activateEvent(ObjectG object, GdkEventKey* event): Looks up key bindings for object to find one matching event, and if one was found, activate it. Since 2.4
byClass BindingSet byClass(void* objectClass): 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.
find BindingSet find(string setName): 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().

Variables

gtkBindingSet GtkBindingSet* gtkBindingSet;: the main Gtk struct