Provided by: libx11-protocol-other-perl_31-1_all bug

NAME

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

SYNOPSIS

        use X11::Protocol::WM;

DESCRIPTION

       This is some window manager related functions for use by client programs, as per the
       "Inter-Client Communication Conventions Manual" and some of the Net-WM "Extended Window
       Manager Hints".

           /usr/share/doc/xorg-docs/icccm/icccm.txt.gz

           <http://www.freedesktop.org/wiki/Specifications/wm-spec>

   Usual Properties
       Every toplevel client window should usually

       ·   "set_wm_class()" to identify itself to other programs (see "WM_CLASS" below).

       ·   "set_wm_name()" and "set_wm_icon_name()" for user-visible window name (see "WM_NAME,
           WM_ICON_NAME" below).

       ·   "set_wm_client_machine_from_syshostname()" and "set_net_wm_pid()" for the running
           process (see "WM_CLIENT_MACHINE" and "_NET_WM_PID" below).

       Then optionally,

       ·   If you have an icon then "set_wm_hints()" with a bitmap or a window (see "WM_HINTS"
           below).

       ·   If the user gave an initial size or position on the command line then
           "set_wm_normal_hints()".  The same if the program has min/max sizes or aspect ratio
           desired (see "WM_NORMAL_HINTS" below).

       ·   If a command to re-run the program can be constructed then "set_wm_command()", and
           preferably keep that up-to-date with changes such as currently open file etc (see
           "WM_COMMAND" below).

FUNCTIONS

   Text Properties
       Property functions taking text strings such as "set_wm_name()" accept either byte strings
       or wide char strings (Perl 5.8 up).  Byte strings are presumed to be Latin-1 and set as
       "STRING" type in properties.  Wide char strings are stored as "STRING" if entirely
       Latin-1, or encoded to "COMPOUND_TEXT" for other chars (see Encode::X11).

       In the future perhaps the string functions could accept some sort of compound text object
       to represent segments of various encodings to become "COMPOUND_TEXT", together with
       manipulations for such content etc.  If text is bytes in one of the ICCCM encodings then
       it might save work to represent it directly as "COMPOUND_TEXT" segments rather than going
       to wide chars and back again.

       "set_text_property ($X, $window, $prop, $str)"
           Set the given $prop (integer atom) property on $window (integer XID) using either
           "STRING" or "COMPOUND_TEXT" as described above.  If $str is "undef" then $prop is
           deleted.

           $str is limited to "$X->maximum_request_length()".  In theory longer strings can be
           stored by piecewise, but there's no attempt to do that here.  The maximum request
           limit is at least 16384 bytes and the server may allow more, possibly much more.

   WM_CLASS
       "X11::Protocol::WM::set_wm_class ($X, $window, $instance, $class)"
           Set the "WM_CLASS" property on $window (an XID).

           This property may be used by the window manager to lookup settings and preferences for
           the program through the X Resource system (see "RESOURCES" in X(7)) or similar.

           Usually the instance name is the program command such as "xterm" and the class name
           something like "XTerm".  Some programs have command line options to set the class
           and/or instance so the user can have different window manager settings applied to a
           particular running copy of a program.

               X11::Protocol::WM::set_wm_class ($X, $window,
                                                "myprog", "MyProg");

           $instance and $class must be ASCII or Latin-1 only.  Wide-char strings which are
           Latin-1 are converted as necessary.

   WM_CLIENT_MACHINE
       "X11::Protocol::WM::set_wm_client_machine ($X, $window, $hostname)"
           Set the "WM_CLIENT_MACHINE" property on $window to $hostname (a string).

           $hostname should be the name of the client machine as seen from the server.  If
           $hostname is "undef" then the property is deleted.

           Usually a machine name is ASCII-only, but anything per "Text Properties" above is
           accepted.

       "X11::Protocol::WM::set_wm_client_machine_from_syshostname ($X, $window)"
           Set the "WM_CLIENT_MACHINE" property on $window using the Sys::Hostname module.

           If "Sys::Hostname" can't determine a hostname by its various gambits then currently
           the property is deleted.  Would it be better to leave it unchanged, or return a flag
           to say if set?

           Some of the "Sys::Hostname" cases might return "localhost".  That's put through
           unchanged, on the assumption that it would be when there's no networking beyond the
           local host so client and server are on the same machine and name "localhost" suffices.

   WM_COMMAND
       "X11::Protocol::WM::set_wm_command ($X, $window, $command, $arg...)"
           Set the "WM_COMMAND" property on $window (an XID).

           This should be a program name and argument strings which will restart the client.
           $command is the program name, followed by any argument strings.

               X11::Protocol::WM::set_wm_command ($X, $window,
                                                  'myprog',
                                                  '--option',
                                                  'filename.txt');

           The command should start the client in its current state, so the command might include
           a filename, command line options for current settings, etc.

           Non-ASCII is allowed per "Text Properties" above.  The ICCCM spec is for Latin-1 to
           work on a POSIX Latin-1 system, but how well anything else survives a session manager
           etc is another matter.

           A client can set this at any time, or if participating in the "WM_SAVE_YOURSELF"
           session manager protocol then it should set in response to a "ClientMessage" of
           "WM_SAVE_YOURSELF" .

           For reference, under "mwm" circa 2017, a client with "WM_SAVE_YOURSELF" receives that
           message for the "mwm" Close button ("f.kill") and is expected to respond within a
           timeout (default 1 second), whereupon "mwm" closes the client connection
           ("KillClient").  Unfortunately if both "WM_SAVE_YOURSELF" and "WM_DELETE_WINDOW" then
           "mwm" still does the "WM_SAVE_YOURSELF" and close, defeating the aim of letting
           "WM_DELETE_WINDOW" query the user and perhaps not close.

           The easiest workaround would be use only "WM_DELETE_WINDOW", keep "WM_COMMAND" always
           up-to-date, and be prepared to save state on connection loss.  This is quite
           reasonable anyway actually, since a "WM_SAVE_YOURSELF" message is fairly limited use,
           given that connection loss or other termination could happen at any time so if state
           is important that it'd be prudent to keep it saved.

   WM_ICON_SIZE
       "($min_width,$min_height, $max_width,$max_height, $width_inc,$height_inc) =
       X11::Protocol::WM::get_wm_icon_size($X,$root)"
           Return the window manager's "WM_ICON_SIZE" recommended icon sizes (in pixels) as a
           range, and increment above the minimum.  If there's no "WM_ICON_SIZE" property then
           return an empty list.

           $root is the root window to read.  If omitted then read the "$X->root" default.

           An icon pixmap or window in "WM_HINTS" should be a size in this range.  Many window
           managers don't set a preferred icon size.  32x32 might be typical on a small screen or
           48x48 on a bigger screen.

   WM_HINTS
       "X11::Protocol::WM::set_wm_hints ($X, $window, key=>value, ...)"
           Set the "WM_HINTS" property on $window (an XID).  For example,

               X11::Protocol::WM::set_wm_hints
                   ($X, $my_window,
                    input         => 1,
                    initial_state => 'NormalState',
                    icon_pixmap   => $my_pixmap);

           The key/value parameters are as follows.

               input             integer 0 or 1
               initial_state     enum string or number
               icon_pixmap       pixmap (XID integer), depth 1
               icon_window       window (XID integer)
               icon_x            \ integer coordinate
               icon_y            / integer coordinate
               icon_mask         pixmap (XID integer)
               window_group      window (XID integer)
               urgency           boolean

           "input" is 1 if the client wants the window manager to give $window the keyboard input
           focus.  This will be with "$X->SetInputFocus()", or if "WM_TAKE_FOCUS" is in
           "WM_PROTOCOLS" then instead by a "ClientMessage".

           "input" is 0 if the window manager should not give the client the focus.  This is
           either because $window is output-only, or if "WM_TAKE_FOCUS" is in "WM_PROTOCOLS" then
           because the client will do a "SetInputFocus()" to itself on an appropriate button
           press etc.

           "initial_state" is a string or number.  The ICCCM allows "NormalState" or
           "IconicState" as initial states.

               "NormalState"       1
               "IconicState"       3

           "icon_pixmap" should be a bitmap, ie. a pixmap (XID) with depth 1.  The window manager
           will draw it in suitable contrasting colours.  "1" pixels are foreground and "0" is
           background.  "icon_mask" bitmap is applied to the displayed icon.  It can be used to
           make a non-rectangular icon.

           "icon_window" is a window which the window manager may show when $window is iconified.
           This can be used for a multi-colour icon, done either by a background or by client
           drawing (in response to "Expose" events, or updated periodically for a clock, etc).
           The "icon_window" should be a child of the root and should use the default visual and
           colormap of the screen.  The window manager might resize the window and/or border.

           The window manager might set a "WM_ICON_SIZE" property on the root window for good
           icon sizes.  See "WM_ICON_SIZE" above.

           "window_group" is the XID of a window which is the group leader of a group of top-
           level windows being used by the client.  The window manager might provide a way to
           manipulate the group as a whole, for example to iconify it all.  If iconified then the
           icon hints of the leader are used for the icon.  The group leader can be an unmapped
           window.  It can be convenient to use a never-mapped window as the leader for all
           subsequent windows.

           "urgency" true means the window is important and the window manager should draw the
           user's attention to it in some way.  The client can change this hint at any time to
           change the current importance.

       "(key => $value, ...) = X11::Protocol::WM::get_wm_hints ($X, $window)"
           Return the "WM_HINTS" property from $window.  The return is a list of key/value pairs
           as per "set_wm_hints()" above

               input => 1,
               icon_pixmap => 1234,
               ...

           Only fields with their flag bits set in the hints are included in the return.  If
           there's no "WM_HINTS" at all or or its flags field is zero then the return is an empty
           list.

           The return can be put into a hash to get fields by name,

               my %hints = X11::Protocol::WM::get_wm_hints ($X, $window);
               if (exists $hints{'icon_pixmap'}) {
                 print "icon_pixmap is ", $hints{'icon_pixmap'}, "\n";
               }

           "initial_state" is a string such as "NormalState".  The pixmaps and windows are string
           "None" if set but zero (which is probably unusual).  If "$X->{'do_interp'}" is
           disabled then all are numbers.

           X11R2 Xlib had a bug in its "XSetWMHints()" which chopped off the "window_group" value
           from the hints stored.  The "window_group" field is omitted from the return if the
           data read is missing that field.

       "(key => $value, ...) = X11::Protocol::WM::change_wm_hints ($X, $window, key=>value, ...)"
           Change some fields of the "WM_HINTS" property on $window.  The given key/value fields
           are changed.  Other fields are left alone.  For example,

               X11::Protocol::WM::set_wm_hints ($X, $window,
                                                urgency => 1);

           A value "undef" means delete a field,

               X11::Protocol::WM::set_wm_hints ($X, $window,
                                                icon_pixmap => undef,
                                                icon_mask   => undef);

           The change requires a server round-trip to fetch the current values from $window.  An
           application might prefer to remember its desired hints and send a full
           "set_wm_hints()" each time.

       "$bytes = X11::Protocol::WM::pack_wm_hints ($X, key=>value...)"
           Pack a set of values into a byte string of "WM_HINTS" format.  The key/value arguments
           are per "set_wm_hints()" above and the result is the raw bytes stored in a "WM_HINTS"
           property.

           The $X argument is not actually used currently, but is present in case "initial_state"
           or other values might use an "$X->num()" lookup in the future.

       "(key => $value, ...) = X11::Protocol::WM::unpack_wm_hints ($X, $bytes)"
           Unpack a byte string as a "WM_HINTS" structure.  The return is key/value pairs as per
           "get_wm_hints()" above.  The $X parameter is used for "do_interp".  There's no
           communication with the server.

   WM_NAME, WM_ICON_NAME
       "X11::Protocol::WM::set_wm_name ($X, $window, $name)"
           Set the "WM_NAME" property on $window (an integer XID) to $name (a string).

           The window manager might display this as a title above the window, or in a menu of
           windows, etc.  It can be a Perl 5.8 wide-char string per "Text Properties" above.  A
           good window manager ought to support non-ASCII or non-Latin-1 titles, but how well it
           displays might depend on fonts etc.

       "X11::Protocol::WM::set_wm_icon_name ($X, $window, $name)"
           Set the "WM_ICON_NAME" property on $window (an integer XID) to $name (a string).

           The window manager might display this when $window is iconified.  If $window doesn't
           have an icon (in "WM_HINTS" or from the window manager itself) then this text might be
           all that's shown.  Either way it should be something short.  It can be a Perl 5.8
           wide-char string per "Text Properties" above.

   WM_NORMAL_HINTS
       "X11::Protocol::WM::set_wm_normal_hints ($X, $window, key=>value,...)"
           Set the "WM_NORMAL_HINTS" property on $window (an integer XID).  This is a
           "WM_SIZE_HINTS" structure which tells the window manager what sizes the client would
           like.  For example,

               set_wm_normal_hints ($X, $window,
                                    min_width => 200,
                                    min_height => 100);

           Generally the window manager restricts user resizing to the hint limits.  Most window
           managers use these hints, but of course they're only hints and a good program should
           be prepared for other sizes even if it won't look good or can't do much useful when
           too big or too small etc.

           The key/value parameters are

               user_position      boolean, window x,y is user specified
               user_size          boolean, window width,height is user specified
               program_position   boolean, window x,y is program specified
               program_size       boolean, window width,height is program specified
               min_width          \ integers, min size in pixels
               min_height         /
               max_width          \ integers, max size in pixels
               max_height         /
               base_width         \ integers, size base in pixels
               base_height        /
               width_inc          \ integers, size increment in pixels
               height_inc         /
               min_aspect         \  fraction 2/3 or decimal 2 or 1.5
               min_aspect_num      | or integer num/den up to 0x7FFFFFFF
               min_aspect_den      |
               max_aspect          |
               max_aspect_num      |
               max_aspect_den     /
               win_gravity        WinGravity enum "NorthEast" etc

           "user_position" and "user_size" are flags meaning that the window's x,y or
           width,height (in the usual core "$X->SetWindowAttributes()") were given by the user,
           for example from a "-geometry" command line option.  The window manager will generally
           obey these values and skip any auto-placement or interactive placement it might
           otherwise do.

           "program_position" and "program_size" are flags meaning the window x,y or width,height
           were calculated by the program.  The window manager might override with its own
           positioning or sizing policy.  There's generally no need to set these fields unless
           the program has a definite idea of where and how big it should be.  For a size it's
           enough to set the core window width,height and let the window manager (if there's one
           running) go from there.

           Items shown grouped above must be given together, so for instance if a "min_width" is
           given then "min_height" should be given too.

           "base_width","base_height" and "width_inc","height_inc" ask that the window be a
           certain base size in pixels then a multiple of "inc" pixels above that.  This can be
           used by things like "xterm" which want a fixed size for border or scrollbar and then a
           multiple of the character size above that.  If "base_width","base_height" are not
           given then "min_width","min_height" is the base size.

           "base_width","base_height" can be smaller than "min_width","min_height".  This means
           the size should still be a base+inc multiple, but the first such which is at least the
           min size.  The window manager generally presents the "inc" multiple to the user, so
           that for example on an xterm the user sees a count of characters.  A min size can then
           demand for example a minimum 1x1 or 2x2 character size.

           "min_aspect","max_aspect" ask that the window have a certain minimum or maximum
           width/height ratio.  For example aspect 2/1 means it should be twice as wide as it is
           high.  This is applied to the size above "base_width","base_height", or if base not
           given then to the whole window size.

           "min_aspect_num","min_aspect_den" and "max_aspect_num","max_aspect_den" set numerator
           and denominator values directly (INT32, so maximum 0x7FFF_FFFF).  Or "min_aspect" and
           "max_aspect" accept a single value in various forms which are turned into num/den
           values.

               2         integer
               1.125     decimal, meaning 1125/1000
               2/3       fraction
               1.5/4.5   fraction with decimals

           Values bigger than 0x7FFFFFFF in these forms are reduced proportionally as necessary.
           A Perl floating point value will usually have more bits of precision than 0x7FFFFFFF
           and is truncated to something that fits.

           "win_gravity" is how the client would like to be shifted to make room for any
           surrounding frame the window manager might add.  For example if the program calculated
           the window size and position to ensure the north-east corner is at a desired position,
           then give "win_gravity => "NorthEast"" so that the window manager keeps the north-east
           corner the same when it applies its frame.

           "win_gravity => "Static"" means the frame is put around the window and the window not
           moved at all.  Of course that might mean some of the frame ends up off-screen.

       "$bytes = X11::Protocol::WM::pack_size_hints ($X, key=>value,...)"
           Return a bytes string which is a "WM_SIZE_HINTS" structure made from the given
           key/value parameters.  "WM_SIZE_HINTS" is structure type for "WM_NORMAL_HINTS"
           described above and the key/value parameters are as described above.

           The $X parameter is used to interpret "win_gravity" enum values.  There's no
           communication with the server.

       "($num,$den) = X11::Protocol::WM::aspect_to_num_den ($aspect)"
           Return a pair of INT32 integers 0 to 0x7FFF_FFFF for the given aspect ratio $aspect.
           This is the conversion applied to "min_aspect" and "max_aspect" above.  $aspect can be
           any of the integer, decimal or fraction described.

   WM_PROTOCOLS
       "X11::Protocol::WM::set_wm_protocols ($X, $window, $protocol,...)"
           Set the "WM_PROTOCOLS" property on $window (an XID).  Each argument is a string
           protocol name or an integer atom ID.

               X11::Protocol::WM::set_wm_protocols
                 ($X, $window, 'WM_DELETE_WINDOW', '_NET_WM_PING')

           For example "WM_DELETE_WINDOW" means that when the user clicks the close button the
           window manager sends a "ClientMessage" event rather than doing a "KillClient()".  The
           "ClientMessage" event allows a program to clean-up or ask the user about saving a
           document before exiting, etc.

   WM_STATE
       The window manager maintains a state for each client window it manages,

           WithdrawnState
           NormalState
           IconicState

       "WithdrawnState" means the window is not mapped and the window manager is not managing it.
       A newly created window ("$X->CreateWindow()") is initially "WithdrawnState" and on first
       "$X->MapWindow()" goes to "NormalState" (or to "IconicState" if that's the initial state
       asked for in "WM_HINTS").

       "iconify()" and "withdraw()" below can change the state to iconic or withdrawn.  A window
       can be restored from iconic to normal by a "MapWindow()".

       "($state, $icon_window) = X11::Protocol::WM::get_wm_state ($X, $window)"
           Return the "WM_STATE" property from $window.  This is set by the window manager on
           top-level application windows.  If there's no such property then the return is an
           empty list.

           $state returned is an enum string, or an integer value if "$X->{'do_interp'}" is
           disabled or the value unrecognised.

               "WithdrawnState"    0      not displayed
               "NormalState"       1      window displayed
               "IconicState"       3      iconified in some way

               "ZoomState"         2      \ no longer in ICCCM
               "InactiveState"     4      /   (zoom meant maximized)

           $icon_window returned is the window (integer XID) used by the window manager to
           display an icon of $window.  If there's no such window then $icon_window is "None" (or
           0 if "$X->{'do_interp'}" is disabled).

           $icon_window might be the icon window from the client's "WM_HINTS" or it might be a
           window created by the window manager.  The client can draw into it for animations etc,
           perhaps selecting "Expose" events on it to know when to redraw.

           "WM_STATE" is set by the window manager when a toplevel window is first mapped (or
           perhaps earlier), and then kept up-to-date.  Generally no "WM_STATE" property or a
           "WM_STATE" set to WithdrawnState means the window manager is not managing the window,
           or not yet doing so.  A client can select "PropertyChange" event mask in the usual way
           to listen for "WM_STATE" changes.

       "($state, $icon_window) = X11::Protocol::WM::unpack_wm_state ($X, $bytes)"
           Unpack the bytes of a "WM_STATE" property to a $state and $icon_window as per
           "get_wm_state()" above.

           $X is used for "$X->{'do_interp'}" but there's no communication with the server.

       "X11::Protocol::WM::iconify ($X, $window)"
       "X11::Protocol::WM::iconify ($X, $window, $root)"
           Change $window to "IconicState" by sending a "ClientMessage" to the window manager.

           If the window manager does not have any iconification then it might do nothing (eg.
           some tiling window managers).  If there's no window manager running then iconification
           is not possible and this message will do nothing.

           $root should be the root window of $window.  If not given or "undef" then it's
           obtained by a "QueryTree()" here.  Any client can iconify any top level window.

           If $window has other windows which are "WM_TRANSIENT_FOR" for it then generally the
           window manager will iconify or hide those windows too (see "WM_TRANSIENT_FOR" below).

       "X11::Protocol::WM::withdraw ($X, $window)"
       "X11::Protocol::WM::withdraw ($X, $window, $root)"
           Change $window to "WithdrawnState" by an "$X->UnmapWindow()" and a synthetic
           "UnmapNotify" message to the window manager.

           If there's no window manager running then the "UnmapWindow()" unmaps and the
           "UnmapNotify" message does nothing.

           $root should be the root window of $window.  If not given or "undef" then it's
           obtained by a "QueryTree()" here.

           If other windows are "WM_TRANSIENT_FOR" this $window (eg. open dialog windows) then
           generally the client should withdraw them too.  The window manager might make such
           other windows inaccessible anyway.

           The ICCCM specifies an "UnmapNotify" message so the window manager is notified of the
           desired state change even if $window is already unmapped, such as in "IconicState" or
           perhaps during some window manager reparenting, etc.

           $window can be changed back to NormalState or IconicState later with "$X->MapWindow()"
           the same as for a newly created window.  (And "WM_HINTS" "initial_state" can give a
           desired initial iconic/normal state).  But before doing so be sure the window manager
           has recognised the "withdraw()".  This will be when the window manager changes the
           "WM_STATE" property to "WithdrawnState", or deletes that property.

           Any client can withdraw any toplevel window, but it's unusual for a client to withdraw
           windows which are not its own.

   WM_TRANSIENT_FOR
       "X11::Protocol::WM::set_wm_transient_for ($X, $window, $transient_for)"
           Set the "WM_TRANSIENT_FOR" property on $window (an XID).

           $transient_for is another window XID, or "undef" if $window is not transient for
           anything so "WM_TRANSIENT_FOR" should be deleted.

           "Transient for" means $window is some sort of dialog or menu related to the given
           $transient_for window.  The window manager will generally iconify $window together
           with its $transient_for, etc.  See "set_motif_wm_hints()" below for "modal"
           transients.

   _MOTIF_WM_HINTS
       "X11::Protocol::WM::set_motif_wm_hints ($X, $window, key=>value...)"
           Set the "MOTIF_WM_HINTS" property on $window (an XID).

           These hints control window decorations and "modal" state.  It originated in the Motif
           "mwm" window manager but is recognised by most other window managers.  It should be
           set on a toplevel window before mapping.  Changes made later might not affect what the
           window manager does.

               X11::Protocol::WM::set_motif_wm_hints
                 ($X, $dialog_window,
                  input_mode => "full_application_modal");
               $X->MapWindow ($dialog_window);

           Ordinary windows generally don't need to restrict their decorations etc, but something
           special like a clock or gadget might benefit.

               X11::Protocol::WM::set_motif_wm_hints
                 ($X, $my_gadget_window,
                  functions   => 4+32,   # move+close
                  decorations => 1+4+8); # border+title+menu

           The key/value arguments are

               functions   => integer bits
               decorations => integer bits
               input_mode  => enum string or integer
               status      => integer bits

           "functions" is what actions the window manager should offer to the user in a drop-down
           menu or similar.  It's an integer bitwise OR of the following values.  If not given
           then the default is normally all functions.

               bit    actions offered
               ---    ---------------
                1     all functions
                2     resize window
                4     move window
                8     minimize, to iconify
               16     maximize, to full-screen (with a frame still)
               32     close window

           "decorations" is what visual decorations the window manager should show around the
           window.  It's an integer bitwise OR of the following values.  If not given then the
           default is normally all decorations.

               bit       decorations displayed
               ---       ---------------------
                1        all decorations
                2        border around the window
                4        resizeh, handles to resize by dragging
                8        title bar, showing WM_NAME
               16        menu, drop-down menu of the "functions" above
               32        minimize button, to iconify
               64        maximize button, to full-screen

           "input_mode" allows a window to be "modal", meaning the user should interact only with
           $window.  The window manager will generally keep it on top, not move the focus to
           other windows, etc.  The value is one of the following strings or corresponding
           integer,

                 string                   integer
               "modeless"                    0    not modal (the default)
               "primary_application_modal"   1    modal to its "transient for"
               "system_modal"                2    modal to the whole display
               "full_application_modal"      3    modal to the current client

           "primary_application_modal" means $window is modal for the "WM_TRANSIENT_FOR" set on
           $window (see "WM_TRANSIENT_FOR" above), but other windows on the display can be used
           normally.  "full_application_modal" means modal for all windows of the same client,
           but other clients can be used normally.

           Modal behaviour is important for good user interaction and therefore ought to be
           implemented by a window manager, but a good program should be prepared to do something
           with input on other windows.

           "status" field is a bitwise OR of the following bits (only one currently).

               bit
                1    tearoff menu window

           Tearoff menu flag is intended for tearoff menus, as the name suggests.

               X11::Protocol::WM::set_motif_wm_hints
                 ($X, $my_tearoff_window, status => 1);

           Motif "mwm" will expand the window to make it wide enough for the "WM_NAME" in the
           frame title bar.  Otherwise a title is generally truncated to as much as fits the
           window's current width.  Expanding can be good for tearoffs where the title bar is
           some originating item name etc which the user should see.  But don't be surprised if
           this flag is ignored by other window managers.

           Perhaps in the future the individual bits above will have some symbolic names.  Either
           constants or string values interpreted.  What would a possible "get_hints()" return,
           and what might be convenient to add/subtract bits?

           See /usr/include/Xm/MwmUtil.h on the hints bits, and see "mwm" sources WmWinInfo.c
           "ProcessWmWindowTitle()" for the "status" tearoff window flag.

   _NET_FRAME_EXTENTS
       "my ($left,$right, $top,$bottom) = X11::Protocol::WM::get_net_frame_extents ($X, $window)"
           Get the "_NET_FRAME_EXTENTS" property from $window.

           This is set on top-level windows by the window manager to report how many pixels of
           frame or decoration it has added around $window.

           If there's no such property set then the return is an empty list.  So for example

               my ($left,$right,$top,$bottom)
                     = get_net_frame_extents ($X, $window)
                 or print "no frame extents";

               my ($left,$right,$top,$bottom)
                 = get_net_frame_extents ($X, $window);
               if (! defined $left) {
                 print "no frame extents";
               }

           A client might look at the frame size if moving a window programmatically so as not to
           put the title bar etc off-screen.  Oldish window managers might not provide this
           information though.

   _NET_WM_PID
       "X11::Protocol::WM::set_net_wm_pid ($X, $window)"
       "X11::Protocol::WM::set_net_wm_pid ($X, $window, $pid)"
       "X11::Protocol::WM::set_net_wm_pid ($X, $window, undef)"
           Set the "_NET_WM_PID" property on $window to the given $pid process ID, or to the $$
           current process ID if omitted.  (See perlvar for $$.)  If $pid is "undef" then the
           property is deleted.

           A window manager or similar might use the PID to forcibly kill an unresponsive client.
           It's only useful if "WM_CLIENT_MACHINE" (above) is set too, to know where the client
           is running.

   _NET_WM_STATE
       An EWMH compliant window manager maintains a set of state flags for each client window.  A
       state is an atom such as "_NET_WM_STATE_FULLSCREEN" and each such state can be present or
       absent.  The supported states are listed in property "_NET_SUPPORTED" on the root
       (together with other features).  For example,

           my @net_supported = X11::Protocol::Other::get_property_atoms
                                ($X, $X->root, $X->atom('_NET_SUPPORTED'));
           if (grep {$_ == $X->atom('_NET_WM_STATE_FULLSCREEN')}
                    @net_supported) {
             print "Have _NET_WM_STATE_FULLSCREEN\n";
           }

       Any client can ask the window manager to change states of any window.  A client might set
       initial states on a new window with "set_net_wm_state()" below.  Possible states include

       _NET_WM_STATE_MODAL
           The window is modal to its "WM_TRANSIENT_FOR" parent, or if "WM_TRANSIENT_FOR" not set
           then modal to its window group.

           See "_MOTIF_WM_HINTS" to set modal with the Motif style hints.

       _NET_WM_STATE_STICKY
           The window is kept in a fixed position on screen when the desktop scrolls.

       _NET_WM_STATE_MAXIMIZED_VERT
       _NET_WM_STATE_MAXIMIZED_HORZ
           The window is maximum size vertically or horizontally or both.  The window still has
           its surrounding decoration and the size should obey size increments specified in
           "WM_NORMAL_HINTS".

       _NET_WM_STATE_FULLSCREEN
           The window is the full screen with no decoration around it, thus being the full
           screen.

           The window manager remembers the "normal" size of the window so that when maximize or
           fullscreen states are removed the previous size is restored.

       _NET_WM_STATE_SHADED
           The window is "shaded" which generally means its title bar is displayed but none of
           the client window.  This is an alternative to iconifying a window.

       _NET_WM_STATE_SKIP_TASKBAR
       _NET_WM_STATE_SKIP_PAGER
           Don't show the window on a task bar or in a pager, respectively.

       _NET_WM_STATE_HIDDEN (read-only)
           This state is set by the window manger when the window is iconified or similar and so
           does not appear on screen.  Clients cannot change this.

       _NET_WM_STATE_ABOVE
       _NET_WM_STATE_BELOW
           The window is kept above or below other client windows.  The stacking order maintained
           is roughly

                top
               +-----------------------------+
               |  _NET_WM_WINDOW_TYPE_DOCK   |   "DOCK" panels (etc) on top,
               +-----------------------------+   except perhaps FULLSCREEN
               |     _NET_WM_STATE_ABOVE     |   windows above those panels
               +-----------------------------+   when focused
               |            normal           |
               +-----------------------------+
               |     _NET_WM_STATE_BELOW     |
               +-----------------------------+
               | _NET_WM_WINDOW_TYPE_DESKTOP |
               +-----------------------------+
                bottom

       _NET_WM_STATE_DEMANDS_ATTENTION
           The window should be brought to the attention of the user in some way.  A client sets
           this and the window manager clears it after the window has received user attention
           (which might mean keyboard focus or similar).

       The following functions get or set the states.

       "change_net_wm_state($X, $window, $action, $state, key=>value,...)"
           Change one of the "_NET_WM_STATE" state flags on $window by sending a message to the
           window manager.  For example,

               change_net_wm_state ($X, $window, "toggle", "FULLSCREEN");

           $window must be a managed window, ie. must have had its initial "MapWindow()" and not
           be an override-redirect.  If that's not so or if there's no window manager or it
           doesn't have EWMH then this change message will have no effect.

           $action is a string or integer how to change the state,

               "remove"       0
               "add"          1
               "toggle"       2

           $state is a string such as "FULLSCREEN" or an atom integer such as
           "$X->atom("_NET_WM_STATE_FULLSCREEN")".

           The further optional key/value parameters are

               state2   => string or atom
               source   => "none", "normal", "user", 0,1,2
               root     => integer XID, or undef

           A change message can act on one or two states.  For two states, the second is
           "state2".  For example to maximize vertically and horizontally in one operation,

               change_net_wm_state ($X, $window, "add", "MAXIMIZED_VERT",
                                    state2 => "MAXIMIZED_HORZ");

           "source" is where the change request came from.  The default is "normal" which means a
           normal application.  "user" is for a user-interface control program such as a pager.
           ("none"=0 is what clients prior to EWMH 1.2 gave.)

           "root" is the root window (integer XID) of $window.  If "undef" or not given then it's
           found by "$X->QueryTree()".  If you already know the root then giving it avoids that
           round-trip query.

       "@strings = get_net_wm_state ($X, $window)"
       "@atoms = get_net_wm_state_atoms ($X, $window)"
           Get the "_NET_WM_STATE" property from $window.  "get_net_wm_state()" returns a list of
           strings such as "FULLSCREEN".  "get_net_wm_state_atoms()" returns a list of atom
           integers such as "$X->atom('_NET_WM_STATE_FULLSCREEN')".  In both cases, if there's no
           such property or if it's empty then return an empty list.

       "set_net_wm_state ($X, $window, $state,...)"
           Set the "_NET_WM_STATE" property on $window.  Each $state can be

              string like "FULLSCREEN"
              string like "_NET_WM_STATE_FULLSCREEN"
              integer atom of a name like _NET_WM_STATE_FULLSCREEN

           A client can set "_NET_WM_STATE" on a new window to tell the window manager of desired
           initial states.  This is only a "should" in the EWMH spec so it might not be obeyed.

               # initial desired state
               set_net_wm_state ($X, $window,
                                 "MAXIMIZED_HORZ", "MAXIMIZED_VERT");

           After the window is managed by the window manager (once mapped), clients should not
           set "_NET_WM_STATE" but instead ask the window manager with "change_net_wm_state()"
           message above.

   _NET_WM_USER_TIME
       "set_net_wm_user_time ($X, $window, $time)"
           Set the "_NET_WM_USER_TIME" property on $window.

           $time should be a server time value (an integer) from the last user keypress etc event
           in $window.  Or when $window is created then the time from the event which caused it
           to be opened.

           On a newly created window, a special $time value 0 means the window should not receive
           the focus when mapped -- assuming the window manager recognises "_NET_WM_USER_TIME" of
           course.

           If the client has the active window it should update "_NET_WM_USER_TIME" for every
           user input.  Generally KeyPress and ButtonPress events are user input, but normally
           KeyRelease and ButtonRelease are not since it's the Press events which are the user
           actively doing something.

           The window manager might use "_NET_WM_USER_TIME" to control focus and/or stacking
           order so that for example a slow popup doesn't steal the focus if you've gone to
           another window to do other work in the interim.

   _NET_WM_WINDOW_TYPE
       "X11::Protocol::WM::set_net_wm_window_type ($X, $window, $window_type)"
           Set the "_NET_WM_WINDOW_TYPE" property on $window (an XID).  $window_type can be

               string like "NORMAL"
               integer atom of a name like _NET_WM_WINDOW_TYPE_NORMAL

           The window types from from the EWMH are as follows.

               "NORMAL"
               "DIALOG"
               "DESKTOP"
               "DOCK"
               "TOOLBAR"
               "MENU"
               "UTILITY"
               "SPLASH"

   Frame to Client
       "$window = X11::Protocol::WM::frame_window_to_client ($X, $frame)"
           Return the client window (an XID) contained within window manager $frame window (an
           XID).  $frame is usually an immediate child of the root window.

           If no client window can be found in $frame then return "undef".  This might happen if
           $frame is an icon window or similar created by the window manager itself, or an
           override-redirect client without a frame, or if there's no window manager running at
           all.  In the latter two cases $frame would be the client already.

           The strategy is to look at $frame and down the window tree seeking a "WM_STATE"
           property which the window manager puts on a client's toplevel when mapped.  The search
           depth and total windows are limited in case the window manager does its decoration in
           some ridiculous way or the client uses excessive windows (which would be traversed if
           there's no window manager).

               +-rootwin--------------------------+
               |                                  |
               |                                  |
               |    +-frame-win--------+          |
               |    | +-client-win---+ |          |
               |    | | WM_STATE ... | |          |
               |    | |              | |          |
               |    | +--------------+ |          |
               |    +------------------+          |
               |                                  |
               +----------------------------------+

           Care is taken not to error out if some windows are destroyed during the search.  When
           a window belongs to other clients it could be destroyed at any time.  If $frame itself
           doesn't exist then the return is "undef".

           This function is similar to what "xwininfo" and similar programs do to go from a
           toplevel root window child down to the client window, per dmsimple.c "Select_Window()"
           or Xlib "XmuClientWindow()".  (See also X11::Protocol::ChooseWindow.)

   Virtual Root
       Some window managers use a "virtual root" window covering the entire screen.  Application
       windows or frame windows are then children of that virtual root.  This can help the window
       manager implement a large desktop or multiple desktops, though it tends to fail in subtle
       ways with various root oriented programs, including for example xsetroot(1) or the click-
       to-select in xwininfo(1) and xprop(1).

       "$window = X11::Protocol::WM::root_to_virtual_root ($X, $root)"
           If the window manager is using a virtual root then return that window XID.  If not
           then return "undef".

           The current implementation searches for a window with an "__SWM_VROOT" property, as
           per the "swm", "tvtwm" and "amiwm" window managers, and as used by the "xscreensaver"
           program and perhaps some versions of KDE.

           There's nothing yet for EWMH "_NET_VIRTUAL_ROOTS".  Do any window managers use it?  Is
           "_NET_CURRENT_DESKTOP" an index into that virtual roots list?

           (See X11::Protocol::XSetRoot for changing the background of a root or virtual root.)

EXPORTS

       Nothing is exported by default, but the functions can be requested in usual "Exporter"
       style,

           use X11::Protocol::WM 'set_wm_hints';
           set_wm_hints ($X, $window, input => 1, ...);

       Or just call with full package name

           use X11::Protocol::WM;
           X11::Protocol::WM::set_wm_hints ($X, $window, input => 1, ...);

       There's no ":all" tag since this module is meant as a grab-bag of functions and to import
       as-yet unknown things would be asking for name clashes.

BUGS

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

SEE ALSO

       X11::Protocol, X11::Protocol::Other, X11::Protocol::ChooseWindow, X11::Protocol::XSetRoot

       "Inter-Client Communication Conventions Manual",
       /usr/share/doc/xorg-docs/icccm/icccm.txt.gz, <http://www.x.org/docs/ICCCM/>

       "Compound Text Encoding" specification.  /usr/share/doc/xorg-docs/ctext/ctext.txt.gz,
       <http://www.x.org/docs/CTEXT/>

       "Extended Window Manager Hints" which is the "_NET_WM" things.
       <http://www.freedesktop.org/wiki/Specifications/wm-spec>,
       <http://mail.gnome.org/archives/wm-spec-list/>

       wmctrl(1), xwit(1), X(7)

HOME PAGE

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

LICENSE

       Copyright 2011, 2012, 2013, 2014, 2016, 2017, 2018, 2019 Kevin Ryde

       X11-Protocol-Other is free software; you can redistribute it and/or modify it under the
       terms of the GNU General Public License as published by the Free Software Foundation;
       either version 3, or (at your option) any later version.

       X11-Protocol-Other is distributed in the hope that it will be useful, but WITHOUT ANY
       WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
       PURPOSE.  See the GNU General Public License for more details.

       You should have received a copy of the GNU General Public License along with
       X11-Protocol-Other.  If not, see <http://www.gnu.org/licenses/>.