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 referred 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 controllable. 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 addition to the common 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 interpreted: 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"><X11/extensions/scrnsaver.h></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 from 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> 944