X11::P...col::WM(3pm)

📦

version 31 · 7 versions

31 · debian bookworm, debian trixie, ubuntu jammy, ubuntu noble (latest)
31 · epel 9
31 · epel 10
31 · arch rolling
31 · fedora 43
31 · fedora 44
31 · ubuntu resolute, ubuntu stonking

, in debian bookworm, debian trixie, ubuntu jammy, ubuntu noble

okay bestie, welcome to the X11::Protocol::WM (3pm) page from the User Contributed Perl Documentation 💖 this one is all about window manager things for client programs, and it's lowkey iconic. let's get into it ✨

✨ NAME ✨

X11::Protocol::WM — window manager things for client programs 🪟💅

✨ SYNOPSIS ✨

use X11::Protocol::WM;

✨ DESCRIPTION ✨

So this is some window manager related functions for use by client programs, as per the "Inter-Client Communication Conventions Manual" and some of the Net-WM "Extended Window Manager Hints". no cap, here's where you read up:

/usr/share/doc/xorg-docs/icccm/icccm.txt.gz

<http://www.freedesktop.org/wiki/Specifications/wm-spec>

🌸 Usual Properties 🌸

Every toplevel client window should usually

set_wm_class() to identify itself to other programs (see WM_CLASS below).
set_wm_name() and set_wm_icon_name() for user-visible window name (see WM_NAME, WM_ICON_NAME below).
set_wm_client_machine_from_syshostname() and set_net_wm_pid() for the running process (see WM_CLIENT_MACHINE and _NET_WM_PID below).

Then optionally,

If you have an icon then set_wm_hints() with a bitmap or a window (see WM_HINTS below).
If the user gave an initial size or position on the command line then set_wm_normal_hints(). The same if the program has min/max sizes or aspect ratio desired (see WM_NORMAL_HINTS below).
If a command to re-run the program can be constructed then set_wm_command(), and preferably keep that up-to-date with changes such as currently open file etc (see WM_COMMAND below).

💅 FUNCTIONS 💅

✨ Text Properties ✨

Property functions taking text strings such as set_wm_name() accept either byte strings or wide char strings (Perl 5.8 up). no cap. Byte strings are presumed to be Latin-1 and set as STRING type in properties. Wide char strings are stored as STRING if entirely Latin-1, or encoded to COMPOUND_TEXT for other chars (see Encode::X11). it's giving encoding realness 🫶

In the future perhaps the string functions could accept some sort of compound text object to represent segments of various encodings to become COMPOUND_TEXT, together with manipulations for such content etc. If text is bytes in one of the ICCCM encodings then it might save work to represent it directly as COMPOUND_TEXT segments rather than going to wide chars and back again. iykyk.

set_text_property ($X, $window, $prop, $str)

Set the given $prop (integer atom) property on $window (integer XID) using either STRING or COMPOUND_TEXT as described above. If $str is undef then $prop is deleted. periodt.

$str is limited to $X->maximum_request_length(). In theory longer strings can be stored by piecewise, but there's no attempt to do that here. The maximum request limit is at least 16384 bytes and the server may allow more, possibly much more. lowkey huge.

🎀 WM_CLASS 🎀

X11::Protocol::WM::set_wm_class ($X, $window, $instance, $class)

Set the WM_CLASS property on $window (an XID).

This property may be used by the window manager to lookup settings and preferences for the program through the X Resource system (see RESOURCES in X(7)) or similar. the way that works is kinda main character energy ngl.

Usually the instance name is the program command such as xterm and the class name something like XTerm. Some programs have command line options to set the class and/or instance so the user can have different window manager settings applied to a particular running copy of a program.

X11::Protocol::WM::set_wm_class ($X, $window,
                                 "myprog", "MyProg");

$instance and $class must be ASCII or Latin-1 only. Wide-char strings which are Latin-1 are converted as necessary.

💜 WM_CLIENT_MACHINE 💜

X11::Protocol::WM::set_wm_client_machine ($X, $window, $hostname)

Set the WM_CLIENT_MACHINE property on $window to $hostname (a string).

$hostname should be the name of the client machine as seen from the server. If $hostname is undef then the property is deleted.

Usually a machine name is ASCII-only, but anything per "Text Properties" above is accepted.

X11::Protocol::WM::set_wm_client_machine_from_syshostname ($X, $window)

Set the WM_CLIENT_MACHINE property on $window using the Sys::Hostname module.

If Sys::Hostname can't determine a hostname by its various gambits then currently the property is deleted. Would it be better to leave it unchanged, or return a flag to say if set? 🤔

Some of the Sys::Hostname cases might return localhost. That's put through unchanged, on the assumption that it would be when there's no networking beyond the local host so client and server are on the same machine and name localhost suffices.

🌈 WM_COMMAND 🌈

X11::Protocol::WM::set_wm_command ($X, $window, $command, $arg...)

Set the WM_COMMAND property on $window (an XID).

This should be a program name and argument strings which will restart the client. $command is the program name, followed by any argument strings.

X11::Protocol::WM::set_wm_command ($X, $window,
                                   'myprog',
                                   '--option',
                                   'filename.txt');

