X11::Protocol::ChooseWindow(3)
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 choose is implemented in a similar way to the "xwininfo" etc
programs. It consists of "GrabPointer()" on the root window, wait for
a "ButtonPress" and "ButtonRelease" from the user, get the frame window
from the "ButtonPress" event, then the client window under there from
"frame_window_to_client()" of "X11::Protocol::WM".
"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.
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");
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.
SEE ALSO
X11::Protocol(3), X11::Protocol::WM(3), X11::CursorFont(3)
xwininfo(1), xkill(1), and their dsimple.c "Select_Window()" code
"Inter-Client Communication Conventions Manual" section "WM_STATE
Property" for notes on using "WM_STATE" to identify client windows.
HOME PAGE
<http://user42.tuxfamily.org/x11-protocol-other/index.html>
LICENSE
Copyright 2010, 2011, 2012, 2013, 2014, 2016, 2017 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/>.
perl v5.28.1 2017-04-06 X11::Protocol::ChooseWindow(3)
x11-protocol-other 30 - Generated Tue Feb 19 07:22:10 CST 2019