specs/saver.xml

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