The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.
 / 
X11-Protocol-Other-11
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. There's a lot a client can get or set, but only a few here yet.

Text

Property functions 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 already and set as "STRING" type.

In the future for general COMPOUND_TEXT manipulations perhaps some sort of OOP representing segments of the various encodings could be accepted.

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 in the style of the X Resources (see "RESOURCES" in X(7)), but perhaps not necessarily using that system.

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 get different preferences.

    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 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" 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 "localhost" is thus a good enough name.

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

WM_NAME, WM_ICON_NAME

X11::Protocol::WM::set_wm_name ($X, $window, $name)

Set the WM_NAME property on $window (an XID) to $name (a string).

The window manager might display this as a title above the window, in a menu of windows, etc. $name can be a Perl 5.8 wide-char string per "Text" above.

X11::Protocol::WM::set_wm_icon_name ($X, $window, $name)

Set the WM_ICON_NAME property on $window (an XID) to $name (a string).

The window manager might display this string when $window is iconified. If $window doesn't have an icon image (per 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_PROTOCOLS

X11::Protocol::WM::set_wm_protocols ($X, $window, $protocol,...)

Set the WM_PROTOCOLS property on $window (an XID). Each $protocol argument is a string protocol name or an integer atom ID. For example,

    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 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 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 given $transient_for window. The window manager will generally iconify $window together with its $transient_for, etc.

_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). 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 at $window creation then 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.)

If the client has the active window it should update _NET_WM_USER_TIME for every user input, though generally it can ignore KeyRelease and ButtonRelease since it's Press events which are the user doing something.

The window manager might 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 switched to another window 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').

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

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

Care is taken not to error out if some windows are destroyed during the search. They 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, as 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() 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/>.