Patch to WM compliance doc

[Maciej Stachowiak <mstachow alum mit edu>]

Here is a patch to the WM compliance document now in CVS (Thanks Dave!).
It makes the following changes:

* Edit introduction to make clear that a fully gnome-compliant window 
manager should also implement ICCCM hints, Motif hints, and X session
management.

* Clarify that _WIN_APP_STATE and _WIN_ICONS are unsused but reserved
for future extension.

* Explain what _WIN_EXPANDED_SIZE means, based on the explanation in
the E sources.

* Added _WIN_AREA and _WIN_AREA_COUNT to the _WIN_SUPPORTED_PROTOCOLS
array, this is admittedly a semantic change but it should not affect
anything since the panel currently won't look for that. However, in
the long term I think we want WM's notifying wether they support this.

* Clarified what properties may be set by the client directly, and which
may be changed throug client messages.

* Clarified which bits of _WIN_STATE and _WIN_HINTS are unused and 
deprecated.

* Explained the special semantics of the WIN_LAYER_DOCK layer. Pointed
out that these semantics may move to a separate hint in the future.

* Line-broke all the paragraphs because it was a huge pain to edit in
emacs otherwise.

The patch does not include corresponding patches to the .html or .TXT
versions of the standard, since there the Makefile.am in devel-docs is
not set up to build them. I would appreciate it if the relevant people
would look over this patch and tell me if it is acceptable or else what
should be changed. I can check it in myself but I can't regenerate the
derived files, so someone else will have to do that.

 - Maciej

cvs server: Diffing wm-comp
Index: wm-comp/wm-comp.sgml
===================================================================
RCS file: /cvs/gnome/gnome-libs/devel-docs/wm-comp/wm-comp.sgml,v
retrieving revision 1.1
diff -u -r1.1 wm-comp.sgml
--- wm-comp.sgml	1999/02/15 15:27:50	1.1
+++ wm-comp.sgml	1999/02/16 01:06:01
@@ -1,9 +1,16 @@
-<book>
-<title>GNOME Window Manager Compliance - How to write a GNOME compliant Window Manager</title>
+<book> <title>GNOME Window Manager Compliance - How to write a GNOME
+compliant Window Manager</title>
 
 
-<para>This document provides quick and concise information for authors of Window Managers for the X Window System who wish to support the GNOME Desktop and its applications. You need to have a very good and detailed knowledge of the X Window System, Xlib, and how Applications and a Window Manager interact. A knowledge of ICCCM and experience
-in dealing with client interaction within a Window Manager framework is also assumed.</para>
+<para>This document provides quick and concise information for authors
+of Window Managers for the X Window System who wish to support the
+GNOME Desktop and its applications. You need to have a good knowledge
+of the X Window System and Xlib, particularly window properties and
+client messages, A knowledge of ICCCM and experience in dealing with
+client interaction within a Window Manager framework is assumed. In
+addition to the <command>_WIN</command> hints documented here, a fully
+gnome-compliant window manager should also support all of the ICCCM
+and Motif hints, as well as X session management.</para>
 
 
 <chapter>
@@ -13,12 +20,25 @@
 <sect1>
 <title>Section 1 - Detection of a GNOME compliant Window Manager</title>
 
-<para>There is a single unambiguous way to detect if there currently is a GNOME compliant Window Manager running. It is the job of the Window Manager to set up a few things to make this possible. Using the following method it is also possible for applications to detect compliance by receiving an event when the Window Manager exits.</para>
+<para>There is a single unambiguous way to detect if there currently
+is a GNOME compliant Window Manager running. It is the job of the
+Window Manager to set up a few things to make this possible. Using the
+following method it is also possible for applications to detect
+compliance by receiving an event when the Window Manager exits.</para>
+
+<para>To do this the Window Manager should create a Window, that is a
+child of the root window. There is no need to map it, just create
+it. The Window Manager may reuse ANY window it has for this purpose -
+even if it is mapped, just as long as the window is never destroyed
+while the Window Manager is running.</para>
+
+<para>Once the Window is created the Window Manager should set a
+property on the root window of the name<command>
+_WIN_SUPPORTING_WM_CHECK</command>, and type CARDINAL. The atom's data
+would be a CARDINAL that is the Window ID of the window that was
+created above. The window that was created would ALSO have this
+property set on it with the same values and type.</para>
 
