man Clutter::BindingPool (3): Pool for key bindings

DESCRIPTION

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:

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

The callback function has a signature of:

    sub callback {
        my (
            $instance,
            $action_name,
            $key_val,
            $modifiers,
            $user_data
        ) = @_;
        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(
            $event->keyval,
            $event->modifier_state,
            $self,
        );
    }

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

HIERARCHY

  Glib::Object
  +----Clutter::BindingPool

METHODS

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)

PROPERTIES

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

ENUMS AND FLAGS

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

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.