table of contents
XScreenSaver(3) | Library Functions Manual | XScreenSaver(3) |
NAME¶
XScreenSaver - X11 Screen Saver extension client librarySYNOPSIS¶
#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.
- 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.
- 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.
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.SEE ALSO¶
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.libXScrnSaver 1.2.2 | X Version 11 |