X11::Protocol::WM(3) User Contributed Perl Documentation X11::Protocol::WM(3)
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
o "set_wm_class()" to identify itself to other programs (see
"WM_CLASS" below).
o "set_wm_name()" and "set_wm_icon_name()" for user-visible window
name (see "WM_NAME, WM_ICON_NAME" below).
o "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,
o If you have an icon then "set_wm_hints()" with a bitmap or a window
(see "WM_HINTS" below).
o 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).
o 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(3), X11::Protocol::Other(3),
X11::Protocol::ChooseWindow(3), X11::Protocol::XSetRoot(3)
"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/>.
perl v5.28.2 2019-06-03 X11::Protocol::WM(3)
x11-protocol-other 31 - Generated Wed Aug 7 07:19:22 CDT 2019