SYNOPSIS
#include <X11/extension/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 event_mask; /* 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_basep, int
*error_basep);
Status XScreenSaverQueryVersion(Display *dpy, int *major_versionp, int
*minor_versionp);
XScreenSaverInfo *XScreenSaverAllocInfo(void);
Status XScreenSaverQueryInfo(Display *dpy, Drawable drawable, XScreen-
SaverInfo *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,
have asked for the mechanism to allow them to write screen saver pro-
grams that provide capabilities similar to those provided by other win-
dow systems. In particular, such users often wish to be able to dis-
play 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 manipula-
tion by the window manager. Furthermore, the X identifier for the win-
dow 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 XScreenSaver-
QueryExtension 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_versionp and minor_versionp .
XScreenSaverAllocInfo allocates and returns an XScreenSaverInfo struc-
ture for use in calls to XScreenSaverQueryInfo. All fields in the
structure are initialized to zero. If insufficient memory is avail-
able, 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 acti-
vate.
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.
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; there-
fore, the effect of changing the contents of those resources is unde-
fined. 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.
ous screen saver window attributes set by this client.
XScreenSaverRegister stores the given XID in the _SCREEN_SAVER_ID prop-
erty (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 win-
dow of the specified screen. It returns zero if an error is encoun-
tered 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.
ERRORS
XScreenSaverSelectInput, XScreenSaverQueryInfo, XScreenSaverSetAt-
tributes 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 XScreenSa-
verSelectInput .
SEE ALSO
Xlib(1), X(7)
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.
XFree86 Version 4.4.0 XScreenSaver(3)
Man(1) output converted with
man2html
|