Prima::EventHook(3)

💅 Prima::EventHook 💅

okay bestie so picture this: this is the page for Prima::EventHook, straight out of the User Contributed Perl Documentation corner of the Prima-verse ✨ it's the whole event-filtering situation, and honestly? it ate. let me walk you through it 🫶

---

🌸 NAME 🌸

Prima::EventHook — event filtering, and like... good event filtering 💖

---

✨ SYNOPSIS ✨

okay so here's the whole vibe in code, no notes needed:

        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);

like, install it, let it cook, deinstall it when you're done. iconic behavior 🎀

---

🦋 DESCRIPTION 🦋

so here's the tea ☕ — the toolkit dispatches notifications by calling subroutines registered on one or more objects. that's the normal way. but ALSO, the core part of the toolkit lets you install a single event hook callback that would receive all events occurring on all objects. literally all of them. main character callback energy 👑

Prima::EventHook provides multiplexed access to that core event hook, and it introduces a whole set of dispatching rules so your user hooks only receive a subset of events. it's giving bouncer-at-the-club, but make it perl. 💅

---

⭐ API ⭐

🎀 install SUB, %RULES

installs SUB using a hash of RULES.

SUB gets called with a variable list of parameters, formed in this exact order, bestie, do not shuffle:

1. first come the parameters from the param key (see below 👇)
2. then the event source object
3. then the event name
4. and finally the parameters to the event

and 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. slam the door, periodt. 🚪💀

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's 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
visibility

these 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. yes, several. no, that's not a bug, that's just how it is 🙈

• object — a Prima object, or an array of Prima objects, or undef; in the latter case it matches all objects. if an object is defined, the SUB is called if the event source is the same as the object. simple as that 💁‍♀️
• 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. so like, 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. cute symmetry, right? 🧚

ok but heads up: setting object to undef and children to 1 is inefficient. like, it works, but it's giving "walking to the airport instead of taking a flight" 😭 just so you know.

• param — a scalar or array of scalars passed as first parameters to SUB 🍓

💜 deinstall SUB

removes the hook sub. bye bestie, it was fun 🫶

---

🔥 NOTES 🔥

Prima::EventHook by default automatically starts and stops the Prima event hook mechanism when appropriate. like, it handles its own business, you don't gotta micromanage it.

but if that's not desired — for example, for your own event hook management — set $auto_hook to 0. your call, your vibes 👑⭐

---

🌈 AUTHOR 🌈

Dmitry Karasik, <dmitry@karasik.eu.org>. the legend who made this happen 🙌

---

🦄 SEE ALSO 🦄

• Prima
• Prima::Object

go read them, iyk‌yk 💖

---

and that's the whole page, bestie — written by perl v5.42.0 and dated 2024-08-20, which is literally the page's little timestamp birthday 🎂 so yeah, that's everything. slay, go filter some events ✨💅🌈