From b58352845cebc1d3b5754215a03ed047d1b28b11 Mon Sep 17 00:00:00 2001 From: jools Date: Wed, 22 Nov 2000 21:40:56 +0000 Subject: update version: David's comments (thanks David!) Sasha revisions to the window gravity stuff (unless somebody finds that it's incorrect) UTF-8 = RFC 2279 reference X style copyright - copied from ICCCM Revision -> 1.0 ! (objections ?) --- wm-spec/wm-spec.sgml | 1039 ++++++++++++++++++++++++++++---------------------- 1 file changed, 592 insertions(+), 447 deletions(-) diff --git a/wm-spec/wm-spec.sgml b/wm-spec/wm-spec.sgml index 7cc89fd..cc67e3a 100644 --- a/wm-spec/wm-spec.sgml +++ b/wm-spec/wm-spec.sgml @@ -10,7 +10,7 @@ Version -This spec is version 1.0pre5. +This spec is version 1.0. @@ -42,276 +42,6 @@ explicitly modifies the ICCCM Window Managers and Clients MUST fulfil these modifications. - - Changes since 1.0pre4 - - -Clarified the interpretation of client-provided geometries on large desktops. - - -Added more explanation for _NET_DESKTOP_NAMES. - - -Added _NET_WM_ICON_NAME and _NET_WM_VISIBLE_ICON_NAME. - - -Tried to improve the wording of _NET_WM_STRUT explanation. - - -Changed _NET_WORKAREA to an array of viewport-relative geometries. - - -Updated list of dependent properties for _NET_NUMBER_OF_DESKTOPS -to include _NET_WORKAREA and _NET_DESKTOP_VIEWPORT. - - -Tidied formatting of all client messages. - - - - - Changes since 1.0pre3 - - -Added information about common non-ICCCM features. - - -Added explanation of sending messages to the root window. - - -Removed XA_ prefix from type names. - - -Clarified that mapping order refers to inital mapping -and specify the directions of both orders. - - -Clarified that desktops have a common size specified by _NET_DESKTOP_GEOMETRY. - - -Rewrote explanation of _NET_DESKTOP_VIEWPORT. - - -Tidied formatting of _NET_CURRENT_DESKTOP. - - -Replaced window handle by window ID. - - -Tidied formatting of _NET_WORKAREA. - - -Rewrote the motivation for _NET_VIRTUAL_ROOTS. - - -Added advice on Pointer grabs to _NET_WM_MOVERESIZE. - - -Fixed typos in _NET_WM_STATE. - - -Added _NET_WM_STATE_SKIP_PAGER. - - -Tidied formatting of _NET_WM_STRUT. - - -Tidied formatting of _NET_WM_ICON_GEOMETRY. - - - - - Changes since 1.0pre2 - - -_NET_SET_NUMBER_OF_DESKTOPS -> _NET_NUMBER_OF_DESKTOPS for consistency. - - -_NET_WM_VISIBLE_NAME_STRING -> _NET_WM_VISIBLE_NAME for consistency. - - -_NET_WM_STATE: added explanation of permitted extensions. Added explanation of -being set / not set. - - -Spellchecked, corrected various typos. - - -UTF8 -> UTF-8 for consistency. - - -added references to the ICCCM an UTF-8 (incomplete). - - -added data and event formats where missing. - - -clarified _NET_SUPPORTING_WM_CHECK. - - -fixed formatting of _NET_CLOSE_WINDOW message. - - - - - Changes since 1.0pre1 - - -Removed implementation note concerning Gnome's (potential) file manager behaviour. - - -The Window Movement section of the implementation notes has been revised. - - - - - Changes since 1.9f - - -Revised revision number for first accepted release 1.9XX -> 1.0preXX. - - -Prerequisites for adoption of this specification added. - - -Tidied formatting of _NET_CURRENT_DESKTOP for consistency. - - -Tidied formatting of _NET_ACTIVE_WINDOW for consistency. Removed doubled text. - - -Tidied formatting of _NET_WM_DESKTOP for consistency. - - -Killing Hung Processes implementation note added. _NET_WM_PID and _NET_WM_PING now link to this. - - -Clarified x_root and y_root meaning for _NET_WM_MOVERESIZE. - - -Added contributor list. - - - - - Changes since 1.9e - - -Added _NET_WM_VISIBLE_NAME_STRING - - -Removed ambiguity from _NET_NUMBER_OF_DESKTOPS and _NET_DESKTOP_NAMES in combination. - - -Set _NET_WM_MOVERESIZE format to 32 for consistency. - - -Removed _NET_PROPERTIES. - - -Removed comment from _NET_WM_MOVERESIZE. - - - - - Changes since 1.9d - - -Added _NET_VIRTUAL_ROOTS - - -Added note about ICCCM compliant window moves. - - -Added _NET_WM_HANDLED_ICONS - - -Added _NET_SUPPORTING_WM_CHECK - - -Removed degrees of activation - - - - - Changes since 1.9c - - - -Removed packaging of hints into 2 X properties. Jim Gettys points out that the -performance gains of fewer round trips can be better achieved using Xlib -routines. - - - - -Clarified that _NET_DESKTOP_VIEWPORT is in pixels - - - - -_NET_DESKTOP_VIEWPORT is now an array, one for each desktop, to allow for -different active viewports on different desktops - - - - -_NET_WM_STRUT now only applies on desktops on which the client is visible - - - - -Introduced RFC 2119 language, and attempted to clarify the roles of the Window -Manager, Pagers and Applications - - - - -Added _NET_WM_NAME - - - - -_NET_DESKTOP_NAMES now in UTF8 - - - - -Desktops now start from 0 - - - - -Added _NET_WM_PID - - - - -Added _NET_WM_PING protocol - - - - -Added _NET_WM_STATE_SKIP_TASKBAR - - - - - - - Changes since 1.9b - - Removed _NET_NUMBER_OF_DESKTOPS client message, as it overlaps unnecessarily with _NET_{INSERT/DELETE}_DESKTOP. - - Replaced _NET_WM_LAYER and _NET_WM_HINTS with _NET_WM_WINDOW_TYPE functional hint. - Changed _NET_WM_STATE to a list of atoms, for extensibility. - Expanded description of _NET_WORKAREA and _NET_WM_STRUT. - Removed _NET_WM_SIZEMOVE_NOTIFY protocol. - Added degrees of activation to _NET_ACTIVE_WINDOW client message - Added _NET_WM_ICON - My comments are in [[ ]]. Comments from Marko's draft are in [[MM: ]] - - Non-ICCCM features @@ -1106,194 +836,609 @@ independent desktops which may or may not be larger than the screen area. When a desktop is larger than the screen it is left to the window manager if it will implement scrolling or paging. - - - File Manager desktop + + + File Manager desktop + +This spec suggests implementing the file manager desktop by mapping a +desktop-sized window (no shape) to all desktops, with +_NET_WM_WINDOW_TYPE_DESKTOP. This makes the desktop focusable and greatly +simplifies implementation of the file manager. It is also faster than +managing lots of small shaped windows. The file manager draws the background +on this window. There should be a root property with a window handle for use +in applications that want to draw the background (xearth). + + + + Implementing enhanced support for application transient windows + +If the WM_TRANSIENT_FOR property is set to None or Root window, the window +should be treated as a transient for all other windows in the same group. It +has been noted that this is a slight ICCCM violation, but as this behaviour is +pretty standard for many toolkits and window managers, and is extremely +unlikely to break anything, it seems reasonable to document it as standard. + + + + Urgency + + Dialog boxes should indicate their urgency level (information or warning) using the urgency bit in the WM_HINTS.flags property, as defined in the ICCCM. + + + + Fixed size windows + + Windows can indicate that they are non-resizable by setting minheight = maxheight and minwidth = maxwidth in the ICCCM WM_NORMAL_HINTS property. The Window Manager MAY decorate such windows differently. + + + + Pagers and Taskbars + + 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. + + + + Window Movement + +Window manager implementors should refer to the ICCCM for definitive +specifications of how to handle MapRequest and ConfigureRequest events. +However, since these aspects of the ICCCM are easily misread, this +document offers the following clarifications: + + + +Window managers MUST honour the win_gravity field of WM_NORMAL_HINTS + for both MapRequest _and_ ConfigureRequest events [1] + + +Applications are free to change their win_gravity setting at any time + + +If application changes its gravity then Window manager should adjust the +reference point, so that client window will not move as the result. +For example if client's gravity was NorthWestGravity and reference point +was +at the top-left corner of the frame window, then after change of gravity to +the SouthEast reference point should be adjusted to point to the +lower-right +corner of the frame. + + +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] + + +XMoveWindow(w,x,y) behaviour depends on the window gravity. Upon receiving a +request from client application the Window Manager calculates a new reference +point, based on the client window's own size, border width and gravity. For given client +window dimentions (width, height) and border width (bw), the reference point will be +placed at: + + + + + + Gravity: + ref_x: + ref_y: + + + StaticGravity + x + y + + + NorthWestGravity + x-bw + y-bw + + + NorthGravity + x+(width/2) + y-bw + + + NorthEastGravity + x+width+bw + y-bw + + + EastGravity + x+width+bw + y+(height/2) + + + SouthEastGravity + x+width+bw + y+height+bw + + + SouthGravity + x+(width/2) + y+height+bw + + + SouthWestGravity + x-bw + y+height+bw + + + WestGravity + x-bw + y+(height/2) + + + CenterGravity + x+(width/2) + y+(height/2) + + + + + + +The Window manager will use the reference point as calculated above, +until next XMoveWindow request. The Window Manager will place frame decorations +in the following position, based on the window gravity : + + +StaticGravity: + + +window's left top corner will be placed at (ref_x,ref_y) + + +NorthWestGravity: + + +window frame's left top corner will be placed at (ref_x,ref_y) + + +NorthGravity: + + +window frame's top side's center will be placed at (ref_x,ref_y) + + +NorthEastGravity: + + +window frame's right top corner will be placed at (ref_x,ref_y) + + +EastGravity: + + +window frame's right side's center will be placed at (ref_x,ref_y) + + +SouthWestGravity: + + +window frame's left bottom corner will be placed at (ref_x,ref_y) + + +SouthGravity: + + +window frame's bottom side's center will be placed at (ref_x,ref_y) + + +SouthEastGravity: + + +window frame's right bottom corner will be placed at (ref_x,ref_y) + + +WestGravity: + + +window frame's left side's center will be placed at (ref_x,ref_y) + + +CenterGravity: + + +window frame's center will be placed at (ref_x,ref_y) + + + +Implementation Note for Application developers: + -This spec suggests implementing the file manager desktop by mapping a -desktop-sized window (no shape) to all desktops, with -_NET_WM_WINDOW_TYPE_DESKTOP. This makes the desktop focusable and greatly -simplifies implementation of the file manager. It is also faster than -managing lots of small shaped windows. The file manager draws the background -on this window. There should be a root property with a window handle for use -in applications that want to draw the background (xearth). +When client window is resized - its reference point does not move. +So for example if window has SouthEastGravity and it is resized - +the bottom-right corner of its frame will not move but instead +top-left corner will be adjusted by the difference in size. + + +Implementation Note for WM developers : + +when calculating reference point at the time of initial placement - +initial window's width should be taken into consideration, as if it +was the frame for this window. + + + +[1] ICCCM Version 2.0, 4.1.2.3 and 4.1.5 + + +[2] ICCCM Version 2.0, 4.2.3 + - Implementing enhanced support for application transient windows - -If the WM_TRANSIENT_FOR property is set to None or Root window, the window -should be treated as a transient for all other windows in the same group. It -has been noted that this is a slight ICCCM violation, but as this behaviour is -pretty standard for many toolkits and window managers, and is extremely -unlikely to break anything, it seems reasonable to document it as standard. - + Window-in-Window MDI + + The authors of this specification acknowledge that there is no standard method to allow the Window Manager to manage windows that are part of a Window-in-Window MDI application. Application authors are advised to use some other form of MDI, or to propose a mechanism to be included in the next revision of this specification. + - - Urgency + + Killing Hung Processes - Dialog boxes should indicate their urgency level (information or warning) using the urgency bit in the WM_HINTS.flags property, as defined in the ICCCM. +If processes fail to respond to the _NET_WM_PING protocol _NET_WM_PID may be used in combination with the ICCCM specified WM_CLIENT_MACHINE(STRING) to attempt to kill a process. - - Fixed size windows - - Windows can indicate that they are non-resizable by setting minheight = maxheight and minwidth = maxwidth in the ICCCM WM_NORMAL_HINTS property. The Window Manager MAY decorate such windows differently. - + + + References + +[1] F. Yergeau,"UTF-8, a transformation format of ISO 10646", RFC 2279 + + +[2] David Rosenthal / Stuart W. Marks "Inter-Client Communication Conventions + Manual (Version 2.0)", X Consortium Standard, X Version 11, Release 6.3 + + + + Copyright + +Copyright (C) 2000 See Contributors List + + +Permission is hereby granted, free of charge, to any person +obtaining a copy of this software and associated documentation +files (the "Software"), to deal in the Software without +restriction, including without limitation the rights to use, +copy, modify, merge, publish, distribute, sublicense, and/or +sell copies of the Software, and to permit persons to whom +the Software is furnished to do so, subject to the following +conditions: + + +The above copyright notice and this permission notice shall +be included in all copies or substantial portions of the +Software. + + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY +KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE +WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE +AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS +BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, +WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING +FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE +OR OTHER DEALINGS IN THE SOFTWARE. + + + + Contributors + + Sasha Vasko + Bradley T. Hughes + Dominik Vogt + Havoc Pennington + Jeff Raven + Jim Gettys + John Harper + Julian Adams + Matthias Ettrich + Micheal Rogers + Nathan Clemons + Tim Janik + Tomi Ollila + Sam Lantinga + The Rasterman + Paul Warren + Owen Taylor + Marko Macek + Greg Badros + Matthias Clasen + David Rosenthal + + + + Change history + + Changes since 1.0pre5 + + +Change history moved to end. + + +UTF-8 Reference updated. + + +Window Gravity information updated. + + +Copyright Added. + + +Minor typo corrections. + + + + + Changes since 1.0pre4 + + +Clarified the interpretation of client-provided geometries on large desktops. + + +Added more explanation for _NET_DESKTOP_NAMES. + + +Added _NET_WM_ICON_NAME and _NET_WM_VISIBLE_ICON_NAME. + + +Tried to improve the wording of _NET_WM_STRUT explanation. + + +Changed _NET_WORKAREA to an array of viewport-relative geometries. + + +Updated list of dependent properties for _NET_NUMBER_OF_DESKTOPS +to include _NET_WORKAREA and _NET_DESKTOP_VIEWPORT. + + +Tidied formatting of all client messages. + + - Pagers and Taskbars - - 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. - + Changes since 1.0pre3 + + +Added information about common non-ICCCM features. + + +Added explanation of sending messages to the root window. + + +Removed XA_ prefix from type names. + + +Clarified that mapping order refers to inital mapping +and specify the directions of both orders. + + +Clarified that desktops have a common size specified by _NET_DESKTOP_GEOMETRY. + + +Rewrote explanation of _NET_DESKTOP_VIEWPORT. + + +Tidied formatting of _NET_CURRENT_DESKTOP. + + +Replaced window handle by window ID. + + +Tidied formatting of _NET_WORKAREA. + + +Rewrote the motivation for _NET_VIRTUAL_ROOTS. + + +Added advice on Pointer grabs to _NET_WM_MOVERESIZE. + + +Fixed typos in _NET_WM_STATE. + + +Added _NET_WM_STATE_SKIP_PAGER. + + +Tidied formatting of _NET_WM_STRUT. + + +Tidied formatting of _NET_WM_ICON_GEOMETRY. + + + + + Changes since 1.0pre2 + + +_NET_SET_NUMBER_OF_DESKTOPS -> _NET_NUMBER_OF_DESKTOPS for consistency. + + +_NET_WM_VISIBLE_NAME_STRING -> _NET_WM_VISIBLE_NAME for consistency. + + +_NET_WM_STATE: added explanation of permitted extensions. Added explanation of +being set / not set. + + +Spellchecked, corrected various typos. + + +UTF8 -> UTF-8 for consistency. + + +added references to the ICCCM an UTF-8 (incomplete). + + +added data and event formats where missing. + + +clarified _NET_SUPPORTING_WM_CHECK. + + +fixed formatting of _NET_CLOSE_WINDOW message. + + + + + Changes since 1.0pre1 + + +Removed implementation note concerning Gnome's (potential) file manager behaviour. + + +The Window Movement section of the implementation notes has been revised. + + + + + Changes since 1.9f + + +Revised revision number for first accepted release 1.9XX -> 1.0preXX. + + +Prerequisites for adoption of this specification added. + + +Tidied formatting of _NET_CURRENT_DESKTOP for consistency. + + +Tidied formatting of _NET_ACTIVE_WINDOW for consistency. Removed doubled text. + + +Tidied formatting of _NET_WM_DESKTOP for consistency. + + +Killing Hung Processes implementation note added. _NET_WM_PID and _NET_WM_PING now link to this. + + +Clarified x_root and y_root meaning for _NET_WM_MOVERESIZE. + + +Added contributor list. + + + + + Changes since 1.9e + + +Added _NET_WM_VISIBLE_NAME_STRING + + +Removed ambiguity from _NET_NUMBER_OF_DESKTOPS and _NET_DESKTOP_NAMES in combination. + + +Set _NET_WM_MOVERESIZE format to 32 for consistency. + + +Removed _NET_PROPERTIES. + + +Removed comment from _NET_WM_MOVERESIZE. + + + + + Changes since 1.9d + + +Added _NET_VIRTUAL_ROOTS + + +Added note about ICCCM compliant window moves. + + +Added _NET_WM_HANDLED_ICONS + + +Added _NET_SUPPORTING_WM_CHECK + + +Removed degrees of activation + + + + + Changes since 1.9c + + + +Removed packaging of hints into 2 X properties. Jim Gettys points out that the +performance gains of fewer round trips can be better achieved using Xlib +routines. + + + + +Clarified that _NET_DESKTOP_VIEWPORT is in pixels + + + + +_NET_DESKTOP_VIEWPORT is now an array, one for each desktop, to allow for +different active viewports on different desktops + + + + +_NET_WM_STRUT now only applies on desktops on which the client is visible + + + + +Introduced RFC 2119 language, and attempted to clarify the roles of the Window +Manager, Pagers and Applications + + + + +Added _NET_WM_NAME + + + + +_NET_DESKTOP_NAMES now in UTF8 + + + + +Desktops now start from 0 + + + + +Added _NET_WM_PID + + + + +Added _NET_WM_PING protocol + + + + +Added _NET_WM_STATE_SKIP_TASKBAR + + + + - Window Movement - -Window manager implementors should refer to the ICCCM for definitive -specifications of how to handle MapRequest and ConfigureRequest events. -However, since these aspects of the ICCCM are easily misread, this -document offers the following clarifications: - + Changes since 1.9b - -Window managers MUST honour the win_gravity field of WM_NORMAL_HINTS - for both MapRequest _and_ ConfigureRequest events [1] - - -Applications are free to change their win_gravity setting at any time - - -If application changes its gravity then Window manager should adjust the -reference point, so that client window will not move as the result. -For example if client's gravity was NorthWestGravity and reference point -was -at the top-left corner of the frame window, then after change of gravity to -the SouthEast reference point should be adjusted to point to the -lower-right -corner of the frame. - - -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] - - -XMoveWindow( w, x, y) behaviour depends on the window gravity: - - -StaticGravity: - - - window's left top corner will be placed at (x,y) - - -NorthWestGravity: - - - window frame's left top corner will be placed at (x,y) - - -NorthEastGravity: - - - window frame's right top corner will be placed at (x,y) - - - -SouthWestGravity: - - - window frame's left bottom corner will be placed at (x,y) - - - -SouthEastGravity: - - - window frame's right bottom corner will be placed at (x,y) - - - -CenterGravity: - - - window frame's center will be placed at (x,y) - - - -(x,y) will become a new "reference point" for the client window. - - -Implementation Note for Application developers: - - -When client window is resized - its reference point does not move. -So for example if window has SouthEastGravity and it is resized - -the bottom-right corner of its frame will not move but instead -top-left corner will be adjusted by the difference in size. - - -Implementation Note for WM developers : - - -when calculating reference point at the time of initial placement - -initial window's width should be taken into consideration, as if it -was the frame for this window. - + Removed _NET_NUMBER_OF_DESKTOPS client message, as it overlaps unnecessarily with _NET_{INSERT/DELETE}_DESKTOP. + + Replaced _NET_WM_LAYER and _NET_WM_HINTS with _NET_WM_WINDOW_TYPE functional hint. + Changed _NET_WM_STATE to a list of atoms, for extensibility. + Expanded description of _NET_WORKAREA and _NET_WM_STRUT. + Removed _NET_WM_SIZEMOVE_NOTIFY protocol. + Added degrees of activation to _NET_ACTIVE_WINDOW client message + Added _NET_WM_ICON + My comments are in [[ ]]. Comments from Marko's draft are in [[MM: ]] - -[1] ICCCM Version 2.0, 4.1.2.3 and 4.1.5 - - -[2] ICCCM Version 2.0, 4.2.3 - - - - Window-in-Window MDI - - The authors of this specification acknowledge that there is no standard method to allow the Window Manager to manage windows that a part of a Window-in-Window MDI application. Application authors are advised to use some other form of MDI, or to propose a mechanism to be included in the next revision of this specification. - - - - Killing Hung Processes - -If processes fail to respond to the _NET_WM_PING protocol _NET_WM_PID may be used in combination with the ICCCM specified WM_CLIENT_MACHINE(STRING) to attempt to kill a process. - - - - - References - [1] UTF-8 - -[2] David Rosenthal / Stuart W. Marks "Inter-Client Communication Conventions - Manual (Version 2.0)", X Consortium Standard, X Version 11, Release 6.3 - - - - Contributors - - Sasha Vasko - Bradley T. Hughes - Dominik Vogt - Havoc Pennington - Jeff Raven - Jim Gettys - John Harper - Julian Adams - Matthias Ettrich - Micheal Rogers - Nathan Clemons - Tim Janik - Tomi Ollila - Sam Lantinga - The Rasterman - Paul Warren - Owen Taylor - Marko Macek - Greg Badros - Matthias Clasen - - - + + -- cgit v1.2.3-70-g09d2