---
name: "X11::Protocol::ChooseWindow"
section: "3pm"
platform: "linux"
package: "perl-x11-protocol-other"
version: "31-6"
release: "Arch Linux 2026-11-01"
platforms: ["linux"]
url: "https://new.carta.tech/X11::Protocol::ChooseWindow"
---

# X11::Protocol::ChooseWindow(3pm)

## 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, X11::Protocol::WM, X11::CursorFont

[**xwininfo**(1)](/xwininfo/1.md), [**xkill**(1)](/xkill/1.md), 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/\>.