home *** CD-ROM | disk | FTP | other *** search
/ InfoMagic Source Code 1993 July / THE_SOURCE_CODE_CD_ROM.iso / X / mit / doc / Xlib / CH14 < prev    next >
Encoding:
Text File  |  1991-08-27  |  93.1 KB  |  3,616 lines
  1. \&
  2. .sp 1
  3. .ce 3
  4. \s+1\fBChapter 14\fP\s-1
  5.  
  6. \s+1\fBInter-Client Communication Functions\fP\s-1
  7. .sp 2
  8. .nr H1 14
  9. .nr H2 0
  10. .nr H3 0
  11. .nr H4 0
  12. .nr H5 0
  13. .na
  14. .LP
  15. .XS
  16. Chapter 14: Inter-Client Communication Functions
  17. .XE
  18. The \fIInter-Client Communication Conventions Manual\fP,
  19. hereafter referred to as the ICCCM, details the
  20. X Consortium approved conventions that govern inter-client communications.
  21. These conventions ensure peer-to-peer client cooperation in the use 
  22. of selections, cut buffers, and shared resources as well as client cooperation
  23. with window and session managers.
  24. For further information,
  25. see the \fIInter-Client Communication Conventions Manual\fP.
  26. .LP
  27. Xlib provides a number of standard properties and programming interfaces
  28. that are ICCCM compliant.
  29. The predefined atoms for some of these properties are defined in the
  30. .Pn < X11/Xatom.h >
  31. header file, where
  32. to avoid name conflicts with user symbols their
  33. .PN #define
  34. name has an XA_ prefix.
  35. For further information about atoms and properties,
  36. see section 4.3.
  37. .LP
  38. Xlib's selection and cut buffer mechanisms provide the primary programming 
  39. interfaces by which peer client applications communicate with each other 
  40. (see sections 4.5 and 16.6).
  41. The functions discussed in this chapter provide 
  42. the primary programming interfaces by which client applications communicate 
  43. with their window and session managers as well as share standard colormaps.
  44. .LP
  45. The standard properties that are of special interest for communicating 
  46. with window and session managers are:
  47. .IN "Atom" "predefined"
  48. .TS H
  49. lw(1.6i) lw(1i) lw(.4i) lw(2.25i)
  50. lw(1.6i) lw(1i) cw(.4i) lw(2.25i).
  51. _
  52. .sp 6p
  53. .B
  54. Name    Type    Format    Description
  55. .sp 6p
  56. _
  57. .TH
  58. .R
  59. T{
  60. \s-1WM_CLASS\s+1
  61. T}    T{
  62. \s-1STRING\s+1
  63. T}    T{
  64. 8
  65. T}    T{
  66. Set by application programs to allow window and session
  67. managers to obtain the application's resources from the resource database.
  68. T}
  69. .sp 6p
  70. T{
  71. \s-1WM_CLIENT_MACHINE\s+1
  72. T}    T{
  73. \s-1TEXT\s+1
  74. T}    T{
  75. T}    T{
  76. The string name of the machine on which the client application is running.
  77. T}
  78. .sp 6p
  79. T{
  80. \s-1WM_COLORMAP_WINDOWS\s+1
  81. T}    T{
  82. \s-1WINDOW\s+1
  83. T}    T{
  84. 32
  85. T}    T{
  86. The list of window IDs that may need a different colormap
  87. than that of their top-level window.
  88. T}
  89. .sp 6p
  90. T{
  91. \s-1WM_COMMAND\s+1
  92. T}    T{
  93. \s-1TEXT\s+1
  94. T}    T{
  95. T}    T{
  96. The command and arguments, null-separated, used to invoke the
  97. application.
  98. T}
  99. .sp 6p
  100. T{
  101. \s-1WM_HINTS\s+1
  102. T}    T{
  103. \s-1WM_HINTS\s+1
  104. T}    T{
  105. 32
  106. T}    T{
  107. Additional hints set by the client for use by the window manager.
  108. The C type of this property is 
  109. .PN XWMHints .
  110. T}
  111. .sp 6p
  112. T{
  113. \s-1WM_ICON_NAME\s+1
  114. T}    T{
  115. \s-1TEXT\s+1
  116. T}    T{
  117. T}    T{
  118. The name to be used in an icon.
  119. T}
  120. .sp 6p
  121. T{
  122. \s-1WM_ICON_SIZE\s+1
  123. T}    T{
  124. \s-1WM_ICON_SIZE\s+1
  125. T}    T{
  126. 32
  127. T}    T{
  128. The window manager may set this property on the root window to
  129. specify the icon sizes it supports.
  130. The C type of this property is 
  131. .PN XIconSize .
  132. T}
  133. .sp 6p
  134. T{
  135. \s-1WM_NAME\s+1
  136. T}    T{
  137. \s-1TEXT\s+1
  138. T}    T{
  139. T}    T{
  140. The name of the application.
  141. T}
  142. .sp 6p
  143. T{
  144. \s-1WM_NORMAL_HINTS\s+1
  145. T}    T{
  146. \s-1WM_SIZE_HINTS\s+1
  147. T}    T{
  148. 32
  149. T}    T{
  150. Size hints for a window in its normal state.
  151. The C type of this property is
  152. .PN XSizeHints .
  153. T}
  154. .sp 6p
  155. T{
  156. \s-1WM_PROTOCOLS\s+1
  157. T}    T{
  158. \s-1ATOM\s+1
  159. T}    T{
  160. 32
  161. T}    T{
  162. List of atoms that identify the communications protocols between the
  163. client and window manager in which the client is willing to participate.
  164. T}
  165. .sp 6p
  166. T{
  167. \s-1WM_STATE\s+1
  168. T}    T{
  169. \s-1WM_STATE\s+1
  170. T}    T{
  171. 32
  172. T}    T{
  173. Intended for communication between window and session managers only.
  174. T}
  175. .sp 6p
  176. T{
  177. \s-1WM_TRANSIENT_FOR\s+1
  178. T}    T{
  179. \s-1WINDOW\s+1
  180. T}    T{
  181. 32
  182. T}    T{
  183. Set by application programs to indicate to the window manager that a transient
  184. top-level window, such as a dialog box.
  185. T}
  186. .sp 6p
  187. _
  188. .TE
  189. .LP
  190. The remainder of this chapter discusses:
  191. .IP \(bu 5
  192. Client-to-window-manager communication
  193. .IP \(bu 5
  194. Client-to-session-manager communication
  195. .IP \(bu 5
  196. Standard colormaps
  197. .NH 2
  198. Client to Window Manager Communication
  199. .XS
  200. \*(SN Client to Window Manager Communication
  201. .XE
  202. .LP
  203. This section discusses how to:
  204. .IP \(bu 5
  205. Manipulate top-level windows
  206. .IP \(bu 5
  207. Convert string lists
  208. .IP \(bu 5
  209. Set and read text properties
  210. .IP \(bu 5
  211. Set and read the WM_NAME property
  212. .IP \(bu 5
  213. Set and read the WM_ICON_NAME property
  214. .IP \(bu 5
  215. Set and read the WM_HINTS property
  216. .IP \(bu 5
  217. Set and read the WM_NORMAL_HINTS property
  218. .IP \(bu 5
  219. Set and read the WM_CLASS property
  220. .IP \(bu 5
  221. Set and read the WM_TRANSIENT_FOR property
  222. .IP \(bu 5
  223. Set and read the WM_PROTOCOLS property
  224. .IP \(bu 5
  225. Set and read the WM_COLORMAP_WINDOWS property
  226. .IP \(bu 5
  227. Set and read the WM_ICON_SIZE property
  228. .IP \(bu 5
  229. Use window manager convenience functions
  230. .NH 3
  231. Manipulating Top-Level Windows
  232. .XS
  233. \*(SN Manipulating Top-Level Windows
  234. .XE
  235. .LP
  236. Xlib provides functions that you can use to change the visibility or size
  237. of top-level windows (that is, those that were created as children 
  238. of the root window).
  239. Note that the subwindows that you create are ignored by window managers.
  240. Therefore,
  241. you should use the basic window functions described in chapter 3
  242. to manipulate your application's subwindows.
  243. .LP
  244. To request that a top-level window be iconified, use
  245. .PN XIconifyWindow .
  246. .IN "XIconifyWindow" "" "@DEF@"
  247. .\" Start marker code here
  248. .FD 0
  249. Status XIconifyWindow\^(\^\fIdisplay\fP, \fIw\fP, \fIscreen_number\fP\^)
  250. .br
  251.       Display *\fIdisplay\fP\^;
  252. .br
  253.       Window \fIw\fP;
  254. .br
  255.       int \fIscreen_number\fP\^;
  256. .FN
  257. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  258. .IP \fIdisplay\fP 1i
  259. Specifies the connection to the X server.
  260. .\" $Header: w.a,v 1.2 88/05/07 11:35:31 mento Exp $
  261. .IP \fIw\fP 1i
  262. Specifies the window.
  263. .IP \fIscreen_number\fP 1i
  264. Specifies the appropriate screen number on the host server.
  265. .\" End marker code here
  266. .LP
  267. The 
  268. .PN XIconifyWindow 
  269. function sends a WM_CHANGE_STATE 
  270. .PN ClientMessage 
  271. event with a format of 32 and a first data element of 
  272. .PN IconicState 
  273. (as described in section 4.1.4 of the 
  274. \fIInter-Client Communication Conventions Manual\fP)
  275. and a window of w
  276. to the root window of the specified screen
  277. with an event mask set to
  278. .PN SubstructureNotifyMask |
  279. .PN SubstructureRedirectMask .
  280. Window managers may elect to receive this message and
  281. if the window is in its normal state, 
  282. may treat it as a request to change the window's state from normal to iconic.
  283. If the WM_CHANGE_STATE property cannot be interned, 
  284. .PN XIconifyWindow
  285. does not send a message and returns a zero status.
  286. It returns a nonzero status if the client message is sent successfully;
  287. otherwise, it returns a zero status.
  288. .sp
  289. .LP
  290. To request that a top-level window be withdrawn, use
  291. .PN XWithdrawWindow .
  292. .IN "XWithdrawWindow" "" "@DEF@"
  293. .\" Start marker code here
  294. .FD 0
  295. Status XWithdrawWindow\^(\^\fIdisplay\fP, \fIw\fP, \fIscreen_number\fP\^)
  296. .br
  297.       Display *\fIdisplay\fP\^;
  298. .br
  299.       Window \fIw\fP\^;
  300. .br
  301.       int \fIscreen_number\fP\^;
  302. .FN
  303. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  304. .IP \fIdisplay\fP 1i
  305. Specifies the connection to the X server.
  306. .\" $Header: w.a,v 1.2 88/05/07 11:35:31 mento Exp $
  307. .IP \fIw\fP 1i
  308. Specifies the window.
  309. .IP \fIscreen_number\fP 1i
  310. Specifies the appropriate screen number on the host server.
  311. .\" End marker code here
  312. .LP
  313. The 
  314. .PN XWithdrawWindow 
  315. function unmaps the specified window 
  316. and sends a synthetic 
  317. .PN UnmapNotify 
  318. event to the root window of the specified screen.
  319. Window managers may elect to receive this message 
  320. and may treat it as a request to change the window's state to withdrawn.
  321. When a window is in the withdrawn state, 
  322. neither its normal nor its iconic representations is visible.
  323. It returns a nonzero status if the 
  324. .PN UnmapNotify 
  325. event is successfully sent; 
  326. otherwise, it returns a zero status.
  327. .LP
  328. .PN XWithdrawWindow
  329. can generate a
  330. .PN BadWindow
  331. error.
  332. .sp
  333. .LP
  334. To request that a top-level window be reconfigured, use
  335. .PN XReconfigureWMWindow .
  336. .IN "XReconfigureWMWindow" "" "@DEF@"
  337. .\" Start marker code here
  338. .FD 0
  339. Status XReconfigureWMWindow\^(\^\fIdisplay\fP, \fIw\fP, \fIscreen_number\fP, \
  340. \fIvalue_mask\fP, \fIvalues\fP\^)
  341. .br
  342.       Display *\fIdisplay\fP\^;
  343. .br
  344.       Window \fIw\fP\^;
  345. .br
  346.       int \fIscreen_number\fP\^;
  347. .br
  348.       unsigned int \fIvalue_mask\fP\^;
  349. .br
  350.       XWindowChanges *\fIvalues\fP;
  351. .FN
  352. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  353. .IP \fIdisplay\fP 1i
  354. Specifies the connection to the X server.
  355. .\" $Header: w.a,v 1.2 88/05/07 11:35:31 mento Exp $
  356. .IP \fIw\fP 1i
  357. Specifies the window.
  358. .IP \fIscreen_number\fP 1i
  359. Specifies the appropriate screen number on the host server.
  360. .\" $Header: value_mask.a,v 1.2 88/05/07 12:39:38 mento Exp $
  361. .IP \fIvalue_mask\fP 1i
  362. Specifies which values are to be set using information in
  363. the values structure.
  364. This mask is the bitwise inclusive OR of the valid configure window values bits.
  365. .\" $Header: values.a,v 1.2 88/05/07 12:41:05 mento Exp $
  366. .IP \fIvalues\fP 1i
  367. Specifies the 
  368. .PN XWindowChanges 
  369. structure.
  370. .\" End marker code here
  371. .LP
  372. The 
  373. .PN XReconfigureWMWindow 
  374. function issues a 
  375. .PN ConfigureWindow 
  376. request on the specified top-level window.
  377. If the stacking mode is changed and the request fails with a 
  378. .PN BadMatch 
  379. error, 
  380. the error is trapped by Xlib and a synthetic 
  381. .PN ConfigureRequestEvent 
  382. containing the same configuration parameters is sent to the root 
  383. of the specified window.
  384. Window managers may elect to receive this event 
  385. and treat it as a request to reconfigure the indicated window.
  386. It returns a nonzero status if the request or event is successfully sent;
  387. otherwise, it returns a zero status.
  388. .LP
  389. .PN XReconfigureWMWindow 
  390. can generate
  391. .PN BadValue 
  392. and 
  393. .PN BadWindow 
  394. errors.
  395. .NH 3
  396. Converting String Lists
  397. .XS
  398. \*(SN Converting String Lists
  399. .XE
  400. .LP
  401. Many of the text properties allow a variety of types and formats.
  402. Because the data stored in these properties are not
  403. simple null-terminated strings, a
  404. .PN XTextProperty
  405. structure is used to describe the encoding, type, and length of the text 
  406. as well as its value.
  407. The
  408. .PN XTextProperty
  409. structure contains:
  410. .IN "XTextProperty" "" "@DEF@"
  411. .\" Start marker code here
  412. .Ds 0
  413. .TA .5i 2.5i
  414. .ta .5i 2.5i
  415. typedef struct         {
  416.     unsigned char *value;    /* property data */
  417.     Atom encoding;    /* type of property */
  418.     int format;    /* 8, 16, or 32 */
  419.     unsigned long nitems;    /* number of items in value */
  420. } XTextProperty;
  421. .De
  422. .\" End marker code here
  423. .LP
  424. Xlib provides functions to convert localized text to or from encodings
  425. which support the inter-client communication conventions for text.
  426. In addition, functions are provided for converting between lists of pointers 
  427. to character strings and text properties in the STRING encoding.
  428. .LP
  429. The functions for localized text return a signed integer error status 
  430. which encodes 
  431. .PN Success
  432. as zero, specific error conditions as negative numbers, and partial conversion
  433. as a count of unconvertible characters.
  434. .LP
  435. .IN "XICCEncodingStyle" "" "@DEF@"
  436. .\" Start marker code here
  437. .TS
  438. lw(.5i) lw(2i) lw(2.5i).
  439. T{
  440. #define
  441. T}    T{
  442. .PN XNoMemory
  443. T}    T{
  444. \-1
  445. T}
  446. T{
  447. #define
  448. T}    T{
  449. .PN XLocaleNotSupported
  450. T}    T{
  451. \-2
  452. T}
  453. T{
  454. #define
  455. T}    T{
  456. .PN XConverterNotFound
  457. T}    T{
  458. \-3
  459. T}
  460. .TE
  461. .Ds 0
  462. .TA .5i 2.5i
  463. .ta .5i 2.5i
  464. typedef enum {
  465.     XStringStyle,        /* STRING */
  466.     XCompoundTextStyle,    /* COMPOUND_TEXT */
  467.     XTextStyle,        /* text in owner's encoding (current locale) */
  468.     XStdICCTextStyle    /* STRING, else COMPOUND_TEXT */
  469. } XICCEncodingStyle;
  470. .De
  471. .\" End marker code here
  472. .sp
  473. .LP
  474. To convert a list of text strings to an 
  475. .PN XTextProperty
  476. structure, use
  477. .PN XmbTextListToTextProperty
  478. or
  479. .PN XwcTextListToTextProperty .
  480. .IN "XmbTextListToTextProperty" "" "@DEF@"
  481. .IN "XwcTextListToTextProperty" "" "@DEF@"
  482. .\" Start marker code here
  483. .FD 0
  484. int XmbTextListToTextProperty\^(\^\fIdisplay\fP\^, \fIlist\fP\^, \fIcount\fP\^, \fIstyle\fP\^, \fItext_prop_return\fP\^)
  485. .br
  486.       Display *\fIdisplay\fP\^;
  487. .br
  488.       char **\fIlist\fP\^;
  489. .br
  490.       int \fIcount\fP\^;
  491. .br
  492.       XICCEncodingStyle \fIstyle\fP\^;
  493. .br
  494.       XTextProperty *\fItext_prop_return\fP\^;
  495. .FN
  496. .FD 0
  497. int XwcTextListToTextProperty\^(\^\fIdisplay\fP\^, \fIlist\fP\^, \fIcount\fP\^, \fIstyle\fP\^, \fItext_prop_return\fP\^)
  498. .br
  499.       Display *\fIdisplay\fP\^;
  500. .br
  501.       wchar_t **\fIlist\fP\^;
  502. .br
  503.       int \fIcount\fP\^;
  504. .br
  505.       XICCEncodingStyle \fIstyle\fP\^;
  506. .br
  507.       XTextProperty *\fItext_prop_return\fP\^;
  508. .FN
  509. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  510. .IP \fIdisplay\fP 1i
  511. Specifies the connection to the X server.
  512. .IP \fIlist\fP 1i
  513. Specifies a list of null-terminated character strings.
  514. .IP \fIcount\fP 1i
  515. Specifies the number of strings specified.
  516. .IP \fIstyle\fP 1i
  517. Specifies the manner in which the property is encoded.
  518. .IP \fItext_prop_return\fP 1i
  519. Returns the
  520. .PN XTextProperty
  521. structure.
  522. .\" End marker code here
  523. .LP
  524. The
  525. .PN XmbTextListToTextProperty
  526. and
  527. .PN XwcTextListToTextProperty
  528. functions set the specified 
  529. .PN XTextProperty
  530. value to a set of null-separated elements representing the concatenation
  531. of the specified list of null-terminated text strings.
  532. A final terminating null is stored at the end of the value field 
  533. of text_prop_return but is not included in the nitems member.
  534. .LP
  535. The functions set the encoding field of text_prop_return to an Atom 
  536. for the specified display 
  537. naming the encoding determined by the specified style, 
  538. and convert the specified text list to this encoding for storage in
  539. the text_prop_return value field.
  540. If the style 
  541. .PN XStringStyle
  542. or 
  543. .PN XCompoundTextStyle
  544. is specified,
  545. this encoding is ``STRING'' or ``COMPOUND_TEXT'', respectively.
  546. If the style 
  547. .PN XTextStyle
  548. is specified,
  549. this encoding is the encoding of the current locale.
  550. If the style 
  551. .PN XStdICCTextStyle
  552. is specified,
  553. this encoding is ``STRING'' if the text is fully convertible to STRING,
  554. else ``COMPOUND_TEXT''.
  555. .LP
  556. If insufficient memory is available for the new value string,
  557. the functions return 
  558. .PN XNoMemory .
  559. If the current locale is not supported,
  560. the functions return 
  561. .PN XLocaleNotSupported .
  562. In both of these error cases,
  563. the functions do not set text_prop_return.
  564. .LP
  565. To determine if the functions are guaranteed not to return
  566. .PN XLocaleNotSupported ,
  567. use
  568. .PN XSupportsLocale .
  569. .LP
  570. If the supplied text is not fully convertible to the specified encoding,
  571. the functions return the number of unconvertible characters.
  572. Each unconvertible character is converted to an implementation-defined and
  573. encoding-specific default string.
  574. Otherwise, the functions return 
  575. .PN Success .
  576. Note that full convertibility to all styles except 
  577. .PN XStringStyle
  578. is guaranteed.
  579. .LP
  580. To free the storage for the value field, use
  581. .PN XFree .
  582. .sp
  583. .LP
  584. To obtain a list of text strings from an 
  585. .PN XTextProperty 
  586. structure, use
  587. .PN XmbTextPropertyToTextList
  588. or
  589. .PN XwcTextPropertyToTextList .
  590. .IN "XmbTextPropertyToTextList" "" "@DEF@"
  591. .IN "XwcTextPropertyToTextList" "" "@DEF@"
  592. .\" Start marker code here
  593. .FD 0
  594. int XmbTextPropertyToTextList\^(\^\fIdisplay\fP\^, \fItext_prop\fP\^, \fIlist_return\fP\^, \fIcount_return\fP\^)
  595. .br
  596.       Display *\fIdisplay\fP\^;
  597. .br
  598.       XTextProperty *\fItext_prop\fP\^;
  599. .br
  600.       char ***\fIlist_return\fP\^;
  601. .br
  602.       int *\fIcount_return\fP\^;
  603. .FN
  604. .FD 0
  605. int XwcTextPropertyToTextList\^(\^\fIdisplay\fP\^, \fItext_prop\fP\^, \fIlist_return\fP\^, \fIcount_return\fP\^)
  606. .br
  607.       Display *\fIdisplay\fP\^;
  608. .br
  609.       XTextProperty *\fItext_prop\fP\^;
  610. .br
  611.       wchar_t ***\fIlist_return\fP\^;
  612. .br
  613.       int *\fIcount_return\fP\^;
  614. .FN
  615. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  616. .IP \fIdisplay\fP 1i
  617. Specifies the connection to the X server.
  618. .IP \fItext_prop\fP 1i
  619. Specifies the
  620. .PN XTextProperty
  621. structure to be used.
  622. .IP \fIlist_return\fP 1i
  623. Returns a list of null-terminated character strings.
  624. .ds Cn strings
  625. .IP \fIcount_return\fP 1i
  626. Returns the number of \*(Cn.
  627. .\" End marker code here
  628. .LP
  629. The 
  630. .PN XmbTextPropertyToTextList
  631. and 
  632. .PN XwcTextPropertyToTextList
  633. functions return a list of text strings in the current locale representing the
  634. null-separated elements of the specified
  635. .PN XTextProperty
  636. structure.
  637. The data in text_prop must be format 8.
  638. .LP
  639. Multiple elements of the property (for example, the strings in a disjoint
  640. text selection) are separated by a null byte.
  641. The contents of the property are not required to be null-terminated;
  642. any terminating null should not be included in text_prop.nitems.
  643. .LP
  644. If insufficient memory is available for the list and its elements,
  645. .PN XmbTextPropertyToTextList
  646. and
  647. .PN XwcTextPropertyToTextList
  648. return 
  649. .PN XNoMemory .
  650. If the current locale is not supported,
  651. the functions return
  652. .PN XLocaleNotSupported .
  653. Otherwise, if the encoding field of text_prop is not convertible 
  654. to the encoding of the current locale,
  655. the functions return
  656. .PN XConverterNotFound .
  657. For supported locales,
  658. existence of a converter from COMPOUND_TEXT, STRING,
  659. or the encoding of the current locale is guaranteed if
  660. .PN XSupportsLocale 
  661. returns 
  662. .PN True
  663. for the current locale (but the actual text may contain unconvertible characters.)
  664. Conversion of other encodings is implementation-dependent.
  665. In all of these error cases,
  666. the functions do not set any return values.
  667. .LP
  668. Otherwise, 
  669. .PN XmbTextPropertyToTextList
  670. and
  671. .PN XwcTextPropertyToTextList
  672. return the list of null-terminated text strings to list_return,
  673. and the number of text strings to count_return.
  674. .LP
  675. If the value field of text_prop is not fully convertible to the encoding of
  676. the current locale,
  677. the functions return the number of unconvertible characters.
  678. Each unconvertible character is converted to a string in the
  679. current locale that is specific to the current locale.
  680. To obtain the value of this string, 
  681. use
  682. .PN XDefaultString .
  683. Otherwise,
  684. .PN XmbTextPropertyToTextList
  685. and
  686. .PN XwcTextPropertyToTextList
  687. return 
  688. .PN Success .
  689. .LP
  690. To free the storage for the list and its contents returned by
  691. .PN XmbTextPropertyToTextList ,
  692. use
  693. .PN XFreeStringList .
  694. To free the storage for the list and its contents returned by
  695. .PN XwcTextPropertyToTextList ,
  696. use
  697. .PN XwcFreeStringList .
  698. .sp
  699. .LP
  700. To free the in-memory data associated with the specified
  701. wide character string list, use
  702. .PN XwcFreeStringList .
  703. .IN "XwcFreeStringList" "" "@DEF@"
  704. .\" Start marker code here
  705. .FD 0
  706. void XwcFreeStringList\^(\^\fIlist\fP\^)
  707. .br
  708.       wchar_t **\fIlist\fP\^;
  709. .FN
  710. .IP \fIlist\fP 1i
  711. Specifies the list of strings to be freed.
  712. .\" End marker code here
  713. .LP
  714. The
  715. .PN XwcFreeStringList
  716. function frees memory allocated by
  717. .PN XwcTextPropertyToTextList .
  718. .sp
  719. .LP
  720. To obtain the default string for text conversion in the current locale,
  721. use
  722. .PN XDefaultString .
  723. .IN "XDefaultString" "" "@DEF@"
  724. .\" Start marker code here
  725. .FD 0
  726. char *XDefaultString\^(\|)
  727. .FN
  728. .\" End marker code here
  729. .LP
  730. The
  731. .PN XDefaultString
  732. function returns the default string used by Xlib for text conversion
  733. (for example, in 
  734. .PN XmbTextListToTextProperty ).
  735. The default string is the string in the current locale which is output 
  736. when an unconvertible character is found during text conversion.
  737. If the string returned by
  738. .PN XDefaultString
  739. is the empty string (""),
  740. no character is output in the converted text.
  741. .PN XDefaultString
  742. does not return NULL.
  743. .LP
  744. The string returned by 
  745. .PN XDefaultString
  746. is independent of the default string for text drawing;
  747. see 
  748. .PN XCreateFontSet
  749. to obtain the default string for an
  750. .PN XFontSet .
  751. .LP
  752. The behavior when an invalid codepoint is supplied to any Xlib function is
  753. undefined.
  754. .LP
  755. The returned string is null-terminated.
  756. It is owned by Xlib and should not be modified or freed by the client.
  757. It may be freed after the current locale is changed.
  758. Until freed, it will not be modified by Xlib.
  759. .sp
  760. .LP
  761. To set the specified list of strings in the STRING encoding to a 
  762. .PN XTextProperty
  763. structure, use
  764. .PN XStringListToTextProperty .
  765. .IN "XStringListToTextProperty" "" "@DEF@"
  766. .\" Start marker code here
  767. .FD 0
  768. Status XStringListToTextProperty\^(\^\fIlist\fP, \fIcount\fP, \
  769. \fItext_prop_return\fP\^)
  770. .br
  771.       char **\fIlist\fP\^;
  772. .br
  773.       int \fIcount\fP\^;
  774. .br
  775.       XTextProperty *\fItext_prop_return\fP\^;
  776. .FN
  777. .IP \fIlist\fP 1i
  778. Specifies a list of null-terminated character strings.
  779. .ds Cn strings
  780. .IP \fIcount\fP 1i
  781. Specifies the number of \*(Cn.
  782. .IP \fItext_prop_return\fP 1i
  783. Returns the
  784. .PN XTextProperty
  785. structure.
  786. .\" End marker code here
  787. .LP
  788. The 
  789. .PN XStringListToTextProperty 
  790. function sets the specified 
  791. .PN XTextProperty
  792. to be of type STRING (format 8) with a value representing the
  793. concatenation of the specified list of null-separated character strings.
  794. An extra null byte (which is not included in the nitems member) 
  795. is stored at the end of the value field of text_prop_return.
  796. The strings are assumed (without verification) to be in the STRING encoding.
  797. If insufficient memory is available for the new value string, 
  798. .PN XStringListToTextProperty
  799. does not set any fields in the
  800. .PN XTextProperty
  801. structure and returns a zero status.
  802. Otherwise, it returns a nonzero status.
  803. To free the storage for the value field, use 
  804. .PN XFree .
  805. .sp
  806. .LP
  807. To obtain a list of strings from a specified
  808. .PN XTextProperty
  809. structure in the STRING encoding, use
  810. .PN XTextPropertyToStringList .
  811. .IN "XTextPropertyToStringList" "" "@DEF@"
  812. .\" Start marker code here
  813. .FD 0
  814. Status XTextPropertyToStringList\^(\^\fItext_prop\fP, \fIlist_return\fP, \
  815. \fIcount_return\fP\^)
  816. .br
  817.        XTextProperty *\fItext_prop\fP\^;
  818. .br
  819.        char ***\fIlist_return\fP\^;
  820. .br
  821.        int *\fIcount_return\fP\^;
  822. .FN
  823. .IP \fItext_prop\fP 1i
  824. Specifies the
  825. .PN XTextProperty
  826. structure to be used.
  827. .IP \fIlist_return\fP 1i
  828. Returns a list of null-terminated character strings.
  829. .ds Cn strings
  830. .IP \fIcount_return\fP 1i
  831. Returns the number of \*(Cn.
  832. .\" End marker code here
  833. .LP
  834. The 
  835. .PN XTextPropertyToStringList 
  836. function returns a list of strings representing the null-separated elements 
  837. of the specified
  838. .PN XTextProperty
  839. structure.
  840. The data in text_prop must be of type STRING and format 8. 
  841. Multiple elements of the property 
  842. (for example, the strings in a disjoint text selection) 
  843. are separated by NULL (encoding 0).
  844. The contents of the property are not null-terminated.
  845. If insufficient memory is available for the list and its elements, 
  846. .PN XTextPropertyToStringList
  847. sets no return values and returns a zero status.
  848. Otherwise, it returns a nonzero status.
  849. To free the storage for the list and its contents, use 
  850. .PN XFreeStringList .
  851. .sp
  852. .LP
  853. To free the in-memory data associated with the specified string list, use
  854. .PN XFreeStringList .
  855. .IN "XFreeStringList" "" "@DEF@"
  856. .\" Start marker code here
  857. .FD 0
  858. void XFreeStringList\^(\^\fIlist\fP\^)
  859. .br
  860.       char **\fIlist\fP\^;
  861. .FN
  862. .IP \fIlist\fP 1i
  863. Specifies the list of strings to be freed.
  864. .\" End marker code here
  865. .LP
  866. The 
  867. .PN XFreeStringList 
  868. function releases memory allocated by 
  869. .PN XmbTextPropertyToTextList
  870. and
  871. .PN XTextPropertyToStringList ,
  872. and the missing charset list allocated by 
  873. .PN XCreateFontSet .
  874. .NH 3
  875. Setting and Reading Text Properties
  876. .XS
  877. \*(SN Setting and Reading Text Properties
  878. .XE
  879. .LP
  880. Xlib provides two functions that you can use to set and read
  881. the text properties for a given window.
  882. You can use these functions to set and read those properties of type TEXT
  883. (WM_NAME, WM_ICON_NAME, WM_COMMAND, and WM_CLIENT_MACHINE).
  884. In addition,
  885. Xlib provides separate convenience functions that you can use to set each 
  886. of these properties.
  887. For further information about these convenience functions,
  888. see sections 14.1.4, 14.1.5, 14.2.1, and 14.2.2, respectively.
  889. .sp
  890. .LP
  891. To set one of a window's text properties, use
  892. .PN XSetTextProperty .
  893. .IN "XSetTextProperty" "" "@DEF@"
  894. .\" Start marker code here
  895. .FD 0
  896. void XSetTextProperty\^(\^\fIdisplay\fP, \fIw\fP, \fItext_prop\fP, \
  897. \fIproperty\fP\^)
  898. .br
  899.       Display *\fIdisplay\fP\^;
  900. .br
  901.       Window \fIw\fP\^;
  902. .br
  903.       XTextProperty *\fItext_prop\fP\^;
  904. .br
  905.       Atom \fIproperty\fP\^;
  906. .FN
  907. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  908. .IP \fIdisplay\fP 1i
  909. Specifies the connection to the X server.
  910. .\" $Header: w.a,v 1.2 88/05/07 11:35:31 mento Exp $
  911. .IP \fIw\fP 1i
  912. Specifies the window.
  913. .IP \fItext_prop\fP 1i
  914. Specifies the
  915. .PN XTextProperty
  916. structure to be used.
  917. .\" $Header: property.a,v 1.2 88/04/05 15:19:43 mento Exp $
  918. .IP \fIproperty\fP 1i
  919. Specifies the property name.
  920. .\" End marker code here
  921. .LP
  922. The
  923. .PN XSetTextProperty
  924. function replaces the existing specified property for the named window 
  925. with the data, type, format, and number of items determined 
  926. by the value field, the encoding field, the format field, 
  927. and the nitems field, respectively, of the specified
  928. .PN XTextProperty
  929. structure.
  930. If the property does not already exist,
  931. .PN XSetTextProperty
  932. sets it for the specified window.
  933. .LP
  934. .PN XSetTextProperty
  935. can generate
  936. .PN BadAlloc ,
  937. .PN BadAtom , 
  938. .PN BadValue , 
  939. and 
  940. .PN BadWindow  
  941. errors.
  942. .sp
  943. .LP
  944. To read one of a window's text properties, use
  945. .PN XGetTextProperty .
  946. .IN "XGetTextProperty" "" "@DEF@"
  947. .\" Start marker code here
  948. .FD 0
  949. Status XGetTextProperty\^(\^\fIdisplay\fP, \fIw\fP, \fItext_prop_return\fP, \
  950. \fIproperty\fP\^)
  951. .br
  952.        Display *\fIdisplay\fP\^;
  953. .br
  954.        Window \fIw\fP\^;
  955. .br
  956.        XTextProperty *\fItext_prop_return\fP\^;
  957. .br
  958.        Atom \fIproperty\fP\^;
  959. .FN
  960. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  961. .IP \fIdisplay\fP 1i
  962. Specifies the connection to the X server.
  963. .\" $Header: w.a,v 1.2 88/05/07 11:35:31 mento Exp $
  964. .IP \fIw\fP 1i
  965. Specifies the window.
  966. .IP \fItext_prop_return\fP 1i
  967. Returns the
  968. .PN XTextProperty
  969. structure.
  970. .\" $Header: property.a,v 1.2 88/04/05 15:19:43 mento Exp $
  971. .IP \fIproperty\fP 1i
  972. Specifies the property name.
  973. .\" End marker code here
  974. .LP
  975. The
  976. .PN XGetTextProperty 
  977. function reads the specified property from the window
  978. and stores the data in the returned
  979. .PN XTextProperty
  980. structure.
  981. It stores the data in the value field,
  982. the type of the data in the encoding field,
  983. the format of the data in the format field, 
  984. and the number of items of data in the nitems field.
  985. An extra byte containing null (which is not included in the nitems member) 
  986. is stored at the end of the value field of text_prop_return.
  987. The particular interpretation of the property's encoding 
  988. and data as ``text'' is left to the calling application.
  989. If the specified property does not exist on the window,
  990. .PN XGetTextProperty
  991. sets the value field to NULL, 
  992. the encoding field to None, 
  993. the format field to zero, 
  994. and the nitems field to zero.
  995. .LP
  996. If it was able to read and store the data in the
  997. .PN XTextProperty
  998. structure,
  999. .PN XGetTextProperty
  1000. returns a nonzero status; 
  1001. otherwise, it returns a zero status.
  1002. .LP
  1003. .PN XGetTextProperty
  1004. can generate
  1005. .PN BadAtom 
  1006. and 
  1007. .PN BadWindow 
  1008. errors.
  1009. .NH 3
  1010. Setting and Reading the WM_NAME Property
  1011. .XS
  1012. \*(SN Setting and Reading the WM_NAME Property
  1013. .XE
  1014. .LP
  1015. Xlib provides convenience functions that you can use to set and read 
  1016. the WM_NAME property for a given window.
  1017. .sp
  1018. .LP
  1019. To set a window's WM_NAME property with the supplied convenience function, use
  1020. .PN XSetWMName .
  1021. .IN "XSetWMName" "" "@DEF@"
  1022. .\" Start marker code here
  1023. .FD 0
  1024. void XSetWMName\^(\^\fIdisplay\fP, \fIw\fP, \fItext_prop\fP\^)
  1025. .br
  1026.       Display *\fIdisplay\fP\^;
  1027. .br
  1028.       Window \fIw\fP\^;
  1029. .br
  1030.       XTextProperty *\fItext_prop\fP\^;
  1031. .FN
  1032. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  1033. .IP \fIdisplay\fP 1i
  1034. Specifies the connection to the X server.
  1035. .\" $Header: w.a,v 1.2 88/05/07 11:35:31 mento Exp $
  1036. .IP \fIw\fP 1i
  1037. Specifies the window.
  1038. .IP \fItext_prop\fP 1i
  1039. Specifies the
  1040. .PN XTextProperty
  1041. structure to be used.
  1042. .\" End marker code here
  1043. .LP
  1044. The
  1045. .PN XSetWMName
  1046. convenience function calls
  1047. .PN XSetTextProperty 
  1048. to set the WM_NAME property.
  1049. .sp
  1050. .LP
  1051. To read a window's WM_NAME property with the supplied convenience function, use
  1052. .PN XGetWMName .
  1053. .IN "XGetWMName" "" "@DEF@"
  1054. .\" Start marker code here
  1055. .FD 0
  1056. Status XGetWMName\^(\^\fIdisplay\fP, \fIw\fP, \fItext_prop_return\fP\^)
  1057. .br
  1058.       Display *\fIdisplay\fP\^;
  1059. .br
  1060.       Window \fIw\fP\^;
  1061. .br
  1062.       XTextProperty *\fItext_prop_return\fP\^;
  1063. .FN
  1064. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  1065. .IP \fIdisplay\fP 1i
  1066. Specifies the connection to the X server.
  1067. .\" $Header: w.a,v 1.2 88/05/07 11:35:31 mento Exp $
  1068. .IP \fIw\fP 1i
  1069. Specifies the window.
  1070. .IP \fItext_prop_return\fP 1i
  1071. Returns the
  1072. .PN XTextProperty
  1073. structure.
  1074. .\" End marker code here
  1075. .LP
  1076. The
  1077. .PN XGetWMName 
  1078. convenience function calls
  1079. .PN XGetTextProperty 
  1080. to obtain the WM_NAME property.
  1081. It returns nonzero status on success; otherwise it returns a zero status.
  1082. .LP
  1083. The following two functions have been superseded by
  1084. .PN XSetWMName
  1085. and
  1086. .PN XGetWMName ,
  1087. respectively. 
  1088. You can use these additional convenience functions 
  1089. for window names that are encoded as STRING properties.
  1090. .sp
  1091. .LP
  1092. To assign a name to a window, use
  1093. .PN XStoreName .
  1094. .IN "Window" "name"
  1095. .IN "XStoreName" "" "@DEF@"
  1096. .\" Start marker code here
  1097. .FD 0
  1098. .\" $Header: XStoreName.f,v 1.1 88/02/26 10:03:53 mento Exp $
  1099. XStoreName\^(\^\fIdisplay\fP, \fIw\fP\^, \fIwindow_name\fP\^)
  1100. .br
  1101.       Display *\fIdisplay\fP\^;
  1102. .br
  1103.       Window \fIw\fP\^;
  1104. .br
  1105.       char *\fIwindow_name\fP\^;
  1106. .FN
  1107. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  1108. .IP \fIdisplay\fP 1i
  1109. Specifies the connection to the X server.
  1110. .\" $Header: w.a,v 1.2 88/05/07 11:35:31 mento Exp $
  1111. .IP \fIw\fP 1i
  1112. Specifies the window.
  1113. .\" $Header: window_name.a,v 1.2 88/05/18 05:22:36 mento Exp $
  1114. .IP \fIwindow_name\fP 1i
  1115. Specifies the window name,
  1116. which should be a null-terminated string.
  1117. .\" End marker code here
  1118. .LP
  1119. .\" $Header: XStoreName.d,v 1.2 88/06/11 07:53:51 mento Exp $
  1120. The
  1121. .PN XStoreName
  1122. function assigns the name passed to window_name to the specified window.
  1123. A window manager can display the window name in some prominent
  1124. place, such as the title bar, to allow users to identify windows easily.
  1125. Some window managers may display a window's name in the window's icon,
  1126. although they are encouraged to use the window's icon name
  1127. if one is provided by the application.
  1128. If the string is not in the Host Portable Character Encoding
  1129. the result is implementation dependent.
  1130. .LP
  1131. .PN XStoreName
  1132. can generate
  1133. .PN BadAlloc
  1134. and
  1135. .PN BadWindow
  1136. errors.
  1137. .LP
  1138. .sp
  1139. To get the name of a window, use
  1140. .PN XFetchName .
  1141. .IN "XFetchName" "" "@DEF@"
  1142. .\" Start marker code here
  1143. .FD 0
  1144. .\" $Header: XFetchName.f,v 1.2 88/04/07 14:34:36 mento Exp $
  1145. Status XFetchName\^(\^\fIdisplay\fP, \fIw\fP\^, \fIwindow_name_return\fP\^)
  1146. .br
  1147.       Display *\fIdisplay\fP\^;
  1148. .br
  1149.       Window \fIw\fP\^;
  1150. .br
  1151.       char **\fIwindow_name_return\fP\^;
  1152. .FN
  1153. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  1154. .IP \fIdisplay\fP 1i
  1155. Specifies the connection to the X server.
  1156. .\" $Header: w.a,v 1.2 88/05/07 11:35:31 mento Exp $
  1157. .IP \fIw\fP 1i
  1158. Specifies the window.
  1159. .\" $Header: window_name1.a,v 1.2 88/05/17 11:14:20 mento Exp $
  1160. .IP \fIwindow_name_return\fP 1i
  1161. Returns the window name, which is a null-terminated string.
  1162. .\" End marker code here
  1163. .LP
  1164. .\" $Header: XFetchName.d,v 1.5 88/06/11 07:50:16 mento Exp $
  1165. The
  1166. .PN XFetchName
  1167. function returns the name of the specified window.
  1168. If it succeeds,
  1169. it returns nonzero; 
  1170. otherwise, no name has been set for the window,
  1171. and it returns zero.
  1172. If the WM_NAME property has not been set for this window,
  1173. .PN XFetchName
  1174. sets window_name_return to NULL.
  1175. If the data returned by the server is in the Latin Portable Character Encoding,
  1176. then the returned string is in the Host Portable Character Encoding.
  1177. Otherwise, the result is implementation dependent.
  1178. When finished with it, a client must free
  1179. the window name string using
  1180. .PN XFree .
  1181. .LP
  1182. .PN XFetchName
  1183. can generate a
  1184. .PN BadWindow
  1185. error.
  1186. .NH 3
  1187. Setting and Reading the WM_ICON_NAME Property
  1188. .XS
  1189. \*(SN Setting and Reading the WM_ICON_NAME Property
  1190. .XE
  1191. .LP
  1192. Xlib provides convenience functions that you can use to set and read 
  1193. the WM_ICON_NAME property for a given window.
  1194. .LP
  1195. .sp
  1196. To set a window's WM_ICON_NAME property,
  1197. use
  1198. .PN XSetWMIconName .
  1199. .IN "XSetWMIconName" "" "@DEF@"
  1200. .\" Start marker code here
  1201. .FD 0
  1202. void XSetWMIconName\^(\^\fIdisplay\fP, \fIw\fP, \fItext_prop\fP\^)
  1203. .br
  1204.       Display *\fIdisplay\fP\^;
  1205. .br
  1206.       Window \fIw\fP\^;
  1207. .br
  1208.       XTextProperty *\fItext_prop\fP\^;
  1209. .FN
  1210. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  1211. .IP \fIdisplay\fP 1i
  1212. Specifies the connection to the X server.
  1213. .\" $Header: w.a,v 1.2 88/05/07 11:35:31 mento Exp $
  1214. .IP \fIw\fP 1i
  1215. Specifies the window.
  1216. .IP \fItext_prop\fP 1i
  1217. Specifies the
  1218. .PN XTextProperty
  1219. structure to be used.
  1220. .\" End marker code here
  1221. .LP
  1222. The
  1223. .PN XSetWMIconName
  1224. convenience function calls
  1225. .PN XSetTextProperty
  1226. to set the WM_ICON_NAME property.
  1227. .sp
  1228. .LP
  1229. To read a window's WM_ICON_NAME property,
  1230. use
  1231. .PN XGetWMIconName .
  1232. .IN "XGetWMIconName" "" "@DEF@"
  1233. .\" Start marker code here
  1234. .FD 0
  1235. Status XGetWMIconName\^(\^\fIdisplay\fP, \fIw\fP, \fItext_prop_return\fP\^)
  1236. .br
  1237.       Display *\fIdisplay\fP\^;
  1238. .br
  1239.       Window \fIw\fP\^;
  1240. .br
  1241.       XTextProperty *\fItext_prop_return\fP\^;
  1242. .FN
  1243. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  1244. .IP \fIdisplay\fP 1i
  1245. Specifies the connection to the X server.
  1246. .\" $Header: w.a,v 1.2 88/05/07 11:35:31 mento Exp $
  1247. .IP \fIw\fP 1i
  1248. Specifies the window.
  1249. .IP \fItext_prop_return\fP 1i
  1250. Returns the
  1251. .PN XTextProperty
  1252. structure.
  1253. .\" End marker code here
  1254. .LP
  1255. The 
  1256. .PN XGetWMIconName 
  1257. convenience function calls
  1258. .PN XGetTextProperty 
  1259. to obtain the WM_ICON_NAME property.
  1260. It returns nonzero status on success; otherwise it returns a zero status.
  1261. .LP
  1262. The next two functions have been superseded by
  1263. .PN XSetWMIconName
  1264. and
  1265. .PN XGetWMIconName ,
  1266. respectively.
  1267. You can use these additional convenience functions 
  1268. for window names that are encoded as STRING properties.
  1269. .sp
  1270. .LP
  1271. .sp
  1272. To set the name to be displayed in a window's icon, use
  1273. .PN XSetIconName .
  1274. .IN "Window" "icon name"
  1275. .IN "XSetIconName" "" "@DEF@"
  1276. .\" Start marker code here
  1277. .FD 0
  1278. .\" $Header: XSetIName.f,v 1.1 88/02/26 10:03:16 mento Exp $
  1279. XSetIconName\^(\^\fIdisplay\fP, \fIw\fP\^, \fIicon_name\fP\^)
  1280. .br
  1281.       Display *\fIdisplay\fP\^;
  1282. .br
  1283.       Window \fIw\fP\^;
  1284. .br
  1285.       char *\fIicon_name\fP\^;
  1286. .FN
  1287. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  1288. .IP \fIdisplay\fP 1i
  1289. Specifies the connection to the X server.
  1290. .\" $Header: w.a,v 1.2 88/05/07 11:35:31 mento Exp $
  1291. .IP \fIw\fP 1i
  1292. Specifies the window.
  1293. .\" $Header: icon_name.a,v 1.2 88/05/17 11:22:33 mento Exp $
  1294. .IP \fIicon_name\fP 1i
  1295. Specifies the icon name,
  1296. which should be a null-terminated string.
  1297. .\" End marker code here
  1298. .LP
  1299. If the string is not in the Host Portable Character Encoding
  1300. the result is implementation dependent.
  1301. .PN XSetIconName
  1302. can generate
  1303. .PN BadAlloc
  1304. and
  1305. .PN BadWindow
  1306. errors.
  1307. .LP
  1308. .sp
  1309. To get the name a window wants displayed in its icon, use
  1310. .PN XGetIconName .
  1311. .IN "XGetIconName" "" "@DEF@"
  1312. .\" Start marker code here
  1313. .FD 0
  1314. .\" $Header: XGetIName.f,v 1.2 88/04/07 14:39:05 mento Exp $
  1315. Status XGetIconName\^(\^\fIdisplay\fP, \fIw\fP\^, \fIicon_name_return\fP\^)
  1316. .br
  1317.       Display *\fIdisplay\fP\^;
  1318. .br
  1319.       Window \fIw\fP\^;
  1320. .br
  1321.       char **\fIicon_name_return\fP\^;
  1322. .FN
  1323. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  1324. .IP \fIdisplay\fP 1i
  1325. Specifies the connection to the X server.
  1326. .\" $Header: w.a,v 1.2 88/05/07 11:35:31 mento Exp $
  1327. .IP \fIw\fP 1i
  1328. Specifies the window.
  1329. .\" $Header: icon_name1.a,v 1.2 88/05/17 11:24:31 mento Exp $
  1330. .IP \fIicon_name_return\fP 1i
  1331. Returns the window's icon name,
  1332. which is a null-terminated string.
  1333. .\" End marker code here
  1334. .LP
  1335. .\" $Header: XGetIName.d,v 1.4 88/06/11 07:51:07 mento Exp $
  1336. The
  1337. .PN XGetIconName
  1338. function returns the name to be displayed in the specified window's icon.
  1339. If it succeeds, it returns nonzero; otherwise, 
  1340. if no icon name has been set for the window,
  1341. it returns zero.
  1342. If you never assigned a name to the window,
  1343. .PN XGetIconName
  1344. sets icon_name_return to NULL.
  1345. If the data returned by the server is in the Latin Portable Character Encoding,
  1346. then the returned string is in the Host Portable Character Encoding.
  1347. Otherwise, the result is implementation dependent.
  1348. When finished with it, a client must free
  1349. the icon name string using
  1350. .PN XFree .
  1351. .LP
  1352. .PN XGetIconName
  1353. can generate a
  1354. .PN BadWindow
  1355. error.
  1356. .NH 3
  1357. Setting and Reading the WM_HINTS Property
  1358. .XS
  1359. \*(SN Setting and Reading the WM_HINTS Property
  1360. .XE
  1361. .LP
  1362. Xlib provides functions that you can use to set and read 
  1363. the WM_HINTS property for a given window.
  1364. These functions use the flags and the
  1365. .PN XWMHints 
  1366. structure, as defined in the
  1367. .Pn < X11/Xutil.h >
  1368. header file.
  1369. .sp
  1370. .LP
  1371. To allocate an
  1372. .PN XWMHints
  1373. structure, use
  1374. .PN XAllocWMHints .
  1375. .IN "XAllocWMHints" "" "@DEF@"
  1376. .\" Start marker code here
  1377. .FD 0
  1378. XWMHints *XAllocWMHints\^(\|)
  1379. .FN
  1380. .\" End marker code here
  1381. .LP
  1382. The
  1383. .PN XAllocWMHints
  1384. function allocates and returns a pointer to a
  1385. .PN XWMHints
  1386. structure.
  1387. Note that all fields in the
  1388. .PN XWMHints
  1389. structure are initially set to zero.
  1390. If insufficient memory is available, 
  1391. .PN XAllocWMHints
  1392. returns NULL.
  1393. To free the memory allocated to this structure,
  1394. use
  1395. .PN XFree .
  1396. .LP
  1397. The
  1398. .PN XWMHints
  1399. structure contains:
  1400. .LP
  1401. .\" Start marker code here
  1402. /* Window manager hints mask bits */
  1403. .TS
  1404. lw(.5i) lw(2.5i) lw(2.5i).
  1405. T{
  1406. #define
  1407. T}    T{
  1408. .PN InputHint
  1409. T}    T{
  1410. (1L << 0)
  1411. T}
  1412. T{
  1413. #define
  1414. T}    T{
  1415. .PN StateHint
  1416. T}    T{
  1417. (1L << 1)
  1418. T}
  1419. T{
  1420. #define
  1421. T}    T{
  1422. .PN IconPixmapHint
  1423. T}    T{
  1424. (1L << 2)
  1425. T}
  1426. T{
  1427. #define
  1428. T}    T{
  1429. .PN IconWindowHint
  1430. T}    T{
  1431. (1L << 3)
  1432. T}
  1433. T{
  1434. #define
  1435. T}    T{
  1436. .PN IconPositionHint
  1437. T}    T{
  1438. (1L << 4)
  1439. T}
  1440. T{
  1441. #define
  1442. T}    T{
  1443. .PN IconMaskHint
  1444. T}    T{
  1445. (1L << 5)
  1446. T}
  1447. T{
  1448. #define
  1449. T}    T{
  1450. .PN WindowGroupHint
  1451. T}    T{
  1452. (1L << 6)
  1453. T}
  1454. T{
  1455. #define
  1456. T}    T{
  1457. .PN AllHints
  1458. T}    T{
  1459. (InputHint|StateHint|IconPixmapHint|
  1460. .br
  1461. IconWindowHint|IconPositionHint|
  1462. .br
  1463. IconMaskHint|WindowGroupHint)
  1464. T}
  1465. .TE
  1466. .IN "XWMHints" "" "@DEF@"
  1467. .Ds 0
  1468. .TA .5i 2.5i
  1469. .ta .5i 2.5i
  1470. /* Values */
  1471.  
  1472. typedef struct {
  1473.     long flags;    /* marks which fields in this structure are defined */
  1474.     Bool input;    /* does this application rely on the window manager to
  1475.             get keyboard input? */
  1476.     int initial_state;    /* see below */
  1477.     Pixmap icon_pixmap;    /* pixmap to be used as icon */
  1478.     Window icon_window;    /* window to be used as icon */
  1479.     int icon_x, icon_y;    /* initial position of icon */
  1480.     Pixmap icon_mask;    /* pixmap to be used as mask for icon_pixmap */
  1481.     XID window_group;    /* id of related window group */
  1482.     /* this structure may be extended in the future */
  1483. } XWMHints;
  1484. .De
  1485. .\" End marker code here
  1486. .LP
  1487. The input member is used to communicate to the window manager the input focus
  1488. model used by the application.
  1489. Applications that expect input but never explicitly set focus to any 
  1490. of their subwindows (that is, use the push model of focus management), 
  1491. such as X Version 10 style applications that use real-estate
  1492. driven focus, should set this member to 
  1493. .PN True .  
  1494. Similarly, applications
  1495. that set input focus to their subwindows only when it is given to their
  1496. top-level window by a window manager should also set this member to 
  1497. .PN True .
  1498. Applications that manage their own input focus by explicitly setting
  1499. focus to one of their subwindows whenever they want keyboard input 
  1500. (that is, use the pull model of focus management) should set this member to 
  1501. .PN False .
  1502. Applications that never expect any keyboard input also should set this member
  1503. to 
  1504. .PN False .
  1505. .LP
  1506. Pull model window managers should make it possible for push model
  1507. applications to get input by setting input focus to the top-level windows of
  1508. applications whose input member is 
  1509. .PN True .  
  1510. Push model window managers should
  1511. make sure that pull model applications do not break them 
  1512. by resetting input focus to 
  1513. .PN PointerRoot 
  1514. when it is appropriate (for example, whenever an application whose
  1515. input member is 
  1516. .PN False 
  1517. sets input focus to one of its subwindows).
  1518. .LP
  1519. The definitions for the initial_state flag are:
  1520. .TS
  1521. lw(.5i) lw(2i) lw(.2i) lw(2.8i).
  1522. T{
  1523. #define
  1524. T}    T{
  1525. .PN WithdrawnState
  1526. T}    T{
  1527. 0
  1528. T}    T{
  1529. T}
  1530. T{
  1531. #define
  1532. T}    T{
  1533. .PN NormalState
  1534. T}    T{
  1535. 1
  1536. T}    T{
  1537. /* most applications start this way */
  1538. T}
  1539. T{
  1540. #define
  1541. T}    T{
  1542. .PN IconicState
  1543. T}    T{
  1544. 3
  1545. T}    T{
  1546. /* application wants to start as an icon */
  1547. T}
  1548. .TE
  1549. The icon_mask specifies which pixels of the icon_pixmap should be used as the
  1550. icon.  
  1551. This allows for nonrectangular icons.
  1552. Both icon_pixmap and icon_mask must be bitmaps.
  1553. The icon_window lets an application provide a window for use as an icon
  1554. for window managers that support such use.
  1555. The window_group lets you specify that this window belongs to a group
  1556. of other windows.
  1557. For example, if a single application manipulates multiple 
  1558. top-level windows, this allows you to provide enough
  1559. information that a window manager can iconify all of the windows
  1560. rather than just the one window.
  1561. .LP
  1562. .sp
  1563. To set a window's WM_HINTS property, use
  1564. .PN XSetWMHints .
  1565. .IN "XSetWMHints" "" "@DEF@"
  1566. .\" Start marker code here
  1567. .FD 0
  1568. XSetWMHints\^(\^\fIdisplay\fP, \fIw\fP, \fIwmhints\fP\^)
  1569. .br
  1570.       Display *\fIdisplay\fP\^;
  1571. .br
  1572.       Window \fIw\fP\^;
  1573. .br
  1574.       XWMHints *\fIwmhints\fP\^;
  1575.  
  1576. .FN
  1577. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  1578. .IP \fIdisplay\fP 1i
  1579. Specifies the connection to the X server.
  1580. .\" $Header: w.a,v 1.2 88/05/07 11:35:31 mento Exp $
  1581. .IP \fIw\fP 1i
  1582. Specifies the window.
  1583. .IP \fIwmhints\fP 1i
  1584. Specifies the 
  1585. .PN XWMHints
  1586. structure to be used.
  1587. .\" End marker code here
  1588. .LP
  1589. .\" $Header: XSetWMHnts.d,v 1.1 88/02/26 10:51:06 mento Exp $
  1590. The
  1591. .PN XSetWMHints
  1592. function sets the window manager hints that include icon information and location,
  1593. the initial state of the window, and whether the application relies on the
  1594. window manager to get keyboard input.
  1595. .LP
  1596. .PN XSetWMHints
  1597. can generate
  1598. .PN BadAlloc
  1599. and
  1600. .PN BadWindow 
  1601. errors.
  1602. .LP
  1603. .sp
  1604. To read a window's WM_HINTS property, use
  1605. .PN XGetWMHints .
  1606. .IN "XGetWMHints" "" "@DEF@"
  1607. .\" Start marker code here
  1608. .FD 0
  1609. XWMHints *XGetWMHints\^(\^\fIdisplay\fP, \fIw\fP\^)
  1610. .br
  1611.       Display *\fIdisplay\fP\^;
  1612. .br
  1613.       Window \fIw\fP\^;
  1614. .FN
  1615. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  1616. .IP \fIdisplay\fP 1i
  1617. Specifies the connection to the X server.
  1618. .\" $Header: w.a,v 1.2 88/05/07 11:35:31 mento Exp $
  1619. .IP \fIw\fP 1i
  1620. Specifies the window.
  1621. .\" End marker code here
  1622. .LP
  1623. .\" $Header: XGetWMHnts.d,v 1.5 88/06/11 07:51:30 mento Exp $
  1624. The
  1625. .PN XGetWMHints
  1626. function reads the window manager hints and 
  1627. returns NULL if no WM_HINTS property was set on the window 
  1628. or returns a pointer to a 
  1629. .PN XWMHints 
  1630. structure if it succeeds.
  1631. When finished with the data,
  1632. free the space used for it by calling
  1633. .PN XFree .
  1634. .LP
  1635. .PN XGetWMHints
  1636. can generate a
  1637. .PN BadWindow 
  1638. error.
  1639. .NH 3
  1640. Setting and Reading the WM_NORMAL_HINTS Property
  1641. .XS
  1642. \*(SN Setting and Reading the WM_NORMAL_HINTS Property
  1643. .XE
  1644. .LP
  1645. Xlib provides functions that you can use to set or read 
  1646. the WM_NORMAL_HINTS property for a given window.
  1647. The functions use the flags and the
  1648. .PN XSizeHints 
  1649. structure, as defined in the
  1650. .Pn < X11/Xutil.h >
  1651. header file.
  1652. .sp
  1653. .LP
  1654. To allocate an
  1655. .PN XSizeHints
  1656. structure, use
  1657. .PN XAllocSizeHints .
  1658. .IN "XAllocSizeHints" "" "@DEF@"
  1659. .\" Start marker code here
  1660. .FD 0
  1661. XSizeHints *XAllocSizeHints\^(\|)
  1662. .FN
  1663. .\" End marker code here
  1664. .LP
  1665. The
  1666. .PN XAllocSizeHints
  1667. function allocates and returns a pointer to a
  1668. .PN XSizeHints
  1669. structure.
  1670. Note that all fields in the
  1671. .PN XSizeHints
  1672. structure are initially set to zero.
  1673. If insufficient memory is available, 
  1674. .PN XAllocSizeHints
  1675. returns NULL.
  1676. To free the memory allocated to this structure,
  1677. use
  1678. .PN XFree .
  1679. .LP
  1680. The
  1681. .PN XSizeHints
  1682. structure contains:
  1683. .LP
  1684. .\" Start marker code here
  1685. /* Size hints mask bits */
  1686. .TS
  1687. lw(.7i) lw(1.1i) lw(.9i) lw(3.1i).
  1688. T{
  1689. #define
  1690. T}    T{
  1691. .PN USPosition
  1692. T}    T{
  1693. (1L << 0)
  1694. T}    T{
  1695. /* user specified x, y */
  1696. T}
  1697. T{
  1698. #define
  1699. T}    T{
  1700. .PN USSize
  1701. T}    T{
  1702. (1L << 1)
  1703. T}    T{
  1704. /* user specified width, height */
  1705. T}
  1706. T{
  1707. #define
  1708. T}    T{
  1709. .PN PPosition
  1710. T}    T{
  1711. (1L << 2)
  1712. T}    T{
  1713. /* program specified position */
  1714. T}
  1715. T{
  1716. #define
  1717. T}    T{
  1718. .PN PSize
  1719. T}    T{
  1720. (1L << 3)
  1721. T}    T{
  1722. /* program specified size */
  1723. T}
  1724. T{
  1725. #define
  1726. T}    T{
  1727. .PN PMinSize
  1728. T}    T{
  1729. (1L << 4)
  1730. T}    T{
  1731. /* program specified minimum size */
  1732. T}
  1733. T{
  1734. #define
  1735. T}    T{
  1736. .PN PMaxSize
  1737. T}    T{
  1738. (1L << 5)
  1739. T}    T{
  1740. /* program specified maximum size */
  1741. T}
  1742. T{
  1743. #define
  1744. T}    T{
  1745. .PN PResizeInc
  1746. T}    T{
  1747. (1L << 6)
  1748. T}    T{
  1749. /* program specified resize increments */
  1750. T}
  1751. T{
  1752. #define
  1753. T}    T{
  1754. .PN PAspect
  1755. T}    T{
  1756. (1L << 7)
  1757. T}    T{
  1758. /* program specified min and max aspect ratios */
  1759. T}
  1760. T{
  1761. #define
  1762. T}    T{
  1763. .PN PBaseSize
  1764. T}    T{
  1765. (1L << 8)
  1766. T}
  1767. T{
  1768. #define
  1769. T}    T{
  1770. .PN PWinGravity
  1771. T}    T{
  1772. (1L << 9)
  1773. T}
  1774. T{
  1775. #define
  1776. T}    T{
  1777. .PN PAllHints
  1778. T}    T{
  1779. (PPosition|PSize|PMinSize|
  1780. .br
  1781. PMaxSize|PResizeInc|PAspect)
  1782. T}    T{
  1783. T}
  1784. .TE
  1785. .IN "XSizeHints" "" "@DEF@"
  1786. .Ds 0
  1787. .TA .5i 2.5i
  1788. .ta .5i 2.5i
  1789. /* Values */
  1790.  
  1791. typedef struct {
  1792.     long flags;    /* marks which fields in this structure are defined */
  1793.     int x, y;    /* Obsolete */
  1794.     int width, height;    /* Obsolete */
  1795.     int min_width, min_height;
  1796.     int max_width, max_height;
  1797.     int width_inc, height_inc;
  1798.     struct {
  1799.            int x;    /* numerator */
  1800.            int y;    /* denominator */
  1801.     } min_aspect, max_aspect;
  1802.     int base_width, base_height;
  1803.     int win_gravity;
  1804. } XSizeHints;
  1805. .De
  1806. .\" End marker code here
  1807. .LP
  1808. The x, y, width, and height members are now obsolete
  1809. and are left solely for compatibility reasons.
  1810. The min_width and min_height members specify the
  1811. minimum window size that still allows the application to be useful.
  1812. The max_width and max_height members specify the maximum window size.
  1813. The width_inc and height_inc members define an arithmetic progression of
  1814. sizes (minimum to maximum) into which the window prefers to be resized.
  1815. The min_aspect and max_aspect members are expressed
  1816. as ratios of x and y, 
  1817. and they allow an application to specify the range of aspect
  1818. ratios it prefers.
  1819. The base_width and base_height members define the desired size of the window.
  1820. The window manager will interpret the position of the window 
  1821. and its border width to position the point of the outer rectangle 
  1822. of the overall window specified by the win_gravity member.
  1823. The outer rectangle of the window includes any borders or decorations
  1824. supplied by the window manager.
  1825. In other words,
  1826. if the window manager decides to place the window where the client asked,
  1827. the position on the parent window's border named by the win_gravity 
  1828. will be placed where the client window would have been placed 
  1829. in the absence of a window manager.
  1830. .LP
  1831. Note that use of the
  1832. .PN PAllHints
  1833. macro is highly discouraged.
  1834. .sp
  1835. .LP
  1836. To set a window's WM_NORMAL_HINTS property, use
  1837. .PN XSetWMNormalHints .
  1838. .IN "XSetWMNormalHints" "" "@DEF@"
  1839. .\" Start marker code here
  1840. .FD 0
  1841. void XSetWMNormalHints\^(\^\fIdisplay\fP, \fIw\fP, \fIhints\fP\^)
  1842. .br
  1843.       Display *\fIdisplay\fP\^;
  1844. .br
  1845.       Window \fIw\fP\^;
  1846. .br
  1847.       XSizeHints *\fIhints\fP\^;
  1848. .FN
  1849. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  1850. .IP \fIdisplay\fP 1i
  1851. Specifies the connection to the X server.
  1852. .\" $Header: w.a,v 1.2 88/05/07 11:35:31 mento Exp $
  1853. .IP \fIw\fP 1i
  1854. Specifies the window.
  1855. .IP \fIhints\fP 1i
  1856. Specifies the size hints for the window in its normal state.
  1857. .\" End marker code here
  1858. .LP
  1859. The 
  1860. .PN XSetWMNormalHints 
  1861. function replaces the size hints for the WM_NORMAL_HINTS property 
  1862. on the specified window.
  1863. If the property does not already exist,
  1864. .PN XSetWMNormalHints
  1865. sets the size hints for the WM_NORMAL_HINTS property on the specified window.
  1866. The property is stored with a type of WM_SIZE_HINTS and a format of 32.
  1867. .LP
  1868. .PN XSetWMNormalHints
  1869. can generate
  1870. .PN BadAlloc
  1871. and
  1872. .PN BadWindow
  1873. errors.
  1874. .sp
  1875. .LP
  1876. To read a window's WM_NORMAL_HINTS property, use
  1877. .PN XGetWMNormalHints .
  1878. .IN "XGetWMNormalHints" "" "@DEF@"
  1879. .\" Start marker code here
  1880. .FD 0
  1881. Status XGetWMNormalHints\^(\^\fIdisplay\fP, \fIw\fP, \fIhints_return\fP, \
  1882. \fIsupplied_return\fP\^)
  1883. .br
  1884.       Display *\fIdisplay\fP\^;
  1885. .br
  1886.       Window \fIw\fP\^;
  1887. .br
  1888.       XSizeHints *\fIhints_return\fP\^;
  1889. .br
  1890.       long *\fIsupplied_return\fP\^;
  1891. .FN
  1892. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  1893. .IP \fIdisplay\fP 1i
  1894. Specifies the connection to the X server.
  1895. .\" $Header: w.a,v 1.2 88/05/07 11:35:31 mento Exp $
  1896. .IP \fIw\fP 1i
  1897. Specifies the window.
  1898. .IP \fIhints_return\fP 1i
  1899. Returns the size hints for the window in its normal state.
  1900. .IP \fIsupplied_return\fP 1i
  1901. Returns the hints that were supplied by the user.
  1902. .\" End marker code here
  1903. .LP
  1904. The 
  1905. .PN XGetWMNormalHints 
  1906. function returns the size hints stored in the WM_NORMAL_HINTS property 
  1907. on the specified window.
  1908. If the property is of type WM_SIZE_HINTS, is of format 32,
  1909. and is long enough to contain either an old (pre-ICCCM) 
  1910. or new size hints structure, 
  1911. .PN XGetWMNormalHints
  1912. sets the various fields of the 
  1913. .PN XSizeHints
  1914. structure, sets the supplied_return argument to the list of fields 
  1915. that were supplied by the user (whether or not they contained defined values),
  1916. and returns a nonzero status.
  1917. Otherwise, it returns a zero status.
  1918. .LP
  1919. If 
  1920. .PN XGetWMNormalHints
  1921. returns successfully and a pre-ICCCM size hints property is read, 
  1922. the supplied_return argument will contain the following bits:
  1923. .LP
  1924. .Ds
  1925. (USPosition|USSize|PPosition|PSize|PMinSize|
  1926.  PMaxSize|PResizeInc|PAspect)
  1927. .De
  1928. .LP
  1929. If the property is large enough to contain the base size 
  1930. and window gravity fields as well, 
  1931. the supplied_return argument will also contain the following bits:
  1932. .LP
  1933. .Ds
  1934. PBaseSize|PWinGravity
  1935. .De
  1936. .LP
  1937. .PN XGetWMNormalHints
  1938. can generate a
  1939. .PN BadWindow
  1940. error.
  1941. .sp
  1942. .LP
  1943. To set a window's WM_SIZE_HINTS property, use
  1944. .PN XSetWMSizeHints .
  1945. .IN "XSetWMSizeHints" "" "@DEF@"
  1946. .\" Start marker code here
  1947. .FD 0
  1948. void XSetWMSizeHints\^(\^\fIdisplay\fP, \fIw\fP, \fIhints\fP, \fIproperty\fP\^)
  1949. .br
  1950.       Display *\fIdisplay\fP\^;
  1951. .br
  1952.       Window \fIw\fP\^;
  1953. .br
  1954.       XSizeHints *\fIhints\fP\^;
  1955. .br
  1956.       Atom \fIproperty\fP\^;
  1957. .FN
  1958. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  1959. .IP \fIdisplay\fP 1i
  1960. Specifies the connection to the X server.
  1961. .\" $Header: w.a,v 1.2 88/05/07 11:35:31 mento Exp $
  1962. .IP \fIw\fP 1i
  1963. Specifies the window.
  1964. .IP \fIhints\fP 1i
  1965. Specifies the
  1966. .PN XSizeHints
  1967. structure to be used.
  1968. .\" $Header: property.a,v 1.2 88/04/05 15:19:43 mento Exp $
  1969. .IP \fIproperty\fP 1i
  1970. Specifies the property name.
  1971. .\" End marker code here
  1972. .LP
  1973. The 
  1974. .PN XSetWMSizeHints 
  1975. function replaces the size hints for the specified property 
  1976. on the named window.
  1977. If the specified property does not already exist,
  1978. .PN XSetWMSizeHints
  1979. sets the size hints for the specified property
  1980. on the named window.
  1981. The property is stored with a type of WM_SIZE_HINTS and a format of 32.
  1982. To set a window's normal size hints, 
  1983. you can use the 
  1984. .PN XSetWMNormalHints
  1985. function.
  1986. .LP
  1987. .PN XSetWMSizeHints
  1988. can generate
  1989. .PN BadAlloc ,
  1990. .PN BadAtom , 
  1991. and 
  1992. .PN BadWindow
  1993. errors.
  1994. .sp
  1995. .LP
  1996. To read a window's WM_SIZE_HINTS property, use
  1997. .PN XGetWMSizeHints .
  1998. .IN "XGetWMSizeHints" "" "@DEF@"
  1999. .\" Start marker code here
  2000. .FD 0
  2001. Status XGetWMSizeHints\^(\^\fIdisplay\fP, \fIw\fP, \fIhints_return\fP, \
  2002. \fIsupplied_return\fP, \fIproperty\fP\^)
  2003. .br
  2004.       Display *\fIdisplay\fP\^;
  2005. .br
  2006.       Window \fIw\fP\^;
  2007. .br
  2008.       XSizeHints *\fIhints_return\fP\^;
  2009. .br
  2010.       long *\fIsupplied_return\fP\^;
  2011. .br
  2012.       Atom \fIproperty\fP\^;
  2013. .FN
  2014. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  2015. .IP \fIdisplay\fP 1i
  2016. Specifies the connection to the X server.
  2017. .\" $Header: w.a,v 1.2 88/05/07 11:35:31 mento Exp $
  2018. .IP \fIw\fP 1i
  2019. Specifies the window.
  2020. .IP \fIhints_return\fP 1i
  2021. Returns the
  2022. .PN XSizeHints
  2023. structure.
  2024. .IP \fIsupplied_return\fP 1i
  2025. Returns the hints that were supplied by the user.
  2026. .\" $Header: property.a,v 1.2 88/04/05 15:19:43 mento Exp $
  2027. .IP \fIproperty\fP 1i
  2028. Specifies the property name.
  2029. .\" End marker code here
  2030. .LP
  2031. The 
  2032. .PN XGetWMSizeHints
  2033. function returns the size hints stored in the specified property 
  2034. on the named window.
  2035. If the property is of type WM_SIZE_HINTS, is of format 32, 
  2036. and is long enough to contain either an old (pre-ICCCM) 
  2037. or new size hints structure, 
  2038. .PN XGetWMSizeHints
  2039. sets the various fields of the 
  2040. .PN XSizeHints
  2041. structure, sets the supplied_return argument to the
  2042. list of fields that were supplied by the user 
  2043. (whether or not they contained defined values), 
  2044. and returns a nonzero status.
  2045. Otherwise, it returns a zero status.
  2046. To get a window's normal size hints, 
  2047. you can use the 
  2048. .PN XGetWMNormalHints 
  2049. function.
  2050. .LP
  2051. If 
  2052. .PN XGetWMSizeHints
  2053. returns successfully and a pre-ICCCM size hints property is read, 
  2054. the supplied_return argument will contain the following bits:
  2055. .LP
  2056. .Ds
  2057. (USPosition|USSize|PPosition|PSize|PMinSize|
  2058.  PMaxSize|PResizeInc|PAspect)
  2059. .De
  2060. .LP
  2061. If the property is large enough to contain the base size 
  2062. and window gravity fields as well, 
  2063. the supplied_return argument will also contain the following bits:
  2064. .LP
  2065. .Ds
  2066. PBaseSize|PWinGravity
  2067. .De
  2068. .LP
  2069. .PN XGetWMSizeHints
  2070. can generate
  2071. .PN BadAtom 
  2072. and 
  2073. .PN BadWindow
  2074. errors.
  2075. .NH 3
  2076. Setting and Reading the WM_CLASS Property
  2077. .XS
  2078. \*(SN Setting and Reading the WM_CLASS Property
  2079. .XE
  2080. .LP
  2081. Xlib provides functions that you can use to set and get 
  2082. the WM_CLASS property for a given window.
  2083. These functions use the
  2084. .PN XClassHint 
  2085. structure, which is defined in the
  2086. .Pn < X11/Xutil.h >
  2087. header file.
  2088. .sp
  2089. .LP
  2090. To allocate an
  2091. .PN XClassHint
  2092. structure, use
  2093. .PN XAllocClassHint .
  2094. .IN "XAllocClassHint" "" "@DEF@"
  2095. .\" Start marker code here
  2096. .FD 0
  2097. XClassHint *XAllocClassHint\^(\|)
  2098. .FN
  2099. .\" End marker code here
  2100. .LP
  2101. The
  2102. .PN XAllocClassHint
  2103. function allocates and returns a pointer to a
  2104. .PN XClassHint
  2105. structure.
  2106. Note that the pointer fields in the
  2107. .PN XClassHint
  2108. structure are initially set to NULL.
  2109. If insufficient memory is available, 
  2110. .PN XAllocClassHint
  2111. returns NULL.
  2112. To free the memory allocated to this structure,
  2113. use
  2114. .PN XFree .
  2115. .LP
  2116. The
  2117. .PN XClassHint
  2118. contains:
  2119. .LP
  2120. .\" Start marker code here
  2121. .IN "XClassHint" "" "@DEF@"
  2122. .Ds 0
  2123. .TA .5i
  2124. .ta .5i
  2125. typedef struct {
  2126.     char *res_name;
  2127.     char *res_class;
  2128. } XClassHint;
  2129. .De
  2130. .\" End marker code here
  2131. .LP
  2132. The res_name member contains the application name, 
  2133. and the res_class member contains the application class. 
  2134. Note that the name set in this property may differ from the name set as WM_NAME.
  2135. That is, WM_NAME specifies what should be displayed in the title bar and,
  2136. therefore, can contain temporal information (for example, the name of
  2137. a file currently in an editor's buffer).
  2138. On the other hand, 
  2139. the name specified as part of WM_CLASS is the formal name of the application
  2140. that should be used when retrieving the application's resources from the 
  2141. resource database.
  2142. .LP
  2143. .sp
  2144. To set a window's WM_CLASS property, use
  2145. .PN XSetClassHint .
  2146. .IN "XSetClassHint" "" "@DEF@"
  2147. .\" Start marker code here
  2148. .FD 0
  2149. XSetClassHint\^(\^\fIdisplay\fP, \fIw\fP, \fIclass_hints\fP\^)
  2150. .br
  2151.       Display *\fIdisplay\fP\^;
  2152. .br
  2153.       Window \fIw\fP\^;
  2154. .br
  2155.       XClassHint *\fIclass_hints\fP\^;
  2156. .FN
  2157. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  2158. .IP \fIdisplay\fP 1i
  2159. Specifies the connection to the X server.
  2160. .\" $Header: w.a,v 1.2 88/05/07 11:35:31 mento Exp $
  2161. .IP \fIw\fP 1i
  2162. Specifies the window.
  2163. .IP \fIclass_hints\fP 1i
  2164. Specifies the
  2165. .PN XClassHint
  2166. structure that is to be used.
  2167. .\" End marker code here
  2168. .LP
  2169. The
  2170. .PN XSetClassHint
  2171. function sets the class hint for the specified window.
  2172. If the strings are not in the Host Portable Character Encoding
  2173. the result is implementation dependent.
  2174. .LP
  2175. .PN XSetClassHint
  2176. can generate
  2177. .PN BadAlloc
  2178. and
  2179. .PN BadWindow
  2180. errors. 
  2181. .LP
  2182. .sp
  2183. To read a window's WM_CLASS property, use
  2184. .PN XGetClassHint .
  2185. .IN "XGetClassHint" "" "@DEF@"
  2186. .\" Start marker code here
  2187. .FD 0
  2188. Status XGetClassHint\^(\^\fIdisplay\fP, \fIw\fP, \fIclass_hints_return\fP\^)
  2189. .br
  2190.       Display *\fIdisplay\fP\^;
  2191. .br
  2192.       Window \fIw\fP;
  2193. .br
  2194.       XClassHint *\fIclass_hints_return\fP\^;
  2195. .FN
  2196. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  2197. .IP \fIdisplay\fP 1i
  2198. Specifies the connection to the X server.
  2199. .\" $Header: w.a,v 1.2 88/05/07 11:35:31 mento Exp $
  2200. .IP \fIw\fP 1i
  2201. Specifies the window.
  2202. .IP \fIclass_hints_return\fP 1i
  2203. Returns the 
  2204. .PN XClassHint
  2205. structure.
  2206. .\" End marker code here
  2207. .LP
  2208. The
  2209. .PN XGetClassHint
  2210. function returns the class hint of the specified window to the members
  2211. of the supplied structure.
  2212. If the data returned by the server is in the Latin Portable Character Encoding,
  2213. then the returned strings are in the Host Portable Character Encoding.
  2214. Otherwise, the result is implementation dependent.
  2215. It returns nonzero status on success; otherwise it returns a zero status.
  2216. To free res_name and res_class when finished with the strings,
  2217. use
  2218. .PN XFree
  2219. on each individually.
  2220. .LP
  2221. .PN XGetClassHint
  2222. can generate a
  2223. .PN BadWindow 
  2224. error.
  2225. .NH 3
  2226. Setting and Reading the WM_TRANSIENT_FOR Property
  2227. .XS
  2228. \*(SN Setting and Reading the WM_TRANSIENT_FOR Property
  2229. .XE
  2230. .LP
  2231. Xlib provides functions that you can use to set and read
  2232. the WM_TRANSIENT_FOR property for a given window.
  2233. .LP
  2234. .sp
  2235. To set a window's WM_TRANSIENT_FOR property, use
  2236. .PN XSetTransientForHint .
  2237. .IN "XSetTransientForHint" "" "@DEF@"
  2238. .\" Start marker code here
  2239. .FD 0
  2240. XSetTransientForHint\^(\^\fIdisplay\fP, \fIw\fP, \fIprop_window\fP\^)
  2241. .br
  2242.       Display *\fIdisplay\fP\^;
  2243. .br
  2244.       Window \fIw\fP\^;
  2245. .br
  2246.       Window \fIprop_window\fP\^;
  2247. .FN
  2248. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  2249. .IP \fIdisplay\fP 1i
  2250. Specifies the connection to the X server.
  2251. .\" $Header: w.a,v 1.2 88/05/07 11:35:31 mento Exp $
  2252. .IP \fIw\fP 1i
  2253. Specifies the window.
  2254. .IP \fIprop_window\fP 1i
  2255. Specifies the window that the WM_TRANSIENT_FOR property is to be set to.
  2256. .\" End marker code here
  2257. .LP
  2258. The
  2259. .PN XSetTransientForHint
  2260. function sets the WM_TRANSIENT_FOR property of the specified window to the 
  2261. specified prop_window.
  2262. .LP
  2263. .PN XSetTransientForHint
  2264. can generate
  2265. .PN BadAlloc
  2266. and
  2267. .PN BadWindow
  2268. errors.
  2269. .LP
  2270. .sp
  2271. To read a window's WM_TRANSIENT_FOR property, use
  2272. .PN XGetTransientForHint .
  2273. .IN "XGetTransientForHint" "" "@DEF@"
  2274. .\" Start marker code here
  2275. .FD 0
  2276. Status XGetTransientForHint\^(\^\fIdisplay\fP, \fIw\fP, \fIprop_window_return\fP\^)
  2277. .br
  2278.       Display *\fIdisplay\fP\^;
  2279. .br
  2280.       Window \fIw\fP\^;
  2281. .br
  2282.       Window *\fIprop_window_return\fP\^;
  2283. .FN
  2284. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  2285. .IP \fIdisplay\fP 1i
  2286. Specifies the connection to the X server.
  2287. .\" $Header: w.a,v 1.2 88/05/07 11:35:31 mento Exp $
  2288. .IP \fIw\fP 1i
  2289. Specifies the window.
  2290. .IP \fIprop_window_return\fP 1i
  2291. Returns the WM_TRANSIENT_FOR property of the specified window.
  2292. .\" End marker code here
  2293. .LP
  2294. The
  2295. .PN XGetTransientForHint
  2296. function returns the WM_TRANSIENT_FOR property for the specified window.
  2297. It returns nonzero status on success; otherwise it returns a zero status.
  2298. .LP
  2299. .PN XGetTransientForHint
  2300. can generate a
  2301. .PN BadWindow 
  2302. error.
  2303. .NH 3
  2304. Setting and Reading the WM_PROTOCOLS Property
  2305. .XS
  2306. \*(SN Setting and Reading the WM_PROTOCOLS Property
  2307. .XE
  2308. .LP
  2309. Xlib provides functions that you can use to set and read
  2310. the WM_PROTOCOLS property for a given window.
  2311. .LP
  2312. .sp
  2313. To set a window's WM_PROTOCOLS property, use
  2314. .PN XSetWMProtocols .
  2315. .IN "XSetWMProtocols" "" "@DEF@"
  2316. .\" Start marker code here
  2317. .FD 0
  2318. Status XSetWMProtocols\^(\^\fIdisplay\fP, \fIw\fP, \fIprotocols\fP, \
  2319. \fIcount\fP\^)
  2320. .br
  2321.       Display *\fIdisplay\fP\^;
  2322. .br
  2323.       Window \fIw\fP\^;
  2324. .br
  2325.       Atom *\fIprotocols\fP\^;
  2326. .br
  2327.       int \fIcount\fP\^;
  2328. .FN
  2329. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  2330. .IP \fIdisplay\fP 1i
  2331. Specifies the connection to the X server.
  2332. .\" $Header: w.a,v 1.2 88/05/07 11:35:31 mento Exp $
  2333. .IP \fIw\fP 1i
  2334. Specifies the window.
  2335. .IP \fIprotocols\fP 1i
  2336. Specifies the list of protocols.
  2337. .ds Cn protocols in the list
  2338. .IP \fIcount\fP 1i
  2339. Specifies the number of \*(Cn.
  2340. .\" End marker code here
  2341. .LP
  2342. The 
  2343. .PN XSetWMProtocols 
  2344. function replaces the WM_PROTOCOLS property on the specified window 
  2345. with the list of atoms specified by the protocols argument.
  2346. If the property does not already exist,
  2347. .PN XSetWMProtocols
  2348. sets the WM_PROTOCOLS property on the specified window
  2349. to the list of atoms specified by the protocols argument.
  2350. The property is stored with a type of ATOM and a format of 32.
  2351. If it cannot intern the WM_PROTOCOLS atom, 
  2352. .PN XSetWMProtocols
  2353. returns a zero status.
  2354. Otherwise, it returns a nonzero status.
  2355. .LP
  2356. .PN XSetWMProtocols
  2357. can generate
  2358. .PN BadAlloc
  2359. and
  2360. .PN BadWindow
  2361. errors.
  2362. .sp
  2363. .LP
  2364. To read a window's WM_PROTOCOLS property, use
  2365. .PN XGetWMProtocols .
  2366. .IN "XGetWMProtocols" "" "@DEF@"
  2367. .\" Start marker code here
  2368. .FD 0
  2369. Status XGetWMProtocols\^(\^\fIdisplay\fP, \fIw\fP, \fIprotocols_return\fP, \
  2370. \fIcount_return\fP\^)
  2371. .br
  2372.       Display *\fIdisplay\fP\^;
  2373. .br
  2374.       Window \fIw\fP\^;
  2375. .br
  2376.       Atom **\fIprotocols_return\fP\^;
  2377. .br
  2378.       int *\fIcount_return\fP\^;
  2379. .FN
  2380. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  2381. .IP \fIdisplay\fP 1i
  2382. Specifies the connection to the X server.
  2383. .\" $Header: w.a,v 1.2 88/05/07 11:35:31 mento Exp $
  2384. .IP \fIw\fP 1i
  2385. Specifies the window.
  2386. .IP \fIprotocols_return\fP 1i
  2387. Returns the list of protocols.
  2388. .ds Cn protocols in the list
  2389. .IP \fIcount_return\fP 1i
  2390. Returns the number of \*(Cn.
  2391. .\" End marker code here
  2392. .LP
  2393. The 
  2394. .PN XGetWMProtocols 
  2395. function returns the list of atoms stored in the WM_PROTOCOLS property 
  2396. on the specified window.
  2397. These atoms describe window manager protocols in which the owner 
  2398. of this window is willing to participate.
  2399. If the property exists, is of type ATOM, is of format 32, 
  2400. and the atom WM_PROTOCOLS can be interned, 
  2401. .PN XGetWMProtocols
  2402. sets the protocols_return argument to a list of atoms, 
  2403. sets the count_return argument to the number of elements in the list, 
  2404. and returns a nonzero status.
  2405. Otherwise, it sets neither of the return arguments
  2406. and returns a zero status.
  2407. To release the list of atoms, use
  2408. .PN XFree .
  2409. .LP
  2410. .PN XGetWMProtocols
  2411. can generate a
  2412. .PN BadWindow
  2413. error.
  2414. .NH 3
  2415. Setting and Reading the WM_COLORMAP_WINDOWS Property
  2416. .XS
  2417. \*(SN Setting and Reading the WM_COLORMAP_WINDOWS Property
  2418. .XE
  2419. .LP
  2420. Xlib provides functions that you can use to set and read
  2421. the WM_COLORMAP_WINDOWS property for a given window.
  2422. .sp
  2423. .LP
  2424. To set a window's WM_COLORMAP_WINDOWS property, use
  2425. .PN XSetWMColormapWindows .
  2426. .IN "XSetWMColormapWindows" "" "@DEF@"
  2427. .\" Start marker code here
  2428. .FD 0
  2429. Status XSetWMColormapWindows\^(\^\fIdisplay\fP, \fIw\fP, \
  2430. \fIcolormap_windows\fP, \fIcount\fP\^)
  2431. .br
  2432.       Display *\fIdisplay\fP\^;
  2433. .br
  2434.       Window \fIw\fP\^;
  2435. .br
  2436.       Window *\fIcolormap_windows\fP\^;
  2437. .br
  2438.       int \fIcount\fP\^;
  2439. .FN
  2440. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  2441. .IP \fIdisplay\fP 1i
  2442. Specifies the connection to the X server.
  2443. .\" $Header: w.a,v 1.2 88/05/07 11:35:31 mento Exp $
  2444. .IP \fIw\fP 1i
  2445. Specifies the window.
  2446. .IP \fIcolormap_windows\fP 1i
  2447. Specifies the list of windows.
  2448. .ds Cn windows in the list
  2449. .IP \fIcount\fP 1i
  2450. Specifies the number of \*(Cn.
  2451. .\" End marker code here
  2452. .LP
  2453. The 
  2454. .PN XSetWMColormapWindows 
  2455. function replaces the WM_COLORMAP_WINDOWS property on the specified
  2456. window with the list of windows specified by the colormap_windows argument.
  2457. It the property does not already exist,
  2458. .PN XSetWMColormapWindows
  2459. sets the WM_COLORMAP_WINDOWS property on the specified
  2460. window to the list of windows specified by the colormap_windows argument.
  2461. The property is stored with a type of WINDOW and a format of 32.
  2462. If it cannot intern the WM_COLORMAP_WINDOWS atom,
  2463. .PN XSetWMColormapWindows
  2464. returns a zero status.
  2465. Otherwise, it returns a nonzero status.
  2466. .LP
  2467. .PN XSetWMColormapWindows
  2468. can generate
  2469. .PN BadAlloc
  2470. and
  2471. .PN BadWindow
  2472. errors.
  2473. .sp
  2474. .LP
  2475. To read a window's WM_COLORMAP_WINDOWS property, use
  2476. .PN XGetWMColormapWindows .
  2477. .IN "XGetWMColormapWindows" "" "@DEF@"
  2478. .\" Start marker code here
  2479. .FD 0
  2480. Status XGetWMColormapWindows\^(\^\fIdisplay\fP, \fIw\fP, \
  2481. \fIcolormap_windows_return\fP, \fIcount_return\fP\^)
  2482. .br
  2483.       Display *\fIdisplay\fP\^;
  2484. .br
  2485.       Window \fIw\fP\^;
  2486. .br
  2487.       Window **\fIcolormap_windows_return\fP\^;
  2488. .br
  2489.       int *\fIcount_return\fP\^;
  2490. .FN
  2491. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  2492. .IP \fIdisplay\fP 1i
  2493. Specifies the connection to the X server.
  2494. .\" $Header: w.a,v 1.2 88/05/07 11:35:31 mento Exp $
  2495. .IP \fIw\fP 1i
  2496. Specifies the window.
  2497. .IP \fIcolormap_windows_return\fP 1i
  2498. Returns the list of windows.
  2499. .ds Cn windows in the list
  2500. .IP \fIcount_return\fP 1i
  2501. Returns the number of \*(Cn.
  2502. .\" End marker code here
  2503. .LP
  2504. The 
  2505. .PN XGetWMColormapWindows 
  2506. function returns the list of window identifiers stored 
  2507. in the WM_COLORMAP_WINDOWS property on the specified window.
  2508. These identifiers indicate the colormaps that the window manager
  2509. may need to install for this window.
  2510. If the property exists, is of type WINDOW, is of format 32, 
  2511. and the atom WM_COLORMAP_WINDOWS can be interned, 
  2512. .PN XGetWMColormapWindows
  2513. sets the windows_return argument to a list of window identifiers, 
  2514. sets the count_return argument to the number of elements in the list, 
  2515. and returns a nonzero status.
  2516. Otherwise, it sets neither of the return arguments
  2517. and returns a zero status.
  2518. To release the list of window identifiers, use
  2519. .PN XFree . 
  2520. .LP
  2521. .PN XGetWMColormapWindows
  2522. can generate a
  2523. .PN BadWindow
  2524. error.
  2525. .NH 3
  2526. Setting and Reading the WM_ICON_SIZE Property
  2527. .XS
  2528. \*(SN Setting and Reading the WM_ICON_SIZE Property
  2529. .XE
  2530. .LP
  2531. Xlib provides functions that you can use to set and read 
  2532. the WM_ICON_SIZE property for a given window.
  2533. These functions use the 
  2534. .PN XIconSize 
  2535. .IN "XIconSize"
  2536. structure, which is defined in the
  2537. .Pn < X11/Xutil.h >
  2538. header file.
  2539. .sp
  2540. .LP
  2541. To allocate an
  2542. .PN XIconSize
  2543. structure, use
  2544. .PN XAllocIconSize .
  2545. .IN "XAllocIconSize" "" "@DEF@"
  2546. .\" Start marker code here
  2547. .FD 0
  2548. XIconSize *XAllocIconSize\^(\|)
  2549. .FN
  2550. .\" End marker code here
  2551. .LP
  2552. The
  2553. .PN XAllocIconSize 
  2554. function allocates and returns a pointer to a
  2555. .PN XIconSize 
  2556. structure.
  2557. Note that all fields in the
  2558. .PN XIconSize
  2559. structure are initially set to zero.
  2560. If insufficient memory is available, 
  2561. .PN XAllocIconSize
  2562. returns NULL.
  2563. To free the memory allocated to this structure,
  2564. use
  2565. .PN XFree .
  2566. .LP
  2567. The
  2568. .PN XIconSize
  2569. structure contains:
  2570. .LP
  2571. .\" Start marker code here
  2572. .IN "XIconSize" "" "@DEF@"
  2573. .Ds 0
  2574. .TA .5i 2.5i
  2575. .ta .5i 2.5i
  2576. typedef struct {
  2577.     int min_width, min_height;
  2578.     int max_width, max_height;
  2579.     int width_inc, height_inc;
  2580. } XIconSize;
  2581. .De
  2582. .\" End marker code here
  2583. .LP
  2584. The width_inc and height_inc members define an arithmetic progression of
  2585. sizes (minimum to maximum) that represent the supported icon sizes.
  2586. .LP
  2587. .sp
  2588. To set a window's WM_ICON_SIZE property, use
  2589. .PN XSetIconSizes .
  2590. .IN "XSetIconSizes" "" "@DEF@"
  2591. .\" Start marker code here
  2592. .FD 0
  2593. XSetIconSizes\^(\^\fIdisplay\fP, \fIw\fP, \fIsize_list\fP, \fIcount\fP\^)
  2594. .br
  2595.       Display *\fIdisplay\fP\^;
  2596. .br
  2597.       Window \fIw\fP\^;
  2598. .br
  2599.       XIconSize *\fIsize_list\fP\^;
  2600. .br
  2601.       int \fIcount\fP\^;
  2602. .FN
  2603. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  2604. .IP \fIdisplay\fP 1i
  2605. Specifies the connection to the X server.
  2606. .\" $Header: w.a,v 1.2 88/05/07 11:35:31 mento Exp $
  2607. .IP \fIw\fP 1i
  2608. Specifies the window.
  2609. .IP \fIsize_list\fP 1i
  2610. Specifies the size list.
  2611. .IP \fIcount\fP 1i
  2612. Specifies the number of items in the size list.
  2613. .\" End marker code here
  2614. .LP
  2615. .\" $Header: XSetISizes.d,v 1.2 88/06/11 07:53:16 mento Exp $
  2616. The
  2617. .PN XSetIconSizes
  2618. function is used only by window managers to set the supported icon sizes.
  2619. .LP
  2620. .PN XSetIconSizes
  2621. can generate
  2622. .PN BadAlloc
  2623. and
  2624. .PN BadWindow 
  2625. errors.
  2626. .LP
  2627. .sp
  2628. To read a window's WM_ICON_SIZE property, use
  2629. .PN XGetIconSizes .
  2630. .IN "XGetIconSizes" "" "@DEF@"
  2631. .\" Start marker code here
  2632. .FD 0
  2633. Status XGetIconSizes\^(\^\fIdisplay\fP, \fIw\fP, \fIsize_list_return\fP, \fIcount_return\fP\^)
  2634. .br
  2635.       Display *\fIdisplay\fP\^;
  2636. .br
  2637.       Window \fIw\fP\^;
  2638. .br
  2639.       XIconSize **\fIsize_list_return\fP\^;
  2640. .br
  2641.       int *\fIcount_return\fP\^;
  2642. .FN
  2643. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  2644. .IP \fIdisplay\fP 1i
  2645. Specifies the connection to the X server.
  2646. .\" $Header: w.a,v 1.2 88/05/07 11:35:31 mento Exp $
  2647. .IP \fIw\fP 1i
  2648. Specifies the window.
  2649. .IP \fIsize_list_return\fP 1i
  2650. Returns the size list.
  2651. .IP \fIcount_return\fP 1i
  2652. Returns the number of items in the size list.
  2653. .\" End marker code here
  2654. .LP
  2655. .\" $Header: XGetISizes.d,v 1.2 88/06/11 07:51:07 mento Exp $
  2656. The
  2657. .PN XGetIconSizes
  2658. function returns zero if a window manager has not set icon sizes;
  2659. otherwise, it return nonzero.
  2660. .PN XGetIconSizes
  2661. should be called by an application that
  2662. wants to find out what icon sizes would be most appreciated by the
  2663. window manager under which the application is running.
  2664. The application
  2665. should then use
  2666. .PN XSetWMHints
  2667. to supply the window manager with an icon pixmap or window in one of the
  2668. supported sizes.
  2669. To free the data allocated in size_list_return, use
  2670. .PN XFree .
  2671. .LP
  2672. .PN XGetIconSizes
  2673. can generate a
  2674. .PN BadWindow 
  2675. error.
  2676. .NH 3
  2677. Using Window Manager Convenience Functions
  2678. .XS
  2679. \*(SN Using Window Manager Convenience Functions
  2680. .XE
  2681. .LP
  2682. The 
  2683. .PN XmbSetWMProperties
  2684. function stores the standard set of window manager properties,
  2685. with text properties in standard encodings
  2686. for internationalized text communication.
  2687. The standard window manager properties for a given window are
  2688. WM_NAME, WM_ICON_NAME, WM_HINTS, WM_NORMAL_HINTS, WM_CLASS,
  2689. WM_COMMAND, WM_CLIENT_MACHINE, and WM_LOCALE_NAME.
  2690. .IN "XmbSetWMProperties" "" "@DEF@"
  2691. .\" Start marker code here
  2692. .FD 0
  2693. void XmbSetWMProperties\^(\^\fIdisplay\fP\^, \fIw\fP\^, \fIwindow_name\fP\^, \fIicon_name\fP\^, \fIargv\fP\^, \fIargc\fP\^,
  2694. .br
  2695.                       \fInormal_hints\fP\^, \fIwm_hints\fP\^, \fIclass_hints\fP\^)
  2696. .br
  2697.       Display *\fIdisplay\fP\^;
  2698. .br
  2699.       Window \fIw\fP\^;
  2700. .br
  2701.       char *\fIwindow_name\fP\^;
  2702. .br
  2703.       char *\fIicon_name\fP\^;
  2704. .br
  2705.       char *\fIargv\fP\^[];
  2706. .br
  2707.       int \fIargc\fP\^;
  2708. .br
  2709.       XSizeHints *\fInormal_hints\fP\^;
  2710. .br
  2711.       XWMHints *\fIwm_hints\fP\^;
  2712. .br
  2713.       XClassHint *\fIclass_hints\fP\^;
  2714. .FN
  2715. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  2716. .IP \fIdisplay\fP 1i
  2717. Specifies the connection to the X server.
  2718. .\" $Header: w.a,v 1.2 88/05/07 11:35:31 mento Exp $
  2719. .IP \fIw\fP 1i
  2720. Specifies the window.
  2721. .\" $Header: window_name.a,v 1.2 88/05/18 05:22:36 mento Exp $
  2722. .IP \fIwindow_name\fP 1i
  2723. Specifies the window name,
  2724. which should be a null-terminated string.
  2725. .\" $Header: icon_name.a,v 1.2 88/05/17 11:22:33 mento Exp $
  2726. .IP \fIicon_name\fP 1i
  2727. Specifies the icon name,
  2728. which should be a null-terminated string.
  2729. .IP \fIargv\fP 1i
  2730. Specifies the application's argument list.
  2731. .IP \fIargc\fP 1i
  2732. Specifies the number of arguments.
  2733. .IP \fIhints\fP 1i
  2734. Specifies the size hints for the window in its normal state.
  2735. .IP \fIwm_hints\fP 1i
  2736. Specifies the
  2737. .PN XWMHints
  2738. structure to be used.
  2739. .IP \fIclass_hints\fP 1i
  2740. Specifies the
  2741. .PN XClassHint
  2742. structure to be used.
  2743. .\" End marker code here
  2744. .LP
  2745. The
  2746. .PN XmbSetWMProperties
  2747. convenience function provides a simple programming interface 
  2748. for setting those essential window properties that are used 
  2749. for communicating with other clients
  2750. (particularly window and session managers).
  2751. .LP
  2752. If the window_name argument is non-NULL,
  2753. .PN XmbSetWMProperties
  2754. sets the WM_NAME property.
  2755. If the icon_name argument is non-NULL,
  2756. .PN XmbSetWMProperties
  2757. sets the WM_ICON_NAME property.
  2758. The window_name and icon_name arguments are null-terminated strings
  2759. in the encoding of the current locale.
  2760. If the arguments can be fully converted to the STRING encoding,
  2761. the properties are created with type ``STRING'': 
  2762. otherwise, the arguments are converted to Compound Text, 
  2763. and the properties are created with type ``COMPOUND_TEXT''.
  2764. .LP
  2765. If the normal_hints argument is non-NULL,
  2766. .PN XmbSetWMProperties
  2767. calls
  2768. .PN XSetWMNormalHints ,
  2769. which sets the WM_NORMAL_HINTS property (see section 14.1.7).
  2770. If the wm_hints argument is non-NULL, 
  2771. .PN XmbSetWMProperties
  2772. calls
  2773. .PN XSetWMHints ,
  2774. which sets the WM_HINTS property (see section 14.1.6).
  2775. .LP
  2776. If the argv argument is non-NULL,
  2777. .PN XmbSetWMProperties
  2778. sets the WM_COMMAND property from argv and argc.
  2779. Note that an argc of 0 indicates a zero-length command.
  2780. .LP
  2781. The hostname of this machine is stored using 
  2782. .PN XSetWMClientMachine 
  2783. (see section 14.2.2).
  2784. .LP
  2785. If the class_hints argument is non-NULL,
  2786. .PN XmbSetWMProperties
  2787. sets the WM_CLASS property.
  2788. If the res_name member in the 
  2789. .PN XClassHint
  2790. structure is set to the NULL pointer and the RESOURCE_NAME
  2791. environment variable is set,
  2792. the value of the environment variable is substituted for res_name.
  2793. If the res_name member is NULL,
  2794. the environment variable is not set, and argv and argv[0] are set,
  2795. then the value of argv[0], stripped of any directory prefixes,
  2796. is substituted for res_name.
  2797. .LP
  2798. It is assumed that the supplied class_hints.res_name and argv,
  2799. the RESOURCE_NAME environment variable, and the hostname of this machine
  2800. are in the encoding of the locale announced for the LC_CTYPE category.
  2801. (On POSIX-compliant systems, the LC_CTYPE, else LANG environment variable).
  2802. The corresponding WM_CLASS, WM_COMMAND, and WM_CLIENT_MACHINE properties
  2803. are typed according to the local host locale announcer.
  2804. No encoding conversion is performed prior to storage in the properties.
  2805. .LP
  2806. For clients that need to process the property text in a locale,
  2807. .PN XmbSetWMProperties
  2808. sets the WM_LOCALE_NAME property to be the name of the current locale.
  2809. The name is assumed to be in the Host Portable Character Encoding,
  2810. and is converted to STRING for storage in the property.
  2811. .LP
  2812. .PN XmbSetWMProperties
  2813. can generate
  2814. .PN BadAlloc
  2815. and
  2816. .PN BadWindow
  2817. errors.
  2818. .sp
  2819. .LP
  2820. To set a window's standard window manager properties
  2821. with strings in the STRING encoding, use
  2822. .PN XSetWMProperties .
  2823. The standard window manager properties for a given window are
  2824. WM_NAME, WM_ICON_NAME, WM_HINTS, WM_NORMAL_HINTS, WM_CLASS,
  2825. WM_COMMAND, and WM_CLIENT_MACHINE.
  2826. .IN "XSetWMProperties" "" "@DEF@"
  2827. .\" Start marker code here
  2828. .FD 0
  2829. void XSetWMProperties\^(\^\fIdisplay\fP, \fIw\fP, \fIwindow_name\fP, \
  2830. \fIicon_name\fP, \fIargv\fP, \fIargc\fP, \fInormal_hints\fP, \fIwm_hints\fP, \
  2831. \fIclass_hints\fP\^)
  2832. .br
  2833.       Display *\fIdisplay\fP\^; 
  2834. .br
  2835.       Window \fIw\fP\^;
  2836. .br
  2837.       XTextProperty *\fIwindow_name\fP\^;
  2838. .br
  2839.       XTextProperty *\fIicon_name\fP\^;
  2840. .br
  2841.       char **\fIargv\fP\^;
  2842. .br
  2843.       int \fIargc\fP\^;
  2844. .br
  2845.       XSizeHints *\fInormal_hints\fP\^;
  2846. .br
  2847.       XWMHints *\fIwm_hints\fP\^;
  2848. .br
  2849.       XClassHint *\fIclass_hints\fP\^;
  2850. .FN
  2851. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  2852. .IP \fIdisplay\fP 1i
  2853. Specifies the connection to the X server.
  2854. .\" $Header: w.a,v 1.2 88/05/07 11:35:31 mento Exp $
  2855. .IP \fIw\fP 1i
  2856. Specifies the window.
  2857. .\" $Header: window_name.a,v 1.2 88/05/18 05:22:36 mento Exp $
  2858. .IP \fIwindow_name\fP 1i
  2859. Specifies the window name,
  2860. which should be a null-terminated string.
  2861. .\" $Header: icon_name.a,v 1.2 88/05/17 11:22:33 mento Exp $
  2862. .IP \fIicon_name\fP 1i
  2863. Specifies the icon name,
  2864. which should be a null-terminated string.
  2865. .IP \fIargv\fP 1i
  2866. Specifies the application's argument list.
  2867. .IP \fIargc\fP 1i
  2868. Specifies the number of arguments.
  2869. .IP \fInormal_hints\fP 1i
  2870. Specifies the size hints for the window in its normal state.
  2871. .IP \fIwm_hints\fP 1i
  2872. Specifies the
  2873. .PN XWMHints
  2874. structure to be used.
  2875. .IP \fIclass_hints\fP 1i
  2876. Specifies the
  2877. .PN XClassHint
  2878. structure to be used.
  2879. .\" End marker code here
  2880. .LP
  2881. The 
  2882. .PN XSetWMProperties 
  2883. convenience function provides a single programming interface 
  2884. for setting those essential window properties that are used 
  2885. for communicating with other clients (particularly window and session
  2886. managers).
  2887. .LP
  2888. If the window_name argument is non-NULL, 
  2889. .PN XSetWMProperties
  2890. calls
  2891. .PN XSetWMName ,
  2892. which in turn, sets the WM_NAME property (see section 14.1.4).
  2893. If the icon_name argument is non-NULL,
  2894. .PN XSetWMProperties
  2895. calls
  2896. .PN XSetWMIconName ,
  2897. which sets the WM_ICON_NAME property (see section 14.1.5).
  2898. If the argv argument is non-NULL, 
  2899. .PN XSetWMProperties
  2900. calls
  2901. .PN XSetCommand ,
  2902. which sets the WM_COMMAND property (see section 14.2.1).
  2903. Note that an argc of zero is allowed to indicate a zero-length command.
  2904. Note also that the hostname of this machine is stored using
  2905. .PN XSetWMClientMachine 
  2906. (see section 14.2.2).
  2907. .LP
  2908. If the normal_hints argument is non-NULL, 
  2909. .PN XSetWMProperties
  2910. calls
  2911. .PN XSetWMNormalHints ,
  2912. which sets the WM_NORMAL_HINTS property (see section 14.1.7).
  2913. If the wm_hints argument is non-NULL, 
  2914. .PN XSetWMProperties
  2915. calls
  2916. .PN XSetWMHints ,
  2917. which sets the WM_HINTS property (see section 14.1.6).
  2918. .LP
  2919. If the class_hints argument is non-NULL, 
  2920. .PN XSetWMProperties
  2921. calls
  2922. .PN XSetClassHint ,
  2923. which sets the WM_CLASS property (see section 14.1.8).
  2924. If the res_name member in the
  2925. .PN XClassHint
  2926. structure is set to the NULL pointer and the RESOURCE_NAME environment 
  2927. variable is set, 
  2928. then the value of the environment variable is substituted for res_name.
  2929. If the res_name member is NULL, 
  2930. the environment variable is not set, 
  2931. and argv and argv[0] are set, 
  2932. then the value of argv[0], stripped of
  2933. any directory prefixes, is substituted for res_name.
  2934. .LP
  2935. .PN XSetWMProperties
  2936. can generate
  2937. .PN BadAlloc
  2938. and
  2939. .PN BadWindow
  2940. errors.
  2941. .NH 2
  2942. Client to Session Manager Communication
  2943. .XS
  2944. \*(SN Client to Session Manager Communication
  2945. .XE
  2946. .LP
  2947. This section discusses how to:
  2948. .IP \(bu 5
  2949. Set and read the WM_COMMAND property
  2950. .IP \(bu 5
  2951. Set and read the WM_CLIENT_MACHINE property
  2952. .NH 3
  2953. Setting and Reading the WM_COMMAND Property
  2954. .XS
  2955. \*(SN Setting and Reading the WM_COMMAND Property
  2956. .XE
  2957. .LP
  2958. Xlib provides functions that you can use to set and read
  2959. the WM_COMMAND property for a given window.
  2960. .sp
  2961. .LP
  2962. To set a window's WM_COMMAND property, use
  2963. .PN XSetCommand .
  2964. .IN "XSetCommand" "" "@DEF@"
  2965. .\" Start marker code here
  2966. .FD 0
  2967. XSetCommand\^(\^\fIdisplay\fP, \fIw\fP, \fIargv\fP, \fIargc\fP\^)
  2968. .br
  2969.       Display *\fIdisplay\fP\^;
  2970. .br
  2971.       Window \fIw\fP\^;
  2972. .br
  2973.       char **\fIargv\fP\^;
  2974. .br
  2975.       int \fIargc\fP\^;
  2976. .FN
  2977. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  2978. .IP \fIdisplay\fP 1i
  2979. Specifies the connection to the X server.
  2980. .\" $Header: w.a,v 1.2 88/05/07 11:35:31 mento Exp $
  2981. .IP \fIw\fP 1i
  2982. Specifies the window.
  2983. .IP \fIargv\fP 1i
  2984. Specifies the application's argument list.
  2985. .IP \fIargc\fP 1i
  2986. Specifies the number of arguments.
  2987. .\" End marker code here
  2988. .LP
  2989. .\" $Header: XSetCmd.d,v 1.3 88/06/11 07:53:04 mento Exp $
  2990. The
  2991. .PN XSetCommand
  2992. function sets the command and arguments used to invoke the
  2993. application.
  2994. (Typically, argv is the argv array of your main program.)
  2995. If the strings are not in the Host Portable Character Encoding
  2996. the result is implementation dependent.
  2997. .LP
  2998. .PN XSetCommand
  2999. can generate
  3000. .PN BadAlloc
  3001. and
  3002. .PN BadWindow 
  3003. errors.
  3004. .sp
  3005. .LP
  3006. To read a window's WM_COMMAND property, use
  3007. .PN XGetCommand .
  3008. .IN "XGetCommand" "" "@DEF@"
  3009. .\" Start marker code here
  3010. .FD 0
  3011. Status XGetCommand\^(\^\fIdisplay\fP, \fIw\fP, \fIargv_return\fP, \
  3012. \fIargc_return\fP\^)
  3013. .br
  3014.       Display *\fIdisplay\fP\^;
  3015. .br
  3016.       Window \fIw\fP\^;
  3017. .br
  3018.       char ***\fIargv_return\fP\^;
  3019. .br
  3020.       int *\fIargc_return\fP\^;
  3021. .FN
  3022. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  3023. .IP \fIdisplay\fP 1i
  3024. Specifies the connection to the X server.
  3025. .\" $Header: w.a,v 1.2 88/05/07 11:35:31 mento Exp $
  3026. .IP \fIw\fP 1i
  3027. Specifies the window.
  3028. .IP \fIargv_return\fP 1i
  3029. Returns the application's argument list.
  3030. .IP \fIargc_return\fP 1i
  3031. Returns the number of arguments returned.
  3032. .\" End marker code here
  3033. .LP
  3034. The 
  3035. .PN XGetCommand 
  3036. function reads the WM_COMMAND property from the specified window 
  3037. and returns a string list.
  3038. If the WM_COMMAND property exists, 
  3039. it is of type STRING and format 8.
  3040. If sufficient memory can be allocated to contain the string list, 
  3041. .PN XGetCommand
  3042. fills in the argv_return and argc_return arguments
  3043. and returns a nonzero status.
  3044. Otherwise, it returns a zero status.
  3045. If the data returned by the server is in the Latin Portable Character Encoding,
  3046. then the returned strings are in the Host Portable Character Encoding.
  3047. Otherwise, the result is implementation dependent.
  3048. To free the memory allocated to the string list, use
  3049. .PN XFreeStringList .
  3050. .NH 3
  3051. Setting and Reading the WM_CLIENT_MACHINE Property
  3052. .XS
  3053. \*(SN Setting and Reading the WM_CLIENT_MACHINE Property
  3054. .XE
  3055. .LP
  3056. Xlib provides functions that you can use to set and read 
  3057. the WM_CLIENT_MACHINE property for a given window.
  3058. .sp
  3059. .LP
  3060. To set a window's WM_CLIENT_MACHINE property, use
  3061. .PN XSetWMClientMachine .
  3062. .IN "XSetWMClientMachine" "" "@DEF@"
  3063. .\" Start marker code here
  3064. .FD 0
  3065. void XSetWMClientMachine\^(\^\fIdisplay\fP, \fIw\fP, \fItext_prop\fP\^)
  3066. .br
  3067.       Display *\fIdisplay\fP\^;
  3068. .br
  3069.       Window \fIw\fP\^;
  3070. .br
  3071.       XTextProperty *\fItext_prop\fP\^;
  3072. .FN
  3073. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  3074. .IP \fIdisplay\fP 1i
  3075. Specifies the connection to the X server.
  3076. .\" $Header: w.a,v 1.2 88/05/07 11:35:31 mento Exp $
  3077. .IP \fIw\fP 1i
  3078. Specifies the window.
  3079. .IP \fItext_prop\fP 1i
  3080. Specifies the
  3081. .PN XTextProperty
  3082. structure to be used.
  3083. .\" End marker code here
  3084. .LP
  3085. The
  3086. .PN XSetWMClientMachine
  3087. convenience function calls
  3088. .PN XSetTextProperty
  3089. to set the WM_CLIENT_MACHINE property.
  3090. .sp
  3091. .LP
  3092. To read a window's WM_CLIENT_MACHINE property, use
  3093. .PN XGetWMClientMachine .
  3094. .IN "XGetWMClientMachine" "" "@DEF@"
  3095. .\" Start marker code here
  3096. .FD 0
  3097. Status XGetWMClientMachine\^(\^\fIdisplay\fP, \fIw\fP, \fItext_prop_return\fP\^)
  3098. .br
  3099.       Display *\fIdisplay\fP\^;
  3100. .br
  3101.       Window \fIw\fP\^;
  3102. .br
  3103.       XTextProperty *\fItext_prop_return\fP\^;
  3104. .FN
  3105. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  3106. .IP \fIdisplay\fP 1i
  3107. Specifies the connection to the X server.
  3108. .\" $Header: w.a,v 1.2 88/05/07 11:35:31 mento Exp $
  3109. .IP \fIw\fP 1i
  3110. Specifies the window.
  3111. .IP \fItext_prop_return\fP 1i
  3112. Returns the
  3113. .PN XTextProperty
  3114. structure.
  3115. .\" End marker code here
  3116. .LP
  3117. The
  3118. .PN XGetWMClientMachine
  3119. convenience function performs an 
  3120. .PN XGetTextProperty 
  3121. on the WM_CLIENT_MACHINE property.
  3122. It returns nonzero status on success; otherwise it returns a zero status.
  3123. .NH 2
  3124. Standard Colormaps
  3125. .XS
  3126. \*(SN Standard Colormaps 
  3127. .XE
  3128. .LP
  3129. Applications with color palettes, smooth-shaded drawings, or digitized
  3130. images demand large numbers of colors.  
  3131. In addition, these applications often require an efficient mapping 
  3132. from color triples to pixel values that display the appropriate colors.
  3133. .LP
  3134. As an example, consider a three-dimensional display program that wants 
  3135. to draw a smoothly shaded sphere.  
  3136. At each pixel in the image of the sphere, 
  3137. the program computes the intensity and color of light
  3138. reflected back to the viewer.  
  3139. The result of each computation is a triple of RGB
  3140. coefficients in the range 0.0 to 1.0.  
  3141. To draw the sphere, the program needs a colormap that provides a
  3142. large range of uniformly distributed colors.  
  3143. The colormap should be arranged so that the program can
  3144. convert its RGB triples into pixel values very quickly,
  3145. because drawing the entire sphere requires many such
  3146. conversions.
  3147. .LP
  3148. On many current workstations,
  3149. the display is limited to 256 or fewer colors.  
  3150. Applications must allocate colors carefully, 
  3151. not only to make sure they cover the entire range they need 
  3152. but also to make use of as many of the available colors as possible.
  3153. On a typical X display, 
  3154. many applications are active at once.
  3155. Most workstations have only one hardware look-up table for colors,
  3156. so only one application colormap can be installed at a given time.
  3157. The application using the installed colormap is displayed correctly, 
  3158. and the other applications ``go technicolor'' and are
  3159. displayed with false colors.
  3160. .LP
  3161. As another example, consider a user who is running an 
  3162. image processing program to display earth-resources data.  
  3163. The image processing program needs a colormap set up with 8 reds, 
  3164. 8 greens, and 4 blues, for a total of 256 colors.
  3165. Because some colors are already in use in the default colormap, 
  3166. the image processing program allocates and installs a new colormap.
  3167. .LP
  3168. The user decides to alter some of the colors in the image
  3169. by invoking a color palette program to mix and choose colors.
  3170. The color palette program also needs a
  3171. colormap with eight reds, eight greens, and four blues, so just like
  3172. the image processing program, it must allocate and
  3173. install a new colormap.
  3174. .LP
  3175. Because only one colormap can be installed at a time,
  3176. the color palette may be displayed incorrectly
  3177. whenever the image processing program is active.
  3178. Conversely, whenever the palette program is active, 
  3179. the image may be displayed incorrectly.  
  3180. The user can never match or compare colors in the palette and image.
  3181. Contention for colormap resources can be reduced if applications
  3182. with similar color needs share colormaps.
  3183. .LP
  3184. The image processing program and the color palette program 
  3185. could share the same colormap if there existed a convention that described
  3186. how the colormap was set up.  
  3187. Whenever either program was active, 
  3188. both would be displayed correctly.
  3189. .LP
  3190. The standard colormap properties define a set of commonly used
  3191. colormaps.  
  3192. Applications that share these colormaps and conventions display 
  3193. true colors more often and provide a better interface to the user.
  3194. .LP
  3195. Standard colormaps allow applications to share commonly used color
  3196. resources.  
  3197. This allows many applications to be displayed in true colors
  3198. simultaneously, even when each application needs an entirely filled
  3199. colormap.
  3200. .LP
  3201. Several standard colormaps are described in this section.
  3202. Usually, a window manager creates these colormaps.
  3203. Applications should use the standard colormaps if they already exist.
  3204. .sp
  3205. .LP
  3206. To allocate an
  3207. .PN XStandardColormap
  3208. structure, use
  3209. .PN XAllocStandardColormap .
  3210. .IN "XAllocStandardColormap" "" "@DEF@"
  3211. .\" Start marker code here
  3212. .FD 0
  3213. XStandardColormap *XAllocStandardColormap\^(\|)
  3214. .FN
  3215. .\" End marker code here
  3216. .LP
  3217. The
  3218. .PN XAllocStandardColormap
  3219. function allocates and returns a pointer to a
  3220. .PN XStandardColormap
  3221. structure.
  3222. Note that all fields in the
  3223. .PN XStandardColormap
  3224. structure are initially set to zero.
  3225. If insufficient memory is available, 
  3226. .PN XAllocStandardColormap
  3227. returns NULL.
  3228. To free the memory allocated to this structure,
  3229. use
  3230. .PN XFree .
  3231. .LP
  3232. The 
  3233. .PN XStandardColormap 
  3234. structure contains:
  3235. .LP
  3236. .\" Start marker code here
  3237. /* Hints */
  3238. .TS
  3239. lw(.5i) lw(2i) lw(1i).
  3240. T{
  3241. #define
  3242. T}    T{
  3243. .PN ReleaseByFreeingColormap
  3244. T}    T{
  3245. ( (XID) 1L)
  3246. T}
  3247. .TE
  3248. /* Values */
  3249. .IN "XStandardColormap" "" "@DEF@"
  3250. .Ds 0
  3251. .TA .5i 2.5i
  3252. .ta .5i 2.5i
  3253. typedef struct {
  3254.     Colormap colormap;
  3255.     unsigned long red_max;
  3256.     unsigned long red_mult;
  3257.     unsigned long green_max;
  3258.     unsigned long green_mult;
  3259.     unsigned long blue_max;
  3260.     unsigned long blue_mult;
  3261.     unsigned long base_pixel;
  3262.     VisualID visualid;
  3263.     XID killid;
  3264. } XStandardColormap;
  3265. .De
  3266. .\" End marker code here
  3267. .LP
  3268. The colormap member is the colormap created by the
  3269. .PN XCreateColormap
  3270. function.
  3271. The red_max, green_max, and blue_max members give the maximum
  3272. red, green, and blue values, respectively.  
  3273. Each color coefficient ranges from zero to its max, inclusive.  
  3274. For example,
  3275. a common colormap allocation is 3/3/2 (3 planes for red, 3
  3276. planes for green, and 2 planes for blue).  
  3277. This colormap would have red_max = 7, green_max = 7, 
  3278. and blue_max = 3.  
  3279. An alternate allocation that uses only 216 colors is red_max = 5, 
  3280. green_max = 5, and blue_max = 5.
  3281. .LP
  3282. The red_mult, green_mult, and blue_mult members give the
  3283. scale factors used to compose a full pixel value. 
  3284. (See the discussion of the base_pixel members for further information.)
  3285. For a 3/3/2 allocation, red_mult might be 32,
  3286. green_mult might be 4, and blue_mult might be 1.  
  3287. For a 6-colors-each allocation, red_mult might be 36, 
  3288. green_mult might be 6, and blue_mult might be 1.
  3289. .LP
  3290. The base_pixel member gives the base pixel value used to
  3291. compose a full pixel value.  
  3292. Usually, the base_pixel is obtained from a call to the 
  3293. .PN XAllocColorPlanes
  3294. function.  
  3295. Given integer red, green, and blue coefficients in their appropriate 
  3296. ranges, one then can compute a corresponding pixel value by
  3297. using the following expression:
  3298. .LP
  3299. .Ds
  3300. .TA .5i 1.5i
  3301. .ta .5i 1.5i
  3302. (r * red_mult + g * green_mult + b * blue_mult + base_pixel) & 0xFFFFFFFF
  3303. .De
  3304. .LP
  3305. For 
  3306. .PN GrayScale
  3307. colormaps, 
  3308. only the colormap, red_max, red_mult, 
  3309. and base_pixel members are defined. 
  3310. The other members are ignored.  
  3311. To compute a 
  3312. .PN GrayScale 
  3313. pixel value, use the following expression:
  3314. .LP
  3315. .Ds
  3316. .TA .5i 1.5i
  3317. .ta .5i 1.5i
  3318. (gray * red_mult + base_pixel) & 0xFFFFFFFF
  3319. .De
  3320. .LP
  3321. Negative multipliers can be represented by converting the 2's
  3322. complement representation of the multiplier into an unsigned long and
  3323. storing the result in the appropriate _mult field.
  3324. The step of masking by 0xFFFFFFFF effectively converts the resulting
  3325. positive multiplier into a negative one.
  3326. The masking step will take place automatically on many machine architectures,
  3327. depending on the size of the integer type used to do the computation,
  3328. .LP
  3329. The visualid member gives the ID number of the visual from which the
  3330. colormap was created.
  3331. The killid member gives a resource ID that indicates whether
  3332. the cells held by this standard colormap are to be released 
  3333. by freeing the colormap ID or by calling the
  3334. .PN XKillClient
  3335. function on the indicated resource.
  3336. (Note that this method is necessary for allocating out of an existing colormap.)
  3337. .LP
  3338. The properties containing the 
  3339. .PN XStandardColormap 
  3340. information have 
  3341. the type RGB_COLOR_MAP.
  3342. .LP
  3343. The remainder of this section discusses standard colormap properties and atoms
  3344. as well as how to manipulate standard colormaps.
  3345. .NH 3
  3346. Standard Colormap Properties and Atoms
  3347. .XS
  3348. \*(SN Standard Colormap Properties and Atoms 
  3349. .XE
  3350. .LP
  3351. .IN "Standard Colormaps"
  3352. .IN "colormaps" "standard"
  3353. Several standard colormaps are available.  
  3354. Each standard colormap is defined by a property, 
  3355. and each such property is identified by an atom.  
  3356. The following list names the atoms and describes the colormap
  3357. associated with each one.
  3358. The
  3359. .Pn < X11/Xatom.h >
  3360. header file contains the definitions for each of the following atoms,
  3361. which are prefixed with XA_.
  3362. .IP RGB_DEFAULT_MAP 5
  3363. This atom names a property.
  3364. The value of the property is an array of
  3365. .PN XStandardColormap
  3366. structures.
  3367. Each entry in the array describes an RGB subset of the default color
  3368. map for the Visual specified by visual_id.
  3369. .IP
  3370. Some applications only need a few RGB colors and
  3371. may be able to allocate them from the system default colormap.
  3372. This is the ideal situation because the fewer colormaps that are
  3373. active in the system the more applications are displayed
  3374. with correct colors at all times.
  3375. .IP
  3376. A typical allocation for the RGB_DEFAULT_MAP on 8-plane displays
  3377. is 6 reds, 6 greens, and 6 blues.  
  3378. This gives 216 uniformly distributed colors 
  3379. (6 intensities of 36 different hues) and still leaves 40 elements 
  3380. of a 256-element colormap available for special-purpose colors 
  3381. for text, borders, and so on.
  3382. .IP RGB_BEST_MAP 5
  3383. .br
  3384. This atom names a property.
  3385. The value of the property is an 
  3386. .PN XStandardColormap .
  3387. .IP 
  3388. The property defines the best RGB colormap available on
  3389. the screen.
  3390. (Of course, this is a subjective evaluation.)
  3391. Many image processing and three-dimensional applications need to
  3392. use all available colormap cells and to distribute as many
  3393. perceptually distinct colors as possible over those cells.
  3394. This implies that there may be more green values available than
  3395. red, as well as more green or red than blue.
  3396. .IP
  3397. For an 8-plane 
  3398. .PN PseudoColor 
  3399. visual, 
  3400. RGB_BEST_MAP is likely to be a 3/3/2 allocation.  
  3401. For a 24-plane 
  3402. .PN DirectColor 
  3403. visual, 
  3404. RGB_BEST_MAP is normally an 8/8/8 allocation.  
  3405. .IP RGB_RED_MAP 5
  3406. .br
  3407. .ns
  3408. .IP RGB_GREEN_MAP 5
  3409. .br
  3410. .ns
  3411. .IP RGB_BLUE_MAP 5
  3412. These atoms name properties.
  3413. The value of each property is an
  3414. .PN XStandardColormap . 
  3415. .IP
  3416. The properties define all-red, all-green, and all-blue
  3417. colormaps, respectively.  
  3418. These maps are used by applications that want to make color-separated 
  3419. images.  
  3420. For example, a user might generate a full-color image 
  3421. on an 8-plane display both by rendering an image three times 
  3422. (once with high color resolution in red, once with green, 
  3423. and once with blue) and by multiply-exposing a single frame in a camera.
  3424. .IP RGB_GRAY_MAP 5
  3425. This atom names a property.
  3426. The value of the property is an 
  3427. .PN XStandardColormap .
  3428. .IP
  3429. The property describes the best 
  3430. .PN GrayScale 
  3431. colormap available on the screen.  
  3432. As previously mentioned, 
  3433. only the colormap, red_max, red_mult, and base_pixel members of the
  3434. .PN XStandardColormap 
  3435. structure are used for 
  3436. .PN GrayScale 
  3437. colormaps.
  3438. .NH 3
  3439. Setting and Obtaining Standard Colormaps
  3440. .XS
  3441. \*(SN Setting and Obtaining Standard Colormaps
  3442. .XE
  3443. .LP
  3444. Xlib provides functions that you can use to set and obtain an
  3445. .PN XStandardColormap
  3446. structure.
  3447. .sp
  3448. .LP
  3449. To set an
  3450. .PN XStandardColormap
  3451. structure, use
  3452. .PN XSetRGBColormaps .
  3453. .IN "XSetRGBColormaps" "" "@DEF@"
  3454. .\" Start marker code here
  3455. .FD 0
  3456. void XSetRGBColormaps\^(\^\fIdisplay\fP, \fIw\fP, \fIstd_colormap\fP, \
  3457. \fIcount\fP, \fIproperty\fP\^)
  3458. .br
  3459.       Display *\fIdisplay\fP\^;
  3460. .br
  3461.       Window \fIw\fP\^;
  3462. .br
  3463.       XStandardColormap *\fIstd_colormap\fP\^;
  3464. .br
  3465.       int \fIcount\fP\^;
  3466. .br
  3467.       Atom \fIproperty\fP\^;
  3468. .FN
  3469. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  3470. .IP \fIdisplay\fP 1i
  3471. Specifies the connection to the X server.
  3472. .\" $Header: w.a,v 1.2 88/05/07 11:35:31 mento Exp $
  3473. .IP \fIw\fP 1i
  3474. Specifies the window.
  3475. .IP \fIstd_colormap\fP 1i
  3476. Specifies the
  3477. .PN XStandardColormap
  3478. structure to be used.
  3479. .ds Cn colormaps
  3480. .IP \fIcount\fP 1i
  3481. Specifies the number of \*(Cn.
  3482. .\" $Header: property.a,v 1.2 88/04/05 15:19:43 mento Exp $
  3483. .IP \fIproperty\fP 1i
  3484. Specifies the property name.
  3485. .\" End marker code here
  3486. .LP
  3487. The 
  3488. .PN XSetRGBColormaps 
  3489. function replaces the RGB colormap definition in the specified property 
  3490. on the named window.
  3491. If the property does not already exist,
  3492. .PN XSetRGBColormaps
  3493. sets the RGB colormap definition in the specified property
  3494. on the named window.
  3495. The property is stored with a type of RGB_COLOR_MAP and a format of 32.
  3496. Note that it is the caller's responsibility to honor the ICCCM
  3497. restriction that only RGB_DEFAULT_MAP contain more than one definition.
  3498. .LP
  3499. The
  3500. .PN XSetRGBColormaps
  3501. function usually is only used by window or session managers.
  3502. To create a standard colormap, 
  3503. follow this procedure:
  3504. .IP 1. 5
  3505. Open a new connection to the same server.
  3506. .IP 2. 5
  3507. Grab the server.
  3508. .IP 3. 5
  3509. See if the property is on the property list of the root window for the screen.
  3510. .IP 4. 5
  3511. If the desired property is not present:
  3512. .RS
  3513. .IP \(bu 5
  3514. Create a colormap (unless using the default colormap of the screen).
  3515. .IP \(bu 5
  3516. Determine the color characteristics of the visual.
  3517. .IP \(bu 5
  3518. Call 
  3519. .PN XAllocColorPlanes
  3520. or 
  3521. .PN XAllocColorCells
  3522. to allocate cells in the colormap.
  3523. .IP \(bu 5
  3524. Call 
  3525. .PN XStoreColors
  3526. to store appropriate color values in the colormap.
  3527. .IP \(bu 5
  3528. Fill in the descriptive members in the 
  3529. .PN XStandardColormap
  3530. structure.
  3531. .IP \(bu 5
  3532. Attach the property to the root window.
  3533. .IP \(bu 5
  3534. Use
  3535. .PN XSetCloseDownMode
  3536. to make the resource permanent.
  3537. .RE
  3538. .IP 5. 5
  3539. Ungrab the server.
  3540. .LP
  3541. .PN XSetRGBColormaps
  3542. can generate
  3543. .PN BadAlloc ,
  3544. .PN BadAtom ,
  3545. and
  3546. .PN BadWindow
  3547. errors.
  3548. .LP
  3549. To obtain the 
  3550. .PN XStandardColormap 
  3551. structure associated with the specified property, use
  3552. .PN XGetRGBColormaps .
  3553. .IN "XGetRGBColormaps" "" "@DEF@"
  3554. .\" Start marker code here
  3555. .FD 0
  3556. Status XGetRGBColormaps\^(\^\fIdisplay\fP, \fIw\fP, \fIstd_colormap_return\fP, \
  3557. \fIcount_return\fP, \fIproperty\fP\^)
  3558. .br
  3559.       Display *\fIdisplay\fP\^;
  3560. .br
  3561.       Window \fIw\fP\^;
  3562. .br
  3563.       XStandardColormap **\fIstd_colormap_return\fP\^;
  3564. .br
  3565.       int *\fIcount_return\fP\^;
  3566. .br
  3567.       Atom \fIproperty\fP\^;
  3568. .FN
  3569. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  3570. .IP \fIdisplay\fP 1i
  3571. Specifies the connection to the X server.
  3572. .\" $Header: w.a,v 1.2 88/05/07 11:35:31 mento Exp $
  3573. .IP \fIw\fP 1i
  3574. Specifies the window.
  3575. .IP \fIstd_colormap_return\fP 1i
  3576. Returns the
  3577. .PN XStandardColormap
  3578. structure.
  3579. .ds Cn colormaps
  3580. .IP \fIcount_return\fP 1i
  3581. Returns the number of \*(Cn.
  3582. .\" $Header: property.a,v 1.2 88/04/05 15:19:43 mento Exp $
  3583. .IP \fIproperty\fP 1i
  3584. Specifies the property name.
  3585. .\" End marker code here
  3586. .LP
  3587. The 
  3588. .PN XGetRGBColormaps
  3589. function returns the RGB colormap definitions stored 
  3590. in the specified property on the named window.
  3591. If the property exists, is of type RGB_COLOR_MAP, is of format 32, 
  3592. and is long enough to contain a colormap definition,
  3593. .PN XGetRGBColormaps
  3594. allocates and fills in space for the returned colormaps
  3595. and returns a nonzero status.
  3596. If the visualid is not present, 
  3597. .PN XGetRGBColormaps 
  3598. assumes the default visual for the screen on which the window is located; 
  3599. if the killid is not present, 
  3600. .PN None
  3601. is assumed, which indicates that the resources cannot be released.
  3602. Otherwise, 
  3603. none of the fields are set, and 
  3604. .PN XGetRGBColormaps
  3605. returns a zero status.
  3606. Note that it is the caller's responsibility to honor the ICCCM
  3607. restriction that only RGB_DEFAULT_MAP contain more than one definition.
  3608. .LP
  3609. .PN XGetRGBColormaps
  3610. can generate
  3611. .PN BadAtom
  3612. and
  3613. .PN BadWindow
  3614. errors.
  3615. .bp
  3616.