Jump to contentJump to page navigation: previous page [access key p]/next page [access key n]

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: This property is 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) thereby allowing 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 it as it wishes. 0xFFFFFFFF indicates that the window SHOULD appear on all desktops.

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
  data.l[1] = source indication
  other data.l[] elements = 0

See Section 7.11, “Source indication in requests” for details on the source indication. 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 behavior 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 behavior for Window Managers that do not recognize the extensions.

Rationale: This hint is intended 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 behavior to windows of the same type. Possible examples of behavior 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 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.

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 state.

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_ABOVE, ATOM
_NET_WM_STATE_BELOW, ATOM
_NET_WM_STATE_DEMANDS_ATTENTION, 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. If the WM_TRANSIENT_FOR hint is set to another toplevel window, the dialog is modal for that window; if WM_TRANSIENT_FOR is not set or set to the root window the dialog is 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} maximized.

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

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.

_NET_WM_STATE_FULLSCREEN indicates that the window should fill the entire screen and have no window decorations. Additionally the Window Manager is responsible for restoring the original geometry after a switch from fullscreen back to normal window. For example, a presentation program would use this hint.

_NET_WM_STATE_ABOVE indicates that the window should be on top of most windows (see Section 7.10, “Stacking order” for details).

_NET_WM_STATE_BELOW indicates that the window should be below most windows (see Section 7.10, “Stacking order” for details).

_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 Section 7.4, “Urgency”).'

_NET_WM_STATE_DEMANDS_ATTENTION indicates that some action in or with the window happened. For example, it may be set by the Window Manager if the window requested activation but the Window Manager refused it, or the application may set it if it finished some work. This state may be set by both the Client and the Window Manager. It should be unset by the Window Manager when it decides the window got the required attention (usually, that it got activated).

To change the state of a mapped window, a Client MUST send a _NET_WM_STATE client message to the root window:

  window  = the respective client window
  message_type = _NET_WM_STATE
  format = 32
  data.l[0] = the action, as listed below
  data.l[1] = first property to alter
  data.l[2] = second property to alter
  data.l[3] = source indication
  other data.l[] elements = 0

This message allows two properties to be changed simultaneously, specifically to allow both horizontal and vertical maximization to be altered together. l[2] MUST be set to zero if only one property is to be changed. See Section 7.11, “Source indication in requests” for details on the source indication. 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_MINIMIZE, 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

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.

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_MINIMIZE indicates that the window may be iconified.

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

_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 is equivalent to a _NET_WM_STRUT_PARTIAL property where all start values are 0 and all end values are the height or width of the logical screen. _NET_WM_STRUT_PARTIAL was introduced later than _NET_WM_STRUT, however, so clients MAY set this property in addition to _NET_WM_STRUT_PARTIAL to ensure backward compatibility with Window Managers supporting older versions of the Specification.

5.10 _NET_WM_STRUT_PARTIAL

_NET_WM_STRUT_PARTIAL, left, right, top, bottom, left_start_y, left_end_y,
right_start_y, right_end_y, top_start_x, top_end_x, bottom_start_x,
bottom_end_x,CARDINAL[12]/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 4 cardinals specifying the width of the reserved area at each border of the screen, and an additional 8 cardinals specifying the beginning and end corresponding to each of the four struts. The order of the values is left, right, top, bottom, left_start_y, left_end_y, right_start_y, right_end_y, top_start_x, top_end_x, bottom_start_x, bottom_end_x. All coordinates are root window coordinates. The client MAY change this property at any time, therefore the Window Manager MUST watch for property notify events if the Window Manager uses this property to assign special semantics to the window.

If both this property and the _NET_WM_STRUT property are set, the Window Manager MUST ignore the _NET_WM_STRUT property values and use instead the values for _NET_WM_STRUT_PARTIAL. This will ensure that Clients can safely set both properties without giving up the improved semantics of the new property.

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 take this reserved area into account when constraining window positions - maximized windows, for example, should not cover that area.

The start and end values associated with each strut allow areas to be reserved which do not span the entire width or height of the screen. Struts MUST be specified in root window coordinates, that is, they are not relative to the edges of any view port or Xinerama monitor.

For example, for a panel-style Client appearing at the bottom of the screen, 50 pixels tall, and occupying the space from 200-600 pixels from the left of the screen edge would set a bottom strut of 50, and set bottom_start_x to 200 and bottom_end_x to 600. Another example is a panel on a screen using the Xinerama extension. Assume that the set up uses two monitors, one running at 1280x1024 and the other to the right running at 1024x768, with the top edge of the two physical displays aligned. If the panel wants to fill the entire bottom edge of the smaller display with a panel 50 pixels tall, it should set a bottom strut of 306, with bottom_start_x of 1280, and bottom_end_x of 2303. Note that the strut is relative to the screen edge, and not the edge of the xinerama monitor.

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.11 _NET_WM_ICON_GEOMETRY

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

This optional property MAY be set by stand alone 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.12 _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. The first two cardinals are width, height. Data is in rows, left to right and top to bottom.

5.13 _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.14 _NET_WM_HANDLED_ICONS

_NET_WM_HANDLED_ICONS

This property can be set by a Pager on one of its own toplevel windows to indicate that the Window Manager need not provide icons for iconified windows, for example if it is a taskbar and provides buttons for iconified windows.

5.15 _NET_WM_USER_TIME

_NET_WM_USER_TIME CARDINAL/32

This property contains the XServer time at which last user activity in this window took place.

Clients should set this property on every new toplevel window, before mapping the window, to the timestamp of the user interaction that caused the window to appear. A client that only deals with core events, might, for example, use the timestamp of the last KeyPress or ButtonPress event. ButtonRelease and KeyRelease events should not generally be considered to be user interaction, because an application may receive KeyRelease events from global keybindings, and generally release events may have later timestamp than actions that were triggered by the matching press events. Clients can obtain the timestamp that caused its first window to appear from the DESKTOP_STARTUP_ID environment variable, if the app was launched with startup notification. If the client does not know the timestamp of the user interaction that caused the first window to appear (e.g. because it was not launched with startup notification), then it should not set the property for that window. The special value of zero on a newly mapped window can be used to request that the window not be initially focused when it is mapped.

If the client has the active window, it should also update this property on the window whenever there's user activity.

Rationale: This property allows a Window Manager to alter the focus, stacking, and/or placement behavior of windows when they are mapped depending on whether the new window was created by a user action or is a "pop-up" window activated by a timer or some other event.

5.16 _NET_FRAME_EXTENTS

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

The Window Manager MUST set _NET_FRAME_EXTENTS to the extents of the window's frame. left, right, top and bottom are widths of the respective borders added by the Window Manager.