$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.

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.

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

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.

$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.

    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.

    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);

    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.

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

    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.

$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.

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 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.

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

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

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.

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.

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

     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

    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.

   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");

$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.

    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"

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.

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?