DESCRIPTION

The X Window
System provides support for changing the image on a display
screen after a user-settable period of inactivity to avoid
burning the cathode ray tube phosphors. However, no
interfaces are provided for the user to control the image
that is drawn. This extension allows an external
‘‘screen saver’’ client to detect
when the alternate image is to be displayed and to provide
the graphics.

Current X
server implementations typically provide at least one form
of ‘‘screen saver’’ image.
Historically, this has been a copy of the X logo drawn
against the root background pattern. However, many users
have asked for the mechanism to allow them to write screen
saver programs that provide capabilities similar to those
provided by other window systems. In particular, such users
often wish to be able to display corporate logos,
instructions on how to reactivate the screen, and automatic
screen-locking utilities. This extension provides a means
for writing such clients.

Assumptions
This extension exports the notion of a special screen saver
window that is mapped above all other windows on a display.
This window has the override-redirect attribute set
so that it is not subject to manipulation by the window
manager. Furthermore, the X identifier for the window is
never returned by QueryTree requests on the root
window, so it is typically not visible to other clients.

XScreenSaverQueryExtension
returns True if the XScreenSaver extension is
available on the given display. A client must call
XScreenSaverQueryExtension before calling any other
XScreenSaver function in order to negotiate a compatible
protocol version; otherwise the client will get undefined
behavior (XScreenSaver may or may not work).

If the
extension is supported, the event number for
ScreenSaverNotify events is returned in the value
pointed to by event_base. Since no additional errors
are defined by this extension, the results of
error_base are not defined.

XScreenSaverQueryVersion
returns True if the request succeeded; the values of
the major and minor protocol versions supported by the
server are returned in major_version_return and
minor_version_return .

XScreenSaverAllocInfo
allocates and returns an XScreenSaverInfo structure
for use in calls to XScreenSaverQueryInfo. All fields
in the structure are initialized to zero. If insufficient
memory is available, NULL is returned. The results of this
routine can be released using XFree.

XScreenSaverQueryInfo
returns information about the current state of the screen
server in saver_info and a non-zero value is
returned. If the extension is not supported,
saver_info is not changed and 0 is returned.

The
state field specifies whether or not the screen saver
is currently active and how the til-or-since value
should be interpreted:

Off

The screen is not currently being saved;
til-or-since specifies the number of milliseconds
until the screen saver is expected to activate.

On

The screen is currently being saved; til-or-since
specifies the number of milliseconds since the screen saver
activated.

Disabled

The screen saver is currently
disabled; til-or-since is zero.

The kind
field specifies the mechanism that either is currently being
used or would have been were the screen being saved:
Blanked

The video signal to the display
monitor was disabled.

Internal

A server-dependent, built-in
screen saver image was displayed; either no client had set
the screen saver window attributes or a different client had
the server grabbed when the screen saver activated.

External

The screen saver window was
mapped with attributes set by a client using the
ScreenSaverSetAttributes request.

The idle
field specifies the number of milliseconds since the last
input was received from the user on any of the input
devices.
The event-mask field specifies which, if any, screen
saver events this client has requested using
ScreenSaverSelectInput.

XScreenSaverSelectInput
asks that events related to the screen saver be generated
for this client. If no bits are set in event-mask,
then no events will be generated. Otherwise, any combination
of the following bits may be set:
ScreenSaverNotify

If this bit is set,
ScreenSaverNotify events are generated whenever the
screen saver is activated or deactivated.

ScreenSaverCycle

If this bit is set,
ScreenSaverNotify events are generated whenever the
screen saver cycle interval passes.