The command should start the client in its current state, so the command might include a filename, command line options for current settings, etc.

Non-ASCII is allowed per "Text Properties" above. The ICCCM spec is for Latin-1 to work on a POSIX Latin-1 system, but how well anything else survives a session manager etc is another matter. ngl that part is a whole vibe check.

A client can set this at any time, or if participating in the WM_SAVE_YOURSELF session manager protocol then it should set in response to a ClientMessage of WM_SAVE_YOURSELF .

For reference, under mwm circa 2017, a client with WM_SAVE_YOURSELF receives that message for the mwm Close button (f.kill) and is expected to respond within a timeout (default 1 second), whereupon mwm closes the client connection (KillClient). Unfortunately if both WM_SAVE_YOURSELF and WM_DELETE_WINDOW then mwm still does the WM_SAVE_YOURSELF and close, defeating the aim of letting WM_DELETE_WINDOW query the user and perhaps not close. 💀

The easiest workaround would be use only WM_DELETE_WINDOW, keep WM_COMMAND always up-to-date, and be prepared to save state on connection loss. This is quite reasonable anyway actually, since a WM_SAVE_YOURSELF message is fairly limited use, given that connection loss or other termination could happen at any time so if state is important that it'd be prudent to keep it saved. fr fr.

🦋 WM_ICON_SIZE 🦋

($min_width,$min_height, $max_width,$max_height, $width_inc,$height_inc) = X11::Protocol::WM::get_wm_icon_size($X,$root)

Return the window manager's WM_ICON_SIZE recommended icon sizes (in pixels) as a range, and increment above the minimum. If there's no WM_ICON_SIZE property then return an empty list.

$root is the root window to read. If omitted then read the $X->root default.

An icon pixmap or window in WM_HINTS should be a size in this range. Many window managers don't set a preferred icon size. 32x32 might be typical on a small screen or 48x48 on a bigger screen. slay.

🍓 WM_HINTS 🍓

X11::Protocol::WM::set_wm_hints ($X, $window, key=>value, ...)

Set the WM_HINTS property on $window (an XID). For example,

X11::Protocol::WM::set_wm_hints
    ($X, $my_window,
     input         => 1,
     initial_state => 'NormalState',
     icon_pixmap   => $my_pixmap);

The key/value parameters are as follows.

input             integer 0 or 1
initial_state     enum string or number
icon_pixmap       pixmap (XID integer), depth 1
icon_window       window (XID integer)
icon_x            \ integer coordinate
icon_y            / integer coordinate
icon_mask         pixmap (XID integer)
window_group      window (XID integer)
urgency           boolean

input is 1 if the client wants the window manager to give $window the keyboard input focus. This will be with $X->SetInputFocus(), or if WM_TAKE_FOCUS is in WM_PROTOCOLS then instead by a ClientMessage.

input is 0 if the window manager should not give the client the focus. This is either because $window is output-only, or if WM_TAKE_FOCUS is in WM_PROTOCOLS then because the client will do a SetInputFocus() to itself on an appropriate button press etc.

initial_state is a string or number. The ICCCM allows NormalState or IconicState as initial states.

"NormalState"       1
"IconicState"       3

icon_pixmap should be a bitmap, ie. a pixmap (XID) with depth 1. The window manager will draw it in suitable contrasting colours. 1 pixels are foreground and 0 is background. icon_mask bitmap is applied to the displayed icon. It can be used to make a non-rectangular icon. obsessed.

icon_window is a window which the window manager may show when $window is iconified. This can be used for a multi-colour icon, done either by a background or by client drawing (in response to Expose events, or updated periodically for a clock, etc). The icon_window should be a child of the root and should use the default visual and colormap of the screen. The window manager might resize the window and/or border.

The window manager might set a WM_ICON_SIZE property on the root window for good icon sizes. See WM_ICON_SIZE above.

window_group is the XID of a window which is the group leader of a group of top-level windows being used by the client. The window manager might provide a way to manipulate the group as a whole, for example to iconify it all. If iconified then the icon hints of the leader are used for the icon. The group leader can be an unmapped window. It can be convenient to use a never-mapped window as the leader for all subsequent windows. iconic.

urgency true means the window is important and the window manager should draw the user's attention to it in some way. The client can change this hint at any time to change the current importance.

(key => $value, ...) = X11::Protocol::WM::get_wm_hints ($X, $window)

Return the WM_HINTS property from $window. The return is a list of key/value pairs as per set_wm_hints() above

input => 1,
icon_pixmap => 1234,
...

Only fields with their flag bits set in the hints are included in the return. If there's no WM_HINTS at all or or its flags field is zero then the return is an empty list.

The return can be dumped straight into a hash so you can grab fields by name, bestie 💖

my %hints = X11::Protocol::WM::get_wm_hints ($X, $window);
if (exists $hints{'icon_pixmap'}) {
  print "icon_pixmap is ", $hints{'icon_pixmap'}, "\n";
}