-<para>To do this the Window Manager should create a Window, that is a child of the root window. There is no need to map it, just create it. The Window Manager may reuse ANY window it has for this purpose - even if it is mapped, just as long as the window is never destroyed while the Window Manager is running.</para>
-
-<para>Once the Window is created the Window Manager should set a property on the root window of the name<command> _WIN_SUPPORTING_WM_CHECK</command>, and type CARDINAL. The atom's data would be a CARDINAL that is the Window ID of the window that was created above. The window that was created would ALSO have this property set on it with the same values and type.</para>
-
 <para>
 Example:
 
@@ -42,10 +62,15 @@
 
 <sect1>
 <title>Section 2 - Listing GNOME Window Manager Compliance</title>
-
-<para>It is important to list which parts of GNOME Window Manager compliance are supported. This is done fairly easily by doing the following:</para>
 
-<para>Create a property on the root window of the atom name<command> _WIN_PROTOCOLS</command>. This property contains a list(array)of atoms that are all the properties the Window Manager supports. These atoms are any number of the following:</para>
+<para>It is important to list which parts of GNOME Window Manager
+compliance are supported. This is done fairly easily by doing the
+following:</para>
+
+<para>Create a property on the root window of the atom name<command>
+_WIN_PROTOCOLS</command>. This property contains a list(array)of atoms
+that are all the properties the Window Manager supports. These atoms
+are any number of the following:</para>
 
 <para>
 <itemizedlist mark="none">
@@ -58,11 +83,19 @@
 <listitem>_WIN_WORKSPACE</listitem>
 <listitem>_WIN_WORKSPACE_COUNT</listitem>
 <listitem>_WIN_WORKSPACE_NAMES</listitem>
+<listitem>_WIN_AREA</listitem>
+<listitem>_WIN_AREA_COUNT</listitem>
 <listitem>_WIN_CLIENT_LIST</listitem>
 </itemizedlist>
 </para>
 
-<para>If you list one of these properties then you support it and applications can expect information provided by, or accepted by the Window Manager to work.</para>
+<para>The <command>_WIN_APP_STATE</command> and
+<command>_WIN_ICONS</command> hints are currently unused but are
+reserved for future use.
+
+<para>If you list one of these properties then you support it and
+applications can expect information provided by, or accepted by the
+Window Manager to work.</para>
 
 <para>
 <programlisting>
@@ -82,6 +115,8 @@
   list[6] = XInternAtom(disp, "_WIN_WORKSPACE", False);
   list[7] = XInternAtom(disp, "_WIN_WORKSPACE_COUNT", False);
   list[8] = XInternAtom(disp, "_WIN_WORKSPACE_NAMES", False);
+  list[6] = XInternAtom(disp, "_WIN_AREA", False);
+  list[7] = XInternAtom(disp, "_WIN_AREA_COUNT", False);
   list[9] = XInternAtom(disp, "_WIN_CLIENT_LIST", False);
   XChangeProperty(disp, root_window, atom_set, XA_ATOM, 32, PropModeReplace,
                   (unsigned char *)list, 10);
@@ -93,7 +128,13 @@
 <sect1>
 <title>Section 3 - Providing Shortcuts Managed Clients</title>
 
-<para>As an aide in having external applications be able to list and access clients being managed by the Window Manager, a property should be set on the root window of the name<command> _WIN_CLIENT_LIST</command> which is an array of type CARDINAL. Each entry is the Window ID of a managed client. If the list of managed clients changes, clients are added or deleted, this list should be updated. </para>
+<para>As an aide in having external applications be able to list and
+access clients being managed by the Window Manager, a property should
+be set on the root window of the name <command>
+_WIN_CLIENT_LIST</command> which is an array of type CARDINAL. Each
+entry is the Window ID of a managed client. If the list of managed
+clients changes, clients are added or deleted, this list should be
+updated. </para>
 
 <para>
 Example:
@@ -120,12 +161,29 @@
 <sect1>
 <title>Section 3 -  Providing Multiple/Virtual Desktop Information.</title>
 
