summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authormatthiasc <matthiasc>2002-09-06 23:21:51 +0000
committermatthiasc <matthiasc>2002-09-06 23:21:51 +0000
commitbc84ce20c028d238da65f42fecb8494c4d8b5585 (patch)
tree80f7ad5520b4ae89736c87518012374d3e64ad98
parente0d503888872804a772b1479cbeb0934a01347a2 (diff)
downloadxdg-specs-bc84ce20c028d238da65f42fecb8494c4d8b5585.tar.xz
New draft.
-rw-r--r--wm-spec/wm-spec.sgml165
1 files changed, 126 insertions, 39 deletions
diff --git a/wm-spec/wm-spec.sgml b/wm-spec/wm-spec.sgml
index 1727454..0961ce4 100644
--- a/wm-spec/wm-spec.sgml
+++ b/wm-spec/wm-spec.sgml
@@ -1,6 +1,6 @@
<!doctype article PUBLIC "-//OASIS//DTD DocBook V4.1//EN" [
<!entity version "DRAFT version 1.2">
-<!entity date "August 19, 2002">
+<!entity date "September 7, 2002">
]>
<article id="index">
<articleinfo>
@@ -26,10 +26,11 @@ This is &version; of the Extended Window Manager Hints (EWMH) spec, updated &dat
<para>
This spec defines interactions between window managers, applications,
and the utilities that form part of a desktop environment. It builds
-on the ICCCM [2], which defines WM (window manager) interactions at a
-lower level. The ICCCM does not provide ways to implement many
-features that modern desktop users expect. The GNOME and KDE desktop
-projects originally developed their own extensions to the ICCCM to
+on the Inter-Client Communication Conventions Manual <citation><link
+ linkend="ICCCM">ICCCM</link></citation>, which defines
+window manager interactions at a lower level. The ICCCM does not provide ways
+to implement many features that modern desktop users expect. The GNOME and KDE
+desktop projects originally developed their own extensions to the ICCCM to
support these features; this spec replaces those custom extensions
with a standardized set of ICCCM additions that any desktop
environment can adopt.
@@ -46,7 +47,7 @@ interpreted as described in RFC 2119.
The key words "Window Manager" refer to a window manager which is adopting this
specification. "Pager" refers to desktop utility applications, including
pagers and taskbars. "Application" refers to other clients. "Clients" refers
-to Pagers + Applications ie. all X clients, except for the Window Manager.
+to Pagers and Applications ie. all X clients, except for the Window Manager.
</para>
</sect2>
<sect2>
@@ -260,7 +261,7 @@ argument).</para>
</sect2>
</sect1>
<sect1>
- <title>Root Window Properties (+Related Messages)</title>
+ <title>Root Window Properties (and Related Messages)</title>
<para>
Whenever this spec speaks about <quote>sending a message to the root
window</quote>, it is understood that the client is supposed to create
@@ -390,7 +391,9 @@ _NET_CURRENT_DESKTOP
_NET_DESKTOP_NAMES, UTF8_STRING[]
]]></programlisting>
<para>
-The names of all virtual desktops. This is a list of NULL-terminated strings in UTF-8 [1] encoding. This property MAY be changed by a Pager or the Window Manager at any time.
+The names of all virtual desktops. This is a list of NULL-terminated strings in
+ UTF-8 encoding <citation><link linkend="UTF8">UTF8</link></citation>. This property MAY be
+ changed by a Pager or the Window Manager at any time.
</para>
<para>
Note: The number of names could be different from _NET_NUMBER_OF_DESKTOPS.
@@ -631,7 +634,37 @@ The Window Manager MUST then attempt to close the window specified.
<para>
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 code, the Window Manager can easily do the job.
</para>
- </sect2><sect2><title>_NET_WM_MOVERESIZE</title>
+ </sect2>
+ <sect2><title>_NET_MOVERESIZE_WINDOW</title>
+<programlisting><![CDATA[
+_NET_MOVERESIZE_WINDOW
+ window = window to be moved or resized
+ message_type = _NET_MOVERESIZE_WINDOW
+ format = 32
+ data.l[0] = gravity
+ data.l[1] = x
+ data.l[2] = y
+ data.l[3] = width
+ data.l[4] = height
+]]></programlisting>
+ <para>
+ Pagers wanting to move or resize a window may send a
+ _NET_MOVERESIZE_WINDOW client message request to the root window
+ instead of using a ConfigureRequest.
+ </para>
+ <para>
+ Window Managers should treat a _NET_MOVERESIZE_WINDOW message exactly
+ like a ConfigureRequest (in particular, adhere to the ICCCM rules about
+ synthetic ConfigureNotify events), except that they should use the
+ gravity specified in the message.
+ </para>
+ <para>
+ Rationale: Using a _NET_MOVERESIZE_WINDOW message with StaticGravity
+ allows Pagers to exactly position and resize a window including its
+ decorations without knowing the size of the decorations.
+ </para>
+ </sect2>
+ <sect2><title>_NET_WM_MOVERESIZE</title>
<programlisting><![CDATA[
_NET_WM_MOVERESIZE
window = window to be moved or resized
@@ -881,7 +914,8 @@ _NET_WM_STATE_SKIP_TASKBAR, ATOM
_NET_WM_STATE_SKIP_PAGER, ATOM
_NET_WM_STATE_HIDDEN, ATOM
_NET_WM_STATE_FULLSCREEN, ATOM
-_NET_WM_STATE_FLOATING, ATOM
+_NET_WM_STATE_ABOVE, ATOM
+_NET_WM_STATE_BELOW, ATOM
]]></programlisting>
<para>
An implementation MAY add new atoms to this list. Implementations
@@ -930,27 +964,34 @@ 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>
<para>
-Implementation note: if an application asks to toggle
-_NET_WM_STATE_HIDDEN the window manager should probably just ignore
+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
-this hint.
+_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 this hint.
</para>
<para>
-_NET_WM_STATE_FLOATING indicates that the window should be on top of other
-windows of the same type. Applications should not set this hint
-if _NET_WM_WINDOW_TYPE already conveys the exact nature of the window.
-Windows in this state would typically appear above other windows of the same
-_NET_WM_WINDOW_TYPE.
+_NET_WM_STATE_ABOVE indicates that the window should be on top of most
+windows (see <xref linkend="STACKINGORDER"> for details).
+ </para>
+
+ <para>
+_NET_WM_STATE_BELOW indicates that the window should be below most
+windows (see <xref linkend="STACKINGORDER"> for details).
+ </para>
+
+ <para>
+ _NET_WM_STATE_ABOVE and _NET_WM_STATE_BELOW are mainly meant for user
+ preferences and should not be used by applications e.g. for drawing
+ attention to their dialogs (the Urgency
+ hint should be used in that case, see <xref linkend="URGENCY">).'
</para>
<para>
@@ -993,6 +1034,7 @@ Possible atoms are:
<programlisting><![CDATA[
_NET_WM_ACTION_MOVE, ATOM
_NET_WM_ACTION_RESIZE, ATOM
+_NET_WM_ACTION_MINIMIZE, ATOM
_NET_WM_ACTION_SHADE, ATOM
_NET_WM_ACTION_STICK, ATOM
_NET_WM_ACTION_MAXIMIZE_HORZ, ATOM
@@ -1029,6 +1071,9 @@ _NET_WM_ACTION_RESIZE indicates that the window may be resized.
window because its minimum and maximum size in WM_NORMAL_HINTS will be the same.)
</para>
<para>
+_NET_WM_ACTION_MINIMIZE indicates that the window may be iconified.
+ </para>
+ <para>
_NET_WM_ACTION_SHADE indicates that the window may be shaded.
</para>
<para>
@@ -1044,7 +1089,7 @@ _NET_WM_ACTION_MAXIMIZE_VERT indicates that the window may be maximized vertical
</para>
<para>
_NET_WM_ACTION_FULLSCREEN indicates that the window may be brought to
- fullscreen mode.
+ fullscreen state.
</para>
<para>
_NET_WM_ACTION_CHANGE_DESKTOP indicates that the window may be moved between desktops.
@@ -1287,7 +1332,8 @@ document offers the following clarifications:
<itemizedlist>
<listitem><para>
Window managers MUST honour the win_gravity field of WM_NORMAL_HINTS
- for both MapRequest _and_ ConfigureRequest events [1]
+ for both MapRequest _and_ ConfigureRequest events (ICCCM Version 2.0,
+ &sect;4.1.2.3 and &sect;4.1.5)
</para></listitem>
<listitem><para>
Applications are free to change their win_gravity setting at any time
@@ -1305,7 +1351,7 @@ corner of the frame.
<listitem><para>
When generating synthetic ConfigureNotify events, the position given
MUST be the top-left corner of the client window in relation to the
- origin of the root window (i.e., ignoring win_gravity) [2]
+ origin of the root window (i.e., ignoring win_gravity) (ICCCM Version 2.0, &sect;4.2.3)
</para></listitem>
<listitem><para>
XMoveWindow(w,x,y) behaviour depends on the window gravity. Upon receiving a
@@ -1460,12 +1506,6 @@ initial window's width should be taken into consideration, as if it
was the frame for this window.
</para></listitem>
</itemizedlist>
- <para>
-[1] ICCCM Version 2.0, &sect;4.1.2.3 and &sect;4.1.5
- </para>
- <para>
-[2] ICCCM Version 2.0, &sect;4.2.3
- </para>
</sect2>
<sect2>
<title>Window-in-Window MDI</title>
@@ -1522,16 +1562,56 @@ int net_get_hostname (char *buf, size_t maxlen)
]]></programlisting>
</para>
</sect2>
+
+ <sect2 id="STACKINGORDER">
+ <title>Stacking order</title>
+ <para>
+ To obtain good interoperability between different Desktop Environments,
+ the following layered stacking order is recommended, from the bottom:
+ <itemizedlist>
+ <listitem><para>windows of type _NET_WM_TYPE_DESKTOP</para></listitem>
+ <listitem><para>windows having state _NET_WM_STATE_BELOW</para></listitem>
+ <listitem><para>windows not belonging in any other layer</para></listitem>
+ <listitem><para>windows of type _NET_WM_TYPE_DOCK (unless they have
+ state _NET_WM_TYPE_BELOW) and windows having state
+ _NET_WM_STATE_ABOVE</para></listitem>
+ <listitem><para>focused windows having state
+ _NET_WM_STATE_FULLSCREEN</para></listitem>
+ </itemizedlist>
+ </para>
+ <para>
+ Windows that are transient for another window should be kept
+ above this window.
+ </para>
+ <para>
+ The window manager may choose to put some windows in different
+ stacking position, for example to allow user to bring currently active
+ window to the top and return it back when the window looses focus.
+ </para>
+ </sect2>
</Sect1>
<Sect1>
<title>References</title>
- <para>
-[1] F. Yergeau,"UTF-8, a transformation format of ISO 10646", RFC 2279
+ <variablelist>
+ <varlistentry>
+ <term>[UTF8]</term>
+ <listitem>
+ <para id="UTF8">
+ F. Yergeau,"UTF-8, a transformation format of ISO 10646", RFC 2279
</para>
- <para>
-[2] David Rosenthal / Stuart W. Marks "Inter-Client Communication Conventions
- Manual (Version 2.0)", X Consortium Standard, X Version 11, Release 6.3
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>[ICCCM]</term>
+ <listitem>
+ <para id="ICCCM">
+ David Rosenthal and Stuart W. Marks, "Inter-Client Communication
+ Conventions Manual (Version 2.0)", X Consortium Standard, X Version 11,
+ Release 6.3
</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
</Sect1>
<Sect1>
<title>Copyright</title>
@@ -1632,8 +1712,15 @@ OR OTHER DEALINGS IN THE SOFTWARE.
Added _NET_SHOWING_DESKTOP.
</para></listitem>
<listitem><para>
- Added _NET_WM_STATE_FLOATING.
- </para></listitem>
+ Added _NET_WM_STATE_ABOVE and _NET_WM_STATE_BELOW and a recommended layered
+ stacking order.
+ </para></listitem>
+ <listitem><para>
+ Added _NET_MOVERESIZE_WINDOW.
+ </para></listitem>
+ <listitem><para>
+ Improve markup of citations.
+ </para></listitem>
</itemizedlist>
</sect2>
<sect2>