1Prima::EventHook(3)   User Contributed Perl Documentation  Prima::EventHook(3)
2
3
4

NAME

6       Prima::EventHook - event filtering
7

SYNOPSIS

9               use Prima::EventHook;
10
11               sub hook
12               {
13                       my ( $my_param, $object, $event, @params) = @_;
14                       ...
15                       print "Object $object received event $event\n";
16                       ...
17                       return 1;
18               }
19
20               Prima::EventHook::install( \&hook,
21                       param    => $my_param,
22                       object   => $my_window,
23                       event    => [qw(Size Move Destroy)],
24                       children => 1
25               );
26
27               Prima::EventHook::deinstall(\&hook);
28

DESCRIPTION

30       Prima dispatches events by calling notifications registered on one or
31       more objects interested in the events. Also, one event hook can be
32       installed that would receive all events occurred on all objects.
33       "Prima::EventHook" provides multiplex access to the core event hook and
34       introduces set of dispatching rules so the user hook subs receive only
35       a defined subset of events.
36
37       The filtering criteria are event names and object hierarchy.
38

API

40   install SUB, %RULES
41       Installs SUB into hook list using hash of RULES.
42
43       The SUB is called with variable list of parameters, formed so first
44       passed parameters from 'param' key ( see below ), then event source
45       object, then event name, and finally parameters to the event. SUB must
46       return an integer, either 0 or 1, to block or pass the event,
47       respectively.  If 1 is returned, other hook subs are called; if 0 is
48       returned, the event is efficiently blocked and no hooks are further
49       called.
50
51       Rules can contain the following keys:
52
53       event
54           Event is either a string, an array of strings, or "undef" value.
55           In the latter case it is equal to '*' string, which selects all
56           events to be passed in the SUB. A string is either name of an
57           event, or one of pre-defined event groups, declared in %groups
58           package hash. The group names are:
59
60                   ability
61                   focus
62                   geometry
63                   keyboard
64                   menu
65                   mouse
66                   objects
67                   visibility
68
69           These contain respective events. See source for detailed
70           description.
71
72           In case 'event' key is an array of strings, each of the strings is
73           also name of either an event or a group. In this case, if '*'
74           string or event duplicate names are present in the list, SUB is
75           called several times which is obviously inefficient.
76
77       object
78           A Prima object, or an array of Prima objects, or undef; the latter
79           case matches all objects. If an object is defined, the SUB is
80           called if event source is same as the object.
81
82       children
83           If 1, SUB is called using same rules as described in 'object', but
84           also if the event source is a child of the object. Thus, selecting
85           "undef" as a filter object and setting 'children' to 0 is almost
86           the same as selecting $::application, which is the root of Prima
87           object hierarchy, as filter object with 'children' set to 1.
88
89           Setting together object to "undef" and children to 1 is
90           inefficient.
91
92       param
93           A scalar or array of scalars passed as first parameters to SUB
94           whenever it is called.
95
96   deinstall SUB
97       Removes the hook sub for the hook list.
98

NOTES

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

AUTHOR

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

SEE ALSO

108       Prima, Prima::Object
109
110
111
112perl v5.32.1                      2021-01-27               Prima::EventHook(3)
Impressum