-<para>If your Window Manager supports the concept of Multiple/Virtual Desktops or Workspaces then you will definitely want to include it. This involves your Window Manager setting several properties on the root window. </para>
+<para>If your Window Manager supports the concept of Multiple/Virtual
+Desktops or Workspaces then you will definitely want to include
+it. This involves your Window Manager setting several properties on
+the root window. </para>
+
+<para>First you should advertise how many Desktops your Window Manager
+supports. This is done by setting a property on the root window with
+the atom name _WIN_WORKSPACE_COUNT of type CARDINAL. The properties
+data is a 32-bit integer that is the number of Desktops your Window
+Manager currently supports. If you can add and delete desktops while
+running, you may change this property and its value whenever
+required. You should also set a property of the atom _WIN_WORKSPACE of
+type CARDINAL that contains the number of the currently active desktop
+(which is a number between 0 and the number advertised by
+_WIN_WORKSPACE_COUNT - 1). Whenever the active desktop changes, change
+this property.</para>
+
+<para>Lastly you should set a property that is a list of strings
+called _WIN_WORKSPACE_NAMES that contains names for the desktops (the
+first string is the name of the first desktop, the second string is
+the second desktop, etc.). This will allow applications to know what
+the name of the desktop is too, possibly to display it.</para>
 
-<para>First you should advertise how many Desktops your Window Manager supports. This is done by setting a property on the root window with the atom name _WIN_WORKSPACE_COUNT of type CARDINAL. The properties data is a 32-bit integer that is the number of Desktops your Window Manager currently supports. If you can add and delete desktops while running, you may change this property and its value whenever required. You should also set a property of the atom _WIN_WORKSPACE of type CARDINAL that contains the number of the currently active desktop (which is a number between 0 and the number advertised by _WIN_WORKSPACE_COUNT - 1). Whenever the active desktop changes, change this property.</para> 
-
-<para>Lastly you should set a property that is a list of strings called _WIN_WORKSPACE_NAMES that contains names for the desktops (the first string is the name of the first desktop, the second string is the second desktop, etc.). This will allow applications to know what the name of the desktop is too, possibly to display it.</para>
-
 <para>
 Example:
 
@@ -174,10 +232,23 @@
 
 <sect1>
 <title>Section 1 - Initial Properties Set On Client Window</title>
-
-<para>When a client first maps a window, before calling XMapWindow, it will set properties on the client window with certain atoms as their types. The property atoms set can be any or all of _WIN_LAYER, _WIN_STATE, _WIN_WORKSPACE, _WIN_EXPANDED_SIZE and _WIN_HINTS. </para>
 
-<para>Each of these properties is of the type CARDINAL, and _WIN_EXPANDED_SIZE is an array of 4 CARDINAL's. For the _WIN_STATE and _WIN_HINTS properties, the bits set mean that state/property is desired by the client. The bitmask for _WIN_STATE is as follows:</para>
+<para>When a client first maps a window, before calling XMapWindow, it
+will set properties on the client window with certain atoms as their
+types. The property atoms set can be any or all of _WIN_LAYER,
+_WIN_STATE, _WIN_WORKSPACE, _WIN_EXPANDED_SIZE and _WIN_HINTS. Each of
+these properties is of the type CARDINAL.</para>
+
+<para>_WIN_EXPANDED_SIZE is an array of 4 CARDINAL's representing an X
+coordinate, a Y coordinate, a width and a height. This is a hint from
+the application to the window manager that it may change to this
+larger geometry (if it has hide and expand buttons for instance), and
+the window manager may use this hint for smarter auto-placement and
+the like. The window manager should never set this property, </para>
+
+<para>For the _WIN_STATE and _WIN_HINTS properties, the bits set mean
+that state/property is desired by the client. The bitmask for
+_WIN_STATE is as follows:</para>
 
 <para>
 <programlisting>
@@ -194,8 +265,22 @@
 </programlisting>
 </para>
 
-<para>These are a simple bitmasks - if the bit is set, that state is desired by the application. Once the application window has been mapped it is the responsibility of the Window Manager to set these properties to the current state of the Window whenever it changes states. If the window is unmapped the application is again responsible, if unmapped by the application.</para>
+<para>These are a simple bitmasks - if the bit is set, that state is
+desired by the application. Once the application window has been
+mapped it is the responsibility of the Window Manager to set these
+properties to the current state of the Window whenever it changes
+states. If the window is unmapped the application is again
+responsible, if unmapped by the application. </para>
+
+<para>Some of the hints bear further explanation. The
+<command>WIN_STATE_HIDDEN</command> bit is redundant with the
+WIN_HINT_SKIP_TASKBAR bit below, and is currently unused. It may be
+removed in a future revision. <command>WIN_STATE_HID_WORKSPACE
+</command> and <command>WIN_STATE_HID_TRANSIENT</command> convey
+redundant information which may be determined from other hints, and
+are therefore also unused and deprecated.</para>
 
