MAN page from OpenSuSE libXss-devel-1.2.3-30.10.x86_64.rpm


Section: C Library Functions (3)
Updated: libXScrnSaver 1.2.3


XScreenSaver - X11 Screen Saver extension client library 


#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 XScreenSaverRegister(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);



The X Window System provides support for changing the image on adisplay screen after a user-settable period of inactivity to avoidburning the cathode ray tube phosphors.However, no interfaces are provided for the user to control the imagethat is drawn.This extension allows an external ``screen saver'' client to detectwhen the alternate image is to be displayed and to provide thegraphics.

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 theroot background pattern.However, many users have asked for the mechanism to allow them towrite screen saver programs that provide capabilities similar to thoseprovided by other window systems.In particular, such users often wish to be able to display corporatelogos, instructions on how to reactivate the screen, and automaticscreen-locking utilities.This extension provides a means for writing such clients. 


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

XScreenSaverQueryExtensionreturnsTrueif theXScreenSaverextension is available on the given display.A client must callXScreenSaverQueryExtensionbefore calling any other XScreenSaver function in orderto negotiate a compatible protocol version; otherwise the client willget undefined behavior (XScreenSaver may or may not work).

If the extension is supported, the event number forScreenSaverNotifyevents is returned in the value pointed to by event_base.Since no additional errors are defined by this extension, the resultsof error_base are not defined.

XScreenSaverQueryVersionreturnsTrueif the request succeeded; the values of the major and minor protocolversions supported by the server are returned inmajor_version_returnandminor_version_return .

XScreenSaverAllocInfoallocates and returns an XScreenSaverInfo structurefor 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.

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

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

The screen is not currently being saved; til-or-sincespecifies the number of milliseconds until the screen saver is expected toactivate.
The screen is currently being saved; til-or-since specifiesthe number of milliseconds since the screen saver activated.
The screen saver is currently disabled; til-or-since is zero.

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

The video signal to the display monitor was disabled.
A server-dependent, built-in screen saver image was displayed; either noclient had set the screen saver window attributes or a different clienthad the server grabbed when the screen saver activated.
The screen saver window was mapped with attributes set by aclient using the ScreenSaverSetAttributes request.

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

XScreenSaverSelectInputasks that events related tothe screen saver be generated for this client.Ifno bits are set in event-mask, then no events will be generated.Otherwise, any combination of the following bits may be set:

If this bit is set, ScreenSaverNotify events are generated wheneverthe screen saver is activated or deactivated.
If this bit is set, ScreenSaverNotify events are generated wheneverthe screen saver cycle interval passes.

XScreenSaverSetAttributessets the attributes to be usedthe 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 ifthey were used in a core CreateWindow request whoseparent is the root.The override-redirect field is ignored as it is implicitly setto True.If the window attributes result in an error according to the rules forCreateWindow, the request is ignored.
Otherwise, the attributes are stored and will take effect on the nextactivation that occurs when the server is not grabbed by another client.Any resources specified for thebackground-pixmap or cursor attributes may befreed immediately.The server is free to copy the background-pixmap or cursorresources or to use them in place; therefore, the effect of changingthe contents of those resources is undefined.If the specified colormap no longer exists when the screen saveractivates, the parent's colormap is used instead.If no errors are generated by this request, any previous screen saverwindow attributes set by this client are released.
When the screen saver next activates and the server is not grabbed byanother client, the screen saver window iscreated, if necessary, and set to the specified attributes and eventsare 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 orderuntil the screen saver is deactivated in response to activity onany of the user input devices, a ForceScreenSaver request witha value of Reset, or any request that would cause the window to beunmapped.
If the screen saver activates while the server is grabbed by anotherclient, the internal saver mechanism is used.The ForceScreenSaver request may be used with a value of Activeto deactivate the internal saver and activate the external saver.
If the screen saver client's connection to the server is brokenwhile the screen saver is activated and the client's close down mode has notbeen RetainPermanent or RetainTemporary, the current screen saveris deactivated and the internal screen saver is immediately activated.
When the screen saver deactivates, the screen saver window's colormapis uninstalled and the window is unmapped (except as described below).The screen saver XID is disassociatedwith 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 immediatelyreactivated (such as when switching screen savers), the servermay leave the screen saver window mapped (typically to avoidgenerating exposures).

XScreenSaverUnsetAttributesinstructs the server to discardany previous screen saver window attributes set by this client.

XScreenSaverRegisterstores the given XID in the _SCREEN_SAVER_IDproperty (of the given type) on theroot window of the specified screen.It returns zero if an error is encountered and the property is notchanged, otherwise it returns non-zero.

XScreenSaverUnregisterremoves any _SCREEN_SAVER_ID from theroot window of the specified screen.It returns zero if an error is encountered and the property ischanged, otherwise it returns non-zero.

XScreenSaverGetRegisteredreturns the XID and type stored inthe _SCREEN_SAVER_ID property on theroot window of the specified screen.It returns zero if an error is encountered or if the property does notexist or is not of the correct format; otherwise it returns non-zero.

XScreenSaverSuspendtemporarily suspends the screensaver and DPMS timer if suspendis 'True', and restarts the timer if suspend is 'False'.
This function should be used by applications that don't want thescreensaver or DPMS to become activated while they're for example inthe process of playing a media sequence, or are otherwise continuouslypresenting visual information to the user while in a non-interactivestate. This function is not intended to be called by an externalscreensaver application.
If XScreenSaverSuspend is called multiple times with suspendset to 'True', it must be called an equal number of times withsuspend set to 'False' in order for the screensaver timer to berestarted. This request has no affect if a client tries to resume thescreensaver without first having suspended it.XScreenSaverSuspend can thus not be used by one client to resumethe screensaver if it's been suspended by another client.
If a client that has suspended the screensaver becomes disconnected fromthe X server, the screensaver timer will automatically be restarted, unlessit's still suspended by another client. Suspending the screensaver timerdoesn't prevent the screensaver from being forceably activated with theForceScreenSaver request, or a DPMS mode from being set with theDPMSForceLevel request.
XScreenSaverSuspend also doesn't deactivate the screensaver or DPMSif either is active at the time the request to suspend them is received bythe X server. But once they've been deactivated, they won't automaticallybe activated again, until the client has canceled the suspension. 


XScreenSaverSelectInput,XScreenSaverQueryInfo,XScreenSaverSetAttributesandXScreenSaverUnsetAttributeswill generate aBadDrawableerror if drawable is not a valid drawable identifier.If any undefined bits are set in event-mask,a BadValue error is generated byXScreenSaverSelectInput .



XScreenSaverSuspend is available in version 1.1 and later versionsof the X Screen Saver Extension. Version 1.1 was first released withX11R7.1.





Jim Fulton and Keith Packard. 


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




This document was created byman2html,using the manual pages.