home *** CD-ROM | disk | FTP | other *** search
/ InfoMagic Source Code 1993 July / THE_SOURCE_CODE_CD_ROM.iso / X / mit / doc / Xlib / CH04 < prev    next >
Encoding:
Text File  |  1991-08-27  |  43.5 KB  |  1,519 lines
  1. \&
  2. .sp 1
  3. .ce 3
  4. \s+1\fBChapter 4\fP\s-1
  5.  
  6. \s+1\fBWindow Information Functions\fP\s-1
  7. .sp 2
  8. .nr H1 4
  9. .nr H2 0
  10. .nr H3 0
  11. .nr H4 0
  12. .nr H5 0
  13. .na
  14. .LP
  15. .XS
  16. Chapter 4: Window Information Functions 
  17. .XE
  18. After you connect the display to the X server and create a window,
  19. you can use the Xlib window information functions to:
  20. .IP \(bu 5
  21. Obtain information about a window
  22. .IP \(bu 5
  23. Translate screen coordinates
  24. .IP \(bu 5
  25. Manipulate property lists
  26. .IP \(bu 5
  27. Obtain and change window properties
  28. .IP \(bu 5
  29. Manipulate selections
  30. .NH 2
  31. Obtaining Window Information
  32. .XS
  33. \*(SN Obtaining Window Information 
  34. .XE
  35. .LP
  36. Xlib provides functions that you can use to obtain information about 
  37. the window tree, the window's current attributes, 
  38. the window's current geometry, or the current pointer coordinates.
  39. Because they are most frequently used by window managers,
  40. these functions all return a status to indicate whether the window still
  41. exists.
  42. .LP
  43. .sp
  44. To obtain the parent, a list of children, and number of children for 
  45. a given window, use 
  46. .PN XQueryTree .
  47. .IN "Child Window"
  48. .IN "Parent Window"
  49. .IN "XQueryTree" "" "@DEF@"
  50. .\" Start marker code here
  51. .FD 0
  52. .\" $Header: XQueryTree.f,v 1.1 88/02/26 10:02:19 mento Exp $
  53. Status XQueryTree\^(\^\fIdisplay\fP, \fIw\fP\^, \fIroot_return\fP\^, \fIparent_return\fP\^, \fIchildren_return\fP\^, \fInchildren_return\fP\^)
  54. .br
  55.       Display *\fIdisplay\fP\^;
  56. .br
  57.       Window \fIw\fP\^;
  58. .br
  59.       Window *\fIroot_return\fP\^;
  60. .br
  61.       Window *\fIparent_return\fP\^;
  62. .br
  63.       Window **\fIchildren_return\fP\^;
  64. .br
  65.       unsigned int *\fInchildren_return\fP\^;
  66. .FN
  67. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  68. .IP \fIdisplay\fP 1i
  69. Specifies the connection to the X server.
  70. .ds Wi whose list of children, root, parent, and number of children \
  71. you want to obtain
  72. .\" $Header: w_gen.a,v 1.4 88/08/04 11:21:56 mento Exp $
  73. .IP \fIw\fP 1i
  74. Specifies the window \*(Wi.
  75. .\" $Header: root.a,v 1.2 88/05/08 10:54:56 mento Exp $
  76. .IP \fIroot_return\fP 1i
  77. Returns the root window.
  78. .IP \fIparent_return\fP 1i
  79. Returns the parent window.
  80. .\" $Header: children.a,v 1.2 88/05/08 10:58:36 mento Exp $
  81. .IP \fIchildren_return\fP 1i
  82. Returns the list of children.
  83. .\" $Header: nchildren.a,v 1.2 88/05/08 11:00:11 mento Exp $
  84. .IP \fInchildren_return\fP 1i
  85. Returns the number of children.
  86. .\" End marker code here
  87. .LP
  88. .\" $Header: XQueryTree.d,v 1.2 88/06/11 07:52:43 mento Exp $
  89. The
  90. .PN XQueryTree
  91. function returns the root ID, the parent window ID, 
  92. a pointer to the list of children windows, 
  93. and the number of children in the list for the specified window.
  94. The children are listed in current stacking order, from bottommost 
  95. (first) to topmost (last).
  96. .PN XQueryTree
  97. returns zero if it fails and nonzero if it succeeds.
  98. To free this list when it is no longer needed, use 
  99. .PN XFree .
  100. .LP
  101. .PN XQueryTree
  102. can generate a
  103. .PN BadWindow
  104. error.
  105. .LP
  106. .sp
  107. To obtain the current attributes of a given window, use 
  108. .PN XGetWindowAttributes .
  109. .IN "XGetWindowAttributes" "" "@DEF@"
  110. .\" Start marker code here
  111. .FD 0
  112. .\" $Header: XGetAttr.f,v 1.1 88/02/26 10:00:23 mento Exp $
  113. Status XGetWindowAttributes\^(\^\fIdisplay\fP, \fIw\fP\^, \fIwindow_attributes_return\fP\^)
  114. .br
  115.       Display *\fIdisplay\fP\^;
  116. .br
  117.       Window \fIw\fP\^;
  118. .br
  119.       XWindowAttributes *\fIwindow_attributes_return\fP\^;
  120. .FN
  121. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  122. .IP \fIdisplay\fP 1i
  123. Specifies the connection to the X server.
  124. .ds Wi whose current attributes you want to obtain
  125. .\" $Header: w_gen.a,v 1.4 88/08/04 11:21:56 mento Exp $
  126. .IP \fIw\fP 1i
  127. Specifies the window \*(Wi.
  128. .\" $Header: windatt.a,v 1.1 88/02/26 10:32:38 mento Exp $
  129. .IP \fIwindow_attributes_return\fP 1i
  130. Returns the specified window's attributes in the
  131. .PN XWindowAttributes
  132. structure.
  133. .\" End marker code here
  134. .LP
  135. .\" $Header: XGetAttr.d,v 1.1 88/02/26 10:42:12 mento Exp $
  136. The
  137. .PN XGetWindowAttributes
  138. function returns the current attributes for the specified window to an
  139. .PN XWindowAttributes
  140. structure.
  141. .LP
  142. .IN "XWindowAttributes" "" "@DEF@"
  143. .\" Start marker code here
  144. .Ds 0
  145. .TA .5i 3i
  146. .ta .5i 3i
  147. typedef struct {
  148.     int x, y;    /* location of window */
  149.     int width, height;    /* width and height of window */
  150.     int border_width;    /* border width of window */
  151.     int depth;    /* depth of window */
  152.     Visual *visual;    /* the associated visual structure */
  153.     Window root;    /* root of screen containing window */
  154.     int class;    /* InputOutput, InputOnly*/
  155.     int bit_gravity;    /* one of the bit gravity values */
  156.     int win_gravity;    /* one of the window gravity values */
  157.     int backing_store;    /* NotUseful, WhenMapped, Always */
  158.     unsigned long backing_planes;    /* planes to be preserved if possible */
  159.     unsigned long backing_pixel;    /* value to be used when restoring planes */
  160.     Bool save_under;    /* boolean, should bits under be saved? */
  161.     Colormap colormap;    /* color map to be associated with window */
  162.     Bool map_installed;    /* boolean, is color map currently installed*/
  163.     int map_state;    /* IsUnmapped, IsUnviewable, IsViewable */
  164.     long all_event_masks;    /* set of events all people have interest in*/
  165.     long your_event_mask;    /* my event mask */
  166.     long do_not_propagate_mask;    /* set of events that should not propagate */
  167.     Bool override_redirect;    /* boolean value for override-redirect */
  168.     Screen *screen;    /* back pointer to correct screen */
  169. } XWindowAttributes;
  170. .De
  171. .\" End marker code here
  172. .LP
  173. The x and y members are set to the upper-left outer
  174. corner relative to the parent window's origin.
  175. The width and height members are set to the inside size of the window, 
  176. not including the border.
  177. The border_width member is set to the window's border width in pixels.
  178. The depth member is set to the depth of the window 
  179. (that is, bits per pixel for the object).
  180. The visual member is a pointer to the screen's associated
  181. .PN Visual
  182. structure.
  183. The root member is set to the root window of the screen containing the window.
  184. The class member is set to the window's class and can be either
  185. .PN InputOutput
  186. or
  187. .PN InputOnly .
  188. .LP
  189. The bit_gravity member is set to the window's bit gravity
  190. and can be one of the following:
  191. .LP
  192. .TS
  193. lw(1.5i) lw(1.5i).
  194. T{
  195. .PN ForgetGravity
  196. T}    T{
  197. .PN EastGravity
  198. T}
  199. T{
  200. .PN NorthWestGravity
  201. T}    T{
  202. .PN SouthWestGravity
  203. T}
  204. T{
  205. .PN NorthGravity
  206. T}    T{
  207. .PN SouthGravity
  208. T}
  209. T{
  210. .PN NorthEastGravity
  211. T}    T{
  212. .PN SouthEastGravity
  213. T}
  214. T{
  215. .PN WestGravity
  216. T}    T{
  217. .PN StaticGravity
  218. T}
  219. .PN CenterGravity
  220. .TE
  221. .LP
  222. The win_gravity member is set to the window's window gravity
  223. and can be one of the following:
  224. .LP
  225. .TS
  226. lw(1.5i) lw(1.5i).
  227. T{
  228. .PN UnmapGravity
  229. T}    T{
  230. .PN EastGravity
  231. T}
  232. T{
  233. .PN NorthWestGravity
  234. T}    T{
  235. .PN SouthWestGravity
  236. T}
  237. T{
  238. .PN NorthGravity
  239. T}    T{
  240. .PN SouthGravity
  241. T}
  242. T{
  243. .PN NorthEastGravity
  244. T}    T{
  245. .PN SouthEastGravity
  246. T}
  247. T{
  248. .PN WestGravity
  249. T}    T{
  250. .PN StaticGravity
  251. T}
  252. .PN CenterGravity
  253. .TE
  254. .LP
  255. For additional information on gravity,
  256. see section 3.3.
  257. .LP
  258. The backing_store member is set to indicate how the X server should maintain
  259. the contents of a window 
  260. and can be 
  261. .PN WhenMapped ,
  262. .PN Always ,
  263. or
  264. .PN NotUseful .
  265. The backing_planes member is set to indicate (with bits set to 1) which bit 
  266. planes of the window hold dynamic data that must be preserved in backing_stores 
  267. and during save_unders.
  268. The backing_pixel member is set to indicate what values to use 
  269. for planes not set in backing_planes.
  270. .LP
  271. The save_under member is set to 
  272. .PN True
  273. or
  274. .PN False .
  275. The colormap member is set to the colormap for the specified window and can be
  276. a colormap ID or 
  277. .PN None .
  278. The map_installed member is set to indicate whether the colormap is 
  279. currently installed and can be 
  280. .PN True
  281. or
  282. .PN False .
  283. The map_state member is set to indicate the state of the window and can be
  284. .PN IsUnmapped ,
  285. .PN IsUnviewable ,
  286. or
  287. .PN IsViewable .
  288. .PN IsUnviewable
  289. is used if the window is mapped but some ancestor is unmapped.
  290. .LP
  291. The all_event_masks member is set to the bitwise inclusive OR of all event 
  292. masks selected on the window by all clients.
  293. The your_event_mask member is set to the bitwise inclusive OR of all event 
  294. masks selected by the querying client.
  295. The do_not_propagate_mask member is set to the bitwise inclusive OR of the 
  296. set of events that should not propagate.
  297. .LP
  298. The override_redirect member is set to indicate whether this window overrides
  299. structure control facilities and can be 
  300. .PN True
  301. or
  302. .PN False .
  303. Window manager clients should ignore the window if this member is
  304. .PN True .
  305. .LP
  306. The screen member is set to a screen pointer that gives you a back pointer 
  307. to the correct screen.
  308. This makes it easier to obtain the screen information without
  309. having to loop over the root window fields to see which field matches.
  310. .LP
  311. .PN XGetWindowAttributes
  312. can generate
  313. .PN BadDrawable
  314. and
  315. .PN BadWindow
  316. errors.
  317. .LP
  318. .sp
  319. To obtain the current geometry of a given drawable, use 
  320. .PN XGetGeometry .
  321. .IN "XGetGeometry" "" "@DEF@"
  322. .\" Start marker code here
  323. .FD 0
  324. .\" $Header: XGetGeometry.f,v 1.1 88/02/26 10:00:34 mento Exp $
  325. Status XGetGeometry\^(\^\fIdisplay\fP, \fId\fP\^, \^\fIroot_return\fP\^, \fIx_return\fP\^, \fIy_return\fP\^, \fIwidth_return\fP\^, 
  326. .br
  327.                       \fIheight_return\fP\^, \fIborder_width_return\fP\^, \fIdepth_return\fP\^)
  328. .br
  329.         Display *\fIdisplay\fP\^;
  330. .br
  331.         Drawable \fId\fP\^;
  332. .br
  333.         Window *\fIroot_return\fP\^;
  334. .br
  335.         int *\fIx_return\fP\^, *\fIy_return\fP\^;
  336. .br
  337.         unsigned int *\fIwidth_return\fP\^, *\fIheight_return\fP\^;
  338. .br
  339.         unsigned int *\fIborder_width_return\fP\^;
  340. .br
  341.         unsigned int *\fIdepth_return\fP\^;
  342. .FN
  343. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  344. .IP \fIdisplay\fP 1i
  345. Specifies the connection to the X server.
  346. .ds Dr , which can be a window or a pixmap
  347. .\" $Header: d_gen.a,v 1.2 88/08/04 11:09:21 mento Exp $
  348. .IP \fId\fP 1i
  349. Specifies the drawable\*(Dr. 
  350. .\" $Header: root.a,v 1.2 88/05/08 10:54:56 mento Exp $
  351. .IP \fIroot_return\fP 1i
  352. Returns the root window.
  353. .\" $Header: getxy.a,v 1.5 88/08/17 09:00:47 mento Exp $
  354. .IP \fIx_return\fP 1i
  355. .br
  356. .ns
  357. .IP \fIy_return\fP 1i
  358. Return the x and y coordinates that define the location of the drawable.
  359. For a window, 
  360. these coordinates specify the upper-left outer corner relative to
  361. its parent's origin.
  362. For pixmaps, these coordinates are always zero.
  363. .IP \fIwidth_return\fP 1i
  364. .br
  365. .ns
  366. .IP \fIheight_return\fP 1i
  367. Return the drawable's dimensions (width and height).
  368. For a window, 
  369. these dimensions specify the inside size, not including the border.
  370. .IP \fIborder_width_return\fP 1i
  371. Returns the border width in pixels. 
  372. If the drawable is a pixmap, it returns zero.
  373. .IP \fIdepth_return\fP 1i
  374. Returns the depth of the drawable (bits per pixel for the object).
  375. .\" End marker code here
  376. .LP
  377. .\" $Header: XGetGeometry.d,v 1.3 88/06/11 07:51:01 mento Exp $
  378. The
  379. .PN XGetGeometry
  380. function returns the root window and the current geometry of the drawable.
  381. The geometry of the drawable includes the x and y coordinates, width and height,
  382. border width, and depth.
  383. These are described in the argument list.
  384. It is legal to pass to this function a window whose class is
  385. .PN InputOnly .
  386. .LP
  387. .PN XGetGeometry
  388. can generate a
  389. .PN BadDrawable
  390. error.
  391. .NH 2
  392. Translating Screen Coordinates
  393. .XS
  394. \*(SN Translating Screen Coordinates 
  395. .XE
  396. .LP
  397. Applications sometimes
  398. need to perform a coordinate transformation from the coordinate
  399. space of one window to another window or need to determine which
  400. window the pointing device is in.
  401. .PN XTranslateCoordinates
  402. and
  403. .PN XQueryPointer
  404. fulfill these needs (and avoids any race conditions) by
  405. asking the X server to perform these operations.
  406. .LP
  407. .sp
  408. To translate a coordinate in one window to the coordinate
  409. space of another window, use
  410. .PN XTranslateCoordinates .
  411. .IN "XTranslateCoordinates" "" "@DEF@"
  412. .\" Start marker code here
  413. .FD 0
  414. .\" $Header: XTranCoords.f,v 1.2 88/04/05 14:44:04 mento Exp $
  415. Bool XTranslateCoordinates\^(\^\fIdisplay\fP, \fIsrc_w\fP\^, \fIdest_w\fP\^, \fIsrc_x\fP\^, \fIsrc_y\fP\^, \fIdest_x_return\fP\^, 
  416. .br
  417.                             \fIdest_y_return\fP\^, \fIchild_return\fP\^)
  418. .br
  419.       Display *\fIdisplay\fP\^;
  420. .br
  421.       Window \fIsrc_w\fP\^, \fIdest_w\fP\^;
  422. .br
  423.       int \fIsrc_x\fP\^, \fIsrc_y\fP\^;
  424. .br
  425.       int *\fIdest_x_return\fP\^, *\fIdest_y_return\fP\^;
  426. .br
  427.       Window *\fIchild_return\fP\^;
  428. .FN
  429. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  430. .IP \fIdisplay\fP 1i
  431. Specifies the connection to the X server.
  432. .\" $Header: sw.a,v 1.2 88/05/07 13:19:45 mento Exp $
  433. .IP \fIsrc_w\fP 1i
  434. Specifies the source window.
  435. .\" $Header: dw.a,v 1.2 88/05/07 13:20:18 mento Exp $
  436. .IP \fIdest_w\fP 1i
  437. Specifies the destination window.
  438. .\" $Header: srcxy1.a,v 1.1 88/02/26 10:31:23 mento Exp $
  439. .IP \fIsrc_x\fP 1i
  440. .br
  441. .ns
  442. .IP \fIsrc_y\fP 1i
  443. Specify the x and y coordinates within the source window.
  444. .\" $Header: destxy.a,v 1.2 88/05/07 13:21:31 mento Exp $
  445. .IP \fIdest_x_return\fP 1i
  446. .br
  447. .ns
  448. .IP \fIdest_y_return\fP 1i
  449. Return the x and y coordinates within the destination window.
  450. .\" $Header: child.a,v 1.1 88/02/26 10:05:43 mento Exp $
  451. .IP \fIchild_return\fP 1i
  452. Returns the child if the coordinates are contained in a mapped child of the
  453. destination window.
  454. .\" End marker code here
  455. .LP
  456. .\" $Header: XTranCoords.d,v 1.5 88/08/17 08:32:02 mento Exp $
  457. If
  458. .PN XTranslateCoordinates
  459. returns
  460. .PN True ,
  461. it takes the src_x and src_y coordinates relative
  462. to the source window's origin and returns these coordinates to 
  463. dest_x_return and dest_y_return
  464. relative to the destination window's origin.
  465. If
  466. .PN XTranslateCoordinates
  467. returns 
  468. .PN False , 
  469. src_w and dest_w are on different screens,
  470. and dest_x_return and dest_y_return are zero.
  471. If the coordinates are contained in a mapped child of dest_w,
  472. that child is returned to child_return.
  473. Otherwise, child_return is set to
  474. .PN None .
  475. .LP
  476. .PN XTranslateCoordinates
  477. can generate a
  478. .PN BadWindow 
  479. error.
  480. .LP
  481. .sp
  482. To obtain the screen coordinates of the pointer,
  483. or to determine the pointer coordinates relative to a specified window, use 
  484. .PN XQueryPointer .
  485. .IN "XQueryPointer" "" "@DEF@"
  486. .\" Start marker code here
  487. .FD 0
  488. .\" $Header: XQueryPntr.f,v 1.1 88/02/26 10:02:18 mento Exp $
  489. Bool XQueryPointer\^(\^\fIdisplay\fP, \fIw\fP\^, \fIroot_return\fP\^, \fIchild_return\fP\^, \fIroot_x_return\fP\^, \fIroot_y_return\fP\^, 
  490. .br
  491.                      \fIwin_x_return\fP\^, \fIwin_y_return\fP\^, \fImask_return\fP\^)
  492. .br
  493.       Display *\fIdisplay\fP\^;
  494. .br
  495.       Window \fIw\fP\^;
  496. .br
  497.       Window *\fIroot_return\fP\^, *\fIchild_return\fP\^;
  498. .br
  499.       int *\fIroot_x_return\fP\^, *\fIroot_y_return\fP\^;
  500. .br
  501.       int *\fIwin_x_return\fP\^, *\fIwin_y_return\fP\^;
  502. .br
  503.       unsigned int *\fImask_return\fP\^;
  504. .FN
  505. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  506. .IP \fIdisplay\fP 1i
  507. Specifies the connection to the X server.
  508. .\" $Header: w.a,v 1.2 88/05/07 11:35:31 mento Exp $
  509. .IP \fIw\fP 1i
  510. Specifies the window.
  511. .ds Ro that the pointer is in
  512. .\" $Header: root_gen.a,v 1.2 88/08/04 11:19:15 mento Exp $
  513. .IP \fIroot_return\fP 1i
  514. Returns the root window \*(Ro.
  515. .IP \fIchild_return\fP 1i
  516. Returns the child window that the pointer is located in, if any.
  517. .\" $Header: rootxy.a,v 1.2 88/08/17 09:03:18 mento Exp $
  518. .IP \fIroot_x_return\fP 1i
  519. .br
  520. .ns
  521. .IP \fIroot_y_return\fP 1i
  522. Return the pointer coordinates relative to the root window's origin.
  523. .\" $Header: winxy.a,v 1.2 88/08/17 09:04:07 mento Exp $
  524. .IP \fIwin_x_return\fP 1i
  525. .br
  526. .ns
  527. .IP \fIwin_y_return\fP 1i
  528. Return the pointer coordinates relative to the specified window.
  529. .\" $Header: mask1.a,v 1.1 88/02/26 10:28:48 mento Exp $
  530. .IP \fImask_return\fP 1i
  531. Returns the current state of the modifier keys and pointer buttons.
  532. .\" End marker code here
  533. .LP
  534. .\" $Header: XQueryPntr.d,v 1.2 88/06/11 07:52:42 mento Exp $
  535. The
  536. .PN XQueryPointer
  537. function returns the root window the pointer is logically on and the pointer
  538. coordinates relative to the root window's origin.
  539. If
  540. .PN XQueryPointer
  541. returns 
  542. .PN False , 
  543. the pointer is not on the same screen as the specified window, and
  544. .PN XQueryPointer
  545. returns 
  546. .PN None
  547. to child_return and zero to win_x_return and win_y_return.
  548. If 
  549. .PN XQueryPointer
  550. returns 
  551. .PN True , 
  552. the pointer coordinates returned to win_x_return and win_y_return
  553. are relative to the origin of the specified window.
  554. In this case, 
  555. .PN XQueryPointer
  556. returns the child that contains the pointer, if any,
  557. or else
  558. .PN None
  559. to child_return.
  560. .LP
  561. .PN XQueryPointer
  562. returns the current logical state of the keyboard buttons 
  563. and the modifier keys in mask_return.
  564. It sets mask_return to the bitwise inclusive OR of one or more
  565. of the button or modifier key bitmasks to match 
  566. the current state of the mouse buttons and the modifier keys.
  567. .LP
  568. Note that the logical state of a device (as seen through Xlib)
  569. may lag the physical state if device event processing is frozen
  570. (see section 12.1).
  571. .LP
  572. .PN XQueryPointer
  573. can generate a
  574. .PN BadWindow 
  575. error.
  576. .NH 2
  577. Properties and Atoms
  578. .XS
  579. \*(SN Properties and Atoms 
  580. .XE
  581. .LP
  582. A property is a collection of named, typed data.
  583. The window system has a set of predefined properties
  584. .IN "Atom" "predefined"
  585. (for example, the name of a window, size hints, and so on), and users can
  586. define any other arbitrary information and associate it with windows.
  587. Each property has a name,
  588. which is an ISO Latin-1 string.
  589. For each named property,
  590. a unique identifier (atom) is associated with it. 
  591. A property also has a type, for example, string or integer.
  592. These types are also indicated using atoms, so arbitrary new
  593. types can be defined.
  594. Data of only one type may be associated with a single
  595. property name.
  596. Clients can store and retrieve properties associated with windows.
  597. For efficiency reasons,
  598. an atom is used rather than a character string.
  599. .PN XInternAtom
  600. can be used to obtain the atom for property names.
  601. .IN "Atom" 
  602. .LP
  603. A property is also stored in one of several possible formats.
  604. The X server can store the information as 8-bit quantities, 16-bit
  605. quantities, or 32-bit quantities.
  606. This permits the X server to present the data in the byte order that the
  607. client expects.
  608. .NT Note
  609. If you define further properties of complex type, 
  610. you must encode and decode them yourself.
  611. These functions must be carefully written if they are to be portable.
  612. For further information about how to write a library extension,
  613. see appendix C.
  614. .NE
  615. The type of a property is defined by an atom, which allows for
  616. arbitrary extension in this type scheme.
  617. .IN "Atom" 
  618. .LP
  619. Certain property names are
  620. predefined in the server for commonly used functions.
  621. The atoms for these properties are defined in 
  622. .Pn < X11/Xatom.h >.
  623. To avoid name clashes with user symbols, the 
  624. .PN #define 
  625. name for each atom has the XA_ prefix.
  626. For definitions of these properties,
  627. see section 4.3.
  628. For an explanation of the functions that let you get and set
  629. much of the information stored in these predefined properties,
  630. see chapter 14.
  631. .LP
  632. The core protocol imposes no semantics on these property names,
  633. but semantics are specified in other X Consortium standards,
  634. such as the \fIInter-Client Communication Conventions Manual\fP
  635. and the \fIX Logical Font Description Conventions\fP.
  636. .LP
  637. You can use properties to communicate other information between
  638. applications.
  639. The functions described in this section let you define new properties 
  640. and get the unique atom IDs in your applications.
  641. .LP
  642. Although any particular atom can have some client interpretation 
  643. within each of the name spaces, 
  644. atoms occur in five distinct name spaces within the protocol: 
  645. .IP \(bu 5
  646. Selections
  647. .IP \(bu 5
  648. Property names
  649. .IP \(bu 5
  650. Property types
  651. .IP \(bu 5
  652. Font properties 
  653. .IP \(bu 5
  654. Type of a 
  655. .PN ClientMessage 
  656. event (none are built into the X server)
  657. .LP
  658. .LP
  659. The built-in selection property names are:
  660. .LP
  661. .Ds 0
  662. .TA .5i 1.5i 3i
  663. .ta .5i 1.5i 3i
  664. .R
  665. PRIMARY
  666. SECONDARY
  667. .De
  668. .LP
  669. The built-in property names are: 
  670. .TS
  671. lw(2i) lw(2i).
  672. .sp 6p
  673. CUT_BUFFER0    RESOURCE_MANAGER
  674. CUT_BUFFER1    WM_CLASS
  675. CUT_BUFFER2    WM_CLIENT_MACHINE
  676. CUT_BUFFER3    WM_COLORMAP_WINDOWS
  677. CUT_BUFFER4    WM_COMMAND
  678. CUT_BUFFER5    WM_HINTS
  679. CUT_BUFFER6    WM_ICON_NAME
  680. CUT_BUFFER7    WM_ICON_SIZE
  681. RGB_BEST_MAP    WM_NAME
  682. RGB_BLUE_MAP    WM_NORMAL_HINTS
  683. RGB_DEFAULT_MAP    WM_PROTOCOLS
  684. RGB_GRAY_MAP    WM_STATE
  685. RGB_GREEN_MAP    WM_TRANSIENT_FOR
  686. RGB_RED_MAP
  687. .sp 6p
  688. .TE
  689. .LP
  690. The built-in property types are: 
  691. .LP
  692. .TS
  693. lw(2i) lw(2i).
  694. .sp 6p
  695. ARC    POINT
  696. ATOM    RGB_COLOR_MAP
  697. BITMAP    RECTANGLE
  698. CARDINAL    STRING
  699. COLORMAP    VISUALID
  700. CURSOR    WINDOW
  701. DRAWABLE    WM_HINTS
  702. FONT    WM_SIZE_HINTS
  703. INTEGER    
  704. PIXMAP
  705. .sp 6p
  706. .TE
  707. .LP
  708. The built-in font property names are: 
  709. .TS
  710. lw(2i) lw(2i).
  711. .sp 6p
  712. MIN_SPACE    STRIKEOUT_DESCENT
  713. NORM_SPACE    STRIKEOUT_ASCENT
  714. MAX_SPACE    ITALIC_ANGLE
  715. END_SPACE    X_HEIGHT
  716. SUPERSCRIPT_X    QUAD_WIDTH
  717. SUPERSCRIPT_Y    WEIGHT
  718. SUBSCRIPT_X    POINT_SIZE
  719. SUBSCRIPT_Y    RESOLUTION
  720. UNDERLINE_POSITION    COPYRIGHT
  721. UNDERLINE_THICKNESS    NOTICE
  722. FONT_NAME    FAMILY_NAME
  723. FULL_NAME    CAP_HEIGHT
  724. .sp 6p
  725. .TE
  726. .LP
  727. For further information about font properties,
  728. see section 8.5.
  729. .LP
  730. .sp
  731. To return an atom for a given name, use 
  732. .PN XInternAtom .
  733. .IN "Atom" "interning"
  734. .IN "XInternAtom" "" "@DEF@"
  735. .\" Start marker code here
  736. .FD 0
  737. .\" $Header: XInternAtom.f,v 1.1 88/02/26 10:01:15 mento Exp $
  738. Atom XInternAtom\^(\^\fIdisplay\fP, \fIatom_name\fP\^, \fIonly_if_exists\fP\^)
  739. .br
  740.       Display *\fIdisplay\fP\^;
  741. .br
  742.       char *\fIatom_name\fP\^;
  743. .br
  744.       Bool \fIonly_if_exists\fP\^;
  745. .FN
  746. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  747. .IP \fIdisplay\fP 1i
  748. Specifies the connection to the X server.
  749. .\" $Header: atom_name.a,v 1.1 88/02/26 10:05:01 mento Exp $
  750. .IP \fIatom_name\fP 1i
  751. Specifies the name associated with the atom you want returned.
  752. .\" $Header: onlyifexist.a,v 1.3 88/05/08 11:36:14 mento Exp $
  753. .IP \fIonly_if_exists\fP 1i
  754. Specifies a Boolean value that indicates whether
  755. .PN XInternAtom
  756. creates the atom.
  757. .\" End marker code here
  758. .LP
  759. .\" $Header: XInternAtom.d,v 1.5 88/08/17 09:06:25 mento Exp $
  760. The
  761. .PN XInternAtom
  762. function returns the atom identifier associated with the specified atom_name
  763. string.
  764. If only_if_exists is 
  765. .PN False ,
  766. the atom is created if it does not exist.
  767. Therefore,
  768. .PN XInternAtom
  769. can return
  770. .PN None .
  771. If the atom name is not in the Host Portable Character Encoding
  772. the result is implementation dependent.
  773. Case matters; the strings \fIthing\fP, \fIThing\fP, and \fIthinG\fP 
  774. all designate different atoms.  
  775. The atom will remain defined even after the client's connection closes.
  776. It will become undefined only when the last connection to
  777. the X server closes.
  778. .LP
  779. .PN XInternAtom
  780. can generate
  781. .PN BadAlloc
  782. and
  783. .PN BadValue 
  784. errors.
  785. .LP
  786. .sp
  787. To return a name for a given atom identifier, use 
  788. .PN XGetAtomName .
  789. .IN "Atom" "getting name"
  790. .IN "XGetAtomName" "" "@DEF@"
  791. .\" Start marker code here
  792. .FD 0
  793. .\" $Header: XGetAtomName.f,v 1.1 88/02/26 10:00:23 mento Exp $
  794. char *XGetAtomName\^(\^\fIdisplay\fP, \fIatom\fP\^)
  795. .br
  796.       Display *\fIdisplay\fP\^;
  797. .br
  798.       Atom \fIatom\fP\^;
  799. .FN
  800. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  801. .IP \fIdisplay\fP 1i
  802. Specifies the connection to the X server.
  803. .\" $Header: atom.a,v 1.2 88/04/06 12:06:45 mento Exp $
  804. .IP \fIatom\fP 1i
  805. Specifies the atom for the property name you want returned.
  806. .\" End marker code here
  807. .LP
  808. .\" $Header: XGetAtomName.d,v 1.3 88/05/08 11:40:48 mento Exp $
  809. The
  810. .PN XGetAtomName
  811. function returns the name associated with the specified atom.
  812. If the data returned by the server is in the Latin Portable Character Encoding,
  813. then the returned string is in the Host Portable Character Encoding.
  814. Otherwise, the result is implementation dependent.
  815. To free the resulting string,
  816. call
  817. .PN XFree .
  818. .LP
  819. .PN XGetAtomName
  820. can generate a
  821. .PN BadAtom 
  822. error.
  823. .NH 2
  824. Obtaining and Changing Window Properties
  825. .XS
  826. \*(SN Obtaining and Changing Window Properties 
  827. .XE
  828. .LP
  829. You can attach a property list to every window.
  830. Each property has a name, a type, and a value (see section 4.3).
  831. The value is an array of 8-bit, 16-bit, or 32-bit quantities,
  832. whose interpretation is left to the clients. 
  833. .LP
  834. Xlib provides functions that you can use to obtain, 
  835. change, update, or interchange window properties.
  836. In addition, Xlib provides other utility functions for inter-client
  837. communication (see chapter 14).
  838. .LP
  839. .sp
  840. To obtain the type, format, and value of a property of a given window, use 
  841. .PN XGetWindowProperty .
  842. .IN "Property" "getting"
  843. .LP
  844. .IN "XGetWindowProperty" "" "@DEF@"
  845. .\" Start marker code here
  846. .FD 0
  847. .\" $Header: XGetProperty.f,v 1.1 88/02/26 10:00:55 mento Exp $
  848. int XGetWindowProperty\^(\^\fIdisplay\fP, \fIw\fP\^, \fIproperty\fP\^, \fIlong_offset\fP\^, \fIlong_length\fP\^, \fIdelete\fP\^, \fIreq_type\fP\^, 
  849. .br
  850.                         \fIactual_type_return\fP\^, \fIactual_format_return\fP\^, \fInitems_return\fP\^, \fIbytes_after_return\fP\^, 
  851. .br
  852.                         \fIprop_return\fP\^)
  853. .br
  854.       Display *\fIdisplay\fP\^;
  855. .br
  856.       Window \fIw\fP\^;
  857. .br
  858.       Atom \fIproperty\fP\^;
  859. .br
  860.       long \fIlong_offset\fP\^, \fIlong_length\fP\^;
  861. .br
  862.       Bool \fIdelete\fP\^;
  863. .br
  864.       Atom \fIreq_type\fP\^; 
  865. .br
  866.       Atom *\fIactual_type_return\fP\^;
  867. .br
  868.       int *\fIactual_format_return\fP\^;
  869. .br
  870.       unsigned long *\fInitems_return\fP\^;
  871. .br
  872.       unsigned long *\fIbytes_after_return\fP\^;
  873. .br
  874.       unsigned char **\fIprop_return\fP\^;
  875. .FN
  876. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  877. .IP \fIdisplay\fP 1i
  878. Specifies the connection to the X server.
  879. .ds Wi whose property you want to obtain
  880. .\" $Header: w_gen.a,v 1.4 88/08/04 11:21:56 mento Exp $
  881. .IP \fIw\fP 1i
  882. Specifies the window \*(Wi.
  883. .\" $Header: property.a,v 1.2 88/04/05 15:19:43 mento Exp $
  884. .IP \fIproperty\fP 1i
  885. Specifies the property name.
  886. .IP \fIlong_offset\fP 1i
  887. Specifies the offset in the specified property (in 32-bit quantities) 
  888. where the data is to be retrieved.
  889. .IP \fIlong_length\fP 1i
  890. Specifies the length in 32-bit multiples of the data to be retrieved.
  891. .\" $Header: delete.a,v 1.4 88/05/08 11:45:29 mento Exp $
  892. .IP \fIdelete\fP 1i
  893. Specifies a Boolean value that determines whether the property is deleted.
  894. .\" $Header: reqtype.a,v 1.3 88/05/08 11:46:32 mento Exp $
  895. .IP \fIreq_type\fP 1i
  896. Specifies the atom identifier associated with the property type or
  897. .PN AnyPropertyType .
  898. .\" $Header: actual_type.a,v 1.1 88/02/26 10:04:47 mento Exp $
  899. .IP \fIactual_type_return\fP 1i
  900. Returns the atom identifier  that defines the actual type of the property.
  901. .\" $Header: act_format.a,v 1.1 88/02/26 10:04:45 mento Exp $
  902. .IP \fIactual_format_return\fP 1i
  903. Returns the actual format of the property.
  904. .IP \fInitems_return\fP 1i
  905. Returns the actual number of 8-bit, 16-bit, or 32-bit items 
  906. stored in the prop_return data.
  907. .IP \fIbytes_after_return\fP 1i
  908. Returns the number of bytes remaining to be read in the property if 
  909. a partial read was performed.
  910. .IP \fIprop_return\fP 1i
  911. Returns the data in the specified format.
  912. .\" End marker code here
  913. .LP
  914. .\" $Header: XGetProperty.d,v 1.3 88/08/17 09:10:14 mento Exp $
  915. The
  916. .PN XGetWindowProperty
  917. function returns the actual type of the property; the actual format of the property;
  918. the number of 8-bit, 16-bit, or 32-bit items transferred; the number of bytes remaining
  919. to be read in the property; and a pointer to the data actually returned.
  920. .PN XGetWindowProperty
  921. sets the return arguments as follows:
  922. .IP \(bu 5
  923. If the specified property does not exist for the specified window,
  924. .PN XGetWindowProperty 
  925. returns 
  926. .PN None
  927. to actual_type_return and the value zero to 
  928. actual_format_return and bytes_after_return.
  929. The nitems_return argument is empty.
  930. In this case, the delete argument is ignored.
  931. .IP \(bu 5
  932. If the specified property exists 
  933. but its type does not match the specified type,
  934. .PN XGetWindowProperty 
  935. returns the actual property type to actual_type_return, 
  936. the actual property format (never zero) to actual_format_return, 
  937. and the property length in bytes (even if the actual_format_return is 16 or 32) 
  938. to bytes_after_return.
  939. It also ignores the delete argument.
  940. The nitems_return argument is empty.
  941. .IP \(bu 5
  942. If the specified property exists and either you assign 
  943. .PN AnyPropertyType 
  944. to the req_type argument or the specified type matches the actual property type,
  945. .PN XGetWindowProperty 
  946. returns the actual property type to actual_type_return and the actual
  947. property format (never zero) to actual_format_return. 
  948. It also returns a value to bytes_after_return and nitems_return, by 
  949. defining the following
  950. values:
  951. .IP
  952. .nf
  953.     N = actual length of the stored property in bytes
  954.          (even if the format is 16 or 32)
  955.     I = 4 * long_offset
  956.     T = N - I
  957.     L = MINIMUM(T, 4 * long_length)
  958.     A = N - (I + L)
  959. .fi
  960. .IP
  961. The returned value starts at byte index I in the property (indexing
  962. from zero), and its length in bytes is L.
  963. If the value for long_offset causes L to be negative,
  964. a
  965. .PN BadValue
  966. error results. 
  967. The value of bytes_after_return is A, 
  968. giving the number of trailing unread bytes in the stored property.
  969. .LP
  970. .PN XGetWindowProperty
  971. always allocates one extra byte in prop_return 
  972. (even if the property is zero length) 
  973. and sets it to ASCII null so that simple properties consisting of characters
  974. do not have to be copied into yet another string before use.
  975. If delete is 
  976. .PN True 
  977. and bytes_after_return is zero, 
  978. .PN XGetWindowProperty
  979. deletes the property 
  980. from the window and generates a 
  981. .PN PropertyNotify 
  982. event on the window.
  983. .LP
  984. The function returns
  985. .PN Success
  986. if it executes successfully.
  987. To free the resulting data,
  988. use
  989. .PN XFree .
  990. .LP
  991. .PN XGetWindowProperty
  992. can generate
  993. .PN BadAtom ,
  994. .PN BadValue ,
  995. and
  996. .PN BadWindow 
  997. errors.
  998. .LP
  999. .sp
  1000. To obtain a given window's property list, use 
  1001. .PN XListProperties .
  1002. .IN "Property" "listing"
  1003. .IN "XListProperties" "" "@DEF@"
  1004. .\" Start marker code here
  1005. .FD 0
  1006. .\" $Header: XListProps.f,v 1.1 88/02/26 10:01:22 mento Exp $
  1007. Atom *XListProperties\^(\^\fIdisplay\fP, \fIw\fP\^, \fInum_prop_return\fP\^)
  1008. .br
  1009.       Display *\fIdisplay\fP\^;
  1010. .br
  1011.       Window \fIw\fP\^;
  1012. .br
  1013.       int *\fInum_prop_return\fP\^; 
  1014. .FN
  1015. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  1016. .IP \fIdisplay\fP 1i
  1017. Specifies the connection to the X server.
  1018. .ds Wi whose property list you want to obtain
  1019. .\" $Header: w_gen.a,v 1.4 88/08/04 11:21:56 mento Exp $
  1020. .IP \fIw\fP 1i
  1021. Specifies the window \*(Wi.
  1022. .IP \fInum_prop_return\fP 1i
  1023. Returns the length of the properties array.
  1024. .\" End marker code here
  1025. .LP
  1026. .\" $Header: XListProps.d,v 1.4 88/05/08 11:58:22 mento Exp $
  1027. The
  1028. .PN XListProperties
  1029. function returns a pointer to an array of atom properties that are defined for 
  1030. the specified window or returns NULL if no properties were found.
  1031. To free the memory allocated by this function, use
  1032. .PN XFree .
  1033. .LP
  1034. .PN XListProperties
  1035. can generate a
  1036. .PN BadWindow 
  1037. error.
  1038. .LP
  1039. .sp
  1040. To change a property of a given window, use
  1041. .PN XChangeProperty .
  1042. .IN "Property" "changing"
  1043. .IN "Property" "appending"
  1044. .IN "Property" "prepending"
  1045. .IN "Property" "replacing"
  1046. .IN "Property" "format"
  1047. .IN "Property" "type"
  1048. .IN "XChangeProperty" "" "@DEF@"
  1049. .\" Start marker code here
  1050. .FD 0
  1051. .\" $Header: XChProperty.f,v 1.1 88/02/26 09:58:33 mento Exp $
  1052. XChangeProperty\^(\^\fIdisplay\fP, \fIw\fP\^, \fIproperty\fP\^, \fItype\fP\^, \fIformat\fP\^, \fImode\fP\^, \fIdata\fP\^, \fInelements\fP\^)
  1053. .br
  1054.       Display *\fIdisplay\fP\^;
  1055. .br
  1056.       Window \fIw\fP\^;
  1057. .br
  1058.       Atom \fIproperty\fP\^, \fItype\fP\^;
  1059. .br
  1060.       int \fIformat\fP\^;
  1061. .br
  1062.       int \fImode\fP\^;
  1063. .br
  1064.       unsigned char *\fIdata\fP\^;
  1065. .br
  1066.       int \fInelements\fP\^;
  1067. .FN
  1068. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  1069. .IP \fIdisplay\fP 1i
  1070. Specifies the connection to the X server.
  1071. .ds Wi whose property you want to change
  1072. .\" $Header: w_gen.a,v 1.4 88/08/04 11:21:56 mento Exp $
  1073. .IP \fIw\fP 1i
  1074. Specifies the window \*(Wi.
  1075. .\" $Header: property.a,v 1.2 88/04/05 15:19:43 mento Exp $
  1076. .IP \fIproperty\fP 1i
  1077. Specifies the property name.
  1078. .\" $Header: type.a,v 1.2 88/03/29 08:07:25 mento Exp $
  1079. .IP \fItype\fP 1i
  1080. Specifies the type of the property.
  1081. The X server does not interpret the type but simply
  1082. passes it back to an application that later calls 
  1083. .PN XGetWindowProperty .
  1084. .\" $Header: format.a,v 1.2 88/05/08 11:59:58 mento Exp $
  1085. .IP \fIformat\fP 1i
  1086. Specifies whether the data should be viewed as a list
  1087. of 8-bit, 16-bit, or 32-bit quantities.
  1088. Possible values are 8, 16, and 32.
  1089. This information allows the X server to correctly perform
  1090. byte-swap operations as necessary.
  1091. If the format is 16-bit or 32-bit,
  1092. you must explicitly cast your data pointer to an (unsigned char *) in the call
  1093. to 
  1094. .PN XChangeProperty .
  1095. .\" $Header: prop_mode.a,v 1.2 88/04/04 11:18:11 mento Exp $
  1096. .\" Changed name of this file to prop_mode.a on 1/13/87
  1097. .IP \fImode\fP 1i
  1098. Specifies the mode of the operation.
  1099. You can pass
  1100. .PN PropModeReplace ,
  1101. .PN PropModePrepend ,
  1102. or
  1103. .PN PropModeAppend .
  1104. .\" $Header: data1.a,v 1.1 88/02/26 10:06:15 mento Exp $
  1105. .IP \fIdata\fP 1i
  1106. Specifies the property data.
  1107. .\" $Header: nelements.a,v 1.2 88/05/08 12:00:41 mento Exp $
  1108. .IP \fInelements\fP 1i
  1109. Specifies the number of elements of the specified data format.
  1110. .\" End marker code here
  1111. .LP
  1112. .\" $Header: XChProperty.d,v 1.2 88/06/11 07:49:04 mento Exp $
  1113. The
  1114. .PN XChangeProperty
  1115. function alters the property for the specified window and
  1116. causes the X server to generate a
  1117. .PN PropertyNotify
  1118. event on that window.
  1119. .PN XChangeProperty
  1120. performs the following:
  1121. .IP \(bu 5
  1122. If mode is
  1123. .PN PropModeReplace ,
  1124. .PN XChangeProperty
  1125. discards the previous property value and stores the new data.
  1126. .IP \(bu 5
  1127. If mode is
  1128. .PN PropModePrepend
  1129. or
  1130. .PN PropModeAppend ,
  1131. .PN XChangeProperty
  1132. inserts the specified data before the beginning of the existing data
  1133. or onto the end of the existing data, respectively.
  1134. The type and format must match the existing property value,
  1135. or a
  1136. .PN BadMatch
  1137. error results.
  1138. If the property is undefined, 
  1139. it is treated as defined with the correct type and
  1140. format with zero-length data.
  1141. .LP
  1142. The lifetime of a property is not tied to the storing client.
  1143. Properties remain until explicitly deleted, until the window is destroyed,
  1144. or until the server resets.
  1145. For a discussion of what happens when the connection to the X server is closed,
  1146. see section 2.6. 
  1147. The maximum size of a property is server dependent and can vary dynamically
  1148. depending on the amount of memory the server has available.
  1149. (If there is insufficient space, a
  1150. .PN BadAlloc
  1151. error results.)
  1152. .LP
  1153. .PN XChangeProperty
  1154. can generate
  1155. .PN BadAlloc ,
  1156. .PN BadAtom ,
  1157. .PN BadMatch ,
  1158. .PN BadValue ,
  1159. and
  1160. .PN BadWindow 
  1161. errors.
  1162. .LP
  1163. .sp
  1164. To rotate a window's property list, use
  1165. .PN XRotateWindowProperties .
  1166. .LP
  1167. .IN "XRotateWindowProperties" "" "@DEF@"
  1168. .\" Start marker code here
  1169. .FD 0
  1170. XRotateWindowProperties\^(\^\fIdisplay\fP, \fIw\fP, \fIproperties\fP, \fInum_prop\fP, \fInpositions\fP\^)
  1171. .br
  1172.       Display *\fIdisplay\fP\^;
  1173. .br
  1174.       Window \fIw\fP\^;
  1175. .br
  1176.       Atom \fIproperties\fP\^[]\^;
  1177. .br
  1178.       int \fInum_prop\fP\^;
  1179. .br
  1180.       int \fInpositions\fP\^;
  1181. .FN
  1182. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  1183. .IP \fIdisplay\fP 1i
  1184. Specifies the connection to the X server.
  1185. .\" $Header: w.a,v 1.2 88/05/07 11:35:31 mento Exp $
  1186. .IP \fIw\fP 1i
  1187. Specifies the window.
  1188. .\" $Header: properties.a,v 1.1 88/02/26 10:30:43 mento Exp $
  1189. .IP \fIproperties\fP 1i
  1190. Specifies the array of properties that are to be rotated.
  1191. .IP \fInum_prop\fP 1i
  1192. Specifies the length of the properties array.
  1193. .IP \fInpositions\fP 1i
  1194. Specifies the rotation amount.
  1195. .\" End marker code here
  1196. .LP
  1197. .\" $Header: XRotProp.d,v 1.3 88/06/11 07:52:52 mento Exp $
  1198. The
  1199. .PN XRotateWindowProperties
  1200. function allows you to rotate properties on a window and causes
  1201. the X server to generate
  1202. .PN PropertyNotify
  1203. events.
  1204. If the property names in the properties array are viewed as being numbered 
  1205. starting from zero and if there are num_prop property names in the list,
  1206. then the value associated with property name I becomes the value associated 
  1207. with property name (I + npositions) mod N for all I from zero to N \- 1.
  1208. The effect is to rotate the states by npositions places around the virtual ring
  1209. of property names (right for positive npositions, 
  1210. left for negative npositions).
  1211. If npositions mod N is nonzero,
  1212. the X server generates a
  1213. .PN PropertyNotify
  1214. event for each property in the order that they are listed in the array.
  1215. If an atom occurs more than once in the list or no property with that 
  1216. name is defined for the window,
  1217. a 
  1218. .PN BadMatch 
  1219. error results.
  1220. If a 
  1221. .PN BadAtom 
  1222. or 
  1223. .PN BadMatch 
  1224. error results,
  1225. no properties are changed.
  1226. .LP
  1227. .PN XRotateWindowProperties
  1228. can generate
  1229. .PN BadAtom ,
  1230. .PN BadMatch ,
  1231. and
  1232. .PN BadWindow 
  1233. errors.
  1234. .LP
  1235. .sp
  1236. To delete a property on a given window, use 
  1237. .PN XDeleteProperty .
  1238. .IN "Property" "deleting"
  1239. .IN "XDeleteProperty" "" "@DEF@"
  1240. .\" Start marker code here
  1241. .FD 0
  1242. .\" $Header: XDeleteProp.f,v 1.1 88/02/26 09:59:36 mento Exp $
  1243. XDeleteProperty\^(\^\fIdisplay\fP, \fIw\fP\^, \fIproperty\fP\^)
  1244. .br
  1245.       Display *\fIdisplay\fP\^;
  1246. .br
  1247.       Window \fIw\fP\^;
  1248. .br
  1249.       Atom \fIproperty\fP\^;
  1250. .FN
  1251. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  1252. .IP \fIdisplay\fP 1i
  1253. Specifies the connection to the X server.
  1254. .ds Wi whose property you want to delete
  1255. .\" $Header: w_gen.a,v 1.4 88/08/04 11:21:56 mento Exp $
  1256. .IP \fIw\fP 1i
  1257. Specifies the window \*(Wi.
  1258. .\" $Header: property.a,v 1.2 88/04/05 15:19:43 mento Exp $
  1259. .IP \fIproperty\fP 1i
  1260. Specifies the property name.
  1261. .\" End marker code here
  1262. .LP
  1263. .\" $Header: XDeleteProp.d,v 1.2 88/05/08 12:07:50 mento Exp $
  1264. The
  1265. .PN XDeleteProperty
  1266. function deletes the specified property only if the
  1267. property was defined on the specified window
  1268. and causes the X server to generate a
  1269. .PN PropertyNotify
  1270. event on the window unless the property does not exist.
  1271. .LP
  1272. .PN XDeleteProperty
  1273. can generate
  1274. .PN BadAtom
  1275. and
  1276. .PN BadWindow 
  1277. errors.
  1278. .NH 2
  1279. Selections
  1280. .XS
  1281. \*(SN Selections
  1282. .XE
  1283. .LP
  1284. .IN "Selection"
  1285. Selections are one method used by applications to exchange data.
  1286. By using the property mechanism,
  1287. applications can exchange data of arbitrary types and can negotiate
  1288. the type of the data.
  1289. A selection can be thought of as an indirect property with a dynamic type.
  1290. That is, rather than having the property stored in the X server,
  1291. the property is maintained by some client (the owner).
  1292. A selection is global in nature (considered to belong to the user 
  1293. but be maintained by clients) rather than being private to a particular 
  1294. window subhierarchy or a particular set of clients.
  1295. .LP
  1296. Xlib provides functions that you can use to set, get, or request conversion
  1297. of selections.
  1298. This allows applications to implement the notion of current selection,
  1299. which requires that notification be sent to applications when they no 
  1300. longer own the selection.
  1301. Applications that support selection often highlight the current selection
  1302. and so must be informed when another application has
  1303. acquired the selection so that they can unhighlight the selection.
  1304. .LP
  1305. When a client asks for the contents of
  1306. a selection, it specifies a selection target type.
  1307. This target type
  1308. can be used to control the transmitted representation of the contents.
  1309. For example, if the selection is ``the last thing the user clicked on''
  1310. and that is currently an image, then the target type might specify
  1311. whether the contents of the image should be sent in XY format or Z format.
  1312. .LP
  1313. The target type can also be used to control the class of
  1314. contents transmitted, for example, 
  1315. asking for the ``looks'' (fonts, line
  1316. spacing, indentation, and so forth) of a paragraph selection, not the
  1317. text of the paragraph.
  1318. The target type can also be used for other
  1319. purposes.
  1320. The protocol does not constrain the semantics.
  1321. .LP
  1322. .sp
  1323. To set the selection owner, use 
  1324. .PN XSetSelectionOwner .
  1325. .IN "Selection" "setting the owner"
  1326. .IN "XSetSelectionOwner" "" "@DEF@"
  1327. .\" Start marker code here
  1328. .FD 0
  1329. .\" $Header: XSetSelOwner.f,v 1.1 88/02/26 10:03:38 mento Exp $
  1330. XSetSelectionOwner\^(\^\fIdisplay\fP, \fIselection\fP\^, \fIowner\fP\^, \fItime\fP\^)
  1331. .br
  1332.       Display *\fIdisplay\fP\^;
  1333. .br
  1334.       Atom \fIselection\fP\^;
  1335. .br
  1336.       Window \fIowner\fP\^; 
  1337. .br
  1338.       Time \fItime\fP\^;
  1339. .FN
  1340. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  1341. .IP \fIdisplay\fP 1i
  1342. Specifies the connection to the X server.
  1343. .\" $Header: selection.a,v 1.1 88/02/26 10:31:11 mento Exp $
  1344. .IP \fIselection\fP 1i
  1345. Specifies the selection atom.
  1346. .\" $Header: owner.a,v 1.2 88/05/08 12:15:34 mento Exp $
  1347. .IP \fIowner\fP 1i
  1348. Specifies the owner of the specified selection atom.
  1349. You can pass a window or
  1350. .PN None .
  1351. .IP \fItime\fP 1i
  1352. Specifies the time.
  1353. You can pass either a timestamp or
  1354. .PN CurrentTime .
  1355. .\" End marker code here
  1356. .LP
  1357. .\" $Header: XSetSelOwner.d,v 1.3 88/06/11 07:53:34 mento Exp $
  1358. The
  1359. .PN XSetSelectionOwner
  1360. function changes the owner and last-change time for the specified selection
  1361. and has no effect if the specified time is earlier than the current
  1362. last-change time of the specified selection 
  1363. or is later than the current X server time.
  1364. Otherwise, the last-change time is set to the specified time,
  1365. with
  1366. .PN CurrentTime
  1367. replaced by the current server time.
  1368. If the owner window is specified as
  1369. .PN None ,
  1370. then the owner of the selection becomes 
  1371. .PN None
  1372. (that is, no owner).
  1373. Otherwise, the owner of the selection becomes the client executing
  1374. the request.
  1375. .LP 
  1376. If the new owner (whether a client or
  1377. .PN None )
  1378. is not
  1379. the same as the current owner of the selection and the current
  1380. owner is not
  1381. .PN None ,
  1382. the current owner is sent a 
  1383. .PN SelectionClear 
  1384. event.
  1385. If the client that is the owner of a selection is later
  1386. terminated (that is, its connection is closed)
  1387. or if the owner window it has specified in the request is later
  1388. destroyed,
  1389. the owner of the selection automatically
  1390. reverts to
  1391. .PN None ,
  1392. but the last-change time is not affected.
  1393. The selection atom is uninterpreted by the X server.
  1394. .PN XGetSelectionOwner
  1395. returns the owner window, which is reported in 
  1396. .PN SelectionRequest
  1397. and
  1398. .PN SelectionClear
  1399. events.
  1400. Selections are global to the X server.
  1401. .LP
  1402. .PN XSetSelectionOwner
  1403. can generate
  1404. .PN BadAtom
  1405. and
  1406. .PN BadWindow 
  1407. errors.
  1408. .LP
  1409. .sp
  1410. To return the selection owner, use 
  1411. .PN XGetSelectionOwner .
  1412. .IN "Selection" "getting the owner"
  1413. .IN "XGetSelectionOwner" "" "@DEF@"
  1414. .\" Start marker code here
  1415. .FD 0
  1416. .\" $Header: XGetSelOwner.f,v 1.1 88/02/26 10:00:59 mento Exp $
  1417. Window XGetSelectionOwner\^(\^\fIdisplay\fP, \fIselection\fP\^)
  1418. .br
  1419.       Display *\fIdisplay\fP\^;
  1420. .br
  1421.       Atom \fIselection\fP\^;
  1422. .FN
  1423. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  1424. .IP \fIdisplay\fP 1i
  1425. Specifies the connection to the X server.
  1426. .ds Se whose owner you want returned
  1427. .\" $Header: select_gen.a,v 1.2 88/08/04 11:20:01 mento Exp $
  1428. .IP \fIselection\fP 1i
  1429. Specifies the selection atom \*(Se.
  1430. .\" End marker code here
  1431. .LP
  1432. .\" $Header: XGetSelOwner.d,v 1.2 88/06/11 07:51:28 mento Exp $
  1433. The
  1434. .PN XGetSelectionOwner
  1435. function
  1436. returns the window ID associated with the window that currently owns the
  1437. specified selection.
  1438. If no selection was specified, the function returns the constant
  1439. .PN None .
  1440. If
  1441. .PN None
  1442. is returned,
  1443. there is no owner for the selection.
  1444. .LP
  1445. .PN XGetSelectionOwner
  1446. can generate a
  1447. .PN BadAtom 
  1448. error.
  1449. .LP
  1450. .sp
  1451. To request conversion of a selection, use 
  1452. .PN XConvertSelection .
  1453. .IN "Selection" "converting"
  1454. .IN "XConvertSelection" "" "@DEF@"
  1455. .\" Start marker code here
  1456. .FD 0
  1457. .\" $Header: XConvertSel.f,v 1.1 88/02/26 09:58:58 mento Exp $
  1458. XConvertSelection\^(\^\fIdisplay\fP, \fIselection\fP\^, \fItarget\fP\^, \fIproperty\fP\^, \fIrequestor\fP\^, \fItime\fP\^)
  1459. .br
  1460.       Display *\fIdisplay\fP\^;
  1461. .br
  1462.       Atom \fIselection\fP\^, \fItarget\fP\^;
  1463. .br
  1464.       Atom \fIproperty\fP\^;
  1465. .br
  1466.       Window \fIrequestor\fP\^;
  1467. .br
  1468.       Time \fItime\fP\^;
  1469. .FN
  1470. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  1471. .IP \fIdisplay\fP 1i
  1472. Specifies the connection to the X server.
  1473. .\" $Header: selection.a,v 1.1 88/02/26 10:31:11 mento Exp $
  1474. .IP \fIselection\fP 1i
  1475. Specifies the selection atom.
  1476. .\" $Header: target.a,v 1.1 88/02/26 10:31:37 mento Exp $
  1477. .IP \fItarget\fP 1i
  1478. Specifies the target atom.
  1479. .\" $Header: property.a,v 1.2 88/04/05 15:19:43 mento Exp $
  1480. .IP \fIproperty\fP 1i
  1481. Specifies the property name.
  1482. You also can pass 
  1483. .PN None .
  1484. .\" $Header: requestor.a,v 1.1 88/02/26 10:30:53 mento Exp $
  1485. .IP \fIrequestor\fP 1i
  1486. Specifies the requestor.
  1487. .IP \fItime\fP 1i
  1488. Specifies the time.
  1489. You can pass either a timestamp or
  1490. .PN CurrentTime .
  1491. .\" End marker code here
  1492. .LP
  1493. .\" $Header: XConvertSel.d,v 1.3 88/05/08 12:25:35 mento Exp $
  1494. .PN XConvertSelection
  1495. requests that the specified selection be converted to the specified target
  1496. type:
  1497. .IP \(bu 5
  1498. If the specified selection has an owner, the X server sends a
  1499. .PN SelectionRequest
  1500. event to that owner.
  1501. .IP \(bu 5
  1502. If no owner for the specified
  1503. selection exists, the X server generates a
  1504. .PN SelectionNotify
  1505. event to the
  1506. requestor with property
  1507. .PN None .
  1508. .LP
  1509. The arguments are passed on unchanged in either of the events.
  1510. There are two predefined selection atoms: PRIMARY and SECONDARY.
  1511. .LP
  1512. .PN XConvertSelection
  1513. can generate
  1514. .PN BadAtom
  1515. and
  1516. .PN BadWindow 
  1517. errors.
  1518. .bp
  1519.