1XScreenSaver(3) Library Functions Manual XScreenSaver(3)
2
6 XScreenSaver - X11 Screen Saver extension client library
7
9 #include <X11/extensions/scrnsaver.h>
10 typedef struct {
12 Window window; /∗ screen saver window */
13 int state; /∗ ScreenSaver{Off,On,Disabled} */
14 int kind; /∗ ScreenSaver{Blanked,Internal,External} */
15 unsigned long til_or_since; /∗ milliseconds */
16 unsigned long idle; /∗ milliseconds */
17 unsigned long eventMask; /∗ events */
18 } XScreenSaverInfo;
19 typedef struct {
21 int type; /∗ of event */
22 unsigned long serial; /∗ # of last request processed by server */
23 Bool send_event; /∗ true if this came frome a SendEvent request */
24 Display *display; /∗ Display the event was read from */
25 Window window; /∗ screen saver window */
26 Window root; /∗ root window of event screen */
27 int state; /∗ ScreenSaver{Off,On,Cycle} */
28 int kind; /∗ ScreenSaver{Blanked,Internal,External} */
29 Bool forced; /∗ extents of new region */
30 Time time; /∗ event timestamp */
31 } XScreenSaverNotifyEvent;
32 Bool XScreenSaverQueryExtension(Display *dpy, int *event_base_return,
34 int *error_base_return);
35 Status XScreenSaverQueryVersion(Display *dpy, int *major_ver‐
37 sion_return, int *minor_version_return);
38 XScreenSaverInfo *XScreenSaverAllocInfo(void);
40 Status XScreenSaverQueryInfo(Display *dpy, Drawable drawable, XScreen‐
42 SaverInfo *saver_info);
43 void XScreenSaverSelectInput(Display *dpy, Drawable drawable, unsigned
45 long mask);
46 void XScreenSaverSetAttributes(Display *dpy, Drawable drawable, int x,
48 int y, unsigned int width, unsigned int height, unsigned int
49 border_width, int depth, unsigned int class, Visual *visual,
50 unsigned long valuemask, XSetWindowAttributes *attributes);
51 void XScreenSaverUnsetAttributes(Display *dpy, Drawable drawable);
53 void XScreenSaverSaverRegister(Display *dpy, int screen, XID xid, Atom
55 type);
56 Status XScreenSaverUnregister(Display *dpy, int screen);
58 Status XScreenSaverGetRegistered(Display *dpy, int screen, XID *xid,
60 Atom *type);
61 void XScreenSaverSuspend(Display *dpy, Bool suspend);
63
65 The X Window System provides support for changing the image on a dis‐
66 play screen after a user-settable period of inactivity to avoid burning
67 the cathode ray tube phosphors. However, no interfaces are provided
68 for the user to control the image that is drawn. This extension allows
69 an external ``screen saver'' client to detect when the alternate image
70 is to be displayed and to provide the graphics.
71 Current X server implementations typically provide at least one form of
73 ``screen saver'' image. Historically, this has been a copy of the X
74 logo drawn against the root background pattern. However, many users
75 have asked for the mechanism to allow them to write screen saver pro‐
76 grams that provide capabilities similar to those provided by other win‐
77 dow systems. In particular, such users often wish to be able to dis‐
78 play corporate logos, instructions on how to reactivate the screen, and
79 automatic screen-locking utilities. This extension provides a means
80 for writing such clients.
81 Assumptions
83 This extension exports the notion of a special screen saver window that
84 is mapped above all other windows on a display. This window has the
85 override-redirect attribute set so that it is not subject to manipula‐
86 tion by the window manager. Furthermore, the X identifier for the win‐
87 dow is never returned by QueryTree requests on the root window, so it
88 is typically not visible to other clients.
89 XScreenSaverQueryExtension returns True if the XScreenSaver extension
91 is available on the given display. A client must call XScreenSaver‐
92 QueryExtension before calling any other XScreenSaver function in order
93 to negotiate a compatible protocol version; otherwise the client will
94 get undefined behavior (XScreenSaver may or may not work).
95 If the extension is supported, the event number for ScreenSaverNotify
97 events is returned in the value pointed to by event_base. Since no
98 additional errors are defined by this extension, the results of
99 error_base are not defined.
100 XScreenSaverQueryVersion returns True if the request succeeded; the
102 values of the major and minor protocol versions supported by the server
103 are returned in major_version_return and minor_version_return .
104 XScreenSaverAllocInfo allocates and returns an XScreenSaverInfo struc‐
106 ture for use in calls to XScreenSaverQueryInfo. All fields in the
107 structure are initialized to zero. If insufficient memory is avail‐
108 able, NULL is returned. The results of this routine can be released
109 using XFree.
110 XScreenSaverQueryInfo returns information about the current state of
112 the screen server in saver_info and a non-zero value is returned. If
113 the extension is not supported, saver_info is not changed and 0 is
114 returned.
115 The state field specifies whether or not the screen saver is currently
117 active and how the til-or-since value should be interpreted:
118 Off The screen is not currently being saved; til-or-since specifies the
120 number of milliseconds until the screen saver is expected to acti‐
121 vate.
122 On The screen is currently being saved; til-or-since specifies the
124 number of milliseconds since the screen saver activated.
125 Disabled
127 The screen saver is currently disabled; til-or-since is zero.
128 The kind field specifies the mechanism that either is currently being
130 used or would have been were the screen being saved:
131 Blanked
133 The video signal to the display monitor was disabled.
134 Internal
136 A server-dependent, built-in screen saver image was displayed;
137 either no client had set the screen saver window attributes or a
138 different client had the server grabbed when the screen saver acti‐
139 vated.
140 External
142 The screen saver window was mapped with attributes set by a client
143 using the ScreenSaverSetAttributes request.
144 The idle field specifies the number of milliseconds since the last
146 input was received from the user on any of the input devices.
147 The event-mask field specifies which, if any, screen saver events this
148 client has requested using ScreenSaverSelectInput.
149 XScreenSaverSelectInput asks that events related to the screen saver be
151 generated for this client. If no bits are set in event-mask, then no
152 events will be generated. Otherwise, any combination of the following
153 bits may be set:
154 ScreenSaverNotify
156 If this bit is set, ScreenSaverNotify events are generated
157 whenever the screen saver is activated or deactivated.
158 ScreenSaverCycle
160 If this bit is set, ScreenSaverNotify events are generated
161 whenever the screen saver cycle interval passes.
162 XScreenSaverSetAttributes sets the attributes to be used the next time
164 the external screen saver is activated. If another client currently
165 has the attributes set, a BadAccess error is generated and the request
166 is ignored.
167 Otherwise, the specified window attributes are checked as if they were
168 used in a core CreateWindow request whose parent is the root. The
169 override-redirect field is ignored as it is implicitly set to True. If
170 the window attributes result in an error according to the rules for
171 CreateWindow, the request is ignored.
172 Otherwise, the attributes are stored and will take effect on the next
173 activation that occurs when the server is not grabbed by another
174 client. Any resources specified for the background-pixmap or cursor
175 attributes may be freed immediately. The server is free to copy the
176 background-pixmap or cursor resources or to use them in place; there‐
177 fore, the effect of changing the contents of those resources is unde‐
178 fined. If the specified colormap no longer exists when the screen
179 saver activates, the parent's colormap is used instead. If no errors
180 are generated by this request, any previous screen saver window
181 attributes set by this client are released.
182 When the screen saver next activates and the server is not grabbed by
183 another client, the screen saver window is created, if necessary, and
184 set to the specified attributes and events are generated as usual. The
185 colormap associated with the screen saver window is installed.
186 Finally, the screen saver window is mapped.
187 The window remains mapped and at the top of the stacking order until
188 the screen saver is deactivated in response to activity on any of the
189 user input devices, a ForceScreenSaver request with a value of Reset,
190 or any request that would cause the window to be unmapped.
191 If the screen saver activates while the server is grabbed by another
192 client, the internal saver mechanism is used. The ForceScreenSaver
193 request may be used with a value of Active to deactivate the internal
194 saver and activate the external saver.
195 If the screen saver client's connection to the server is broken while
196 the screen saver is activated and the client's close down mode has not
197 been RetainPermanent or RetainTemporary, the current screen saver is
198 deactivated and the internal screen saver is immediately activated.
199 When the screen saver deactivates, the screen saver window's colormap
200 is uninstalled and the window is unmapped (except as described below).
201 The screen saver XID is disassociated with the window and the server
202 may, but is not required to, destroy the window along with any chil‐
203 dren.
204 When the screen saver is being deactivated and then immediately reacti‐
205 vated (such as when switching screen savers), the server may leave the
206 screen saver window mapped (typically to avoid generating exposures).
207 XScreenSaverUnsetAttributes instructs the server to discard any previ‐
209 ous screen saver window attributes set by this client.
210 XScreenSaverRegister stores the given XID in the _SCREEN_SAVER_ID prop‐
212 erty (of the given type) on the root window of the specified screen.
213 It returns zero if an error is encountered and the property is not
214 changed, otherwise it returns non-zero.
215 XScreenSaverUnregister removes any _SCREEN_SAVER_ID from the root win‐
217 dow of the specified screen. It returns zero if an error is encoun‐
218 tered and the property is changed, otherwise it returns non-zero.
219 XScreenSaverGetRegistered returns the XID and type stored in the
221 _SCREEN_SAVER_ID property on the root window of the specified screen.
222 It returns zero if an error is encountered or if the property does not
223 exist or is not of the correct format; otherwise it returns non-zero.
224 XScreenSaverSuspend temporarily suspends the screensaver and DPMS timer
226 if suspend is 'True', and restarts the timer if suspend is 'False'.
227 This function should be used by applications that don't want the
228 screensaver or DPMS to become activated while they're for example in
229 the process of playing a media sequence, or are otherwise continuously
230 presenting visual information to the user while in a non-interactive
231 state. This function is not intended to be called by an external
232 screensaver application.
233 If XScreenSaverSuspend is called multiple times with suspend set to
234 'True', it must be called an equal number of times with suspend set to
235 'False' in order for the screensaver timer to be restarted. This
236 request has no affect if a client tries to resume the screensaver with‐
237 out first having suspended it. XScreenSaverSuspend can thus not be
238 used by one client to resume the screensaver if it's been suspended by
239 another client.
240 If a client that has suspended the screensaver becomes disconnected
241 from the X server, the screensaver timer will automatically be
242 restarted, unless it's still suspended by another client. Suspending
243 the screensaver timer doesn't prevent the screensaver from being force‐
244 ably activated with the ForceScreenSaver request, or a DPMS mode from
245 being set with the DPMSForceLevel request.
246 XScreenSaverSuspend also doesn't deactivate the screensaver or DPMS if
247 either is active at the time the request to suspend them is received by
248 the X server. But once they've been deactivated, they won't automati‐
249 cally be activated again, until the client has canceled the suspension.
250
252 XScreenSaverSelectInput, XScreenSaverQueryInfo, XScreenSaverSetAt‐
253 tributes and XScreenSaverUnsetAttributes will generate a BadDrawable
254 error if drawable is not a valid drawable identifier. If any undefined
255 bits are set in event-mask, a BadValue error is generated by XScreenSa‐
256 verSelectInput .
257
259 XScreenSaverSuspend is available in version 1.1 and later versions of
260 the X Screen Saver Extension. Version 1.1 was first released with
261 X11R7.1.
262
264 X(7)
265
267 Jim Fulton and Keith Packard.
268
270 This API is considered as experimental. The Xss library major revision
271 may be incremented whenever incompatible changes are done to the API
272 without notice. Use with care.
273X Version 11 libXScrnSaver 1.2.0 XScreenSaver(3)