+
 <para>The bitmask for _WIN_HINTS is as follows:</para>
 
 <para>
@@ -208,13 +293,20 @@
 </programlisting>
 </para>
 
-
-<para>This is also a simple bitmask but only the application changes it, thus whenever this property changes the Window Manager should re-read it and honor any changes.</para>
-
-<para>_WIN_WORKSPACE is a CARDINAL that is the Desktop number the app would like to be on. This desktop number is updated by the Window Manager after the window is mapped and until the window is unmapped by the application. The value for
-this property is simply the numeric for the desktop 0, being the first desktop available.</para>
 
-<para>_WIN_LAYER is also a CARDINAL that is the stacking layer the application wishes to exist in. The values for this property are:</para>
+<para>This is also a simple bitmask but only the application changes
+it, thus whenever this property changes the Window Manager should
+re-read it and honor any changes.</para>
+
+<para>_WIN_WORKSPACE is a CARDINAL that is the Desktop number the app
+would like to be on. This desktop number is updated by the Window
+Manager after the window is mapped and until the window is unmapped by
+the application. The value for this property is simply the numeric for
+the desktop 0, being the first desktop available.</para>
+
+<para>_WIN_LAYER is also a CARDINAL that is the stacking layer the
+application wishes to exist in. The values for this property
+are:</para>
 
 <para>
 <programlisting>
@@ -229,13 +321,32 @@
 </para>
 
 
-<para>The application can choose one of these layers to exist in. It can also specify a layer other than the ones listed above if it wishes to exist between 2 layers. The layer remains constant and the window will always be arranged in stacking order between windows in the layers above and below its own layer. If the Window Manager changes the layer of an application it should change this property.</para>
+<para>The application can choose one of these layers to exist in. It
+can also specify a layer other than the ones listed above if it wishes
+to exist between 2 layers. The layer remains constant and the window
+will always be arranged in stacking order between windows in the
+layers above and below its own layer. If the Window Manager changes
+the layer of an application it should change this property. </para>
+
+<para>The <command>WIN_LAYER_DOCK</para> layer has a special meaning -
+the window manager should avoid the space taken up by windows in this
+layer when maximizing windows; it may also choose to avoid this space
+when placing windows. This is intended for applications like taskbars
+or panels which take up some portion of the screen. In the future, the
+special meaning of this layer may be replaced with a separate
+hint.</para>
+
 </sect1>
 
 <sect1>
 <title>Section 2 - State Change Requests</title>
 
-<para>After an application has mapped a window, it may wish to change its own state. To do this the client sends ClientMessages to the root window with information on how to change the application's state. Clients will send messages as follows:</para>
+<para>After an application has mapped a window, it may wish to change
+its own state. As documented previously, the client may set the
+_WIN_HINT and _WIN_EXPANDED_SIZE properties at any time. To request
+changes in _WIN_STATE or _WIN_LAYER, the client sends ClientMessages
+to the root window with information on how to change the application's
+state. Clients will send messages as follows:</para>
 
 <para>
 <programlisting>
@@ -274,7 +385,8 @@
 
 
 
-<para>If an application wishes to change the current active desktop it will send a client message to the root window as follows:</para>
+<para>If an application wishes to change the current active desktop it
+will send a client message to the root window as follows:</para>
 
 
 <para>
@@ -289,7 +401,8 @@
 </para>
 
 
-<para>If the Window Manager picks up any of these ClientMessage events it should honor them.</para>
+<para>If the Window Manager picks up any of these ClientMessage events
+it should honor them.</para>
 
 </sect1>
 </chapter>
@@ -298,12 +411,26 @@
 
 
 <chapter>
-<title>Desktop areas, button presses, and releases on the root window.</title>
+<title>Desktop areas, button presses, and releases on the root
+window.</title>
 
  <sect1>
- <title>Section 1 - Button press and release forwarding for the desktop window.</title>
+ <title>Section 1 - Button press and release forwarding for the
+desktop window.</title>
 
