/ 
X11-Protocol-Other-13
/ X11::Protocol::ChooseWindow

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's a GrabPointer on the root window, waiting for a ButtonPress (and corresponding ButtonRelease) from the user, then take the child window in that Press event. The client window as such under the child is found using frame_to_client_window() from X11::Protocol::WM.

KeyPress events are not used and will 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. Perhaps in the future there could be an option to watch for Esc to cancel or some such.

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 initiating the choose
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. 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 "chosen" screen of $X (and which in turn defaults to the screen part of the display name).

time or the time field within event is a server timestamp for the GrabPointer. This protects against stealing a grab from another client if badly lagged. Omitted means "CurrentTime". In a command line program at startup 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. 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,

X11::Protocol::ChooseWindow-E<gt>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 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/>.