| Prima::EventHook(3) | User Contributed Perl Documentation | Prima::EventHook(3) |
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 visibilityThese 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
| 2024-08-20 | perl v5.40.0 |