1X11::Protocol::WM(3)  User Contributed Perl Documentation X11::Protocol::WM(3)
2
3
4

NAME

6       X11::Protocol::WM -- window manager things for client programs
7

SYNOPSIS

9        use X11::Protocol::WM;
10

DESCRIPTION

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
16           /usr/share/doc/xorg-docs/icccm/icccm.txt.gz
17
18           <http://www.freedesktop.org/wiki/Specifications/wm-spec>
19
20   Usual Properties
21       Every toplevel client window should usually
22
23       ·   "set_wm_class()" to identify itself to other programs (see
24           "WM_CLASS" below).
25
26       ·   "set_wm_name()" and "set_wm_icon_name()" for user-visible window
27           name (see "WM_NAME, WM_ICON_NAME" below).
28
29       ·   "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
33       Then optionally,
34
35       ·   If you have an icon then "set_wm_hints()" with a bitmap or a window
36           (see "WM_HINTS" below).
37
38       ·   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
42       ·   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

FUNCTIONS

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
54       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
61       "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
66           $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
71   WM_CLASS
72       "X11::Protocol::WM::set_wm_class ($X, $window, $instance, $class)"
73           Set the "WM_CLASS" property on $window (an XID).
74
75           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
79           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
85               X11::Protocol::WM::set_wm_class ($X, $window,
86                                                "myprog", "MyProg");
87
88           $instance and $class must be ASCII or Latin-1 only.  Wide-char
89           strings which are Latin-1 are converted as necessary.
90
91   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
96           $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
99           Usually a machine name is ASCII-only, but anything per "Text
100           Properties" above is accepted.
101
102       "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
107           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
111           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
116   WM_COMMAND
117       "X11::Protocol::WM::set_wm_command ($X, $window, $command, $arg...)"
118           Set the "WM_COMMAND" property on $window (an XID).
119
120           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
124               X11::Protocol::WM::set_wm_command ($X, $window,
125                                                  'myprog',
126                                                  '--option',
127                                                  'filename.txt');
128
129           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
133           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
137           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
141           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
150           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
157   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
165           $root is the root window to read.  If omitted then read the
166           "$X->root" default.
167
168           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
173   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
177               X11::Protocol::WM::set_wm_hints
178                   ($X, $my_window,
179                    input         => 1,
180                    initial_state => 'NormalState',
181                    icon_pixmap   => $my_pixmap);
182
183           The key/value parameters are as follows.
184
185               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
195           "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
200           "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
206           "initial_state" is a string or number.  The ICCCM allows
207           "NormalState" or "IconicState" as initial states.
208
209               "NormalState"       1
210               "IconicState"       3
211
212           "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
218           "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
226           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
229           "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
237           "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
241       "(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
245               input => 1,
246               icon_pixmap => 1234,
247               ...
248
249           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
253           The return can be put into a hash to get fields by name,
254
255               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
260           "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
264           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
269       "(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
275               X11::Protocol::WM::set_wm_hints ($X, $window,
276                                                urgency => 1);
277
278           A value "undef" means delete a field,
279
280               X11::Protocol::WM::set_wm_hints ($X, $window,
281                                                icon_pixmap => undef,
282                                                icon_mask   => undef);
283
284           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
288       "$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
293           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
297       "(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
303   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
308           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
314       "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
318           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
324   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
330               set_wm_normal_hints ($X, $window,
331                                    min_width => 200,
332                                    min_height => 100);
333
334           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
340           The key/value parameters are
341
342               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
362           "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
369           "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
377           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
380           "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
387           "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
395           "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
401           "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
407               2         integer
408               1.125     decimal, meaning 1125/1000
409               2/3       fraction
410               1.5/4.5   fraction with decimals
411
412           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
417           "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
424           "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
428       "$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
434           The $X parameter is used to interpret "win_gravity" enum values.
435           There's no communication with the server.
436
437       "($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
443   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
448               X11::Protocol::WM::set_wm_protocols
449                 ($X, $window, 'WM_DELETE_WINDOW', '_NET_WM_PING')
450
451           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
457   WM_STATE
458       The window manager maintains a state for each client window it manages,
459
460           WithdrawnState
461           NormalState
462           IconicState
463
464       "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
470       "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
474       "($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
480           $state returned is an enum string, or an integer value if
481           "$X->{'do_interp'}" is disabled or the value unrecognised.
482
483               "WithdrawnState"    0      not displayed
484               "NormalState"       1      window displayed
485               "IconicState"       3      iconified in some way
486
487               "ZoomState"         2      \ no longer in ICCCM
488               "InactiveState"     4      /   (zoom meant maximized)
489
490           $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
495           $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
500           "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
507       "($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
512           $X is used for "$X->{'do_interp'}" but there's no communication
513           with the server.
514
515       "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
520           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
525           $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
529           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
533       "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
538           If there's no window manager running then the "UnmapWindow()"
539           unmaps and the "UnmapNotify" message does nothing.
540
541           $root should be the root window of $window.  If not given or
542           "undef" then it's obtained by a "QueryTree()" here.
543
544           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
549           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
554           $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
562           Any client can withdraw any toplevel window, but it's unusual for a
563           client to withdraw windows which are not its own.
564
565   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
569           $transient_for is another window XID, or "undef" if $window is not
570           transient for anything so "WM_TRANSIENT_FOR" should be deleted.
571
572           "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
577   _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
581           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
587               X11::Protocol::WM::set_motif_wm_hints
588                 ($X, $dialog_window,
589                  input_mode => "full_application_modal");
590               $X->MapWindow ($dialog_window);
591
592           Ordinary windows generally don't need to restrict their decorations
593           etc, but something special like a clock or gadget might benefit.
594
595               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
600           The key/value arguments are
601
602               functions   => integer bits
603               decorations => integer bits
604               input_mode  => enum string or integer
605               status      => integer bits
606
607           "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
612               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
621           "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
626               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
636           "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
641                 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
647           "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
653           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
658           "status" field is a bitwise OR of the following bits (only one
659           currently).
660
661               bit
662                1    tearoff menu window
663
664           Tearoff menu flag is intended for tearoff menus, as the name
665           suggests.
666
667               X11::Protocol::WM::set_motif_wm_hints
668                 ($X, $my_tearoff_window, status => 1);
669
670           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
677           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
682           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
686   _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
691           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
694           If there's no such property set then the return is an empty list.
695           So for example
696
697               my ($left,$right,$top,$bottom)
698                     = get_net_frame_extents ($X, $window)
699                 or print "no frame extents";
700
701               my ($left,$right,$top,$bottom)
702                 = get_net_frame_extents ($X, $window);
703               if (! defined $left) {
704                 print "no frame extents";
705               }
706
707           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
711   _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
719           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
723   _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
730           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
737       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
741       _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
745           See "_MOTIF_WM_HINTS" to set modal with the Motif style hints.
746
747       _NET_WM_STATE_STICKY
748           The window is kept in a fixed position on screen when the desktop
749           scrolls.
750
751       _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
757       _NET_WM_STATE_FULLSCREEN
758           The window is the full screen with no decoration around it, thus
759           being the full screen.
760
761           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
765       _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
770       _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
774       _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
779       _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
784                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
798       _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
804       The following functions get or set the states.
805
806       "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
810               change_net_wm_state ($X, $window, "toggle", "FULLSCREEN");
811
812           $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
817           $action is a string or integer how to change the state,
818
819               "remove"       0
820               "add"          1
821               "toggle"       2
822
823           $state is a string such as "FULLSCREEN" or an atom integer such as
824           "$X->atom("_NET_WM_STATE_FULLSCREEN")".
825
826           The further optional key/value parameters are
827
828               state2   => string or atom
829               source   => "none", "normal", "user", 0,1,2
830               root     => integer XID, or undef
831
832           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
836               change_net_wm_state ($X, $window, "add", "MAXIMIZED_VERT",
837                                    state2 => "MAXIMIZED_HORZ");
838
839           "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
844           "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
848       "@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
857       "set_net_wm_state ($X, $window, $state,...)"
858           Set the "_NET_WM_STATE" property on $window.  Each $state can be
859
860              string like "FULLSCREEN"
861              string like "_NET_WM_STATE_FULLSCREEN"
862              integer atom of a name like _NET_WM_STATE_FULLSCREEN
863
864           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
868               # initial desired state
869               set_net_wm_state ($X, $window,
870                                 "MAXIMIZED_HORZ", "MAXIMIZED_VERT");
871
872           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
876   _NET_WM_USER_TIME
877       "set_net_wm_user_time ($X, $window, $time)"
878           Set the "_NET_WM_USER_TIME" property on $window.
879
880           $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
884           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
888           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
894           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
899   _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
904               string like "NORMAL"
905               integer atom of a name like _NET_WM_WINDOW_TYPE_NORMAL
906
907           The window types from from the EWMH are as follows.
908
909               "NORMAL"
910               "DIALOG"
911               "DESKTOP"
912               "DOCK"
913               "TOOLBAR"
914               "MENU"
915               "UTILITY"
916               "SPLASH"
917
918   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
924           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
930           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
937               +-rootwin--------------------------+
938               |                                  |
939               |                                  |
940               |    +-frame-win--------+          |
941               |    | +-client-win---+ |          |
942               |    | | WM_STATE ... | |          |
943               |    | |              | |          |
944               |    | +--------------+ |          |
945               |    +------------------+          |
946               |                                  |
947               +----------------------------------+
948
949           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
954           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
959   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
967       "$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
971           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
976           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
980           (See X11::Protocol::XSetRoot for changing the background of a root
981           or virtual root.)
982

