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.