
Prev		Next

5. Application Window Properties

5.1. _NET_WM_NAME

_NET_WM_NAME, UTF8_STRING

The Client SHOULD set this to the title of the window in UTF-8 encoding. If +set, the Window Manager should use this in preference to WM_NAME. +

5.2. _NET_WM_VISIBLE_NAME

_NET_WM_VISIBLE_NAME, UTF8_STRING

If the Window Manager displays a window name other than _NET_WM_NAME the Window Manager MUST set this to the title displayed in UTF-8 encoding. +

Rationale: For window managers that display a title different from the _NET_WM_NAME or WM_NAME of the window (i.e. xterm <1>, xterm <2>, ... is shown, but _NET_WM_NAME / WM_NAME is still xterm for each window). This property allows taskbars / pagers to display the same title as the window manager. +

5.3. _NET_WM_ICON_NAME

_NET_WM_ICON_NAME, UTF8_STRING

The Client SHOULD set this to the title of the icon for this window in UTF-8 +encoding. If set, the Window Manager should use this in preference to +WM_ICON_NAME. +

5.4. _NET_WM_VISIBLE_ICON_NAME

_NET_WM_VISIBLE_ICON_NAME, UTF8_STRING

If the Window Manager displays an icon name other than _NET_WM_ICON_NAME +the Window Manager MUST set this to the title displayed in UTF-8 encoding. +

5.5. _NET_WM_DESKTOP

_NET_WM_DESKTOP desktop, CARDINAL/32

Cardinal to determine the desktop the window is in (or wants to be) starting +with 0 for the first desktop. A Client MAY choose not to set this property, +in which case the Window Manager SHOULD place as it wishes. 0xFFFFFFFF +indicates that the window SHOULD appear on all desktops/workspaces. +

The Window Manager should honor _NET_WM_DESKTOP whenever a withdrawn window +requests to be mapped. +

The Window Manager should remove the property whenever +a window is withdrawn, but it should leave the property in place when it is +shutting down, e.g. in response to losing ownership of the WM_Sn manager +selection. +

Rationale: Removing the property upon window withdrawal helps legacy +applications which want to reuse withdrawn windows. Not removing the property +upon shutdown allows the next Window Manager to restore windows to their +previous desktops. +

A Client can request a change of desktop for a non-withdrawn window by sending +a _NET_WM_DESKTOP client message to the root window: +

_NET_WM_DESKTOP
+  window  = the respective client window
+  message_type = _NET_WM_DESKTOP
+  format = 32
+  data.l[0] = new_desktop

The Window Manager MUST keep this property updated on all windows. +

5.6. _NET_WM_WINDOW_TYPE

_NET_WM_WINDOW_TYPE, ATOM[]/32

This SHOULD be set by the Client before mapping, to a list of atoms indicating +the functional type of the window. This property SHOULD be used by the window +manager in determining the decoration, stacking position and other behaviour +of the window. The Client SHOULD specify window types in order of preference +(the first being most preferable), but MUST include at least one of the basic +window type atoms from the list below. This is to allow for extension of the +list of types, whilst providing default behaviour for window managers that do +not recognise the extensions. +

Rationale: This hint is intend to replace the MOTIF hints. One of the +objections to the MOTIF hints is that they are a purely visual description of +the window decoration. By describing the function of the window, the window +manager can apply consistent decoration and behaviour to windows of the same +type. Possible examples of behaviour include keeping dock/panels on top or +allowing pinnable menus / toolbars to only be hidden when another window has +focus (NextStep style). +

_NET_WM_WINDOW_TYPE_DESKTOP, ATOM
+_NET_WM_WINDOW_TYPE_DOCK, ATOM
+_NET_WM_WINDOW_TYPE_TOOLBAR, ATOM
+_NET_WM_WINDOW_TYPE_MENU, ATOM
+_NET_WM_WINDOW_TYPE_UTILITY, ATOM
+_NET_WM_WINDOW_TYPE_SPLASH, ATOM
+_NET_WM_WINDOW_TYPE_DIALOG, ATOM
+_NET_WM_WINDOW_TYPE_NORMAL, ATOM

_NET_WM_WINDOW_TYPE_DESKTOP indicates a desktop feature. This can include a +single window containing desktop icons with the same dimensions as the screen, +allowing the desktop environment to have full control of the desktop, without +the need for proxying root window clicks. +

_NET_WM_WINDOW_TYPE_DOCK indicates a dock or panel feature. Typically a +window manager would keep such windows on top of all other windows. +

