Ubuntu Manpage: XScreenSaver - X11 Screen Saver extension client library

NAME

       XScreenSaver - X11 Screen Saver extension client library

SYNOPSIS

       #include <X11/extensions/scrnsaver.h>

       typedef struct {
           Window window;                /∗ screen saver window */
           int state;                    /∗ ScreenSaver{Off,On,Disabled} */
           int kind;                     /∗ ScreenSaver{Blanked,Internal,External} */
           unsigned long til_or_since;   /∗ milliseconds */
           unsigned long idle;           /∗ milliseconds */
           unsigned long eventMask;      /∗ events */
       } XScreenSaverInfo;

       typedef struct {
           int type;               /∗ of event */
           unsigned long serial;   /∗ # of last request processed by server */
           Bool send_event;        /∗ true if this came frome a SendEvent request */
           Display *display;       /∗ Display the event was read from */
           Window window;          /∗ screen saver window */
           Window root;            /∗ root window of event screen */
           int state;              /∗ ScreenSaver{Off,On,Cycle} */
           int kind;               /∗ ScreenSaver{Blanked,Internal,External} */
           Bool forced;            /∗ extents of new region */
           Time time;              /∗ event timestamp */
       } XScreenSaverNotifyEvent;

       Bool     XScreenSaverQueryExtension(Display     *dpy,    int    *event_base_return,    int
              *error_base_return);

       Status   XScreenSaverQueryVersion(Display    *dpy,    int    *major_version_return,    int
              *minor_version_return);

       XScreenSaverInfo *XScreenSaverAllocInfo(void);

       Status    XScreenSaverQueryInfo(Display    *dpy,   Drawable   drawable,   XScreenSaverInfo
              *saver_info);

       void XScreenSaverSelectInput(Display *dpy, Drawable drawable, unsigned long mask);

       void XScreenSaverSetAttributes(Display *dpy, Drawable drawable, int x, int y, unsigned int
              width,  unsigned  int  height,  unsigned  int border_width, int depth, unsigned int
              class, Visual *visual, unsigned long valuemask, XSetWindowAttributes *attributes);

       void XScreenSaverUnsetAttributes(Display *dpy, Drawable drawable);

       void XScreenSaverSaverRegister(Display *dpy, int screen, XID xid, Atom type);

       Status XScreenSaverUnregister(Display *dpy, int screen);

       Status XScreenSaverGetRegistered(Display *dpy, int screen, XID *xid, Atom *type);

       void XScreenSaverSuspend(Display *dpy, Bool suspend);

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.

AUTHORS

       Jim Fulton and Keith Packard.

STABILITY

       This API is considered as experimental.  The Xss library major revision may be incremented
       whenever incompatible changes are done to the API without notice.  Use with care.