PageRenderTime 58ms CodeModel.GetById 23ms app.highlight 24ms RepoModel.GetById 1ms app.codeStats 0ms

/specs/saver.xml

#
XML | 943 lines | 856 code | 87 blank | 0 comment | 0 complexity | 588103b3f3354a6418bd4711cb5429d0 MD5 | raw file
  1<?xml version="1.0" encoding="UTF-8" ?>
  2<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
  3                   "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd"
  4[
  5<!ENTITY % defs SYSTEM "defs.ent"> %defs;
  6]>
  7
  8<book id="saver">
  9
 10<bookinfo>
 11   <title>X11 Screen Saver Extension</title>
 12   <subtitle>MIT X Consortium Proposed Standard</subtitle>
 13   <releaseinfo>X Version 11, Release &fullrelvers;</releaseinfo>
 14   <releaseinfo>Version 1.0</releaseinfo>
 15   <authorgroup>
 16     <author>
 17      <firstname>Jim</firstname><surname>Fulton</surname>
 18      <affiliation><orgname>Network Computing Devices, Inc</orgname></affiliation>
 19     </author>
 20     <author>
 21      <firstname>Keith</firstname><surname>Packard</surname>
 22      <affiliation><orgname>
 23X Consortium, Laboratory for Computer Science, Massachusetts Institute of Technology
 24      </orgname></affiliation>
 25     </author>
 26   </authorgroup>
 27
 28   <copyright><year>1992</year>
 29     <holder>Massachusetts Institute of Technology</holder>
 30     <holder>Network Computing Devices, Inc</holder>
 31   </copyright>
 32
 33
 34<legalnotice>
 35<para>
 36Permission to use, copy, modify, and distribute this documentation for any
 37purpose and without fee is hereby granted, provided that the above copyright
 38notice and this permission notice appear in all copies.  MIT and
 39Network Computing Devices, Inc. make no
 40representations about the suitability for any purpose of the information in
 41this document.  This documentation is provided "as is" without express or
 42implied warranty.
 43</para>
 44
 45</legalnotice>
 46</bookinfo>
 47
 48<chapter id='Introduction'>
 49<title>Introduction</title>
 50<para>
 51The X Window System provides support for changing the image on a display screen
 52after a user-settable period of inactivity to avoid burning the cathode ray
 53tube phosphors.  However, no interfaces are provided for the user to control
 54the image that is drawn.  This extension allows an external "screen saver"
 55client to detect when the alternate image is to be displayed and to provide the
 56graphics.
 57</para>
 58<para>
 59Current X server implementations typically provide at least one form of
 60"screen saver" image.  Historically, this has been a copy of the X logo
 61drawn against the root background pattern.  However, many users have asked
 62for the mechanism to allow them to write screen saver programs that provide
 63capabilities similar to those provided by other window systems.  In
 64particular, such users often wish to be able to display corporate logos,
 65instructions on how to reactivate the screen, and automatic screen-locking
 66utilities.  This extension provides a means for writing such clients.
 67</para>
 68</chapter>
 69
 70<chapter id="Assumptions">
 71<title>Assumptions</title>
 72<para>
 73This extension exports the notion of a special screen saver window that is
 74mapped above all other windows on a display.  This window has the
 75<emphasis remap='I'>override-redirect</emphasis> attribute set so that it is not subject to manipulation by
 76the window manager.  Furthermore, the X identifier for the window is never
 77returned by <function>QueryTree</function> requests on the root window, so it is typically
 78not visible to other clients.
 79</para>
 80</chapter>
 81
 82<chapter id="Overview">
 83<title>Overview</title>
 84<para>
 85The core
 86<function>SetScreenSaver</function>
 87request can be used to set the length of time without
 88activity on any input devices after which the screen saver should "activate"
 89and alter the image on the screen.  This image periodically "cycles" to
 90reduce
 91the length of time that any particular pixel is illuminated.  Finally, the
 92screen saver is "deactivated" in response to activity on any of the input
 93devices
 94or particular X requests.
 95</para>
 96
 97<para>
 98Screen saving is typically done by disabling video output to the display tube
 99or by drawing a changing pattern onto the display.  If the server chooses the