_NET_WM_WINDOW_TYPE_TOOLBAR and _NET_WM_WINDOW_TYPE_MENU indicate toolbar and +pinnable menu windows, respectively (i.e. toolbars and menus "torn off" from +the main application). Windows of this type may set the WM_TRANSIENT_FOR +hint indicating the main application window. +

_NET_WM_WINDOW_TYPE_UTILITY indicates a small persistent utility window, such as +a palette or toolbox. It is distinct from type TOOLBAR because it does not +correspond to a toolbar torn off from the main application. It's distinct from +type DIALOG because it isn't a transient dialog, the user will probably keep it +open while they're working. Windows of this type may set the WM_TRANSIENT_FOR +hint indicating the main application window. +

_NET_WM_WINDOW_TYPE_SPLASH indicates that the window is a splash screen +displayed as an application is starting up. +

_NET_WM_WINDOW_TYPE_DIALOG indicates that this is a dialog window. If +_NET_WM_WINDOW_TYPE is not set, then windows with WM_TRANSIENT_FOR set MUST +be taken as this type. +

_NET_WM_WINDOW_TYPE_NORMAL indicates that this is a normal, top-level window. +Windows with neither _NET_WM_WINDOW_TYPE nor WM_TRANSIENT_FOR are set MUST +be taken as this type. +

5.7. _NET_WM_STATE

_NET_WM_STATE, ATOM[]

A list of hints describing the window state. Atoms present in the list MUST be +considered set, atoms not present in the list MUST be considered not set. The +Window Manager SHOULD honor +_NET_WM_STATE whenever a withdrawn window requests to be mapped. A Client +wishing to change the state of a window MUST send a _NET_WM_STATE client +message to the root window (see below). The Window Manager MUST keep this +property updated to reflect the current state of the window. +

Possible atoms are: +

_NET_WM_STATE_MODAL, ATOM
+_NET_WM_STATE_STICKY, ATOM
+_NET_WM_STATE_MAXIMIZED_VERT, ATOM
+_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
+_NET_WM_STATE_FLOATING, ATOM

An implementation MAY add new atoms to this list. Implementations +without extensions MUST ignore any unknown atoms, effectively removing +them from the list. These extension atoms MUST NOT start with the prefix +_NET. +

_NET_WM_STATE_MODAL indicates that this is a modal dialog box. The +WM_TRANSIENT_FOR hint MUST be set to indicate which window the dialog is a +modal for, or set to the root window if the dialog is a modal for its window +group. +

_NET_WM_STATE_STICKY indicates that the Window Manager SHOULD keep the +window's position fixed on the screen, even when the virtual desktop scrolls. +

_NET_WM_STATE_MAXIMIZED_{VERT,HORZ} indicates that the window is +{vertically,horizontally} maximised. +

_NET_WM_STATE_SHADED indicates that the window is shaded. +

_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. +

_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. +

_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. +[1] +

_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_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. +

To change the state of a mapped window, a Client MUST send a _NET_WM_STATE +client message to the root window (window is the respective window, type +_NET_WM_STATE, format 32, l[0]=<the action, as listed below>, +l[1]=<First property to alter>, l[2]=<Second property to alter>). +This message allows two properties to be changed simultaneously, specifically +to allow both horizontal and vertical maximisation to be altered together. +l[2] MUST be set to zero if only one property is to be changed. l[0], the +action, MUST be one of: +

_NET_WM_STATE_REMOVE        0    /* remove/unset property */
+_NET_WM_STATE_ADD           1    /* add/set property */
+_NET_WM_STATE_TOGGLE        2    /* toggle property  */

See also the implementation notes on urgency and fixed size windows. +

5.8. _NET_WM_ALLOWED_ACTIONS

_NET_WM_ALLOWED_ACTIONS, ATOM[]

A list of atoms indicating user operations that the window manager supports for +this window. Atoms present in the list indicate allowed actions, atoms not +present in the list indicate actions that are not supported for this window. +The window manager MUST keep this property updated to reflect the +actions which are currently "active" or "sensitive" for a window. +Taskbars, Pagers, and other tools use _NET_WM_ALLOWED_ACTIONS to +decide which actions should be made available to the user. +

Possible atoms are: +

_NET_WM_ACTION_MOVE, ATOM
+_NET_WM_ACTION_RESIZE, ATOM
+_NET_WM_ACTION_SHADE, ATOM
+_NET_WM_ACTION_STICK, ATOM
+_NET_WM_ACTION_MAXIMIZE_HORZ, ATOM
+_NET_WM_ACTION_MAXIMIZE_VERT, ATOM
+_NET_WM_ACTION_FULLSCREEN, ATOM
+_NET_WM_ACTION_CHANGE_DESKTOP, ATOM
+_NET_WM_ACTION_CLOSE, ATOM

