NAME

Prima::EventHook - event filtering

SYNOPSIS

        use Prima::EventHook;

        sub hook
        {
                my ( $my_param, $object, $event, @params) = @_;
                ...
                print "Object $object received event $event\n";
                ...
                return 1;
        }

        Prima::EventHook::install( \&hook,
                param    => $my_param,
                object   => $my_window,
                event    => [qw(Size Move Destroy)],
                children => 1
        );

        Prima::EventHook::deinstall(\&hook);

DESCRIPTION

The toolkit dispatches notifications by calling subroutines registered on one or more objects. Also, the core part of the toolkit allows a single event hook callback to be installed that would receive all events occurring on all objects. Prima::EventHook provides multiplexed access to the core event hook and introduces a set of dispatching rules so that the user hooks can receive only a subset of events.

API

install SUB, %RULES

Installs SUB using a hash of RULES.

The SUB is called with a variable list of parameters, formed so that first come parameters from the 'param' key ( see below ), then the event source object, then the event name, and finally the parameters to the event. The SUB must return an integer, either 0 or 1, to block or pass the event, respectively. If 1 is returned, other hook subs are called; if 0 is returned, the event is efficiently blocked and no hooks are called further.

Rules can contain the following keys:

event

An event is either a string, an array of strings, or an undef value. In the latter case, it is equal to a '*' string which selects all events to be passed to the SUB. A string is either the name of an event or one of the pre-defined event groups, declared in the %groups package hash. The group names are:

        ability
        focus
        geometry
        keyboard
        menu
        mouse
        objects
        visibility

These contain the respective events. See the source for a detailed description.

In case the 'event' key is an array of strings, each of the strings is also the name of either an event or a group. In this case, if the '*' string or event duplicate names are present in the list, SUB is called several times.

object

A Prima object, or an array of Prima objects, or undef; in the latter case matches all objects. If an object is defined, the SUB is called if the event source is the same as the object.

children

If 1, SUB is called using the same rules as described in 'object', but also if the event source is a child of the object. Thus, selecting undef as a filter object and setting 'children' to 0 is almost the same as selecting $::application, which is the root of the Prima object hierarchy, as a filter object with 'children' set to 1.

Setting object to undef and children to 1 is inefficient.

param

A scalar or array of scalars passed as first parameters to SUB

deinstall SUB

Removes the hook sub

NOTES

Prima::EventHook by default automatically starts and stops the Prima event hook mechanism when appropriate. If it is not desired, for example for your own event hook management, set $auto_hook to 0.

AUTHOR

Dmitry Karasik, <dmitry@karasik.eu.org>.

SEE ALSO

Prima, Prima::Object