/ 
X11-Protocol-Other-15
River stage one • 2 direct dependents • 2 total dependents
/ 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.

Text

Property functions for text strings such as set_wm_name() below accept Perl 5.8 wide char strings and encode to either "STRING" or "COMPOUND_TEXT" as necessary. Byte strings and Perl 5.6 and earlier strings are presumed to be Latin-1 and set as "STRING" type.

In the future perhaps the string functions could accept some OOPery for a string of COMPOUND_TEXT segments, in the various encodings, with manipulations of the contents etc. (If an input is bytes of one of the ICCCM encodings then passing it directly as COMPOUND_TEXT is better than going to wide chars and back again.)

FUNCTIONS

WM_CLASS

X11::Protocol::WM::set_wm_class ($X, $window, $instance, $class)

Set the WM_CLASS property on $window (an XID). This might be used by the window manager to lookup settings and preferences for the program, perhaps 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 control what they set, so the user can have different settings on a particular running copy.

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

$instance and $class must be ASCII or Latin-1 characters only. Perl 5.8 wide-char strings are converted to Latin-1 if 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" 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 that module can't determine a hostname by its various gambits then currently the property is deleted. Should it leave it unchanged, or return a flag to say if set?

Some of the Sys::Hostname cases might end up returning "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 always 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.

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

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

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

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.

$bytes = X11::Protocol::WM::pack_wm_hints ($X, key=>value...)

Pack a set of values into a byte string of WM_HINTS type. 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.

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, in a menu of windows, etc. It can be a Perl 5.8 wide-char string per "Text" above, though support for non-ascii titles tends to be a bit variable among different window managers.

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 string when $window is iconified. If $window doesn't have an icon image (in WM_HINTS or from the window manager itself) then this text may be all that's shown. Either way it should be something short. It can be a Perl 5.8 wide-char string per "Text" 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 contains a WM_SIZE_HINTS structure which tells the window manager what size 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 perhaps 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 the window's x,y or width,height (the 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 interactive window placement it might otherwise do.

program_position and program_size are flags meaning instead the window x,y or width,height were calculated by the program. The window manager then might override with its own positioning or sizing policy. There's generally no need to set these flags 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 attributes 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. 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 be a base+inc multiple, but the first which is at least the min size. The window manager generally presents the increment multiple to the user, so for example on an xterm the user sees a count of characters. A min size can then force 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 (integers up to 0x7FFFFFFF). Or min_aspect and max_aspect for convenience 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 will be 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 will keep 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 is 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.)

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 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 to save a document before exiting, etc.

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 an 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" (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 created by the window manager. Either way the client can draw into it for animations etc, perhaps selecting Expose events for that.

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 mean the window manager is not managing the window, or not yet doing so.

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

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 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). This controls window decorations and "modal" state. It originated in the Motif mwm window manager but is recognised by many 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 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 the default is usually 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 the default is usually all decorations.

bit 
 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), and other windows can still be used normally. "primary_application_modal" means modal for all windows of the same client, but other clients are unaffected.

Modal behaviour is important for good user interaction and therefore ought to be implemented by almost all window managers, but a good program should be prepared for input on other windows.

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

bit
 1    tearoff menu window

"Tearoff menu" is intended for tearoff menus, as the name suggests. Motif mwm will expand the window to make it wide enough for the WM_NAME in the frame title bar.

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

By default 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. However 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 might match a possible "get_hints" and be convenient for adding/subtracting perhaps?

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

_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 this to forcibly kill an unresponsive client. But it's only useful if WM_CLIENT_MACHINE (above) is set too, to know where the client is running.

_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 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. (If 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 it can ignore KeyRelease and ButtonRelease since it's only 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 popup which is slow to start doesn't steal the focus if you've gone to another window to do something else 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 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').

Frame to Client

$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 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 current 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. The windows may belong to other clients and 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.

BUGS

Not much attention has been paid to text on an EBCDIC system. Wide char strings probably work, but byte strings may go straight through where they ought to be re-coded to latin-1. But the same might apply to some of the core X11::Protocol things such as $X->atom_name() too where you'd want to convert the latin-1 from the server to native EBCDIC.

SEE ALSO

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

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