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 CtkCssProvider 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 CdkModifierType name and key names such as those defined in cdk/cdkkeysyms.h or returned from cdk_keyval_name(), they have to be parsable by ctk_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 CtkEntry widget to the “move-cursor” signal (so movement occurs in 3-character steps), the following binding can be used:

1
2
3
4
5
6
7
8
9
10

@binding-set MoveCursor3
{
  bind "<Control>Right" { "move-cursor" (visual-positions, 3, 0) };
  bind "<Control>Left" { "move-cursor" (visual-positions, -3, 0) };
}

entry
{
  -ctk-key-bindings: MoveCursor3;
}

Unbinding existing key bindings

CTK+ 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 CTK+, 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.

1
2
3
4
5
6
7
8
9
10

@binding-set MoveCursor3
{
  bind "<Control>Right" {  };
  bind "<Control>Left" {  };
}

entry
{
  -ctk-key-bindings: MoveCursor3;
}

The above example will not have the desired effect of causing “<Control>Right” and “<Control>Left” key presses to be ignored by CTK+. 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”. CTK+ will thus continue to search for matching key bindings, and will eventually lookup and find the default CTK+ bindings for entries which implement word movement. To keep CTK+ from activating its default bindings, the “unbind” keyword can be used like this:

1
2
3
4
5
6
7
8
9
10

@binding-set MoveCursor3
{
  unbind "<Control>Right";
  unbind "<Control>Left";
}

entry
{
  -ctk-key-bindings: MoveCursor3;
}

Now, CTK+ 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.

ctk_binding_entry_add_signall ()

void
ctk_binding_entry_add_signall (CtkBindingSet *binding_set,
                               guint keyval,
                               CdkModifierType modifiers,
                               const gchar *signal_name,
                               GSList *binding_args);

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

ctk_binding_set_new ()

CtkBindingSet *
ctk_binding_set_new (const gchar *set_name);

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

[skip]

ctk_binding_set_by_class ()

CtkBindingSet *
ctk_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]

ctk_binding_set_find ()

CtkBindingSet *
ctk_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 ctk_binding_set_new() or the type name of a class used in ctk_binding_set_by_class().

ctk_bindings_activate ()

gboolean
ctk_bindings_activate (GObject *object,
                       guint keyval,
                       CdkModifierType modifiers);

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

ctk_bindings_activate_event ()

gboolean
ctk_bindings_activate_event (GObject *object,
                             CdkEventKey *event);

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

Since: 2.4

ctk_binding_set_activate ()

gboolean
ctk_binding_set_activate (CtkBindingSet *binding_set,
                          guint keyval,
                          CdkModifierType modifiers,
                          GObject *object);

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

ctk_binding_entry_add_signal ()

void
ctk_binding_entry_add_signal (CtkBindingSet *binding_set,
                              guint keyval,
                              CdkModifierType 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.

1
2
3
4
5
6
7
8
9
10

CtkBindingSet *binding_set;
CdkModifierType modmask = CDK_CONTROL_MASK;
int count = 1;
ctk_binding_entry_add_signal (binding_set,
                              CDK_KEY_space,
                              modmask,
                              "move-cursor", 2,
                              CTK_TYPE_MOVEMENT_STEP, CTK_MOVEMENT_PAGES,
                              G_TYPE_INT, count,
                              G_TYPE_BOOLEAN, FALSE);

ctk_binding_entry_add_signal_from_string ()

GTokenType
ctk_binding_entry_add_signal_from_string
                               (CtkBindingSet *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 ctk_accelerator_parse().

Since: 3.0

ctk_binding_entry_skip ()

void
ctk_binding_entry_skip (CtkBindingSet *binding_set,
                        guint keyval,
                        CdkModifierType 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

ctk_binding_entry_remove ()

void
ctk_binding_entry_remove (CtkBindingSet *binding_set,
                          guint keyval,
                          CdkModifierType modifiers);

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

ctk_binding_set_add_path ()

void
ctk_binding_set_add_path (CtkBindingSet *binding_set,
                          CtkPathType path_type,
                          const gchar *path_pattern,
                          CtkPathPriorityType priority);

This function was used internally by the CtkRC parsing mechanism to assign match patterns to CtkBindingSet structures.

In CTK+ 3, these match patterns are unused.

struct CtkBindingSet

struct CtkBindingSet {
  gchar           *set_name;
  gint             priority;
  GSList          *widget_path_pspecs;
  GSList          *widget_class_pspecs;
  GSList          *class_branch_pspecs;
  CtkBindingEntry *entries;
  CtkBindingEntry *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 CtkWidgetPath. 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 CtkBindingEntry

struct CtkBindingEntry {
  /* key portion */
  guint             keyval;
  CdkModifierType   modifiers;

  CtkBindingSet    *binding_set;
  guint             destroyed     : 1;
  guint             in_emission   : 1;
  guint             marks_unbound : 1;
  CtkBindingEntry  *set_next;
  CtkBindingEntry  *hash_next;
  CtkBindingSignal *signals;
};

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

struct CtkBindingSignal

struct CtkBindingSignal {
  CtkBindingSignal *next;
  gchar            *signal_name;
  guint             n_args;
  CtkBindingArg    *args;
};

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

struct CtkBindingArg

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

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