Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
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
       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

perl v5.24.1			  2017-02-28		   Prima::EventHook(3)

NAME | SYNOPSIS | DESCRIPTION | API | NOTES | AUTHOR | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Prima::EventHook&sektion=3&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help