"initial_state" comes back as a string like "NormalState". The pixmaps and windows are the string "None" if they're set but zero (which, ngl, is probably unusual 🙈). And if "$X->{'do_interp'}" is switched off then literally everything is just numbers.

🦋 Historical tea: X11R2 Xlib had a bug in its XSetWMHints() where it chopped the window_group value right off the hints it stored. So if the data we read is missing that field, window_group gets omitted from the return. Not us being messy — that's the bug's fault, fr fr.

`(key => $value, ...) = X11::Protocol::WM::change_wm_hints ($X, $window, key=>value, ...)`

Change some fields of the WM_HINTS property on $window — the key/value fields you hand over get changed, and every other field is left exactly as it was. Iconic behaviour honestly. Like,

X11::Protocol::WM::set_wm_hints ($X, $window,
                                 urgency => 1);

A value of undef means "delete this field bestie":

X11::Protocol::WM::set_wm_hints ($X, $window,
                                 icon_pixmap => undef,
                                 icon_mask   => undef);

Heads up though 🫶 this change needs a server round-trip to go fetch the current values from $window first. So an application might prefer to just remember its desired hints and send a full set_wm_hints() every single time instead. Your call, main character.

`$bytes = X11::Protocol::WM::pack_wm_hints ($X, key=>value...)`

Pack a set of values into a byte string in WM_HINTS format ✨. The key/value args work per set_wm_hints() above, and what you get back is the raw bytes that get stored in a WM_HINTS property.

The $X argument isn't actually used right now, but it's sitting there just in case "initial_state" or some other value wants an "$X->num()" lookup in the future. Forward thinking, we love to see it 💅

`(key => $value, ...) = X11::Protocol::WM::unpack_wm_hints ($X, $bytes)`

Unpack a byte string as a WM_HINTS structure. You get back key/value pairs, same deal as get_wm_hints() above 🎀. The $X parameter is used for do_interp. Zero communication with the server here — it's all local, no cap.

🏷️ WM_NAME, WM_ICON_NAME

`X11::Protocol::WM::set_wm_name ($X, $window, $name)`

Sets the WM_NAME property on $window (an integer XID) to $name (a string).

The window manager might display this as a title above the window, or in a menu of windows, etc. It can be a Perl 5.8 wide-char string per Text Properties above 🌈. A good window manager ought to support non-ASCII or non-Latin-1 titles, but how well it actually displays them might depend on fonts etc. So... vibes may vary.

`X11::Protocol::WM::set_wm_icon_name ($X, $window, $name)`

Sets the WM_ICON_NAME property on $window (an integer XID) to $name (a string).

The window manager might display this when $window is iconified 🌸. And if $window doesn't have an icon (whether from WM_HINTS or from the window manager itself) then this text might be literally all that's shown. Either way it should be something short, okay? Keep it cute and brief. It can be a Perl 5.8 wide-char string per Text Properties above.

📐 WM_NORMAL_HINTS

`X11::Protocol::WM::set_wm_normal_hints ($X, $window, key=>value,...)`

Sets the WM_NORMAL_HINTS property on $window (an integer XID). This is a WM_SIZE_HINTS structure, and it's how the client tells the window manager what sizes it would like 👑. For example,

set_wm_normal_hints ($X, $window,
                     min_width => 200,
                     min_height => 100);

Generally the window manager restricts user resizing to the hint limits. Most window managers use these hints, but of course they're only hints — a good program should be prepared for other sizes even if it won't look good or can't do much useful when it's too big or too small etc. 😭

The key/value parameters are

user_position      boolean, window x,y is user specified
user_size          boolean, window width,height is user specified
program_position   boolean, window x,y is program specified
program_size       boolean, window width,height is program specified
min_width          \ integers, min size in pixels
min_height         /
max_width          \ integers, max size in pixels
max_height         /
base_width         \ integers, size base in pixels
base_height        /
width_inc          \ integers, size increment in pixels
height_inc         /
min_aspect         \  fraction 2/3 or decimal 2 or 1.5
min_aspect_num      | or integer num/den up to 0x7FFFFFFF
min_aspect_den      |
max_aspect          |
max_aspect_num      |
max_aspect_den     /
win_gravity        WinGravity enum "NorthEast" etc

user_position and user_size are flags meaning the window's x,y or width,height (in the usual core "$X->SetWindowAttributes()") were given by the user — like from a -geometry command line option, iykyk. The window manager will generally obey these values and skip any auto-placement or interactive placement it might otherwise have done. Respect the user's choices, periodt ✨