100latter approach, a window with a special identifier is created and mapped at
101the top of the stacking order where it remains until the screen saver
102deactivates.  At this time, the window is unmapped and is not accessible to any
103client requests.
104</para>
105<para>
106The server's default mechanism is refered to as the <emphasis remap='I'>internal</emphasis> screen
107saver.  An <emphasis remap='I'>external</emphasis>
108screen saver client requires a means of determining the window
109id for the screen saver window and setting the attributes (e.g. size,
110location, visual, colormap) to be used when the window is mapped.  These
111requirements form the basis of this extension.
112</para>
113</chapter>
114
115<chapter id="Issues">
116<title>Issues</title>
117<para>
118This extension raises several interesting issues.  First is the question of
119what should be done if some other client has the server grabbed when the screen
120saver is supposed to activate?  This commonly occurs with window managers that
121automatically ask the user to position a window when it is first mapped by
122grabbing the server and drawing XORed lines on the root window.
123</para>
124<para>
125Second, a screen saver program must control the actual RGB values sent to the
126display tube to ensure that the values change periodically to avoid phosphor
127burn in.  Thus, the client must have a known colormap installed whenever the
128screen saver window is displayed.  To prevent screen flashing, the visual type
129of the screen saver window should also be controlable.
130</para>
131<para>
132Third, some implementations may wish to destroy the screen saver window when
133it is not mapped so that it need not be avoided during event delivery.  Thus,
134screen saver clients may find that the requests that reference the screen
135saver window may fail when the window is not displayed.
136</para>
137</chapter>
138
139<chapter id="Protocol">
140<title>Protocol</title>
141<para>
142The Screen Saver extension is as follows:
143</para>
144
145<sect1 id="Types">
146<title>Types</title>
147<para>
148In adition to the comon types described in the core protocol, the following
149type is used in the request and event definitions in subsequent sections.
150</para>
151
152<informaltable frame="topbot">
153  <?dbfo keep-together="always" ?>
154  <tgroup cols='2' align='left' colsep='0' rowsep='0'>
155  <colspec colname='c1' colwidth="1.0*"/>
156  <colspec colname='c2' colwidth="1.5*"/>
157  <thead>
158    <row rowsep='1'>
159      <entry>Name</entry>
160      <entry>Value</entry>
161    </row>
162  </thead>
163  <tbody>
164    <row>
165      <entry>SCREENSAVEREVENT</entry>
166      <entry><emphasis role="bold">ScreenSaverNotify</emphasis>,
167      <emphasis role="bold">ScreenSaverCycle</emphasis></entry>
168    </row>
169  </tbody>
170  </tgroup>
171</informaltable>
172</sect1>
173
174<sect1 id="Errors">
175<title>Errors</title>
176<para>
177The Screen Saver extension adds no errors beyond the core protocol.
178</para>
179</sect1>
180
181<sect1 id="Requests">
182<title>Requests</title>
183<para>
184The Screen Saver extension adds the following requests:
185</para>
186
187<literallayout>
188<emphasis role="bold">ScreenSaverQueryVersion</emphasis>
189     client-major-version: CARD8
190     client-minor-version: CARD8
191->
192     server-major-version: CARD8
193     server-minor-version: CARD8
194</literallayout>
195
196<para>
197This request allows the client and server to determine which version of
198the protocol should be used.  The client sends the version that it
199prefers; if the server understands that
200version, it returns the same values and interprets subsequent requests
201for this extension according to the specified version.  Otherwise,
202the server returns the closest version of the protocol that it can
203support and interprets subsequent requests according to that version.
204This document describes major version 1, minor version 0; the major
205and minor revision numbers should only be incremented in response to
206incompatible and compatible changes, respectively.
207</para>
208
209<literallayout>
210<emphasis role="bold">ScreenSaverQueryInfo</emphasis>
211<emphasis>drawable</emphasis> DRAWABLE
212
213saver-window: WINDOW
214state: {<emphasis role="bold">Disabled</emphasis>, <emphasis role="bold">Off</emphasis>, <emphasis role="bold">On</emphasis>}
215kind: {<emphasis role="bold">Blanked</emphasis>, <emphasis role="bold">Internal</emphasis>, <emphasis role="bold">External</emphasis>}
216til-or-since: CARD32
217idle: CARD32
218event-mask: SETofSCREENSAVEREVENT
219
220Errors: <emphasis role="bold">Drawable</emphasis>
221</literallayout>
222
223<para>
224This request returns information about the state of the screen
225saver on the screen associated with <emphasis remap='I'>drawable</emphasis>.  The <emphasis remap='I'>saver-window</emphasis>
226is the XID that is associated with the screen saver window.  This
227window is not guaranteed to exist
228except when external screen saver is active.  Although it is a
229child of the root, this window is not returned by
230<function>QueryTree</function>
231requests on the root.  Whenever this window is mapped, it is always above
232any of its siblings in the stacking order.  XXX - TranslateCoords?
233</para>
234<para>
235The <emphasis remap='I'>state</emphasis> field specifies whether or not the screen saver is currently
236active and how the <emphasis remap='I'>til-or-since</emphasis> value should be interpretted:
237</para>
238
239<informaltable frame="none">
240  <?dbfo keep-together="always" ?>
241  <tgroup cols='2' align='left' colsep='0' rowsep='0'>
242  <colspec colname='c1' colwidth="1.0*"/>
243  <colspec colname='c2' colwidth="5.0*"/>
244  <tbody>
245    <row>
246      <entry><emphasis role="bold">Off</emphasis></entry>
247      <entry>
248The screen is not currently being saved;
249<emphasis remap='I'>til-or-since</emphasis>
250specifies the number of milliseconds until the screen saver is expected to
251activate.
252      </entry>
253    </row>
254    <row>
255      <entry><emphasis role="bold">On</emphasis></entry>
256      <entry>
257The screen is currently being saved;
258<emphasis remap='I'>til-or-since</emphasis> specifies
259the number of milliseconds since the screen saver activated.
260      </entry>
261    </row>
262    <row>
263      <entry><emphasis role="bold">Disabled</emphasis></entry>
264      <entry>
265The screen saver is currently disabled;
266<emphasis remap='I'>til-or-since</emphasis> is zero.
267      </entry>
268    </row>
269  </tbody>
270  </tgroup>
271</informaltable>
272
273<para>
274The <emphasis remap='I'>kind</emphasis> field specifies the mechanism that either is currently being
275used or would have been were the screen being saved:
276</para>
277
278<informaltable frame="none">
279  <?dbfo keep-together="always" ?>
280  <tgroup cols='2' align='left' colsep='0' rowsep='0'>
281  <colspec colname='c1' colwidth="1.0*"/>
282  <colspec colname='c2' colwidth="5.0*"/>
283  <tbody>
284    <row>
285      <entry><emphasis role="bold">Blanked</emphasis></entry>
286      <entry>The video signal to the display monitor was disabled.</entry>
287    </row>
288    <row>
289      <entry><emphasis role="bold">Internal</emphasis></entry>
290      <entry>A server-dependent, built-in screen saver image was displayed; either no
291      client had set the screen saver window attributes or a different client
292      had the server grabbed when the screen saver activated.</entry>
293    </row>
294    <row>
295      <entry><emphasis role="bold">External</emphasis></entry>
296      <entry>The screen saver window was mapped with attributes set by a
297      client using the <function>ScreenSaverSetAttributes</function> request.</entry>
298    </row>
299  </tbody>
300  </tgroup>
301</informaltable>
302
303<para>
304The <emphasis remap='I'>idle</emphasis> field specifies the number of milliseconds since the last
305input was received from the user on any of the input devices.
306</para>
307
308<para>
309The <emphasis remap='I'>event-mask</emphasis> field specifies which, if any, screen saver
310events this client has requested using <function>ScreenSaverSelectInput</function>.
311</para>
312
313<para>
314If <emphasis remap='I'>drawable</emphasis> is not a valid drawable identifier, a Drawable
315error is returned and the request is ignored.
316</para>
317
318<literallayout>
319<emphasis role="bold">ScreenSaverSelectInput</emphasis>
320drawable: DRAWABLE
321event-mask: SETofSCREENSAVEREVENT
322</literallayout>
323
324<para>
325Errors:
326<emphasis role="bold">Drawable</emphasis>,
327<emphasis role="bold">Match</emphasis>
328</para>
329
330<para>
331This request specifies which Screen Saver extension events on the screen
332associated with <emphasis remap='I'>drawable</emphasis> should be generated for this client.  If
333no bits are set in <emphasis remap='I'>event-mask</emphasis>, then no events will be generated.
334Otherwise, any combination of the following bits may be set:
335</para>
336
337<informaltable frame="none">
338  <?dbfo keep-together="always" ?>
339  <tgroup cols='2' align='left' colsep='0' rowsep='0'>
340  <colspec colname='c1' colwidth="1.0*"/>
341  <colspec colname='c2' colwidth="3.0*"/>
342  <tbody>
343    <row>
344      <entry><emphasis role="bold">ScreenSaverNotify</emphasis></entry>
345      <entry>
346If this bit is set, <emphasis role="bold">ScreenSaverNotify</emphasis> events are generated whenever
347the screen saver is activated or deactivated.
348      </entry>
349    </row>
350    <row>
351      <entry><emphasis role="bold">ScreenSaverCycle</emphasis></entry>
352      <entry>
353If this bit is set, <emphasis role="bold">ScreenSaverNotify</emphasis> events are generated whenever
354the screen saver cycle interval passes.
355      </entry>
356    </row>
357  </tbody>
358  </tgroup>
359</informaltable>
360
361<para>
362If <emphasis remap='I'>drawable</emphasis> is not a valid drawable identifier, a Drawable
363error is returned.  If any undefined bits are set in <emphasis remap='I'>event-mask</emphasis>,
364a Value error is returned.  If an error is returned,
365the request is ignored.
366</para>
367
368<para>
369<emphasis role="bold">ScreenSaverSetAttributes</emphasis>
370</para>
371<literallayout>
372drawable: DRAWABLE
373class:
374{<emphasis role="bold">InputOutput</emphasis>, <emphasis role="bold">InputOnly</emphasis>, <emphasis role="bold">CopyFromParent</emphasis>}
375depth: CARD8
376visual: VISUALID or <emphasis role="bold">CopyFromParent</emphasis>
377x, y: INT16
378width, height, border-width: CARD16
379value-mask: BITMASK
380value-list: LISTofVALUE
381
382<emphasis role="bold">Access</emphasis>, <emphasis role="bold">Window</emphasis>, <emphasis role="bold">Pixmap</emphasis>, <emphasis role="bold">Colormap</emphasis>, <emphasis role="bold">Cursor</emphasis>, <emphasis role="bold">Match</emphasis>, <emphasis role="bold">Value</emphasis>, <emphasis role="bold">Alloc</emphasis>
383</literallayout>
384
385<para>
386This request sets the attributes that this client would like to see
387used in creating the screen saver window on the screen associated
388with <emphasis remap='I'>drawable</emphasis>.  If another client currently has the attributes set,
389an Access error is generated and the request is ignored.
390</para>
391
392<para>
393Otherwise, the specified window attributes are checked as if
394they were used in a core <function>CreateWindow</function> request whose
395parent is the root.  The <emphasis remap='I'>override-redirect</emphasis> field is ignored as
396it is implicitly set to True.  If the window attributes result in an
397error according to the rules for <function>CreateWindow</function>, the request is ignored.
398</para>
399<para>
400Otherwise, the attributes are stored and will take effect on the next
401activation that occurs when the server is not grabbed by another client.
402Any resources specified for the
403<emphasis remap='I'>background-pixmap</emphasis> or <emphasis remap='I'>cursor</emphasis> attributes may be
404freed immediately.  The server is free to copy the <emphasis remap='I'>background-pixmap</emphasis>
405or <emphasis remap='I'>cursor</emphasis> resources or to use them in place; therefore, the effect of
406changing the contents of those resources is undefined.  If the
407specified <emphasis remap='I'>colormap</emphasis> no longer exists when the screen saver activates,
408the parent's colormap is used instead.  If no errors are generated by this
409request, any previous
410screen saver window attributes set by this client are released.
411</para>
412<para>
413When the screen saver next activates and the server is not grabbed by
414another client, the screen saver window is
415created, if necessary, and set to the specified attributes and events
416are generated as usual.  The colormap
417associated with the screen saver window is
418installed.  Finally, the screen saver window is mapped.
419</para>
420<para>
421The window remains mapped and at the top of the stacking order
422until the screen saver is deactivated in response to activity on
423any of the user input devices, a <function>ForceScreenSaver</function> request with
424a value of Reset, or any request that would cause the window to be
425unmapped.
426</para>
427<para>
428If the screen saver activates while the server is grabbed by another
429client, the internal saver mechanism is used.  The <function>ForceScreenSaver</function>
430request may be used with a value of Active to
431deactivate the internal saver and activate the external saver.
432</para>
433<para>
434If the screen saver client's connection to the server is broken
435while the screen saver is activated and the client's close down mode has not
436been RetainPermanent or RetainTemporary, the current screen saver
437is deactivated and the internal screen saver is immediately activated.
438</para>
439<para>
440When the screen saver deactivates, the screen saver window's colormap
441is uninstalled and the window is unmapped (except as described below).
442The screen saver XID is disassociated
443with the window and the server may, but is not required to,
444destroy the window along with any children.
445</para>
446<para>
447When the screen saver is being deactivated and then immediately
448reactivated (such as when switching screen savers), the server
449may leave the screen saver window mapped (typically to avoid
450generating exposures).
451</para>
452
453<para>
454<emphasis role="bold">ScreenSaverUnsetAttributes</emphasis>
455</para>
456
457<literallayout>
458<emphasis>drawble</emphasis>: <emphasis role="bold">DRAWABLE</emphasis>
459
460Errors: <emphasis role="bold">Drawable</emphasis>
461</literallayout>
462
463<para>
464This request notifies the server that this client no longer
465wishes to control the screen saver window.  Any screen saver
466attributes set by this client and any descendents of the screen
467saver window created by this client should be released
468immediately if the screen saver is not active, else upon
469deactivation.
470</para>
471<para>
472This request is ignored if the client has not previously set the screen saver
473window attributes.
474</para>
475</sect1>
476
477<sect1 id="Events">
478<title>Events</title>
479<para>
480The Screen Saver extension adds one event:
481</para>
482<para>
483<emphasis role="bold">ScreenSaverNotify</emphasis>
484</para>
485
486<literallayout>
487<emphasis role="bold">root</emphasis>: WINDOW
488<emphasis role="bold">window</emphasis>: WINDOW
489<emphasis role="bold">state</emphasis>: {<emphasis role="bold">Off</emphasis>, <emphasis role="bold">On</emphasis>, <emphasis role="bold">Cycle</emphasis>}
490<emphasis role="bold">kind</emphasis>: { <emphasis role="bold">Blanked</emphasis>, <emphasis role="bold">Internal</emphasis> , <emphasis role="bold">External</emphasis> }
491<emphasis role="bold">forced</emphasis>: BOOL
492<emphasis role="bold">time</emphasis>: TIMESTAMP
493</literallayout>
494<para>
495This event is delivered to clients that have requested
496ScreenSaverNotify events using the <function>ScreenSaverSelectInput</function> request
497whenever the screen saver activates or deactivates.
498</para>
499<para>
500The <emphasis remap='I'>root</emphasis> field specifies root window of the screen for
501which the event was generated.  The <emphasis remap='I'>window</emphasis> field specifies
502the value that is returned by <function>ScreenSaverQueryInfo</function> as
503the identifier for the screen saver window.  This window is not
504required to exist if the external screen saver is not active.
505</para>
506<para>
507The <emphasis remap='I'>state</emphasis> field specifies the cause of the event:
508</para>
509
510<informaltable frame="none">
511  <?dbfo keep-together="always" ?>
512  <tgroup cols='2' align='left' colsep='0' rowsep='0'>
513  <colspec colname='c1' colwidth="1.0*"/>
514  <colspec colname='c2' colwidth="5.0*"/>
515  <tbody>
516    <row>
517      <entry><emphasis role="bold">Off</emphasis></entry>
518      <entry>
519The screen saver deactivated; this event is sent if the client has set the
520ScreenSaverNotify bit in its event mask.
521      </entry>
522    </row>
523    <row>
524      <entry><emphasis role="bold">On</emphasis></entry>
525      <entry>
526The screen saver activated.  This event is sent if the client has set the
527ScreenSaverNotify bit in its event mask.
528      </entry>
529    </row>
530    <row>
531      <entry><emphasis role="bold">Cycle</emphasis></entry>
532      <entry>
533The cycle interval passed and the client is expected to change the image on
534the screen.  This event is sent if the client has set the
535ScreenSaverCycle bit in its event mask.
536      </entry>
537    </row>
538  </tbody>
539  </tgroup>
540</informaltable>
541
542<para>
543If <emphasis remap='I'>state</emphasis> is set to
544<emphasis role="bold">On </emphasis> or
545<emphasis role="bold">Off</emphasis>
546then <emphasis remap='I'>forced</emphasis> indicates whether or not
547activation or deactivation was caused by a core
548<function>ForceScreenSaver</function>
549request; otherwise, <emphasis remap='I'>forced</emphasis> is set to False.
550</para>
551
552<para>
553The <emphasis remap='I'>kind</emphasis> field specifies mechanism that was used to save the screen
554when the screen saver was activated, as described in
555<function>ScreenSaverQueryInfo</function>.
556</para>
557
558<para>
559The <emphasis remap='I'>time</emphasis> field indicates the server time
560when the event was generated.
561</para>
562</sect1>
563</chapter>
564
565<chapter id="Encoding">
566<title>Encoding</title>
567<para>
568Please refer to the X11 Protocol Encoding document as this document uses
569conventions established there.
570</para>
571<para>
572The name of this extension is "SCREEN-SAVER".
573</para>
574
575<sect1 id="Common_Types">
576<title>Common Types</title>
577<literallayout class="monospaced">
578SETofSCREENSAVEREVENT
579     #x00000001     ScreenSaverNotifyMask
580     #x00000002     ScreenSaverCycleMask
581</literallayout>
582</sect1>
583
584<sect1 id="Requests_2">
585<title>Requests</title>
586<literallayout class="monospaced">
587<emphasis role="bold">ScreenSaverQueryVersion</emphasis>
5881     CARD8                   screen saver opcode
5891     0                       minor opcode
5902     2                       request length
5911     CARD8                   client major version
5921     CARD8                   client minor version
5932                             unused
594->
5951     1                       Reply
5961                             unused
5972     CARD16                  sequence number
5984     0                       reply length
5991     CARD8                   server major version
6001     CARD8                   server minor version
60122                            unused
602
603<emphasis role="bold">ScreenSaverQueryInfo</emphasis>
6041     CARD8                   screen saver opcode
6051     1                       minor opcode
6062     2                       request length
6074     DRAWABLE                drawable associated with screen
608->
6091     1                       Reply
6101     CARD8                   state
611      0          Off
612      1          On
613      3          Disabled
6142     CARD16                  sequence number
6154     0                       reply length
6164     WINDOW                  saver window
6174     CARD32                  milliseconds until saver or since saver
6184     CARD32                  milliseconds since last user device input
6194     SETofSCREENSAVEREVENT   event mask
6201     CARD8                   kind
621      0          Blanked
622      1          Internal
623      2          External
62410               unused
625
626<emphasis role="bold">ScreenSaverSelectInput</emphasis>
6271     CARD8                   screen saver opcode
6281     2                       minor opcode
6292     3                       request length
6304     DRAWABLE                drawable associated with screen
6314     SETofSCREENSAVEREVENT   event mask
632
633<emphasis role="bold">ScreenSaverSetAttributes</emphasis>
6341     CARD8                   screen saver opcode
6351     3                       minor opcode
6362     6+n                     request length
6374     DRAWABLE                drawable associated with screen
6382     INT16                   x
6392     INT16                   y
6402     CARD16                  width
6412     CARD16                  height
6422     CARD16                  border-width
6431                             class
644      0          CopyFromParent
645      1          InputOutput
646      2          InputOnly
6471     CARD8                   depth
6484     VISUALID                visual
649      0          CopyFromParent
6504     BITMASK                 value-mask (has n bits set to 1)
651      encodings are the same as for core CreateWindow
6524n    LISTofVALUE             value-list
653      encodings are the same as for core CreateWindow
654
655<emphasis role="bold">ScreenSaverUnsetAttributes</emphasis>
6561     CARD8                   screen saver opcode
6571     4                       minor opcode
6582     3                       request length
6594     DRAWABLE                drawable associated with screen
660</literallayout>
661</sect1>
662
663<sect1 id="Events_2">
664<title>Events</title>
665
666<literallayout class="monospaced">
667<emphasis role="bold">ScreenSaverNotify</emphasis>
6681     CARD8                   code assigned by core
6691     CARD8                   state
670      0          Off
671      1          On
672      2          Cycle
6732     CARD16                  sequence number
6744     TIMESTAMP               time
6754     WINDOW                  root
6764     WINDOW                  screen saver window
6771     CARD8                   kind
678      0          Blanked
679      1          Internal
680      2          External
6811     BOOL                    forced
68214                            unused
683</literallayout>
684</sect1>
685</chapter>
686
687<chapter id='Inter_Client_Communications_Conventions'>
688<title>Inter-Client Communications Conventions</title>
689<para>
690Screen saver clients should create at least one resource value whose
691identifier can be stored in a property named
692<emphasis role="bold">_SCREEN_SAVER_ID</emphasis>
693on the root of each screen it is managing.
694This property should have one 32-bit value corresponding to the resource
695identifier; the type of the property should indicate the type of the
696resource and should be one of the following:
697<emphasis role="bold">WINDOW</emphasis>,
698<emphasis role="bold">PIXMAP</emphasis>,
699<emphasis role="bold">CURSOR</emphasis>,
700<emphasis role="bold">FONT</emphasis>, or
701<emphasis role="bold">COLORMAP</emphasis>.
702</para>
703</chapter>
704
705<chapter id="C_language_binding">
706<title>C language binding</title>
707
708<para>
709The C binding for this extension simply provide access to the protocol; they
710add no semantics beyond what is described above.
711</para>
712
713<para>
714The include file for this extension is
715<emphasis role="bold">&lt;X11/extensions/scrnsaver.h&gt;</emphasis>.
716</para>
717
718
719<funcsynopsis id='XScreenSaverQueryExtension'>
720<funcprototype>
721  <funcdef>Bool <function>XScreenSaverQueryExtension</function></funcdef>
722    <paramdef>Display <parameter>*display</parameter></paramdef>
723    <paramdef>int <parameter>*event_base</parameter></paramdef>
724    <paramdef>int <parameter>*error_base</parameter></paramdef>
725</funcprototype>
726</funcsynopsis>
727
728<para>
729This routine returns
730<emphasis role="bold">True</emphasis>
731if the specified <emphasis remap='I'>display</emphasis> supports the
732SCREEN-SAVER extension; otherwise it returns
733<emphasis role="bold">False</emphasis>.
734If the extension is supported, the event number for
735<function>ScreenSaverNotify</function>
736events is returned in the value pointed to by
737<emphasis remap='I'>event_base</emphasis>.  Since
738no additional errors are defined by this extension, the results
739of <emphasis remap='I'>error_base</emphasis> are not defined.
740</para>
741
742<funcsynopsis id='XScreenSaverQueryVersion'>
743<funcprototype>
744  <funcdef>Status <function>XScreenSaverQueryVersion</function></funcdef>
745    <paramdef>Display <parameter>*display</parameter></paramdef>
746    <paramdef>int <parameter>*major</parameter></paramdef>
747    <paramdef>int <parameter>*minor</parameter></paramdef>
748</funcprototype>
749</funcsynopsis>
750
751<para>
752If the specified <emphasis remap='I'>display</emphasis> supports the
753extension, the version numbers of the protocol
754expected by the server are returned in
755<emphasis remap='I'>major</emphasis> and
756<emphasis remap='I'>minor</emphasis> and
757a non-zero value is returned.  Otherwise, the arguments are not
758set and 0 is returned.
759</para>
760
761<para>XScreenSaverInfo *</para>
762<para>XScreenSaverAllocInfo()</para>
763
764<para>
765This routine allocates and returns an
766<emphasis role="bold">XScreenSaverInfo</emphasis> structure
767for use in calls to <xref linkend='XScreenSaverQueryInfo' xrefstyle='select: title'/>.
768All fields in the
769structure are initialized to zero.  If insufficient memory is available,
770NULL is returned.  The results of this routine can be released
771using <olink targetdoc='libX11' targetptr='XFree'><function>XFree</function></olink>.
772</para>
773
774<funcsynopsis id='XScreenSaverQueryInfo'>
775<funcprototype>
776  <funcdef>Status <function>XScreenSaverQueryInfo</function></funcdef>
777    <paramdef>Display <parameter>*display</parameter></paramdef>
778    <paramdef>Drawable <parameter>drawable</parameter></paramdef>
779    <paramdef>XScreenSaverInfo <parameter>*saver_info</parameter></paramdef>
780</funcprototype>
781</funcsynopsis>
782
783<para>
784If the specified <emphasis remap='I'>display</emphasis> supports the extension,
785information about the current state of the
786screen server is returned in <emphasis remap='I'>saver_info</emphasis> and a non-zero value is
787returned.  The <function>XScreenSaverInfo</function> structure is
788defined as follows:
789</para>
790
791<literallayout class="monospaced">
792typedef struct {
793    Window window;                /* screen saver window */
794    int state;                    /* ScreenSaver{Off,On,Disabled} */
795    int kind;                     /* ScreenSaver{Blanked,Internal,External} */
796    unsigned long til_or_since;   /* milliseconds */
797    unsigned long idle;           /* milliseconds */
798    unsigned long event_mask;     /* events */
799} XScreenSaverInfo;
800</literallayout>
801
802<para>
803See the <function>ScreenSaverQueryInfo</function> request for a
804description of the fields.  If the extension is not supported,
805<emphasis remap='I'>saver_info</emphasis> is not changed and 0
806is returned.
807</para>
808
809<funcsynopsis id='XScreenSaverSelectInput'>
810<funcprototype>
811  <funcdef>void <function>XScreenSaverSelectInput</function></funcdef>
812    <paramdef>Display <parameter>*display</parameter></paramdef>
813    <paramdef>Drawable <parameter>drawable</parameter></paramdef>
814    <paramdef>unsigned long <parameter>event_mask</parameter></paramdef>
815</funcprototype>
816</funcsynopsis>
817
818<para>
819If the specified <emphasis remap='I'>display</emphasis> supports the extension,
820this routine asks that events related to
821the screen saver be generated for this client.
822The format of the events generated is:
823</para>
824
825<literallayout class="monospaced">
826typedef struct {
827    int type;               /* of event */
828    unsigned long serial;   /* # of last request processed by server */
829    Bool send_event;        /* true if this came frome a SendEvent request */
830    Display *display;       /* Display the event was read from */
831    Window window;          /* screen saver window */
832    Window root;            /* root window of event screen */
833    int state;              /* ScreenSaver{Off,On,Cycle} */
834    int kind;               /* ScreenSaver{Blanked,Internal,External} */
835    Bool forced;            /* extents of new region */
836    Time time;              /* event timestamp */
837} XScreenSaverNotifyEvent;
838</literallayout>
839
840<para>
841See the definition of the
842<function>ScreenSaverSelectInput</function> request for descriptions
843of the allowed event masks.   <!-- xref ? -->
844</para>
845
846<funcsynopsis id='XScreenSaverSetAttributes'>
847<funcprototype>
848  <funcdef>void <function>XScreenSaverSetAttributes</function></funcdef>
849    <paramdef>Display <parameter>*dpy</parameter></paramdef>
850    <paramdef>Drawable <parameter>drawable</parameter></paramdef>
851    <paramdef>int <parameter>x</parameter></paramdef>
852    <paramdef>int <parameter>y</parameter></paramdef>
853    <paramdef>unsigned int <parameter>width</parameter></paramdef>
854    <paramdef>unsigned int <parameter>height</parameter></paramdef>
855    <paramdef>unsigned int <parameter>border_width</parameter></paramdef>
856    <paramdef>int <parameter>depth</parameter></paramdef>
857    <paramdef>unsigned int <parameter>class</parameter></paramdef>
858    <paramdef>Visual <parameter>*visual</parameter></paramdef>
859    <paramdef>unsigned long <parameter>valuemask</parameter></paramdef>
860    <paramdef>XSetWindowAttributes <parameter>*attributes</parameter></paramdef>
861</funcprototype>
862</funcsynopsis>
863
864<para>
865If the specified <emphasis remap='I'>display</emphasis> supports the
866extension, this routine sets the attributes to be used
867the next time the external screen saver is activated.  See the definition
868of the <function>ScreenSaverSetAttributes</function> request for a
869description of each of the arguments.
870</para>
871
872<funcsynopsis id='XScreenSaverUnsetAttributes'>
873<funcprototype>
874  <funcdef>void <function>XScreenSaverUnsetAttributes</function></funcdef>
875    <paramdef>Display <parameter>*display</parameter></paramdef>
876    <paramdef>Drawable <parameter>drawable</parameter></paramdef>
877</funcprototype>
878</funcsynopsis>
879
880<para>
881If the specified <emphasis remap='I'>display</emphasis> supports the
882extension, this routine instructs the server to discard
883any previous screen saver window attributes set by this client.
884</para>
885
886<funcsynopsis id='XScreenSaverRegister'>
887<funcprototype>
888  <funcdef>Status <function>XScreenSaverRegister</function></funcdef>
889    <paramdef>Display <parameter>*display</parameter></paramdef>
890    <paramdef>int <parameter>screen</parameter></paramdef>
891    <paramdef>XID <parameter>xid</parameter></paramdef>
892    <paramdef>Atom <parameter>type</parameter></paramdef>
893</funcprototype>
894</funcsynopsis>
895
896<para>
897This routine stores the given <emphasis remap='I'>XID</emphasis> in the
898<emphasis role="bold">_SCREEN_SAVER_ID</emphasis> property (of the given
899<emphasis remap='I'>type</emphasis>) on the root window of the specified
900<emphasis remap='I'>screen</emphasis>.  It returns zero if an error
901is encountered and the property is not changed, otherwise it returns
902non-zero.
903</para>
904
905<funcsynopsis id='XScreenSaverUnregister'>
906<funcprototype>
907  <funcdef>Status <function>XScreenSaverUnregister</function></funcdef>
908    <paramdef>Display <parameter>*display</parameter></paramdef>
909    <paramdef>int <parameter>screen</parameter></paramdef>
910</funcprototype>
911</funcsynopsis>
912
913<para>
914This routine removes any <function>_SCREEN_SAVER_ID</function> from the
915root window of the specified <emphasis remap='I'>screen</emphasis>.
916It returns zero if an error is encountered and the property is changed,
917otherwise it returns non-zero.
918</para>
919
920<funcsynopsis id='XScreenSaverGetRegistered'>
921<funcprototype>
922  <funcdef>Status <function>XScreenSaverGetRegistered</function></funcdef>
923    <paramdef>Display <parameter>*display</parameter></paramdef>
924    <paramdef>int <parameter>screen</parameter></paramdef>
925    <paramdef>XID <parameter>*xid</parameter></paramdef>
926    <paramdef>ATOM <parameter>*type</parameter></paramdef>
927</funcprototype>
928</funcsynopsis>
929
930
931<para>
932This routine returns the
933<emphasis remap='I'>XID</emphasis> and
934<emphasis remap='I'>type</emphasis> stored in the
935<emphasis role="bold">_SCREEN_SAVER_ID</emphasis> property on the
936root window of the specified <emphasis remap='I'>screen</emphasis>.
937It returns zero if an error
938is encountered or if the property does not exist or is not of the correct
939format; otherwise it returns non-zero.
940</para>
941
942</chapter>
943</book>