Clutter::BindingPool(3) Pool for key bindings


Clutter::BindingPool is a data structure holding a set of key bindings.

Each key binding associates a key symbol (eventually with modifiers) to an action. A callback function is associated to each action.

For a given key symbol and modifier mask combination there can be only one action; for each action there can be only one callback. There can be multiple actions with the same name, and the same callback can be used to handle multiple key bindings.

Actors requiring key bindings should create a new Clutter::BindingPool inside their class initialization function and then install actions like this:

        my ($self) = @_;
        my $binding_pool = Clutter::BindingPool->new('MyActor');
        # install a key binding for 'Up'
            $Clutter::Keysyms{Up}, [ ],
        # install a key binding for Shift+Up; the action name
        # is the same, as well as the callback
            $Clutter::Keysyms{Up}, [ qw( shift-mask ) ],
        # keep a reference on the binding pool
        $self->{binding_pool} = $binding_pool;

The callback function has a signature of:

    sub callback {
        my (
        ) = @_;
        return $was_the_action_handled;

The actor should then override the Clutter::Actor ``key-press-event'' signal and use Clutter::BindingPool::activate() to match a Clutter::Event::Key to one of the actions:

    sub on_key_press_event {
        my ($self, $event) = @_;
        return $self->{binding_pool}->activate(

The Clutter::BindingPool::activate() method will return "FALSE" if no action for the given key binding was found in the pool, if the action was blocked using Clutter::BindingPool::block_action(), or if the handler returned "FALSE"; otherwise, it will return "TRUE".




bindingpool = Clutter::BindingPool->new ($name)

  • $name (string)

boolean = $pool->activate ($key_val, $modifiers, $object)

  • $key_val (integer)
  • $modifiers (Clutter::ModifierType)
  • $object (Glib::Object)

$pool->block_action ($action_name)

  • $action_name (string)

string = $pool->find_action ($key_val, $modifiers)

  • $key_val (integer)
  • $modifiers (Clutter::ModifierType)

$pool->install_action ($action_name, $key_val, $modifiers, $func, $data=undef)

  • $action_name (string)
  • $key_val (integer)
  • $modifiers (Clutter::ModifierType)
  • $func (scalar)
  • $data (scalar)

$pool->override_action ($key_val, $modifiers, $func, $data=undef)

  • $key_val (integer)
  • $modifiers (Clutter::ModifierType)
  • $func (scalar)
  • $data (scalar)

$pool->remove_action ($key_val, $modifiers)

  • $key_val (integer)
  • $modifiers (Clutter::ModifierType)

$pool->unblock_action ($action_name)

  • $action_name (string)


'name' (string : readable / writable / construct-only / private)
The unique name of the binding pool


flags Clutter::ModifierType

  • 'shift-mask' / 'CLUTTER_SHIFT_MASK'
  • 'lock-mask' / 'CLUTTER_LOCK_MASK'
  • 'control-mask' / 'CLUTTER_CONTROL_MASK'
  • 'mod1-mask' / 'CLUTTER_MOD1_MASK'
  • 'mod2-mask' / 'CLUTTER_MOD2_MASK'
  • 'mod3-mask' / 'CLUTTER_MOD3_MASK'
  • 'mod4-mask' / 'CLUTTER_MOD4_MASK'
  • 'mod5-mask' / 'CLUTTER_MOD5_MASK'
  • 'button1-mask' / 'CLUTTER_BUTTON1_MASK'
  • 'button2-mask' / 'CLUTTER_BUTTON2_MASK'
  • 'button3-mask' / 'CLUTTER_BUTTON3_MASK'
  • 'button4-mask' / 'CLUTTER_BUTTON4_MASK'
  • 'button5-mask' / 'CLUTTER_BUTTON5_MASK'
  • 'super-mask' / 'CLUTTER_SUPER_MASK'
  • 'hyper-mask' / 'CLUTTER_HYPER_MASK'
  • 'meta-mask' / 'CLUTTER_META_MASK'
  • 'release-mask' / 'CLUTTER_RELEASE_MASK'
  • 'modifier-mask' / 'CLUTTER_MODIFIER_MASK'


Copyright (C) 2006, 2007, 2008 OpenedHand Ltd

Copyright (C) 2009 Intel Corporation

This module is free software; you can redistribute it and/or modify it under the terms of either:

  • the GNU Lesser General Public Library version 2.1; or
  • the Artistic License, version 2.0.

See Clutter for the full copyright notice.