Fwd: Draft 1

[Matthias Ettrich <ettrich troll no>]

Here's a draft for some hints I consider both necessary and useful.
Note that it's far from being totally defined or complete.

The draft is based on my experiences with KDE, the GNOME Hints and some
intensive discussion with Raster and Alfredo. Any remaining errors are mine,
of course.



======================
Properties of the client window
======================

_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_WM_LOCATION <desktop>

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. Type CARDINAL,
format 32.

A window manager honors _NET_WM_LOCATION 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_LOCATION
client message to the root window. (window is the respective window,
type _NET_WM_LOCATION, format 32, l[0]=<desktop>)



_NET_WM_DECORATION

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

#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 */

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

Type CARDINAL, format 32.


_NET_WM_LAYER

#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


Type CARDINAL, format 32

_NET_WM_STATE

#define _NET_WM_STATE_STICKY (1<<0) /* the window sticks on the screen even when the virtual desktop scrolls */
#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> )

_NET_WM_HINTS
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_FIXED_POSITION  (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)*/

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

Type CARDINAL, format 32.

_NET_WM_MOVERESIZEGRIP

Defines an array of childwindows that serves as move or sizegrips. The
windowmanager may install a passive button grab on these windows to
takeover the resize or move handling. The property is handled when a
window becomes mapped the very first time (map request). Type
XA_WINDOW, format 32.

The default is resize to bottom right. But the grips may define an
additional property _NET_WM_MOVERESIZE_DIRECTION of Type XA_CARDINAL,
Format32 with the following values:

#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 */



_NET_WM_STRUT

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.


======================
WM_PROTOCOLS
======================


_NET_WM_SIZEMOVE_NOTIFY

If this protocol is selected, the window will receive
_NET_WM_SIZEMOVE_ENTER and _NET_WM_SIZEMOVE_EXIT 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.


======================
Properties of the root window
======================

_NET_SUPPORTED

This property is supposed to be set by the window manager to indicate
whether the protocol is supported and up to which version. Type
CARDINAL, format 32.

_NET_CLIENT_LIST

An array of all X Windows managed by the window manager. Type
XA_WINDOW, format 32.

_NET_NUMBER_OF_DESKTOPS

The number of virtual desktops. Type CARDINAL, format 32. 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> )


_NET_DESKTOP_GEOMETRY 

Array of two Cardinals (type CARDINAL, format 32 ) 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

Array of two Cardinals (type CARDINAL, format 32 ) 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

The index of the current desktop, starts with desktop 1.  Type
CARDINAL, format 32. 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.


_NET_ACTIVE_WINDOW

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 )




======================
Misc
======================

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