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

EXPORTS

982       Nothing is exported by default, but the functions can be requested in
983       usual "Exporter" style,
984
985           use X11::Protocol::WM 'set_wm_hints';
986           set_wm_hints ($X, $window, input => 1, ...);
987
988       Or just call with full package name
989
990           use X11::Protocol::WM;
991           X11::Protocol::WM::set_wm_hints ($X, $window, input => 1, ...);
992
993       There's no ":all" tag since this module is meant as a grab-bag of
994       functions and to import as-yet unknown things would be asking for name
995       clashes.
996

BUGS

998       Not much attention is paid to text on an EBCDIC system.  Wide char
999       strings probably work, but byte strings may go straight through whereas
1000       they ought to be re-coded to Latin-1.  But the same probably applies to
1001       parts of the core "X11::Protocol" such as "$X->atom_name()" where you'd
1002       want to convert Latin-1 from the server to native EBCDIC.
1003

SEE ALSO

1005       X11::Protocol, X11::Protocol::Other, X11::Protocol::ChooseWindow,
1006       X11::Protocol::XSetRoot
1007
1008       "Inter-Client Communication Conventions Manual",
1009       /usr/share/doc/xorg-docs/icccm/icccm.txt.gz,
1010       <http://www.x.org/docs/ICCCM/>
1011
1012       "Compound Text Encoding" specification.
1013       /usr/share/doc/xorg-docs/ctext/ctext.txt.gz,
1014       <http://www.x.org/docs/CTEXT/>
1015
1016       "Extended Window Manager Hints" which is the "_NET_WM" things.
1017       <http://www.freedesktop.org/wiki/Specifications/wm-spec>,
1018       <http://mail.gnome.org/archives/wm-spec-list/>
1019
1020       wmctrl(1), xwit(1), X(7)
1021

HOME PAGE

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

LICENSE

1026       Copyright 2011, 2012, 2013, 2014, 2016, 2017, 2018, 2019 Kevin Ryde
1027
1028       X11-Protocol-Other is free software; you can redistribute it and/or
1029       modify it under the terms of the GNU General Public License as
1030       published by the Free Software Foundation; either version 3, or (at
1031       your option) any later version.
1032
1033       X11-Protocol-Other is distributed in the hope that it will be useful,
1034       but WITHOUT ANY WARRANTY; without even the implied warranty of
1035       MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
1036       General Public License for more details.
1037
1038       You should have received a copy of the GNU General Public License along
1039       with X11-Protocol-Other.  If not, see <http://www.gnu.org/licenses/>.
1040
1041
1042
1043perl v5.36.0                      2023-01-20              X11::Protocol::WM(3)
Impressum