EXPORTS

984       Nothing is exported by default, but the functions can be requested in
985       usual "Exporter" style,
986
987           use X11::Protocol::WM 'set_wm_hints';
988           set_wm_hints ($X, $window, input => 1, ...);
989
990       Or just call with full package name
991
992           use X11::Protocol::WM;
993           X11::Protocol::WM::set_wm_hints ($X, $window, input => 1, ...);
994
995       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

BUGS

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

SEE ALSO

1007       X11::Protocol, X11::Protocol::Other, X11::Protocol::ChooseWindow,
1008       X11::Protocol::XSetRoot
1009
1010       "Inter-Client Communication Conventions Manual",
1011       /usr/share/doc/xorg-docs/icccm/icccm.txt.gz,
1012       <http://www.x.org/docs/ICCCM/>
1013
1014       "Compound Text Encoding" specification.
1015       /usr/share/doc/xorg-docs/ctext/ctext.txt.gz,
1016       <http://www.x.org/docs/CTEXT/>
1017
1018       "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
1022       wmctrl(1), xwit(1), X(7)
1023

HOME PAGE

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

LICENSE

1028       Copyright 2011, 2012, 2013, 2014, 2016, 2017, 2018, 2019 Kevin Ryde
1029
1030       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
1035       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
1040       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/>.
1042
1043
1044
1045perl v5.30.1                      2020-01-30              X11::Protocol::WM(3)
Impressum