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