home *** CD-ROM | disk | FTP | other *** search
/ InfoMagic Source Code 1993 July / THE_SOURCE_CODE_CD_ROM.iso / X / mit / doc / ICCCM / icccm.ms next >
Encoding:
Text File  |  1991-07-28  |  155.0 KB  |  5,038 lines
  1. .\" Use tbl, eqn, -ms, and macros.t
  2. .EH ''''
  3. .OH ''''
  4. .EF ''''
  5. .OF ''''
  6. .ps 11
  7. .nr PS 11
  8. \&
  9. .sp 8
  10. .ce 4
  11. \s+2\fBInter-Client Communication Conventions Manual\fP\s-2
  12.  
  13. \fBVersion 1.1\fP
  14.  
  15. \fBMIT X Consortium Standard\fP
  16.  
  17. \fBX Version 11, Release 5\fP
  18. .sp 6
  19. .ce 2
  20. \s+1David Rosenthal\s-1
  21. .sp 6p
  22. \s+1Sun Microsystems, Inc.\s-1
  23. .bp
  24. \&
  25. .ps 9
  26. .nr PS 9
  27. .sp 8
  28. .LP
  29. X Window System is a trademark of M.I.T.
  30. .LP             
  31. .LP
  32. Copyright \(co 1988, 1991
  33. Massachusetts Institute of Technology, 
  34. Cambridge, MA USA.
  35. .LP
  36. Copyright \(co 1987, 1988, 1989 
  37. Sun Microsystems, Inc
  38. .LP 
  39. Permission to use, copy, modify, and distribute this documentation 
  40. for any purpose and without fee is hereby granted, provided 
  41. that the above copyright notice and this permission 
  42. notice appear in all copies.
  43. MIT and Sun Microsystems make no representations about the 
  44. suitability for any purpose of the information in this document. 
  45. This documentation is provided as is without express or implied warranty. 
  46. .ps 11
  47. .nr PS 11
  48. .bp
  49. .XS iii
  50. Acknowledgments
  51. .XE
  52. \&
  53. .sp 1
  54. .ce 3
  55. \s+1\fBAcknowledgments\fP\s-1
  56. .sp 2
  57. .na
  58. .LP
  59. David Rosenthal had overall architectural responsibility 
  60. for the conventions defined in this document;
  61. he wrote most of the text and edited the document, 
  62. but its the development has been a communal effort.
  63. The details were thrashed out in meetings at the January 1988 MIT X Conference
  64. and at the 1988 Summer Usenix conference,
  65. and through months (and megabytes) of argument
  66. on the
  67. .PN wmtalk
  68. mail alias.
  69. Thanks are due to everyone who contributed,
  70. and especially to the following people.
  71. .LP
  72. For the Selection section:
  73. .LP
  74. .Ds
  75. Jerry Farrell
  76. Phil Karlton
  77. Loretta Guarino Reid
  78. Mark Manasse
  79. Bob Scheifler
  80. .De
  81. .LP
  82. For the Cut-Buffer section:
  83. .LP
  84. .Ds
  85. Andrew Palay.
  86. .De
  87. .LP
  88. For the Window and Session Manager sections:
  89. .LP
  90. .Ds
  91. Todd Brunhoff
  92. Ellis Cohen
  93. Jim Fulton
  94. Hania Gajewska
  95. Jordan Hubbard
  96. Kerry Kimbrough
  97. Audrey Ishizaki
  98. Matt Landau
  99. Mark Manasse
  100. Bob Scheifler
  101. Ralph Swick
  102. Mike Wexler
  103. Glenn Widener
  104. .De
  105. .LP
  106. For the Device Color Characterization section:
  107. .Ds
  108. Keith Packard.
  109. .De
  110. .LP
  111. In addition, thanks are due to those who contributed to the public review:
  112. .LP
  113. .Ds
  114. Gary Combs
  115. Errol Crary
  116. Nancy Cyprych
  117. John Diamant
  118. Clive Feather
  119. Burns Fisher
  120. Richard Greco
  121. Tim Greenwood
  122. Kee Hinckley
  123. Brian Holt
  124. John Interrante
  125. John Irwin
  126. Vania Joloboff
  127. John Laporta
  128. Ken Lee
  129. Stuart Marks
  130. Allan Mimms
  131. Colas Nahaboo
  132. Mark Patrick
  133. Steve Pitschke
  134. Brad Reed
  135. John Thomas
  136. .De
  137. .bp 5
  138. .EH '\fBInter-Client Communication Conventions\fP''\fBX11, Release 5'
  139. .OH '\fBInter-Client Communication Conventions\fP''\fBX11, Release 5'
  140. .EF ''\fB % \fP''
  141. .OF ''\fB % \fP''
  142. .NH 1
  143. Introduction
  144. .XS
  145. \*(SN Introduction
  146. .XE
  147. .LP
  148. It was an explicit design goal of X Version 11 to specify mechanism,
  149. not policy.
  150. As a result,  
  151. a client that converses with the server using the protocol defined 
  152. by the \fIX Window System Protocol\fP, \fIVersion 11\fP may operate correctly 
  153. in isolation but may not coexist properly with others sharing the same server.
  154. .LP
  155. Being a good citizen in the X Version 11 world involves adhering to
  156. conventions that govern inter-client communications in the following areas:
  157. .IP \(bu 5
  158. Selection mechanism
  159. .IP \(bu 5
  160. Cut buffers
  161. .IP \(bu 5
  162. Window manager
  163. .IP \(bu 5
  164. Session manager
  165. .IP \(bu 5
  166. Manipulation of shared resources
  167. .IP \(bu 5
  168. Device color characterization
  169. .LP
  170. This document proposes suitable conventions without attempting to enforce 
  171. any particular user interface.
  172. To permit clients written in different languages to communicate,
  173. these conventions are expressed solely in terms of protocol operations,
  174. not in terms of their associated Xlib interfaces,
  175. which are probably more familiar.
  176. The binding of these operations to the Xlib interface for C
  177. and to the equivalent interfaces for other languages
  178. is the subject of other documents.
  179. .NH 2
  180. Evolution of the Conventions
  181. .XS
  182. \*(SN Evolution of the Conventions
  183. .XE
  184. .LP
  185. In the interests of timely acceptance,
  186. the \fIInter-Client Communication Conventions Manual\fP (ICCCM)
  187. covers only a minimal set of required conventions.
  188. These conventions will be added to and updated as appropriate,
  189. based on the experiences of the X Consortium.
  190. .LP
  191. As far as possible,
  192. these conventions are upwardly compatible with those in the February 25, 1988,
  193. draft that was distributed with the X Version 11, Release 2 of the software.
  194. In some areas,
  195. semantic problems were discovered with those conventions,
  196. and, thus, complete upward compatibility could not be assured.
  197. These areas are noted in the text and are summarized in Appendix A.
  198. .LP
  199. In the course of developing these conventions,
  200. a number of minor changes to the protocol were identified as desirable.
  201. They also are identified in the text, are summarized in Appendix B,
  202. and are offered as input to a future protocol revision process.
  203. If and when a protocol revision incorporating these changes is undertaken,
  204. it is anticipated that the ICCCM will need to be revised.
  205. Because it is difficult to ensure that clients and servers are upgraded
  206. simultaneously, 
  207. clients using the revised conventions should examine the minor protocol 
  208. revision number and be prepared to use the older conventions 
  209. when communicating with an older server.
  210. .LP
  211. It is expected that these revisions will ensure that clients using 
  212. the conventions appropriate to protocol minor revision \fIn\fP 
  213. will interoperate correctly with those that use the conventions 
  214. appropriate to protocol minor revision \fIn\fP+1 if the server supports both.
  215. .NH 2
  216. Atoms
  217. .XS
  218. \*(SN Atoms
  219. .XE
  220. .LP
  221. Many of the conventions use atoms.
  222. To assist the reader,
  223. the following sections attempt to amplify the description of atoms 
  224. that is provided in the protocol specification.
  225. .NH 3
  226. What Are Atoms?
  227. .XS
  228. \*(SN What Are Atoms?
  229. .XE
  230. .LP
  231. At the conceptual level, 
  232. atoms are unique names that clients can use to communicate information 
  233. to each other.
  234. They can be thought of as a bundle of octets,
  235. like a string but without an encoding being specified.
  236. The elements are not necessarily ASCII characters,
  237. and no case folding happens.\s-2\u1\d\s0
  238. .FS
  239. 1.  The comment in the protocol specification for 
  240. .PN InternAtom 
  241. that ISO Latin-1 encoding should be used is in the nature of a convention;
  242. the server treats the string as a byte sequence.
  243. .FE
  244. .LP
  245. The protocol designers felt that passing these
  246. sequences of bytes back and forth across the wire would be too costly.
  247. Further, they thought it important that events 
  248. as they appear ``on the wire'' have a fixed size (in fact, 32 bytes)
  249. and that because some events contain atoms, a fixed-size representation 
  250. for them was needed.
  251. .LP
  252. To allow a fixed-size representation,
  253. a protocol request 
  254. .Pn ( InternAtom )
  255. was provided to register a byte sequence with the server,
  256. which returns a 32-bit value (with the top three bits zero) 
  257. that maps to the byte sequence.
  258. The inverse operator is also available 
  259. .Pn ( GetAtomName ).
  260. .NH 3
  261. Predefined Atoms
  262. .XS
  263. \*(SN Predefined Atoms
  264. .XE
  265. .LP
  266. The protocol specifies a number of atoms as being predefined:
  267. .QP
  268. Predefined atoms are not strictly necessary
  269. and may not be useful in all environments,
  270. but they will eliminate many 
  271. .PN InternAtom
  272. requests in most applications.
  273. Note that they are predefined only in the sense of having numeric values, 
  274. not in the sense of having required semantics.
  275. .LP
  276. Predefined atoms are an implementation trick to avoid the cost of interning
  277. many of the atoms that are expected to be used during the startup phase 
  278. of all applications.
  279. The results of the 
  280. .PN InternAtom 
  281. requests, which require a handshake, can be assumed \fIa priori\fP.
  282. .LP
  283. Language interfaces should probably cache the atom-name mappings 
  284. and get them only when required.
  285. The CLX interface, for instance, makes no distinction between predefined atoms
  286. and other atoms; all atoms are viewed as symbols at the interface.
  287. However, a CLX implementation will typically keep a symbol or atom cache 
  288. and will typically initialize this cache with the predefined atoms.
  289. .NH 3
  290. Naming Conventions
  291. .XS
  292. \*(SN Naming Conventions
  293. .XE
  294. .LP
  295. The built-in atoms are composed of uppercase ASCII characters with the
  296. logical words separated by an underscore character (_), for example,  
  297. WM_ICON_NAME.
  298. The protocol specification recommends that atoms used 
  299. for private vendor-specific reasons should begin with an underscore.
  300. To prevent conflicts among organizations, 
  301. additional prefixes should be chosen 
  302. (for example,  _DEC_WM_DECORATION_GEOMETRY).
  303. .LP
  304. The names were chosen in this fashion to make it easy to use them in a
  305. natural way within LISP.
  306. Keyword constructors allow the programmer to specify the atoms as LISP atoms.
  307. If the atoms were not all uppercase,
  308. special quoting conventions would have to be used.
  309. .NH 3
  310. Semantics
  311. .XS
  312. \*(SN Semantics
  313. .XE
  314. .LP
  315. The core protocol imposes no semantics on atoms except as they are used in
  316. FONTPROP structures.
  317. For further information on FONTPROP semantics,
  318. see the \fIX Logical Font Description Conventions\fP.
  319. .NH 3
  320. Name Spaces
  321. .XS
  322. \*(SN Name Spaces
  323. .XE
  324. .LP
  325. The protocol defines six distinct spaces in which atoms are interpreted.
  326. Any particular atom may or may not have some valid interpretation
  327. with respect to each of these name spaces.
  328. .TS
  329. l l l.
  330. _
  331. .sp 6p
  332. .B
  333. Space    Briefly    Examples
  334. .sp 6p
  335. _
  336. .sp 6p
  337. .TH
  338. .R
  339. Property name    Name    (WM_HINTS, WM_NAME, RGB_BEST_MAP, and so on)
  340. Property type    Type    (WM_HINTS, CURSOR, RGB_COLOR_MAP, and so on)
  341. Selection name    Selection    (PRIMARY, SECONDARY, CLIPBOARD)
  342. Selection target    Target    (FILE_NAME, POSTSCRIPT, PIXMAP, and so on)
  343. Font property        (QUAD_WIDTH, POINT_SIZE, and so on)
  344. T{
  345. .PN ClientMessage
  346. type
  347. T}    T{
  348. T}    T{
  349. (WM_SAVE_YOURSELF, _DEC_SAVE_EDITS, and so on)
  350. T}
  351. .sp 6p
  352. _
  353. .TE
  354. .NH 1
  355. Peer-to-Peer Communication by Means of Selections
  356. .XS
  357. \*(SN Peer-to-Peer Communication by Means of Selections
  358. .XE
  359. .LP
  360. Selections are the primary mechanism that X Version 11 defines 
  361. for the exchange of information between clients,
  362. for example, by cutting and pasting between windows.
  363. Note that there can be an arbitrary number of selections
  364. (each named by an atom) and that they are global to the server.
  365. Section 2.6 discusses the choice of an atom.
  366. Each selection is owned by a client and is attached to a window.
  367. .LP
  368. Selections communicate between an owner and a requestor.
  369. The owner has the data representing the value of its selection,
  370. and the requestor receives it.
  371. A requestor wishing to obtain the value of a selection provides the following:
  372. .IP \(bu 5
  373. The name of the selection
  374. .IP \(bu 5
  375. The name of a property
  376. .IP \(bu 5
  377. A window
  378. .IP \(bu 5
  379. The atom representing the data type required
  380. .LP
  381. If the selection is currently owned,
  382. the owner receives an event and is expected to do the following:
  383. .IP \(bu 5
  384. Convert the contents of the selection to the requested data type
  385. .IP \(bu 5
  386. Place this data in the named property on the named window
  387. .IP \(bu 5
  388. Send the requestor an event to let it know the property is available
  389. .LP
  390. Clients are strongly encouraged to use this mechanism.
  391. In particular,
  392. displaying text in a permanent window without providing the ability 
  393. to select and convert it into a string is definitely considered antisocial.
  394. .LP
  395. Note that all data transferred between an owner and a requestor must usually 
  396. go by means of the server in an X Version 11 environment.
  397. A client cannot assume that another client can open the same files
  398. or even communicate directly.
  399. The other client may be talking to the server by means of 
  400. a completely different networking mechanism (for example,  one client might
  401. be DECnet and the other TCP/IP).
  402. Thus, passing indirect references to data 
  403. (such as file names,  host names and port numbers, and so on) 
  404. is permitted only if both clients specifically agree.
  405. .NH 2
  406. Acquiring Selection Ownership
  407. .XS
  408. \*(SN Acquiring Selection Ownership
  409. .XE
  410. .LP
  411. A client wishing to acquire ownership of a particular selection
  412. should call 
  413. .PN SetSelectionOwner,
  414. which is defined as follows:
  415. .LP
  416. .\" Start marker code here
  417. .IN "SetSelectionOwner" "" "@DEF@"
  418. .PN SetSelectionOwner
  419. .in +.2i
  420. .LP
  421. \fIselection\fP\^: ATOM
  422. .br
  423. \fIowner\fP\^: WINDOW or
  424. .PN None
  425. .br
  426. \fItime\fP\^: TIMESTAMP or
  427. .PN CurrentTime
  428. .in -.2i
  429. .\" End marker code here
  430. .LP
  431. The client should set the specified selection to the atom that represents 
  432. the selection,
  433. set the specified owner to some window that the client created,
  434. and set the specified time to some time between the current last-change time 
  435. of the selection concerned and the current server time.
  436. This time value usually will be obtained from the timestamp of the event 
  437. that triggers the acquisition of the selection.
  438. Clients should not set the time
  439. value to 
  440. .PN CurrentTime ,
  441. because if they do so, they have no way of finding
  442. when they gained ownership of the selection.
  443. Clients must use a window they created so that requestors
  444. can route events to the owner of the selection.\s-2\u2\d\s0
  445. .FS
  446. 2.  At present, no part of the protocol requires requestors
  447. to send events to the owner of a selection.
  448. This restriction is imposed to prepare for possible future extensions.
  449. .FE
  450. .NT Convention
  451. Clients attempting to acquire a selection must set the time value of the 
  452. .PN SetSelectionOwner 
  453. request to the timestamp of the event triggering the acquisition attempt, 
  454. not to 
  455. .PN CurrentTime .
  456. A zero-length append to a property is a way to obtain a timestamp for
  457. this purpose;
  458. the timestamp is in the corresponding 
  459. .PN PropertyNotify
  460. event.
  461. .NE
  462. .LP
  463. If the time in the 
  464. .PN SetSelectionOwner 
  465. request is in the future relative to the server's current time 
  466. or is in the past relative to the last time the specified selection 
  467. changed hands, the 
  468. .PN SetSelectionOwner
  469. request appears to the client to succeed,
  470. but ownership is not actually transferred.
  471. .LP
  472. Because clients cannot name other clients directly,
  473. the specified owner window is used to refer to the owning client
  474. in the replies to 
  475. .PN GetSelectionOwner ,
  476. in 
  477. .PN SelectionRequest 
  478. and
  479. .PN SelectionClear
  480. events, and possibly as a place to put properties describing the selection
  481. in question.
  482. To discover the owner of a particular selection,
  483. a client should invoke
  484. .PN GetSelectionOwner ,
  485. which is defined as follows:
  486. .LP
  487. .\" Start marker code here
  488. .IN "GetSelectionOwner" "" "@DEF@"
  489. .PN GetSelectionOwner
  490. .in +.2i
  491. .LP
  492. \fIselection\fP\^: ATOM
  493. .in -.2i
  494. .LP
  495.    =>
  496. .in +.2i
  497. .LP
  498. owner: WINDOW or
  499. .PN None
  500. .in -.2i
  501. .\" End marker code here
  502. .NT Convention
  503. Clients are expected to provide some visible confirmation
  504. of selection ownership.
  505. To make this feedback reliable,
  506. a client must perform a sequence like the following:
  507. .sp
  508. .Ds 0
  509. SetSelectionOwner(selection=PRIMARY, owner=Window, time=timestamp)
  510. owner = GetSelectionOwner(selection=PRIMARY)
  511. if (owner != Window) Failure
  512. .De
  513. .NE
  514. .LP
  515. If the 
  516. .PN SetSelectionOwner
  517. request succeeds (not merely appears to succeed),
  518. the client that issues it is recorded by the server as being the owner 
  519. of the selection for the time period starting at the specified time.
  520. .NT Problem
  521. There is no way for anyone to find out the last-change time of
  522. a selection.
  523. At the next protocol revision,  
  524. .PN GetSelectionOwner
  525. should be changed to return the last-change time as well as the owner.
  526. .NE
  527. .NH 2
  528. Responsibilities of the Selection Owner
  529. .XS
  530. \*(SN Responsibilities of the Selection Owner
  531. .XE
  532. .LP
  533. When a requestor wants the value of a selection,
  534. the owner receives a 
  535. .PN SelectionRequest
  536. event, which is defined as follows:
  537. .LP
  538. .\" Start marker code here
  539. .IN "SelectionRequest" "" "@DEF@"
  540. .PN SelectionRequest
  541. .in +.2i
  542. .LP
  543. \fIowner\fP\^: WINDOW
  544. .br
  545. \fIselection\fP\^: ATOM
  546. .br
  547. \fItarget\fP\^: ATOM
  548. .br
  549. \fIproperty\fP\^: ATOM or
  550. .PN None
  551. .br
  552. \fIrequestor\fP\^: WINDOW
  553. .br
  554. \fItime\fP\^: TIMESTAMP or
  555. .PN CurrentTime
  556. .in -.2i
  557. .\" End marker coder here
  558. .LP
  559. The specified owner and selection will be the values that were specified in the 
  560. .PN SetSelectionOwner 
  561. request.
  562. The owner should compare the timestamp with the period 
  563. it has owned the selection and, if the time is outside,
  564. refuse the 
  565. .PN SelectionRequest 
  566. by sending the requestor window a 
  567. .PN SelectionNotify 
  568. event with the property set to 
  569. .PN None 
  570. (by means of a
  571. .PN SendEvent
  572. request with an empty event mask).
  573. .LP
  574. More advanced selection owners are free to maintain a history
  575. of the value of the selection and to respond to requests for the
  576. value of the selection during periods they owned it
  577. even though they do not own it now.
  578. .LP
  579. If the specified property is 
  580. .PN None ,
  581. the requestor is an obsolete client.
  582. Owners are encouraged to support these clients by using the specified target
  583. atom as the property name to be used for the reply.
  584. .LP
  585. Otherwise,
  586. the owner should use the target to decide the form into which the selection
  587. should be converted.
  588. If the selection cannot be converted into that form, however,
  589. the owner should refuse the 
  590. .PN SelectionRequest ,
  591. as previously described.
  592. .LP
  593. If the specified property is not 
  594. .PN None ,
  595. the owner should place the data resulting from converting the selection 
  596. into the specified property on the requestor window
  597. and should set the property's type to some appropriate value,
  598. which need not be the same as the specified target.
  599. .NT Convention
  600. All properties used to reply to 
  601. .PN SelectionRequest
  602. events must be placed on the requestor window.
  603. .NE
  604. .LP
  605. In either case, 
  606. if the data comprising the selection cannot be stored on the requestor window 
  607. (for example, because the server cannot provide sufficient memory),
  608. the owner must refuse the 
  609. .PN SelectionRequest ,
  610. as previously described.
  611. See also section 2.5.
  612. .LP
  613. If the property is successfully stored,
  614. the owner should acknowledge the successful conversion
  615. by sending the requestor window a 
  616. .PN SelectionNotify 
  617. event (by means of a
  618. .PN SendEvent
  619. request with an empty mask).
  620. .PN SelectionNotify
  621. is defined as follows:
  622. .LP
  623. .\" Start marker code here
  624. .IN "SelectionNotify" "" "@DEF@"
  625. .PN SelectionNotify
  626. .in +.2i
  627. .LP
  628. \fIrequestor\fP\^: WINDOW
  629. .br
  630. \fIselection\fP, \fItarget\fP\^: ATOM
  631. .br
  632. \fIproperty\fP\^: ATOM or
  633. .PN None
  634. .br
  635. \fItime\fP\^: TIMESTAMP or
  636. .PN CurrentTime
  637. .in -.2i
  638. .\" End marker code here
  639. .LP
  640. The owner should set the specified selection, target, time, 
  641. and property arguments to the values received in the 
  642. .PN SelectionRequest 
  643. event.
  644. (Note that setting the property argument to 
  645. .PN None 
  646. indicates that the conversion requested could not be made.)
  647. .NT Convention
  648. The selection, target, time, and property arguments in the 
  649. .PN SelectionNotify 
  650. event should be set to the values received in the 
  651. .PN SelectionRequest 
  652. event.
  653. .NE
  654. .LP
  655. The data stored in the property must eventually be deleted.
  656. A convention is needed to assign the responsibility for doing so.
  657. .NT Convention
  658. Selection requestors are responsible for deleting properties whose
  659. names they receive in 
  660. .PN SelectionNotify 
  661. events (see section 2.4) or in properties with type MULTIPLE.
  662. .NE
  663. .LP
  664. A selection owner will often need confirmation that the data comprising the
  665. selection has actually been transferred.
  666. (For example, 
  667. if the operation has side effects on the owner's internal data structures, 
  668. these should not take place until the requestor has indicated 
  669. that it has successfully received the data.)
  670. Owners should express interest in 
  671. .PN PropertyNotify 
  672. events for the specified requestor window 
  673. and wait until the property in the 
  674. .PN SelectionNotify 
  675. event has been deleted before assuming that the selection data 
  676. has been transferred.
  677. .LP
  678. When some other client acquires a selection,
  679. the previous owner receives a 
  680. .PN SelectionClear 
  681. event, which is defined as follows:
  682. .LP
  683. .\" Start marker code here
  684. .IN "SelectionClear" "" "@DEF@"
  685. .PN SelectionClear
  686. .in +.2i
  687. .LP
  688. \fIowner\fP\^: WINDOW
  689. .br
  690. \fIselection\fP\^: ATOM
  691. .br
  692. \fItime\fP\^: TIMESTAMP
  693. .in -.2i
  694. .\" End marker code here
  695. .LP
  696. The timestamp argument is the time at which the ownership changed hands,
  697. and the owner argument is the window the previous owner specified in its
  698. .PN SetSelectionOwner 
  699. request.
  700. .LP
  701. If an owner loses ownership while it has a transfer in progress (that is,
  702. before it receives notification that the requestor has received all the data),
  703. it must continue to service the ongoing transfer until it is complete.
  704. .NH 2
  705. Giving Up Selection Ownership
  706. .XS
  707. \*(SN Giving Up Selection Ownership
  708. .XE
  709. .LP
  710. Clients may either give up selection ownership voluntarily 
  711. or lose it forcibly as the result of some other client's actions.
  712. .NH 3
  713. Voluntarily Giving Up Selection Ownership
  714. .XS
  715. \*(SN Voluntarily Giving Up Selection Ownership
  716. .XE
  717. .LP
  718. To relinquish ownership of a selection voluntarily,
  719. a client should execute a 
  720. .PN SetSelectionOwner 
  721. request for that selection atom, with owner specified as 
  722. .PN None
  723. and the time specified as the timestamp that was used to acquire the selection.
  724. .LP
  725. Alternatively,
  726. the client may destroy the window used as the owner value of the 
  727. .PN SetSelectionOwner 
  728. request, or the client may terminate.
  729. In both cases,
  730. the ownership of the selection involved will revert to 
  731. .PN None .
  732. .NH 3
  733. Forcibly Giving Up Selection Ownership
  734. .XS
  735. \*(SN Forcibly Giving Up Selection Ownership
  736. .XE
  737. .LP
  738. If a client gives up ownership of a selection
  739. or if some other client executes a 
  740. .PN SetSelectionOwner 
  741. for it and thus reassigns it forcibly,
  742. the previous owner will receive a 
  743. .PN SelectionClear 
  744. event.
  745. For the definition of a 
  746. .PN SelectionClear
  747. event, see section 2.2.
  748. .LP
  749. The timestamp is the time the selection changed hands.
  750. The specified owner is the window that was specified by the current owner 
  751. in its 
  752. .PN SetSelectionOwner
  753. request.
  754. .NH 2
  755. Requesting a Selection
  756. .XS
  757. \*(SN Requesting a Selection
  758. .XE
  759. .LP
  760. A client that wishes to obtain the value of a selection in a particular
  761. form (the requestor) issues a 
  762. .PN ConvertSelection 
  763. request, which is defined as follows:
  764. .LP
  765. .\" Start marker code here
  766. .IN "ConvertSelection" "" "@DEF@"
  767. .PN ConvertSelection
  768. .in +.2i
  769. .LP
  770. \fIselection\fP, \fItarget\fP\^: ATOM
  771. .br
  772. \fIproperty\fP\^: ATOM or
  773. .PN None
  774. .br
  775. \fIrequestor\fP\^: WINDOW
  776. .br
  777. \fItime\fP\^: TIMESTAMP or
  778. .PN CurrentTime
  779. .in -.2i
  780. .\" End marker code here
  781. .LP
  782. The selection argument specifies the particular selection involved,
  783. and the target argument specifies the required form of the information.
  784. For information about the choice of suitable atoms to use,
  785. see section 2.6.
  786. The requestor should set the requestor argument to a window that it created;
  787. the owner will place the reply property there.
  788. The requestor should set the time argument to the timestamp on the event 
  789. that triggered the request for the selection value.
  790. Note that clients should not specify 
  791. .PN CurrentTime .
  792. .NT Convention
  793. Clients should not use 
  794. .PN CurrentTime 
  795. for the time argument of a 
  796. .PN ConvertSelection
  797. request.
  798. Instead, they should use the timestamp of the event that caused the request 
  799. to be made.
  800. .NE
  801. .LP
  802. The requestor should set the property argument to the name of a property 
  803. that the owner can use to report the value of the selection.
  804. Note that the requestor of a selection need not know the client
  805. that owns the selection or the window it is attached to.
  806. .LP
  807. The protocol allows the property field to be set to 
  808. .PN None ,
  809. in which case the owner is supposed to choose a property name.
  810. However, it is difficult for the owner to make this choice safely.
  811. .NT Conventions
  812. .IP 1. 5
  813. Requestors should not use 
  814. .PN None
  815. for the property argument of a
  816. .PN ConvertSelection
  817. request.
  818. .IP 2. 5
  819. Owners receiving 
  820. .PN ConvertSelection 
  821. requests with a property argument of
  822. .PN None
  823. are talking to an obsolete client.
  824. They should choose the target atom as the property name to be used 
  825. for the reply.
  826. .NE
  827. .LP
  828. The result of the 
  829. .PN ConvertSelection
  830. request is that a 
  831. .PN SelectionNotify
  832. event will be received.
  833. For the definition of a
  834. .PN SelectionNotify
  835. event, see section 2.2.
  836. .LP
  837. The requestor, selection, time, and target arguments will be the same
  838. as those on the 
  839. .PN ConvertSelection 
  840. request.
  841. .LP
  842. If the property argument is 
  843. .PN None ,
  844. the conversion has been refused.
  845. This can mean either that there is no owner for the selection, 
  846. that the owner does not support the conversion implied by the target,
  847. or that the server did not have sufficient space to accommodate the data.
  848. .LP
  849. If the property argument is not 
  850. .PN None ,
  851. then that property will exist on the requestor window.
  852. The value of the selection can be retrieved from this
  853. property by using the 
  854. .PN GetProperty
  855. request, which is defined as follows:
  856. .LP
  857. .\" Start marker code here
  858. .IN "GetProperty" "" "@DEF@"
  859. .PN GetProperty
  860. .in +.2i
  861. .LP
  862. \fIwindow\fP\^: WINDOW
  863. .br
  864. \fIproperty\fP\^: ATOM
  865. .br
  866. \fItype\fP\^: ATOM or
  867. .PN AnyPropertyType
  868. .br
  869. \fIlong-offset\fP, \fIlong-length\fP\^: CARD32
  870. .br
  871. \fIdelete\fP\^: BOOL
  872. .in -.2i
  873. .LP
  874.    =>
  875. .in +.2i
  876. .LP
  877. type: ATOM or
  878. .PN None
  879. .br
  880. format: {0, 8, 16, 32}
  881. .br
  882. bytes-after: CARD32
  883. .br
  884. value: LISTofINT8 or LISTofINT16 or LISTofINT32
  885. .in -.2i
  886. .\" End marker code here
  887. .LP
  888. When using 
  889. .PN GetProperty 
  890. to retrieve the value of a selection,  
  891. the property argument should be set to the corresponding value in the 
  892. .PN SelectionNotify
  893. event.
  894. Because the requestor has no way of knowing beforehand what type 
  895. the selection owner will use,
  896. the type argument should be set to 
  897. .PN AnyPropertyType .
  898. Several 
  899. .PN GetProperty 
  900. requests may be needed to retrieve all the data in the selection;
  901. each should set the long-offset argument to the amount of data received so far,
  902. and the size argument to some reasonable buffer size (see section 2.5).
  903. If the returned value of bytes-after is zero,
  904. the whole property has been transferred.
  905. .LP
  906. Once all the data in the selection has been retrieved
  907. (which may require getting the values of several properties\-see section 2.7),
  908. the requestor should delete the property in the 
  909. .PN SelectionNotify
  910. request by using a 
  911. .PN GetProperty
  912. request with the delete argument set to
  913. .PN True .
  914. As previously discussed,
  915. the owner has no way of knowing when the data has been
  916. transferred to the requestor unless the property is removed.
  917. .NT Convention
  918. The requestor must delete the property named in the 
  919. .PN SelectionNotify
  920. once all the data has been retrieved.
  921. The requestor should invoke either 
  922. .PN DeleteProperty 
  923. or
  924. .PN GetProperty (delete==True)
  925. after it has successfully retrieved all the data in the selection.
  926. For further information,
  927. see section 2.5.
  928. .NE
  929. .NH 2
  930. Large Data Transfers
  931. .XS
  932. \*(SN Large Data Transfers
  933. .XE
  934. .LP
  935. Selections can get large, which poses two problems:
  936. .IP \(bu 5
  937. Transferring large amounts of data to the server is expensive.
  938. .IP \(bu 5
  939. All servers will have limits on the amount of data that can be stored
  940. in properties.
  941. Exceeding this limit will result in an 
  942. .PN Alloc
  943. error on the 
  944. .PN ChangeProperty 
  945. request that the selection owner uses to store the data.
  946. .LP
  947. The problem of limited server resources is addressed by the following
  948. conventions:
  949. .NT Conventions
  950. .IP 1. 5
  951. Selection owners should transfer the data describing a large selection
  952. (relative to the maximum-request-size they received 
  953. in the connection handshake) using the INCR property mechanism 
  954. (see section 2.7.2).
  955. .IP 2. 5
  956. Any client using 
  957. .PN SetSelectionOwner
  958. to acquire selection ownership should arrange to process 
  959. .PN Alloc
  960. errors in property change requests.
  961. For clients using Xlib,
  962. this involves using the
  963. .PN XSetErrorHandler
  964. function to override the default handler.
  965. .IP 3. 5
  966. A selection owner must confirm that no 
  967. .PN Alloc
  968. error occurred while storing the properties for a selection 
  969. before replying with a confirming 
  970. .PN SelectionNotify
  971. event.
  972. .IP 4. 5
  973. When storing large amounts of data (relative to maximum-request-size),
  974. clients should use a sequence of 
  975. .PN ChangeProperty (mode==Append)
  976. requests for reasonable quantities of data.
  977. This avoids locking servers up and limits the waste of data an
  978. .PN Alloc 
  979. error would cause.
  980. .IP 5. 5
  981. If an 
  982. .PN Alloc 
  983. error occurs during the storing of the selection data,
  984. all properties stored for this selection should be deleted
  985. and the 
  986. .PN ConvertSelection
  987. request should be refused (see section 2.2).
  988. .IP 6. 5
  989. To avoid locking servers up for inordinate lengths of time,
  990. requestors retrieving large quantities of data from a property
  991. should perform a series of 
  992. .PN GetProperty 
  993. requests, each asking for a reasonable amount of data.
  994. .NE
  995. .NT Problem
  996. Single-threaded servers should be changed to avoid locking up during large
  997. data transfers.
  998. .NE
  999. .NH 2
  1000. Use of Selection Atoms
  1001. .XS
  1002. \*(SN Use of Selection Atoms
  1003. .XE
  1004. .LP
  1005. Defining a new atom consumes resources in the server
  1006. that are not released until the server reinitializes.
  1007. Thus, reducing the need for newly minted atoms is an important goal
  1008. for the use of the selection atoms.
  1009. .NH 3
  1010. Selection Atoms
  1011. .XS
  1012. \*(SN Selection Atoms
  1013. .XE
  1014. .LP
  1015. There can be an arbitrary number of selections, each named by an atom.
  1016. To conform with the inter-client conventions, however,
  1017. clients need deal with only these three selections:
  1018. .IP \(bu 5
  1019. PRIMARY
  1020. .IP \(bu 5
  1021. SECONDARY
  1022. .IP \(bu 5
  1023. CLIPBOARD
  1024. .LP
  1025. Other selections may be used freely for private communication among
  1026. related groups of clients.
  1027. .NT Problem
  1028. How does a client find out which selection atoms are valid?
  1029. .NE
  1030. .NH 4
  1031. The PRIMARY Selection
  1032. .XS
  1033. \*(SN The PRIMARY Selection
  1034. .XE
  1035. .LP
  1036. The selection named by the atom PRIMARY is used for all commands
  1037. that take only a single argument and is the principal means of communication 
  1038. between clients that use the selection mechanism.
  1039. .NH 4
  1040. The SECONDARY Selection
  1041. .XS
  1042. \*(SN The SECONDARY Selection
  1043. .XE
  1044. .LP
  1045. The selection named by the atom SECONDARY is used:
  1046. .IP \(bu 5
  1047. As the second argument to commands taking two arguments 
  1048. (for example, ``exchange primary and secondary selections'')
  1049. .IP \(bu 5
  1050. As a means of obtaining data when there is a primary selection
  1051. and the user does not want to disturb it
  1052. .NH 4
  1053. The CLIPBOARD Selection
  1054. .XS
  1055. \*(SN The CLIPBOARD Selection
  1056. .XE
  1057. .LP
  1058. The selection named by the atom CLIPBOARD is used to hold data
  1059. that is being transferred between clients, 
  1060. that is, data that usually is being cut or copied, and then pasted.
  1061. Whenever a client wants to transfer data to the clipboard:
  1062. .IP \(bu 5
  1063. It should assert ownership of the CLIPBOARD.
  1064. .IP \(bu 5
  1065. If it succeeds in acquiring ownership,
  1066. it should be prepared to respond to a request for the contents of the CLIPBOARD
  1067. in the usual way (retaining the data to be able to return it).
  1068. The request may be generated by the clipboard client described below.
  1069. .IP \(bu 5
  1070. If it fails to acquire ownership,
  1071. a cutting client should not actually perform the cut or provide feedback 
  1072. that would suggest that it has actually transferred data to the clipboard.
  1073. .LP
  1074. The owner should repeat this process whenever the data to be transferred
  1075. would change.
  1076. .LP
  1077. Clients wanting to paste data from the clipboard should request 
  1078. the contents of the CLIPBOARD selection in the usual way.
  1079. .LP
  1080. Except while a client is actually deleting or copying data,
  1081. the owner of the CLIPBOARD selection may be a single, special client
  1082. implemented for the purpose.
  1083. This client maintains the content of the clipboard up-to-date
  1084. and responds to requests for data from the clipboard as follows:
  1085. .IP \(bu 5
  1086. It should assert ownership of the CLIPBOARD selection
  1087. and reassert it any time the clipboard data changes.
  1088. .IP \(bu 5
  1089. If it loses the selection (because another client has some new data 
  1090. for the clipboard),
  1091. it should:
  1092. .RS
  1093. .IP \- 5
  1094. Obtain the contents of the selection from the new owner by using the timestamp
  1095. in the 
  1096. .PN SelectionClear
  1097. event.
  1098. .IP \- 5
  1099. Attempt to reassert ownership of the CLIPBOARD selection 
  1100. by using the same timestamp.
  1101. .IP \- 5
  1102. Restart the process using a newly acquired timestamp if this attempt fails.
  1103. This timestamp should be obtained by asking the current owner of the
  1104. CLIPBOARD selection to convert it to a TIMESTAMP.
  1105. If this conversion is refused or if the same timestamp is received twice,
  1106. the clipboard client should acquire a fresh timestamp in the
  1107. usual way (for example by a zero-length append to a property).
  1108. .RE
  1109. .IP \(bu 5
  1110. It should respond to requests for the CLIPBOARD contents in the usual way.
  1111. .LP
  1112. A special CLIPBOARD client is not necessary.
  1113. The protocol used by the cutting client and the pasting client
  1114. is the same whether the CLIPBOARD client is running or not.
  1115. The reasons for running the special client include:
  1116. .IP \(bu 5
  1117. Stability \- If the cutting client were to crash or terminate,
  1118. the clipboard value would still be available.
  1119. .IP \(bu 5
  1120. Feedback \- The clipboard client can display the contents of the clipboard.
  1121. .IP \(bu 5
  1122. Simplicity \- A client deleting data does not have to retain it for so long,
  1123. thus reducing the chance of race conditions causing problems.
  1124. .LP
  1125. The reasons not to run the clipboard client include:
  1126. .IP \(bu 5
  1127. Performance \- Data is only transferred if it is actually required 
  1128. (that is, when some client actually wants the data).
  1129. .IP \(bu 5
  1130. Flexibility \- The clipboard data may be available as more than one target.
  1131. .NH 3
  1132. Target Atoms
  1133. .XS
  1134. \*(SN Target Atoms
  1135. .XE
  1136. .LP
  1137. The atom that a requestor supplies as the target of a 
  1138. .PN ConvertSelection
  1139. request determines the form of the data supplied.
  1140. The set of such atoms is extensible, 
  1141. but a generally accepted base set of target atoms is needed.
  1142. As a starting point for this, 
  1143. the following table  contains those that have been suggested so far.
  1144. .TS H
  1145. lw(2i) lw(1i) lw(3i).
  1146. _
  1147. .sp 6p
  1148. .B
  1149. Atom    Type     Data Received
  1150. .sp 6p
  1151. _
  1152. .sp 6p
  1153. .TH
  1154. .R
  1155. TARGETS    ATOM    A list of valid target atoms
  1156. MULTIPLE    ATOM_PAIR    T{
  1157. (see the discussion that follows)
  1158. T}
  1159. TIMESTAMP    INTEGER    T{
  1160. The timestamp used to acquire the selection
  1161. T}
  1162. STRING    STRING    ISO Latin-1 (+TAB+NEWLINE) text
  1163. COMPOUND_TEXT    COMPOUND_TEXT    Compound Text
  1164. TEXT    TEXT    T{
  1165. The text in the owner's choice of encoding
  1166. T}
  1167. LIST_LENGTH    INTEGER    T{
  1168. The number of disjoint parts of the selection
  1169. T}
  1170. PIXMAP    DRAWABLE    A list of pixmap IDs
  1171. DRAWABLE    DRAWABLE    A list of drawable IDs
  1172. BITMAP    BITMAP    A list of bitmap IDs
  1173. FOREGROUND    PIXEL    A list of pixmap values
  1174. BACKGROUND    PIXEL    A list of pixel values
  1175. COLORMAP    COLORMAP    A list of colormap IDs
  1176. ODIF    TEXT    T{
  1177. ISO Office Document Interchange Format
  1178. T}
  1179. OWNER_OS    TEXT    T{
  1180. The operating system of the owner client
  1181. T}
  1182. FILE_NAME    TEXT    The full path name of a file
  1183. HOST_NAME    TEXT    (see section 5.1.1.2)
  1184. CHARACTER_POSITION    SPAN    T{
  1185. The start and end of the selection in bytes
  1186. T}
  1187. LINE_NUMBER    SPAN    T{
  1188. The start and end line numbers
  1189. T}
  1190. COLUMN_NUMBER    SPAN    T{
  1191. The start and end column numbers
  1192. T}
  1193. LENGTH    INTEGER    T{
  1194. The number of bytes in the selection
  1195. T}
  1196. USER    TEXT    T{
  1197. The name of the user running the owner
  1198. T}
  1199. PROCEDURE    TEXT    T{
  1200. The name of the selected procedure
  1201. T}
  1202. MODULE    TEXT    T{
  1203. The name of the selected procedure
  1204. T}
  1205. PROCESS    INTEGER,    T{
  1206. The process ID of the owner
  1207. T}
  1208.     TEXT
  1209. TASK    INTEGER,    T{
  1210. The task ID of the owner
  1211. T}
  1212.     TEXT
  1213. CLASS    TEXT    (see section 4.1.2.5)
  1214. NAME    TEXT    (see section 4.1.2.1)
  1215. CLIENT_WINDOW    WINDOW    T{
  1216. A top-level window of the owner
  1217. T}
  1218. DELETE    NULL    (see section 2.6.3.1)
  1219. INSERT_SELECTION    NULL    (see section 2.6.3.2)
  1220. INSERT_PROPERTY    NULL    (see section 2.6.3.3)
  1221. .sp 6p
  1222. _
  1223. .TE
  1224. .LP
  1225. It is expected that this table will grow over time.
  1226. .LP
  1227. Selection owners are required to support the following targets.
  1228. All other targets are optional.
  1229. .IP \(bu 5
  1230. TARGETS \- The owner should return a list of atoms that represent
  1231. the targets for which an attempt to convert the current selection
  1232. will succeed (barring unforseeable problems such as 
  1233. .PN Alloc 
  1234. errors).
  1235. This list should include all the required atoms.
  1236. .IP \(bu 5
  1237. MULTIPLE \- The MULTIPLE target atom is valid only when a property 
  1238. is specified on the 
  1239. .PN ConvertSelection 
  1240. request.
  1241. If the property argument in the 
  1242. .PN SelectionRequest 
  1243. event is 
  1244. .PN None 
  1245. and the target is MULTIPLE, 
  1246. it should be refused.
  1247. .IP
  1248. When a selection owner receives a 
  1249. .PN SelectionRequest (target==MULTIPLE)
  1250. request,
  1251. the contents of the property named in the request will be a list of atom pairs:
  1252. the first atom naming a target and the second naming a property 
  1253. .Pn ( None 
  1254. is not valid here).
  1255. The effect should be as if the owner had received a sequence of
  1256. .PN SelectionRequest 
  1257. events (one for each atom pair) except that:
  1258. .RS
  1259. .IP \- 5
  1260. The owner should reply with a 
  1261. .PN SelectionNotify 
  1262. only when all the requested conversions have been performed.
  1263. .IP \- 5
  1264. If the owner fails to convert the target used by an atom 
  1265. in the MULTIPLE property,
  1266. it should replace that atom in the property with
  1267. .PN None .
  1268. .RE
  1269. .NT Convention
  1270. The entries in a MULTIPLE property must be processed in the order
  1271. they appear in the property.
  1272. For further information,
  1273. see section 2.6.3.
  1274. .NE
  1275. .IP \(bu 5
  1276. TIMESTAMP \- To avoid some race conditions,
  1277. it is important that requestors be able to discover the timestamp 
  1278. the owner used to acquire ownership.
  1279. Until and unless the protocol is changed so that a
  1280. .PN GetSelectionOwner
  1281. request returns the timestamp used to acquire ownership,
  1282. selection owners must support conversion to TIMESTAMP,
  1283. returning the timestamp they used to obtain the selection.
  1284. .NT Problem
  1285. The protocol should be changed to return in response to a 
  1286. .PN GetSelectionOwner
  1287. request the timestamp used to acquire the selection.
  1288. .NE
  1289. .NH 3
  1290. Selection Targets with Side Effects
  1291. .XS
  1292. \*(SN Selection Targets with Side Effects
  1293. .XE
  1294. .LP
  1295. Some targets (for example, DELETE) have side effects.
  1296. To render these targets unambiguous,
  1297. the entries in a MULTIPLE property must be processed in the order 
  1298. that they appear in the property.
  1299. .LP
  1300. In general,
  1301. targets with side effects will return no information,
  1302. that is, they will return a zero-length property of type NULL.
  1303. (Type NULL means the result of
  1304. .PN InternAtom
  1305. on the string "NULL", not the value zero.)
  1306. In all cases,
  1307. the requested side effect must be performed before the conversion is accepted.
  1308. If the requested side effect cannot be performed,
  1309. the corresponding conversion request must be refused.
  1310. .NT Conventions
  1311. .IP 1. 5
  1312. Targets with side effects should return no information
  1313. (that is, they should have a zero-length property of type NULL).
  1314. .IP 2. 5
  1315. The side effect of a target must be performed before the conversion is accepted.
  1316. .IP 3. 5
  1317. If the side effect of a target cannot be performed,
  1318. the corresponding conversion request must be refused.
  1319. .NE
  1320. .RE
  1321. .NT Problem
  1322. The need to delay responding to the 
  1323. .PN ConvertSelection 
  1324. request until a further conversion has succeeded poses problems 
  1325. for the Intrinsics interface that need to be addressed.
  1326. .NE
  1327. .LP
  1328. These side effect targets are used to implement operations such as
  1329. ``exchange PRIMARY and SECONDARY selections.''
  1330. .NH 4
  1331. DELETE
  1332. .XS
  1333. \*(SN DELETE
  1334. .XE
  1335. .LP
  1336. When the owner of a selection receives a request to convert it to DELETE,
  1337. it should delete the corresponding selection
  1338. (whatever doing so means for its internal data structures)
  1339. and return a zero-length property of type NULL if the deletion was successful.
  1340. .NH 4
  1341. INSERT_SELECTION
  1342. .XS
  1343. \*(SN INSERT_SELECTION
  1344. .XE
  1345. .LP
  1346. When the owner of a selection receives a request to convert it to 
  1347. INSERT_SELECTION,
  1348. the property named will be of type ATOM_PAIR.
  1349. The first atom will name a selection,
  1350. and the second will name a target.
  1351. The owner should use the selection mechanism to convert the named selection
  1352. into the named target and should insert it at the location of the selection
  1353. for which it got the INSERT_SELECTION request
  1354. (whatever doing so means for its internal data structures).
  1355. .NH 4
  1356. INSERT_PROPERTY
  1357. .XS
  1358. \*(SN INSERT_PROPERTY
  1359. .XE
  1360. .LP
  1361. When the owner of a selection receives a request to convert it to
  1362. INSERT_PROPERTY, 
  1363. it should insert the property named in the request at the location 
  1364. of the selection for which it got the INSERT_SELECTION request
  1365. (whatever doing so means for its internal data structures).
  1366. .NH 2
  1367. Use of Selection Properties
  1368. .XS
  1369. \*(SN Use of Selection Properties
  1370. .XE
  1371. .LP
  1372. The names of the properties used in selection data transfer are chosen by
  1373. the requestor.
  1374. The use of 
  1375. .PN None 
  1376. property fields in 
  1377. .PN ConvertSelection 
  1378. requests (which request the selection owner to choose a name)
  1379. is not permitted by these conventions.
  1380. .LP
  1381. The selection owner always chooses the type of the property 
  1382. in the selection data transfer.
  1383. Some types have special semantics assigned by convention,
  1384. and these are reviewed in the following sections.
  1385. .LP
  1386. In all cases,
  1387. a request for conversion to a target should return either
  1388. a property of one of the types listed in the previous table for that property
  1389. or a property of type INCR and then a property of one of the listed types.
  1390. .LP
  1391. The selection owner will return a list of zero or more items
  1392. of the type indicated by the property type.
  1393. In general,
  1394. the number of items in the list will correspond to the number 
  1395. of disjoint parts of the selection.
  1396. Some targets (for example, side-effect targets) will be of length zero
  1397. irrespective of the number of disjoint selection parts.
  1398. In the case of fixed-size items,
  1399. the requestor may determine the number of items by the property size.
  1400. For variable-length items such as text, 
  1401. the separators are listed in the following table:
  1402. .TS H
  1403. l c l.
  1404. _
  1405. .sp 6p
  1406. .B
  1407. Type Atom    Format    Separator
  1408. .sp 6p
  1409. _
  1410. .sp 6p
  1411. .TH
  1412. .R
  1413. STRING    8    Null
  1414. COMPOUND_TEXT    8    Null
  1415. ATOM    32    Fixed-size
  1416. ATOM_PAIR    32    Fixed-size
  1417. BITMAP    32    Fixed-size
  1418. PIXMAP    32    Fixed-size
  1419. DRAWABLE    32    Fixed-size
  1420. SPAN    32    Fixed-size
  1421. INTEGER    32    Fixed-size
  1422. WINDOW    32    Fixed-size
  1423. INCR    32    Fixed-size
  1424. .sp 6p
  1425. _
  1426. .TE
  1427. .LP
  1428. It is expected that this table will grow over time.
  1429. .NH 3
  1430. TEXT Properties
  1431. .XS
  1432. \*(SN TEXT Properties
  1433. .XE
  1434. .LP
  1435. In general, 
  1436. the encoding for the characters in a text string property is specified 
  1437. by its type.
  1438. It is highly desirable for there to be a simple, invertible mapping 
  1439. between string property types and any character set names
  1440. embedded within font names in any font naming standard adopted by the
  1441. Consortium.
  1442. .LP
  1443. The atom TEXT is a polymorphic target.
  1444. Requesting conversion into TEXT will convert into whatever encoding 
  1445. is convenient for the owner.
  1446. The encoding chosen will be indicated by the type of the property returned.
  1447. TEXT is not defined as a type;
  1448. it will never be the returned type from a selection conversion request.
  1449. .LP
  1450. If the requestor wants the owner to return the contents of the selection
  1451. in a specific encoding,
  1452. it should request conversion into the name of that encoding.
  1453. .LP
  1454. In the table in section 2.6.2,
  1455. the word TEXT (in the Type column) is used to indicate one 
  1456. of the registered encoding names.
  1457. The type would not actually be TEXT;
  1458. it would be STRING or some other ATOM naming the encoding chosen by the owner.
  1459. .LP
  1460. STRING as a type or a target specifies the ISO Latin-1 character set plus the
  1461. control characters TAB (octal 11) and NEWLINE (octal 12).
  1462. The spacing interpretation of TAB is context dependent.
  1463. Other ASCII control characters are explicitly not included in STRING 
  1464. at the present time.
  1465. .LP
  1466. COMPOUND_TEXT as a type or a target specifies the Compound Text interchange
  1467. format; see the \fICompound Text Encoding\fP.
  1468. .LP
  1469. Type STRING and COMPOUND_TEXT properties will consist of a list of elements separated by null
  1470. characters;
  1471. other encodings will need to specify an appropriate list format.
  1472. .NH 3
  1473. INCR Properties
  1474. .XS
  1475. \*(SN INCR Properties
  1476. .XE
  1477. .LP
  1478. Requestors may receive a property of type INCR\s-2\u3\d\s0
  1479. in response to any target that results in selection data.
  1480. .FS
  1481. 3. These properties were called INCREMENTAL in an earlier draft.
  1482. The protocol for using them has changed, 
  1483. and so the name has changed to avoid confusion.
  1484. .FE
  1485. This indicates that the owner will send the actual data incrementally.
  1486. The contents of the INCR property will be an integer,  
  1487. which represents a lower bound on the number of bytes of data in the selection.
  1488. The requestor and the selection owner transfer the data in the selection 
  1489. in the following manner.
  1490. .LP
  1491. The selection requestor starts the transfer process by deleting
  1492. the (type==INCR) property forming the reply to the selection.
  1493. .LP
  1494. The selection owner then:
  1495. .IP \(bu 5
  1496. Appends the data in suitable-size chunks to the
  1497. same property on the same window as the selection reply
  1498. with a type corresponding to the actual type of the converted selection.
  1499. The size should be less than the maximum-request-size in the connection
  1500. handshake.
  1501. .IP \(bu 5
  1502. Waits between each append for a 
  1503. .PN PropertyNotify (state==Deleted) 
  1504. event that shows that the requestor has read the data.
  1505. The reason for doing this is to limit the consumption of space in the server.
  1506. .IP \(bu 5
  1507. Waits (after the entire data has been transferred to the server) until a 
  1508. .PN PropertyNotify (state==Deleted)
  1509. event that shows that the data has been read by the requestor
  1510. and then writes zero-length data to the property.
  1511. .LP
  1512. The selection requestor:
  1513. .IP \(bu 5
  1514. Waits for the 
  1515. .PN SelectionNotify 
  1516. event.
  1517. .IP \(bu 5
  1518. Loops:
  1519. .RS
  1520. .IP \- 5
  1521. Retrieving data using 
  1522. .PN GetProperty 
  1523. with the delete argument
  1524. .PN True .
  1525. .IP \- 5
  1526. Waiting for a 
  1527. .PN PropertyNotify 
  1528. with the state argument 
  1529. .PN NewValue .
  1530. .RE
  1531. .IP \(bu 5
  1532. Waits until the property named by the
  1533. .PN PropertyNotify
  1534. event is zero-length.
  1535. .IP \(bu 5
  1536. Deletes the zero-length property.
  1537. .LP
  1538. The type of the converted selection is the type of the first partial property.
  1539. The remaining partial properties must have the same type.
  1540. .NH 3
  1541. DRAWABLE Properties
  1542. .XS
  1543. \*(SN DRAWABLE Properties
  1544. .XE
  1545. .LP
  1546. Requestors may receive properties of type PIXMAP, BITMAP, DRAWABLE, or WINDOW,
  1547. which contain an appropriate ID.
  1548. While information about these drawables is available from the server by means of
  1549. the 
  1550. .PN GetGeometry 
  1551. request,
  1552. the following items are not:
  1553. .IP \(bu 5
  1554. Foreground pixel
  1555. .IP \(bu 5
  1556. Background pixel
  1557. .IP \(bu 5
  1558. Colormap ID
  1559. .LP
  1560. In general,
  1561. requestors converting into targets whose returned type in the table 
  1562. in section 2.6.2 is one of the DRAWABLE types should expect to convert also 
  1563. into the following targets (using the MULTIPLE mechanism):
  1564. .IP \(bu 5
  1565. FOREGROUND returns a PIXEL value.
  1566. .IP \(bu 5
  1567. BACKGROUND returns a PIXEL value.
  1568. .IP \(bu 5
  1569. COLORMAP returns a colormap ID.
  1570. .NH 3
  1571. SPAN Properties
  1572. .XS
  1573. \*(SN SPAN Properties
  1574. .XE
  1575. .LP
  1576. Properties with type SPAN contain a list of cardinal-pairs
  1577. with the length of the cardinals determined by the format.
  1578. The first specifies the starting position,
  1579. and the second specifies the ending position plus one.
  1580. The base is zero.
  1581. If they are the same,
  1582. the span is zero-length and is before the specified position.
  1583. The units are implied by the target atom, 
  1584. such as LINE_NUMBER or CHARACTER_POSITION.
  1585. .NH 1
  1586. Peer-to-Peer Communication by Means of Cut Buffers
  1587. .XS
  1588. \*(SN Peer-to-Peer Communication by Means of Cut Buffers
  1589. .XE
  1590. .LP
  1591. The cut buffer mechanism is much simpler but much less powerful 
  1592. than the selection mechanism.
  1593. The selection mechanism is active in that it provides a link 
  1594. between the owner and requestor clients.
  1595. The cut buffer mechanism is passive;
  1596. an owner places data in a cut buffer from which a requestor retrieves
  1597. the data at some later time.
  1598. .LP
  1599. The cut buffers consist of eight properties on the root of screen zero,
  1600. named by the predefined atoms CUT_BUFFER0 to CUT_BUFFER7.
  1601. These properties must, at present, have type STRING and format 8.
  1602. A client that uses the cut buffer mechanism must initially ensure that
  1603. all eight properties exist by using
  1604. .PN ChangeProperty 
  1605. requests to append zero-length data to each.
  1606. .LP
  1607. A client that stores data in the cut buffers (an owner) first must rotate the
  1608. ring of buffers by plus 1 by using
  1609. .PN RotateProperties 
  1610. requests to rename each buffer;
  1611. that is, CUT_BUFFER0 to CUT_BUFFER1, CUT_BUFFER1 to CUT_BUFFER2,...,
  1612. and CUT_BUFFER7 to CUT_BUFFER0.
  1613. It then must store the data into CUT_BUFFER0 by using a
  1614. .PN ChangeProperty 
  1615. request in mode 
  1616. .PN Replace .
  1617. .LP
  1618. A client that obtains data from the cut buffers should use a
  1619. .PN GetProperty 
  1620. request to retrieve the contents of CUT_BUFFER0.
  1621. .LP
  1622. In response to a specific user request,
  1623. a client may rotate the cut buffers by minus 1 by using 
  1624. .PN RotateProperties 
  1625. requests to rename each buffer;
  1626. that is, CUT_BUFFER7 to CUT_BUFFER6, CUT_BUFFER6 to CUT_BUFFER5,...,
  1627. and CUT_BUFFER0 to CUT_BUFFER7.
  1628. .LP
  1629. Data should be stored to the cut buffers
  1630. and the ring rotated only when requested by explicit user action.
  1631. Users depend on their mental model of cut buffer operation
  1632. and need to be able to identify operations that transfer data to and fro.
  1633. .NH 1
  1634. Client to Window Manager Communication
  1635. .XS
  1636. \*(SN Client to Window Manager Communication
  1637. .XE
  1638. .LP
  1639. To permit window managers to perform their role of mediating the competing
  1640. demands for resources such as screen space,
  1641. the clients being managed must adhere to certain conventions
  1642. and must expect the window managers to do likewise.
  1643. These conventions are covered here from the client's point of view
  1644. and again from the window manager's point of view in the forthcoming
  1645. \fIWindow and Session Manager Conventions Manual\fP.
  1646. .LP
  1647. In general,
  1648. these conventions are somewhat complex
  1649. and will undoubtedly change as new window management paradigms are developed.
  1650. Thus, there is a strong bias toward defining only those conventions
  1651. that are essential and that apply generally to all window management paradigms.
  1652. Clients designed to run with a particular window manager can easily
  1653. define private protocols to add to these conventions,
  1654. but they must be aware that their users may decide to run some other
  1655. window manager no matter how much the designers of the private protocol
  1656. are convinced that they have seen the ``one true light'' of user interfaces.
  1657. .LP
  1658. It is a principle of these conventions that a general client should
  1659. neither know nor care which window manager is running or, indeed, 
  1660. if one is running at all.
  1661. The conventions do not support all client functions 
  1662. without a window manager running;
  1663. for example, the concept of Iconic 
  1664. is not directly supported by clients.
  1665. If no window manager is running,
  1666. the concept of Iconic does not apply.
  1667. A goal of the conventions is to make it possible to kill and
  1668. restart window managers without loss of functionality.
  1669. .LP
  1670. Each window manager will implement a particular window management policy;
  1671. the choice of an appropriate window management policy
  1672. for the user's circumstances is not one for an individual client to
  1673. make but will be made by the user or the user's system administrator.
  1674. This does not exclude the possibility of writing clients that
  1675. use a private protocol to restrict themselves to operating only
  1676. under a specific window manager.
  1677. Rather, 
  1678. it merely ensures that no claim of general utility is made for such programs.
  1679. .LP
  1680. For example,
  1681. the claim is often made: 
  1682. ``The client I'm writing is important, and it needs to be on top.''
  1683. Perhaps it is important when it is being run in earnest,
  1684. and it should then be run under the control of a window manager 
  1685. that recognizes ``important'' windows through some private protocol 
  1686. and ensures that they are on top.
  1687. However, imagine, for example, that the ``important'' client is being debugged.
  1688. Then,  ensuring that it is always on top is no longer 
  1689. the appropriate window management policy,
  1690. and it should be run under a window manager that allows other windows 
  1691. (for example, the debugger) to appear on top.
  1692. .NH 2
  1693. Client's Actions
  1694. .XS
  1695. \*(SN Client's Actions
  1696. .XE
  1697. .LP
  1698. In general, 
  1699. the object of the X Version 11 design is that clients should,
  1700. as far as possible, do exactly what they would do in the absence 
  1701. of a window manager, except for the following:
  1702. .IP \(bu 5
  1703. Hinting to the window manager about the resources they would like
  1704. to obtain
  1705. .IP \(bu 5
  1706. Cooperating with the window manager by accepting the resources they
  1707. are allocated even if they are not those requested
  1708. .IP \(bu 5
  1709. Being prepared for resource allocations to change at any time
  1710. .NH 3
  1711. Creating a Top-Level Window
  1712. .XS
  1713. \*(SN Creating a Top-Level Window
  1714. .XE
  1715. .LP
  1716. A client usually would expect to create its top-level windows
  1717. as children of one or more of the root windows by using some
  1718. boilerplate like the following:
  1719. .LP
  1720. .Ds 0
  1721. .TA 2i
  1722. .ta 2i
  1723. win = XCreateSimpleWindow(dpy, DefaultRootWindow(dpy), xsh.x, xsh.y, 
  1724.     xsh.width, xsh.height, bw, bd, bg);
  1725. .De
  1726. .LP
  1727. If a particular one of the root windows was required, however,
  1728. it could use something like the following:
  1729. .LP
  1730. .Ds 0
  1731. .TA 2i
  1732. .ta 2i
  1733. win = XCreateSimpleWindow(dpy, RootWindow(dpy, screen), xsh.x, xsh.y, 
  1734.     xsh.width, xsh.height, bw, bd, bg);
  1735. .De
  1736. .LP
  1737. Ideally,
  1738. it should be possible to override the choice of a root window 
  1739. and allow clients (including window managers) to treat a nonroot window 
  1740. as a pseudo-root.
  1741. This would allow, for example, the testing of window managers and the
  1742. use of application-specific window managers to control the subwindows
  1743. owned by the members of a related suite of clients.
  1744. Doing so properly requires an extension,
  1745. the design of which is under study.
  1746. .LP
  1747. From the client's point of view,
  1748. the window manager will regard its top-level window as being in 
  1749. one of three states:
  1750. .IP \(bu 5
  1751. Normal
  1752. .IP \(bu 5
  1753. Iconic
  1754. .IP \(bu 5
  1755. Withdrawn
  1756. .LP
  1757. Newly created windows start in the Withdrawn state.
  1758. Transitions between states happen when the top-level window is mapped
  1759. and unmapped and when the window manager receives certain messages.
  1760. For further details, see sections 4.1.2.4 and 4.1.4.
  1761. .NH 3
  1762. Client Properties
  1763. .XS
  1764. \*(SN Client Properties
  1765. .XE
  1766. .LP
  1767. Once the client has one or more top-level windows, 
  1768. it should place properties on those windows to inform the window manager 
  1769. of the behavior that the client desires.
  1770. Window managers will assume values they find convenient 
  1771. for any of these properties that are not supplied;
  1772. clients that depend on particular values must explicitly supply them.
  1773. The window manager will not change properties written by the client.
  1774. .LP
  1775. The window manager will examine the contents of these
  1776. properties when the window makes the transition from the Withdrawn state
  1777. and will monitor some properties for changes while the window is 
  1778. in the Iconic or Normal state.
  1779. When the client changes one of these properties, 
  1780. it must use 
  1781. .PN Replace
  1782. mode to overwrite the entire property with new data;
  1783. the window manager will retain no memory of the old value of the property.
  1784. All fields of the property must be set to suitable values in a single 
  1785. .PN Replace
  1786. mode 
  1787. .PN ChangeProperty
  1788. request.
  1789. This ensures that the full contents of the property will be
  1790. available to a new window manager if the existing one crashes,
  1791. if it is shut down and restarted,
  1792. or if the session needs to be shut down and restarted by the session manager.
  1793. .NT Convention
  1794. Clients writing or rewriting window manager properties must
  1795. ensure that the entire content of each property remains valid
  1796. at all times.
  1797. .NE
  1798. .LP
  1799. If these properties are longer than expected,
  1800. clients should ignore the remainder of the property.
  1801. Extending these properties is reserved to the X Consortium;
  1802. private extensions to them are forbidden.
  1803. Private additional communication between clients and window managers 
  1804. should take place using separate properties.
  1805. .LP
  1806. The next sections describe each of the properties the clients
  1807. need to set, in turn.
  1808. They are summarized in the table in section 4.3.
  1809. .NH 4
  1810. WM_NAME Property
  1811. .XS
  1812. \*(SN WM_NAME Property
  1813. .XE
  1814. .LP
  1815. The WM_NAME property is an uninterpreted string 
  1816. that the client wants the window manager to display
  1817. in association with the window (for example, in a window headline bar).
  1818. .LP
  1819. The encoding used for this string 
  1820. (and all other uninterpreted string properties) 
  1821. is implied by the type of the property.
  1822. The type atoms to be used for this purpose are described in section 2.7.1.
  1823. .LP
  1824. Window managers are expected to make an effort to display this information.
  1825. Simply ignoring WM_NAME is not acceptable behavior.
  1826. Clients can assume that at least the first part of this string
  1827. is visible to the user and that if the information is not visible to the user,
  1828. it is because the user has taken an explicit action to make it invisible.
  1829. .LP
  1830. On the other hand,
  1831. there is no guarantee that the user can see the WM_NAME string 
  1832. even if the window manager supports window headlines.
  1833. The user may have placed the headline off-screen
  1834. or have covered it by other windows.
  1835. WM_NAME should not be used for application-critical information 
  1836. or to announce asynchronous changes of an application's state 
  1837. that require timely user response.
  1838. The expected uses are to permit the user to identify one of a
  1839. number of instances of the same client
  1840. and to provide the user with noncritical state information.
  1841. .LP
  1842. Even window managers that support headline bars will place some limit 
  1843. on the length of the WM_NAME string that can be visible;
  1844. brevity here will pay dividends.
  1845. .NH 4
  1846. WM_ICON_NAME Property
  1847. .XS
  1848. \*(SN WM_ICON_NAME Property
  1849. .XE
  1850. .LP
  1851. The WM_ICON_NAME property is an uninterpreted string 
  1852. that the client wants to be displayed in association with the window 
  1853. when it is iconified (for example, in an icon label).
  1854. In other respects, 
  1855. including the type, it is similar to WM_NAME.
  1856. For obvious geometric reasons,
  1857. fewer characters will normally be visible in WM_ICON_NAME than WM_NAME.
  1858. .LP
  1859. Clients should not attempt to display this string in their icon pixmaps
  1860. or windows; rather, they should rely on the window manager to do so.
  1861. .NH 4
  1862. WM_NORMAL_HINTS Property
  1863. .XS
  1864. \*(SN WM_NORMAL_HINTS Property
  1865. .XE
  1866. .LP
  1867. The type of the WM_NORMAL_HINTS property is WM_SIZE_HINTS.
  1868. Its contents are as follows:
  1869. .TS H
  1870. l l l.
  1871. _
  1872. .sp 6p
  1873. .B
  1874. Field    Type    Comments
  1875. .sp 6p
  1876. _
  1877. .sp 6p
  1878. .TH
  1879. .R
  1880. flags    CARD32    (see the next table)
  1881. pad    4*CARD32    For backwards compatibility
  1882. min_width    INT32    If missing, assume base_width
  1883. min_height    INT32    If missing, assume base_height
  1884. max_width    INT32
  1885. max_height    INT32
  1886. width_inc    INT32
  1887. height_inc    INT32
  1888. min_aspect    (INT32,INT32)
  1889. max_aspect    (INT32,INT32)
  1890. base_width    INT32    If missing, assume min-width
  1891. base_height    INT32    If missing, assume min_height
  1892. win_gravity    INT32    If missing, assume NorthWest
  1893. .sp 6p
  1894. _
  1895. .TE
  1896. .LP
  1897. The WM_SIZE_HINTS.flags bit definitions are as follows:
  1898. .TS H
  1899. l n l.
  1900. _
  1901. .sp 6p
  1902. .B
  1903. Name    Value    Field
  1904. .sp 6p
  1905. _
  1906. .sp 6p
  1907. .TH
  1908. .R
  1909. USPosition    1    User-specified x, y
  1910. USSize    2    User-specified width, height
  1911. PPosition    4    Program-specified position
  1912. PSize    8    Program-specified size
  1913. PMinSize    16    Program-specified minimum size
  1914. PMaxSize    32    Program-specified maximum size
  1915. PResizeInc    64    Program-specified resize increments
  1916. PAspect    128    Program-specified min and max aspect ratios
  1917. PBaseSize    256    Program-specified base size
  1918. PWinGravity    512    Program-specified window gravity
  1919. .sp 6p
  1920. _
  1921. .TE
  1922. .LP
  1923. To indicate that the size and position of the window 
  1924. (when mapped from the Withdrawn state) was specified by the user, 
  1925. the client should set the
  1926. .PN USPosition
  1927. and
  1928. .PN USSize
  1929. flags, 
  1930. which allow a window manager to know that the user specifically asked where
  1931. the window should be placed or how the window should be sized and that
  1932. further interaction is superfluous.
  1933. To indicate that it was specified by the client without any user involvement,
  1934. the client should set 
  1935. .PN PPosition
  1936. and 
  1937. .PN PSize .
  1938. .LP
  1939. The size specifiers refer to the width and height of the client's window 
  1940. excluding borders.
  1941. The window manager will interpret the position of the window 
  1942. and its border width to position the point of the outer rectangle 
  1943. of the overall window specified by the win_gravity in the size hints.
  1944. The outer rectangle of the window includes any borders or decorations
  1945. supplied by the window manager.
  1946. In other words,
  1947. if the window manager decides to place the window where the client asked,
  1948. the position on the parent window's border named by the win_gravity 
  1949. will be placed where the client window would have been placed 
  1950. in the absence of a window manager.
  1951. .LP
  1952. The defined values for win_gravity are those specified for WINGRAVITY
  1953. in the core X protocol with the exception of 
  1954. .PN Unmap 
  1955. and 
  1956. .PN Static :
  1957. .PN NorthWest 
  1958. (1), 
  1959. .PN North 
  1960. (2), 
  1961. .PN NorthEast 
  1962. (3), 
  1963. .PN West 
  1964. (4), 
  1965. .PN Center
  1966. (5),
  1967. .PN East
  1968. (6), 
  1969. .PN SouthWest
  1970. (7),
  1971. .PN South
  1972. (8), and 
  1973. .PN SouthEast
  1974. (9).
  1975. .LP
  1976. The min_width and min_height elements specify the
  1977. minimum size that the window can be for the client to be useful.
  1978. The max_width and max_height elements specify the maximum size.
  1979. The base_width and base_height elements in conjunction with width_inc
  1980. and height_inc define an arithmetic progression of preferred window
  1981. widths and heights for nonnegative integers \fIi\fP and \fIj\fP:
  1982. .LP
  1983. .Ds
  1984. width = base_width + ( i * width_inc )
  1985. height = base_height + ( j * height_inc )
  1986. .De
  1987. .LP
  1988. Window managers are encouraged to use \fIi\fP and \fIj\fP 
  1989. instead of width and height in reporting window sizes to users.
  1990. If a base size is not provided, 
  1991. the minimum size is to be used in its place and vice versa.
  1992. .LP
  1993. The min_aspect and max_aspect fields are fractions
  1994. with the numerator first and the denominator second,
  1995. and they allow a client to specify the range of aspect ratios it prefers.
  1996. .NH 4
  1997. WM_HINTS Property
  1998. .XS
  1999. \*(SN WM_HINTS Property
  2000. .XE
  2001. .LP
  2002. The WM_HINTS property (whose type is WM_HINTS)
  2003. is used to communicate to the window manager.
  2004. It conveys the information the window manager needs 
  2005. other than the window geometry,
  2006. which is available from the window itself;
  2007. the constraints on that geometry,
  2008. which is available from the WM_NORMAL_HINTS structure;
  2009. and various strings,
  2010. which need separate properties, such as WM_NAME.
  2011. The contents of the properties are as follows:
  2012. .TS H
  2013. l l l.
  2014. _
  2015. .sp 6p
  2016. .B
  2017. Field    Type    Comments
  2018. .sp 6p
  2019. _
  2020. .sp 6p
  2021. .TH
  2022. .R
  2023. flags    CARD32    (see the next table)
  2024. input    CARD32    The client's input model
  2025. initial_state    CARD32    The state when first mapped
  2026. icon_pixmap    PIXMAP    The pixmap for the icon image
  2027. icon_window    WINDOW    The window for the icon image
  2028. icon_x    INT32    The icon location
  2029. icon_y    INT32
  2030. icon_mask    PIXMAP    The mask for the icon shape
  2031. window_group    WINDOW    The ID of the group leader window
  2032. .sp 6p
  2033. _
  2034. .TE
  2035. .LP
  2036. The WM_HINTS.flags bit definitions are as follows:
  2037. .TS H
  2038. l n l.
  2039. _
  2040. .sp 6p
  2041. .B
  2042. Name    Value    Field
  2043. .sp 6p
  2044. _
  2045. .sp 6p
  2046. .TH
  2047. .R
  2048. InputHint    1    input
  2049. StateHint    2    initial_state
  2050. IconPixmapHint    4    icon_pixmap
  2051. IconWindowHint    8    icon_window
  2052. IconPositionHint    16    icon_x & icon_y
  2053. IconMaskHint    32    icon_mask
  2054. WindowGroupHint    64    window_group
  2055. MessageHint    128    This bit is obsolete
  2056. .sp 6p
  2057. _
  2058. .TE
  2059. .LP
  2060. Window managers are free to assume convenient values for all fields of
  2061. the WM_HINTS property if a window is mapped without one.
  2062. .LP
  2063. The input field is used to communicate to the window manager the input focus
  2064. model used by the client (see section 4.1.7).
  2065. .LP
  2066. Clients with the Globally Active and No Input models should set the
  2067. input flag to
  2068. .PN False .
  2069. Clients with the Passive and Locally Active models should set the input
  2070. flag to
  2071. .PN True .
  2072. .LP
  2073. From the client's point of view, 
  2074. the window manager will regard the client's top-level window as being 
  2075. in one of three states:
  2076. .IP \(bu 5
  2077. Normal
  2078. .IP \(bu 5
  2079. Iconic
  2080. .IP \(bu 5
  2081. Withdrawn
  2082. .LP
  2083. The semantics of these states are described in section 4.1.4.
  2084. Newly created windows start in the Withdrawn state.
  2085. Transitions between states happen when a non-override-redirect
  2086. top-level window is mapped and unmapped
  2087. and when the window manager receives certain messages.
  2088. .LP
  2089. The value of the initial_state field determines the state the client
  2090. wishes to be in at the time the top-level window is mapped 
  2091. from the Withdrawn state, as shown in the following table:
  2092. .TS H
  2093. l n l.
  2094. _
  2095. .sp 6p
  2096. .B
  2097. State    Value    Comments
  2098. .sp 6p
  2099. _
  2100. .sp 6p
  2101. .TH
  2102. .R
  2103. NormalState    1    The window is visible
  2104. IconicState    3    The icon is visible
  2105. .sp 6p
  2106. _
  2107. .TE
  2108. .LP
  2109. The icon_pixmap field may specify a pixmap to be used as an icon.
  2110. This pixmap should be:
  2111. .IP \(bu 5
  2112. One of the sizes specified in the WM_ICON_SIZE property 
  2113. on the root if it exists (see section 4.1.3.2).
  2114. .IP \(bu 5
  2115. 1-bit deep.
  2116. The window manager will select, through the defaults database,
  2117. suitable background (for the 0 bits) and foreground (for the 1 bits) colors.
  2118. These defaults can, of course, specify different colors for the icons 
  2119. of different clients.
  2120. .LP
  2121. The icon_mask specifies which pixels of the icon_pixmap should be used as the
  2122. icon, allowing for icons to appear nonrectangular.
  2123. .LP
  2124. The icon_window field is the ID of a window the client wants used as its icon.
  2125. Most, but not all, window managers will support icon windows.
  2126. Those that do not are likely to have a user interface in which small
  2127. windows that behave like icons are completely inappropriate.
  2128. Clients should not attempt to remedy the omission by working around it.
  2129. .LP
  2130. Clients that need more capabilities from the icons than a simple two-color
  2131. bitmap should use icon windows.
  2132. Rules for clients that do are set out in section 4.1.9.
  2133. .LP
  2134. The (icon_x,icon_y) coordinate is a hint to the window manager 
  2135. as to where it should position the icon.
  2136. The policies of the window manager control the positioning of icons,
  2137. so clients should not depend on attention being paid to this hint.
  2138. .LP
  2139. The window_group field lets the client specify that this window belongs 
  2140. to a group of windows.
  2141. An example is a single client manipulating multiple 
  2142. children of the root window.
  2143. .NT Conventions
  2144. .IP 1. 5
  2145. The window_group field should be set to the ID of the group leader.
  2146. The window group leader may be a window that exists only for that purpose;
  2147. a placeholder group leader of this kind would never be mapped
  2148. either by the client or by the window manager.
  2149. .IP 2. 5
  2150. The properties of the window group leader are those for the group as
  2151. a whole (for example, the icon to be shown when the entire group is iconified).
  2152. .NE
  2153. .LP
  2154. Window managers may provide facilities for manipulating the group as a whole.
  2155. Clients, at present, have no way to operate on the group as a whole.
  2156. .LP
  2157. The messages bit, if set in the flags field, indicates that the
  2158. client is using an obsolete window manager communication protocol,\s-2\u4\d\s0
  2159. rather than the WM_PROTOCOLS mechanism of section 4.1.2.7.
  2160. .FS
  2161. 4.  This obsolete protocol was described in the July 27, 1988
  2162. draft of the ICCCM.
  2163. Windows using it can also be detected because their WM_HINTS properties are
  2164. four bytes longer than expected.
  2165. Window managers are free to support clients using the obsolete protocol
  2166. in a ``backwards compatibility'' mode.
  2167. .FE
  2168. .NH 4
  2169. WM_CLASS Property
  2170. .XS
  2171. \*(SN WM_CLASS Property
  2172. .XE
  2173. .LP
  2174. The WM_CLASS property (of type STRING without control characters)
  2175. contains two consecutive null-terminated strings.
  2176. These specify the Instance and Class names to be used by both the client 
  2177. and the window manager for looking up resources for the application 
  2178. or as identifying information.
  2179. This property must be present when the window leaves the Withdrawn state
  2180. and may be changed only while the window is in the Withdrawn state.
  2181. Window managers may examine the property only when they start up 
  2182. and when the window leaves the Withdrawn state,
  2183. but there should be no need for a client to change its state dynamically.
  2184. .LP
  2185. The two strings, respectively, are:
  2186. .IP \(bu 5
  2187. A string that names the particular instance of the application to which
  2188. the client that owns this window belongs.
  2189. Resources that are specified by instance name override any resources
  2190. that are specified by class name.
  2191. Instance names can be specified by the user in an operating-system specific 
  2192. manner.
  2193. On POSIX-conformant systems,
  2194. the following conventions are used:
  2195. .RS
  2196. .IP \- 5
  2197. If "\-name NAME" is given on the command line,
  2198. NAME is used as the instance name.
  2199. .IP \- 5
  2200. Otherwise, if the environment variable RESOURCE_NAME is set,
  2201. its value will be used as the instance name.
  2202. .IP \- 5
  2203. Otherwise,
  2204. the trailing part of the name used to invoke the program
  2205. (argv[0] stripped of any directory names) is used as the instance name.
  2206. .RE
  2207. .IP \(bu 5
  2208. A string that names the general class of applications to which the client 
  2209. that owns this window belongs.
  2210. Resources that are specified by class apply to all applications 
  2211. that have the same class name.
  2212. Class names are specified by the application writer.
  2213. Examples of commonly used class names include: 
  2214. "Emacs", "XTerm", "XClock", "XLoad", and so on.
  2215. .LP
  2216. Note that WM_CLASS strings are null-terminated
  2217. and, thus, differ from the general conventions that STRING properties 
  2218. are null-separated.
  2219. This inconsistency is necessary for backwards compatibility.
  2220. .NH 4
  2221. WM_TRANSIENT_FOR Property
  2222. .XS
  2223. \*(SN WM_TRANSIENT_FOR Property
  2224. .XE
  2225. .LP
  2226. The WM_TRANSIENT_FOR property (of type WINDOW)
  2227. contains the ID of another top-level window.
  2228. The implication is that this window is a pop-up on behalf of the named window,
  2229. and window managers may decide not to decorate transient windows
  2230. or may treat them differently in other ways.
  2231. In particular,
  2232. window managers should present newly mapped WM_TRANSIENT_FOR
  2233. windows without requiring any user interaction,
  2234. even if mapping top-level windows normally does require interaction.
  2235. Dialogue boxes, for example, are an example of windows that should have
  2236. WM_TRANSIENT_FOR set.
  2237. .LP
  2238. It is important not to confuse WM_TRANSIENT_FOR with override-redirect.
  2239. WM_TRANSIENT_FOR should be used in those cases where the pointer
  2240. is not grabbed while the window is mapped (in other words, 
  2241. if other windows are allowed to be active while the transient is up).
  2242. If other windows must be prevented from processing input
  2243. (for example, when implementing pop-up menus),
  2244. use override-redirect and grab the pointer while the window is mapped.
  2245. .NH 4
  2246. WM_PROTOCOLS Property
  2247. .XS
  2248. \*(SN WM_PROTOCOLS Property
  2249. .XE
  2250. .LP
  2251. The WM_PROTOCOLS property (of type ATOM) is a list of atoms.
  2252. Each atom identifies a communication protocol between the client 
  2253. and the window manager in which the client is willing to participate.
  2254. Atoms can identify both standard protocols and private protocols
  2255. specific to individual window managers.
  2256. .LP
  2257. All the protocols in which a client can volunteer to take part 
  2258. involve the window manager sending the client a 
  2259. .PN ClientMessage
  2260. event and the client taking appropriate action.
  2261. For details of the contents of the event,
  2262. see section 4.2.8.
  2263. In each case,
  2264. the protocol transactions are initiated by the window manager.
  2265. .LP
  2266. The WM_PROTOCOLS property is not required.
  2267. If it is not present,
  2268. the client does not want to participate in any window manager protocols.
  2269. .LP
  2270. The X Consortium will maintain a registry of protocols to avoid collisions 
  2271. in the name space.
  2272. The following table lists the protocols that have been defined to date.
  2273. .TS H
  2274. l c l.
  2275. _
  2276. .sp 6p
  2277. .B
  2278. Protocol    Section    Purpose
  2279. .sp 6p
  2280. _
  2281. .sp 6p
  2282. .TH
  2283. .R
  2284. WM_TAKE_FOCUS    4.1.7    Assignment of input focus
  2285. WM_SAVE_YOURSELF    5.2.1    Save client state warning
  2286. WM_DELETE_WINDOW    5.2.2    Request to delete top-level window
  2287. .sp 6p
  2288. _
  2289. .TE
  2290. It is expected that this table will grow over time.
  2291. .NH 4
  2292. WM_COLORMAP_WINDOWS Property
  2293. .XS
  2294. \*(SN WM_COLORMAP_WINDOWS Property
  2295. .XE
  2296. .LP
  2297. The WM_COLORMAP_WINDOWS property (of type WINDOW) on a top-level window 
  2298. is a list of the IDs of windows that may need colormaps installed
  2299. that differ from the colormap of the top-level window.
  2300. The window manager will watch this list of windows for changes in their
  2301. colormap attributes.
  2302. The top-level window is always (implicitly or explicitly) on the watch list.
  2303. For the details of this mechanism,
  2304. see section 4.1.8.
  2305. .NH 3
  2306. Window Manager Properties
  2307. .XS
  2308. \*(SN Window Manager Properties
  2309. .XE
  2310. .LP
  2311. The properties that were described in the previous section are those 
  2312. that the client is responsible for maintaining on its top-level windows.
  2313. This section describes the properties that the window manager places on
  2314. client's top-level windows and on the root.
  2315. .NH 4
  2316. WM_STATE Property
  2317. .XS
  2318. \*(SN WM_STATE Property
  2319. .XE
  2320. .LP
  2321. The window manager will place a WM_STATE property (of type WM_STATE)
  2322. on each top-level client window.
  2323. In general,
  2324. clients should not need to examine the contents of this property;
  2325. it is intended for communication between window and session managers.
  2326. See section 5.1.1.3 for more details.
  2327. .NH 4
  2328. WM_ICON_SIZE Property
  2329. .XS
  2330. \*(SN WM_ICON_SIZE Property
  2331. .XE
  2332. .LP
  2333. A window manager that wishes to place constraints on the sizes of icon
  2334. pixmaps and/or windows should place a property called WM_ICON_SIZE on the root.
  2335. The contents of this property are listed in the following table. 
  2336. .TS H
  2337. l l l.
  2338. _
  2339. .sp 6p
  2340. .B
  2341. Field    Type    Comments
  2342. .sp 6p
  2343. _
  2344. .sp 6p
  2345. .TH
  2346. .R
  2347. min_width    CARD32    The data for the icon size series
  2348. min_height    CARD32
  2349. max_width    CARD32
  2350. max_height    CARD32
  2351. width_inc    CARD32
  2352. height_inc    CARD32
  2353. .sp 6p
  2354. _
  2355. .TE
  2356. .LP
  2357. For more details see section 14.1.12 in \fIXlib \- C Language X Interface\fP.
  2358. .NH 3
  2359. Changing Window State
  2360. .XS
  2361. \*(SN Changing Window State
  2362. .XE
  2363. .LP
  2364. From the client's point of view,
  2365. the window manager will regard each of the client's top-level 
  2366. nonoverride-redirect windows as being in one of three states,
  2367. whose semantics are as follows:
  2368. .IP \(bu 5
  2369. .PN NormalState
  2370. \- The client's top-level window is visible.
  2371. .IP \(bu 5
  2372. .PN IconicState
  2373. \- The client's top-level window is iconic
  2374. (whatever that means for this window manager).
  2375. The client can assume that its icon_window (if any) will be visible
  2376. and, failing that, 
  2377. its icon_pixmap (if any) or its WM_ICON_NAME will be visible.
  2378. .IP \(bu 5
  2379. .PN WithdrawnState
  2380. \- Neither the client's top-level window nor its icon are visible.
  2381. .LP
  2382. In fact,
  2383. the window manager may implement states with semantics 
  2384. other than those described above.
  2385. For example,
  2386. a window manager might implement a concept of InactiveState
  2387. in which an infrequently used client's window would be represented 
  2388. as a string in a menu.
  2389. But this state is invisible to the client,
  2390. which would see itself merely as being in IconicState.
  2391. .LP
  2392. Newly created top-level windows are in the Withdrawn state.
  2393. Once the window has been provided with suitable properties,
  2394. the client is free to change its state as follows:\s-2\u5\d\s0
  2395. .FS
  2396. 5.  The conventions described in earlier drafts of the ICCCM
  2397. had some serious semantic problems.
  2398. These new conventions are designed to be compatible with clients
  2399. using earlier conventions,  except in areas where the earlier
  2400. conventions would not actually have worked.
  2401. .FE
  2402. .IP \(bu 5
  2403. Withdrawn \(-> Normal \- The client should map the window with 
  2404. WM_HINTS.initial_state being 
  2405. .PN NormalState .
  2406. .IP \(bu 5
  2407. Withdrawn \(-> Iconic \- The client should map the window with 
  2408. WM_HINTS.initial_state being 
  2409. .PN IconicState .
  2410. .IP \(bu 5
  2411. Normal \(-> Iconic \- The client should send a client message event 
  2412. as described later in this section.
  2413. .IP \(bu 5
  2414. Normal \(-> Withdrawn \- The client should unmap the window and follow it 
  2415. with a synthetic 
  2416. .PN UnmapNotify
  2417. event as described later in this section.\s-2\u6\d\s0
  2418. .FS
  2419. 6.  For compatibility with obsolete clients, 
  2420. window managers should trigger the transition on the real 
  2421. .PN UnmapNotify
  2422. rather than wait for the synthetic one.
  2423. They should also trigger the transition if they receive a synthetic 
  2424. .PN UnmapNotify
  2425. on a window for which they have not yet received a real 
  2426. .PN UnmapNotify .
  2427. .FE
  2428. .IP \(bu 5
  2429. Iconic \(-> Normal \- The client should map the window.
  2430. The contents of WM_HINTS.initial_state are irrelevant in this case.
  2431. .IP \(bu 5
  2432. Iconic \(-> Withdrawn \- The client should unmap the window 
  2433. and follow it with a synthetic 
  2434. .PN UnmapNotify
  2435. event as described below.
  2436. .LP
  2437. Once a client's nonoverride-redirect top-level window
  2438. has left the Withdrawn state,
  2439. the client will know that the window is in the Normal state if it is mapped
  2440. and that the window is in the Iconic state if it is not mapped.
  2441. It may select for 
  2442. .PN StructureNotify
  2443. events on the top-level window,  
  2444. and it will receive an
  2445. .PN UnmapNotify
  2446. event when it moves to the Iconic state and a 
  2447. .PN MapNotify
  2448. event when it moves to the Normal state.
  2449. This implies that a reparenting window manager will unmap the
  2450. top-level window as well as the parent window when changing 
  2451. to the Iconic state.
  2452. .NT Convention
  2453. Reparenting window managers must unmap the client's top-level window
  2454. whenever they unmap the window to which they have reparented it.
  2455. .NE
  2456. .LP
  2457. If the transition is to the Withdrawn state,
  2458. a synthetic 
  2459. .PN UnmapNotify
  2460. event, in addition to unmapping the window itself, 
  2461. must be sent by using a
  2462. .PN SendEvent 
  2463. request with the following arguments:
  2464. .TS
  2465. l l.
  2466. _
  2467. .sp 6p
  2468. .B
  2469. Argument    Value
  2470. .sp 6p
  2471. _
  2472. .sp 6p
  2473. .R
  2474. destination:    The root
  2475. propagate:    T{
  2476. .PN False
  2477. T}
  2478. event-mask:    T{
  2479. .Pn ( SubstructureRedirect|SubstructureNotify )
  2480. T}
  2481. T{
  2482. event: an 
  2483. .PN UnmapNotify
  2484. with:
  2485. T}    T{
  2486. T}
  2487. \ \ \ \ \ \ \ \ event:    The root
  2488. \ \ \ \ \ \ \ \ window:    The window itself
  2489. \ \ \ \ \ \ \ \ from-configure:    T{
  2490. .PN False
  2491. T}
  2492. .sp 6p
  2493. _
  2494. .TE
  2495. .LP
  2496. The reason for doing this is to ensure that the window manager
  2497. gets some notification of the desire to change state,
  2498. even though the window may already be unmapped when the desire is expressed.
  2499. .LP
  2500. If the transition is from the Normal to the Iconic state,
  2501. the client should send a 
  2502. .PN ClientMessage 
  2503. event to the root with:
  2504. .IP \(bu 5
  2505. Window == the window to be iconified
  2506. .IP \(bu 5
  2507. Type == the atom WM_CHANGE_STATE\s-2\u7\d\s0
  2508. .FS
  2509. 7.  The type field of the 
  2510. .PN ClientMessage 
  2511. event (called the message_type field by Xlib) should not be confused with
  2512. the ``code'' field of the event itself,
  2513. which will have the value 33 
  2514. .Pn ( ClientMessage ).
  2515. .FE
  2516. .IP \(bu 5
  2517. Format == 32
  2518. .IP \(bu 5
  2519. Data[0] == IconicState\s-2\u8\d\s0
  2520. .FS
  2521. 8.  We use the notation data[n] to indicate the nth element 
  2522. of the LISTofINT8, LISTofINT16, or LISTofINT32 in the data field of the 
  2523. .PN ClientMessage ,
  2524. according to the format field.
  2525. The list is indexed from zero.
  2526. .FE
  2527. .LP
  2528. Other values of data[0] are reserved for future extensions to these
  2529. conventions.\s-2\u9\d\s0
  2530. .FS
  2531. 9.  The format of this 
  2532. .PN ClientMessage 
  2533. event does not match the format of 
  2534. .PN ClientMessages
  2535. in section 4.2.8.
  2536. This is because they are sent by the window manager to clients,
  2537. and this is sent by clients to the window manager.
  2538. .FE
  2539. The parameters of the 
  2540. .PN SendEvent 
  2541. event should be those described for the synthetic
  2542. .PN UnmapNotify
  2543. event.
  2544. .LP
  2545. Clients can also select for 
  2546. .PN VisibilityChange
  2547. events on their top-level or icon windows.
  2548. They will then receive a 
  2549. .PN VisibilityNotify (state==FullyObscured)
  2550. event when the window concerned becomes completely
  2551. obscured even though mapped (and thus, perhaps a waste
  2552. of time to update) and a 
  2553. .PN VisibilityNotify (state!=FullyObscured)
  2554. event when it becomes even partly viewable.
  2555. .NH 3
  2556. Configuring the Window
  2557. .XS
  2558. \*(SN Configuring the Window
  2559. .XE
  2560. .LP
  2561. Clients can resize and reposition their top-level windows by using the 
  2562. .PN ConfigureWindow 
  2563. request.
  2564. The attributes of the window that can be altered 
  2565. with this request are as follows:
  2566. .IP \(bu 5
  2567. The [x,y] location of the window's upper left-outer corner
  2568. .IP \(bu 5
  2569. The [width,height] of the inner region of the window (excluding
  2570. borders)
  2571. .IP \(bu 5
  2572. The border width of the window
  2573. .IP \(bu 5
  2574. The window's position in the stack
  2575. .LP
  2576. The coordinate system in which the location is expressed is that of the root
  2577. (irrespective of any reparenting that may have occurred).
  2578. The border width to be used and win_gravity position hint
  2579. to be used are those most recently requested by the client.
  2580. Client configure requests are interpreted by the window manager
  2581. in the same manner as the initial window geometry mapped from
  2582. the Withdrawn state, as described in section 4.1.2.3.
  2583. Clients must be aware that there is no guarantee that the window manager
  2584. will allocate them the requested size or location and must be prepared to
  2585. deal with any size and location.
  2586. If the window manager decides to respond to a 
  2587. .PN ConfigureRequest
  2588. request by:
  2589. .IP \(bu 5
  2590. Not changing the size or location of the window at all
  2591. .IP
  2592. A client will receive a synthetic 
  2593. .PN ConfigureNotify
  2594. event that describes the (unchanged) state of the window.
  2595. The (x,y) coordinates will be in the root coordinate system 
  2596. and adjusted for the border width the client requested,
  2597. irrespective of any reparenting that has taken place.
  2598. The border_width will be the border width the client requested.
  2599. The client will not receive a real
  2600. .PN ConfigureNotify
  2601. event because no change has actually taken place.
  2602. .IP \(bu 5
  2603. Moving the window without resizing it
  2604. .IP
  2605. A client will receive a synthetic 
  2606. .PN ConfigureNotify 
  2607. event following the move that describes the new state of the window, 
  2608. whose (x,y) coordinates will be in the root coordinate system adjusted 
  2609. for the border width the client requested.
  2610. The border_width will be the border width the client requested.
  2611. The client may not receive a real 
  2612. .PN ConfigureNotify
  2613. event that describes this change because the window manager may have reparented
  2614. the top-level window.
  2615. If the client does receive a real event,
  2616. the synthetic event will follow the real one.
  2617. .IP \(bu 5
  2618. Resizing the window (whether or not it is moved)
  2619. .IP
  2620. A client that has selected for 
  2621. .PN StructureNotify
  2622. events will receive a 
  2623. .PN ConfigureNotify
  2624. event.
  2625. Note that the coordinates in this event are relative to the parent,
  2626. which may not be the root if the window has been reparented.
  2627. The coordinates will reflect the actual border width of the window
  2628. (which the window manager may have changed).
  2629. The 
  2630. .PN TranslateCoordinates
  2631. request can be used to convert the coordinates if required.
  2632. .LP
  2633. The general rule is that coordinates in real 
  2634. .PN ConfigureNotify
  2635. events are in the parent's space; 
  2636. in synthetic events, they are in the root space.
  2637. .LP
  2638. Clients should be aware that their borders may not be visible.
  2639. Window managers are free to use reparenting techniques to
  2640. decorate client's top-level windows with borders containing
  2641. titles,  controls, and other details to maintain a consistent look-and-feel.
  2642. If they do,
  2643. they are likely to override the client's attempts to set the border width
  2644. and set it to zero.
  2645. Clients, therefore, should not depend on the top-level window's border 
  2646. being visible or use it to display any critical information.
  2647. Other window managers will allow the top-level windows border to
  2648. be visible.
  2649. .NT Convention
  2650. Clients should set the desired value of the border-width attribute on all 
  2651. .PN ConfigureWindow
  2652. requests to avoid a race condition.
  2653. .NE
  2654. .LP
  2655. Clients that change their position in the stack must be aware 
  2656. that they may have been reparented,
  2657. which means that windows that used to be siblings no longer are.
  2658. Using a nonsibling as the sibling parameter on a 
  2659. .PN ConfigureWindow 
  2660. request will cause an error.
  2661. .NT Convention
  2662. Clients that use a
  2663. .PN ConfigureWindow
  2664. request to request a change in their position in the stack 
  2665. should do so using 
  2666. .PN None
  2667. in the sibling field.
  2668. .NE
  2669. .LP
  2670. Clients that must position themselves in the stack relative to some
  2671. window that was originally a sibling must do the 
  2672. .PN ConfigureWindow
  2673. request (in case they are running under a nonreparenting window manager),
  2674. be prepared to deal with a resulting error,
  2675. and then follow with a synthetic 
  2676. .PN ConfigureRequest 
  2677. event by invoking a
  2678. .PN SendEvent
  2679. request with the following arguments:
  2680. .TS
  2681. l l.
  2682. _
  2683. .sp 6p
  2684. .B
  2685. Argument    Value
  2686. .sp 6p
  2687. _
  2688. .sp 6p
  2689. .R
  2690. destination:    The root
  2691. propagate:    T{
  2692. .PN False
  2693. T}
  2694. event-mask:    T{
  2695. .Pn ( SubstructureRedirect|SubstructureNotify )
  2696. T}
  2697. T{
  2698. event: a 
  2699. .PN ConfigureRequest 
  2700. with:
  2701. T}    T{
  2702. T}
  2703. \ \ \ \ \ \ \ \ event:    The root
  2704. \ \ \ \ \ \ \ \ window:    The window itself
  2705. T{
  2706. \ \ \ \ \ \ \ \ ....
  2707. T}    T{
  2708. Other parameters from the
  2709. .PN ConfigureWindow
  2710. T}
  2711. .sp 6p
  2712. _
  2713. .TE
  2714. .LP
  2715. Doing this is deprecated,
  2716. and window managers are in any case free to position windows in the stack
  2717. as they see fit.
  2718. Clients should ignore the above field of both real and synthetic
  2719. .PN ConfigureNotify
  2720. events that they receive on their nonoverride-redirect top-level windows
  2721. because they cannot be guaranteed to contain useful information.
  2722. .NH 3
  2723. Changing Window Attributes
  2724. .XS
  2725. \*(SN Changing Window Attributes
  2726. .XE
  2727. .LP
  2728. The attributes that may be supplied when a window is created may be
  2729. changed by using the 
  2730. .PN ChangeWindowAttributes
  2731. request.
  2732. The window attributes are listed in the following table.
  2733. .TS H
  2734. l l
  2735. l c.
  2736. _
  2737. .sp 6p
  2738. .B
  2739. Attribute    Private to Client
  2740. .sp 6p
  2741. _
  2742. .sp 6p
  2743. .TH
  2744. .R
  2745. Background pixmap    Yes
  2746. Background pixel    Yes
  2747. Border pixmap    Yes
  2748. Border pixel    Yes
  2749. Bit gravity    Yes
  2750. Window gravity    No
  2751. Backing-store hint    Yes
  2752. Save-under hint    No
  2753. Event mask    No
  2754. Do-Not-propagate mask    Yes
  2755. Override-redirect flag    No
  2756. Colormap    Yes
  2757. Cursor    Yes
  2758. .sp 6p
  2759. _
  2760. .TE
  2761. .LP
  2762. Most attributes are private to the client and will never be interfered with
  2763. by the window manager.
  2764. For the attributes that are not private to the client:
  2765. .IP \(bu 5
  2766. The window manager is free to override the window gravity;
  2767. a reparenting window manager may want to set the top-level window's
  2768. window gravity for its own purposes.
  2769. .IP \(bu 5
  2770. Clients are free to set the save-under hint on their top-level windows,
  2771. but they must be aware that the hint may be overridden by the window manager.
  2772. .IP \(bu 5
  2773. Windows, in effect, have per-client event masks,
  2774. and so, clients may select for whatever events are convenient irrespective 
  2775. of any events the window manager is selecting for.
  2776. There are some events for which only one client at a time may select,
  2777. but the window manager should not select for them on any of the client's
  2778. windows.
  2779. .IP \(bu 5
  2780. Clients can set override-redirect on top-level windows but are
  2781. encouraged not to do so except as described in sections 4.1.10 and 4.2.9.
  2782. .NH 3
  2783. Input Focus
  2784. .XS
  2785. \*(SN Input Focus
  2786. .XE
  2787. .LP
  2788. There are four models of input handling:
  2789. .IP \(bu 5
  2790. No Input \- The client never expects keyboard input.
  2791. An example would be 
  2792. .PN xload
  2793. or another output-only client.
  2794. .IP \(bu 5
  2795. Passive Input \- The client expects keyboard input but never explicitly sets 
  2796. the input focus.
  2797. An example would be a simple client with no subwindows,
  2798. which will accept input in 
  2799. .PN PointerRoot
  2800. mode or when the window manager sets the input focus to its top-level window 
  2801. (in click-to-type mode).
  2802. .IP \(bu 5
  2803. Locally Active Input \- The client expects keyboard input and explicitly sets 
  2804. the input focus, 
  2805. but it only does so when one of its windows already has the focus.
  2806. An example would be a client with subwindows defining various data
  2807. entry fields that uses Next and Prev keys to move the input focus
  2808. between the fields.
  2809. It does so when its top-level window has acquired the focus in 
  2810. .PN PointerRoot
  2811. mode or when the window manager sets the input focus to its top-level window 
  2812. (in click-to-type mode).
  2813. .IP \(bu 5
  2814. Globally Active Input \- The client expects keyboard input and explicitly sets 
  2815. the input focus, 
  2816. even when it is in windows the client does not own.
  2817. An example would be a client with a scroll bar that wants to allow
  2818. users to scroll the window without disturbing the input focus even if
  2819. it is in some other window.
  2820. It wants to acquire the input focus when the user clicks in the scrolled
  2821. region but not when the user clicks in the scroll bar itself.
  2822. Thus, it wants to prevent the window manager from setting the input focus 
  2823. to any of its windows.
  2824. .LP
  2825. The four input models and the corresponding values of the input field
  2826. and the presence or absence of the WM_TAKE_FOCUS atom in the
  2827. WM_PROTOCOLS property are listed in the following table:
  2828. .TS H
  2829. l l l
  2830. l c c.
  2831. _
  2832. .sp 6p
  2833. .B
  2834. Input Model    Input Field    WM_TAKE_FOCUS
  2835. .sp 6p
  2836. _
  2837. .sp 6p
  2838. .TH
  2839. .R
  2840. T{
  2841. No Input
  2842. T}    T{
  2843. .PN False
  2844. T}    T{
  2845. Absent
  2846. T}
  2847. T{
  2848. Passive
  2849. T}    T{
  2850. .PN True
  2851. T}    T{
  2852. Absent
  2853. T}
  2854. T{
  2855. Locally Active
  2856. T}    T{
  2857. .PN True
  2858. T}    T{
  2859. Present
  2860. T}
  2861. T{
  2862. Globally Active
  2863. T}    T{
  2864. .PN False
  2865. T}    T{
  2866. Present
  2867. T}
  2868. .sp 6p
  2869. _
  2870. .TE
  2871. .LP
  2872. Passive and Locally Active clients set the input field of WM_HINTS to
  2873. .PN True ,
  2874. which indicates that they require window manager assistance  in acquiring the
  2875. input focus.
  2876. No Input and Globally Active clients set the input field to
  2877. .PN False ,
  2878. which requests that the window manager not set the input focus 
  2879. to their top-level window.
  2880. .LP
  2881. Clients that use a
  2882. .PN SetInputFocus
  2883. request must set the time field to the timestamp of the event 
  2884. that caused them to make the attempt.
  2885. This cannot be a 
  2886. .PN FocusIn
  2887. event because they do not have timestamps.
  2888. Clients may also acquire 
  2889. the focus without a corresponding 
  2890. .PN EnterNotify .
  2891. Note that clients must not use 
  2892. .PN CurrentTime 
  2893. in the time field.
  2894. .LP
  2895. Clients using the Globally Active model can only use a
  2896. .PN SetInputFocus
  2897. request to acquire the input focus when they do not already have it on
  2898. receipt of one of the following events:
  2899. .IP \(bu 5
  2900. .PN ButtonPress
  2901. .IP \(bu 5
  2902. .PN ButtonRelease
  2903. .IP \(bu 5
  2904. Passive-grabbed 
  2905. .PN KeyPress
  2906. .IP \(bu 5
  2907. Passive-grabbed
  2908. .PN KeyRelease
  2909. .LP
  2910. In general,
  2911. clients should avoid using passive-grabbed key events for this purpose,
  2912. except when they are unavoidable (as, for example, a selection tool 
  2913. that establishes a passive grab on the keys that cut,  copy,  or paste).
  2914. .LP
  2915. The method by which the user commands the window manager to
  2916. set the focus to a window is up to the window manager.
  2917. For example, 
  2918. clients cannot determine whether they will see the click 
  2919. that transfers the focus.
  2920. .LP
  2921. Windows with the atom WM_TAKE_FOCUS in their WM_PROTOCOLS property
  2922. may receive a 
  2923. .PN ClientMessage 
  2924. event from the window manager (as described in section 4.2.8)
  2925. with WM_TAKE_FOCUS in their data[0] field.
  2926. If they want the focus,
  2927. they should respond with a 
  2928. .PN SetInputFocus
  2929. request with its window field set to the window of theirs 
  2930. that last had the input focus or to their ``default input window,''
  2931. and the time field set to the timestamp in the message.
  2932. For further information,
  2933. see section 4.2.7.
  2934. .LP
  2935. A client could receive WM_TAKE_FOCUS when opening from an icon
  2936. or when the user has clicked outside the top-level window in an area that
  2937. indicates to the window manager that it should assign the focus 
  2938. (for example, clicking in the headline bar can be used to assign the focus).
  2939. .LP
  2940. The goal is to support window managers that want to assign the input focus
  2941. to a top-level window in such a way that the top-level window either
  2942. can assign it to one of its subwindows or can decline the offer of the focus.
  2943. For example, a clock or a text editor with no currently open frames 
  2944. might not want to take focus even though the window manager generally 
  2945. believes that clients should take the input focus after being deiconified 
  2946. or raised.
  2947. .NT Problem
  2948. There would be no need for WM_TAKE_FOCUS if the 
  2949. .PN FocusIn
  2950. event contained a timestamp and a previous-focus field.
  2951. This could avoid the potential race condition.
  2952. There is space in the event for this information;
  2953. it should be added at the next protocol revision.
  2954. .NE
  2955. .LP
  2956. Clients that set the input focus need to decide a value for the
  2957. revert-to field of the 
  2958. .PN SetInputFocus
  2959. request.
  2960. This determines the behavior of the input focus 
  2961. if the window the focus has been set to becomes not viewable.
  2962. The value can be any of the following:
  2963. .IP \(bu 5
  2964. .PN Parent
  2965. \- In general, 
  2966. clients should use this value when assigning focus to one of their subwindows.
  2967. Unmapping the subwindow will cause focus to revert to the parent,
  2968. which is probably what you want.
  2969. .IP \(bu 5
  2970. .PN PointerRoot 
  2971. \- Using
  2972. this value with a click-to-type focus management policy
  2973. leads to race conditions because the window becoming unviewable may
  2974. coincide with the window manager deciding to move the focus elsewhere.
  2975. .IP \(bu 5
  2976. .PN None 
  2977. \- Using
  2978. this value causes problems if the window manager reparents 
  2979. the window, as most window managers will, and then crashes.
  2980. The input focus will be 
  2981. .PN None , 
  2982. and there will probably be no way to change it.
  2983. .KE
  2984. .LP
  2985. Note that neither
  2986. .PN PointerRoot
  2987. nor
  2988. .PN None
  2989. is really safe to use.
  2990. .NT Convention
  2991. Clients that invoke a
  2992. .PN SetInputFocus 
  2993. request should set the revert-to argument to 
  2994. .PN Parent .
  2995. .NE
  2996. .LP
  2997. A convention is also required for clients that want to give up the
  2998. input focus.
  2999. There is no safe value set for them to set the input focus to;
  3000. therefore, they should ignore input material.
  3001. .NT Convention
  3002. Clients should not give up the input focus of their own volition.
  3003. They should ignore input that they receive instead.
  3004. .NE
  3005. .NH 3
  3006. Colormaps
  3007. .XS
  3008. \*(SN Colormaps
  3009. .XE
  3010. .LP
  3011. The window manager is responsible for installing and uninstalling 
  3012. colormaps.\s-2\u10\d\s0
  3013. .FS
  3014. 10.  The conventions described in earlier drafts by which clients 
  3015. and window managers shared responsibility for installing colormaps 
  3016. suffered from semantic problems.
  3017. .FE
  3018. Clients provide the window manager with hints as to which colormaps to 
  3019. install and uninstall,
  3020. but clients must not install or uninstall colormaps themselves.
  3021. When a client's top-level window gets the colormap focus
  3022. (as a result of whatever colormap focus policy is implemented 
  3023. by the window manager),
  3024. the window manager will insure that one or more of the client's colormaps 
  3025. are installed.
  3026. The reason for this convention is that there is no safe way for
  3027. multiple clients to install and uninstall colormaps.
  3028. .NT Convention
  3029. Clients must not use 
  3030. .PN InstallColormap 
  3031. or 
  3032. .PN UninstallColormap
  3033. requests.
  3034. .NE
  3035. .LP
  3036. There are two possible ways in which clients could hint to the window
  3037. manager about the colormaps they want installed.
  3038. Using a property, 
  3039. they could tell the window manager one of the following:
  3040. .IP \(bu 5
  3041. A priority ordered list of the colormaps they want installed
  3042. .IP \(bu 5
  3043. A priority ordered list of the windows whose colormaps they want installed
  3044. .LP
  3045. The second of these alternatives has been selected because:
  3046. .IP \(bu 5
  3047. It allows window managers to know the visuals for the colormaps, thus,
  3048. permitting visual-dependent colormap installation policies.
  3049. .IP \(bu 5
  3050. It allows window managers to select for 
  3051. .PN VisibilityChange
  3052. events on the windows concerned and ensure that maps are only installed 
  3053. if the windows that need them are visible.
  3054. .LP
  3055. Clients whose top-level windows and subwindows all use the same colormap
  3056. should set its ID in the colormap field of the window's attributes.
  3057. They should not set a WM_COLORMAP_WINDOWS property on the top-level window.
  3058. If they want to change the colormap,  they should change the window
  3059. attribute.
  3060. The window manager will install the colormap for them.
  3061. .LP
  3062. Clients that create windows can use the value 
  3063. .PN CopyFromParent
  3064. to inherit their parent's colormap.
  3065. Window managers will ensure that the root window's colormap field
  3066. contains a colormap that is suitable for clients to inherit.
  3067. In particular, the colormap will provide distinguishable colors for 
  3068. .PN BlackPixel 
  3069. and 
  3070. .PN WhitePixel .
  3071. .LP
  3072. Top-level windows that have subwindows or override-redirect pop-up windows
  3073. whose colormap requirements differ from the top-level window
  3074. should have a WM_COLORMAP_WINDOWS property.
  3075. This property contains a list of IDs for windows 
  3076. whose colormaps the window manager should attempt to have installed
  3077. when, in the course of its individual colormap focus policy,
  3078. it assigns the colormap focus to the top-level window (see
  3079. section 4.1.2.8).
  3080. The list is ordered by the importance to the client of having the
  3081. colormaps installed.
  3082. If this order changes,
  3083. the property should be updated.
  3084. The window manager will track changes to this property
  3085. and will track changes to the colormap attribute of the windows in the property.
  3086. .LP
  3087. WM_TRANSIENT_FOR windows either can have their own WM_COLORMAP_WINDOWS
  3088. property or can appear in the property of the window they are transient for,
  3089. as appropriate.
  3090. .LP
  3091. Clients should be aware of the min-installed-maps and max-installed-maps 
  3092. fields of the connection startup information, and the effect that the minimum
  3093. value has on the so-called ``required list:''
  3094. .QP
  3095. At any time, 
  3096. there is a subset of the installed maps, 
  3097. viewed as an ordered list, called the required list.
  3098. The length of the required list is at most M, 
  3099. where M is the min-installed-maps specified for the screen 
  3100. in the connection setup.
  3101. The required list is maintained as follows.
  3102. When a colormap is an explicit argument to 
  3103. .PN InstallColormap ,
  3104. it is added to the head of the list, 
  3105. and the list is truncated at the tail if necessary to keep the length 
  3106. of the list to at most M.
  3107. When a colormap is an explicit argument to 
  3108. .PN UninstallColormap
  3109. and it is in the required list, it is removed from the list.
  3110. A colormap is not added to the required list when it is installed implicitly 
  3111. by the server, and the server cannot implicitly uninstall a colormap 
  3112. that is in the required list.
  3113. .LP
  3114. In less precise words, 
  3115. the min-installed-maps most recently installed maps are guaranteed 
  3116. to be installed.
  3117. Min-installed-maps will often be one;
  3118. clients needing multiple colormaps should beware.
  3119. .LP
  3120. The window manager will identify and track changes to the colormap attribute
  3121. of the windows identified by the WM_COLORMAP_WINDOWS property
  3122. and the top-level window if it does not appear in the list.
  3123. If the top-level window does not appear in the list,
  3124. it will be assumed to be higher priority than any window in the list.
  3125. It will also track changes in the contents of the WM_COLORMAP_WINDOWS property,
  3126. in case the set of windows or their relative priority changes.
  3127. The window manager will define some colormap focus policy and,
  3128. whenever the top-level window has the colormap focus,
  3129. will attempt to maximize the number of colormaps from the head 
  3130. of the WM_COLORMAP_WINDOWS list that is installed.
  3131. .NH 3
  3132. Icons
  3133. .XS
  3134. \*(SN Icons
  3135. .XE
  3136. .LP
  3137. A client can hint to the window manager about the desired appearance 
  3138. of its icon by setting:
  3139. .IP \(bu 5
  3140. A string in WM_ICON_NAME
  3141. .IP
  3142. All clients should do this  
  3143. because it provides a fallback for window managers whose ideas 
  3144. about icons differ widely from those of the client.
  3145. .IP \(bu 5
  3146. A 
  3147. .PN Pixmap 
  3148. into the icon_pixmap field of the WM_HINTS property
  3149. and possibly another into the icon_mask field 
  3150. .IP
  3151. The window manager is expected to display the pixmap masked by the mask.
  3152. The pixmap should be one of the sizes found in the WM_ICON_SIZE property
  3153. on the root.
  3154. If this property is not found,
  3155. the window manager is unlikely to display icon pixmaps.
  3156. Window managers usually will clip or tile pixmaps that do not match
  3157. WM_ICON_SIZE.
  3158. .IP \(bu 5
  3159. A window into the icon_window field of the WM_HINTS property
  3160. .IP
  3161. The window manager is expected to map that window whenever the client is
  3162. in the Iconic state.
  3163. In general,
  3164. the size of the icon window should be one of those specified in WM_ICON_SIZE 
  3165. on the root, if it exists.
  3166. Window managers are free to resize icon windows.
  3167. .LP
  3168. In the Iconic state,
  3169. the window manager usually will ensure that:
  3170. .IP \(bu 5
  3171. If the window's WM_HINTS.icon_window is set,
  3172. the window it names is visible.
  3173. .IP \(bu 5
  3174. If the window's WM_HINTS.icon_window is not set
  3175. but the window's WM_HINTS.icon_pixmap is set,
  3176. the pixmap it names is visible.
  3177. .IP \(bu 5
  3178. Otherwise,
  3179. the window's WM_ICON_NAME string is visible.
  3180. .LP
  3181. Clients should observe the following conventions about their icon windows:
  3182. .NT Conventions
  3183. .IP 1. 5
  3184. The icon window should be an 
  3185. .PN InputOutput
  3186. child of the root.
  3187. .IP 2. 5
  3188. The icon window should be one of the sizes specified 
  3189. in the WM_ICON_SIZE property on the root.
  3190. .IP 3. 5
  3191. The icon window should use the root visual and default colormap 
  3192. for the screen in question.
  3193. .IP 4. 5
  3194. Clients should not map their icon windows.
  3195. .IP 5. 5
  3196. Clients should not unmap their icon windows.
  3197. .IP 6. 5
  3198. Clients should not configure their icon windows.
  3199. .IP 7. 5
  3200. Clients should not set override-redirect on their icon windows
  3201. or select for 
  3202. .PN ResizeRedirect 
  3203. events on them.
  3204. .IP 8. 5
  3205. Clients must not depend on being able to receive input events
  3206. by means of their icon windows.
  3207. .IP 9. 5
  3208. Clients must not manipulate the borders of their icon windows.
  3209. .IP 10. 5
  3210. Clients must select for 
  3211. .PN Exposure
  3212. events on their icon window and repaint it when requested.
  3213. .NE
  3214. .LP
  3215. Window managers will differ as to whether they support input events
  3216. to client's icon windows;
  3217. most will allow the client to receive some subset of the keys and buttons.
  3218. .LP
  3219. Window managers will ignore any WM_NAME, WM_ICON_NAME, WM_NORMAL_HINTS,
  3220. WM_HINTS, WM_CLASS, WM_TRANSIENT_FOR, WM_PROTOCOLS, or WM_COLORMAP_WINDOWS
  3221. properties they find on icon windows.
  3222. Session managers will ignore any WM_COMMAND or WM_CLIENT_MACHINE
  3223. properties they find on icon windows.
  3224. .NH 3
  3225. Pop-up Windows
  3226. .XS
  3227. \*(SN Pop-up Windows
  3228. .XE
  3229. .LP
  3230. Clients that wish to pop up a window can do one of three things:
  3231. .IP 1. 5
  3232. They can create and map another normal top-level window,
  3233. which will get decorated and managed as normal by the window manager.
  3234. See the discussion of window groups that follows.
  3235. .IP 2. 5
  3236. If the window will be visible for a relatively short time
  3237. and deserves a somewhat lighter treatment,
  3238. they can set the WM_TRANSIENT_FOR property.
  3239. They can expect less decoration but can set all the normal
  3240. window manager properties on the window.
  3241. An example would be a dialog box.
  3242. .IP 3. 5
  3243. If the window will be visible for a very short time
  3244. and should not be decorated at all,
  3245. the client can set override-redirect on the window.
  3246. In general,
  3247. this should be done only if the pointer is grabbed while the window is mapped.
  3248. The window manager will never interfere with these windows,
  3249. which should be used with caution.
  3250. An example of an appropriate use is a pop-up menu.
  3251. .LP
  3252. Window managers are free to decide if WM_TRANSIENT_FOR windows
  3253. should be iconified when the window they are transient for is.
  3254. Clients displaying WM_TRANSIENT_FOR windows that have 
  3255. (or request to have) the window they are transient for iconified
  3256. do not need to request that the same operation be performed
  3257. on the WM_TRANSIENT_FOR window;
  3258. the window manager will change its state if that is the policy it wishes 
  3259. to enforce.
  3260. .NH 3
  3261. Window Groups
  3262. .XS
  3263. \*(SN Window Groups
  3264. .XE
  3265. .LP
  3266. A set of top-level windows that should be treated from the user's point of view
  3267. as related (even though they may belong to a number of clients) should be linked
  3268. together using the window_group field of the WM_HINTS structure.
  3269. .LP
  3270. One of the windows (that is, the one the others point to) 
  3271. will be the group leader and will carry the group as opposed 
  3272. to the individual properties.
  3273. Window managers may treat the group leader differently 
  3274. from other windows in the group.
  3275. For example,
  3276. group leaders may have the full set of decorations,
  3277. and other group members may have a restricted set.
  3278. .LP
  3279. It is not necessary that the client ever map the group leader;
  3280. it may be a window that exists solely as a placeholder.
  3281. .LP
  3282. It is up to the window manager to determine the policy 
  3283. for treating the windows in a group.
  3284. At present, 
  3285. there is no way for a client to request a group, 
  3286. as opposed to an individual, operation.
  3287. .NH 2
  3288. Client Responses to Window Manager Actions
  3289. .XS
  3290. \*(SN Client Responses to Window Manager Actions
  3291. .XE
  3292. .LP
  3293. The window manager performs a number of operations on client resources,
  3294. primarily on their top-level windows.
  3295. Clients must not try to fight this but may elect to receive notification 
  3296. of the window manager's operations.
  3297. .NH 3
  3298. Reparenting
  3299. .XS
  3300. \*(SN Reparenting
  3301. .XE
  3302. .LP
  3303. Clients must be aware that some window managers will reparent 
  3304. their nonoverride-redirect top-level windows
  3305. so that a window that was created as a child of the root will be displayed 
  3306. as a child of some window belonging to the window manager.
  3307. The effects that this reparenting will have on the client are as follows:
  3308. .IP \(bu 5
  3309. The parent value returned by a 
  3310. .PN QueryTree
  3311. request will no longer be the value supplied to the 
  3312. .PN CreateWindow 
  3313. request that created the reparented window.
  3314. There should be no need for the client to be aware of the identity 
  3315. of the window to which the top-level window has been reparented.
  3316. In particular,
  3317. a client that wishes to create further top-level windows should continue 
  3318. to use the root as the parent for these new windows.
  3319. .IP \(bu 5
  3320. The server will interpret the (x,y) coordinates in a 
  3321. .PN ConfigureWindow
  3322. request in the new parent's coordinate space.
  3323. In fact, they usually will not be interpreted by the server
  3324. because a reparenting window manager usually will have intercepted
  3325. these operations (see section 4.2.2).
  3326. Clients should use the root coordinate space for these requests
  3327. (see section 4.1.5).
  3328. .IP \(bu 5
  3329. .PN ConfigureWindow
  3330. requests that name a specific sibling window may fail because the window named,
  3331. which used to be a sibling, no longer is after the reparenting operation
  3332. (see section 4.1.5).
  3333. .IP \(bu 5
  3334. The (x,y) coordinates returned by a 
  3335. .PN GetGeometry
  3336. request are in the parent's coordinate space 
  3337. and are thus not directly useful after a reparent operation.
  3338. .IP \(bu 5
  3339. A background of 
  3340. .PN ParentRelative
  3341. will have unpredictable results.
  3342. .IP \(bu 5
  3343. A cursor of 
  3344. .PN None
  3345. will have unpredictable results.
  3346. .LP
  3347. Clients that want to be notified when they are reparented can select for
  3348. .PN StructureNotify
  3349. events on their top-level window.
  3350. They will receive a 
  3351. .PN ReparentNotify
  3352. event if and when reparenting takes place.
  3353. .LP
  3354. If the window manager reparents a client's window,
  3355. the reparented window will be placed in the save-set 
  3356. of the parent window.
  3357. This means that the reparented window will not be destroyed 
  3358. if the window manager terminates and will be remapped if it was unmapped.
  3359. Note that this applies to all client windows the window manager reparents,
  3360. including transient windows and client icon windows.
  3361. .LP
  3362. When the window manager gives up control over a client's top-level window,
  3363. it will reparent it (and any associated windows, for example, WM_TRANSIENT_FOR
  3364. windows) back to the root.
  3365. .LP
  3366. There is a potential race condition here.
  3367. A client might want to reuse the top-level window, 
  3368. reparenting it somewhere else.
  3369. .NT Convention
  3370. Clients that want to reparent their top-level windows should do so
  3371. only when they have their original parents.
  3372. They may select for 
  3373. .PN StructureNotify 
  3374. events on their top-level windows and will receive 
  3375. .PN ReparentNotify
  3376. events informing them when this is true.
  3377. .NE
  3378. .NH 3
  3379. Redirection of Operations
  3380. .XS
  3381. \*(SN Redirection of Operations
  3382. .XE
  3383. .LP
  3384. Clients must be aware that some window managers will arrange 
  3385. for some client requests to be intercepted and redirected.
  3386. Redirected requests are not executed; 
  3387. they result instead in events being sent to the window manager,
  3388. which may decide to do nothing, to alter the arguments, 
  3389. or to perform the request on behalf of the client.
  3390. .LP
  3391. The possibility that a request may be redirected means 
  3392. that a client cannot assume that any redirectable request is actually
  3393. performed when the request is issued or is actually performed at all.
  3394. For example,  the following is incorrect because the 
  3395. .PN MapWindow
  3396. request may be intercepted and the
  3397. .PN PolyLine
  3398. output made to an unmapped window:
  3399. .LP
  3400. .DS
  3401. MapWindow A
  3402. PolyLine A GC <point> <point> ....
  3403. .DE
  3404. .LP
  3405. The client must wait for an 
  3406. .PN Expose
  3407. event before drawing in the window.\s-2\u11\d\s0
  3408. .FS
  3409. 11.  This is true even if the client set the backing-store attribute to 
  3410. .PN Always .
  3411. The backing-store attribute is a only a hint, 
  3412. and the server may stop maintaining backing store contents at any time.
  3413. .FE
  3414. .LP
  3415. This next example incorrectly assumes that the 
  3416. .PN ConfigureWindow
  3417. request is actually executed with the arguments supplied:
  3418. .LP
  3419. .DS
  3420. ConfigureWindow width=N height=M
  3421. <output assuming window is N by M>
  3422. .DE
  3423. .LP
  3424. .LP
  3425. The requests that may be redirected are:
  3426. .IP \(bu 5
  3427. MapWindow
  3428. .IP \(bu 5
  3429. ConfigureWindow
  3430. .IP \(bu 5
  3431. CirculateWindow
  3432. .LP
  3433. A window with the override-redirect bit set is immune from redirection,
  3434. but the bit should be set on top-level windows only in cases 
  3435. where other windows should be prevented from processing input
  3436. while the override-redirect window is mapped (see section 4.1.10)
  3437. and while responding to 
  3438. .PN ResizeRequest
  3439. events (see section 4.2.9).
  3440. .LP
  3441. Clients that have no non-Withdrawn top-level windows 
  3442. and that map an override-redirect top-level window are taking over total
  3443. responsibility for the state of the system.
  3444. It is their responsibility to:
  3445. .IP \(bu 5
  3446. Prevent any preexisting window manager from interfering with their activities
  3447. .IP \(bu 5
  3448. Restore the status quo exactly after they unmap the window
  3449. so that any preexisting window manager does not get confused
  3450. .LP
  3451. In effect,  clients of this kind are acting as temporary window managers.
  3452. Doing so is strongly discouraged because these clients will be unaware
  3453. of the user interface policies the window manager is trying to maintain
  3454. and because their user interface behavior is likely to conflict with that of
  3455. less demanding clients.
  3456. .NH 3
  3457. Window Move
  3458. .XS
  3459. \*(SN Window Move
  3460. .XE
  3461. .LP
  3462. If the window manager moves a top-level window without changing its size,
  3463. the client will receive a synthetic 
  3464. .PN ConfigureNotify
  3465. event following the move that describes the new location
  3466. in terms of the root coordinate space.
  3467. Clients must not respond to being moved by attempting to move
  3468. themselves to a better location.
  3469. .LP
  3470. Any real 
  3471. .PN ConfigureNotify
  3472. event on a top-level window implies that the window's position 
  3473. on the root may have changed,
  3474. even though the event reports that the window's position 
  3475. in its parent is unchanged because the window may have been reparented.
  3476. Note that the coordinates in the event will not, in this case,
  3477. be directly useful.
  3478. .LP
  3479. The window manager will send these events by using a
  3480. .PN SendEvent
  3481. request with the following arguments:
  3482. .TS
  3483. l l.
  3484. _
  3485. .sp 6p
  3486. .B
  3487. Argument    Value
  3488. .sp 6p
  3489. _
  3490. .sp 6p
  3491. .R
  3492. destination:    The client's window
  3493. propagate:    T{
  3494. .PN False
  3495. T}
  3496. event-mask:    T{
  3497. .PN StructureNotify
  3498. T}
  3499. .sp 6p
  3500. _
  3501. .TE
  3502. .NH 3
  3503. Window Resize
  3504. .XS
  3505. \*(SN Window Resize
  3506. .XE
  3507. .LP
  3508. The client can elect to receive notification of being resized by selecting for
  3509. .PN StructureNotify
  3510. events on its top-level windows.
  3511. It will receive a 
  3512. .PN ConfigureNotify
  3513. event.
  3514. The size information in the event will be correct,
  3515. but the location will be in the parent window (which may not be the root).
  3516. .LP
  3517. The response of the client to being resized should be to accept
  3518. the size it has been given and to do its best with it.
  3519. Clients must not respond to being resized by attempting to resize
  3520. themselves to a better size.
  3521. If the size is impossible to work with,
  3522. clients are free to request to change to the Iconic state.
  3523. .NH 3
  3524. Iconify and Deiconify
  3525. .XS
  3526. \*(SN Iconify and Deiconify
  3527. .XE
  3528. .LP
  3529. A nonoverride-redirect window that is not Withdrawn will be 
  3530. in the Normal state if it is mapped and in the Iconic state if it is unmapped.
  3531. This will be true even if the window has been reparented;
  3532. the window manager will unmap the window as well as its parent
  3533. when switching to the Iconic state.
  3534. .LP
  3535. The client can elect to be notified of these state changes by selecting for 
  3536. .PN StructureNotify 
  3537. events on the top-level window.
  3538. It will receive a
  3539. .PN UnmapNotify
  3540. event when it goes Iconic and a
  3541. .PN MapNotify
  3542. event when it goes Normal.
  3543. .NH 3
  3544. Colormap Change
  3545. .XS
  3546. \*(SN Colormap Change
  3547. .XE
  3548. .LP
  3549. Clients that wish to be notified of their colormaps being installed
  3550. or uninstalled should select for 
  3551. .PN ColormapNotify
  3552. events on their top-level windows and on any windows they have named 
  3553. in WM_COLORMAP_WINDOWS properties on their top-level windows.
  3554. They will receive 
  3555. .PN ColormapNotify
  3556. events with the new field FALSE when the colormap for that window 
  3557. is installed or uninstalled.
  3558. .NT Problem
  3559. There is an inadequacy in the protocol.
  3560. At the next revision, the 
  3561. .PN InstallColormap
  3562. request should be changed to include a timestamp to avoid the possibility 
  3563. of race conditions if more than one client attempts to install 
  3564. and uninstall colormaps.
  3565. These conventions attempt to avoid the problem by restricting use
  3566. of these requests to the window manager.
  3567. .NE
  3568. .NH 3
  3569. Input Focus
  3570. .XS
  3571. \*(SN Input Focus
  3572. .XE
  3573. .LP
  3574. Clients can request notification that they have the input focus by selecting
  3575. for 
  3576. .PN FocusChange
  3577. events on their top-level windows;
  3578. they will receive 
  3579. .PN FocusIn 
  3580. and 
  3581. .PN FocusOut
  3582. events.
  3583. Clients that need to set the input focus to one of their
  3584. subwindows should not do so unless
  3585. they have set WM_TAKE_FOCUS in their WM_PROTOCOLS property 
  3586. and have done one of the following:
  3587. .IP \(bu 5
  3588. Set the input field of WM_HINTS to 
  3589. .PN True
  3590. and actually have the input focus in one of their top-level windows
  3591. .IP \(bu 5
  3592. Set the input field of WM_HINTS to 
  3593. .PN False
  3594. and have received a suitable event as described in section 4.1.7
  3595. .IP \(bu 5
  3596. Have received a WM_TAKE_FOCUS message as described in section 4.1.7
  3597. .LP
  3598. Clients should not warp the pointer in an attempt to transfer the focus;
  3599. they should set the focus and leave the pointer alone.
  3600. For further information,
  3601. see section 6.2.
  3602. .LP
  3603. Once a client satisfies these conditions,
  3604. it may transfer the focus to another of its windows by using the 
  3605. .PN SetInputFocus
  3606. request, which is defined as follows:
  3607. .LP
  3608. .\" Start marker code here
  3609. .IN "SetInputFocus" "" "@DEF@"
  3610. .PN SetInputFocus
  3611. .in +.2i
  3612. .LP
  3613. \fIfocus\fP\^: WINDOW or
  3614. .PN PointerRoot
  3615. or
  3616. .PN None
  3617. .br
  3618. \fIrevert-to\fP\^:
  3619. .Pn { Parent ,
  3620. .PN PointerRoot ,
  3621. .PN None }
  3622. .br
  3623. \fItime\fP\^: TIMESTAMP or
  3624. .PN CurrentTime
  3625. .in -.2i
  3626. .\" End marker code here
  3627. .NT Conventions
  3628. .IP 1. 5
  3629. Clients that use a  
  3630. .PN SetInputFocus
  3631. request must set the time argument to the timestamp of the event 
  3632. that caused them to make the attempt.
  3633. This cannot be a 
  3634. .PN FocusIn
  3635. event because they do not have timestamps.
  3636. Clients may also acquire the focus without a corresponding 
  3637. .PN EnterNotify 
  3638. event.
  3639. Clients must not use 
  3640. .PN CurrentTime
  3641. for the time argument.
  3642. .IP 2. 5
  3643. Clients that use a  
  3644. .PN SetInputFocus
  3645. request to set the focus to one of their windows must set 
  3646. the revert-to field to 
  3647. .PN Parent .
  3648. .NE
  3649. .NH 3
  3650. ClientMessage Events
  3651. .XS
  3652. \*(SN ClientMessage Events
  3653. .XE
  3654. .LP
  3655. There is no way for clients to prevent themselves being sent
  3656. .PN ClientMessage
  3657. events.
  3658. .LP
  3659. Top-level windows with a WM_PROTOCOLS property may be sent 
  3660. .PN ClientMessage
  3661. events specific to the protocols named by the atoms in the property 
  3662. (see section 4.1.2.7).
  3663. For all protocols, the 
  3664. .PN ClientMessage
  3665. events have the following:
  3666. .IP \(bu 5
  3667. WM_PROTOCOLS as the type field
  3668. .IP \(bu 5
  3669. Format 32
  3670. .IP \(bu 5
  3671. The atom that names their protocol in the data[0] field
  3672. .IP \(bu 5
  3673. A timestamp in their data[1] field
  3674. .LP
  3675. The remaining fields of the event,
  3676. including the window field,
  3677. are determined by the protocol.
  3678. .LP
  3679. These events will be sent by using a
  3680. .PN SendEvent
  3681. request with the following arguments:
  3682. .TS
  3683. l l.
  3684. _
  3685. .sp 6p
  3686. .B
  3687. Argument    Value
  3688. .sp 6p
  3689. _
  3690. .sp 6p
  3691. .R
  3692. destination:    The client's window
  3693. propagate:    T{
  3694. .PN False
  3695. T}
  3696. event-mask:    () empty
  3697. event:    As specified by the protocol
  3698. .sp 6p
  3699. _
  3700. .TE
  3701. .NH 3
  3702. Redirecting Requests
  3703. .XS
  3704. \*(SN Redirecting Requests
  3705. .XE
  3706. .LP
  3707. Normal clients can use the redirection mechanism just as window managers do
  3708. by selecting for 
  3709. .PN SubstructureRedirect
  3710. events on a parent window or 
  3711. .PN ResizeRedirect
  3712. events on a window itself.
  3713. However, at most,
  3714. one client per window can select for these events,
  3715. and a convention is needed to avoid clashes.
  3716. .NT Convention
  3717. Clients (including window managers) should select for 
  3718. .PN SubstructureRedirect
  3719. and
  3720. .PN ResizeRedirect
  3721. events only on windows that they own.
  3722. .NE
  3723. .LP
  3724. In particular, 
  3725. clients that need to take some special action if they are resized can select
  3726. for 
  3727. .PN ResizeRedirect
  3728. events on their top-level windows.
  3729. They will receive a
  3730. .PN ResizeRequest
  3731. event if the window manager resizes their window,
  3732. and the resize will not actually take place.
  3733. Clients are free to make what use they like of the information
  3734. that the window manager wants to change their size,
  3735. but they must configure the window to the width and height specified 
  3736. in the event in a timely fashion.
  3737. To ensure that the resize will actually happen at this stage
  3738. instead of being intercepted and executed by the window manager
  3739. (and thus restarting the process),
  3740. the client needs temporarily to set override-redirect on the window.
  3741. .NT Convention
  3742. Clients receiving 
  3743. .PN ResizeRequest
  3744. events must respond by doing the following:
  3745. .IP \(bu 5
  3746. Setting override-redirect on the window specified in the event
  3747. .IP \(bu 5
  3748. Configuring the window specified in the event 
  3749. to the width and height specified in the event as soon as possible 
  3750. and before making any other geometry requests
  3751. .IP \(bu 5
  3752. Clearing override-redirect on the window specified in the event
  3753. .NE
  3754. .LP
  3755. If a window manager detects that a client is not obeying this convention,
  3756. it is free to take whatever measures it deems appropriate to deal with
  3757. the client.
  3758. .NH 2
  3759. Summary of Window Manager Property Types
  3760. .XS
  3761. \*(SN Summary of Window Manager Property Types
  3762. .XE
  3763. .LP
  3764. The window manager properties are summarized in the following table
  3765. (see also section 14.1 of \fIXlib \- C Language X Interface\fP).
  3766. .TS H
  3767. l l n c.
  3768. _
  3769. .sp 6p
  3770. .B
  3771. Name    Type    Format    See Section
  3772. .sp 6p
  3773. _
  3774. .sp 6p
  3775. .TH
  3776. .R
  3777. WM_CLASS    STRING    8    4.1.2.5
  3778. WM_COLORMAP_WINDOWS    WINDOW    32    4.1.2.8
  3779. WM_HINTS    WM_HINTS    32    4.1.2.4
  3780. WM_ICON_NAME    TEXT        4.1.2.2
  3781. WM_ICON_SIZE    WM_ICON_SIZE    32    4.1.3.2
  3782. WM_NAME    TEXT        4.1.2.1
  3783. WM_NORMAL_HINTS    WM_SIZE_HINTS    32    4.1.2.3
  3784. WM_PROTOCOLS    ATOM    32    4.1.2.7
  3785. WM_STATE    WM_STATE    32    4.1.3.1
  3786. WM_TRANSIENT_FOR    WINDOW    32    4.1.2.6
  3787. .sp 6p
  3788. _
  3789. .TE
  3790. .NH 1
  3791. Client to Session Manager Communication
  3792. .XS
  3793. \*(SN Client to Session Manager Communication
  3794. .XE
  3795. .LP
  3796. The session manager's role is to manage a collection of clients.
  3797. It should be capable of:
  3798. .IP \(bu 5
  3799. Starting a collection of clients as a group
  3800. .IP \(bu 5
  3801. Remembering the state of a collection of clients so that
  3802. they can be restarted in the same state
  3803. .IP \(bu 5
  3804. Stopping a collection of clients in a controlled way
  3805. .LP
  3806. It may also provide a user interface to these capabilities.
  3807. .NH 2
  3808. Client Actions
  3809. .XS
  3810. \*(SN Client Actions
  3811. .XE
  3812. .LP
  3813. There are two ways in which clients should cooperate with the session manager:
  3814. .IP 1. 5
  3815. Stateful clients should cooperate with the session manager by providing
  3816. it with information it can use to restart them if that should become necessary.
  3817. .IP 2. 5
  3818. Clients, typically those with more than one top-level window,
  3819. whose server connection needs to survive the deletion of their top-level
  3820. window should take part in the WM_DELETE_WINDOW protocol (see section 5.2.2).
  3821. .NH 3
  3822. Properties
  3823. .XS
  3824. \*(SN Properties
  3825. .XE
  3826. .LP
  3827. The client communicates with the session manager by placing two properties
  3828. (WM_COMMAND and WM_CLIENT_MACHINE) on its top-level window.
  3829. If the client has a group of top-level windows,
  3830. these properties should be placed on the group leader window.
  3831. .LP
  3832. The window manager is responsible for placing a WM_STATE property
  3833. on each top-level client window for use by session managers and other clients
  3834. that need to be able to identify top-level client windows and their state.
  3835. .NH 4
  3836. WM_COMMAND Property
  3837. .XS
  3838. \*(SN WM_COMMAND Property
  3839. .XE
  3840. .LP
  3841. The WM_COMMAND property represents the command used to start 
  3842. or restart the client.
  3843. By updating this property,
  3844. clients should ensure that it always reflects a command 
  3845. that will restart them in their current state.
  3846. The content and type of the property depends on the operating system of
  3847. the machine running the client.
  3848. On POSIX-conformant systems using ISO Latin-1 characters 
  3849. for their command lines,
  3850. the property should:
  3851. .IP \(bu 5
  3852. Be of type STRING
  3853. .IP \(bu 5
  3854. Contain a list of null-terminated strings
  3855. .IP \(bu 5
  3856. Be initialized from argv
  3857. .IP
  3858. Other systems will need to set appropriate conventions for the type 
  3859. and contents of WM_COMMAND properties.
  3860. Window and session managers should not assume that STRING is 
  3861. the type of WM_COMMAND or that they will be able to understand 
  3862. or display its contents.
  3863. .LP
  3864. Note that WM_COMMAND strings are null-terminated
  3865. and differ from the general conventions that STRING properties
  3866. are null-separated.
  3867. This inconsistency is necessary for backwards-compatibility.
  3868. .LP
  3869. A client with multiple top-level windows should ensure 
  3870. that exactly one of them has a WM_COMMAND with nonzero length.
  3871. Zero-length WM_COMMAND properties can be used to reply to WM_SAVE_YOURSELF
  3872. messages on other top-level windows but will otherwise be ignored 
  3873. (see section 5.2.1).
  3874. .NH 4
  3875. WM_CLIENT_MACHINE Property
  3876. .XS
  3877. \*(SN WM_CLIENT_MACHINE Property
  3878. .XE
  3879. .LP
  3880. The client should set the WM_CLIENT_MACHINE property
  3881. (of one of the TEXT types)
  3882. to a string that forms the name of the machine running the client
  3883. as seen from the machine running the server.
  3884. .NH 4
  3885. WM_STATE Property
  3886. .XS
  3887. \*(SN WM_STATE Property
  3888. .XE
  3889. .LP
  3890. The window manager will place a WM_STATE property
  3891. (of type WM_STATE) on each top-level client window.
  3892. .LP
  3893. Programs like
  3894. .PN xprop
  3895. that want to operate on client's top-level windows can use this
  3896. property to identify them.
  3897. A client's top-level window is one that has override-redirect set to
  3898. .PN False
  3899. and a WM_STATE property
  3900. or that is a mapped child of the root that has no descendant with a WM_STATE
  3901. property.
  3902. .LP
  3903. Recursion is necessary to cover all window manager reparenting
  3904. possibilities.
  3905. Note that clients other than window and session managers should
  3906. not need to examine the contents of WM_STATE properties,
  3907. which are not formally defined by the ICCCM.
  3908. The presence or absence of the property is all they need to know.
  3909. .LP
  3910. Suggested contents of the WM_STATE property are listed in the following
  3911. table:
  3912. .TS H
  3913. l l l.
  3914. _
  3915. .sp 6p
  3916. .B
  3917. Field    Type    Comments
  3918. .sp 6p
  3919. _
  3920. .sp 6p
  3921. .TH
  3922. .R
  3923. state    CARD32    (see the next table)
  3924. icon    WINDOW    ID of icon window
  3925. .sp 6p
  3926. _
  3927. .TE
  3928. .LP
  3929. The following table lists the WM_STATE.state values:
  3930. .TS H
  3931. l n.
  3932. _
  3933. .sp 6p
  3934. .B
  3935. State    Value
  3936. .sp 6p
  3937. _
  3938. .sp 6p
  3939. .TH
  3940. .R
  3941. WithdrawnState    0
  3942. NormalState    1
  3943. IconicState    3
  3944. .sp 6p
  3945. _
  3946. .TE
  3947. .LP
  3948. Adding other fields to this property is reserved to the X Consortium.
  3949. .LP
  3950. The icon field should either contain the window ID of the window 
  3951. that the window manager uses as the icon window for the
  3952. window on which this property is set if one exists or
  3953. .PN None
  3954. if one does not.
  3955. Note that this window is not necessarily the same as the icon window 
  3956. that the client may have specified.
  3957. It can be one of the following:
  3958. .IP \(bu 5
  3959. The client's icon window
  3960. .IP \(bu 5
  3961. A window that the window manager supplied and that contains the client's icon
  3962. pixmap
  3963. .IP \(bu 5
  3964. The least ancestor of the client's icon window (or of the window
  3965. that contains the client's icon pixmap), which contains no other icons
  3966. .LP
  3967. The state field describes the window manager's idea of the state 
  3968. the window is in, which may not match the client's idea as expressed 
  3969. in the initial_state field of the WM_HINTS property 
  3970. (for example, if the user has asked the window manager to iconify the window).
  3971. If it is 
  3972. .PN NormalState ,
  3973. the window manager believes the client should be animating its window.
  3974. If it is 
  3975. .PN IconicState ,
  3976. the client should animate its icon window.
  3977. In either state,
  3978. clients should be prepared to handle exposure events from either window.
  3979. .LP
  3980. The contents of WM_STATE properties and other aspects of the communication
  3981. between window and session managers will be specified in the forthcoming
  3982. \fIWindow and Session Manager Conventions Manual\fP.
  3983. .NH 3
  3984. Termination
  3985. .XS
  3986. \*(SN Termination
  3987. .XE
  3988. .LP
  3989. Because they communicate by means of unreliable network connections,
  3990. clients must be prepared for their connection to the server 
  3991. to be terminated at any time without warning.
  3992. They cannot depend on getting notification that termination is imminent
  3993. or on being able to use the server to negotiate with the user about their fate.
  3994. For example,
  3995. clients cannot depend on being able to put up a dialog box.
  3996. .LP
  3997. Similarly,
  3998. clients may terminate at any time without notice to the session manager.
  3999. When a client terminates itself rather than being terminated 
  4000. by the session manager,
  4001. it is viewed as having resigned from the session in question,
  4002. and it will not be revived if the session is revived.
  4003. .NH 2
  4004. Client Responses to Session Manager Actions
  4005. .XS
  4006. \*(SN Client Responses to Session Manager Actions
  4007. .XE
  4008. .LP
  4009. Clients may need to respond to session manager actions in two ways:
  4010. .IP \(bu 5
  4011. Saving their internal state
  4012. .IP \(bu 5
  4013. Deleting a window
  4014. .NH 3
  4015. Saving Client State
  4016. .XS
  4017. \*(SN Saving Client State
  4018. .XE
  4019. .LP
  4020. Clients that want to be warned when the session manager feels 
  4021. that they should save their internal state (for example,
  4022. when termination impends) should include the atom WM_SAVE_YOURSELF 
  4023. in the WM_PROTOCOLS property on their top-level windows to participate 
  4024. in the WM_SAVE_YOURSELF protocol.
  4025. They will receive a 
  4026. .PN ClientMessage
  4027. event as described in section 4.2.8 
  4028. with the atom WM_SAVE_YOURSELF in its data[0] field.
  4029. .LP
  4030. Clients that receive WM_SAVE_YOURSELF should place themselves in a state from
  4031. which they can be restarted and should update WM_COMMAND to
  4032. be a command that will restart them in this state.
  4033. The session manager will be waiting for a 
  4034. .PN PropertyNotify
  4035. event on WM_COMMAND as a confirmation that the client has saved its state.
  4036. Therefore, WM_COMMAND should be updated (perhaps with a zero-length append)
  4037. even if its contents are correct.
  4038. No interactions with the user are permitted during this process.
  4039. .LP
  4040. Once it has received this confirmation,
  4041. the session manager will feel free to terminate the client if that is what 
  4042. the user asked for.
  4043. Otherwise,
  4044. if the user asked for the session to be put to sleep,
  4045. the session manager will ensure that the client does not
  4046. receive any mouse or keyboard events.
  4047. .LP
  4048. After receiving a WM_SAVE_YOURSELF, saving its state, and updating WM_COMMAND,
  4049. the client should not change its state (in the sense of doing anything 
  4050. that would require a change to WM_COMMAND) until it receives a mouse 
  4051. or keyboard event.
  4052. Once it does so,
  4053. it can assume that the danger is over.
  4054. The session manager will ensure that these events do not reach
  4055. clients until the danger is over or until the clients have been killed.
  4056. .LP
  4057. Irrespective of how they are arranged in window groups,
  4058. clients with multiple top-level windows should ensure the following:
  4059. .IP \(bu 5
  4060. Only one of their top-level windows has a nonzero-length WM_COMMAND
  4061. property.
  4062. .IP \(bu 5
  4063. They respond to a WM_SAVE_YOURSELF message by:
  4064. .RS
  4065. .IP \- 5
  4066. First, updating the nonzero-length WM_COMMAND property, if necessary
  4067. .IP \- 5
  4068. Second, updating the WM_COMMAND property on the window for which they received
  4069. the WM_SAVE_YOURSELF message if it was not updated in the first step
  4070. .RE
  4071. .LP
  4072. Receiving WM_SAVE_YOURSELF on a window is, conceptually, a command 
  4073. to save the entire client state.\s-2\u12\d\s0
  4074. .FS
  4075. 12.  This convention has changed since earlier drafts because of the 
  4076. introduction of the protocol in the next section.
  4077. In the public review draft,
  4078. there was ambiguity as to whether WM_SAVE_YOURSELF was a checkpoint 
  4079. or a shutdown facility.
  4080. It is now unambiguously a checkpoint facility;
  4081. if a shutdown facility is judged to be necessary,
  4082. a separate WM_PROTOCOLS protocol will be developed and registered 
  4083. with the X Consortium.
  4084. .FE
  4085. .NH 3
  4086. Window Deletion
  4087. .XS
  4088. \*(SN Window Deletion
  4089. .XE
  4090. .LP
  4091. Clients,
  4092. usually those with multiple top-level windows,
  4093. whose server connection must survive the deletion of some of their
  4094. top-level windows should include the atom WM_DELETE_WINDOW
  4095. in the WM_PROTOCOLS property on each such window.
  4096. They will receive a 
  4097. .PN ClientMessage 
  4098. event as described in section 4.2.8 whose data[0] field is WM_DELETE_WINDOW.
  4099. .LP
  4100. Clients receiving a WM_DELETE_WINDOW message should behave as if the user
  4101. selected "delete window" from a hypothetical menu.
  4102. They should perform any confirmation dialog with the user
  4103. and, if they decide to complete the deletion, should do the following:
  4104. .IP \(bu 5
  4105. Either change the window's state to Withdrawn (as described in section 4.1.4)
  4106. or destroy the window
  4107. .IP \(bu 5
  4108. Destroy any internal state associated with the window
  4109. .LP
  4110. If the user aborts the deletion during the confirmation dialog,
  4111. the client should ignore the message.
  4112. .LP
  4113. Clients are permitted to interact with the user and ask, for example,
  4114. whether a file associated with the window to be deleted should be saved
  4115. or the window deletion should be cancelled.
  4116. Clients are not required to destroy the window itself;
  4117. the resource may be reused,
  4118. but all associated state (for example, backing store) should be released.
  4119. .LP
  4120. If the client aborts a destroy and the user then selects DELETE WINDOW again,
  4121. the window manager should start the WM_DELETE_WINDOW protocol again.
  4122. Window managers should not use 
  4123. .PN DestroyWindow
  4124. requests on a window that has WM_DELETE_WINDOW in its WM_PROTOCOLS property.
  4125. .LP
  4126. Clients that choose not to include WM_DELETE_WINDOW in the WM_PROTOCOLS
  4127. property may be disconnected from the server
  4128. if the user asks for one of the client's top-level windows to be deleted.
  4129. .LP
  4130. Note that the WM_SAVE_YOURSELF and WM_DELETE_WINDOW protocols are
  4131. orthogonal to each other and may be selected independently.
  4132. .NH 2
  4133. Summary of Session Manager Property Types
  4134. .XS
  4135. \*(SN Summary of Session Manager Property Types
  4136. .XE
  4137. .LP
  4138. The session manager properties are listed in the following table:
  4139. .TS H
  4140. l l n c.
  4141. _
  4142. .sp 6p
  4143. .B
  4144. Name    Type    Format    See Section
  4145. .sp 6p
  4146. _
  4147. .sp 6p
  4148. .TH
  4149. .R
  4150. WM_CLIENT_MACHINE    TEXT        5.1.1.2
  4151. WM_COMMAND    TEXT        5.1.1.1
  4152. WM_STATE    WM_STATE    32    5.1.1.3
  4153. .sp 6p
  4154. _
  4155. .TE
  4156. .NH 1
  4157. Manipulation of Shared Resources
  4158. .XS
  4159. \*(SN Manipulation of Shared Resource
  4160. .XE
  4161. .LP
  4162. X Version 11 permits clients to manipulate a number of shared resources,
  4163. for example, the input focus, the pointer, and colormaps.
  4164. Conventions are required so that clients share resources in an
  4165. orderly fashion.
  4166. .if 0 \{
  4167. .IP
  4168. <XXX - grab rules>
  4169. \}
  4170. .NH 2
  4171. The Input Focus
  4172. .XS
  4173. \*(SN The Input Focus
  4174. .XE
  4175. .LP
  4176. Clients that explicitly set the input focus must observe one of two modes:
  4177. .IP \(bu 5
  4178. Locally active mode
  4179. .IP \(bu 5
  4180. Globally active mode
  4181. .NT Conventions
  4182. .IP 1. 5
  4183. Locally active clients should set the input focus to one of their windows 
  4184. only when it is already in one of their windows
  4185. or when they receive a WM_TAKE_FOCUS message.
  4186. They should set the input field of the WM_HINTS structure to
  4187. .PN True .
  4188. .IP 2. 5
  4189. Globally active clients should set the input focus to one of their windows 
  4190. only when they receive a button event and a passive-grabbed key event,
  4191. or when they receive a WM_TAKE_FOCUS message.
  4192. They should set the input field of the WM_HINTS structure to
  4193. .PN False .
  4194. .IP 3. 5
  4195. In addition, clients should use the timestamp of the event 
  4196. that caused them to attempt to set the input focus as the time field on the 
  4197. .PN SetInputFocus
  4198. request, not
  4199. .PN CurrentTime .
  4200. .NE
  4201. .NH 2
  4202. The Pointer
  4203. .XS
  4204. \*(SN The Pointer
  4205. .XE
  4206. .LP
  4207. In general, clients should not warp the pointer.
  4208. Window managers, however, may do so
  4209. (for example, to maintain the invariant that the pointer is always
  4210. in the window with the input focus).
  4211. Other window managers may want to preserve the illusion that the user
  4212. is in sole control of the pointer.
  4213. .NT Conventions
  4214. .IP 1. 5
  4215. Clients should not warp the pointer.
  4216. .IP 2. 5
  4217. Clients that insist on warping the pointer should do so only
  4218. with the src-window argument of the 
  4219. .PN WarpPointer 
  4220. request set to one of their windows.
  4221. .NE
  4222. .NH 2
  4223. Grabs
  4224. .XS
  4225. \*(SN Grabs
  4226. .XE
  4227. .LP
  4228. A client's attempt to establish a button or a key grab on a window
  4229. will fail if some other client has already established a conflicting
  4230. grab on the same window.
  4231. The grabs, therefore, are shared resources,
  4232. and their use requires conventions.
  4233. .LP
  4234. In conformance with the principle that clients should behave,
  4235. as far as possible,
  4236. when a window manager is running as they would when it is not,
  4237. a client that has the input focus may assume that it can receive all 
  4238. the available keys and buttons.
  4239. .NT Convention
  4240. Window managers should ensure that they provide some mechanism for
  4241. their clients to receive events from all keys and all buttons,
  4242. except for events involving keys whose KeySyms are registered as being for
  4243. window management functions (for example, a hypothetical WINDOW KeySym).
  4244. .NE
  4245. .LP
  4246. In other words,
  4247. window managers must provide some mechanism by which a client
  4248. can receive events from every key and button (regardless of modifiers)
  4249. unless and until the X Consortium registers some KeySyms as being reserved 
  4250. for window management functions.
  4251. Currently, no KeySyms are registered for window management functions.
  4252. .LP
  4253. Even so, clients are advised to allow the key and button combinations
  4254. used to elicit program actions to be modified,
  4255. because some window managers may choose not to observe this convention
  4256. or may not provide a convenient method for the user to transmit events
  4257. from some keys.
  4258. .NT Convention
  4259. Clients should establish button and key grabs only on windows that
  4260. they own.
  4261. .NE
  4262. .LP
  4263. In particular, this convention means that a window manager that wishes 
  4264. to establish a grab over the client's top-level window should either establish 
  4265. the grab on the root, or reparent the window and establish the grab 
  4266. on a proper ancestor.
  4267. In some cases,
  4268. a window manager may want to consume the event received,
  4269. placing the window in a state where a subsequent such event will go to
  4270. the client.
  4271. Examples are:
  4272. .IP \(bu 5
  4273. Clicking in a window to set focus with the click not being offered 
  4274. to the client
  4275. .IP \(bu 5
  4276. Clicking in a buried window to raise it, again, with the click not offered 
  4277. to the client
  4278. .LP
  4279. More typically,
  4280. a window manager should add to rather than replace the client's semantics 
  4281. for key+button combinations by allowing the event to be used by the client 
  4282. after the window manager is done with it.
  4283. To ensure this,
  4284. the window manager should establish the grab on the parent 
  4285. by using the following:
  4286. .LP
  4287. .Ds
  4288. pointer/keyboard-mode == Synchronous
  4289. .De
  4290. .LP
  4291. Then, the window manager should release the grab by using an
  4292. .PN AllowEvents 
  4293. request with the following specified:
  4294. .LP
  4295. .Ds
  4296. mode == ReplayPointer/Keyboard
  4297. .De
  4298. .LP
  4299. In this way,
  4300. the client will receive the events as if they had not been intercepted.
  4301. .LP
  4302. Obviously,
  4303. these conventions place some constraints on possible user interface policies.
  4304. There is a trade-off here between freedom for window managers to implement
  4305. their user interface policies and freedom for clients to implement theirs.
  4306. The dilemma is resolved by:
  4307. .IP \(bu 5
  4308. Allowing window managers to decide if and when a client will receive an
  4309. event from any given key or button
  4310. .IP \(bu 5
  4311. Placing a requirement on the window manager to provide some mechanism,
  4312. perhaps a ``Quote'' key,
  4313. by which the user can send an event from any key or button to the client
  4314. .NH 2
  4315. Colormaps
  4316. .XS
  4317. \*(SN Colormaps
  4318. .XE
  4319. .LP
  4320. Section 4.1.8 prescribes the following:
  4321. .NT Conventions
  4322. .IP 1. 5
  4323. If a client has a top-level window that has subwindows
  4324. or override-redirect pop-up windows whose colormap requirements differ 
  4325. from the top-level window,
  4326. it should set a WM_COLORMAP_WINDOWS property on the top-level window.
  4327. The WM_COLORMAP_WINDOWS property contains a list of the window IDs of
  4328. windows that the window manager should track for colormap changes.
  4329. .IP 2. 5
  4330. When a client's colormap requirements change,
  4331. the client should change the colormap window attribute of a top-level window
  4332. or one of the windows indicated by a WM_COLORMAP_WINDOWS property.
  4333. .IP 3. 5
  4334. Clients must not use 
  4335. .PN InstallColormap
  4336. or
  4337. .PN UninstallColormap
  4338. requests.
  4339. .NE
  4340. .LP
  4341. If your clients are
  4342. .PN DirectColor
  4343. type applications,
  4344. you should consult section 14.3 of \fIXlib \- C Language X Interface\fP
  4345. for conventions connected with sharing standard colormaps.
  4346. They should look for and create the properties described there on
  4347. the root window of the appropriate screen.
  4348. .LP
  4349. The contents of the RGB_COLOR_MAP type property are as follows:
  4350. .TS H
  4351. l l l.
  4352. _
  4353. .sp 6p
  4354. .B
  4355. Field    Type    Comments
  4356. .sp 6p
  4357. _
  4358. .sp 6p
  4359. .TH
  4360. .R
  4361. colormap    COLORMAP    ID of the colormap described
  4362. red_max    CARD32    Values for pixel calculations
  4363. red_mult    CARD32
  4364. green_max    CARD32
  4365. green_mult    CARD32
  4366. blue_max    CARD32
  4367. blue_mult    CARD32
  4368. base_pixel    CARD32
  4369. visual_id    VISUALID    Visual to which colormap belongs
  4370. kill_id    CARD32    ID for destroying the resources
  4371. .sp 6p
  4372. _
  4373. .TE
  4374. .LP
  4375. When deleting or replacing an RGB_COLOR_MAP,
  4376. it is not sufficient to delete the property;
  4377. it is important to free the associated colormap resources as well.
  4378. If kill_id is greater than one,
  4379. the resources should be freed by issuing a 
  4380. .PN KillClient
  4381. request with kill_id as the argument.
  4382. If kill_id is one,
  4383. the resources should be freed by issuing a
  4384. .PN FreeColormap
  4385. request with colormap as the colormap
  4386. argument.
  4387. If kill_id is zero,
  4388. no attempt should be made to free the resources.
  4389. A client that creates an RGB_COLOR_MAP for which the colormap resource 
  4390. is created specifically for this purpose should set kill_id to one 
  4391. (and can create more than one such standard colormap 
  4392. using a single connection).
  4393. A client that creates an RGB_COLOR_MAP for which the colormap resource 
  4394. is shared in some way (for example, is the default colormap 
  4395. for the root window) should create an arbitrary resource and use its 
  4396. resource ID for kill_id (and should create no other standard colormaps 
  4397. on the connection).
  4398. .NT Convention
  4399. If an RGB_COLOR_MAP property is too short to contain the visual_id field,
  4400. it can be assumed that the visual_id is the root visual 
  4401. of the appropriate screen.
  4402. If an RGB_COLOR_MAP property is too short to contain the kill_id field,
  4403. a value of zero can be assumed.
  4404. .NE
  4405. .LP
  4406. During the connection handshake,
  4407. the server informs the client of the default colormap for each screen.
  4408. This is a colormap for the root visual,
  4409. and clients can use it to improve the extent of colormap sharing
  4410. if they use the root visual.
  4411. .NH 2
  4412. The Keyboard Mapping
  4413. .XS
  4414. \*(SN The Keyboard Mapping
  4415. .XE
  4416. .LP
  4417. The X server contains a table (which is read by 
  4418. .PN GetKeyboardMapping
  4419. requests) that describes the set of symbols appearing 
  4420. on the corresponding key for each keycode generated by the server.
  4421. This table does not affect the server's operations in any way;
  4422. it is simply a database used by clients that attempt to understand 
  4423. the keycodes they receive.
  4424. Nevertheless, it is a shared resource and requires conventions.
  4425. .LP
  4426. It is possible for clients to modify this table by using a
  4427. .PN ChangeKeyboardMapping
  4428. request.
  4429. In general, clients should not do this.
  4430. In particular, this is not the way in which clients should implement 
  4431. key bindings or key remapping.
  4432. The conversion between a sequence of keycodes received from the server
  4433. and a string in a particular encoding is a private matter for each client
  4434. (as it must be in a world where applications may be using different
  4435. encodings to support different languages and fonts).
  4436. See the Xlib reference manual for converting keyboard events to text.
  4437. .LP
  4438. The only valid reason for using a
  4439. .PN ChangeKeyboardMapping
  4440. request is when the symbols written on the keys have changed as, for example,
  4441. when a Dvorak key conversion kit or a set of APL keycaps has been installed.
  4442. Of course, a client may have to take the change to the keycap on trust.
  4443. .LP
  4444. The following illustrates a permissible interaction between a client 
  4445. and a user:
  4446. .IP Client: 10
  4447. ``You just started me on a server without a Pause key.
  4448. Please choose a key to be the Pause key and press it now.''
  4449. .IP User: 10
  4450. Presses the Scroll Lock key
  4451. .IP Client: 10
  4452. ``Adding Pause to the symbols on the Scroll Lock key: Confirm or Abort.''
  4453. .IP User: 10
  4454. Confirms
  4455. .IP Client: 10
  4456. Uses a
  4457. .PN ChangeKeyboardMapping
  4458. request to add Pause to the keycode that already contains Scroll Lock and
  4459. issues this request, ``Please paint Pause on the Scroll Lock key.''
  4460. .NT Convention
  4461. Clients should not use 
  4462. .PN ChangeKeyboardMapping
  4463. requests.
  4464. .NE
  4465. .LP
  4466. If a client succeeds in changing the keyboard mapping table,
  4467. all clients will receive 
  4468. .PN MappingNotify (request==Keyboard)
  4469. events.
  4470. There is no mechanism to avoid receiving these events.
  4471. .NT Convention
  4472. Clients receiving 
  4473. .PN MappingNotify (request==Keyboard)
  4474. events should update any internal keycode translation tables they are using.
  4475. .NE
  4476. .NH 2
  4477. The Modifier Mapping
  4478. .XS
  4479. \*(SN The Modifier Mapping
  4480. .XE
  4481. .LP
  4482. X Version 11 supports eight modifier bits of which three are preassigned 
  4483. to Shift, Lock, and Control.
  4484. Each modifier bit is controlled by the state of a set of keys,
  4485. and these sets are specified in a table accessed by
  4486. .PN GetModifierMapping
  4487. and
  4488. .PN SetModifierMapping
  4489. requests.
  4490. This table is a shared resource and requires conventions.
  4491. .LP
  4492. A client that needs to use one of the preassigned modifiers should assume 
  4493. that the modifier table has been set up correctly to control these modifiers.
  4494. The Lock modifier should be interpreted as Caps Lock or Shift Lock
  4495. according as the keycodes in its controlling set include XK_Caps_Lock
  4496. or XK_Shift_Lock.
  4497. .NT Convention
  4498. Clients should determine the meaning of a modifier bit from the KeySyms
  4499. being used to control it.
  4500. .NE
  4501. .LP
  4502. A client that needs to use an extra modifier (for example, META) should do
  4503. the following:
  4504. .IP \(bu 5
  4505. Scan the existing modifier mappings.
  4506. If it finds a modifier that contains a keycode whose set of KeySyms
  4507. includes XK_Meta_L or XK_Meta_R,
  4508. it should use that modifier bit.
  4509. .IP \(bu 5
  4510. If there is no existing modifier controlled by  XK_Meta_L or XK_Meta_R,
  4511. it should select an unused modifier bit (one with an empty controlling set)
  4512. and do the following:
  4513. .RS
  4514. .IP \- 5
  4515. If there is a keycode with XL_Meta_L in its set of KeySyms,
  4516. add that keycode to the set for the chosen modifier.
  4517. .IP \- 5
  4518. If there is a keycode with XL_Meta_R in its set of KeySyms,
  4519. add that keycode to the set for the chosen modifier.
  4520. .IP \- 5
  4521. If the controlling set is still empty,
  4522. interact with the user to select one or more keys to be META.
  4523. .RE
  4524. .IP \(bu 5
  4525. If there are no unused modifier bits,
  4526. ask the user to take corrective action.
  4527. .NT Conventions
  4528. .IP 1. 5
  4529. Clients needing a modifier not currently in use should assign keycodes
  4530. carrying suitable KeySyms to an unused modifier bit.
  4531. .IP 2. 5
  4532. Clients assigning their own modifier bits should ask the user politely to
  4533. remove his or her hands from the key in question if their 
  4534. .PN SetModifierMapping
  4535. request returns a 
  4536. .PN Busy
  4537. status.
  4538. .NE
  4539. .LP
  4540. There is no good solution to the problem of reclaiming assignments
  4541. to the five nonpreassigned modifiers when they are no longer being used.
  4542. .NT Convention
  4543. The user has to use
  4544. .PN xmodmap
  4545. or some other utility to deassign obsolete modifier mappings by hand.
  4546. .NE
  4547. .NT Problem
  4548. This is unpleasantly low-tech.
  4549. .NE
  4550. .LP
  4551. When a client succeeds in performing a 
  4552. .PN SetModifierMapping
  4553. request,
  4554. all clients will receive 
  4555. .PN MappingNotify (request==Modifier)
  4556. events.
  4557. There is no mechanism for preventing these events from being received.
  4558. A client that uses one of the nonpreassigned modifiers that receives
  4559. one of these events should do a 
  4560. .PN GetModifierMapping
  4561. request to discover the new mapping,
  4562. and if the modifier it is using has been cleared,
  4563. it should reinstall the modifier.
  4564. .LP
  4565. Note that a
  4566. .PN GrabServer
  4567. request must be used to make the 
  4568. .PN GetModifierMapping 
  4569. and
  4570. .PN SetModifierMapping
  4571. pair in these transactions atomic.
  4572. .NH 1
  4573. Device Color Characterization
  4574. .XS
  4575. \*(SN Device Color Characterization
  4576. .XE
  4577. .LP
  4578. .EQ
  4579. delim @@
  4580. define oc % "\\fR{\\fP" %
  4581. define cc % "\\fR}\\fP" %
  4582. .EN
  4583. The X protocol provides explicit RGB values
  4584. which are used to directly drive a monitor, and color names.  RGB values
  4585. provide a mechanism for accessing the full capabilities of the display
  4586. device, but at the expense of having the color perceived by the user remain
  4587. unknowable through the protocol.  Color names were originally designed to
  4588. provide access to a device-independent color database by having the server
  4589. vendor tune the definitions of the colors in that textual database.
  4590. Unfortunately, this still does not provide the client anyway of using
  4591. an existing device-independent color, nor for the client to get
  4592. device-independent color information back about colors which it has selected.
  4593. .LP
  4594. Furthermore, the client must be able to discover which set of colors are
  4595. displayable by the device (the device gamut), both to allow colors to be
  4596. intelligently modified to fit within the device capabilities (gamut
  4597. compression) and to enable the user interface to display a representation of
  4598. the reachable color space to the user (gamut display).
  4599. .LP
  4600. So, a system is needed which will provide full access to
  4601. device-independent color spaces for X clients.  This system should use a
  4602. standard mechanism for naming the colors, be able to provide names for
  4603. existing colors, and provide means by which unreachable colors can be
  4604. modified to fall within the device gamut.
  4605. .LP
  4606. We are fortunate in this area to have a seminal work, the 1931 CIE color
  4607. standard, which is nearly universally agreed upon as adequate for describing
  4608. colors on CRT devices.  This standard uses a tri-stimulus model called CIE
  4609. XYZ in which each perceivable color is specified as a triplet of numbers.
  4610. Other appropriate device independent color models do exist, but most of them
  4611. are directly traceable back to this original work.
  4612. .LP
  4613. X device color characterization
  4614. provides device-independent color spaces to X clients.  It does this by
  4615. providing the barest possible amount of information to the client which
  4616. allows the client to construct a mapping between CIE XYZ and the regular X
  4617. RGB color descriptions.
  4618. .LP
  4619. Device color characterization is defined by
  4620. the name and contents of two window properties which,
  4621. together, permit converting between CIE XYZ space and
  4622. linear RGB device space (such as standard CRTs).
  4623. Linear RGB devices require just two
  4624. pieces of information to completely characterize them:
  4625. .RS
  4626. .LP
  4627. A 3x3 matrix @M@ (and it's inverse, @M sup -1@) which convert between XYZ
  4628. and RGB intensity (@RGB sub intensity@):
  4629. .EQ
  4630.     RGB sub intensity ~ = ~ M ~ times ~ XYZ
  4631. .EN C
  4632. .EQ
  4633.     XYZ ~ = ~ M sup -1 ~ times ~ RGB sub intensity
  4634. .EN
  4635. .LP
  4636. A way of mapping between RGB intensity and RGB protocol value.  XDCCC
  4637. supports three mechanisms which will be outlined below.
  4638. .RE
  4639. .LP
  4640. If other device types are eventually necessary, additional
  4641. properties will be required to describe them.
  4642. .NH 2
  4643. XYZ \*(dA RGB Conversion Matrices
  4644. .XS
  4645. \*(SN XYZ \*(dA RGB Conversion Matrices
  4646. .XE
  4647. .LP
  4648. Because of the limited dynamic range of both XYZ and RGB intensity,
  4649. these matrices will be encoded using a fixed point representation of a
  4650. 32-bit 2s complement number scaled by @2 sup 27@, giving a range of @-16@ to
  4651. @16 - epsilon@, where @epsilon ~ = ~ 2 sup -37@.
  4652. .LP
  4653. These matrices will be packed into an 18 element list of 32 bit values,
  4654. XYZ \*(fA RGB matrix first, in row major order and stored in the
  4655. "XDCCC_LINEAR_RGB_MATRICES" properties (format = 32) on the root window of
  4656. each screen, using values appropriate for that screen.
  4657. .LP
  4658. This will be encoded as:
  4659. .TS
  4660. center;
  4661. c s s
  4662. c c c
  4663. l l l.
  4664. XDCCC_LINEAR_RGB_MATRICES property contents
  4665. _
  4666. Field    Type    Comments
  4667. @M sub 0,0@    INT32    Interpreted as a fixed point number @-16 <= x < 16@
  4668. @M sub 0,1@    INT32    
  4669. \&...
  4670. @M sub 3,3@    INT32    
  4671. @{M sup -1} sub 0,0@    INT32    
  4672. @{M sup -1} sub 0,1@    INT32    
  4673. \&...
  4674. @{M sup -1} sub 3,3@    INT32    
  4675. .TE
  4676. .NH 2
  4677. Intensity \*(dA RGB value Conversion
  4678. .XS
  4679. \*(SN Intensity \*(dA RGB value Conversion
  4680. .XE
  4681. .LP
  4682. XDCCC provides two representations for describing the conversion
  4683. between RGB intensity and the actual X protocol RGB values:
  4684. .RS
  4685. 0    RGB value/RGB intensity level pairs
  4686. .br
  4687. 1    RGB intensity ramp
  4688. .RE
  4689. .LP
  4690. In both cases, the relevant data will be stored in the
  4691. "XDCCC_LINEAR_RGB_CORRECTION" properties on the root window of each screen,
  4692. using values appropriate for that screen, in whatever format provides
  4693. adequate resolution.  Each property can consist of multiple entries
  4694. concatenated together, if different visuals for the screen require different
  4695. conversion data.  A entry with a VisualID of 0 specifies data for all
  4696. visuals of the screen that are not otherwise explicitly listed.
  4697. .LP
  4698. The first representation is an array of RGB value/intensity level pairs, with
  4699. the RGB values in strictly increasing order.  When converting, the client must
  4700. linearly interpolate between adjacent entries in the table to compute the
  4701. desired value.  This is to allow the server to perform gamma correction
  4702. itself and encode that fact in a short 2 element correction table.  The
  4703. intensity will be encoded as an unsigned number to be interpreted as a value
  4704. between 0 and 1 (inclusive).  The precision of this value will depend on the
  4705. format of the property in which it is stored (8, 16 or 32 bits).  For 16 and
  4706. 32 bit formats, the RGB value will simply be the value stored in the
  4707. property.  When stored in 8-bit format, the RGB value can be computed from
  4708. the value in the property by:
  4709. .EQ
  4710.     RGB sub value ~ = ~ { Property ~ Value ~ times ~ 65535 } over 255
  4711. .EN
  4712. .LP
  4713. Because the three electron guns in the device may not be exactly alike in
  4714. response characteristics, it is necessary to allow for three separate
  4715. tables, one each for red, green and blue.  So, each table will be preceded
  4716. by the number of entries in that table, and the set of tables will be
  4717. preceded by the number of tables.
  4718. When 3 tables are provided, they will be in red, green, blue order.
  4719. .LP
  4720. This will be encoded as:
  4721. .TS
  4722. center;
  4723. c s s
  4724. c c c
  4725. l l l.
  4726. XDCCC_LINEAR_RGB_CORRECTION property contents for type 0 correction
  4727. _
  4728. \fIField\fP    \fIType\fP    \fIComments\fP
  4729. VisualID0    CARD    Most significant portion of VisualID
  4730. VisualID1    CARD    (exists iff property format is 8)
  4731. VisualID2    CARD    (exists iff property format is 8)
  4732. VisualID3    CARD    Least significant (exists iff property format is 8 or 16)
  4733. type    CARD    0 for this type of correction
  4734. count    CARD    number of tables following (either 1 or 3)
  4735. length    CARD    number of pairs - 1 following in this table
  4736. value    CARD    X Protocol RGB value
  4737. intensity    CARD    Interpret as a number 0 <= intensity <= 1
  4738. \&...    ...    Total of \fIlength+1\fP pairs of value/intensity values
  4739. lengthg    CARD    number of pairs - 1 following in this table (iff \fIcount\fP is 3)
  4740. value    CARD    X Protocol RGB value
  4741. intensity    CARD    Interpret as a number 0 <= intensity <= 1
  4742. \&...    ...    Total of \fIlengthg+1\fP pairs of value/intensity values
  4743. lengthb    CARD    number of pairs - 1 following in this table (iff \fIcount\fP is 3)
  4744. value    CARD    X Protocol RGB value
  4745. intensity    CARD    Interpret as a number 0 <= intensity <= 1
  4746. \&...    ...    Total of \fIlengthb+1\fP pairs of value/intensity values
  4747. .TE
  4748. .LP
  4749. Note that the VisualID is stored in 4, 2, or 1 pieces, depending on whether
  4750. the property format is 8, 16, or 32, respectively.  The VisualID is always
  4751. stored most-significant piece first.
  4752. Note that the length fields are stored as one less than the actual length,
  4753. so that 256 entries can be stored in format 8.
  4754. .LP
  4755. The second representation is a simple array of intensities for a linear subset
  4756. of RGB values.  The expected size of this table is the bits-per-rgb-value of
  4757. the screen, but it can be any length.  This is similar to the first mechanism,
  4758. except that the RGB value numbers are implicitly defined by the index in the
  4759. array (indices start at 0):
  4760. .EQ
  4761.     RGB sub value = { Array ~ Index ~ times ~ 65535 } over { Array ~ Size ~ - ~ 1 }
  4762. .EN
  4763. When converting, the client may linearly interpolate between entries in this
  4764. table.  The intensity values will be encoded just as in the first
  4765. representation.
  4766. .LP
  4767. This will be encoded as:
  4768. .TS
  4769. center;
  4770. c s s
  4771. c c c
  4772. l l l.
  4773. XDCCC_LINEAR_RGB_CORRECTION property contents for type 1 correction
  4774. _
  4775. \fIField\fP    \fIType\fP    \fIComments\fP
  4776. VisualID0    CARD    Most significant portion of VisualID
  4777. VisualID1    CARD    (exists iff property format is 8)
  4778. VisualID2    CARD    (exists iff property format is 8)
  4779. VisualID3    CARD    Least significant (exists iff property format is 8 or 16)
  4780. type    CARD    1 for this type of correction
  4781. count    CARD    number of tables following (either 1 or 3)
  4782. length    CARD    number of elements - 1 following in this table
  4783. intensity    CARD    Interpret as a number 0 <= intensity <= 1
  4784. \&...    ...    Total of \fIlength+1\fP intensity elements
  4785. lengthg    CARD    number of elements - 1 following in this table (iff \fIcount\fP is 3)
  4786. intensity    CARD    Interpret as a number 0 <= intensity <= 1
  4787. \&...    ...    Total of \fIlengthg+1\fP intensity elements
  4788. lengthb    CARD    number of elements - 1 following in this table (iff \fIcount\fP is 3)
  4789. intensity    CARD    Interpret as a number 0 <= intensity <= 1
  4790. \&...    ...    Total of \fIlengthb+1\fP intensity elements
  4791. .TE
  4792. .NH 1
  4793. Conclusion
  4794. .XS
  4795. \*(SN Conclusion
  4796. .XE
  4797. .LP
  4798. This document provides the protocol-level specification of the minimal
  4799. conventions needed to ensure that X Version 11 clients can 
  4800. interoperate properly.
  4801. A further document is required, specifically
  4802. a \fIWindow and Session Manager Conventions Manual\fP to cover these
  4803. convention from the opposite point of view and to add extra conventions
  4804. of interest to window and session manager implementors.
  4805. .bp
  4806. \&
  4807. .sp 1
  4808. .ce 3
  4809. \s+1\fBAppendix A\fP\s-1
  4810.  
  4811. \s+1\fBCompatibility with Earlier Drafts\fP\s-1
  4812. .sp 2
  4813. .LP
  4814. .XS
  4815. Appendix A: Compatibility with Earlier Drafts
  4816. .XE
  4817. This appendix summarizes the incompatibilities between this and earlier drafts:
  4818. .IP \(bu 5
  4819. The R2 draft
  4820. .IP \(bu 5
  4821. The July 27, 1988 draft
  4822. .IP \(bu 5
  4823. The public review drafts
  4824. .SH
  4825. The R2 Draft
  4826. .LP
  4827. The February 25, 1988 draft that was distributed as part of X Version 11,
  4828. Release 2 was clearly labeled as such,
  4829. and many areas were explicitly labeled as liable to change.
  4830. Nevertheless, in the revision work since then,
  4831. we have been very careful not to introduce gratuitous incompatibility.
  4832. As far as possible,
  4833. we have tried to ensure that clients obeying the conventions
  4834. in the earlier draft would still work.
  4835. .LP
  4836. The areas in which incompatibilities have become necessary are:
  4837. .IP \(bu 5
  4838. The use of property 
  4839. .PN None
  4840. in 
  4841. .PN ConvertSelection
  4842. requests is no longer allowed.
  4843. Owners that receive them are free to use the target atom as the property 
  4844. to respond with,
  4845. which will work in most cases.
  4846. .IP \(bu 5
  4847. The protocol for INCREMENTAL type properties as selection replies has changed,
  4848. and the name has been changed to INCR.
  4849. Selection requestors are free to implement the earlier protocol 
  4850. if they receive properties of type INCREMENTAL.
  4851. .IP \(bu 5
  4852. The protocol for INDIRECT type properties as selection replies has changed,
  4853. and the name has been changed to MULTIPLE.
  4854. Selection requestors are free to implement the earlier protocol 
  4855. if they receive properties of type INDIRECT.
  4856. .IP \(bu 5
  4857. The protocol for the special CLIPBOARD client has changed.
  4858. The earlier protocol is subject to race conditions and should not be used.
  4859. .IP \(bu 5
  4860. The set of state values in WM_HINTS.initial_state has been reduced,
  4861. but the values that are still valid are unchanged.
  4862. Window managers should treat the other values sensibly.
  4863. .IP \(bu 5
  4864. The methods an application uses to change the state of its top-level window
  4865. have changed but in such a way that cases that used to work will still work.
  4866. .IP \(bu 5
  4867. The x, y, width, and height fields have been removed from the WM_NORMAL_HINTS
  4868. property and replaced by pad fields.
  4869. Values set into these fields will be ignored.
  4870. The position and size of the window should be set by setting the appropriate
  4871. window attributes.
  4872. .IP \(bu 5
  4873. A pair of base fields and a win_gravity field have been added 
  4874. to the WM_NORMAL_HINTS property.
  4875. Window managers will assume values for these fields if the client
  4876. sets a short property.
  4877. .SH
  4878. The July 27, 1988 Draft
  4879. .LP
  4880. The Consortium review was based on a draft dated July 27, 1988.
  4881. Incompatibilities have been introduced in the following areas:
  4882. .IP \(bu 5
  4883. The messages field of the WM_HINTS property was found to be unwieldy
  4884. and difficult to evolve.
  4885. It has been replaced by the WM_PROTOCOLS property,
  4886. but clients that use the earlier mechanism can be detected 
  4887. because they set the messages bit in the flags field of the WM_HINTS property,
  4888. and window managers can provide a backwards-compatibility mode.
  4889. .IP \(bu 5
  4890. The mechanism described in the earlier draft by which clients installed
  4891. their own subwindow colormaps could not be made to work reliably
  4892. and mandated some features of the look and feel.
  4893. It has been replaced by the WM_COLORMAP_WINDOWS property.
  4894. Clients that use the earlier mechanism can be detected by the WM_COLORMAPS
  4895. property they set on their top-level window,
  4896. but providing a reliable backwards compatibility mode is not possible.
  4897. .IP \(bu 5
  4898. The recommendations for window manager treatment of top-level window borders
  4899. have been changed as those in the earlier draft produced problems
  4900. with Visibility events.
  4901. For nonwindow manager clients,
  4902. there is no incompatibility.
  4903. .IP \(bu 5
  4904. The pseudoroot facility in the earlier draft has been removed.
  4905. Although it has been successfully implemented,
  4906. it turns out to be inadequate to support the uses envisaged.
  4907. An extension will be required to support these uses fully,
  4908. and it was felt that the maximum freedom should be left to the designers
  4909. of the extension.
  4910. In general,
  4911. the previous mechanism was invisible to clients and no incompatibility
  4912. should result.
  4913. .IP \(bu 5
  4914. The addition of the WM_DELETE_WINDOW protocol (which prevents the danger
  4915. that multi-window clients may be terminated unexpectedly)
  4916. has meant some changes in the WM_SAVE_YOURSELF protocol,
  4917. to ensure that the two protocols are orthogonal.
  4918. Clients using the earlier protocol can be detected (see WM_PROTOCOLS above)
  4919. and supported in a backwards-compatibility mode.
  4920. .IP \(bu 5
  4921. The conventions in Section 14.3.1. of \fIXlib \- C Language X Interface\fP
  4922. regarding properties of type RGB_COLOR_MAP have been changed,  
  4923. but clients that use the earlier conventions can be detected 
  4924. because their properties are four bytes shorter.
  4925. These clients will work correctly if the server supports only a single Visual
  4926. or if they use only the Visual of the root.
  4927. These are the only cases in which they would have worked, anyway.
  4928. .SH
  4929. The Public Review Drafts
  4930. .LP
  4931. The public review resulted in a set of mostly editorial changes.
  4932. The changes that introduced some degree of incompatibility are:
  4933. .IP \(bu 5
  4934. A new section (6.3) was added covering the window manager's
  4935. use of Grabs.
  4936. The restrictions it imposes should affect only window managers.
  4937. .IP \(bu 5
  4938. The TARGETS selection target has been clarified,
  4939. and it may be necessary for clients to add some entries to their replies.
  4940. .IP \(bu 5
  4941. A selection owner using INCR transfer should no longer replace targets in
  4942. a MULTIPLE property with the atom INCR.
  4943. .IP \(bu 5
  4944. The contents of the 
  4945. .PN ClientMessage
  4946. event sent by a client to iconify itself has been clarified,
  4947. but there should be no incompatibility because the earlier contents
  4948. would not in fact have worked.
  4949. .IP \(bu 5
  4950. The border-width in synthetic 
  4951. .PN ConfigureNotify
  4952. events is now specified,
  4953. but this should not cause any incompatibility.
  4954. .IP \(bu 5
  4955. Clients are now asked to set a border-width on all 
  4956. .PN ConfigureWindow
  4957. requests.
  4958. .IP \(bu 5
  4959. Window manager properties on icon windows now will be ignored,
  4960. but there should be no incompatibility 
  4961. because there was no specification that they be obeyed previously.
  4962. .IP \(bu 5
  4963. The ordering of real and synthetic 
  4964. .PN ConfigureNotify
  4965. events is now specified,
  4966. but any incompatibility should affect only window managers.
  4967. .IP \(bu 5
  4968. The semantics of WM_SAVE_YOURSELF have been clarified and restricted to
  4969. be a checkpoint operation only.
  4970. Clients that were using it as part of a shutdown sequence may need to
  4971. be modified,
  4972. especially if they were interacting with the user during the shutdown.
  4973. .IP \(bu 5
  4974. A kill_id field has been added to RGB_COLOR_MAP properties.
  4975. Clients using earlier conventions can be detected by the size of their
  4976. RGB_COLOR_MAP properties,
  4977. and the cases that would have worked will still work.
  4978. .bp
  4979. \&
  4980. .sp 1
  4981. .ce 3
  4982. \s+1\fBAppendix B\fP\s-1
  4983.  
  4984. \s+1\fBSuggested Protocol Revisions\fP\s-1
  4985. .sp 2
  4986. .LP
  4987. .XS
  4988. Appendix B: Suggested Protocol Revisions
  4989. .XE
  4990. .LP
  4991. During the development of these conventions,
  4992. a number of inadequacies have been discovered in the protocol.
  4993. They are summarized here as input to an eventual protocol revision
  4994. design process.
  4995. .IP \(bu 5
  4996. There is no way for anyone to find out the last-change time of
  4997. a selection.
  4998. At the next protocol revision, the
  4999. .PN GetSelectionOwner
  5000. request should be changed to return the last-change time as well as the owner.
  5001. .IP \(bu 5
  5002. How does a client find out which selection atoms are valid?
  5003. .IP \(bu 5
  5004. The protocol should be changed to return in response to a 
  5005. .PN GetSelectionOwner
  5006. request the timestamp used to acquire the selection.
  5007. .IP \(bu 5
  5008. There would be no need for WM_TAKE_FOCUS if the 
  5009. .PN FocusIn
  5010. event contained a timestamp and a previous-focus field.
  5011. This could avoid the potential race condition.
  5012. There is space in the event for this information;
  5013. it should be added at the next protocol revision.
  5014. .IP \(bu 5
  5015. There is a race condition in the
  5016. .PN InstallColormap 
  5017. request.
  5018. It does not take a timestamp and may be executed after the top-level colormap
  5019. has been uninstalled.
  5020. The next protocol revision should provide the timestamp in the
  5021. .PN InstallColormap ,
  5022. .PN UninstallColormap ,
  5023. .PN ListInstalledColormaps 
  5024. requests and in the 
  5025. .PN ColormapNotify
  5026. event.
  5027. The timestamp should be used in a similar way to the last-focus-change
  5028. time for the input focus.
  5029. .IP \(bu 5
  5030. The protocol needs to be changed to provide some way of identifying
  5031. the Visual and the Screen of a colormap.
  5032. .IP \(bu 5
  5033. There should be some way to reclaim assignments to the five nonpre-assigned
  5034. modifiers when they are no longer needed.
  5035. .bp
  5036. .tm .pn \n%
  5037. .TC
  5038.