1X11::Protocol::WM(3) User Contributed Perl Documentation X11::Protocol::WM(3)
2
6 X11::Protocol::WM -- window manager things for client programs
7
9 use X11::Protocol::WM;
10
12 This is some window manager related functions for use by client
13 programs, as per the "Inter-Client Communication Conventions Manual"
14 and some of the Net-WM "Extended Window Manager Hints".
15 /usr/share/doc/xorg-docs/icccm/icccm.txt.gz
17 <http://www.freedesktop.org/wiki/Specifications/wm-spec>
19 Usual Properties
21 Every toplevel client window should usually
22 • set_wm_class() to identify itself to other programs (see "WM_CLASS"
24 below).
25 • set_wm_name() and set_wm_icon_name() for user-visible window name
27 (see "WM_NAME, WM_ICON_NAME" below).
28 • set_wm_client_machine_from_syshostname() and set_net_wm_pid() for
30 the running process (see "WM_CLIENT_MACHINE" and "_NET_WM_PID"
31 below).
32 Then optionally,
34 • If you have an icon then set_wm_hints() with a bitmap or a window
36 (see "WM_HINTS" below).
37 • If the user gave an initial size or position on the command line
39 then set_wm_normal_hints(). The same if the program has min/max
40 sizes or aspect ratio desired (see "WM_NORMAL_HINTS" below).
41 • If a command to re-run the program can be constructed then
43 set_wm_command(), and preferably keep that up-to-date with changes
44 such as currently open file etc (see "WM_COMMAND" below).
45
47 Text Properties
48 Property functions taking text strings such as set_wm_name() accept
49 either byte strings or wide char strings (Perl 5.8 up). Byte strings
50 are presumed to be Latin-1 and set as "STRING" type in properties.
51 Wide char strings are stored as "STRING" if entirely Latin-1, or
52 encoded to "COMPOUND_TEXT" for other chars (see Encode::X11).
53 In the future perhaps the string functions could accept some sort of
55 compound text object to represent segments of various encodings to
56 become "COMPOUND_TEXT", together with manipulations for such content
57 etc. If text is bytes in one of the ICCCM encodings then it might save
58 work to represent it directly as "COMPOUND_TEXT" segments rather than
59 going to wide chars and back again.
60 "set_text_property ($X, $window, $prop, $str)"
62 Set the given $prop (integer atom) property on $window (integer
63 XID) using either "STRING" or "COMPOUND_TEXT" as described above.
64 If $str is "undef" then $prop is deleted.
65 $str is limited to "$X->maximum_request_length()". In theory
67 longer strings can be stored by piecewise, but there's no attempt
68 to do that here. The maximum request limit is at least 16384 bytes
69 and the server may allow more, possibly much more.
70 WM_CLASS
72 "X11::Protocol::WM::set_wm_class ($X, $window, $instance, $class)"
73 Set the "WM_CLASS" property on $window (an XID).
74 This property may be used by the window manager to lookup settings
76 and preferences for the program through the X Resource system (see
77 "RESOURCES" in X(7)) or similar.
78 Usually the instance name is the program command such as "xterm"
80 and the class name something like "XTerm". Some programs have
81 command line options to set the class and/or instance so the user
82 can have different window manager settings applied to a particular
83 running copy of a program.
84 X11::Protocol::WM::set_wm_class ($X, $window,
86 "myprog", "MyProg");
87 $instance and $class must be ASCII or Latin-1 only. Wide-char
89 strings which are Latin-1 are converted as necessary.
90 WM_CLIENT_MACHINE
92 "X11::Protocol::WM::set_wm_client_machine ($X, $window, $hostname)"
93 Set the "WM_CLIENT_MACHINE" property on $window to $hostname (a
94 string).
95 $hostname should be the name of the client machine as seen from the
97 server. If $hostname is "undef" then the property is deleted.
98 Usually a machine name is ASCII-only, but anything per "Text
100 Properties" above is accepted.
101 "X11::Protocol::WM::set_wm_client_machine_from_syshostname ($X,
103 $window)"
104 Set the "WM_CLIENT_MACHINE" property on $window using the
105 Sys::Hostname module.
106 If "Sys::Hostname" can't determine a hostname by its various
108 gambits then currently the property is deleted. Would it be better
109 to leave it unchanged, or return a flag to say if set?
110 Some of the "Sys::Hostname" cases might return "localhost". That's
112 put through unchanged, on the assumption that it would be when
113 there's no networking beyond the local host so client and server
114 are on the same machine and name "localhost" suffices.
115 WM_COMMAND
117 "X11::Protocol::WM::set_wm_command ($X, $window, $command, $arg...)"
118 Set the "WM_COMMAND" property on $window (an XID).
119 This should be a program name and argument strings which will
121 restart the client. $command is the program name, followed by any
122 argument strings.
123 X11::Protocol::WM::set_wm_command ($X, $window,
125 'myprog',
126 '--option',
127 'filename.txt');
128 The command should start the client in its current state, so the
130 command might include a filename, command line options for current
131 settings, etc.
132 Non-ASCII is allowed per "Text Properties" above. The ICCCM spec
134 is for Latin-1 to work on a POSIX Latin-1 system, but how well
135 anything else survives a session manager etc is another matter.
136 A client can set this at any time, or if participating in the
138 "WM_SAVE_YOURSELF" session manager protocol then it should set in
139 response to a "ClientMessage" of "WM_SAVE_YOURSELF" .
140 For reference, under "mwm" circa 2017, a client with
142 "WM_SAVE_YOURSELF" receives that message for the "mwm" Close button
143 ("f.kill") and is expected to respond within a timeout (default 1
144 second), whereupon "mwm" closes the client connection
145 ("KillClient"). Unfortunately if both "WM_SAVE_YOURSELF" and
146 "WM_DELETE_WINDOW" then "mwm" still does the "WM_SAVE_YOURSELF" and
147 close, defeating the aim of letting "WM_DELETE_WINDOW" query the
148 user and perhaps not close.
149 The easiest workaround would be use only "WM_DELETE_WINDOW", keep
151 "WM_COMMAND" always up-to-date, and be prepared to save state on
152 connection loss. This is quite reasonable anyway actually, since a
153 "WM_SAVE_YOURSELF" message is fairly limited use, given that
154 connection loss or other termination could happen at any time so if
155 state is important that it'd be prudent to keep it saved.
156 WM_ICON_SIZE
158 "($min_width,$min_height, $max_width,$max_height,
159 $width_inc,$height_inc) =
160 X11::Protocol::WM::get_wm_icon_size($X,$root)"
161 Return the window manager's "WM_ICON_SIZE" recommended icon sizes
162 (in pixels) as a range, and increment above the minimum. If
163 there's no "WM_ICON_SIZE" property then return an empty list.
164 $root is the root window to read. If omitted then read the
166 "$X->root" default.
167 An icon pixmap or window in "WM_HINTS" should be a size in this
169 range. Many window managers don't set a preferred icon size.
170 32x32 might be typical on a small screen or 48x48 on a bigger
171 screen.
172 WM_HINTS
174 "X11::Protocol::WM::set_wm_hints ($X, $window, key=>value, ...)"
175 Set the "WM_HINTS" property on $window (an XID). For example,
176 X11::Protocol::WM::set_wm_hints
178 ($X, $my_window,
179 input => 1,
180 initial_state => 'NormalState',
181 icon_pixmap => $my_pixmap);
182 The key/value parameters are as follows.
184 input integer 0 or 1
186 initial_state enum string or number
187 icon_pixmap pixmap (XID integer), depth 1
188 icon_window window (XID integer)
189 icon_x \ integer coordinate
190 icon_y / integer coordinate
191 icon_mask pixmap (XID integer)
192 window_group window (XID integer)
193 urgency boolean
194 "input" is 1 if the client wants the window manager to give $window
196 the keyboard input focus. This will be with "$X->SetInputFocus()",
197 or if "WM_TAKE_FOCUS" is in "WM_PROTOCOLS" then instead by a
198 "ClientMessage".
199 "input" is 0 if the window manager should not give the client the
201 focus. This is either because $window is output-only, or if
202 "WM_TAKE_FOCUS" is in "WM_PROTOCOLS" then because the client will
203 do a SetInputFocus() to itself on an appropriate button press etc.
204 "initial_state" is a string or number. The ICCCM allows
206 "NormalState" or "IconicState" as initial states.
207 "NormalState" 1
209 "IconicState" 3
210 "icon_pixmap" should be a bitmap, ie. a pixmap (XID) with depth 1.
212 The window manager will draw it in suitable contrasting colours.
213 "1" pixels are foreground and "0" is background. "icon_mask"
214 bitmap is applied to the displayed icon. It can be used to make a
215 non-rectangular icon.
216 "icon_window" is a window which the window manager may show when
218 $window is iconified. This can be used for a multi-colour icon,
219 done either by a background or by client drawing (in response to
220 "Expose" events, or updated periodically for a clock, etc). The
221 "icon_window" should be a child of the root and should use the
222 default visual and colormap of the screen. The window manager
223 might resize the window and/or border.
224 The window manager might set a "WM_ICON_SIZE" property on the root
226 window for good icon sizes. See "WM_ICON_SIZE" above.
227 "window_group" is the XID of a window which is the group leader of
229 a group of top-level windows being used by the client. The window
230 manager might provide a way to manipulate the group as a whole, for
231 example to iconify it all. If iconified then the icon hints of the
232 leader are used for the icon. The group leader can be an unmapped
233 window. It can be convenient to use a never-mapped window as the
234 leader for all subsequent windows.
235 "urgency" true means the window is important and the window manager
237 should draw the user's attention to it in some way. The client can
238 change this hint at any time to change the current importance.
239 "(key => $value, ...) = X11::Protocol::WM::get_wm_hints ($X, $window)"
241 Return the "WM_HINTS" property from $window. The return is a list
242 of key/value pairs as per set_wm_hints() above
243 input => 1,
245 icon_pixmap => 1234,
246 ...
247 Only fields with their flag bits set in the hints are included in
249 the return. If there's no "WM_HINTS" at all or or its flags field
250 is zero then the return is an empty list.
251 The return can be put into a hash to get fields by name,
253 my %hints = X11::Protocol::WM::get_wm_hints ($X, $window);
255 if (exists $hints{'icon_pixmap'}) {
256 print "icon_pixmap is ", $hints{'icon_pixmap'}, "\n";
257 }
258 "initial_state" is a string such as "NormalState". The pixmaps and
260 windows are string "None" if set but zero (which is probably
261 unusual). If "$X->{'do_interp'}" is disabled then all are numbers.
262 X11R2 Xlib had a bug in its XSetWMHints() which chopped off the
264 "window_group" value from the hints stored. The "window_group"
265 field is omitted from the return if the data read is missing that
266 field.
267 "(key => $value, ...) = X11::Protocol::WM::change_wm_hints ($X,
269 $window, key=>value, ...)"
270 Change some fields of the "WM_HINTS" property on $window. The
271 given key/value fields are changed. Other fields are left alone.
272 For example,
273 X11::Protocol::WM::set_wm_hints ($X, $window,
275 urgency => 1);
276 A value "undef" means delete a field,
278 X11::Protocol::WM::set_wm_hints ($X, $window,
280 icon_pixmap => undef,
281 icon_mask => undef);
282 The change requires a server round-trip to fetch the current values
284 from $window. An application might prefer to remember its desired
285 hints and send a full set_wm_hints() each time.
286 "$bytes = X11::Protocol::WM::pack_wm_hints ($X, key=>value...)"
288 Pack a set of values into a byte string of "WM_HINTS" format. The
289 key/value arguments are per set_wm_hints() above and the result is
290 the raw bytes stored in a "WM_HINTS" property.
291 The $X argument is not actually used currently, but is present in
293 case "initial_state" or other values might use an "$X->num()"
294 lookup in the future.
295 "(key => $value, ...) = X11::Protocol::WM::unpack_wm_hints ($X,
297 $bytes)"
298 Unpack a byte string as a "WM_HINTS" structure. The return is
299 key/value pairs as per get_wm_hints() above. The $X parameter is
300 used for "do_interp". There's no communication with the server.
301 WM_NAME, WM_ICON_NAME
303 "X11::Protocol::WM::set_wm_name ($X, $window, $name)"
304 Set the "WM_NAME" property on $window (an integer XID) to $name (a
305 string).
306 The window manager might display this as a title above the window,
308 or in a menu of windows, etc. It can be a Perl 5.8 wide-char
309 string per "Text Properties" above. A good window manager ought to
310 support non-ASCII or non-Latin-1 titles, but how well it displays
311 might depend on fonts etc.
312 "X11::Protocol::WM::set_wm_icon_name ($X, $window, $name)"
314 Set the "WM_ICON_NAME" property on $window (an integer XID) to
315 $name (a string).
316 The window manager might display this when $window is iconified.
318 If $window doesn't have an icon (in "WM_HINTS" or from the window
319 manager itself) then this text might be all that's shown. Either
320 way it should be something short. It can be a Perl 5.8 wide-char
321 string per "Text Properties" above.
322 WM_NORMAL_HINTS
324 "X11::Protocol::WM::set_wm_normal_hints ($X, $window, key=>value,...)"
325 Set the "WM_NORMAL_HINTS" property on $window (an integer XID).
326 This is a "WM_SIZE_HINTS" structure which tells the window manager
327 what sizes the client would like. For example,
328 set_wm_normal_hints ($X, $window,
330 min_width => 200,
331 min_height => 100);
332 Generally the window manager restricts user resizing to the hint
334 limits. Most window managers use these hints, but of course
335 they're only hints and a good program should be prepared for other
336 sizes even if it won't look good or can't do much useful when too
337 big or too small etc.
338 The key/value parameters are
340 user_position boolean, window x,y is user specified
342 user_size boolean, window width,height is user specified
343 program_position boolean, window x,y is program specified
344 program_size boolean, window width,height is program specified
345 min_width \ integers, min size in pixels
346 min_height /
347 max_width \ integers, max size in pixels
348 max_height /
349 base_width \ integers, size base in pixels
350 base_height /
351 width_inc \ integers, size increment in pixels
352 height_inc /
353 min_aspect \ fraction 2/3 or decimal 2 or 1.5
354 min_aspect_num | or integer num/den up to 0x7FFFFFFF
355 min_aspect_den |
356 max_aspect |
357 max_aspect_num |
358 max_aspect_den /
359 win_gravity WinGravity enum "NorthEast" etc
360 "user_position" and "user_size" are flags meaning that the window's
362 x,y or width,height (in the usual core "$X->SetWindowAttributes()")
363 were given by the user, for example from a "-geometry" command line
364 option. The window manager will generally obey these values and
365 skip any auto-placement or interactive placement it might otherwise
366 do.
367 "program_position" and "program_size" are flags meaning the window
369 x,y or width,height were calculated by the program. The window
370 manager might override with its own positioning or sizing policy.
371 There's generally no need to set these fields unless the program
372 has a definite idea of where and how big it should be. For a size
373 it's enough to set the core window width,height and let the window
374 manager (if there's one running) go from there.
375 Items shown grouped above must be given together, so for instance
377 if a "min_width" is given then "min_height" should be given too.
378 "base_width","base_height" and "width_inc","height_inc" ask that
380 the window be a certain base size in pixels then a multiple of
381 "inc" pixels above that. This can be used by things like "xterm"
382 which want a fixed size for border or scrollbar and then a multiple
383 of the character size above that. If "base_width","base_height"
384 are not given then "min_width","min_height" is the base size.
385 "base_width","base_height" can be smaller than
387 "min_width","min_height". This means the size should still be a
388 base+inc multiple, but the first such which is at least the min
389 size. The window manager generally presents the "inc" multiple to
390 the user, so that for example on an xterm the user sees a count of
391 characters. A min size can then demand for example a minimum 1x1
392 or 2x2 character size.
393 "min_aspect","max_aspect" ask that the window have a certain
395 minimum or maximum width/height ratio. For example aspect 2/1
396 means it should be twice as wide as it is high. This is applied to
397 the size above "base_width","base_height", or if base not given
398 then to the whole window size.
399 "min_aspect_num","min_aspect_den" and
401 "max_aspect_num","max_aspect_den" set numerator and denominator
402 values directly (INT32, so maximum 0x7FFF_FFFF). Or "min_aspect"
403 and "max_aspect" accept a single value in various forms which are
404 turned into num/den values.
405 2 integer
407 1.125 decimal, meaning 1125/1000
408 2/3 fraction
409 1.5/4.5 fraction with decimals
410 Values bigger than 0x7FFFFFFF in these forms are reduced
412 proportionally as necessary. A Perl floating point value will
413 usually have more bits of precision than 0x7FFFFFFF and is
414 truncated to something that fits.
415 "win_gravity" is how the client would like to be shifted to make
417 room for any surrounding frame the window manager might add. For
418 example if the program calculated the window size and position to
419 ensure the north-east corner is at a desired position, then give
420 "win_gravity => "NorthEast"" so that the window manager keeps the
421 north-east corner the same when it applies its frame.
422 "win_gravity => "Static"" means the frame is put around the window
424 and the window not moved at all. Of course that might mean some of
425 the frame ends up off-screen.
426 "$bytes = X11::Protocol::WM::pack_size_hints ($X, key=>value,...)"
428 Return a bytes string which is a "WM_SIZE_HINTS" structure made
429 from the given key/value parameters. "WM_SIZE_HINTS" is structure
430 type for "WM_NORMAL_HINTS" described above and the key/value
431 parameters are as described above.
432 The $X parameter is used to interpret "win_gravity" enum values.
434 There's no communication with the server.
435 "($num,$den) = X11::Protocol::WM::aspect_to_num_den ($aspect)"
437 Return a pair of INT32 integers 0 to 0x7FFF_FFFF for the given
438 aspect ratio $aspect. This is the conversion applied to
439 "min_aspect" and "max_aspect" above. $aspect can be any of the
440 integer, decimal or fraction described.
441 WM_PROTOCOLS
443 "X11::Protocol::WM::set_wm_protocols ($X, $window, $protocol,...)"
444 Set the "WM_PROTOCOLS" property on $window (an XID). Each argument
445 is a string protocol name or an integer atom ID.
446 X11::Protocol::WM::set_wm_protocols
448 ($X, $window, 'WM_DELETE_WINDOW', '_NET_WM_PING')
449 For example "WM_DELETE_WINDOW" means that when the user clicks the
451 close button the window manager sends a "ClientMessage" event
452 rather than doing a KillClient(). The "ClientMessage" event allows
453 a program to clean-up or ask the user about saving a document
454 before exiting, etc.
455 WM_STATE
457 The window manager maintains a state for each client window it manages,
458 WithdrawnState
460 NormalState
461 IconicState
462 "WithdrawnState" means the window is not mapped and the window manager
464 is not managing it. A newly created window ("$X->CreateWindow()") is
465 initially "WithdrawnState" and on first "$X->MapWindow()" goes to
466 "NormalState" (or to "IconicState" if that's the initial state asked
467 for in "WM_HINTS").
468 iconify() and withdraw() below can change the state to iconic or
470 withdrawn. A window can be restored from iconic to normal by a
471 MapWindow().
472 "($state, $icon_window) = X11::Protocol::WM::get_wm_state ($X,
474 $window)"
475 Return the "WM_STATE" property from $window. This is set by the
476 window manager on top-level application windows. If there's no
477 such property then the return is an empty list.
478 $state returned is an enum string, or an integer value if
480 "$X->{'do_interp'}" is disabled or the value unrecognised.
481 "WithdrawnState" 0 not displayed
483 "NormalState" 1 window displayed
484 "IconicState" 3 iconified in some way
485 "ZoomState" 2 \ no longer in ICCCM
487 "InactiveState" 4 / (zoom meant maximized)
488 $icon_window returned is the window (integer XID) used by the
490 window manager to display an icon of $window. If there's no such
491 window then $icon_window is "None" (or 0 if "$X->{'do_interp'}" is
492 disabled).
493 $icon_window might be the icon window from the client's "WM_HINTS"
495 or it might be a window created by the window manager. The client
496 can draw into it for animations etc, perhaps selecting "Expose"
497 events on it to know when to redraw.
498 "WM_STATE" is set by the window manager when a toplevel window is
500 first mapped (or perhaps earlier), and then kept up-to-date.
501 Generally no "WM_STATE" property or a "WM_STATE" set to
502 WithdrawnState means the window manager is not managing the window,
503 or not yet doing so. A client can select "PropertyChange" event
504 mask in the usual way to listen for "WM_STATE" changes.
505 "($state, $icon_window) = X11::Protocol::WM::unpack_wm_state ($X,
507 $bytes)"
508 Unpack the bytes of a "WM_STATE" property to a $state and
509 $icon_window as per get_wm_state() above.
510 $X is used for "$X->{'do_interp'}" but there's no communication
512 with the server.
513 "X11::Protocol::WM::iconify ($X, $window)"
515 "X11::Protocol::WM::iconify ($X, $window, $root)"
516 Change $window to "IconicState" by sending a "ClientMessage" to the
517 window manager.
518 If the window manager does not have any iconification then it might
520 do nothing (eg. some tiling window managers). If there's no window
521 manager running then iconification is not possible and this message
522 will do nothing.
523 $root should be the root window of $window. If not given or
525 "undef" then it's obtained by a QueryTree() here. Any client can
526 iconify any top level window.
527 If $window has other windows which are "WM_TRANSIENT_FOR" for it
529 then generally the window manager will iconify or hide those
530 windows too (see "WM_TRANSIENT_FOR" below).
531 "X11::Protocol::WM::withdraw ($X, $window)"
533 "X11::Protocol::WM::withdraw ($X, $window, $root)"
534 Change $window to "WithdrawnState" by an "$X->UnmapWindow()" and a
535 synthetic "UnmapNotify" message to the window manager.
536 If there's no window manager running then the UnmapWindow() unmaps
538 and the "UnmapNotify" message does nothing.
539 $root should be the root window of $window. If not given or
541 "undef" then it's obtained by a QueryTree() here.
542 If other windows are "WM_TRANSIENT_FOR" this $window (eg. open
544 dialog windows) then generally the client should withdraw them too.
545 The window manager might make such other windows inaccessible
546 anyway.
547 The ICCCM specifies an "UnmapNotify" message so the window manager
549 is notified of the desired state change even if $window is already
550 unmapped, such as in "IconicState" or perhaps during some window
551 manager reparenting, etc.
552 $window can be changed back to NormalState or IconicState later
554 with "$X->MapWindow()" the same as for a newly created window.
555 (And "WM_HINTS" "initial_state" can give a desired initial
556 iconic/normal state). But before doing so be sure the window
557 manager has recognised the withdraw(). This will be when the
558 window manager changes the "WM_STATE" property to "WithdrawnState",
559 or deletes that property.
560 Any client can withdraw any toplevel window, but it's unusual for a
562 client to withdraw windows which are not its own.
563 WM_TRANSIENT_FOR
565 "X11::Protocol::WM::set_wm_transient_for ($X, $window, $transient_for)"
566 Set the "WM_TRANSIENT_FOR" property on $window (an XID).
567 $transient_for is another window XID, or "undef" if $window is not
569 transient for anything so "WM_TRANSIENT_FOR" should be deleted.
570 "Transient for" means $window is some sort of dialog or menu
572 related to the given $transient_for window. The window manager
573 will generally iconify $window together with its $transient_for,
574 etc. See set_motif_wm_hints() below for "modal" transients.
575 _MOTIF_WM_HINTS
577 "X11::Protocol::WM::set_motif_wm_hints ($X, $window, key=>value...)"
578 Set the "MOTIF_WM_HINTS" property on $window (an XID).
579 These hints control window decorations and "modal" state. It
581 originated in the Motif "mwm" window manager but is recognised by
582 most other window managers. It should be set on a toplevel window
583 before mapping. Changes made later might not affect what the
584 window manager does.
585 X11::Protocol::WM::set_motif_wm_hints
587 ($X, $dialog_window,
588 input_mode => "full_application_modal");
589 $X->MapWindow ($dialog_window);
590 Ordinary windows generally don't need to restrict their decorations
592 etc, but something special like a clock or gadget might benefit.
593 X11::Protocol::WM::set_motif_wm_hints
595 ($X, $my_gadget_window,
596 functions => 4+32, # move+close
597 decorations => 1+4+8); # border+title+menu
598 The key/value arguments are
600 functions => integer bits
602 decorations => integer bits
603 input_mode => enum string or integer
604 status => integer bits
605 "functions" is what actions the window manager should offer to the
607 user in a drop-down menu or similar. It's an integer bitwise OR of
608 the following values. If not given then the default is normally
609 all functions.
610 bit actions offered
612 --- ---------------
613 1 all functions
614 2 resize window
615 4 move window
616 8 minimize, to iconify
617 16 maximize, to full-screen (with a frame still)
618 32 close window
619 "decorations" is what visual decorations the window manager should
621 show around the window. It's an integer bitwise OR of the
622 following values. If not given then the default is normally all
623 decorations.
624 bit decorations displayed
626 --- ---------------------
627 1 all decorations
628 2 border around the window
629 4 resizeh, handles to resize by dragging
630 8 title bar, showing WM_NAME
631 16 menu, drop-down menu of the "functions" above
632 32 minimize button, to iconify
633 64 maximize button, to full-screen
634 "input_mode" allows a window to be "modal", meaning the user should
636 interact only with $window. The window manager will generally keep
637 it on top, not move the focus to other windows, etc. The value is
638 one of the following strings or corresponding integer,
639 string integer
641 "modeless" 0 not modal (the default)
642 "primary_application_modal" 1 modal to its "transient for"
643 "system_modal" 2 modal to the whole display
644 "full_application_modal" 3 modal to the current client
645 "primary_application_modal" means $window is modal for the
647 "WM_TRANSIENT_FOR" set on $window (see "WM_TRANSIENT_FOR" above),
648 but other windows on the display can be used normally.
649 "full_application_modal" means modal for all windows of the same
650 client, but other clients can be used normally.
651 Modal behaviour is important for good user interaction and
653 therefore ought to be implemented by a window manager, but a good
654 program should be prepared to do something with input on other
655 windows.
656 "status" field is a bitwise OR of the following bits (only one
658 currently).
659 bit
661 1 tearoff menu window
662 Tearoff menu flag is intended for tearoff menus, as the name
664 suggests.
665 X11::Protocol::WM::set_motif_wm_hints
667 ($X, $my_tearoff_window, status => 1);
668 Motif "mwm" will expand the window to make it wide enough for the
670 "WM_NAME" in the frame title bar. Otherwise a title is generally
671 truncated to as much as fits the window's current width. Expanding
672 can be good for tearoffs where the title bar is some originating
673 item name etc which the user should see. But don't be surprised if
674 this flag is ignored by other window managers.
675 Perhaps in the future the individual bits above will have some
677 symbolic names. Either constants or string values interpreted.
678 What would a possible get_hints() return, and what might be
679 convenient to add/subtract bits?
680 See /usr/include/Xm/MwmUtil.h on the hints bits, and see "mwm"
682 sources WmWinInfo.c ProcessWmWindowTitle() for the "status" tearoff
683 window flag.
684 _NET_FRAME_EXTENTS
686 "my ($left,$right, $top,$bottom) =
687 X11::Protocol::WM::get_net_frame_extents ($X, $window)"
688 Get the "_NET_FRAME_EXTENTS" property from $window.
689 This is set on top-level windows by the window manager to report
691 how many pixels of frame or decoration it has added around $window.
692 If there's no such property set then the return is an empty list.
694 So for example
695 my ($left,$right,$top,$bottom)
697 = get_net_frame_extents ($X, $window)
698 or print "no frame extents";
699 my ($left,$right,$top,$bottom)
701 = get_net_frame_extents ($X, $window);
702 if (! defined $left) {
703 print "no frame extents";
704 }
705 A client might look at the frame size if moving a window
707 programmatically so as not to put the title bar etc off-screen.
708 Oldish window managers might not provide this information though.
709 _NET_WM_PID
711 "X11::Protocol::WM::set_net_wm_pid ($X, $window)"
712 "X11::Protocol::WM::set_net_wm_pid ($X, $window, $pid)"
713 "X11::Protocol::WM::set_net_wm_pid ($X, $window, undef)"
714 Set the "_NET_WM_PID" property on $window to the given $pid process
715 ID, or to the $$ current process ID if omitted. (See perlvar for
716 $$.) If $pid is "undef" then the property is deleted.
717 A window manager or similar might use the PID to forcibly kill an
719 unresponsive client. It's only useful if "WM_CLIENT_MACHINE"
720 (above) is set too, to know where the client is running.
721 _NET_WM_STATE
723 An EWMH compliant window manager maintains a set of state flags for
724 each client window. A state is an atom such as
725 "_NET_WM_STATE_FULLSCREEN" and each such state can be present or
726 absent. The supported states are listed in property "_NET_SUPPORTED"
727 on the root (together with other features). For example,
728 my @net_supported = X11::Protocol::Other::get_property_atoms
730 ($X, $X->root, $X->atom('_NET_SUPPORTED'));
731 if (grep {$_ == $X->atom('_NET_WM_STATE_FULLSCREEN')}
732 @net_supported) {
733 print "Have _NET_WM_STATE_FULLSCREEN\n";
734 }
735 Any client can ask the window manager to change states of any window.
737 A client might set initial states on a new window with
738 set_net_wm_state() below. Possible states include
739 _NET_WM_STATE_MODAL
741 The window is modal to its "WM_TRANSIENT_FOR" parent, or if
742 "WM_TRANSIENT_FOR" not set then modal to its window group.
743 See "_MOTIF_WM_HINTS" to set modal with the Motif style hints.
745 _NET_WM_STATE_STICKY
747 The window is kept in a fixed position on screen when the desktop
748 scrolls.
749 _NET_WM_STATE_MAXIMIZED_VERT
751 _NET_WM_STATE_MAXIMIZED_HORZ
752 The window is maximum size vertically or horizontally or both. The
753 window still has its surrounding decoration and the size should
754 obey size increments specified in "WM_NORMAL_HINTS".
755 _NET_WM_STATE_FULLSCREEN
757 The window is the full screen with no decoration around it, thus
758 being the full screen.
759 The window manager remembers the "normal" size of the window so
761 that when maximize or fullscreen states are removed the previous
762 size is restored.
763 _NET_WM_STATE_SHADED
765 The window is "shaded" which generally means its title bar is
766 displayed but none of the client window. This is an alternative to
767 iconifying a window.
768 _NET_WM_STATE_SKIP_TASKBAR
770 _NET_WM_STATE_SKIP_PAGER
771 Don't show the window on a task bar or in a pager, respectively.
772 _NET_WM_STATE_HIDDEN (read-only)
774 This state is set by the window manger when the window is iconified
775 or similar and so does not appear on screen. Clients cannot change
776 this.
777 _NET_WM_STATE_ABOVE
779 _NET_WM_STATE_BELOW
780 The window is kept above or below other client windows. The
781 stacking order maintained is roughly
782 top
784 +-----------------------------+
785 | _NET_WM_WINDOW_TYPE_DOCK | "DOCK" panels (etc) on top,
786 +-----------------------------+ except perhaps FULLSCREEN
787 | _NET_WM_STATE_ABOVE | windows above those panels
788 +-----------------------------+ when focused
789 | normal |
790 +-----------------------------+
791 | _NET_WM_STATE_BELOW |
792 +-----------------------------+
793 | _NET_WM_WINDOW_TYPE_DESKTOP |
794 +-----------------------------+
795 bottom
796 _NET_WM_STATE_DEMANDS_ATTENTION
798 The window should be brought to the attention of the user in some
799 way. A client sets this and the window manager clears it after the
800 window has received user attention (which might mean keyboard focus
801 or similar).
802 The following functions get or set the states.
804 "change_net_wm_state($X, $window, $action, $state, key=>value,...)"
806 Change one of the "_NET_WM_STATE" state flags on $window by sending
807 a message to the window manager. For example,
808 change_net_wm_state ($X, $window, "toggle", "FULLSCREEN");
810 $window must be a managed window, ie. must have had its initial
812 MapWindow() and not be an override-redirect. If that's not so or
813 if there's no window manager or it doesn't have EWMH then this
814 change message will have no effect.
815 $action is a string or integer how to change the state,
817 "remove" 0
819 "add" 1
820 "toggle" 2
821 $state is a string such as "FULLSCREEN" or an atom integer such as
823 "$X->atom("_NET_WM_STATE_FULLSCREEN")".
824 The further optional key/value parameters are
826 state2 => string or atom
828 source => "none", "normal", "user", 0,1,2
829 root => integer XID, or undef
830 A change message can act on one or two states. For two states, the
832 second is "state2". For example to maximize vertically and
833 horizontally in one operation,
834 change_net_wm_state ($X, $window, "add", "MAXIMIZED_VERT",
836 state2 => "MAXIMIZED_HORZ");
837 "source" is where the change request came from. The default is
839 "normal" which means a normal application. "user" is for a user-
840 interface control program such as a pager. ("none"=0 is what
841 clients prior to EWMH 1.2 gave.)
842 "root" is the root window (integer XID) of $window. If "undef" or
844 not given then it's found by "$X->QueryTree()". If you already
845 know the root then giving it avoids that round-trip query.
846 "@strings = get_net_wm_state ($X, $window)"
848 "@atoms = get_net_wm_state_atoms ($X, $window)"
849 Get the "_NET_WM_STATE" property from $window. get_net_wm_state()
850 returns a list of strings such as "FULLSCREEN".
851 get_net_wm_state_atoms() returns a list of atom integers such as
852 "$X->atom('_NET_WM_STATE_FULLSCREEN')". In both cases, if there's
853 no such property or if it's empty then return an empty list.
854 "set_net_wm_state ($X, $window, $state,...)"
856 Set the "_NET_WM_STATE" property on $window. Each $state can be
857 string like "FULLSCREEN"
859 string like "_NET_WM_STATE_FULLSCREEN"
860 integer atom of a name like _NET_WM_STATE_FULLSCREEN
861 A client can set "_NET_WM_STATE" on a new window to tell the window
863 manager of desired initial states. This is only a "should" in the
864 EWMH spec so it might not be obeyed.
865 # initial desired state
867 set_net_wm_state ($X, $window,
868 "MAXIMIZED_HORZ", "MAXIMIZED_VERT");
869 After the window is managed by the window manager (once mapped),
871 clients should not set "_NET_WM_STATE" but instead ask the window
872 manager with change_net_wm_state() message above.
873 _NET_WM_USER_TIME
875 "set_net_wm_user_time ($X, $window, $time)"
876 Set the "_NET_WM_USER_TIME" property on $window.
877 $time should be a server time value (an integer) from the last user
879 keypress etc event in $window. Or when $window is created then the
880 time from the event which caused it to be opened.
881 On a newly created window, a special $time value 0 means the window
883 should not receive the focus when mapped -- assuming the window
884 manager recognises "_NET_WM_USER_TIME" of course.
885 If the client has the active window it should update
887 "_NET_WM_USER_TIME" for every user input. Generally KeyPress and
888 ButtonPress events are user input, but normally KeyRelease and
889 ButtonRelease are not since it's the Press events which are the
890 user actively doing something.
891 The window manager might use "_NET_WM_USER_TIME" to control focus
893 and/or stacking order so that for example a slow popup doesn't
894 steal the focus if you've gone to another window to do other work
895 in the interim.
896 _NET_WM_WINDOW_TYPE
898 "X11::Protocol::WM::set_net_wm_window_type ($X, $window, $window_type)"
899 Set the "_NET_WM_WINDOW_TYPE" property on $window (an XID).
900 $window_type can be
901 string like "NORMAL"
903 integer atom of a name like _NET_WM_WINDOW_TYPE_NORMAL
904 The window types from from the EWMH are as follows.
906 "NORMAL"
908 "DIALOG"
909 "DESKTOP"
910 "DOCK"
911 "TOOLBAR"
912 "MENU"
913 "UTILITY"
914 "SPLASH"
915 Frame to Client
917 "$window = X11::Protocol::WM::frame_window_to_client ($X, $frame)"
918 Return the client window (an XID) contained within window manager
919 $frame window (an XID). $frame is usually an immediate child of
920 the root window.
921 If no client window can be found in $frame then return "undef".
923 This might happen if $frame is an icon window or similar created by
924 the window manager itself, or an override-redirect client without a
925 frame, or if there's no window manager running at all. In the
926 latter two cases $frame would be the client already.
927 The strategy is to look at $frame and down the window tree seeking
929 a "WM_STATE" property which the window manager puts on a client's
930 toplevel when mapped. The search depth and total windows are
931 limited in case the window manager does its decoration in some
932 ridiculous way or the client uses excessive windows (which would be
933 traversed if there's no window manager).
934 +-rootwin--------------------------+
936 | |
937 | |
938 | +-frame-win--------+ |
939 | | +-client-win---+ | |
940 | | | WM_STATE ... | | |
941 | | | | | |
942 | | +--------------+ | |
943 | +------------------+ |
944 | |
945 +----------------------------------+
946 Care is taken not to error out if some windows are destroyed during
948 the search. When a window belongs to other clients it could be
949 destroyed at any time. If $frame itself doesn't exist then the
950 return is "undef".
951 This function is similar to what "xwininfo" and similar programs do
953 to go from a toplevel root window child down to the client window,
954 per dmsimple.c Select_Window() or Xlib XmuClientWindow(). (See
955 also X11::Protocol::ChooseWindow.)
956 Virtual Root
958 Some window managers use a "virtual root" window covering the entire
959 screen. Application windows or frame windows are then children of that
960 virtual root. This can help the window manager implement a large
961 desktop or multiple desktops, though it tends to fail in subtle ways
962 with various root oriented programs, including for example xsetroot(1)
963 or the click-to-select in xwininfo(1) and xprop(1).
964 "$window = X11::Protocol::WM::root_to_virtual_root ($X, $root)"
966 If the window manager is using a virtual root then return that
967 window XID. If not then return "undef".
968 The current implementation searches for a window with an
970 "__SWM_VROOT" property, as per the "swm", "tvtwm" and "amiwm"
971 window managers, and as used by the "xscreensaver" program and
972 perhaps some versions of KDE.
973 There's nothing yet for EWMH "_NET_VIRTUAL_ROOTS". Do any window
975 managers use it? Is "_NET_CURRENT_DESKTOP" an index into that
976 virtual roots list?
977 (See X11::Protocol::XSetRoot for changing the background of a root
979 or virtual root.)
980
982 Nothing is exported by default, but the functions can be requested in
983 usual "Exporter" style,
984 use X11::Protocol::WM 'set_wm_hints';
986 set_wm_hints ($X, $window, input => 1, ...);
987 Or just call with full package name
989 use X11::Protocol::WM;
991 X11::Protocol::WM::set_wm_hints ($X, $window, input => 1, ...);
992 There's no ":all" tag since this module is meant as a grab-bag of
994 functions and to import as-yet unknown things would be asking for name
995 clashes.
996
998 Not much attention is paid to text on an EBCDIC system. Wide char
999 strings probably work, but byte strings may go straight through whereas
1000 they ought to be re-coded to Latin-1. But the same probably applies to
1001 parts of the core "X11::Protocol" such as "$X->atom_name()" where you'd
1002 want to convert Latin-1 from the server to native EBCDIC.
1003
1005 X11::Protocol, X11::Protocol::Other, X11::Protocol::ChooseWindow,
1006 X11::Protocol::XSetRoot
1007 "Inter-Client Communication Conventions Manual",
1009 /usr/share/doc/xorg-docs/icccm/icccm.txt.gz,
1010 <http://www.x.org/docs/ICCCM/>
1011 "Compound Text Encoding" specification.
1013 /usr/share/doc/xorg-docs/ctext/ctext.txt.gz,
1014 <http://www.x.org/docs/CTEXT/>
1015 "Extended Window Manager Hints" which is the "_NET_WM" things.
1017 <http://www.freedesktop.org/wiki/Specifications/wm-spec>,
1018 <http://mail.gnome.org/archives/wm-spec-list/>
1019 wmctrl(1), xwit(1), X(7)
1021
1023 <http://user42.tuxfamily.org/x11-protocol-other/index.html>
1024
1026 Copyright 2011, 2012, 2013, 2014, 2016, 2017, 2018, 2019 Kevin Ryde
1027 X11-Protocol-Other is free software; you can redistribute it and/or
1029 modify it under the terms of the GNU General Public License as
1030 published by the Free Software Foundation; either version 3, or (at
1031 your option) any later version.
1032 X11-Protocol-Other is distributed in the hope that it will be useful,
1034 but WITHOUT ANY WARRANTY; without even the implied warranty of
1035 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
1036 General Public License for more details.
1037 You should have received a copy of the GNU General Public License along
1039 with X11-Protocol-Other. If not, see <http://www.gnu.org/licenses/>.
1040perl v5.38.0 2023-07-21 X11::Protocol::WM(3)