diff options
| -rw-r--r-- | wm-spec/wm-spec.sgml | 165 |
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, + §4.1.2.3 and §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, §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, §4.1.2.3 and §4.1.5 - </para> - <para> -[2] ICCCM Version 2.0, §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> |