WIP: wm-spec 1.9b

[Marko Macek <Marko Macek gmx net>]

Nathan Clemons wrote:
> 
> Hey Marko, just wanted to touch base about the status of the draft you
> were working on before. I know you were up to 1.9a, did you ever have a
> chance to work beyond that? Either way, please send me what you have so we
> can keep moving forward.

I have now reread the entire thread posted after 1.9a and have made some
updates. 

It still very much a work in progress. Lots of the text must be
rewritten to be more readable/understandable/accurate/clear...
and spelled properly. (I just did an ispell and things aren't that bad).

Unfortunately I will not have much time to work on it in the next month. 

Matthias, it would be great if you can provide more explanation for the
STRUT mechanism.

        _NET* window manager hints,protocols... proposal draft 1.9b
        -----------------------------------------------------------

Several people mentioned that this specification allows applications to
do 
lots of weird things that user might not want. I agree with most of
them. 

We should probably include  a policy statement saying that applications
are allowed to do things like changing states, ... only as a direct
consequence of the user action.. The application must not use these
hints to enforce things the way it wants them if the user thinks
differently. 

If we design a WM spec thinking just about misuse of certain hints, we
will get nowhere. IMO, if applications misuse parts of this spec, it
will annoy the users and cause them to switch to another app.

Changes from 1.9a:
	- NET_WM_DECORATION obsoleted (do we need it? see below) (MWM hints?)
        - NET_CLIENT_LIST_STACKING added (do we need _FOCUS too?). 
          There is still a question of efficiency.
        - Description for packaging hints into 2 properties.
          _NET_ALL_STATE, _NET_ALL_HINTS. 
        - Advice for WM authors for implementing application modal
windows.
        - _NET_WM_STATE_OMNIPRESENT has been replaced by 0xFFFFFFFF
value in 
          the _NET_WM_DESKTOP
        - _NET_SUPPORTED is now list of supported atoms.
        - More information about File Manager desktop.

Adapted from draft#1 by. Matthias Ettrich

Some properties may have been renamed. Some probably should be.

Work in progress. My (Marko Macek) comments are in [[]].

0. Packaging the hints into 2 X properties for performance (less
roundtrips)
----------------------------------------------------------------------------

2 properties are used:

  _NET_ALL_STATE for state that is initialized by app and updated by the
WM
  when it changes. Application must send ClientMessages to modify them.
  
  _NET_ALL_HINTS for application set hints (modified only by the app
  using XChangeProperty).

I need to update this spec to say where individual hints belong, but
most are obvious.  _NET_PROPERTIES is part of _NET_ALL_HINTS and should
still specify all hints, not just the ones from this spe if it is used.

Packaging format is as follows: XA_CARDINAL/32

  <ATOM><LENGTH><DATA[LENGTH]>

When sending ClientMessages, all unused fields must be set to 0.

1. Root Window Properties (+Related Messages)
---------------------------------------------

_NET_SUPPORTED, ATOM[]/32

This property is supposed to be set by the window manager to indicate
whether which protocol hints are supported. This assumes that backwards
incompatible changes will not be made to the hints (without being
renamed).

_NET_CLIENT_LIST, XA_WINDOW[]/32
_NET_CLIENT_LIST_STACKING, XA_WINDOW[]/32

An array of all X Windows managed by the window manager.

_NET_CLIENT_LIST has mapping order
_NET_CLIENT_LIST_STACKING has stacking order

[[This is simple. Does anyone feel we need a faster mechanism based  on
incremental updates? (based selection query + ADD/REMOVE updates, we
must  be careful about race conditions if we do this)?
It would be nice to have a query for managed windows in Z-order, for
external implementation of Alt-Tab]]

_NET_NUMBER_OF_DESKTOPS <#desktops>, CARDINAL/32

The number of virtual desktops. If a client wants to change the number
of desktops, it can send a _NET_NUMBER_OF_DESKTOPS client message to
the root window (type _NET_NUMBER_OF_DESKTOPS, format 32, l[0]=<new
number>) 

If the clients wants to delete/insert a certain desktop, it must send
_NET_{INSERT/DELETE}_DESKTOP to the root window (l[0] = desktop to
insert/delete, (insert must also work for appending one desktop). When
a desktop is deleted, it's windows get moved to the  newly active
desktop (=the current desktop if some other desktop was deleted, the
next desktop if current desktop was deleted, or the last desktop if the
last desktop was deleted). This operation should not be ordinarily
performed by normal applications.

_NET_DESKTOP_GEOMETRY width,height, CARDINAL[2]/32

Array of two Cardinals that defines the width and height of each
desktop in pixel. If a client wants to change the desktop geometry, it
can send a _NET_DESKTOP_GEOMETRY client message to the root window
(type _NET_DESKTOP_GEOMETRY, format 32, l[0]=<new width>, l[1]=<new
height>).

_NET_DESKTOP_VIEWPORT x,y, CARDINAL[2]/32

Array of two Cardinals that defines the toplevel corner of the current
view. For window managers that don't support paged desktops, this is
always (0,0). If a client wants to change the desktop viewport, it can
send a _NET_DESKTOP_VIEWPORT client message to the root window (type
_NET_DESKTOP_VIEWPORT, format 32, l[0]=<new x>, l[1]=<new y> ). 

_NET_CURRENT_DESKTOP <desktop>, CARDINAL[1]/32

The index of the current desktop, starts with desktop 1. If a client
wants to switch to another virtual desktop, it can send a
_NET_CURRENT_DESKTOP client message to the root window (type
_NET_CURRENT_DESKTOP, format 32, l[0]=<new index> )

_NET_DESKTOP_NAMES

The names of all virtual desktops. Text Property. Can be changed by
anyone (by pager for example, when renaming desktops).

[[Should WM update this when modifying desktop count?]]
[[What does this mean with respect to Unicode if anything?]]

_NET_ACTIVE_WINDOW, WINDOW/32

The window handle of the currently active window. This is a read-only
property set by the window manager. If a client (for example a
taskbar) wants to activate another window, it can send a
_NET_ACTIVE_WINDOW client message request to the root window (window
is the respective window, type _NET_ACTIVE_WINDOW, format 32,
l[0]=0 /*may be used later*/ )

  Rationale: XSetInputFocus is not sufficient, since the window may be
  hidden on another virtual desktop ( in that case XSetInputFocus
  fails with a BadWindow error )

_NET_WORKAREA CARDINAL[][4]/32

Readonly property set by WM upon calculating the work area for each
desktop. (the first quadruple = desktop 1, etc).
Contains the left,right,top,bottom coordinates for each desktop.
Work area is used for maximizing windows and by the desktop to place
desktop icons appropriatelly.

Work area refers to current page minus space occupied by panels, docks
etc.  The purpose is to ensure that maximised applications do not cover
panels, and so that desktop icons don't get put under panels. 

[[IMHO having different work areas on different desktops is messy,
although flexible]].

2. Other Root Window Messages
-----------------------------

_NET_CLOSE_WINDOW

Clients that wish to close another client ( typical examples are
pagers or taskbars ), shall send a _NET_CLOSE_WINDOW client message
request to the root window (window is the respective window that shall
be closed, type _NET_ACTIVE_WINDOW, format 32, l[0]=0 /*may be used
later*/ )

  Rationale: A window manager might be more clever than the usual
  method (send WM_DELETE message if the protocol is selected,
  XKillClient otherwise). It might introduce a timeout, for example.
  Instead of duplicating the close code, the WM can easily do the job.

_NET_WM_MOVERESIZE

When application wishes to initiate window resizing it must send
a message to the root window:

   window = target app window
   message_type = _NET_WM_MOVERESIZE
   format = 32
   data.s[0] = x_root
   data.s[1] = y_root
   data.s[2] = direction:

#define _NET_WM_MOVERESIZE_DIRECTION_TOPLEFT 0 /* towards the top-left
*/
#define _NET_WM_MOVERESIZE_DIRECTION_TOP 1 /* towards the top */
#define _NET_WM_MOVERESIZE_DIRECTION_TOPRRIGHT 2 /* towards the
top-right */
#define _NET_WM_MOVERESIZE_DIRECTION_RIGHT 3 /* towards the right */
#define _NET_WM_MOVERESIZE_DIRECTION_BOTTOMRIGHT 4 /* towards the
bottom-right*/
#define _NET_WM_MOVERESIZE_DIRECTION_BOTTOM 5 /* towards the bottom */
#define _NET_WM_MOVERESIZE_DIRECTION_BOTTOMLEFT 6 /* towards the
bottom-left */
#define _NET_WM_MOVERESIZE_DIRECTION_LEFT 7 /* towards the left */
#define _NET_WM_MOVERESIZE_DIRECTION_MOVE 8 /* only movement */



3. Application Window Properties
--------------------------------

_NET_PROPERTIES, ATOM[]/32

Enables only use of listed properties on this window. If this property
is set, the WM will only handle (XGetWindowProperty) properties listed
here. This property must be set before any other _NET hints can be
used. If this property is set, it must also include any ICCCM
client-only (not WM_STATE) hints and MOTIF hints that are set by the
client. If WM_PROTOCOLS is not listed here, the WM is safe to assume
that it contains exactly WM_DELETE_WINDOW.

This is a performance optimization.

[[I still have to do a benchmark.]]

_NET_WM_DESKTOP <desktop>, CARDINAL[1]/32

Cardinal to determine the desktop the window is in (or wants to be),
starting with 1 for the first desktop. 0 indicates that the window is
withdrawn and the window manager is free to place it. 0xFFFFFFFF
indicates
that window appears on all desktops/workspaces.

A window manager honors _NET_WM_DESKTOP whenever a withdrawn window
requests to be mapped.  When being in another state (iconified or
mapped), the client can request a change by sending a _NET_WM_DESKTOP
client message to the root window. (window is the respective window,
type _NET_WM_DESKTOP, format 32, l[0]=<desktop>) If <desktop> is set to
0, 
the window is mapped to the current desktop.

_NET_WM_LAYER, CARDINAL/32

#define _NET_WIN_LAYER_DESKTOP                0
#define _NET_WIN_LAYER_BELOW                  2
#define _NET_WIN_LAYER_NORMAL                 4
#define _NET_WIN_LAYER_ONTOP                  6
#define _NET_WIN_LAYER_DOCK                   8
#define _NET_WIN_LAYER_ABOVE_DOCK             10
#define _NET_WIN_LAYER_MENU                   12

The intentions are as follows:

DESKTOP: A single window at the bottom should be a desktop with icons.
It should have the same dimensions as the screen.
[[Even with virtual scrolling desktop?]]
This allows the desktop environment to have full control of the desktop.
(With focusing, background handling and no shaped windows).

NORMAL: the default for all windows

ONTOP,BELOW: Normal window that stay on top/below other windows.

DOCK: Windows docked at the edge of the screen.

MENU: layer for NextStep/WMaker style menus that stay on top.

[[Some adjustments for DOCK might be necessary when _NET_WM_STRUT is
finalized]]

_NET_WM_STATE CARDINAL/32

#define _NET_WM_STATE_STICKY (1<<0) /* the window sticks on the screen
even when the virtual desktop scrolls */
REMOVED: #define _NET_WM_STATE_OMNIPRESENT (1<<1) /* the window is
visible on all
virtual desktops */
#define _NET_WM_STATE_MAXIMIZED_VERT (1<<2)  /* the window is vertically
maximized */
#define _NET_WM_STATE_MAXIMIZED_HORZ (1<<3)  /* the window is
horizontally maximized */
#define _NET_WM_STATE_SHADED (1<<4)  /* the window is shaded */

A window manager honors _NET_WM_STATE whenever a withdrawn window
requests to be mapped.  When being in another state (iconified or
mapped), the client can request a change by sending a _NET_WM_STATE
client message to the root window. (window is the respective window,
type _NET_WM_STATE, format 32, l[0]=<mask>, l[1]=<new values for masked
bits> )

[[A big problem with this property is that is not extensible by anyone.
Someone needs to arbitrate the bits]].

_NET_WM_HINTS CARDINAL/32
Additional hints for the window manager or tools like panels or
taskbars.
Possible values:

#define _NET_WM_HINTS_SKIP_FOCUS (1<<0) /* "alt-tab" skips this win */
#define _NET_WM_HINTS_SKIP_WINLIST (1<<1)  /* do not show in window list
*/
#define _NET_WM_HINTS_SKIP_TASKBAR (1<<2) /* do not show on taskbar */
#define _NET_WM_HINTS_NO_AUTO_FOCUS (1<<3) /* do not automatically put
focus on this window when it pops up */
#define _NET_WM_HINTS_STANDALONE_MENUBAR  (1<<4) /* this window is a
standalone menubar */
#define _NET_WM_HINTS_IGNORE_ARRANGE  (1<<5) /* this window has a fixed
position (should be excluded from desktop uncluttering etc.) */
#define _NET_WM_HINTS_DO_NOT_COVER (1<<6) /* attempt to never cover up
this window if possible (placement policy priority hint)*/
#define _NET_WM_HINTS_LOCK_ZORDER (1<<7) /* window will not be raised
when clicked even if WM does this for normal windows)*/
//remove?: #define _NET_WM_HINTS_NO_MOVE_WITH_OWNER (1<<8) /* for
transient
windows, will not be moved when owner is moved/sized */

A window manager honors _NET_WM_HINTS whenever a withdrawn window
requests to be mapped.  When being in another state (iconified or
mapped), the client can request a change by sending a _NET_WM_HINTS
client message to the root window.  (window is the respective window,
type _NET_WM_HINTS, format 32, l[0]=<mask>, l[1]=<new values for masked
bits> )

[[Also not extensible.]]

_NET_WM_STRUT CARDINAL[][4]/32

An array of struts. Strut[0] is the global strut, i.e. it appears on
all virtual desktops. The optional following struts appear only on
their respective virtual desktop.  A strut is defined as 4-tupel of
cardinals, one for each border of the screen. The order of the borders
is left, right, top, bottom. The client may change this property
anytime, a window manager therefore has to watch out for property
notify events. A strut is valid when the window is mapped relatively
to its virtual desktop.

Type _NET_WM_CARDINAL, format 32.

[[Mathiass, please describe this in more detail]]

_NET_WM_ICON_GEOMETRY

An array x,y,w,h of type CARDINAL, format 32.  This optional property
may be set by standalone tools like a taskbar or an iconbox. It
specifies the geometry of a possible icon in case the window is
iconified.

  Rationale: This makes it possible for a window manager to display a
  nice animation like morphing the window into its icon.

======================
_NET_PROPERTIES (recommended) or WM_PROTOCOLS:
======================

_NET_WM_SIZEMOVE_NOTIFY

If this protocol is selected, the window will receive
_NET_WM_SIZEMOVE_BEGIN and _NET_WM_SIZEMOVE_END client messages when the
window manager starts or ends resizing in opaque mode.

  Rationale: This allows slow applications to use a faster resizing
  method until they finally receive the _NET_WM_SIZEMOVE_EXIT hint.

[[Changed to include resizing only. Do we need move too? In that case
we need to report what is actually being done]]

4. Client Window Messages
-------------------------

_NET_WM_SIZEMOVE_BEGIN
_NET_WM_SIZEMOVE_END

See above.

5. Desktop/workspace model
--------------------------

This spec assumes desktop model that consists of one or more completely
independent desktops which may or may not be larger than screen area.
When desktop is larger than screen it is left to the window manager if
it will implement scrolling or paging.

6. File Manager desktop
-----------------------

This spec suggests implementing the file manager desktop by mapping a
desktop-sized window (no shape) to all desktops with Layer=Desktop. 
This makes the desktop focusable and greatly simplifies implementation 
of the file manager. It is also faster than managing lots of small
shaped 
windows. The file manager draws the background on this window. There
should be a  root property with a window handle for use in applications
that want to draw the background (xearth).

Several GNOME file manager developers have accepted this model.

7. Implementing enhanced support for application-modal dialogs in the
WM.
-------------------------------------------------------------------------

If the WM_TRANSIENT_FOR property is set to None or Root window, the
window
should stay above all other windows in the same group.

[[ should the same happen if the group leader is not managed? ]]


------------------
OBSOLETE (or not):
------------------
_NET_WM_DECORATION, CARDINAL/32

How the window's decoration frame should look like. Possible values
are None, Normal, Tiny, Tool and Menu.

#define _NET_WM_DECORATION_NONE 0  /* the window should not be decorated
at all (but managed!)*/
#define _NET_WM_DECORATION_NORMAL 1  /* normal decoration */
#define _NET_WM_DECORATION_TINY 2  /* a tiny decoration, just a small
frame that fits into the look and feel */
#define _NET_WM_DECORATION_TOOL 3 /* a toolwindow, i.e. slightly smaller
decorations */
#define _NET_WM_DECORATION_MENU 3 /* tearoff menu */

[[It would be a good thing to make these atoms. Anyone disagree?]]

A window manager honors _NET_WM_DECORATION whenever a withdrawn window
requests to be mapped.  When being in another state (iconified or
mapped), the client can request a change by sending a _NET_WM_DECORATION
client message to the root window. (window is the respective window,
type _NET_WM_DECORATION, format 32, l[0]=<decoration>)

  Rationale: especially DECORATION_NONE is very important. It allows
  application developers to create borderless windows ( for example
  taskbars, desktop panels or application specific floating toolbars )
  without the need of making them override_redirect. This way the
  window can benefit from the window manager's focus handling, which
  isn't possible at all with override_redirect windows.

[[How should overlaps with MWM hints be handled?]]

------
THINK: 
------

1. Degrees of activation: (proposed by Dominik Vogt)

> Do you have a suggestion for meaningful degrees of activation? 

  _NET_ACTIVATE_VISIBLE_ON_VIEWPORT:  make visible if on the active
viewport
  _NET_ACTIVATE_VISIBLE_ON_DESK:      make visible if on the active
desktop
  _NET_ACTIVATE_VISIBLE_EVERYWHERE:   make visible everywhere

One bit each, if multiple bits are set, EVERYWHERE take precedence over
ON_DESK, ON_DESK takes precedence over ON_VIEWPORT.

  _NET_ACTIVATE_NORMALIZE:            de-iconify and unshade

One bit, may be set independently of the other bits.

  _NET_ACTIVATE_FOCUS:                give it the focus
  _NET_ACTIVATE_FOCUS_AND_WARP:       give it the focus wnd warp into it

One bit each. If multiple bits are set, FOCUS_AND_WARP takes precedence.

[[ I am worried about the WARP thing, so I'll have to think about it. I
think assumes that the app knows about the focus model (currently it 
doesn't and I'd like to keep it that way if possible) ]]


2. We must include an KWM_WIN_ICON equivalent for setting small icons. 
(16x16 icon) (This assumes that we allow minor ICCCM violation for 
specifying colored large icons the ICCCM way (ICCCM allows only 1-bit)).
(IMO ICCCM needs to be updated to allow root-window depth icons,
everyone
does it anyway).

_NET_WIN_ICON? PIXMAP[2]/32 (pixmap/mask of size 16x16).

Alternatively, icewm currently implements _WIN_ICONS hint that is part 
of currently implemented GNOME wm hints (it allows any number of
icons/masks
with all the information from XGetGeometry already in the property as a 
speed optimization). (I support KWM_WIN_ICON too, but I hope we can
agree
on a single thing for small icons).

Before anyone suggests passing raw image data to the WM, I will say
that is IMO a really bad idea.

Mark
-- 
... GUI: WPS.
------------------------------------------------------------------------
Marko.Macek@gmx.net                 http://www.kiss.uni-lj.si/~k4fr0235/