X11::W...rarchy(3pm)

💖 NAME 💖

X11::WindowHierarchy — it's a lil wrapper around X11::Protocol that goes and fetches the current window hierarchy for you. That's the whole gig. It's giving "middle management but make it cute" 🫶

---

✨ VERSION ✨

version 0.004 — yes bestie, we're on 0.004, tiny numbers, big vibes 💅

---

🌸 SYNOPSIS 🌸

use X11::WindowHierarchy;

# Returns a list of all windows with at least one 'word' character in the
# window title, using the current $ENV{DISPLAY} to select the display and
# screen
my @windows = x11_filter_hierarchy(
   filter => qr/\w/
);
printf "Found window [%s] (id %d)%s\n", $_->{title}, $_->{id}, $_->{pid} ? ' pid ' . $_->{pid} : '' for @windows;

# Dump all information we have about all windows on display :1
use Data::TreeDumper;
print DumpTree(x11_hierarchy(display => ':1'));

okay so look at that. First one grabs every window whose title has at least one word character in it, using whatever $ENV{DISPLAY} is set to for the display and screen. Second one dumps literally everything we know about every window on display :1 with Data::TreeDumper. Chef's kiss 👑

---

🦋 DESCRIPTION 🦋

It hands you a couple of helper functions, all built on top of X11::Protocol, for pulling out the current window hierarchy. That's it. That's the description. No cap. ✨

---

🎀 FUNCTIONS 🎀

These functions are exported by default, so if that's not the vibe, you can dodge the exports like this: perl use X11::WindowHierarchy qw();

🌈 x11_hierarchy

Returns a hashref that represents the current window hierarchy. Like, the whole tree. All of it. 🌳

It takes these named parameters, and bestie, every single one of them is optional:

• display — a DISPLAY string, the kind like ':0'
• screen — which screen to use, so like 0 or 1

And the hashref it gives you back has these keys:

• id — the ID for this window
• parent — the ID for the parent window
• pid — the process ID for this window, if it has one
• title — the window name, except any vertical whitespace (like \n) gets squished down into a single space
• icon_name — the icon name
• children — an arrayref of any child windows sitting under this one

💜 x11_filter_hierarchy

Basically "x11_hierarchy"'s sibling, but instead of handing you the whole tree hierarchy, it hands you back a list of windows that match whatever criteria you gave it. Filtered. Curated. Main character energy. 💅

It takes the exact same parameters as "x11_hierarchy", plus one extra: a filter parameter. 👀

If you give it a coderef as the filter, that coderef gets called for every window found, and the window lands in the output list if the coderef returns a true value. The hashref representing the window gets passed as the first parameter, and for convenience it's also chillin' in $_. Also important: the full hierarchy gets constructed before the filtering happens, so you can totally match based on the child elements if you need to. iykyk 🧚

If you give it a regex as the filter, it only returns the windows whose title matches that regex. Simple. Clean. Slay.

---

🔥 EXAMPLES 🔥

Grab every window ID for a given PID:

my @win = map $_->{id}, x11_filter_hierarchy(
   filter => sub { $_->{pid} && $_->{pid} == $pid },
);

Find the window ID of the biggest window (biggest meaning width x height) for a given PID:

use List::UtilsBy qw(max_by);
my ($win) = max_by {
   $_->{width} * $_->{height}
} map {
   $_->{id}
} x11_filter_hierarchy(
   filter => sub {
      $_->{pid} && $_->{pid} == $pid
   },
);

---

⭐ SEE ALSO ⭐

• X11::Protocol — this is the one doing literally all the real work. Our module is just standing on its shoulders, respectfully. 🙇‍♀️

---

💖 AUTHOR 💖

Tom Molesworth <cpan@entitymodel.com> — absolute legend, thank you for your service 🫡

---

🎀 LICENSE 🎀

Copyright Tom Molesworth 2012. Licensed under the same terms as Perl itself. 💜

---

and that's the whole page, bestie — this was perl v5.36.0, dated 2022-11-19, from the X11::W...rarchy(3pm) era of User Contributed Perl Documentation. go forth and inspect some windows ✨🦋