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
Prima dispatches events by calling notifications registered on one or
more objects interested in the events. Also, one event hook can be
installed that would receive all events occurred on all objects.
"Prima::EventHook" provides multiplex access to the core event hook and
introduces set of dispatching rules so the user hook subs receive only
a defined subset of events.
The filtering criteria are event names and object hierarchy.
API
install SUB, %RULES
Installs SUB into hook list using hash of RULES.
The SUB is called with variable list of parameters, formed so first
passed parameters from 'param' key ( see below ), then event source
object, then event name, and finally parameters to the event. 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 further
called.
Rules can contain the following keys:
event
Event is either a string, an array of strings, or "undef" value.
In the latter case it is equal to '*' string, which selects all
events to be passed in the SUB. A string is either name of an
event, or one of pre-defined event groups, declared in %groups
package hash. The group names are:
ability
focus
geometry
keyboard
menu
mouse
objects
visibility
These contain respective events. See source for detailed
description.
In case 'event' key is an array of strings, each of the strings is
also name of either an event or a group. In this case, if '*'
string or event duplicate names are present in the list, SUB is
called several times which is obviously inefficient.
object
A Prima object, or an array of Prima objects, or undef; the latter
case matches all objects. If an object is defined, the SUB is
called if event source is same as the object.
children
If 1, SUB is called using 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 Prima
object hierarchy, as filter object with 'children' set to 1.
Setting together object to "undef" and children to 1 is
inefficient.
param
A scalar or array of scalars passed as first parameters to SUB
whenever it is called.
deinstall SUB
Removes the hook sub for the hook list.
NOTES
"Prima::EventHook" by default automatically starts and stops 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