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