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

6 Window Manager Protocols

6.1 _NET_WM_PING

This protocol allows the Window Manager to determine if the Client is still processing X events. This can be used by the Window Manager to determine if a window which fails to close after being sent WM_DELETE_WINDOW has stopped responding or has stalled for some other reason, such as waiting for user confirmation. A Client SHOULD indicate that it is willing to participate in this protocol by listing _NET_WM_PING in the WM_PROTOCOLS property of the client window.

A Window Manager can use this protocol at any time by sending a client message as follows:

type = ClientMessage
window = the respective client window
message_type = WM_PROTOCOLS
format = 32
data.l[0] = _NET_WM_PING
data.l[1] = timestamp
data.l[2] = the respective client window
other data.l[] elements = 0

A participating Client receiving this message MUST send it back to the root window immediately, by setting window = root, and calling XSendEvent with the same event mask like all other root window messages in this specification use. The Client MUST NOT alter any field in the event other than the window. This includes all 5 longs in the data.l[5] array. The Window Manager can uniquely identify the ping by the timestamp and the data.l[2] field if necessary. Note that some older clients may not preserve data.l[2] through data.l[4].

The Window Manager MAY kill the Client (using _NET_WM_PID) if it fails to respond to this protocol within a reasonable time.

See also the implementation notes on killing hung processes.

6.2 _NET_WM_SYNC_REQUEST

This protocol uses the XSync extension (see the protocol specification (http://freedesktop.org/cgi-bin/viewcvs.cgi/xorg/xc/doc/hardcopy/Xext/sync.PS.gz) and the library documentation (http://freedesktop.org/cgi-bin/viewcvs.cgi/xorg/xc/doc/hardcopy/Xext/synclib.PS.gz)) to let client and window manager synchronize the repaint of the window manager frame and the client window. A client indicates that it is willing to participate in the protocol by listing _NET_WM_SYNC_REQUEST in the WM_PROTOCOLS property of the client window and storing the XID of an XSync counter in the property _NET_WM_SYNC_REQUEST_COUNTER. The initial value of this counter is not defined by this specification.

A window manager uses this protocol by preceding a ConfigureNotify event sent to a client by a client message as follows:

type = ClientMessage
window = the respective client window
message_type = WM_PROTOCOLS
format = 32
data.l[0] = _NET_WM_SYNC_REQUEST
data.l[1] = timestamp
data.l[2] = low 32 bits of the update request number
data.l[3] = high 32 bits of the update request number
other data.l[] elements = 0

After receiving one or more such message/ConfigureNotify pairs, and having handled all repainting associated with the ConfigureNotify events, the client MUST set the _NET_WM_SYNC_REQUEST_COUNTER to the 64 bit number indicated by the data.l[2] and data.l[3] fields of the last client message received.

By using either the Alarm or the Await mechanisms of the XSync extension, the window manager can know when the client has finished handling the ConfigureNotify events. The window manager SHOULD not resize the window faster than the client can keep up.

The update request number in the client message is determined by the window manager subject to the restriction that it MUST NOT be 0. The number is generally intended to be incremented by one for each message sent. Since the initial value of the XSync counter is not defined by this specification, the window manager MAY set the value of the XSync counter at any time, and MUST do so when it first manages a new window.

6.3 _NET_WM_FULLSCREEN_MONITORS

_NET_WM_FULLSCREEN_MONITORS, CARDINAL[4]/32

A read-only list of 4 monitor indices indicating the top, bottom, left, and right edges of the window when the fullscreen state is enabled. The indices are from the set returned by the Xinerama extension.

Windows transient for the window with _NET_WM_FULLSCREEN_MONITORS set, such as those with type _NEW_WM_WINDOW_TYPE_DIALOG, are generally expected to be positioned (e.g. centered) with respect to only one of the monitors. This might be the monitor containing the mouse pointer or the monitor containing the non-full-screen window.

A Client wishing to change this list MUST send a _NET_WM_FULLSCREEN_MONITORS client message to the root window. The Window Manager MUST keep this list updated to reflect the current state of the window.

  window  = the respective client window
  message_type = _NET_WM_FULLSCREEN_MONITORS
  format = 32
  data.l[0] = the monitor whose top edge defines the top edge of the fullscreen window
  data.l[1] = the monitor whose bottom edge defines the bottom edge of the fullscreen window
  data.l[2] = the monitor whose left edge defines the left edge of the fullscreen window
  data.l[3] = the monitor whose right edge defines the right edge of the fullscreen window
  data.l[4] = source indication

See Section 9.11, “Source indication in requests” for details on the source indication.

Virtual machine software may use this hint to have a virtual operating system instance that sees multiple monitors. The application window stretches over several monitors, giving the appearance that these monitors have been taken over by the guest virtual machine.

This hint might also be used by a movie or presentation application allowing users to display the media spanned over several monitors.

In both cases, the application would have some user interface allowing users to configure which monitors the application fullscreens to. The window manager need not provide such an interface, though it could.

In the event of a change in monitor configuration, the application is responsible for re-computing the monitors on which it wants to appear. The window manager may continue using the same monitor indices as before or simply clear the list, returning to "normal" fullscreen.