commit _NET_WM_STATE_HIDDEN docs, apparently I hadn't commited them before.

1 files changed, 84 insertions, 9 deletions

diff --git a/wm-spec/wm-spec.sgml b/wm-spec/wm-spec.sgml
index 17ed1d3..836997a 100644
--- a/wm-spec/wm-spec.sgml
+++ b/wm-spec/wm-spec.sgml
@@ -160,11 +160,13 @@ The first is to use multiple virtual roots (see <xref linkend="largedesksimpl">)
 desktop by manipulating the stacking order of the virtual roots.  This is 
 completely ICCCM compliant, but has the issues outlined in <xref linkend="largedesksimpl"></para>
 <para>The second option is to keep all managed windows as children of the root 
-window and unmap the frames of those which are not on the current desktop.
-This puts the clients in an undefined ICCCM state, since they are unviewable,
-but not iconic.  In practice, this seems to cause no problems and the ICCCM
-compliant alternative to iconify all clients on non-current desktops (without
-showing their icons) is clearly not acceptable.</para>
+window and unmap the frames of those which are not on the current
+desktop. Unmapped windows should be placed in IconicState, according to 
+the ICCCM. Windows which are actually iconified or minimized 
+should have the _NET_WM_STATE_HIDDEN property set, to 
+communicate to pagers that the window should not be represented as 
+"onscreen."
+</para>
 </sect3>
 </sect2>
 <sect2>
@@ -685,6 +687,7 @@ _NET_WM_STATE_MAXIMIZED_HORZ, ATOM
 _NET_WM_STATE_SHADED, ATOM
 _NET_WM_STATE_SKIP_TASKBAR, ATOM
 _NET_WM_STATE_SKIP_PAGER, ATOM
+_NET_WM_STATE_HIDDEN, ATOM
 _NET_WM_STATE_FULLSCREEN, ATOM
 ]]></programlisting>
       <para>
@@ -711,13 +714,39 @@ _NET_WM_STATE_MAXIMIZED_{VERT,HORZ} indicates that the window is
 _NET_WM_STATE_SHADED indicates that the window is shaded.
 	</para>
 	<para>
-_NET_WM_STATE_SKIP_TASKBAR indicates that the window should not be included on a
-taskbar.
+_NET_WM_STATE_SKIP_TASKBAR indicates that the window should not be
+included on a taskbar. This hint should be requested by the
+application, i.e. it indicates that the window by nature is never
+in the taskbar.  Applications should not set this hint if
+_NET_WM_WINDOW_TYPE already conveys the exact nature of the
+window.
 	</para>
 	<para>
-_NET_WM_STATE_SKIP_PAGER indicates that the window should not be included on a
-pager.
+_NET_WM_STATE_SKIP_PAGER indicates that the window should not be
+included on a pager. This hint should be requested by the application,
+i.e. it indicates that the window by nature is never in the
+pager. Applications should not set this hint if _NET_WM_WINDOW_TYPE
+already conveys the exact nature of the window.
 	</para>
+        <para>
+_NET_WM_STATE_HIDDEN should be set by the window manager to indicate
+that a window would not be visible on the screen if its
+desktop/viewport were active and its coordinates were within the
+screen bounds. The canonical example is that minimized windows should
+be in the _NET_WM_STATE_HIDDEN state.  Pagers and similar applications
+should use _NET_WM_STATE_HIDDEN instead of WM_STATE to decide whether
+to display a window in miniature representations of the windows on a
+desktop.
+<footnote>
+<para>
+Implementation note: if an application asks to toggle
+_NET_WM_STATE_HIDDEN the window manager should probably just ignore
+the request, since _NET_WM_STATE_HIDDEN is a function of some other
+aspect of the window such as minimization, rather than an independent
+state.
+</para>
+</footnote>
+        </para>
 	<para>
 _NET_WM_STATE_FULLSCREEN indicates that the window should fill the entire screen
 and have no window decorations. For example, a presentation program would use
@@ -1001,6 +1030,45 @@ unlikely to break anything, it seems reasonable to document it as standard.
 	<para>
 	This specification attempts to make reasonable provisions for WM independent pagers and taskbars.  Window Managers that require / desire additional functionality beyond what can be achieved using the mechanisms set out in this specification may choose to implement their own pagers, which communicates with the Window Manager using further, WM-specific hints, or some other means.
 	</para>
+        <para>
+        Pagers should decide whether to show a miniature version of a
+        window using the following guidelines:
+          <itemizedlist>
+            <listitem>
+              <para>
+                If either _NET_WM_STATE_SKIP_PAGER or
+                _NET_WM_STATE_HIDDEN are set on a window, then the
+                pager should not show that window.
+              </para>
+            </listitem>
+            <listitem>
+              <para>
+                The pager may choose not to display windows with 
+                certain semantic types; this spec has no
+                recommendations, but common practice is to avoid 
+                displaying _NET_WM_WINDOW_TYPE_DOCK for example.
+              </para>
+            </listitem>
+            <listitem>
+              <para>
+                If the _NET_WM_STATE_SKIP_PAGER and
+                _NET_WM_STATE_HIDDEN hints are not present, and the
+                window manager claims to support _NET_WM_STATE_HIDDEN,
+                then the window should be shown if it's in either
+                NormalState or IconicState.
+              </para>
+            </listitem>
+            <listitem>
+              <para>
+                For window managers that do not support
+                _NET_WM_STATE_HIDDEN, the pager should 
+                not show windows in IconicState. These window 
+                managers are probably using an older version 
+                of this specification.
+              </para>
+            </listitem>
+          </itemizedlist>
+        </para>
 	</sect2>
 	<sect2>
 	<title>Window Movement</title>
@@ -1332,6 +1400,13 @@ OR OTHER DEALINGS IN THE SOFTWARE.
  			<listitem><para>
  Added _NET_WM_ALLOWED_ACTIONS.
  			</para></listitem>
+ 			<listitem><para>
+ Added _NET_WM_STATE_HIDDEN and clarified purpose of
+ _NET_WM_STATE_SKIP_PAGER and _NET_WM_STATE_SKIP_TASKBAR. Changed
+ section on virtual desktop implementation to suggest ICCCM compliance
+ regarding IconicState, using _NET_WM_STATE_HIDDEN to avoid confusion.
+ Added implementation note for pagers on when to display a window.
+ 			</para></listitem>
  	</itemizedlist>
  	</sect2>
     <sect2>