X11::P...eWindow(3pm)

🌸 X11::Protocol::ChooseWindow — bestie, you click a window and it's chosen 💅

okay so this is the X11::Protocol::ChooseWindow page from the User Contributed Perl Documentation (that's the 3pm vibe, iykyk). it lives in X11-Protocol-Other and it does exactly one thing and does it gorgeously: it lets a human point at a window and pick it. 🫶

---

✨ NAME ✨

X11::Protocol::ChooseWindow — user click to choose window 🖱️💖

---

🎀 SYNOPSIS 🎀

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

like. that's it. that's the whole thing. slay. ✨

---

💜 DESCRIPTION 💜

This lil spot of code lets the user click on a toplevel window to choose it, in a similar style to the xwininfo or xkill programs. no cap, same energy as those icons. 👑

🌈 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. the way it just. walks down to the actual client window. obsessed. 🦋

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. bestie that's lowkey a feature — you can still rage-quit with ^C and it just works. 😌 Perhaps in the future there could be an option to watch for Esc to cancel or some such. (manifesting that for later ✨)

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. so if you're on some funky virtual-root WM, it's got you. 🫶

---

👑 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. rn it's a class method, but the door is open for object main-character energy later. 🚪✨

🌟 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

okay now let's go through these one by one, no skipping, we don't do that here 💅

• 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. like yeah normally you already have your connection, but sometimes a fresh one is just the move. 🌸
• 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. automatic. iconic. ✨
• 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. so it's like, protection against grab-stealing when things are laggy, and if you got nothing, CurrentTime is what you got. periodt. ⏰
• 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");

the exchange cursor for a swap/flip situation?? the theming?? immaculate. 🔄✨

• 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.

⚠️ bestie do NOT forget the flush if you're creating a cursor on one connection and using it from another — it will not be ready and you will be sad. 💀

---

🦋 SEE ALSO 🦋

• X11::Protocol, X11::Protocol::WM, X11::CursorFont
• 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, 2019 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/>.

---

and that's the whole page bestie, mwah 💋 — this was X11::P...eWindow(3pm) from perl v5.28.1, dated 2019-08-26. go click a window, you deserve it. 🎀✨