---
name: "X11::WindowHierarchy"
section: "3pm"
platform: "linux"
package: "libx11-windowhierarchy-perl"
version: "0.004-3"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/X11::WindowHierarchy"
---

# X11::WindowHierarchy(3pm)

wrapper around X11::Protocol for retrieving the current window hierarchy

## NAME

X11::WindowHierarchy - wrapper around X11::Protocol for retrieving the current window hierarchy

## VERSION

version 0.004

## 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'));
```

## DESCRIPTION

Provides a couple of helper functions based on X11::Protocol for extracting the current window hierarchy.

## FUNCTIONS

The following functions are exported by default, to avoid this:

```
 use X11::WindowHierarchy qw();
```

### x11\_hierarchy

Returns a hashref representing the current window hierarchy.

Takes the following named parameters, all of which are optional:

- •

  display - DISPLAY string, such as ':0'

- •

  screen - the screen to use, such as 0 or 1

Returns a hashref structure which contains the following 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, with any vertical whitespace (such as \\n) converted to a single space

- •

  icon\_name - the icon name

- •

  children - an arrayref of any child windows under this

### x11\_filter\_hierarchy

Similar to "x11\_hierarchy" function, but instead of returning a tree hierarchy, returns a list of windows which match the given criteria.

Takes the same parameters as "x11\_hierarchy", with the addition of a `" filter "` parameter.

If given a coderef as the filter, this will be called for each window found, including the window in the output list if the coderef returns a true value. The hashref representing the window will be passed as the first parameter and for convenience is also available in `$_`. The full hierarchy will be constructed before filtering the list of windows, so you can perform matches based on the child elements if required.

If given a regex as the filter, returns only the windows whose title matches the given regex.

## EXAMPLES

Get all window IDs for a given PID:

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

Find the window ID for the largest (as measured by width x height) window 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 - provides all the real functionality this module uses

## AUTHOR

Tom Molesworth \<cpan@entitymodel.com\>

## LICENSE

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