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

EXPORTS

954       Nothing is exported by default, but the functions can be requested in
955       usual "Exporter" style,
956
957           use X11::Protocol::WM 'set_wm_hints';
958           set_wm_hints ($X, $window, input => 1, ...);
959
960       Or just call with full package name
961
962           use X11::Protocol::WM;
963           X11::Protocol::WM::set_wm_hints ($X, $window, input => 1, ...);
964
965       There's no ":all" tag since this module is meant as a grab-bag of
966       functions and to import as-yet unknown things would be asking for name
967       clashes.
968

BUGS

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

SEE ALSO

977       X11::Protocol, X11::Protocol::Other, X11::Protocol::ChooseWindow,
978       X11::Protocol::XSetRoot
979
980       "Inter-Client Communication Conventions Manual",
981       /usr/share/doc/xorg-docs/specs/ICCCM/icccm.txt.gz,
982       <http://www.x.org/docs/ICCCM/>
983
984       "Compound Text Encoding" specification.
985       /usr/share/doc/xorg-docs/specs/CTEXT/ctext.txt.gz,
986       <http://www.x.org/docs/CTEXT/>
987
988       "Extended Window Manager Hints" which is the "_NET_WM" things.
989       <http://www.freedesktop.org/wiki/Specifications/wm-spec>,
990       <http://mail.gnome.org/archives/wm-spec-list/>
991
992       wmctrl(1), xwit(1), X(7)
993

HOME PAGE

995       <http://user42.tuxfamily.org/x11-protocol-other/index.html>
996

LICENSE

998       Copyright 2011, 2012, 2013, 2014, 2016 Kevin Ryde
999
1000       X11-Protocol-Other is free software; you can redistribute it and/or
1001       modify it under the terms of the GNU General Public License as
1002       published by the Free Software Foundation; either version 3, or (at
1003       your option) any later version.
1004
1005       X11-Protocol-Other is distributed in the hope that it will be useful,
1006       but WITHOUT ANY WARRANTY; without even the implied warranty of
1007       MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
1008       General Public License for more details.
1009
1010       You should have received a copy of the GNU General Public License along
1011       with X11-Protocol-Other.  If not, see <http://www.gnu.org/licenses/>.
1012
1013
1014
1015perl v5.28.1                      2016-02-18              X11::Protocol::WM(3)
Impressum