NAME

       X11::Protocol::ChooseWindow -- user click to choose window

SYNOPSIS

        use X11::Protocol::ChooseWindow;
        my $client_window = X11::Protocol::ChooseWindow->choose (X => $X);

DESCRIPTION

       This spot of code lets the user click on a toplevel window to choose it, in a similar
       style to the "xwininfo" or "xkill" programs.

   Implementation
       The method is similar to the "xwininfo" etc programs.  It consists of a "GrabPointer" on
       the root window, waits for a "ButtonPress" and corresponding "ButtonRelease" from the
       user, get the frame window is from the Press event, then the client window under there
       from "frame_window_to_client()" in "X11::Protocol::WM".

       "KeyPress" events are not used and go to the focus window in the usual way.  This can be
       good in a command line program since it lets the user press "^C" ("SIGINT") in an "xterm"
       or similar.  Perhaps in the future there could be an option to watch for "Esc" to cancel
       or some such.

       A virtual root per "root_to_virtual_root()" in "X11::Protocol::WM" is used if present.
       This helps "ChooseWindow" work with "amiwm" and similar virtual root window managers.

FUNCTIONS

       The following "choose()" is in class method style with the intention of perhaps in the
       future having objects of type "X11::Protocol::ChooseWindow" holding state and advanced by
       events supplied by an external main loop.

   Choosing
       "$window = X11::Protocol::ChooseWindow->choose (key=>value,...)"
           Read a user button press to choose a toplevel window.  The key/value options are as
           follows,

               X        => X11::Protocol object
               display  => string ":0:0" etc

               screen   => integer, eg. 0
               root     => XID of root window

               time     => integer server timestamp
               event    => hashref of event initiating the choose

               cursor       => XID of cursor
               cursor_glyph => integer glyph for cursor font
               cursor_name  => string name from cursor font

           "X" or "display" gives the server, or the default is to open the "DISPLAY" environment
           variable.  "X" for an "X11::Protocol" object is usual, but sometimes it can make sense
           to open a new connection just to choose.

           "root" or "screen" gives the root window to choose on, or the default is the current
           screen of $X, which in turn defaults to the screen part of the display name.  If
           there's a window manager virtual root then that's automatically used as necessary.

           "time" or the time field in "event" is a server timestamp for the "GrabPointer()".
           This guards against stealing a grab from another client if badly lagged.  Omitted or
           "undef" means "CurrentTime".  In a command line program there might be no initiating
           event, making "CurrentTime" all that's possible.

           "cursor" etc is the mouse pointer cursor to show during the choose, as a visual
           indication to the user.  The default is a "crosshair".  "cursor_name" or
           "cursor_glyph" are from the usual cursor font.  See X11::CursorFont for available
           names.  For example perhaps the "exchange" cursor to choose a window for some sort of
           swap or flip,

               $window = X11::Protocol::ChooseWindow->choose
                           (X => $X,
                            cursor_name => "exchange");

SEE ALSO

       X11::Protocol, X11::Protocol::WM, X11::CursorFont

       xwininfo(1), xkill(1), and their dsimple.c "Select_Window()" code

HOME PAGE

       <http://user42.tuxfamily.org/x11-protocol-other/index.html>

LICENSE

       Copyright 2010, 2011, 2012, 2013 Kevin Ryde

       X11-Protocol-Other is free software; you can redistribute it and/or modify it under the
       terms of the GNU General Public License as published by the Free Software Foundation;
       either version 3, or (at your option) any later version.

       X11-Protocol-Other is distributed in the hope that it will be useful, but WITHOUT ANY
       WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
       PURPOSE.  See the GNU General Public License for more details.

       You should have received a copy of the GNU General Public License along with
       X11-Protocol-Other.  If not, see <http://www.gnu.org/licenses/>.