1XScreenSaver(3)            Library Functions Manual            XScreenSaver(3)
2
3
4

NAME

6       XScreenSaver - X11 Screen Saver extension client library
7

SYNOPSIS

9       #include <X11/extensions/scrnsaver.h>
10
11       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
20       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
33       Bool  XScreenSaverQueryExtension(Display  *dpy, int *event_base_return,
34              int *error_base_return);
35
36       Status   XScreenSaverQueryVersion(Display   *dpy,    int    *major_ver‐
37              sion_return, int *minor_version_return);
38
39       XScreenSaverInfo *XScreenSaverAllocInfo(void);
40
41       Status  XScreenSaverQueryInfo(Display *dpy, Drawable drawable, XScreen‐
42              SaverInfo *saver_info);
43
44       void XScreenSaverSelectInput(Display *dpy, Drawable drawable,  unsigned
45              long mask);
46
47       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
52       void XScreenSaverUnsetAttributes(Display *dpy, Drawable drawable);
53
54       void XScreenSaverRegister(Display  *dpy,  int  screen,  XID  xid,  Atom
55              type);
56
57       Status XScreenSaverUnregister(Display *dpy, int screen);
58
59       Status  XScreenSaverGetRegistered(Display  *dpy,  int screen, XID *xid,
60              Atom *type);
61
62       void XScreenSaverSuspend(Display *dpy, Bool suspend);
63

DESCRIPTION

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
72       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
82   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
90       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
96       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
101       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
105       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
111       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
116       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
119       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
123       On  The  screen  is  currently  being saved; til-or-since specifies the
124           number of milliseconds since the screen saver activated.
125
126       Disabled
127           The screen saver is currently disabled; til-or-since is zero.
128
129       The kind field specifies the mechanism that either is  currently  being
130       used or would have been were the screen being saved:
131
132       Blanked
133           The video signal to the display monitor was disabled.
134
135       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
141       External
142           The screen saver window was mapped with attributes set by a  client
143           using the ScreenSaverSetAttributes request.
144
145       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
150       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
155       ScreenSaverNotify
156               If this bit is  set,  ScreenSaverNotify  events  are  generated
157               whenever the screen saver is activated or deactivated.
158
159       ScreenSaverCycle
160               If  this  bit  is  set,  ScreenSaverNotify events are generated
161               whenever the screen saver cycle interval passes.
162
163       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
208       XScreenSaverUnsetAttributes  instructs the server to discard any previ‐
209       ous screen saver window attributes set by this client.
210
211       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
216       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
220       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
225       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

ERRORS

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

AVAILABILITY

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

SEE ALSO

264       X(7)
265

AUTHORS

267       Jim Fulton and Keith Packard.
268

STABILITY

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.
273
274
275
276X Version 11                  libXScrnSaver 1.2.3              XScreenSaver(3)
Impressum