XScreenSaverSetAttributes
sets the attributes to be used the next time the external
screen saver is activated. If another client currently has
the attributes set, a BadAccess error is generated and the
request is ignored.
Otherwise, the specified window attributes are checked as if
they were used in a core CreateWindow request whose
parent is the root. The override-redirect field is
ignored as it is implicitly set to True. If the window
attributes result in an error according to the rules for
CreateWindow, the request is ignored.
Otherwise, the attributes are stored and will take effect on
the next activation that occurs when the server is not
grabbed by another client. Any resources specified for the
background-pixmap or cursor attributes may be
freed immediately. The server is free to copy the
background-pixmap or cursor resources or to
use them in place; therefore, the effect of changing the
contents of those resources is undefined. If the specified
colormap no longer exists when the screen saver
activates, the parent’s colormap is used instead. If
no errors are generated by this request, any previous screen
saver window attributes set by this client are released.
When the screen saver next activates and the server is not
grabbed by another client, the screen saver window is
created, if necessary, and set to the specified attributes
and events are generated as usual. The colormap associated
with the screen saver window is installed. Finally, the
screen saver window is mapped.
The window remains mapped and at the top of the stacking
order until the screen saver is deactivated in response to
activity on any of the user input devices, a
ForceScreenSaver request with a value of Reset, or
any request that would cause the window to be unmapped.
If the screen saver activates while the server is grabbed by
another client, the internal saver mechanism is used. The
ForceScreenSaver request may be used with a value of
Active to deactivate the internal saver and activate the
external saver.
If the screen saver client’s connection to the server
is broken while the screen saver is activated and the
client’s close down mode has not been RetainPermanent
or RetainTemporary, the current screen saver is deactivated
and the internal screen saver is immediately activated.
When the screen saver deactivates, the screen saver
window’s colormap is uninstalled and the window is
unmapped (except as described below). The screen saver XID
is disassociated with the window and the server may, but is
not required to, destroy the window along with any children.
When the screen saver is being deactivated and then
immediately reactivated (such as when switching screen
savers), the server may leave the screen saver window mapped
(typically to avoid generating exposures).

XScreenSaverUnsetAttributes
instructs the server to discard any previous screen saver
window attributes set by this client.

XScreenSaverRegister
stores the given XID in the _SCREEN_SAVER_ID
property (of the given type) on the root window of
the specified screen. It returns zero if an error is
encountered and the property is not changed, otherwise it
returns non-zero.

XScreenSaverUnregister
removes any _SCREEN_SAVER_ID from the root window of
the specified screen. It returns zero if an error is
encountered and the property is changed, otherwise it
returns non-zero.

XScreenSaverGetRegistered
returns the XID and type stored in the
_SCREEN_SAVER_ID property on the root window of the
specified screen. It returns zero if an error is
encountered or if the property does not exist or is not of
the correct format; otherwise it returns non-zero.

XScreenSaverSuspend
temporarily suspends the screensaver and DPMS timer if
suspend is ’True’, and restarts the timer
if suspend is ’False’.
This function should be used by applications that
don’t want the screensaver or DPMS to become activated
while they’re for example in the process of playing a
media sequence, or are otherwise continuously presenting
visual information to the user while in a non-interactive
state. This function is not intended to be called by an
external screensaver application.
If XScreenSaverSuspend is called multiple times with
suspend set to ’True’, it must be called
an equal number of times with suspend set to
’False’ in order for the screensaver timer to be
restarted. This request has no affect if a client tries to
resume the screensaver without first having suspended it.
XScreenSaverSuspend can thus not be used by one
client to resume the screensaver if it’s been
suspended by another client.
If a client that has suspended the screensaver becomes
disconnected from the X server, the screensaver timer will
automatically be restarted, unless it’s still
suspended by another client. Suspending the screensaver
timer doesn’t prevent the screensaver from being
forceably activated with the ForceScreenSaver
request, or a DPMS mode from being set with the
DPMSForceLevel request.
XScreenSaverSuspend also doesn’t deactivate the
screensaver or DPMS if either is active at the time the
request to suspend them is received by the X server. But
once they’ve been deactivated, they won’t
automatically be activated again, until the client has
canceled the suspension.

ERRORS

XScreenSaverSelectInput,
XScreenSaverQueryInfo, XScreenSaverSetAttributes and
XScreenSaverUnsetAttributes will generate a
BadDrawable error if drawable is not a valid
drawable identifier. If any undefined bits are set in
event-mask, a BadValue error is generated by
XScreenSaverSelectInput .

AVAILABILITY

XScreenSaverSuspend
is available in version 1.1 and later versions of the X
Screen Saver Extension. Version 1.1 was first released with
X11R7.1.