PageRenderTime 58ms CodeModel.GetById 27ms RepoModel.GetById 0ms app.codeStats 0ms

/specs/saver.xml

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