Note that the actions listed here are those that the Window +Manager will honor for this window. The operations must still be +requested through the normal mechanisms outlined in this specification. For +example, _NET_WM_ACTION_CLOSE does not mean that clients can send a +WM_DELETE_WINDOW message to this window; it means that clients can use a +_NET_CLOSE_WINDOW message to ask the Window Manager to do so. +

Window Managers SHOULD ignore the value of _NET_WM_ALLOWED_ACTIONS when they +initially manage a window. This value may be left over from a previous window +manager with different policies. +

_NET_WM_ACTION_MOVE indicates that the window may be moved around the screen. +

_NET_WM_ACTION_RESIZE indicates that the window may be resized. +(Implementation note: window managers can identify a non-resizable +window because its minimum and maximum size in WM_NORMAL_HINTS will be the same.) +

_NET_WM_ACTION_SHADE indicates that the window may be shaded. +

_NET_WM_ACTION_STICK indicates that the window may have its sticky state +toggled (as for _NET_WM_STATE_STICKY). Note that this state has to do with +viewports, not desktops. +

_NET_WM_ACTION_MAXIMIZE_HORZ indicates that the window may be maximized horizontally. +

_NET_WM_ACTION_MAXIMIZE_VERT indicates that the window may be maximized vertically. +

_NET_WM_ACTION_FULLSCREEN indicates that the window may be brought to + fullscreen mode. +

_NET_WM_ACTION_CHANGE_DESKTOP indicates that the window may be moved between desktops. +

_NET_WM_ACTION_CLOSE indicates that the window may be closed (i.e. a WM_DELETE_WINDOW +message may be sent). +

5.9. _NET_WM_STRUT

_NET_WM_STRUT, left, right, top, bottom, CARDINAL[4]/32

This property MUST be set by the Client if the window is to reserve space at +the edge of the screen. The property contains a 4 cardinals specifying the +width of the reserved area at each border of the screen. +The order of the borders is left, right, top, bottom. +The client MAY change this property anytime, therefore the Window Manager MUST +watch out for property notify events. +

The purpose of struts is to reserve space at the borders of the desktop. This +is very useful for a docking area, a taskbar or a panel, for instance. The +window manager should know about this reserved space in order to be able to +preserve the space. Also maximized windows should not cover that reserved +space. +

Rationale: A simple "do not cover" hint is not enough for dealing with e.g. +auto-hide panels. +

Notes: An auto-hide panel SHOULD set the strut to be its minimum, hidden size. +A "corner" panel that does not extend for the full length of a screen border +SHOULD only set one strut. +

5.10. _NET_WM_ICON_GEOMETRY

_NET_WM_ICON_GEOMETRY, x, y, width, height, CARDINAL[4]/32

This optional property MAY be set by standalone tools like a taskbar or an +iconbox. It specifies the geometry of a possible icon in case the window is iconified. +

Rationale: This makes it possible for a window manager to display a nice +animation like morphing the window into its icon. +

5.11. _NET_WM_ICON

_NET_WM_ICON CARDINAL[][2+n]/32

This is an array of possible icons for the client. This specification does +not stipulate what size these icons should be, but individual desktop +environments or toolkits may do so. The Window Manager MAY scale any of these +icons to an appropriate size. +

This is an array of 32bit packed CARDINAL ARGB with high byte being A, low +byte being B. First two cardinals are width, height. Data is in rows, left to +right and top to bottom. +

5.12. _NET_WM_PID

_NET_WM_PID CARDINAL/32

If set, this property MUST contain the process ID of the client owning this +window. This MAY be used by the Window Manager to kill windows which do not +respond to the _NET_WM_PING protocol. +

If _NET_WM_PID is set, the ICCCM-specified property WM_CLIENT_MACHINE +MUST also be set. While the ICCCM only requests that WM_CLIENT_MACHINE is set +" to a string that forms the name of the machine running the client as +seen from the machine running the server" conformance to this +specification requires that WM_CLIENT_MACHINE be set to the fully-qualified domain +name of the client's host. +

See also the implementation notes on killing hung processes. +

5.13. _NET_WM_HANDLED_ICONS

_NET_WM_HANDLED_ICONS

This property can be set by clients to indicate that the Window Manager need +not provide icons for iconified windows, for example if the client is a taskbar +and provides buttons for iconified windows. +

Prev	Home	Next
Other Root Window Messages		Window Manager Protocols