.\" Automatically generated by Pod::Man 2.28 (Pod::Simple 3.28)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{
.    if \nF \{
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Prima::EventHook 3"
.TH Prima::EventHook 3 "2009-02-24" "perl v5.20.1" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Prima::EventHook \- event filtering
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&        use Prima::EventHook;
\&
\&        sub hook
\&        {
\&                my ( $my_param, $object, $event, @params) = @_;
\&                ...
\&                print "Object $object received event $event\en";
\&                ...
\&                return 1;
\&        }
\&
\&        Prima::EventHook::install( \e&hook, 
\&                param    => $my_param,
\&                object   => $my_window, 
\&                event    => [qw(Size Move Destroy)],
\&                children => 1
\&        );
\&
\&        Prima::EventHook::deinstall(\e&hook);
.Ve
.SH "DESCRIPTION"
.IX Header "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. \f(CW\*(C`Prima::EventHook\*(C'\fR 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.
.PP
The filtering criteria are event names and object hierarchy.
.SH "API"
.IX Header "API"
.ie n .SS "install \s-1SUB,\s0 %RULES"
.el .SS "install \s-1SUB,\s0 \f(CW%RULES\fP"
.IX Subsection "install SUB, %RULES"
Installs \s-1SUB\s0 into hook list using hash of \s-1RULES.\s0
.PP
The \s-1SUB\s0 is called with variable list of parameters, formed so first passed
parameters from \f(CW\*(Aqparam\*(Aq\fR key ( see below ), then event source object, then
event name, and finally parameters to the event. \s-1SUB\s0 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.
.PP
Rules can contain the following keys:
.IP "event" 4
.IX Item "event"
Event is either a string, an array of strings, or \f(CW\*(C`undef\*(C'\fR value.  In the latter
case it is equal to \f(CW\*(Aq*\*(Aq\fR string, which selects all events to be passed in the
\&\s-1SUB. A\s0 string is either name of an event, or one of pre-defined event groups, 
declared in \f(CW%groups\fR package hash. The group names are:
.Sp
.Vb 8
\&        ability
\&        focus
\&        geometry
\&        keyboard
\&        menu
\&        mouse  
\&        objects
\&        visibility
.Ve
.Sp
These contain respective events. See source for detailed description.
.Sp
In case \f(CW\*(Aqevent\*(Aq\fR key is an array of strings, each of the strings is
also name of either an event or a group. In this case, if \f(CW\*(Aq*\*(Aq\fR string
or event duplicate names are present in the list, \s-1SUB\s0 is called several
times which is obviously inefficient.
.IP "object" 4
.IX Item "object"
A Prima object, or an array of Prima objects, or undef; the latter case
matches all objects. If an object is defined, the \s-1SUB\s0 is called
if event source is same as the object.
.IP "children" 4
.IX Item "children"
If 1, \s-1SUB\s0 is called using same rules as described in \f(CW\*(Aqobject\*(Aq\fR, but also if
the event source is a child of the object. Thus, selecting \f(CW\*(C`undef\*(C'\fR as a filter
object and setting \f(CW\*(Aqchildren\*(Aq\fR to 0 is almost the same as selecting
\&\f(CW$::application\fR, which is the root of Prima object hierarchy, as filter
object with \f(CW\*(Aqchildren\*(Aq\fR set to 1.
.Sp
Setting together object to \f(CW\*(C`undef\*(C'\fR and children to 1 is inefficient.
.IP "param" 4
.IX Item "param"
A scalar or array of scalars passed as first parameters to \s-1SUB \s0
whenever it is called.
.SS "deinstall \s-1SUB\s0"
.IX Subsection "deinstall SUB"
Removes the hook sub for the hook list.
.SH "NOTES"
.IX Header "NOTES"
\&\f(CW\*(C`Prima::EventHook\*(C'\fR 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 \f(CW$auto_hook\fR to 0.
.SH "AUTHOR"
.IX Header "AUTHOR"
Dmitry Karasik, <dmitry@karasik.eu.org>.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Prima, Prima::Object