Root Window Properties (+Related Messages)

Extended Window Manager Hints
Prev |  | Next

# 3. Root Window Properties (+Related Messages)

Whenever this spec speaks about "sending a message to the root window", it is understood that the client is supposed to create a ClientMessage event with the specified contents and send it by using a SendEvent request with the following arguments:

    destination     root
    propagate       False
    event-mask      (SubstructureNotify|SubstructureRedirect)
    event           the specified ClientMessage

## 3.1. _NET_SUPPORTED

    _NET_SUPPORTED, ATOM[]/32

This property MUST be set by the Window Manager to indicate which hints it supports. For example: considering _NET_WM_STATE both this atom and all supported states e.g. _NET_WM_STATE_MODAL, _NET_WM_STATE_STICKY, would be listed. This assumes that backwards incompatible changes will not be made to the hints (without being renamed).

## 3.2. _NET_CLIENT_LIST

    _NET_CLIENT_LIST, WINDOW[]/32
    _NET_CLIENT_LIST_STACKING, WINDOW[]/32

These arrays contain all X Windows managed by the Window Manager. _NET_CLIENT_LIST has initial mapping order, starting with the oldest window. _NET_CLIENT_LIST_STACKING has bottom-to-top stacking order. These properties SHOULD be set and updated by the Window Manager.

## 3.3. _NET_NUMBER_OF_DESKTOPS

    _NET_NUMBER_OF_DESKTOPS, CARDINAL/32

This property SHOULD be set and updated by the Window Manager to indicate the number of virtual desktops.

A Pager can request change in the desktops number by sending a _NET_NUMBER_OF_DESKTOPS message to the root window:

    _NET_NUMBER_OF_DESKTOPS
      message_type = _NET_NUMBER_OF_DESKTOPS
      format = 32
      data.l[0] = new_number_of_desktops

The Window Manager is free to honor or reject this request. If request is honored _NET_NUMBER_OF_DESKTOPS MUST be set to the new number of desktops, _NET_VIRTUAL_ROOTS MUST be set to store the new number of desktop virtual root window IDs and _NET_DESKTOP_VIEWPORT and _NET_WORKAREA must also be changed accordingly. The _NET_DESKTOP_NAMES property MAY remain unchanged.

If the number of desktops is shrinking and _NET_CURRENT_DESKTOP is out of the new range of available desktops, then this MUST be set to the last available desktop from the new set. If number of desktops is shrinking then clients that are still present on desktops, that are out of the new range, MUST be moved to the very last desktop from the new set. For these _NET_WM_DESKTOP MUST be updated.

## 3.4. _NET_DESKTOP_GEOMETRY

    _NET_DESKTOP_GEOMETRY width, height, CARDINAL[2]/32

Array of two cardinals that defines the common size of all desktops. This property SHOULD be set by the Window Manager.

A Pager can request a change in the desktop geometry by sending a _NET_DESKTOP_GEOMETRY client message to the root window:

    _NET_DESKTOP_GEOMETRY
      message_type = _NET_DESKTOP_GEOMETRY
      format = 32
      data.l[0] = new_width
      data.l[1] = new_height

The Window Manager MAY choose to ignore this message, in which case _NET_DESKTOP_GEOMETRY property will remain unchanged.

## 3.5. _NET_DESKTOP_VIEWPORT

    _NET_DESKTOP_VIEWPORT x, y, CARDINAL[][2]/32

Array of pairs of cardinals that define the top left corner of each desktops viewport. For window managers that don't support large desktops, this MUST always be set to (0,0).

A Pager can request to change the viewport for the current desktop by sending a _NET_DESKTOP_VIEWPORT client message to the root window:

    _NET_DESKTOP_VIEWPORT
      message_type = _NET_DESKTOP_VIEWPORT
      format = 32
      data.l[0] = new_vx
      data.l[1] = new_vy

The Window Manager MAY choose to ignore this message, in which case _NET_DESKTOP_VIEWPORT property will remain unchanged.

## 3.6. _NET_CURRENT_DESKTOP

    _NET_CURRENT_DESKTOP desktop, CARDINAL/32

The index of the current desktop. This is always an integer between 0 and _NET_NUMBER_OF_DESKTOPS - 1. This MUST be set and updated by the Window Manager If a Pager wants to switch to another virtual desktop, it MUST send a _NET_CURRENT_DESKTOP client message to the root window:

    _NET_CURRENT_DESKTOP
      message_type = _NET_CURRENT_DESKTOP
      format = 32
      data.l[0] = new_index

## 3.7. _NET_DESKTOP_NAMES

    _NET_DESKTOP_NAMES, UTF-8_STRING[]

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.

Note: The number of names could be different from _NET_NUMBER_OF_DESKTOPS. If it is less than _NET_NUMBER_OF_DESKTOPS - then the desktops with high numbers are unnamed. If it is larger than _NET_NUMBER_OF_DESKTOPS, then the excess names outside of the _NET_NUMBER_OF_DESKTOPS are considered to be reserved in case number of desktops is increased.

Rationale: The name is not a necessary attribute of a virtual desktop. Thus the availability or unavailability of names has no impact on virtual desktop functionality. Since names are set by users and users are likely to preset names for a fixed number of desktops, it doesn't make sense to shrink or grow this list when the number of available desktops changes.

## 3.8. _NET_ACTIVE_WINDOW

    _NET_ACTIVE_WINDOW, WINDOW/32

The window ID of the currently active window or None if no window has the focus. This is a read-only property set by the window manager. If a client (for example, a taskbar) wants to activate another window, it MUST send a _NET_ACTIVE_WINDOW client message to the root window:

    _NET_ACTIVE_WINDOW
      window  = window to activate
      message_type = _NET_ACTIVE_WINDOW
      format = 32
      data.l[0] = 0 /* may be used later */

## 3.9. _NET_WORKAREA

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

This property MUST be set by WM upon calculating the work area for each desktop. Contains a geometry for each desktop. These geometries are specified relative to the viewport on each desktop and specify an area that is completely contained within the viewport. Work area SHOULD be used by desktop applications to place desktop icons appropriately.

The window manager SHOULD calculate this space by taking the current page minus space occupied by dock and panel windows, as indicated by the _NET_WM_STRUT property set on client windows.

## 3.10. _NET_SUPPORTING_WM_CHECK

    _NET_SUPPORTING_WM_CHECK, WINDOW/32

The Window Manager MUST set this property on the root window to be the ID of a child window created by the WM, to indicate that a compliant WM is active. The child window MUST also have the _NET_SUPPORTING_WM_CHECK property set to the ID of the child window. The child window MUST also have the _NET_WM_NAME property set to the name of the Window Manager.

Rationale: The child window is used to distinguish an active window manager from a stale _NET_SUPPORTING_WM_CHECK property that happens to point to another window. If the _NET_SUPPORTING_WM_CHECK window on the client window is missing or not properly set, clients SHOULD assume that no conforming window manager is present.

## 3.11. _NET_VIRTUAL_ROOTS

    _NET_VIRTUAL_ROOTS, WINDOW[]/32

To implement virtual desktops, some window managers reparent client windows to a child of the root window. Window managers using this technique MUST set this property to a list of IDs for windows that are acting as virtual root windows. This property allows background setting programs to work with virtual roots and allows clients to figure out the WM frame windows of their windows.

Prev | Home | Next
Non-ICCCM features |  | Other Root Window Messages