Implementation

"KeyPress" events are not used and they 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.

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

A "cursor" XID can be created by any client as usual. Don't forget to flush if creating a cursor from one connection, so it's ready for use from another.