/ 
X11-Protocol-Other-10
/ X11::Protocol::WM

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. There's a lot a client can get or set, but only a few here yet.

FUNCTIONS

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 is with the SetInputFocus request, or if if you ask for WM_TAKE_FOCUS in WM_PROTOCOLS then instead by a ClientMessage instead.

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

initial_state is a string or number. "NormalState" or "IconicState" are allowed by the ICCCM as a desired initial state.

"NormalState"       1
"IconicState"       3

icon_pixmap should be a bitmap, ie. a pixmap of depth 1. The window manager will draw it in suitable contrasting colours.

icon_window is a window which the window manager can show when $window is iconified. This can be used to show a multi-colour icon, either with a desired background or drawn on-demand (Expose events etc).

The window manager might set a WM_ICON_SIZE property on the root window for good icon sizes to use in icon_pixmap and icon_window but there's nothing in this module to retrieve that yet.

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 in the hints at any time to change the current importance.

WM State

($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 integer value if $X->{'do_interp'} is disabled or the value unrecognised.

"WithdrawnState"    0      neither window nor icon display
"NormalState"       1      window displayed
"IconicState"       3      iconified in some way

"ZoomState"         2    \ no longer in ICCCM
"InactiveState"     4    /

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

$icon_window might be the icon window from the client's WM_HINTS, or it might be created by the window manager. Either way the client can draw into it for animations etc, perhaps selecting Expose events to do so.

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 both no WM_STATE or a WM_STATE of WithdrawnState mean the window manager is not (or not yet) managing the window.

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.

"Transient for" means $window is some sort of dialog or menu related to the $transient_for window. The window manager will generally iconify $window together with its $transient_for, etc.

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 a type string as follows from the EWMH,

NORMAL
DIALOG
DESKTOP
DOCK
TOOLBAR
MENU
UTILITY
SPLASH

$window_type can also be an integer atom such as $X->atom('_NET_WM_WINDOW_TYPE_DIALOG').

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 in $window, or at $window creation then from the event which caused it to be opened.

On a newly created window special $time value 0 means the window should not receive the focus when mapped. (For window managers which recognise _NET_WM_USER_TIME.)

If the client has the active window it should update _NET_WM_USER_TIME for every user input. Generally it can ignore KeyRelease and ButtonRelease since it's Press events which begin something.

The window manager can use _NET_WM_USER_TIME to control focus and/or stacking order so for example a popup which is slow to start doesn't steal the focus if you've gone on to do other work in another window.

Other Operations

$window = X11::Protocol::WM::frame_window_to_client ($X, $frame)

Return the client window (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 could be 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. In the latter two cases $frame would be the client already.

The current strategy is to look at $frame and down the window tree seeking a WM_STATE property which the window manager sets on a client's toplevel (once 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 (traversed when there's no window manager).

Care is taken not to error out if some windows are destroyed during the search. They belong to other clients, so could be destroyed at any time. If $frame itself doesn't exist then the return is undef.

This code 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().

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

SEE ALSO

X11::Protocol, X11::Protocol::Other

HOME PAGE

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

LICENSE

Copyright 2011 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/>.