- <para>X imposes the limitation that only 1 client can be selected for button presses on a window - this is due to the implicit grab nature of button press events in X. This poses a problem when more than one client wishes to select for these events on the same window - E.g., the root window, or in the case of a WM that has more than one root window (virtual root windows) any of these windows. The solution to this is to have the client that receives these events handle any of the events it is interested in, and then ``proxy'' or ``pass on'' any events it does not care about. The traditional model has always been that the WM selects for button presses on the desktop, it is only natural that it keep doing this BUT have a way of sending unwanted presses onto some other process(es) that may well be interested.</para>
+ <para>X imposes the limitation that only 1 client can be selected for
+button presses on a window - this is due to the implicit grab nature
+of button press events in X. This poses a problem when more than one
+client wishes to select for these events on the same window - E.g.,
+the root window, or in the case of a WM that has more than one root
+window (virtual root windows) any of these windows. The solution to
+this is to have the client that receives these events handle any of
+the events it is interested in, and then ``proxy'' or ``pass on'' any
+events it does not care about. The traditional model has always been
+that the WM selects for button presses on the desktop, it is only
+natural that it keep doing this BUT have a way of sending unwanted
+presses onto some other process(es) that may well be
+interested.</para>
 
 
  <para>This is done as follows:</para>
@@ -356,12 +483,29 @@
 
  <sect1>
  <title>Section 2 - Desktop Areas as opposed to multiple desktops.</title>
-
- <para>The best way to explain this is as follows. Desktops are completely geometrically disjoint workspaces. They have no geometric relevance to each other in terms of the client window plane. Desktop Areas have geometric relevance - they are next to, above, or below each other. The best examples are FVWM's desktops and virtual desktops - you can have multiple desktops that are disjoint and each desktop can be N x M screens in size - these N x M areas are what are termed ``desktop areas'' for the purposes of this document and the WM API.</para>
-
- <para>If your WM supports both methods like FVMW, Enlightenment and possible others, you should use<command> _WIN_WORKSPACE</command> messages and atoms for the geometrically disjoint desktops - for geometrically arranged desktops you should use the<command> _WIN_AREA</command> messages and atoms. if you only support one of these it is preferable to use<command> _WIN_WORKSPACE</command> only.</para>
 
- <para>The APi for<command> _WIN_AREA</command> is very similar to<command> _WIN_WORKSPACE</command>. To advertise the size of your areas (E.g., N x M screens in size) you set an atom on the root window as follows:</para>
+ <para>The best way to explain this is as follows. Desktops are
+completely geometrically disjoint workspaces. They have no geometric
+relevance to each other in terms of the client window plane. Desktop
+Areas have geometric relevance - they are next to, above, or below
+each other. The best examples are FVWM's desktops and virtual desktops
+- you can have multiple desktops that are disjoint and each desktop
+can be N x M screens in size - these N x M areas are what are termed
+``desktop areas'' for the purposes of this document and the WM
+API.</para>
+
+ <para>If your WM supports both methods like FVMW, Enlightenment and
+possible others, you should use<command> _WIN_WORKSPACE</command>
+messages and atoms for the geometrically disjoint desktops - for
+geometrically arranged desktops you should use the<command>
+_WIN_AREA</command> messages and atoms. if you only support one of
+these it is preferable to use<command> _WIN_WORKSPACE</command>
+only.</para>
+
+ <para>The API for<command> _WIN_AREA</command> is very similar
+to<command> _WIN_WORKSPACE</command>. To advertise the size of your
+areas (E.g., N x M screens in size) you set an atom on the root window
+as follows:</para>
 
  <programlisting>
   Display            *disp;
@@ -393,7 +537,8 @@
  </programlisting>
 
 
-<para>If a client wishes to change what the current active area is they simply send a client message like:</para>
+<para>If a client wishes to change what the current active area is
+they simply send a client message like:</para>
 
 <programlisting>
   Display            *disp;
@@ -419,20 +564,11 @@
 <sect1>
 <title>Section 1 - What Else Is There?</title>
 
-<para>There are currently a set of other hints available that are, at the current time, not essential and therefore not documented here. It is, however envisaged that they will be finalized and added to this document, but for now are not needed.</para>
+<para>There are currently a set of other hints available that are, at
+the current time, not essential and therefore not documented here. It
+is, however envisaged that they will be finalized and added to this
+document, but for now are not needed.</para>
 
 </sect1>
 </chapter>
 </book>
-
-
-
-
-
-
-
-
-
-
-
-