program_position and program_size are flags meaning the window x,y or width,height were calculated by the program. The window manager might override with its own positioning or sizing policy. There's generally no need to set these fields unless the program has a definite idea of where and how big it should be. For a size it's enough to set the core window width,height and let the window manager (if there's one running) go from there 💅

Items shown grouped above must be given together — so for instance if a min_width is given then min_height should be given too. No leaving your bestie behind.

base_width, base_height and width_inc, height_inc ask that the window be a certain base size in pixels and then a multiple of inc pixels above that. This can be used by things like xterm which want a fixed size for border or scrollbar and then a multiple of the character size above that 🎀. If base_width,base_height are not given then min_width,min_height is the base size.

base_width, base_height can be smaller than min_width,min_height. This means the size should still be a base+inc multiple, but the first such multiple which is at least the min size. The window manager generally presents the inc multiple to the user, so that for example on an xterm the user sees a count of characters 👑. A min size can then demand, for example, a minimum 1x1 or 2x2 character size.

min_aspect, max_aspect ask that the window have a certain minimum or maximum width/height ratio 🌸. For example aspect 2/1 means it should be twice as wide as it is high. This gets applied to the size above base_width,base_height, or if base isn't given then to the whole window size.

min_aspect_num, min_aspect_den and max_aspect_num, max_aspect_den set numerator and denominator values directly (INT32, so maximum 0x7FFF_FFFF). Or min_aspect and max_aspect accept a single value in various forms which get turned into num/den values:

2         integer
1.125     decimal, meaning 1125/1000
2/3       fraction
1.5/4.5   fraction with decimals

Values bigger than 0x7FFFFFFF in these forms are reduced proportionally as necessary. A Perl floating point value will usually have more bits of precision than 0x7FFFFFFF and is truncated to something that fits. Math is doing its thing, we're just here for it 😭

win_gravity is how the client would like to be shifted to make room for any surrounding frame the window manager might add. For example if the program calculated the window size and position to ensure the north-east corner is at a desired position, then give win_gravity => "NorthEast" so the window manager keeps the north-east corner the same when it applies its frame 🧚

win_gravity => "Static" means the frame gets put around the window and the window is not moved at all. Of course that might mean some of the frame ends up off-screen 💀. It is what it is.

`$bytes = X11::Protocol::WM::pack_size_hints ($X, key=>value,...)`

Returns a byte string which is a WM_SIZE_HINTS structure made from the given key/value parameters ✨. WM_SIZE_HINTS is the structure type for WM_NORMAL_HINTS described above, and the key/value parameters work exactly as described above.

The $X parameter is used to interpret win_gravity enum values. And nope, no communication with the server — it's all packed right here, local legend behaviour 💅

`($num,$den) = X11::Protocol::WM::aspect_to_num_den ($aspect)`

Returns a pair of INT32 integers from 0 to 0x7FFF_FFFF for the given aspect ratio $aspect 🎀. This is exactly the conversion applied to min_aspect and max_aspect above. $aspect can be any of the integer, decimal or fraction forms described up there. Slay.

📨 WM_PROTOCOLS

`X11::Protocol::WM::set_wm_protocols ($X, $window, $protocol,...)`

Sets the WM_PROTOCOLS property on $window (an XID). Each argument is a string protocol name or an integer atom ID 🔥

X11::Protocol::WM::set_wm_protocols
  ($X, $window, 'WM_DELETE_WINDOW', '_NET_WM_PING')

For example "WM_DELETE_WINDOW" means that when the user clicks the close button, the window manager sends a ClientMessage event rather than doing a KillClient() 😌. The ClientMessage event lets a program clean up or ask the user about saving a document before exiting, etc. Politely asking instead of just snatching the window away — iconic.

🦋 WM_STATE

The window manager maintains a state for each client window it manages,

WithdrawnState
NormalState
IconicState

WithdrawnState means the window is not mapped and the window manager is not managing it. A newly created window ("$X->CreateWindow()") is initially WithdrawnState and on first "$X->MapWindow()" goes to NormalState (or to IconicState if that's the initial state asked for in WM_HINTS).

iconify() and withdraw() below can change the state to iconic or withdrawn. And a window can be restored from iconic to normal by a MapWindow() ✨

`($state, $icon_window) = X11::Protocol::WM::get_wm_state ($X, $window)`

Returns the WM_STATE property from $window. This is set by the window manager on top-level application windows 👑. If there's no such property then the return is an empty list. Rude, but fine.

$state comes back as an enum string, or an integer value if "$X->{'do_interp'}" is disabled or the value is unrecognised.

"WithdrawnState"    0      not displayed
"NormalState"       1      window displayed
"IconicState"       3      iconified in some way

               "ZoomState"         2      \ no longer in ICCCM
               "InactiveState"     4      /   (zoom meant maximized)

$icon_window — bestie, this is the window (an integer XID, periodt) that the window manager uses to display an icon of $window. If there's no such window then $icon_window is "None" (or 0 if $X->{'do_interp'} is switched off, no cap).

Now the way that $icon_window works: it might be the icon window straight out of the client's WM_HINTS, or it might be a window that the window manager itself created. Either way, the client can draw into it for animations and such — maybe selecting Expose events on it so it knows when to redraw. So cute, so functional. 💖

WM_STATE gets set by the window manager when a toplevel window is first mapped (or perhaps earlier, lowkey), and then it's kept up-to-date. Generally speaking, no WM_STATE property at all, or a WM_STATE set to WithdrawnState, means the window manager is not managing the window — or not yet doing so. A client can select PropertyChange event mask in the usual way to listen for WM_STATE changes. iykyk. ✨

($state, $icon_window) = X11::Protocol::WM::unpack_wm_state ($X, $bytes) — Unpack the bytes of a WM_STATE property into a $state and $icon_window, exactly like get_wm_state() above does. $X is used for $X->{'do_interp'}, but there's no communication with the server — it's all local, no round trip, we love a low-effort icon. 💅
X11::Protocol::WM::iconify ($X, $window)
X11::Protocol::WM::iconify ($X, $window, $root) — Change $window to IconicState by sending a ClientMessage to the window manager. If the window manager doesn't have any iconification then it might do nothing (eg. some tiling window managers, they said what they said). And if there's no window manager running at all, then iconification is not possible and this message will do nothing — it's giving "shouting into the void". 😭 $root should be the root window of $window. If it's not given or it's undef then it's obtained by a QueryTree() right here. Any client can iconify any top level window. If $window has other windows which are WM_TRANSIENT_FOR for it, then generally the window manager will iconify or hide those windows too (peep WM_TRANSIENT_FOR below 👀).
X11::Protocol::WM::withdraw ($X, $window)
X11::Protocol::WM::withdraw ($X, $window, $root) — Change $window to WithdrawnState by an $X->UnmapWindow() plus a synthetic UnmapNotify message to the window manager. If there's no window manager running, then the UnmapWindow() unmaps and the UnmapNotify message just does nothing. $root should be the root window of $window — if it's not given or undef, it's obtained by a QueryTree() here. If other windows are WM_TRANSIENT_FOR this $window (eg. open dialog windows) then generally the client should withdraw them too. The window manager might make such other windows inaccessible anyway. The ICCCM specifies an UnmapNotify message so the window manager is notified of the desired state change even if $window is already unmapped — like when it's in IconicState, or perhaps during some window manager reparenting, etc. $window can be changed back to NormalState or IconicState later with $X->MapWindow() the same as for a newly created window. (And WM_HINTS initial_state can give a desired initial iconic/normal state.) But before doing so, bestie, be sure the window manager has recognised the withdraw() — that's when the window manager changes the WM_STATE property to WithdrawnState, or deletes that property. Any client can withdraw any toplevel window, but it's unusual for a client to withdraw windows which are not its own. 🙈

🦋 WM_TRANSIENT_FOR 🦋

X11::Protocol::WM::set_wm_transient_for ($X, $window, $transient_for) — Set the WM_TRANSIENT_FOR property on $window (an XID). $transient_for is another window XID, or undef if $window is not transient for anything, in which case WM_TRANSIENT_FOR should be deleted. "Transient for" means $window is some sort of dialog or menu related to the given $transient_for window. The window manager will generally iconify $window together with its $transient_for, etc. Peep set_motif_wm_hints() below for "modal" transients. ✨

💅 _MOTIF_WM_HINTS 💅

X11::Protocol::WM::set_motif_wm_hints ($X, $window, key=>value...) — Set the MOTIF_WM_HINTS property on $window (an XID). These hints control window decorations and the "modal" state. It originated in the Motif mwm window manager, but most other window managers recognise it too. It should be set on a toplevel window before mapping. Changes made later might not affect what the window manager does — so don't come crying later, okay? 😭

X11::Protocol::WM::set_motif_wm_hints
  ($X, $dialog_window,
   input_mode => "full_application_modal");
$X->MapWindow ($dialog_window);

Ordinary windows generally don't need to restrict their decorations etc, but something special like a clock or gadget might benefit. Main character windows only, fr fr. ⭐

X11::Protocol::WM::set_motif_wm_hints
  ($X, $my_gadget_window,
   functions   => 4+32,   # move+close
   decorations => 1+4+8); # border+title+menu

The key/value arguments are

functions   => integer bits
decorations => integer bits
input_mode  => enum string or integer
status      => integer bits

functions is what actions the window manager should offer to the user in a drop-down menu or similar. It's an integer bitwise OR of the following values. If it's not given, then the default is normally all functions.

bit    actions offered
---    ---------------
 1     all functions
 2     resize window
 4     move window
 8     minimize, to iconify
16     maximize, to full-screen (with a frame still)
32     close window

decorations is what visual decorations the window manager should show around the window. It's an integer bitwise OR of the following values. If it's not given, then the default is normally all decorations.

bit       decorations displayed
---       ---------------------
 1        all decorations
 2        border around the window
 4        resizeh, handles to resize by dragging
 8        title bar, showing WM_NAME
16        menu, drop-down menu of the "functions" above
32        minimize button, to iconify
64        maximize button, to full-screen

input_mode allows a window to be "modal", meaning the user should interact only with $window. The window manager will generally keep it on top, not move the focus to other windows, etc. The value is one of the following strings or the corresponding integer — pick your fighter: 🎀

  string                   integer
"modeless"                    0    not modal (the default)
"primary_application_modal"   1    modal to its "transient for"
"system_modal"                2    modal to the whole display
"full_application_modal"      3    modal to the current client

primary_application_modal means $window is modal for the WM_TRANSIENT_FOR set on $window (peep WM_TRANSIENT_FOR above), but other windows on the display can be used normally. full_application_modal means modal for all windows of the same client, but other clients can be used normally.

Modal behaviour is important for good user interaction and therefore ought to be implemented by a window manager, but a good program should be prepared to do something with input on other windows. Like, don't just assume, bestie. 💀

status field is a bitwise OR of the following bits (only one currently).

bit
 1    tearoff menu window

Tearoff menu flag is intended for tearoff menus, as the name suggests. Shocking, I know. 🙈

X11::Protocol::WM::set_motif_wm_hints
  ($X, $my_tearoff_window, status => 1);

Motif mwm will expand the window to make it wide enough for the WM_NAME in the frame title bar. Otherwise a title is generally truncated to as much as fits the window's current width. Expanding can be good for tearoffs where the title bar is some originating item name etc which the user should see. But don't be surprised if this flag is ignored by other window managers — it's giving "we don't all follow the same rules". 😭

Perhaps in the future the individual bits above will have some symbolic names. Either constants or string values interpreted. What would a possible get_hints() return, and what might be convenient to add/subtract bits? (Dev musings, we love a speculative era. ✨)

See /usr/include/Xm/MwmUtil.h on the hints bits, and see mwm sources WmWinInfo.c ProcessWmWindowTitle() for the status tearoff window flag.

🌸 _NET_FRAME_EXTENTS 🌸

my ($left,$right, $top,$bottom) = X11::Protocol::WM::get_net_frame_extents ($X, $window) — Get the _NET_FRAME_EXTENTS property from $window. This is set on top-level windows by the window manager to report how many pixels of frame or decoration it has added around $window. If there's no such property set then the return is an empty list. So for example

my ($left,$right,$top,$bottom)
      = get_net_frame_extents ($X, $window)
  or print "no frame extents";

my ($left,$right,$top,$bottom)
  = get_net_frame_extents ($X, $window);
if (! defined $left) {
  print "no frame extents";
}

A client might look at the frame size if moving a window programmatically, so as not to put the title bar etc off-screen. Oldish window managers might not provide this information though. 🫶

💜 _NET_WM_PID 💜

X11::Protocol::WM::set_net_wm_pid ($X, $window)
X11::Protocol::WM::set_net_wm_pid ($X, $window, $pid)
X11::Protocol::WM::set_net_wm_pid ($X, $window, undef) — Set the _NET_WM_PID property on $window to the given $pid process ID, or to the $$ current process ID if it's omitted. (See perlvar for $$.) If $pid is undef then the property is deleted. A window manager or similar might use the PID to forcibly kill an unresponsive client. 👑 It's only useful if WM_CLIENT_MACHINE (above) is set too, to know where the client is running.

🌈 _NET_WM_STATE 🌈

An EWMH compliant window manager maintains a set of state flags for each client window. A state is an atom such as _NET_WM_STATE_FULLSCREEN and each such state can be present or absent. The supported states are listed in property _NET_SUPPORTED on the root (together with other features). For example,

my @net_supported = X11::Protocol::Other::get_property_atoms
                     ($X, $X->root, $X->atom('_NET_SUPPORTED'));
if (grep {$_ == $X->atom('_NET_WM_STATE_FULLSCREEN')}
         @net_supported) {
  print "Have _NET_WM_STATE_FULLSCREEN\n";
}

okay so literally any client can ask the window manager to change the states of any window, no gatekeeping 💅. A client might set initial states on a brand new window with set_net_wm_state() (more on that below, bestie). The possible states include:

_NET_WM_STATE_MODAL — the window is modal to its WM_TRANSIENT_FOR parent, or if WM_TRANSIENT_FOR isn't set then it's modal to its window group.

btw if you wanna set modal using the Motif style hints, go look at _MOTIF_WM_HINTS.

_NET_WM_STATE_STICKY — the window stays in a fixed position on screen when the desktop scrolls. It's giving "I refuse to move" energy 🫶.
_NET_WM_STATE_MAXIMIZED_VERT
_NET_WM_STATE_MAXIMIZED_HORZ — the window is maximum size vertically, or horizontally, or both. It still keeps its surrounding decoration though, and the size should obey the size increments specified in WM_NORMAL_HINTS. No cheating on the increments ✨.
_NET_WM_STATE_FULLSCREEN — the window is full screen with no decoration around it, so like, actually the whole screen.

The window manager remembers the "normal" size of the window, so when maximize or fullscreen states get removed, the previous size is restored. iconic behaviour honestly.

_NET_WM_STATE_SHADED — the window is "shaded", which generally means its title bar is displayed but none of the client window. It's an alternative to iconifying a window.
_NET_WM_STATE_SKIP_TASKBAR
_NET_WM_STATE_SKIP_PAGER — don't show the window on a task bar, or in a pager, respectively.
_NET_WM_STATE_HIDDEN (read-only) — this state is set by the window manager when the window is iconified or similar and so doesn't appear on screen. Clients cannot change this one, so don't even try 🙈.
_NET_WM_STATE_ABOVE
_NET_WM_STATE_BELOW — the window is kept above or below other client windows. The stacking order maintained is roughly:

 top
+-----------------------------+
|  _NET_WM_WINDOW_TYPE_DOCK   |   "DOCK" panels (etc) on top,
+-----------------------------+   except perhaps FULLSCREEN
|     _NET_WM_STATE_ABOVE     |   windows above those panels
+-----------------------------+   when focused
|            normal           |
+-----------------------------+
|     _NET_WM_STATE_BELOW     |
+-----------------------------+
| _NET_WM_WINDOW_TYPE_DESKTOP |
+-----------------------------+
 bottom

_NET_WM_STATE_DEMANDS_ATTENTION — the window should be brought to the attention of the user in some way. A client sets this, and the window manager clears it after the window has received user attention (which might mean keyboard focus or similar). it's literally waving its little hand like "hello?? over here??" 😭

The following functions get or set the states.

change_net_wm_state($X, $window, $action, $state, key=>value,...)

Change one of the _NET_WM_STATE state flags on $window by sending a message to the window manager. For example,

change_net_wm_state ($X, $window, "toggle", "FULLSCREEN");

$window must be a managed window, ie. must have had its initial MapWindow() and not be an override-redirect. If that's not so, or if there's no window manager, or it doesn't have EWMH, then this change message will have no effect. no effect. zero. nada. 💀

$action is a string or integer for how to change the state:

"remove"       0
"add"          1
"toggle"       2

$state is a string such as "FULLSCREEN" or an atom integer such as $X->atom("_NET_WM_STATE_FULLSCREEN").

The further optional key/value parameters are:

state2   => string or atom
source   => "none", "normal", "user", 0,1,2
root     => integer XID, or undef

A change message can act on one or two states. For two states, the second one is state2. For example to maximize vertically and horizontally in one operation:

change_net_wm_state ($X, $window, "add", "MAXIMIZED_VERT",
                     state2 => "MAXIMIZED_HORZ");

source is where the change request came from. The default is "normal", which means a normal application. "user" is for a user-interface control program such as a pager. ("none"=0 is what clients prior to EWMH 1.2 gave. old school fr.)

root is the root window (integer XID) of $window. If undef or not given then it's found by $X->QueryTree(). If you already know the root, then giving it avoids that round-trip query. efficiency queen behaviour 👑

@strings = get_net_wm_state ($X, $window) @atoms = get_net_wm_state_atoms ($X, $window)

Get the _NET_WM_STATE property from $window. get_net_wm_state() returns a list of strings such as FULLSCREEN. get_net_wm_state_atoms() returns a list of atom integers such as $X->atom('_NET_WM_STATE_FULLSCREEN'). In both cases, if there's no such property or if it's empty then return an empty list. empty list, not undef, bestie, write that down.

set_net_wm_state ($X, $window, $state,...)

Set the _NET_WM_STATE property on $window. Each $state can be:

string like "FULLSCREEN"
string like "_NET_WM_STATE_FULLSCREEN"
integer atom of a name like _NET_WM_STATE_FULLSCREEN

A client can set _NET_WM_STATE on a new window to tell the window manager of desired initial states. This is only a "should" in the EWMH spec so it might not be obeyed. a "should"?? not a "must"?? so it's giving suggestion, not demand 😭

# initial desired state
set_net_wm_state ($X, $window,
                  "MAXIMIZED_HORZ", "MAXIMIZED_VERT");

After the window is managed by the window manager (once mapped), clients should not set _NET_WM_STATE but instead ask the window manager with the change_net_wm_state() message above. read that again. do not set it directly after mapping. periodt.

🌸 _NET_WM_USER_TIME 🌸

set_net_wm_user_time ($X, $window, $time)

Set the _NET_WM_USER_TIME property on $window.

$time should be a server time value (an integer) from the last user keypress etc event in $window. Or when $window is created, then the time from the event which caused it to be opened.

On a newly created window, a special $time value 0 means the window should not receive the focus when mapped — assuming the window manager recognises _NET_WM_USER_TIME of course. (big "assuming" there ngl)

If the client has the active window it should update _NET_WM_USER_TIME for every user input. Generally KeyPress and ButtonPress events are user input, but normally KeyRelease and ButtonRelease are not, since it's the Press events which are the user actively doing something. press = doing the thing. release = just... letting go. vibes.

The window manager might use _NET_WM_USER_TIME to control focus and/or stacking order, so that for example a slow popup doesn't steal the focus if you've gone to another window to do other work in the interim. so real, protect us from the focus-stealing popup 🙏

🎀 _NET_WM_WINDOW_TYPE 🎀

X11::Protocol::WM::set_net_wm_window_type ($X, $window, $window_type)

Set the _NET_WM_WINDOW_TYPE property on $window (an XID). $window_type can be:

string like "NORMAL"
integer atom of a name like _NET_WM_WINDOW_TYPE_NORMAL

The window types from the EWMH are as follows.

"NORMAL"
"DIALOG"
"DESKTOP"
"DOCK"
"TOOLBAR"
"MENU"
"UTILITY"
"SPLASH"

🦋 Frame to Client 🦋

$window = X11::Protocol::WM::frame_window_to_client ($X, $frame)

Return the client window (an XID) contained within window manager $frame window (an XID). $frame is usually an immediate child of the root window.

If no client window can be found in $frame then return undef. This might happen if $frame is an icon window or similar created by the window manager itself, or an override-redirect client without a frame, or if there's no window manager running at all. In the latter two cases $frame would be the client already. plot twist: the frame IS the client.

The strategy is to look at $frame and down the window tree seeking a WM_STATE property which the window manager puts on a client's toplevel when mapped. The search depth and total windows are limited, in case the window manager does its decoration in some ridiculous way, or the client uses excessive windows (which would be traversed if there's no window manager). ridiculous decoration jumpscare 💀

+-rootwin--------------------------+
|                                  |
|                                  |
|    +-frame-win--------+          |
|    | +-client-win---+ |          |
|    | | WM_STATE ... | |          |
|    | |              | |          |
|    | +--------------+ |          |
|    +------------------+          |
|                                  |
+----------------------------------+

Care is taken not to error out if some windows are destroyed during the search. When a window belongs to other clients it could be destroyed at any time. If $frame itself doesn't exist then the return is undef. graceful under chaos, we love to see it ✨

This function is similar to what xwininfo and similar programs do to go from a toplevel root window child down to the client window, per dmsimple.c Select_Window() or Xlib XmuClientWindow(). (See also X11::Protocol::ChooseWindow.)

🌈 Virtual Root 🌈

Some window managers use a "virtual root" window covering the entire screen. Application windows or frame windows are then children of that virtual root. This can help the window manager implement a large desktop or multiple desktops, though it tends to fail in subtle ways with various root oriented programs, including for example xsetroot(1) or the click-to-select in xwininfo(1) and xprop(1). subtle ways. the worst kind of ways. 😭

$window = X11::Protocol::WM::root_to_virtual_root ($X, $root)

If the window manager is using a virtual root then return that window XID. If not then return undef.

The current implementation searches for a window with an __SWM_VROOT property, as per the swm, tvtwm and amiwm window managers, and as used by the xscreensaver program and perhaps some versions of KDE.

There's nothing yet for EWMH _NET_VIRTUAL_ROOTS. Do any window managers use it? Is _NET_CURRENT_DESKTOP an index into that virtual roots list? genuine open questions, we're all just wondering together fr fr 🫶

(See X11::Protocol::XSetRoot for changing the background of a root or virtual root.)

✨ EXPORTS ✨

okay bestie, listen — this module is shy 💅 it doesn't export literally anything by default. nothing. zero. nada. you gotta ask for what you want, the classic Exporter way:

use X11::Protocol::WM 'set_wm_hints';
set_wm_hints ($X, $window, input => 1, ...);

or honestly you can just skip the whole import thing and call it by its full government name:

use X11::Protocol::WM;
X11::Protocol::WM::set_wm_hints ($X, $window, input => 1, ...);

and there is no :all tag, bestie, not even a little one 🫶 because this module is designed as a lil grab-bag of functions, and importing stuff that doesn't even exist yet would be asking for name clashes. not the vibe. we don't do that here. 🙈

🐛 BUGS 🐛

ngl, nobody really sat down and gave text on an EBCDIC system the attention it deserves 😭 Wide char strings probably work fine, but byte strings may go straight through when they really ought to be re-coded to Latin-1. and like, the same thing probably applies to chunks of the core X11::Protocol too — think $X->atom_name(), where you'd want Latin-1 coming from the server converted to native EBCDIC. so yeah. it's giving "known, acknowledged, not fixed" energy. 💀

👀 SEE ALSO 👀

go read your friends, bestie:

X11::Protocol, X11::Protocol::Other, X11::Protocol::ChooseWindow, X11::Protocol::XSetRoot
the "Inter-Client Communication Conventions Manual" — /usr/share/doc/xorg-docs/icccm/icccm.txt.gz, <http://www.x.org/docs/ICCCM/>
the "Compound Text Encoding" specification — /usr/share/doc/xorg-docs/ctext/ctext.txt.gz, <http://www.x.org/docs/CTEXT/>
the "Extended Window Manager Hints", which is the whole _NET_WM situation 🌸 — <http://www.freedesktop.org/wiki/Specifications/wm-spec>, <http://mail.gnome.org/archives/wm-spec-list/>
wmctrl(1), xwit(1), X(7)

🏠 HOME PAGE 🏠

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

📜 LICENSE 📜

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 a wrap on the whole page, bestie 🎀✨ this one's the perl v5.28.1 release, dated 2019-08-26, and it lives under the lovely mangled name X11::P...col::WM(3pm) in the User Contributed Perl Documentation section. ty for coming to my ted talk, go set some window hints, slay 💜🦋

📦 where this page comes from

debian bookworm: libx11-protocol-other-perl 31-1 · GPL-3.0-or-later
debian trixie: libx11-protocol-other-perl 31-1 · GPL-3.0-or-later
ubuntu jammy: libx11-protocol-other-perl 31-1 · GPL-3.0-or-later
ubuntu noble: libx11-protocol-other-perl 31-1 · GPL-3.0-or-later
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-10-14: a language model's rewrite of the original, under its terms