1X11::Protocol::ChooseWiUnsdeorw(C3o)ntributed Perl DocumXe1n1t:a:tPiroontocol::ChooseWindow(3)
2
3
4

NAME

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

SYNOPSIS

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

DESCRIPTION

13       This spot of code lets the user click on a toplevel window to choose
14       it, in a similar style to the "xwininfo" or "xkill" programs.
15
16   Implementation
17       The choose is implemented in a similar way to the "xwininfo" etc
18       programs.  It consists of "GrabPointer()" on the root window, wait for
19       a "ButtonPress" and "ButtonRelease" from the user, get the frame window
20       from the "ButtonPress" event, then the client window under there from
21       "frame_window_to_client()" of "X11::Protocol::WM".
22
23       "KeyPress" events are not used and they go to the focus window in the
24       usual way.  This can be good in a command line program since it lets
25       the user press "^C" ("SIGINT") in an "xterm" or similar.  Perhaps in
26       the future there could be an option to watch for "Esc" to cancel or
27       some such.
28
29       A virtual root per "root_to_virtual_root()" in "X11::Protocol::WM" is
30       used if present.  This helps "ChooseWindow" work with "amiwm" and
31       similar virtual root window managers.
32

FUNCTIONS

34       The following "choose()" is in class method style with the intention of
35       perhaps in the future having objects of type
36       "X11::Protocol::ChooseWindow" holding state and advanced by events
37       supplied by an external main loop.
38
39   Choosing
40       "$window = X11::Protocol::ChooseWindow->choose (key=>value,...)"
41           Read a user button press to choose a toplevel window.  The
42           key/value options are as follows,
43
44               X        => X11::Protocol object
45               display  => string ":0:0" etc
46
47               screen   => integer, eg. 0
48               root     => XID of root window
49
50               time     => integer server timestamp
51               event    => hashref of event initiating the choose
52
53               cursor       => XID of cursor
54               cursor_glyph => integer glyph for cursor font
55               cursor_name  => string name from cursor font
56
57           "X" or "display" gives the server, or the default is to open the
58           "DISPLAY" environment variable.  "X" for an "X11::Protocol" object
59           is usual, but sometimes it can make sense to open a new connection
60           just to choose.
61
62           "root" or "screen" gives the root window to choose on, or the
63           default is the current screen of $X, which in turn defaults to the
64           screen part of the display name.  If there's a window manager
65           virtual root then that's automatically used as necessary.
66
67           "time" or the time field in "event" is a server timestamp for the
68           "GrabPointer()".  This guards against stealing a grab from another
69           client if badly lagged.  Omitted or "undef" means "CurrentTime".
70           In a command line program there might be no initiating event,
71           making "CurrentTime" all that's possible.
72
73           "cursor" etc is the mouse pointer cursor to show during the choose,
74           as a visual indication to the user.  The default is a "crosshair".
75           "cursor_name" or "cursor_glyph" are from the usual cursor font.
76           See X11::CursorFont for available names.  For example perhaps the
77           "exchange" cursor to choose a window for some sort of swap or flip,
78
79               $window = X11::Protocol::ChooseWindow->choose
80                           (X => $X,
81                            cursor_name => "exchange");
82
83           A "cursor" XID can be created by any client as usual.  Don't forget
84           to flush if creating a cursor from one connection, so it's ready
85           for use from another.
86

SEE ALSO

88       X11::Protocol, X11::Protocol::WM, X11::CursorFont
89
90       xwininfo(1), xkill(1), and their dsimple.c "Select_Window()" code
91
92       "Inter-Client Communication Conventions Manual" section "WM_STATE
93       Property" for notes on using "WM_STATE" to identify client windows.
94

HOME PAGE

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

LICENSE

99       Copyright 2010, 2011, 2012, 2013, 2014, 2016, 2017, 2019 Kevin Ryde
100
101       X11-Protocol-Other is free software; you can redistribute it and/or
102       modify it under the terms of the GNU General Public License as
103       published by the Free Software Foundation; either version 3, or (at
104       your option) any later version.
105
106       X11-Protocol-Other is distributed in the hope that it will be useful,
107       but WITHOUT ANY WARRANTY; without even the implied warranty of
108       MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
109       General Public License for more details.
110
111       You should have received a copy of the GNU General Public License along
112       with X11-Protocol-Other.  If not, see <http://www.gnu.org/licenses/>.
113
114
115
116perl v5.36.0                      2022-07-22    X11::Protocol::ChooseWindow(3)
Impressum