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
24 "WM_CLASS" below).
25 • "set_wm_name()" and "set_wm_icon_name()" for user-visible window
27 name (see "WM_NAME, WM_ICON_NAME" below).
28 • "set_wm_client_machine_from_syshostname()" and "set_net_wm_pid()"
30 for 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
44 changes 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
204 etc.
205 "initial_state" is a string or number. The ICCCM allows
207 "NormalState" or "IconicState" as initial states.
208 "NormalState" 1
210 "IconicState" 3
211 "icon_pixmap" should be a bitmap, ie. a pixmap (XID) with depth 1.
213 The window manager will draw it in suitable contrasting colours.
214 "1" pixels are foreground and "0" is background. "icon_mask"
215 bitmap is applied to the displayed icon. It can be used to make a
216 non-rectangular icon.
217 "icon_window" is a window which the window manager may show when
219 $window is iconified. This can be used for a multi-colour icon,
220 done either by a background or by client drawing (in response to
221 "Expose" events, or updated periodically for a clock, etc). The
222 "icon_window" should be a child of the root and should use the
223 default visual and colormap of the screen. The window manager
224 might resize the window and/or border.
225 The window manager might set a "WM_ICON_SIZE" property on the root
227 window for good icon sizes. See "WM_ICON_SIZE" above.
228 "window_group" is the XID of a window which is the group leader of
230 a group of top-level windows being used by the client. The window
231 manager might provide a way to manipulate the group as a whole, for
232 example to iconify it all. If iconified then the icon hints of the
233 leader are used for the icon. The group leader can be an unmapped
234 window. It can be convenient to use a never-mapped window as the
235 leader for all subsequent windows.
236 "urgency" true means the window is important and the window manager
238 should draw the user's attention to it in some way. The client can
239 change this hint at any time to change the current importance.
240 "(key => $value, ...) = X11::Protocol::WM::get_wm_hints ($X, $window)"
242 Return the "WM_HINTS" property from $window. The return is a list
243 of key/value pairs as per "set_wm_hints()" above
244 input => 1,
246 icon_pixmap => 1234,
247 ...
248 Only fields with their flag bits set in the hints are included in
250 the return. If there's no "WM_HINTS" at all or or its flags field
251 is zero then the return is an empty list.
252 The return can be put into a hash to get fields by name,
254 my %hints = X11::Protocol::WM::get_wm_hints ($X, $window);
256 if (exists $hints{'icon_pixmap'}) {
257 print "icon_pixmap is ", $hints{'icon_pixmap'}, "\n";
258 }
259 "initial_state" is a string such as "NormalState". The pixmaps and
261 windows are string "None" if set but zero (which is probably
262 unusual). If "$X->{'do_interp'}" is disabled then all are numbers.
263 X11R2 Xlib had a bug in its "XSetWMHints()" which chopped off the
265 "window_group" value from the hints stored. The "window_group"
266 field is omitted from the return if the data read is missing that
267 field.
268 "(key => $value, ...) = X11::Protocol::WM::change_wm_hints ($X,
270 $window, key=>value, ...)"
271 Change some fields of the "WM_HINTS" property on $window. The
272 given key/value fields are changed. Other fields are left alone.
273 For example,
274 X11::Protocol::WM::set_wm_hints ($X, $window,
276 urgency => 1);
277 A value "undef" means delete a field,
279 X11::Protocol::WM::set_wm_hints ($X, $window,
281 icon_pixmap => undef,
282 icon_mask => undef);
283 The change requires a server round-trip to fetch the current values
285 from $window. An application might prefer to remember its desired
286 hints and send a full "set_wm_hints()" each time.
287 "$bytes = X11::Protocol::WM::pack_wm_hints ($X, key=>value...)"
289 Pack a set of values into a byte string of "WM_HINTS" format. The
290 key/value arguments are per "set_wm_hints()" above and the result
291 is the raw bytes stored in a "WM_HINTS" property.
292 The $X argument is not actually used currently, but is present in
294 case "initial_state" or other values might use an "$X->num()"
295 lookup in the future.
296 "(key => $value, ...) = X11::Protocol::WM::unpack_wm_hints ($X,
298 $bytes)"
299 Unpack a byte string as a "WM_HINTS" structure. The return is
300 key/value pairs as per "get_wm_hints()" above. The $X parameter is
301 used for "do_interp". There's no communication with the server.
302 WM_NAME, WM_ICON_NAME
304 "X11::Protocol::WM::set_wm_name ($X, $window, $name)"
305 Set the "WM_NAME" property on $window (an integer XID) to $name (a
306 string).
307 The window manager might display this as a title above the window,
309 or in a menu of windows, etc. It can be a Perl 5.8 wide-char
310 string per "Text Properties" above. A good window manager ought to
311 support non-ASCII or non-Latin-1 titles, but how well it displays
312 might depend on fonts etc.
313 "X11::Protocol::WM::set_wm_icon_name ($X, $window, $name)"
315 Set the "WM_ICON_NAME" property on $window (an integer XID) to
316 $name (a string).
317 The window manager might display this when $window is iconified.
319 If $window doesn't have an icon (in "WM_HINTS" or from the window
320 manager itself) then this text might be all that's shown. Either
321 way it should be something short. It can be a Perl 5.8 wide-char
322 string per "Text Properties" above.
323 WM_NORMAL_HINTS
325 "X11::Protocol::WM::set_wm_normal_hints ($X, $window, key=>value,...)"
326 Set the "WM_NORMAL_HINTS" property on $window (an integer XID).
327 This is a "WM_SIZE_HINTS" structure which tells the window manager
328 what sizes the client would like. For example,
329 set_wm_normal_hints ($X, $window,
331 min_width => 200,
332 min_height => 100);
333 Generally the window manager restricts user resizing to the hint
335 limits. Most window managers use these hints, but of course
336 they're only hints and a good program should be prepared for other
337 sizes even if it won't look good or can't do much useful when too
338 big or too small etc.
339 The key/value parameters are
341 user_position boolean, window x,y is user specified
343 user_size boolean, window width,height is user specified
344 program_position boolean, window x,y is program specified
345 program_size boolean, window width,height is program specified
346 min_width \ integers, min size in pixels
347 min_height /
348 max_width \ integers, max size in pixels
349 max_height /
350 base_width \ integers, size base in pixels
351 base_height /
352 width_inc \ integers, size increment in pixels
353 height_inc /
354 min_aspect \ fraction 2/3 or decimal 2 or 1.5
355 min_aspect_num | or integer num/den up to 0x7FFFFFFF
356 min_aspect_den |
357 max_aspect |
358 max_aspect_num |
359 max_aspect_den /
360 win_gravity WinGravity enum "NorthEast" etc
361 "user_position" and "user_size" are flags meaning that the window's
363 x,y or width,height (in the usual core "$X->SetWindowAttributes()")
364 were given by the user, for example from a "-geometry" command line
365 option. The window manager will generally obey these values and
366 skip any auto-placement or interactive placement it might otherwise
367 do.
368 "program_position" and "program_size" are flags meaning the window
370 x,y or width,height were calculated by the program. The window
371 manager might override with its own positioning or sizing policy.
372 There's generally no need to set these fields unless the program
373 has a definite idea of where and how big it should be. For a size
374 it's enough to set the core window width,height and let the window
375 manager (if there's one running) go from there.
376 Items shown grouped above must be given together, so for instance
378 if a "min_width" is given then "min_height" should be given too.
379 "base_width","base_height" and "width_inc","height_inc" ask that
381 the window be a certain base size in pixels then a multiple of
382 "inc" pixels above that. This can be used by things like "xterm"
383 which want a fixed size for border or scrollbar and then a multiple
384 of the character size above that. If "base_width","base_height"
385 are not given then "min_width","min_height" is the base size.
386 "base_width","base_height" can be smaller than
388 "min_width","min_height". This means the size should still be a
389 base+inc multiple, but the first such which is at least the min
390 size. The window manager generally presents the "inc" multiple to
391 the user, so that for example on an xterm the user sees a count of
392 characters. A min size can then demand for example a minimum 1x1
393 or 2x2 character size.
394 "min_aspect","max_aspect" ask that the window have a certain
396 minimum or maximum width/height ratio. For example aspect 2/1
397 means it should be twice as wide as it is high. This is applied to
398 the size above "base_width","base_height", or if base not given
399 then to the whole window size.
400 "min_aspect_num","min_aspect_den" and
402 "max_aspect_num","max_aspect_den" set numerator and denominator
403 values directly (INT32, so maximum 0x7FFF_FFFF). Or "min_aspect"
404 and "max_aspect" accept a single value in various forms which are
405 turned into num/den values.
406 2 integer
408 1.125 decimal, meaning 1125/1000
409 2/3 fraction
410 1.5/4.5 fraction with decimals
411 Values bigger than 0x7FFFFFFF in these forms are reduced
413 proportionally as necessary. A Perl floating point value will
414 usually have more bits of precision than 0x7FFFFFFF and is
415 truncated to something that fits.
416 "win_gravity" is how the client would like to be shifted to make
418 room for any surrounding frame the window manager might add. For
419 example if the program calculated the window size and position to
420 ensure the north-east corner is at a desired position, then give
421 "win_gravity => "NorthEast"" so that the window manager keeps the
422 north-east corner the same when it applies its frame.
423 "win_gravity => "Static"" means the frame is put around the window
425 and the window not moved at all. Of course that might mean some of
426 the frame ends up off-screen.
427 "$bytes = X11::Protocol::WM::pack_size_hints ($X, key=>value,...)"
429 Return a bytes string which is a "WM_SIZE_HINTS" structure made
430 from the given key/value parameters. "WM_SIZE_HINTS" is structure
431 type for "WM_NORMAL_HINTS" described above and the key/value
432 parameters are as described above.
433 The $X parameter is used to interpret "win_gravity" enum values.
435 There's no communication with the server.
436 "($num,$den) = X11::Protocol::WM::aspect_to_num_den ($aspect)"
438 Return a pair of INT32 integers 0 to 0x7FFF_FFFF for the given
439 aspect ratio $aspect. This is the conversion applied to
440 "min_aspect" and "max_aspect" above. $aspect can be any of the
441 integer, decimal or fraction described.
442 WM_PROTOCOLS
444 "X11::Protocol::WM::set_wm_protocols ($X, $window, $protocol,...)"
445 Set the "WM_PROTOCOLS" property on $window (an XID). Each argument
446 is a string protocol name or an integer atom ID.
447 X11::Protocol::WM::set_wm_protocols
449 ($X, $window, 'WM_DELETE_WINDOW', '_NET_WM_PING')
450 For example "WM_DELETE_WINDOW" means that when the user clicks the
452 close button the window manager sends a "ClientMessage" event
453 rather than doing a "KillClient()". The "ClientMessage" event
454 allows a program to clean-up or ask the user about saving a
455 document before exiting, etc.
456 WM_STATE
458 The window manager maintains a state for each client window it manages,
459 WithdrawnState
461 NormalState
462 IconicState
463 "WithdrawnState" means the window is not mapped and the window manager
465 is not managing it. A newly created window ("$X->CreateWindow()") is
466 initially "WithdrawnState" and on first "$X->MapWindow()" goes to
467 "NormalState" (or to "IconicState" if that's the initial state asked
468 for in "WM_HINTS").
469 "iconify()" and "withdraw()" below can change the state to iconic or
471 withdrawn. A window can be restored from iconic to normal by a
472 "MapWindow()".
473 "($state, $icon_window) = X11::Protocol::WM::get_wm_state ($X,
475 $window)"
476 Return the "WM_STATE" property from $window. This is set by the
477 window manager on top-level application windows. If there's no
478 such property then the return is an empty list.
479 $state returned is an enum string, or an integer value if
481 "$X->{'do_interp'}" is disabled or the value unrecognised.
482 "WithdrawnState" 0 not displayed
484 "NormalState" 1 window displayed
485 "IconicState" 3 iconified in some way
486 "ZoomState" 2 \ no longer in ICCCM
488 "InactiveState" 4 / (zoom meant maximized)
489 $icon_window returned is the window (integer XID) used by the
491 window manager to display an icon of $window. If there's no such
492 window then $icon_window is "None" (or 0 if "$X->{'do_interp'}" is
493 disabled).
494 $icon_window might be the icon window from the client's "WM_HINTS"
496 or it might be a window created by the window manager. The client
497 can draw into it for animations etc, perhaps selecting "Expose"
498 events on it to know when to redraw.
499 "WM_STATE" is set by the window manager when a toplevel window is
501 first mapped (or perhaps earlier), and then kept up-to-date.
502 Generally no "WM_STATE" property or a "WM_STATE" set to
503 WithdrawnState means the window manager is not managing the window,
504 or not yet doing so. A client can select "PropertyChange" event
505 mask in the usual way to listen for "WM_STATE" changes.
506 "($state, $icon_window) = X11::Protocol::WM::unpack_wm_state ($X,
508 $bytes)"
509 Unpack the bytes of a "WM_STATE" property to a $state and
510 $icon_window as per "get_wm_state()" above.
511 $X is used for "$X->{'do_interp'}" but there's no communication
513 with the server.
514 "X11::Protocol::WM::iconify ($X, $window)"
516 "X11::Protocol::WM::iconify ($X, $window, $root)"
517 Change $window to "IconicState" by sending a "ClientMessage" to the
518 window manager.
519 If the window manager does not have any iconification then it might
521 do nothing (eg. some tiling window managers). If there's no window
522 manager running then iconification is not possible and this message
523 will do nothing.
524 $root should be the root window of $window. If not given or
526 "undef" then it's obtained by a "QueryTree()" here. Any client can
527 iconify any top level window.
528 If $window has other windows which are "WM_TRANSIENT_FOR" for it
530 then generally the window manager will iconify or hide those
531 windows too (see "WM_TRANSIENT_FOR" below).
532 "X11::Protocol::WM::withdraw ($X, $window)"
534 "X11::Protocol::WM::withdraw ($X, $window, $root)"
535 Change $window to "WithdrawnState" by an "$X->UnmapWindow()" and a
536 synthetic "UnmapNotify" message to the window manager.
537 If there's no window manager running then the "UnmapWindow()"
539 unmaps and the "UnmapNotify" message does nothing.
540 $root should be the root window of $window. If not given or
542 "undef" then it's obtained by a "QueryTree()" here.
543 If other windows are "WM_TRANSIENT_FOR" this $window (eg. open
545 dialog windows) then generally the client should withdraw them too.
546 The window manager might make such other windows inaccessible
547 anyway.
548 The ICCCM specifies an "UnmapNotify" message so the window manager
550 is notified of the desired state change even if $window is already
551 unmapped, such as in "IconicState" or perhaps during some window
552 manager reparenting, etc.
553 $window can be changed back to NormalState or IconicState later
555 with "$X->MapWindow()" the same as for a newly created window.
556 (And "WM_HINTS" "initial_state" can give a desired initial
557 iconic/normal state). But before doing so be sure the window
558 manager has recognised the "withdraw()". This will be when the
559 window manager changes the "WM_STATE" property to "WithdrawnState",
560 or deletes that property.
561 Any client can withdraw any toplevel window, but it's unusual for a
563 client to withdraw windows which are not its own.
564 WM_TRANSIENT_FOR
566 "X11::Protocol::WM::set_wm_transient_for ($X, $window, $transient_for)"
567 Set the "WM_TRANSIENT_FOR" property on $window (an XID).
568 $transient_for is another window XID, or "undef" if $window is not
570 transient for anything so "WM_TRANSIENT_FOR" should be deleted.
571 "Transient for" means $window is some sort of dialog or menu
573 related to the given $transient_for window. The window manager
574 will generally iconify $window together with its $transient_for,
575 etc. See "set_motif_wm_hints()" below for "modal" transients.
576 _MOTIF_WM_HINTS
578 "X11::Protocol::WM::set_motif_wm_hints ($X, $window, key=>value...)"
579 Set the "MOTIF_WM_HINTS" property on $window (an XID).
580 These hints control window decorations and "modal" state. It
582 originated in the Motif "mwm" window manager but is recognised by
583 most other window managers. It should be set on a toplevel window
584 before mapping. Changes made later might not affect what the
585 window manager does.
586 X11::Protocol::WM::set_motif_wm_hints
588 ($X, $dialog_window,
589 input_mode => "full_application_modal");
590 $X->MapWindow ($dialog_window);
591 Ordinary windows generally don't need to restrict their decorations
593 etc, but something special like a clock or gadget might benefit.
594 X11::Protocol::WM::set_motif_wm_hints
596 ($X, $my_gadget_window,
597 functions => 4+32, # move+close
598 decorations => 1+4+8); # border+title+menu
599 The key/value arguments are
601 functions => integer bits
603 decorations => integer bits
604 input_mode => enum string or integer
605 status => integer bits
606 "functions" is what actions the window manager should offer to the
608 user in a drop-down menu or similar. It's an integer bitwise OR of
609 the following values. If not given then the default is normally
610 all functions.
611 bit actions offered
613 --- ---------------
614 1 all functions
615 2 resize window
616 4 move window
617 8 minimize, to iconify
618 16 maximize, to full-screen (with a frame still)
619 32 close window
620 "decorations" is what visual decorations the window manager should
622 show around the window. It's an integer bitwise OR of the
623 following values. If not given then the default is normally all
624 decorations.
625 bit decorations displayed
627 --- ---------------------
628 1 all decorations
629 2 border around the window
630 4 resizeh, handles to resize by dragging
631 8 title bar, showing WM_NAME
632 16 menu, drop-down menu of the "functions" above
633 32 minimize button, to iconify
634 64 maximize button, to full-screen
635 "input_mode" allows a window to be "modal", meaning the user should
637 interact only with $window. The window manager will generally keep
638 it on top, not move the focus to other windows, etc. The value is
639 one of the following strings or corresponding integer,
640 string integer
642 "modeless" 0 not modal (the default)
643 "primary_application_modal" 1 modal to its "transient for"
644 "system_modal" 2 modal to the whole display
645 "full_application_modal" 3 modal to the current client
646 "primary_application_modal" means $window is modal for the
648 "WM_TRANSIENT_FOR" set on $window (see "WM_TRANSIENT_FOR" above),
649 but other windows on the display can be used normally.
650 "full_application_modal" means modal for all windows of the same
651 client, but other clients can be used normally.
652 Modal behaviour is important for good user interaction and
654 therefore ought to be implemented by a window manager, but a good
655 program should be prepared to do something with input on other
656 windows.
657 "status" field is a bitwise OR of the following bits (only one
659 currently).
660 bit
662 1 tearoff menu window
663 Tearoff menu flag is intended for tearoff menus, as the name
665 suggests.
666 X11::Protocol::WM::set_motif_wm_hints
668 ($X, $my_tearoff_window, status => 1);
669 Motif "mwm" will expand the window to make it wide enough for the
671 "WM_NAME" in the frame title bar. Otherwise a title is generally
672 truncated to as much as fits the window's current width. Expanding
673 can be good for tearoffs where the title bar is some originating
674 item name etc which the user should see. But don't be surprised if
675 this flag is ignored by other window managers.
676 Perhaps in the future the individual bits above will have some
678 symbolic names. Either constants or string values interpreted.
679 What would a possible "get_hints()" return, and what might be
680 convenient to add/subtract bits?
681 See /usr/include/Xm/MwmUtil.h on the hints bits, and see "mwm"
683 sources WmWinInfo.c "ProcessWmWindowTitle()" for the "status"
684 tearoff window flag.
685 _NET_FRAME_EXTENTS
687 "my ($left,$right, $top,$bottom) =
688 X11::Protocol::WM::get_net_frame_extents ($X, $window)"
689 Get the "_NET_FRAME_EXTENTS" property from $window.
690 This is set on top-level windows by the window manager to report
692 how many pixels of frame or decoration it has added around $window.
693 If there's no such property set then the return is an empty list.
695 So for example
696 my ($left,$right,$top,$bottom)
698 = get_net_frame_extents ($X, $window)
699 or print "no frame extents";
700 my ($left,$right,$top,$bottom)
702 = get_net_frame_extents ($X, $window);
703 if (! defined $left) {
704 print "no frame extents";
705 }
706 A client might look at the frame size if moving a window
708 programmatically so as not to put the title bar etc off-screen.
709 Oldish window managers might not provide this information though.
710 _NET_WM_PID
712 "X11::Protocol::WM::set_net_wm_pid ($X, $window)"
713 "X11::Protocol::WM::set_net_wm_pid ($X, $window, $pid)"
714 "X11::Protocol::WM::set_net_wm_pid ($X, $window, undef)"
715 Set the "_NET_WM_PID" property on $window to the given $pid process
716 ID, or to the $$ current process ID if omitted. (See perlvar for
717 $$.) If $pid is "undef" then the property is deleted.
718 A window manager or similar might use the PID to forcibly kill an
720 unresponsive client. It's only useful if "WM_CLIENT_MACHINE"
721 (above) is set too, to know where the client is running.
722 _NET_WM_STATE
724 An EWMH compliant window manager maintains a set of state flags for
725 each client window. A state is an atom such as
726 "_NET_WM_STATE_FULLSCREEN" and each such state can be present or
727 absent. The supported states are listed in property "_NET_SUPPORTED"
728 on the root (together with other features). For example,
729 my @net_supported = X11::Protocol::Other::get_property_atoms
731 ($X, $X->root, $X->atom('_NET_SUPPORTED'));
732 if (grep {$_ == $X->atom('_NET_WM_STATE_FULLSCREEN')}
733 @net_supported) {
734 print "Have _NET_WM_STATE_FULLSCREEN\n";
735 }
736 Any client can ask the window manager to change states of any window.
738 A client might set initial states on a new window with
739 "set_net_wm_state()" below. Possible states include
740 _NET_WM_STATE_MODAL
742 The window is modal to its "WM_TRANSIENT_FOR" parent, or if
743 "WM_TRANSIENT_FOR" not set then modal to its window group.
744 See "_MOTIF_WM_HINTS" to set modal with the Motif style hints.
746 _NET_WM_STATE_STICKY
748 The window is kept in a fixed position on screen when the desktop
749 scrolls.
750 _NET_WM_STATE_MAXIMIZED_VERT
752 _NET_WM_STATE_MAXIMIZED_HORZ
753 The window is maximum size vertically or horizontally or both. The
754 window still has its surrounding decoration and the size should
755 obey size increments specified in "WM_NORMAL_HINTS".
756 _NET_WM_STATE_FULLSCREEN
758 The window is the full screen with no decoration around it, thus
759 being the full screen.
760 The window manager remembers the "normal" size of the window so
762 that when maximize or fullscreen states are removed the previous
763 size is restored.
764 _NET_WM_STATE_SHADED
766 The window is "shaded" which generally means its title bar is
767 displayed but none of the client window. This is an alternative to
768 iconifying a window.
769 _NET_WM_STATE_SKIP_TASKBAR
771 _NET_WM_STATE_SKIP_PAGER
772 Don't show the window on a task bar or in a pager, respectively.
773 _NET_WM_STATE_HIDDEN (read-only)
775 This state is set by the window manger when the window is iconified
776 or similar and so does not appear on screen. Clients cannot change
777 this.
778 _NET_WM_STATE_ABOVE
780 _NET_WM_STATE_BELOW
781 The window is kept above or below other client windows. The
782 stacking order maintained is roughly
783 top
785 +-----------------------------+
786 | _NET_WM_WINDOW_TYPE_DOCK | "DOCK" panels (etc) on top,
787 +-----------------------------+ except perhaps FULLSCREEN
788 | _NET_WM_STATE_ABOVE | windows above those panels
789 +-----------------------------+ when focused
790 | normal |
791 +-----------------------------+
792 | _NET_WM_STATE_BELOW |
793 +-----------------------------+
794 | _NET_WM_WINDOW_TYPE_DESKTOP |
795 +-----------------------------+
796 bottom
797 _NET_WM_STATE_DEMANDS_ATTENTION
799 The window should be brought to the attention of the user in some
800 way. A client sets this and the window manager clears it after the
801 window has received user attention (which might mean keyboard focus
802 or similar).
803 The following functions get or set the states.
805 "change_net_wm_state($X, $window, $action, $state, key=>value,...)"
807 Change one of the "_NET_WM_STATE" state flags on $window by sending
808 a message to the window manager. For example,
809 change_net_wm_state ($X, $window, "toggle", "FULLSCREEN");
811 $window must be a managed window, ie. must have had its initial
813 "MapWindow()" and not be an override-redirect. If that's not so or
814 if there's no window manager or it doesn't have EWMH then this
815 change message will have no effect.
816 $action is a string or integer how to change the state,
818 "remove" 0
820 "add" 1
821 "toggle" 2
822 $state is a string such as "FULLSCREEN" or an atom integer such as
824 "$X->atom("_NET_WM_STATE_FULLSCREEN")".
825 The further optional key/value parameters are
827 state2 => string or atom
829 source => "none", "normal", "user", 0,1,2
830 root => integer XID, or undef
831 A change message can act on one or two states. For two states, the
833 second is "state2". For example to maximize vertically and
834 horizontally in one operation,
835 change_net_wm_state ($X, $window, "add", "MAXIMIZED_VERT",
837 state2 => "MAXIMIZED_HORZ");
838 "source" is where the change request came from. The default is
840 "normal" which means a normal application. "user" is for a user-
841 interface control program such as a pager. ("none"=0 is what
842 clients prior to EWMH 1.2 gave.)
843 "root" is the root window (integer XID) of $window. If "undef" or
845 not given then it's found by "$X->QueryTree()". If you already
846 know the root then giving it avoids that round-trip query.
847 "@strings = get_net_wm_state ($X, $window)"
849 "@atoms = get_net_wm_state_atoms ($X, $window)"
850 Get the "_NET_WM_STATE" property from $window.
851 "get_net_wm_state()" returns a list of strings such as
852 "FULLSCREEN". "get_net_wm_state_atoms()" returns a list of atom
853 integers such as "$X->atom('_NET_WM_STATE_FULLSCREEN')". In both
854 cases, if there's no such property or if it's empty then return an
855 empty list.
856 "set_net_wm_state ($X, $window, $state,...)"
858 Set the "_NET_WM_STATE" property on $window. Each $state can be
859 string like "FULLSCREEN"
861 string like "_NET_WM_STATE_FULLSCREEN"
862 integer atom of a name like _NET_WM_STATE_FULLSCREEN
863 A client can set "_NET_WM_STATE" on a new window to tell the window
865 manager of desired initial states. This is only a "should" in the
866 EWMH spec so it might not be obeyed.
867 # initial desired state
869 set_net_wm_state ($X, $window,
870 "MAXIMIZED_HORZ", "MAXIMIZED_VERT");
871 After the window is managed by the window manager (once mapped),
873 clients should not set "_NET_WM_STATE" but instead ask the window
874 manager with "change_net_wm_state()" message above.
875 _NET_WM_USER_TIME
877 "set_net_wm_user_time ($X, $window, $time)"
878 Set the "_NET_WM_USER_TIME" property on $window.
879 $time should be a server time value (an integer) from the last user
881 keypress etc event in $window. Or when $window is created then the
882 time from the event which caused it to be opened.
883 On a newly created window, a special $time value 0 means the window
885 should not receive the focus when mapped -- assuming the window
886 manager recognises "_NET_WM_USER_TIME" of course.
887 If the client has the active window it should update
889 "_NET_WM_USER_TIME" for every user input. Generally KeyPress and
890 ButtonPress events are user input, but normally KeyRelease and
891 ButtonRelease are not since it's the Press events which are the
892 user actively doing something.
893 The window manager might use "_NET_WM_USER_TIME" to control focus
895 and/or stacking order so that for example a slow popup doesn't
896 steal the focus if you've gone to another window to do other work
897 in the interim.
898 _NET_WM_WINDOW_TYPE
900 "X11::Protocol::WM::set_net_wm_window_type ($X, $window, $window_type)"
901 Set the "_NET_WM_WINDOW_TYPE" property on $window (an XID).
902 $window_type can be
903 string like "NORMAL"
905 integer atom of a name like _NET_WM_WINDOW_TYPE_NORMAL
906 The window types from from the EWMH are as follows.
908 "NORMAL"
910 "DIALOG"
911 "DESKTOP"
912 "DOCK"
913 "TOOLBAR"
914 "MENU"
915 "UTILITY"
916 "SPLASH"
917 Frame to Client
919 "$window = X11::Protocol::WM::frame_window_to_client ($X, $frame)"
920 Return the client window (an XID) contained within window manager
921 $frame window (an XID). $frame is usually an immediate child of
922 the root window.
923 If no client window can be found in $frame then return "undef".
925 This might happen if $frame is an icon window or similar created by
926 the window manager itself, or an override-redirect client without a
927 frame, or if there's no window manager running at all. In the
928 latter two cases $frame would be the client already.
929 The strategy is to look at $frame and down the window tree seeking
931 a "WM_STATE" property which the window manager puts on a client's
932 toplevel when mapped. The search depth and total windows are
933 limited in case the window manager does its decoration in some
934 ridiculous way or the client uses excessive windows (which would be
935 traversed if there's no window manager).
936 +-rootwin--------------------------+
938 | |
939 | |
940 | +-frame-win--------+ |
941 | | +-client-win---+ | |
942 | | | WM_STATE ... | | |
943 | | | | | |
944 | | +--------------+ | |
945 | +------------------+ |
946 | |
947 +----------------------------------+
948 Care is taken not to error out if some windows are destroyed during
950 the search. When a window belongs to other clients it could be
951 destroyed at any time. If $frame itself doesn't exist then the
952 return is "undef".
953 This function is similar to what "xwininfo" and similar programs do
955 to go from a toplevel root window child down to the client window,
956 per dmsimple.c "Select_Window()" or Xlib "XmuClientWindow()". (See
957 also X11::Protocol::ChooseWindow.)
958 Virtual Root
960 Some window managers use a "virtual root" window covering the entire
961 screen. Application windows or frame windows are then children of that
962 virtual root. This can help the window manager implement a large
963 desktop or multiple desktops, though it tends to fail in subtle ways
964 with various root oriented programs, including for example xsetroot(1)
965 or the click-to-select in xwininfo(1) and xprop(1).
966 "$window = X11::Protocol::WM::root_to_virtual_root ($X, $root)"
968 If the window manager is using a virtual root then return that
969 window XID. If not then return "undef".
970 The current implementation searches for a window with an
972 "__SWM_VROOT" property, as per the "swm", "tvtwm" and "amiwm"
973 window managers, and as used by the "xscreensaver" program and
974 perhaps some versions of KDE.
975 There's nothing yet for EWMH "_NET_VIRTUAL_ROOTS". Do any window
977 managers use it? Is "_NET_CURRENT_DESKTOP" an index into that
978 virtual roots list?
979 (See X11::Protocol::XSetRoot for changing the background of a root
981 or virtual root.)
982
984 Nothing is exported by default, but the functions can be requested in
985 usual "Exporter" style,
986 use X11::Protocol::WM 'set_wm_hints';
988 set_wm_hints ($X, $window, input => 1, ...);
989 Or just call with full package name
991 use X11::Protocol::WM;
993 X11::Protocol::WM::set_wm_hints ($X, $window, input => 1, ...);
994 There's no ":all" tag since this module is meant as a grab-bag of
996 functions and to import as-yet unknown things would be asking for name
997 clashes.
998
1000 Not much attention is paid to text on an EBCDIC system. Wide char
1001 strings probably work, but byte strings may go straight through whereas
1002 they ought to be re-coded to Latin-1. But the same probably applies to
1003 parts of the core "X11::Protocol" such as "$X->atom_name()" where you'd
1004 want to convert Latin-1 from the server to native EBCDIC.
1005
1007 X11::Protocol, X11::Protocol::Other, X11::Protocol::ChooseWindow,
1008 X11::Protocol::XSetRoot
1009 "Inter-Client Communication Conventions Manual",
1011 /usr/share/doc/xorg-docs/icccm/icccm.txt.gz,
1012 <http://www.x.org/docs/ICCCM/>
1013 "Compound Text Encoding" specification.
1015 /usr/share/doc/xorg-docs/ctext/ctext.txt.gz,
1016 <http://www.x.org/docs/CTEXT/>
1017 "Extended Window Manager Hints" which is the "_NET_WM" things.
1019 <http://www.freedesktop.org/wiki/Specifications/wm-spec>,
1020 <http://mail.gnome.org/archives/wm-spec-list/>
1021 wmctrl(1), xwit(1), X(7)
1023
1025 <http://user42.tuxfamily.org/x11-protocol-other/index.html>
1026
1028 Copyright 2011, 2012, 2013, 2014, 2016, 2017, 2018, 2019 Kevin Ryde
1029 X11-Protocol-Other is free software; you can redistribute it and/or
1031 modify it under the terms of the GNU General Public License as
1032 published by the Free Software Foundation; either version 3, or (at
1033 your option) any later version.
1034 X11-Protocol-Other is distributed in the hope that it will be useful,
1036 but WITHOUT ANY WARRANTY; without even the implied warranty of
1037 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
1038 General Public License for more details.
1039 You should have received a copy of the GNU General Public License along
1041 with X11-Protocol-Other. If not, see <http://www.gnu.org/licenses/>.
1042perl v5.34.0 2022-01-21 X11::Protocol::WM(3)