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/specs/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 A client can set this at any time, or if participating in the
130 "WM_SAVE_YOURSELF" session manager protocol then it should set in
131 response to a "ClientMessage" of "WM_SAVE_YOURSELF" .
132 The command should start the client in its current state as far as
134 possible, so the command might include a filename, command line
135 options for current settings, etc.
136 Non-ASCII is allowed per "Text Properties" above. The ICCCM spec
138 is for Latin-1 to work on a POSIX Latin-1 system, but how well
139 anything else survives a session manager etc is another matter.
140 WM_ICON_SIZE
142 "($min_width,$min_height, $max_width,$max_height,
143 $width_inc,$height_inc) =
144 X11::Protocol::WM::get_wm_icon_size($X,$root)"
145 Return the window manager's "WM_ICON_SIZE" recommended icon sizes
146 (in pixels) as a range, and increment above the minimum. If
147 there's no "WM_ICON_SIZE" property then return an empty list.
148 $root is the root window to read. If omitted then read the
150 "$X->root" default.
151 An icon pixmap or window in "WM_HINTS" should be a size in this
153 range. Many window managers don't set a preferred icon size.
154 32x32 might be typical on a small screen or 48x48 on a bigger
155 screen.
156 WM_HINTS
158 "X11::Protocol::WM::set_wm_hints ($X, $window, key=>value, ...)"
159 Set the "WM_HINTS" property on $window (an XID). For example,
160 X11::Protocol::WM::set_wm_hints
162 ($X, $my_window,
163 input => 1,
164 initial_state => 'NormalState',
165 icon_pixmap => $my_pixmap);
166 The key/value parameters are as follows.
168 input integer 0 or 1
170 initial_state enum string or number
171 icon_pixmap pixmap (XID integer), depth 1
172 icon_window window (XID integer)
173 icon_x \ integer coordinate
174 icon_y / integer coordinate
175 icon_mask pixmap (XID integer)
176 window_group window (XID integer)
177 urgency boolean
178 "input" is 1 if the client wants the window manager to give $window
180 the keyboard input focus. This will be with "$X->SetInputFocus()",
181 or if "WM_TAKE_FOCUS" is in "WM_PROTOCOLS" then instead by a
182 "ClientMessage".
183 "input" is 0 if the window manager should not give the client the
185 focus. This is either because $window is output-only, or if
186 "WM_TAKE_FOCUS" is in "WM_PROTOCOLS" then because the client will
187 do a "SetInputFocus()" to itself on an appropriate button press
188 etc.
189 "initial_state" is a string or number. The ICCCM allows
191 "NormalState" or "IconicState" as initial states.
192 "NormalState" 1
194 "IconicState" 3
195 "icon_pixmap" should be a bitmap, ie. a pixmap (XID) with depth 1.
197 The window manager will draw it in suitable contrasting colours.
198 "1" pixels are foreground and "0" is background. "icon_mask"
199 bitmap is applied to the displayed icon. It can be used to make a
200 non-rectangular icon.
201 "icon_window" is a window which the window manager may show when
203 $window is iconified. This can be used for a multi-colour icon,
204 done either by a background or by client drawing (in response to
205 "Expose" events, or updated periodically for a clock, etc). The
206 "icon_window" should be a child of the root and should use the
207 default visual and colormap of the screen. The window manager
208 might resize the window and/or border.
209 The window manager might set a "WM_ICON_SIZE" property on the root
211 window for good icon sizes. See "WM_ICON_SIZE".
212 "window_group" is the XID of a window which is the group leader of
214 a group of top-level windows being used by the client. The window
215 manager might provide a way to manipulate the group as a whole, for
216 example to iconify it all. If iconified then the icon hints of the
217 leader are used for the icon. The group leader can be an unmapped
218 window. It can be convenient to use a never-mapped window as the
219 leader for all subsequent windows.
220 "urgency" true means the window is important and the window manager
222 should draw the user's attention to it in some way. The client can
223 change this hint at any time to change the current importance.
224 "(key => $value, ...) = X11::Protocol::WM::get_wm_hints ($X, $window)"
226 Return the "WM_HINTS" property from $window. The return is a list
227 of key/value pairs as per "set_wm_hints()" above
228 input => 1,
230 icon_pixmap => 1234,
231 ...
232 Only fields with their flag bits set in the hints are included in
234 the return. If there's no "WM_HINTS" at all or or its flags field
235 is zero then the return is an empty list.
236 The return can be put into a hash to get fields by name,
238 my %hints = X11::Protocol::WM::get_wm_hints ($X, $window);
240 if (exists $hints{'icon_pixmap'}) {
241 print "icon_pixmap is ", $hints{'icon_pixmap'}, "\n";
242 }
243 "initial_state" is a string such as "NormalState". The pixmaps and
245 windows are string "None" if set but zero (which is probably
246 unusual). If "$X->{'do_interp'}" is disabled then all are numbers.
247 X11R2 Xlib had a bug in its "XSetWMHints()" which chopped off the
249 "window_group" value from the hints stored. The "window_group"
250 field is omitted from the return in that case.
251 "(key => $value, ...) = X11::Protocol::WM::change_wm_hints ($X,
253 $window, key=>value, ...)"
254 Change some fields of the "WM_HINTS" property on $window. The
255 given key/value fields are changed. Other fields are left alone.
256 For example,
257 X11::Protocol::WM::set_wm_hints ($X, $window,
259 urgency => 1);
260 A value "undef" means delete a field,
262 X11::Protocol::WM::set_wm_hints ($X, $window,
264 icon_pixmap => undef,
265 icon_mask => undef);
266 The change requires a server round-trip to fetch the current values
268 from $window. An application might prefer to remember its desired
269 hints and send a full "set_wm_hints()" each time.
270 "$bytes = X11::Protocol::WM::pack_wm_hints ($X, key=>value...)"
272 Pack a set of values into a byte string of "WM_HINTS" format. The
273 key/value arguments are per "set_wm_hints()" above and the result
274 is the raw bytes stored in a "WM_HINTS" property.
275 The $X argument is not actually used currently, but is present in
277 case "initial_state" or other values might use an "$X->num()"
278 lookup in the future.
279 "(key => $value, ...) = X11::Protocol::WM::unpack_wm_hints ($X,
281 $bytes)"
282 Unpack a byte string as a "WM_HINTS" structure. The return is
283 key/value pairs as per "get_wm_hints()" above. The $X parameter is
284 used for "do_interp". There's no communication with the server.
285 WM_NAME, WM_ICON_NAME
287 "X11::Protocol::WM::set_wm_name ($X, $window, $name)"
288 Set the "WM_NAME" property on $window (an integer XID) to $name (a
289 string).
290 The window manager might display this as a title above the window,
292 or in a menu of windows, etc. It can be a Perl 5.8 wide-char
293 string per "Text Properties" above. A good window manager ought to
294 support non-ASCII or non-Latin-1 titles, but how well it displays
295 might depend on fonts etc.
296 "X11::Protocol::WM::set_wm_icon_name ($X, $window, $name)"
298 Set the "WM_ICON_NAME" property on $window (an integer XID) to
299 $name (a string).
300 The window manager might display this when $window is iconified.
302 If $window doesn't have an icon (in "WM_HINTS" or from the window
303 manager itself) then this text might be all that's shown. Either
304 way it should be something short. It can be a Perl 5.8 wide-char
305 string per "Text Properties" above.
306 WM_NORMAL_HINTS
308 "X11::Protocol::WM::set_wm_normal_hints ($X, $window, key=>value,...)"
309 Set the "WM_NORMAL_HINTS" property on $window (an integer XID).
310 This is a "WM_SIZE_HINTS" structure which tells the window manager
311 what sizes the client would like. For example,
312 set_wm_normal_hints ($X, $window,
314 min_width => 200,
315 min_height => 100);
316 Generally the window manager restricts user resizing to the hint
318 limits. Most window managers use these hints, but of course
319 they're only hints and a good program should be prepared for other
320 sizes even if it won't look good or can't do much useful when too
321 big or too small etc.
322 The key/value parameters are
324 user_position boolean, window x,y is user specified
326 user_size boolean, window width,height is user specified
327 program_position boolean, window x,y is program specified
328 program_size boolean, window width,height is program specified
329 min_width \ integers, min size in pixels
330 min_height /
331 max_width \ integers, max size in pixels
332 max_height /
333 base_width \ integers, size base in pixels
334 base_height /
335 width_inc \ integers, size increment in pixels
336 height_inc /
337 min_aspect \ fraction 2/3 or decimal 2 or 1.5
338 min_aspect_num | or integer num/den up to 0x7FFFFFFF
339 min_aspect_den |
340 max_aspect |
341 max_aspect_num |
342 max_aspect_den /
343 win_gravity WinGravity enum "NorthEast" etc
344 "user_position" and "user_size" are flags meaning that the window's
346 x,y or width,height (in the usual core "$X->SetWindowAttributes()")
347 were given by the user, for example from a "-geometry" command line
348 option. The window manager will generally obey these values and
349 skip any auto-placement or interactive placement it might otherwise
350 do.
351 "program_position" and "program_size" are flags meaning the window
353 x,y or width,height were calculated by the program. The window
354 manager might override with its own positioning or sizing policy.
355 There's generally no need to set these fields unless the program
356 has a definite idea of where and how big it should be. For a size
357 it's enough to set the core window width,height and let the window
358 manager (if there's one running) go from there.
359 Items shown grouped above must be given together, so for instance
361 if a "min_width" is given then "min_height" should be given too.
362 "base_width","base_height" and "width_inc","height_inc" ask that
364 the window be a certain base size in pixels then a multiple of
365 "inc" pixels above that. This can be used by things like "xterm"
366 which want a fixed size for border or scrollbar and then a multiple
367 of the character size above that. If "base_width","base_height"
368 are not given then "min_width","min_height" is the base size.
369 "base_width","base_height" can be smaller than
371 "min_width","min_height". This means the size should still be a
372 base+inc multiple, but the first such which is at least the min
373 size. The window manager generally presents the "inc" multiple to
374 the user, so that for example on an xterm the user sees a count of
375 characters. A min size can then demand for example a minimum 1x1
376 or 2x2 character size.
377 "min_aspect","max_aspect" ask that the window have a certain
379 minimum or maximum width/height ratio. For example aspect 2/1
380 means it should be twice as wide as it is high. This is applied to
381 the size above "base_width","base_height", or if base not given
382 then to the whole window size.
383 "min_aspect_num","min_aspect_den" and
385 "max_aspect_num","max_aspect_den" set numerator and denominator
386 values directly (INT32, so maximum 0x7FFF_FFFF). Or "min_aspect"
387 and "max_aspect" accept a single value in various forms which are
388 turned into num/den values.
389 2 integer
391 1.125 decimal, meaning 1125/1000
392 2/3 fraction
393 1.5/4.5 fraction with decimals
394 Values bigger than 0x7FFFFFFF in these forms are reduced
396 proportionally as necessary. A Perl floating point value will
397 usually have more bits of precision than 0x7FFFFFFF and is
398 truncated to something that fits.
399 "win_gravity" is how the client would like to be shifted to make
401 room for any surrounding frame the window manager might add. For
402 example if the program calculated the window size and position to
403 ensure the north-east corner is at a desired position, then give
404 "win_gravity => "NorthEast"" so that the window manager keeps the
405 north-east corner the same when it applies its frame.
406 "win_gravity => "Static"" means the frame is put around the window
408 and the window not moved at all. Of course that might mean some of
409 the frame ends up off-screen.
410 "$bytes = X11::Protocol::WM::pack_size_hints ($X, key=>value,...)"
412 Return a bytes string which is a "WM_SIZE_HINTS" structure made
413 from the given key/value parameters. "WM_SIZE_HINTS" is structure
414 type for "WM_NORMAL_HINTS" described above and the key/value
415 parameters are as described above.
416 The $X parameter is used to interpret "win_gravity" enum values.
418 There's no communication with the server.
419 "($num,$den) = X11::Protocol::WM::aspect_to_num_den ($aspect)"
421 Return a pair of INT32 integers 0 to 0x7FFF_FFFF for the given
422 aspect ratio $aspect. This is the conversion applied to
423 "min_aspect" and "max_aspect" above. $aspect can be any of the
424 integer, decimal or fraction described.
425 WM_PROTOCOLS
427 "X11::Protocol::WM::set_wm_protocols ($X, $window, $protocol,...)"
428 Set the "WM_PROTOCOLS" property on $window (an XID). Each argument
429 is a string protocol name or an integer atom ID.
430 X11::Protocol::WM::set_wm_protocols
432 ($X, $window, 'WM_DELETE_WINDOW', '_NET_WM_PING')
433 For example "WM_DELETE_WINDOW" means that when the user clicks the
435 close button the window manager sends a "ClientMessage" event
436 rather than doing a "KillClient()". The "ClientMessage" event
437 allows a program to clean-up or ask the user about saving a
438 document before exiting, etc.
439 WM_STATE
441 The window manager maintains a state for each client window it manages,
442 WithdrawnState
444 NormalState
445 IconicState
446 "WithdrawnState" means the window is not mapped and the window manager
448 is not managing it. A newly created window ("$X->CreateWindow()") is
449 initially "WithdrawnState" and on first "$X->MapWindow()" goes to
450 "NormalState" (or to "IconicState" if that's the initial state asked
451 for in "WM_HINTS").
452 "iconify()" and "withdraw()" below can change the state to iconic or
454 withdrawn. A window can be restored from iconic to normal by a
455 "MapWindow()".
456 "($state, $icon_window) = X11::Protocol::WM::get_wm_state ($X,
458 $window)"
459 Return the "WM_STATE" property from $window. This is set by the
460 window manager on top-level application windows. If there's no
461 such property then the return is an empty list.
462 $state returned is an enum string, or an integer value if
464 "$X->{'do_interp'}" is disabled or the value unrecognised.
465 "WithdrawnState" 0 not displayed
467 "NormalState" 1 window displayed
468 "IconicState" 3 iconified in some way
469 "ZoomState" 2 \ no longer in ICCCM
471 "InactiveState" 4 / (zoom meant maximized)
472 $icon_window returned is the window (integer XID) used by the
474 window manager to display an icon of $window. If there's no such
475 window then $icon_window is "None" (or 0 if "$X->{'do_interp'}" is
476 disabled).
477 $icon_window might be the icon window from the client's "WM_HINTS"
479 or it might be a window created by the window manager. The client
480 can draw into it for animations etc, perhaps selecting "Expose"
481 events on it to know when to redraw.
482 "WM_STATE" is set by the window manager when a toplevel window is
484 first mapped (or perhaps earlier), and then kept up-to-date.
485 Generally no "WM_STATE" property or a "WM_STATE" set to
486 WithdrawnState means the window manager is not managing the window,
487 or not yet doing so. A client can select "PropertyChange" event
488 mask in the usual way to listen for "WM_STATE" changes.
489 "($state, $icon_window) = X11::Protocol::WM::unpack_wm_state ($X,
491 $bytes)"
492 Unpack the bytes of a "WM_STATE" property to a $state and
493 $icon_window as per "get_wm_state()" above.
494 $X is used for "$X->{'do_interp'}" but there's no communication
496 with the server.
497 "X11::Protocol::WM::iconify ($X, $window)"
499 "X11::Protocol::WM::iconify ($X, $window, $root)"
500 Change $window to "IconicState" by sending a "ClientMessage" to the
501 window manager.
502 If the window manager does not have any iconification then it might
504 do nothing (eg. some tiling window managers). If there's no window
505 manager running then iconification is not possible and this message
506 will do nothing.
507 $root should be the root window of $window. If not given or
509 "undef" then it's obtained from a "QueryTree()". Any client can
510 iconify any top level window.
511 If $window has other windows which are "WM_TRANSIENT_FOR" for it
513 then generally the window manager will iconify or hide those
514 windows too (see "WM_TRANSIENT_FOR" below).
515 "X11::Protocol::WM::withdraw ($X, $window)"
517 "X11::Protocol::WM::withdraw ($X, $window, $root)"
518 Change $window to "WithdrawnState" by an "$X->UnmapWindow()" and a
519 synthetic "UnmapNotify" message to the window manager.
520 If there's no window manager running then the "UnmapWindow()"
522 unmaps and the "UnmapNotify" message does nothing.
523 $root should be the root window of $window. If not given or
525 "undef" then it's obtained from a "$X->QueryTree()".
526 If other windows are "WM_TRANSIENT_FOR" this $window (eg. open
528 dialog windows) then generally the client should withdraw them too.
529 The window manager might make such other windows inaccessible
530 anyway.
531 The ICCCM specifies an "UnmapNotify" message so the window manager
533 is notified of the desired state change even if $window is already
534 unmapped, such as in "IconicState" or perhaps during some window
535 manager reparenting, etc.
536 $window can be changed back to NormalState or IconicState later
538 with "$X->MapWindow()" the same as for a newly created window.
539 (And "WM_HINTS" "initial_state" can give a desired initial
540 iconic/normal state). But before doing so be sure the window
541 manager has recognised the "withdraw()". This will be when the
542 window manager changes the "WM_STATE" property to "WithdrawnState",
543 or deletes that property.
544 Any client can withdraw any toplevel window, but it's unusual for a
546 client to withdraw windows which are not its own.
547 WM_TRANSIENT_FOR
549 "X11::Protocol::WM::set_wm_transient_for ($X, $window, $transient_for)"
550 Set the "WM_TRANSIENT_FOR" property on $window (an XID).
551 $transient_for is another window XID, or "undef" if $window is not
553 transient for anything so "WM_TRANSIENT_FOR" should be deleted.
554 "Transient for" means $window is some sort of dialog or menu
556 related to the given $transient_for window. The window manager
557 will generally iconify $window together with its $transient_for,
558 etc. See "set_motif_wm_hints()" below for "modal" transients.
559 _MOTIF_WM_HINTS
561 "X11::Protocol::WM::set_motif_wm_hints ($X, $window, key=>value...)"
562 Set the "MOTIF_WM_HINTS" property on $window (an XID).
563 These hints control window decorations and "modal" state. It
565 originated in the Motif "mwm" window manager but is recognised by
566 most other window managers. It should be set on a toplevel window
567 before mapping. Changes made later might not affect what the
568 window manager does.
569 X11::Protocol::WM::set_motif_wm_hints
571 ($X, $dialog_window,
572 input_mode => "full_application_modal");
573 $X->MapWindow ($dialog_window);
574 Ordinary windows generally don't need to restrict their decorations
576 etc, but something special like a clock or gadget might benefit.
577 X11::Protocol::WM::set_motif_wm_hints
579 ($X, $my_gadget_window,
580 functions => 4+32, # move+close
581 decorations => 1+4+8); # border+title+menu
582 The key/value arguments are
584 functions => integer bits
586 decorations => integer bits
587 input_mode => enum string or integer
588 status => integer bits
589 "functions" is what actions the window manager should offer to the
591 user in a drop-down menu or similar. It's an integer bitwise OR of
592 the following values. If not given then the default is normally
593 all functions.
594 bit actions offered
596 --- ---------------
597 1 all functions
598 2 resize window
599 4 move window
600 8 minimize, to iconify
601 16 maximize, to full-screen (with a frame still)
602 32 close window
603 "decorations" is what visual decorations the window manager should
605 show around the window. It's an integer bitwise OR of the
606 following values. If not given then the default is normally all
607 decorations.
608 bit decorations displayed
610 --- ---------------------
611 1 all decorations
612 2 border around the window
613 4 resizeh, handles to resize by dragging
614 8 title bar, showing WM_NAME
615 16 menu, drop-down menu of the "functions" above
616 32 minimize button, to iconify
617 64 maximize button, to full-screen
618 "input_mode" allows a window to be "modal", meaning the user should
620 interact only with $window. The window manager will generally keep
621 it on top, not move the focus to other windows, etc. The value is
622 one of the following strings or corresponding integer,
623 string integer
625 "modeless" 0 not modal (the default)
626 "primary_application_modal" 1 modal to its "transient for"
627 "system_modal" 2 modal to the whole display
628 "full_application_modal" 3 modal to the current client
629 "primary_application_modal" means $window is modal for the
631 "WM_TRANSIENT_FOR" set on $window (see "WM_TRANSIENT_FOR" above),
632 but other windows on the display can be used normally.
633 "full_application_modal" means modal for all windows of the same
634 client, but other clients can be used normally.
635 Modal behaviour is important for good user interaction and
637 therefore ought to be implemented by a window manager, but a good
638 program should be prepared to do something with input on other
639 windows.
640 "status" field is a bitwise OR of the following bits (only one
642 currently).
643 bit
645 1 tearoff menu window
646 Tearoff menu flag is intended for tearoff menus, as the name
648 suggests.
649 X11::Protocol::WM::set_motif_wm_hints
651 ($X, $my_tearoff_window, status => 1);
652 Motif "mwm" will expand the window to make it wide enough for the
654 "WM_NAME" in the frame title bar. Otherwise a title is generally
655 truncated to as much as fits the window's current width. Expanding
656 can be good for tearoffs where the title bar is some originating
657 item name etc which the user should see. But don't be surprised if
658 this flag is ignored by other window managers.
659 Perhaps in the future the individual bits above will have some
661 symbolic names. Either constants or string values interpreted.
662 What would a possible "get_hints()" return, and what might be
663 convenient to add/subtract bits?
664 See /usr/include/Xm/MwmUtil.h on the hints bits, and see "mwm"
666 sources WmWinInfo.c "ProcessWmWindowTitle()" for the "status"
667 tearoff window flag.
668 _NET_FRAME_EXTENTS
670 "my ($left,$right, $top,$bottom) =
671 X11::Protocol::WM::get_net_frame_extents ($X, $window)"
672 Get the "_NET_FRAME_EXTENTS" property from $window.
673 This is set on top-level windows by the window manager to report
675 how many pixels of frame or decoration it has added around $window.
676 If there's no such property set then the return is an empty list.
678 So for example
679 my ($left,$right,$top,$bottom)
681 = get_net_frame_extents ($X, $window)
682 or print "no frame extents";
683 my ($left,$right,$top,$bottom)
685 = get_net_frame_extents ($X, $window);
686 if (! defined $left) {
687 print "no frame extents";
688 }
689 A client might look at the frame size if moving a window
691 programmatically so as not to put the title bar etc off-screen.
692 Oldish window managers might not provide this information though.
693 _NET_WM_PID
695 "X11::Protocol::WM::set_net_wm_pid ($X, $window)"
696 "X11::Protocol::WM::set_net_wm_pid ($X, $window, $pid)"
697 "X11::Protocol::WM::set_net_wm_pid ($X, $window, undef)"
698 Set the "_NET_WM_PID" property on $window to the given $pid process
699 ID, or to the $$ current process ID if omitted. (See perlvar for
700 $$.) If $pid is "undef" then the property is deleted.
701 A window manager or similar might use the PID to forcibly kill an
703 unresponsive client. It's only useful if "WM_CLIENT_MACHINE"
704 (above) is set too, to know where the client is running.
705 _NET_WM_STATE
707 An EWMH compliant window manager maintains a set of state flags for
708 each client window. A state is an atom such as
709 "_NET_WM_STATE_FULLSCREEN" and each such state can be present or
710 absent. The supported states are listed in "_NET_SUPPORTED". Any
711 client can ask the window manager to change states on any window. A
712 client might be able to ask for an initial set of states for a new
713 window (see "set_net_wm_state()" below). Possible states include
714 _NET_WM_STATE_MODAL
716 The window is modal to its "WM_TRANSIENT_FOR" parent or if
717 "WM_TRANSIENT_FOR" not set then modal to its window group.
718 See "_MOTIF_WM_HINTS" to set modal with the Motif style hints.
720 _NET_WM_STATE_STICKY
722 The window is kept in a fixed position on screen when the desktop
723 scrolls.
724 _NET_WM_STATE_MAXIMIZED_VERT
726 _NET_WM_STATE_MAXIMIZED_HORZ
727 The window is maximum size vertically or horizontally or both. The
728 window still has its surrounding decoration and the size should
729 obey size increments specified in "WM_NORMAL_HINTS".
730 _NET_WM_STATE_FULLSCREEN
732 The window is the full screen with no decoration around it, thus
733 being the full screen.
734 The window manager remembers the "normal" size of the window so
736 that when maximize or fullscreen state is removed the previous size
737 is restored.
738 _NET_WM_STATE_SHADED
740 The window is "shaded" which generally means its title bar is
741 displayed but none of the client window. This is an alternative to
742 iconifying a window.
743 _NET_WM_STATE_SKIP_TASKBAR
745 _NET_WM_STATE_SKIP_PAGER
746 Don't show the window on a task bar or in a pager, respectively.
747 _NET_WM_STATE_HIDDEN (read-only)
749 This state is set by the window manger when the window is iconified
750 or similar and so does not appear on screen. Clients cannot change
751 this.
752 _NET_WM_STATE_ABOVE
754 _NET_WM_STATE_BELOW
755 The window is kept above or below other client windows. The
756 stacking order maintained is roughly
757 top
759 +-----------------------------+
760 | _NET_WM_WINDOW_TYPE_DOCK | "DOCK" panels (etc) on top,
761 +-----------------------------+ except perhaps FULLSCREEN
762 | _NET_WM_STATE_ABOVE | windows above those panels
763 +-----------------------------+ when focused
764 | normal |
765 +-----------------------------+
766 | _NET_WM_STATE_BELOW |
767 +-----------------------------+
768 | _NET_WM_WINDOW_TYPE_DESKTOP |
769 +-----------------------------+
770 bottom
771 _NET_WM_STATE_DEMANDS_ATTENTION
773 The window should be brought to the attention of the user in some
774 way. A client sets this and the window manager clears it after the
775 window has received user attention (which might mean keyboard focus
776 or similar).
777 The following functions get or set the states.
779 "change_net_wm_state($X, $window, $action, $state, key=>value,...)"
781 Change one of the "_NET_WM_STATE" state flags on $window by sending
782 a message to the window manager. For example,
783 change_net_wm_state ($X, $window, "toggle", "FULLSCREEN");
785 $window must be a managed window, ie. must have had its initial
787 "MapWindow()" and not be an override-redirect. If that's not so or
788 if there's no window manager or it doesn't have EWMH then this
789 change message will have no effect.
790 $action is a string or integer how to change the state,
792 "remove" 0
794 "add" 1
795 "toggle" 2
796 $state is a string such as "FULLSCREEN" or an atom integer such as
798 "$X->atom("_NET_WM_STATE_FULLSCREEN")".
799 The further optional key/value parameters are
801 state2 => string or atom
803 source => "none", "normal", "user", 0,1,2
804 root => integer XID, or undef
805 A change message can act on one or two states. For two states the
807 second is "state2". For example to maximize vertically and
808 horizontally in one operation,
809 change_net_wm_state ($X, $window, "add", "MAXIMIZED_VERT",
811 state2 => "MAXIMIZED_HORZ");
812 "source" is where the change request came from. The default is
814 "normal" which means a normal application. "user" is for a user-
815 interface control program such as a pager. ("none"=0 is what
816 clients prior to EWMH 1.2 gave.)
817 "root" is the root window (integer XID) of $window. If "undef" or
819 not given then it's found with "$X->QueryTree()". If you already
820 know the root then giving it avoids that round-trip query.
821 "@strings = get_net_wm_state ($X, $window)"
823 "@atoms = get_net_wm_state_atoms ($X, $window)"
824 Get the "_NET_WM_STATE" property from $window.
825 "get_net_wm_state()" returns a list of strings such as
826 "FULLSCREEN". "get_net_wm_state_atoms()" returns a list of atom
827 integers such as "$X->atom('_NET_WM_STATE_FULLSCREEN')". In both
828 cases if there's no such property or if it's empty then return an
829 empty list.
830 "set_net_wm_state ($X, $window, $state,...)"
832 Set the "_NET_WM_STATE" property on $window. Each $state can be a
833 string such as "FULLSCREEN" or an atom integer such as
834 "$X->atom('_NET_WM_STATE_FULLSCREEN')".
835 A client can set "_NET_WM_STATE" on a new window to tell the window
837 manager of desired initial states. However this is only a "should"
838 in the EWMH spec so it might not be obeyed.
839 # initial desired state
841 set_net_wm_state ($X, $window,
842 "MAXIMIZED_HORZ", "MAXIMIZED_VERT");
843 After the window is managed by the window manager (once mapped)
845 clients should not set "_NET_WM_STATE" but instead ask the window
846 manager with "change_net_wm_state()" per above.
847 _NET_WM_USER_TIME
849 "set_net_wm_user_time ($X, $window, $time)"
850 Set the "_NET_WM_USER_TIME" property on $window.
851 $time should be a server time value (an integer) from the last user
853 keypress etc event in $window. Or when $window is created then the
854 time from the event which caused it to be opened.
855 On a newly created window a special $time value 0 means the window
857 should not receive the focus when mapped -- assuming the window
858 manager recognises "_NET_WM_USER_TIME" of course.
859 If the client has the active window it should update
861 "_NET_WM_USER_TIME" for every user input. Generally KeyPress and
862 ButtonPress events are user input, but KeyRelease and ButtonRelease
863 are not since it's the Press events which are the user actively
864 doing something.
865 The window manager might use "_NET_WM_USER_TIME" to control focus
867 and/or stacking order so that for example a slow popup doesn't
868 steal the focus if you've gone to another window to do other work
869 in the interim.
870 _NET_WM_WINDOW_TYPE
872 "X11::Protocol::WM::set_net_wm_window_type ($X, $window, $window_type)"
873 Set the "_NET_WM_WINDOW_TYPE" property on $window (an XID).
874 $window_type can be a type string as follows from the EWMH,
875 "NORMAL"
877 "DIALOG"
878 "DESKTOP"
879 "DOCK"
880 "TOOLBAR"
881 "MENU"
882 "UTILITY"
883 "SPLASH"
884 $window_type can also be an integer atom such as
886 "$X->atom('_NET_WM_WINDOW_TYPE_DIALOG')".
887 Frame to Client
889 "$window = X11::Protocol::WM::frame_window_to_client ($X, $frame)"
890 Return the client window (XID) contained within window manager
891 $frame window (an XID). $frame is usually an immediate child of
892 the root window.
893 If no client window can be found in $frame then return "undef".
895 This might happen if $frame is an icon window or similar created by
896 the window manager itself, or an override-redirect client without a
897 frame, or if there's no window manager running at all. In the
898 latter two cases $frame would be the client already.
899 The strategy is to look at $frame and down the window tree seeking
901 a "WM_STATE" property which the window manager puts on a client's
902 toplevel when mapped. The search depth and total windows are
903 limited in case the window manager does its decoration in some
904 ridiculous way or the client uses excessive windows (which would be
905 traversed if there's no window manager).
906 +-rootwin--------------------------+
908 | |
909 | |
910 | +-frame-win--------+ |
911 | | +-client-win---+ | |
912 | | | WM_STATE ... | | |
913 | | | | | |
914 | | +--------------+ | |
915 | +------------------+ |
916 | |
917 +----------------------------------+
918 Care is taken not to error out if some windows are destroyed during
920 the search. The windows may belong to other clients and could be
921 destroyed at any time. If $frame itself doesn't exist then the
922 return is "undef".
923 This function is similar to what "xwininfo" and similar programs do
925 to go from a toplevel root window child down to the client window,
926 per dmsimple.c "Select_Window()" or Xlib "XmuClientWindow()". (See
927 also X11::Protocol::ChooseWindow.)
928 Virtual Root
930 Some window managers use a "virtual root" window covering the entire
931 screen. Application windows or frame windows are then children of that
932 virtual root. This can help the window manager implement a large
933 desktop or multiple desktops, though it tends to fail in subtle ways
934 with various root oriented programs, including for example xsetroot(1)
935 or the click-to-select in xwininfo(1) and xprop(1).
936 "$window = X11::Protocol::WM::root_to_virtual_root ($X, $root)"
938 If the window manager is using a virtual root then return that
939 window XID. If not then return "undef".
940 The current implementation searches for a window with an
942 "__SWM_VROOT" property, as per the "swm", "tvtwm" and "amiwm"
943 window managers, and as used by the "xscreensaver" program and
944 perhaps some versions of KDE.
945 There's nothing yet for EWMH "_NET_VIRTUAL_ROOTS". Do any window
947 managers use it? Is "_NET_CURRENT_DESKTOP" an index into that
948 virtual roots list?
949 (See X11::Protocol::XSetRoot for changing the background of a root
951 or virtual root.)
952
954 Nothing is exported by default, but the functions can be requested in
955 usual "Exporter" style,
956 use X11::Protocol::WM 'set_wm_hints';
958 set_wm_hints ($X, $window, input => 1, ...);
959 Or just call with full package name
961 use X11::Protocol::WM;
963 X11::Protocol::WM::set_wm_hints ($X, $window, input => 1, ...);
964 There's no ":all" tag since this module is meant as a grab-bag of
966 functions and to import as-yet unknown things would be asking for name
967 clashes.
968
970 Not much attention is paid to text on an EBCDIC system. Wide char
971 strings probably work, but byte strings may go straight through where
972 they ought to be re-coded to Latin-1. But the same probably applies to
973 parts of the core "X11::Protocol" such as "$X->atom_name()" where you'd
974 want to convert Latin-1 from the server to native EBCDIC.
975
977 X11::Protocol, X11::Protocol::Other, X11::Protocol::ChooseWindow,
978 X11::Protocol::XSetRoot
979 "Inter-Client Communication Conventions Manual",
981 /usr/share/doc/xorg-docs/specs/ICCCM/icccm.txt.gz,
982 <http://www.x.org/docs/ICCCM/>
983 "Compound Text Encoding" specification.
985 /usr/share/doc/xorg-docs/specs/CTEXT/ctext.txt.gz,
986 <http://www.x.org/docs/CTEXT/>
987 "Extended Window Manager Hints" which is the "_NET_WM" things.
989 <http://www.freedesktop.org/wiki/Specifications/wm-spec>,
990 <http://mail.gnome.org/archives/wm-spec-list/>
991 wmctrl(1), xwit(1), X(7)
993
995 <http://user42.tuxfamily.org/x11-protocol-other/index.html>
996
998 Copyright 2011, 2012, 2013, 2014, 2016 Kevin Ryde
999 X11-Protocol-Other is free software; you can redistribute it and/or
1001 modify it under the terms of the GNU General Public License as
1002 published by the Free Software Foundation; either version 3, or (at
1003 your option) any later version.
1004 X11-Protocol-Other is distributed in the hope that it will be useful,
1006 but WITHOUT ANY WARRANTY; without even the implied warranty of
1007 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
1008 General Public License for more details.
1009 You should have received a copy of the GNU General Public License along
1011 with X11-Protocol-Other. If not, see <http://www.gnu.org/licenses/>.
1012perl v5.28.0 2016-02-18 X11::Protocol::WM(3)