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 <!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>
  23 X 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>
  36 Permission to use, copy, modify, and distribute this documentation for any
  37 purpose and without fee is hereby granted, provided that the above copyright
  38 notice and this permission notice appear in all copies.  MIT and
  39 Network Computing Devices, Inc. make no
  40 representations about the suitability for any purpose of the information in
  41 this document.  This documentation is provided "as is" without express or
  42 implied warranty.
  43 </para>
  44
  45 </legalnotice>
  46 </bookinfo>
  47
  48 <chapter id='Introduction'>
  49 <title>Introduction</title>
  50 <para>
  51 The X Window System provides support for changing the image on a display screen
  52 after a user-settable period of inactivity to avoid burning the cathode ray
  53 tube phosphors.  However, no interfaces are provided for the user to control
  54 the image that is drawn.  This extension allows an external "screen saver"
  55 client to detect when the alternate image is to be displayed and to provide the
  56 graphics.
  57 </para>
  58 <para>
  59 Current X server implementations typically provide at least one form of
  60 "screen saver" image.  Historically, this has been a copy of the X logo
  61 drawn against the root background pattern.  However, many users have asked
  62 for the mechanism to allow them to write screen saver programs that provide
  63 capabilities similar to those provided by other window systems.  In
  64 particular, such users often wish to be able to display corporate logos,
  65 instructions on how to reactivate the screen, and automatic screen-locking
  66 utilities.  This extension provides a means for writing such clients.
  67 </para>
  68 </chapter>
  69
  70 <chapter id="Assumptions">
  71 <title>Assumptions</title>
  72 <para>
  73 This extension exports the notion of a special screen saver window that is
  74 mapped 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
  76 the window manager.  Furthermore, the X identifier for the window is never
  77 returned by <function>QueryTree</function> requests on the root window, so it is typically
  78 not visible to other clients.
  79 </para>
  80 </chapter>
  81
  82 <chapter id="Overview">
  83 <title>Overview</title>
  84 <para>
  85 The core
  86 <function>SetScreenSaver</function>
  87 request can be used to set the length of time without
  88 activity on any input devices after which the screen saver should "activate"
  89 and alter the image on the screen.  This image periodically "cycles" to
  90 reduce
  91 the length of time that any particular pixel is illuminated.  Finally, the
  92 screen saver is "deactivated" in response to activity on any of the input
  93 devices
  94 or particular X requests.
  95 </para>
  96
  97 <para>
  98 Screen saving is typically done by disabling video output to the display tube
  99 or by drawing a changing pattern onto the display.  If the server chooses the
 100 latter approach, a window with a special identifier is created and mapped at
 101 the top of the stacking order where it remains until the screen saver
 102 deactivates.  At this time, the window is unmapped and is not accessible to any
 103 client requests.
 104 </para>
 105 <para>
 106 The server's default mechanism is refered to as the <emphasis remap='I'>internal</emphasis> screen
 107 saver.  An <emphasis remap='I'>external</emphasis>
 108 screen saver client requires a means of determining the window
 109 id for the screen saver window and setting the attributes (e.g. size,
 110 location, visual, colormap) to be used when the window is mapped.  These
 111 requirements form the basis of this extension.
 112 </para>
 113 </chapter>
 114
 115 <chapter id="Issues">
 116 <title>Issues</title>
 117 <para>
 118 This extension raises several interesting issues.  First is the question of
 119 what should be done if some other client has the server grabbed when the screen
 120 saver is supposed to activate?  This commonly occurs with window managers that
 121 automatically ask the user to position a window when it is first mapped by
 122 grabbing the server and drawing XORed lines on the root window.
 123 </para>
 124 <para>
 125 Second, a screen saver program must control the actual RGB values sent to the
 126 display tube to ensure that the values change periodically to avoid phosphor
 127 burn in.  Thus, the client must have a known colormap installed whenever the
 128 screen saver window is displayed.  To prevent screen flashing, the visual type
 129 of the screen saver window should also be controlable.
 130 </para>
 131 <para>
 132 Third, some implementations may wish to destroy the screen saver window when
 133 it is not mapped so that it need not be avoided during event delivery.  Thus,
 134 screen saver clients may find that the requests that reference the screen
 135 saver window may fail when the window is not displayed.
 136 </para>
 137 </chapter>
 138
 139 <chapter id="Protocol">
 140 <title>Protocol</title>
 141 <para>
 142 The Screen Saver extension is as follows:
 143 </para>
 144
 145 <sect1 id="Types">
 146 <title>Types</title>
 147 <para>
 148 In adition to the comon types described in the core protocol, the following
 149 type 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>
 177 The 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>
 184 The 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>
 197 This request allows the client and server to determine which version of
 198 the protocol should be used.  The client sends the version that it
 199 prefers; if the server understands that
 200 version, it returns the same values and interprets subsequent requests
 201 for this extension according to the specified version.  Otherwise,
 202 the server returns the closest version of the protocol that it can
 203 support and interprets subsequent requests according to that version.
 204 This document describes major version 1, minor version 0; the major
 205 and minor revision numbers should only be incremented in response to
 206 incompatible and compatible changes, respectively.
 207 </para>
 208
 209 <literallayout>
 210 <emphasis role="bold">ScreenSaverQueryInfo</emphasis>
 211 <emphasis>drawable</emphasis> DRAWABLE
 212
 213 saver-window: WINDOW
 214 state: {<emphasis role="bold">Disabled</emphasis>, <emphasis role="bold">Off</emphasis>, <emphasis role="bold">On</emphasis>}
 215 kind: {<emphasis role="bold">Blanked</emphasis>, <emphasis role="bold">Internal</emphasis>, <emphasis role="bold">External</emphasis>}
 216 til-or-since: CARD32
 217 idle: CARD32
 218 event-mask: SETofSCREENSAVEREVENT
 219
 220 Errors: <emphasis role="bold">Drawable</emphasis>
 221 </literallayout>
 222
 223 <para>
 224 This request returns information about the state of the screen
 225 saver on the screen associated with <emphasis remap='I'>drawable</emphasis>.  The <emphasis remap='I'>saver-window</emphasis>
 226 is the XID that is associated with the screen saver window.  This
 227 window is not guaranteed to exist
 228 except when external screen saver is active.  Although it is a
 229 child of the root, this window is not returned by
 230 <function>QueryTree</function>
 231 requests on the root.  Whenever this window is mapped, it is always above
 232 any of its siblings in the stacking order.  XXX - TranslateCoords?
 233 </para>
 234 <para>
 235 The <emphasis remap='I'>state</emphasis> field specifies whether or not the screen saver is currently
 236 active 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>
 248 The screen is not currently being saved;
 249 <emphasis remap='I'>til-or-since</emphasis>
 250 specifies the number of milliseconds until the screen saver is expected to
 251 activate.
 252       </entry>
 253     </row>
 254     <row>
 255       <entry><emphasis role="bold">On</emphasis></entry>
 256       <entry>
 257 The screen is currently being saved;
 258 <emphasis remap='I'>til-or-since</emphasis> specifies
 259 the number of milliseconds since the screen saver activated.
 260       </entry>
 261     </row>
 262     <row>
 263       <entry><emphasis role="bold">Disabled</emphasis></entry>
 264       <entry>
 265 The 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>
 274 The <emphasis remap='I'>kind</emphasis> field specifies the mechanism that either is currently being
 275 used 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>
 304 The <emphasis remap='I'>idle</emphasis> field specifies the number of milliseconds since the last
 305 input was received from the user on any of the input devices.
 306 </para>
 307
 308 <para>
 309 The <emphasis remap='I'>event-mask</emphasis> field specifies which, if any, screen saver
 310 events this client has requested using <function>ScreenSaverSelectInput</function>.
 311 </para>
 312
 313 <para>
 314 If <emphasis remap='I'>drawable</emphasis> is not a valid drawable identifier, a Drawable
 315 error is returned and the request is ignored.
 316 </para>
 317
 318 <literallayout>
 319 <emphasis role="bold">ScreenSaverSelectInput</emphasis>
 320 drawable: DRAWABLE
 321 event-mask: SETofSCREENSAVEREVENT
 322 </literallayout>
 323
 324 <para>
 325 Errors:
 326 <emphasis role="bold">Drawable</emphasis>,
 327 <emphasis role="bold">Match</emphasis>
 328 </para>
 329
 330 <para>
 331 This request specifies which Screen Saver extension events on the screen
 332 associated with <emphasis remap='I'>drawable</emphasis> should be generated for this client.  If
 333 no bits are set in <emphasis remap='I'>event-mask</emphasis>, then no events will be generated.
 334 Otherwise, 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>
 346 If this bit is set, <emphasis role="bold">ScreenSaverNotify</emphasis> events are generated whenever
 347 the screen saver is activated or deactivated.
 348       </entry>
 349     </row>
 350     <row>
 351       <entry><emphasis role="bold">ScreenSaverCycle</emphasis></entry>
 352       <entry>
 353 If this bit is set, <emphasis role="bold">ScreenSaverNotify</emphasis> events are generated whenever
 354 the screen saver cycle interval passes.
 355       </entry>
 356     </row>
 357   </tbody>
 358   </tgroup>
 359 </informaltable>
 360
 361 <para>
 362 If <emphasis remap='I'>drawable</emphasis> is not a valid drawable identifier, a Drawable
 363 error is returned.  If any undefined bits are set in <emphasis remap='I'>event-mask</emphasis>,
 364 a Value error is returned.  If an error is returned,
 365 the request is ignored.
 366 </para>
 367
 368 <para>
 369 <emphasis role="bold">ScreenSaverSetAttributes</emphasis>
 370 </para>
 371 <literallayout>
 372 drawable: DRAWABLE
 373 class:
 374 {<emphasis role="bold">InputOutput</emphasis>, <emphasis role="bold">InputOnly</emphasis>, <emphasis role="bold">CopyFromParent</emphasis>}
 375 depth: CARD8
 376 visual: VISUALID or <emphasis role="bold">CopyFromParent</emphasis>
 377 x, y: INT16
 378 width, height, border-width: CARD16
 379 value-mask: BITMASK
 380 value-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>
 386 This request sets the attributes that this client would like to see
 387 used in creating the screen saver window on the screen associated
 388 with <emphasis remap='I'>drawable</emphasis>.  If another client currently has the attributes set,
 389 an Access error is generated and the request is ignored.
 390 </para>
 391
 392 <para>
 393 Otherwise, the specified window attributes are checked as if
 394 they were used in a core <function>CreateWindow</function> request whose
 395 parent is the root.  The <emphasis remap='I'>override-redirect</emphasis> field is ignored as
 396 it is implicitly set to True.  If the window attributes result in an
 397 error according to the rules for <function>CreateWindow</function>, the request is ignored.
 398 </para>
 399 <para>
 400 Otherwise, the attributes are stored and will take effect on the next
 401 activation that occurs when the server is not grabbed by another client.
 402 Any resources specified for the
 403 <emphasis remap='I'>background-pixmap</emphasis> or <emphasis remap='I'>cursor</emphasis> attributes may be
 404 freed immediately.  The server is free to copy the <emphasis remap='I'>background-pixmap</emphasis>
 405 or <emphasis remap='I'>cursor</emphasis> resources or to use them in place; therefore, the effect of
 406 changing the contents of those resources is undefined.  If the
 407 specified <emphasis remap='I'>colormap</emphasis> no longer exists when the screen saver activates,
 408 the parent's colormap is used instead.  If no errors are generated by this
 409 request, any previous
 410 screen saver window attributes set by this client are released.
 411 </para>
 412 <para>
 413 When the screen saver next activates and the server is not grabbed by
 414 another client, the screen saver window is
 415 created, if necessary, and set to the specified attributes and events
 416 are generated as usual.  The colormap
 417 associated with the screen saver window is
 418 installed.  Finally, the screen saver window is mapped.
 419 </para>
 420 <para>
 421 The window remains mapped and at the top of the stacking order
 422 until the screen saver is deactivated in response to activity on
 423 any of the user input devices, a <function>ForceScreenSaver</function> request with
 424 a value of Reset, or any request that would cause the window to be
 425 unmapped.
 426 </para>
 427 <para>
 428 If the screen saver activates while the server is grabbed by another
 429 client, the internal saver mechanism is used.  The <function>ForceScreenSaver</function>
 430 request may be used with a value of Active to
 431 deactivate the internal saver and activate the external saver.
 432 </para>
 433 <para>
 434 If the screen saver client's connection to the server is broken
 435 while the screen saver is activated and the client's close down mode has not
 436 been RetainPermanent or RetainTemporary, the current screen saver
 437 is deactivated and the internal screen saver is immediately activated.
 438 </para>
 439 <para>
 440 When the screen saver deactivates, the screen saver window's colormap
 441 is uninstalled and the window is unmapped (except as described below).
 442 The screen saver XID is disassociated
 443 with the window and the server may, but is not required to,
 444 destroy the window along with any children.
 445 </para>
 446 <para>
 447 When the screen saver is being deactivated and then immediately
 448 reactivated (such as when switching screen savers), the server
 449 may leave the screen saver window mapped (typically to avoid
 450 generating 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
 460 Errors: <emphasis role="bold">Drawable</emphasis>
 461 </literallayout>
 462
 463 <para>
 464 This request notifies the server that this client no longer
 465 wishes to control the screen saver window.  Any screen saver
 466 attributes set by this client and any descendents of the screen
 467 saver window created by this client should be released
 468 immediately if the screen saver is not active, else upon
 469 deactivation.
 470 </para>
 471 <para>
 472 This request is ignored if the client has not previously set the screen saver
 473 window attributes.
 474 </para>
 475 </sect1>
 476
 477 <sect1 id="Events">
 478 <title>Events</title>
 479 <para>
 480 The 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>
 495 This event is delivered to clients that have requested
 496 ScreenSaverNotify events using the <function>ScreenSaverSelectInput</function> request
 497 whenever the screen saver activates or deactivates.
 498 </para>
 499 <para>
 500 The <emphasis remap='I'>root</emphasis> field specifies root window of the screen for
 501 which the event was generated.  The <emphasis remap='I'>window</emphasis> field specifies
 502 the value that is returned by <function>ScreenSaverQueryInfo</function> as
 503 the identifier for the screen saver window.  This window is not
 504 required to exist if the external screen saver is not active.
 505 </para>
 506 <para>
 507 The <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>
 519 The screen saver deactivated; this event is sent if the client has set the
 520 ScreenSaverNotify bit in its event mask.
 521       </entry>
 522     </row>
 523     <row>
 524       <entry><emphasis role="bold">On</emphasis></entry>
 525       <entry>
 526 The screen saver activated.  This event is sent if the client has set the
 527 ScreenSaverNotify bit in its event mask.
 528       </entry>
 529     </row>
 530     <row>
 531       <entry><emphasis role="bold">Cycle</emphasis></entry>
 532       <entry>
 533 The cycle interval passed and the client is expected to change the image on
 534 the screen.  This event is sent if the client has set the
 535 ScreenSaverCycle bit in its event mask.
 536       </entry>
 537     </row>
 538   </tbody>
 539   </tgroup>
 540 </informaltable>
 541
 542 <para>
 543 If <emphasis remap='I'>state</emphasis> is set to
 544 <emphasis role="bold">On </emphasis> or
 545 <emphasis role="bold">Off</emphasis>
 546 then <emphasis remap='I'>forced</emphasis> indicates whether or not
 547 activation or deactivation was caused by a core
 548 <function>ForceScreenSaver</function>
 549 request; otherwise, <emphasis remap='I'>forced</emphasis> is set to False.
 550 </para>
 551
 552 <para>
 553 The <emphasis remap='I'>kind</emphasis> field specifies mechanism that was used to save the screen
 554 when the screen saver was activated, as described in
 555 <function>ScreenSaverQueryInfo</function>.
 556 </para>
 557
 558 <para>
 559 The <emphasis remap='I'>time</emphasis> field indicates the server time
 560 when the event was generated.
 561 </para>
 562 </sect1>
 563 </chapter>
 564
 565 <chapter id="Encoding">
 566 <title>Encoding</title>
 567 <para>
 568 Please refer to the X11 Protocol Encoding document as this document uses
 569 conventions established there.
 570 </para>
 571 <para>
 572 The name of this extension is "SCREEN-SAVER".
 573 </para>
 574
 575 <sect1 id="Common_Types">
 576 <title>Common Types</title>
 577 <literallayout class="monospaced">
 578 SETofSCREENSAVEREVENT
 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>
 588 1     CARD8                   screen saver opcode
 589 1     0                       minor opcode
 590 2     2                       request length
 591 1     CARD8                   client major version
 592 1     CARD8                   client minor version
 593 2                             unused
 594 ->
 595 1     1                       Reply
 596 1                             unused
 597 2     CARD16                  sequence number
 598 4     0                       reply length
 599 1     CARD8                   server major version
 600 1     CARD8                   server minor version
 601 22                            unused
 602
 603 <emphasis role="bold">ScreenSaverQueryInfo</emphasis>
 604 1     CARD8                   screen saver opcode
 605 1     1                       minor opcode
 606 2     2                       request length
 607 4     DRAWABLE                drawable associated with screen
 608 ->
 609 1     1                       Reply
 610 1     CARD8                   state
 611       0          Off
 612       1          On
 613       3          Disabled
 614 2     CARD16                  sequence number
 615 4     0                       reply length
 616 4     WINDOW                  saver window
 617 4     CARD32                  milliseconds until saver or since saver
 618 4     CARD32                  milliseconds since last user device input
 619 4     SETofSCREENSAVEREVENT   event mask
 620 1     CARD8                   kind
 621       0          Blanked
 622       1          Internal
 623       2          External
 624 10               unused
 625
 626 <emphasis role="bold">ScreenSaverSelectInput</emphasis>
 627 1     CARD8                   screen saver opcode
 628 1     2                       minor opcode
 629 2     3                       request length
 630 4     DRAWABLE                drawable associated with screen
 631 4     SETofSCREENSAVEREVENT   event mask
 632
 633 <emphasis role="bold">ScreenSaverSetAttributes</emphasis>
 634 1     CARD8                   screen saver opcode
 635 1     3                       minor opcode
 636 2     6+n                     request length
 637 4     DRAWABLE                drawable associated with screen
 638 2     INT16                   x
 639 2     INT16                   y
 640 2     CARD16                  width
 641 2     CARD16                  height
 642 2     CARD16                  border-width
 643 1                             class
 644       0          CopyFromParent
 645       1          InputOutput
 646       2          InputOnly
 647 1     CARD8                   depth
 648 4     VISUALID                visual
 649       0          CopyFromParent
 650 4     BITMASK                 value-mask (has n bits set to 1)
 651       encodings are the same as for core CreateWindow
 652 4n    LISTofVALUE             value-list
 653       encodings are the same as for core CreateWindow
 654
 655 <emphasis role="bold">ScreenSaverUnsetAttributes</emphasis>
 656 1     CARD8                   screen saver opcode
 657 1     4                       minor opcode
 658 2     3                       request length
 659 4     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>
 668 1     CARD8                   code assigned by core
 669 1     CARD8                   state
 670       0          Off
 671       1          On
 672       2          Cycle
 673 2     CARD16                  sequence number
 674 4     TIMESTAMP               time
 675 4     WINDOW                  root
 676 4     WINDOW                  screen saver window
 677 1     CARD8                   kind
 678       0          Blanked
 679       1          Internal
 680       2          External
 681 1     BOOL                    forced
 682 14                            unused
 683 </literallayout>
 684 </sect1>
 685 </chapter>
 686
 687 <chapter id='Inter_Client_Communications_Conventions'>
 688 <title>Inter-Client Communications Conventions</title>
 689 <para>
 690 Screen saver clients should create at least one resource value whose
 691 identifier can be stored in a property named
 692 <emphasis role="bold">_SCREEN_SAVER_ID</emphasis>
 693 on the root of each screen it is managing.
 694 This property should have one 32-bit value corresponding to the resource
 695 identifier; the type of the property should indicate the type of the
 696 resource 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>
 709 The C binding for this extension simply provide access to the protocol; they
 710 add no semantics beyond what is described above.
 711 </para>
 712
 713 <para>
 714 The 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>
 729 This routine returns
 730 <emphasis role="bold">True</emphasis>
 731 if the specified <emphasis remap='I'>display</emphasis> supports the
 732 SCREEN-SAVER extension; otherwise it returns
 733 <emphasis role="bold">False</emphasis>.
 734 If the extension is supported, the event number for
 735 <function>ScreenSaverNotify</function>
 736 events is returned in the value pointed to by
 737 <emphasis remap='I'>event_base</emphasis>.  Since
 738 no additional errors are defined by this extension, the results
 739 of <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>
 752 If the specified <emphasis remap='I'>display</emphasis> supports the
 753 extension, the version numbers of the protocol
 754 expected by the server are returned in
 755 <emphasis remap='I'>major</emphasis> and
 756 <emphasis remap='I'>minor</emphasis> and
 757 a non-zero value is returned.  Otherwise, the arguments are not
 758 set and 0 is returned.
 759 </para>
 760
 761 <para>XScreenSaverInfo *</para>
 762 <para>XScreenSaverAllocInfo()</para>
 763
 764 <para>
 765 This routine allocates and returns an
 766 <emphasis role="bold">XScreenSaverInfo</emphasis> structure
 767 for use in calls to <xref linkend='XScreenSaverQueryInfo' xrefstyle='select: title'/>.
 768 All fields in the
 769 structure are initialized to zero.  If insufficient memory is available,
 770 NULL is returned.  The results of this routine can be released
 771 using <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>
 784 If the specified <emphasis remap='I'>display</emphasis> supports the extension,
 785 information about the current state of the
 786 screen server is returned in <emphasis remap='I'>saver_info</emphasis> and a non-zero value is
 787 returned.  The <function>XScreenSaverInfo</function> structure is
 788 defined as follows:
 789 </para>
 790
 791 <literallayout class="monospaced">
 792 typedef 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>
 803 See the <function>ScreenSaverQueryInfo</function> request for a
 804 description of the fields.  If the extension is not supported,
 805 <emphasis remap='I'>saver_info</emphasis> is not changed and 0
 806 is 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>
 819 If the specified <emphasis remap='I'>display</emphasis> supports the extension,
 820 this routine asks that events related to
 821 the screen saver be generated for this client.
 822 The format of the events generated is:
 823 </para>
 824
 825 <literallayout class="monospaced">
 826 typedef 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>
 841 See the definition of the
 842 <function>ScreenSaverSelectInput</function> request for descriptions
 843 of 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>
 865 If the specified <emphasis remap='I'>display</emphasis> supports the
 866 extension, this routine sets the attributes to be used
 867 the next time the external screen saver is activated.  See the definition
 868 of the <function>ScreenSaverSetAttributes</function> request for a
 869 description 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>
 881 If the specified <emphasis remap='I'>display</emphasis> supports the
 882 extension, this routine instructs the server to discard
 883 any 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>
 897 This 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
 901 is encountered and the property is not changed, otherwise it returns
 902 non-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>
 914 This routine removes any <function>_SCREEN_SAVER_ID</function> from the
 915 root window of the specified <emphasis remap='I'>screen</emphasis>.
 916 It returns zero if an error is encountered and the property is changed,
 917 otherwise 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>
 932 This 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
 936 root window of the specified <emphasis remap='I'>screen</emphasis>.
 937 It returns zero if an error
 938 is encountered or if the property does not exist or is not of the correct
 939 format; otherwise it returns non-zero.
 940 </para>
 941
 942 </chapter>
 943 </book>