home *** CD-ROM | disk | FTP | other *** search
/ InfoMagic Source Code 1993 July / THE_SOURCE_CODE_CD_ROM.iso / X / mit / doc / Xlib / CH02 < prev    next >
Encoding:
Text File  |  1991-08-18  |  43.7 KB  |  1,732 lines
  1. \&
  2. .sp 1
  3. .ce 3
  4. \s+1\fBChapter 2\fP\s-1
  5.  
  6. \s+1\fBDisplay Functions\fP\s-1
  7. .sp 2
  8. .nr H1 2
  9. .nr H2 0
  10. .nr H3 0
  11. .nr H4 0
  12. .nr H5 0
  13. .na
  14. .LP
  15. .XS
  16. Chapter 2: Display Functions
  17. .XE
  18. Before your program can use a display, you must establish a connection
  19. to the X server.
  20. Once you have established a connection,
  21. you then can use the Xlib macros and functions discussed in this chapter
  22. to return information about the display.
  23. This chapter discusses how to:
  24. .IP \(bu 5
  25. Open (connect to) the display
  26. .IP \(bu 5
  27. Obtain information about the display, image format, and screen
  28. .IP \(bu 5
  29. Free client-created data
  30. .IP \(bu 5
  31. Close (disconnect from) a display
  32. .LP
  33. The chapter concludes with a general discussion of what
  34. occurs when the connection to the X server is closed.
  35. .NH 2
  36. Opening the Display
  37. .XS
  38. \*(SN Opening the Display
  39. .XE
  40. .LP
  41. To open a connection to the X server that controls a display, use
  42. .PN XOpenDisplay .
  43. .IN "XOpenDisplay" "" "@DEF@"
  44. .LP
  45. .\" Start marker code here
  46. .FD 0
  47. .\" $Header: XOpenDisplay.f,v 1.1 88/02/26 10:01:40 mento Exp $
  48. Display *XOpenDisplay\^(\^\fIdisplay_name\fP\^)
  49. .br
  50.       char *\fIdisplay_name\fP\^;
  51. .FN    
  52. .\" $Header: display_name.a,v 1.2 88/03/30 14:12:53 mento Exp $
  53. .IP \fIdisplay_name\fP 1i
  54. Specifies the hardware display name, which determines the display
  55. and communications domain to be used.
  56. On a POSIX-conformant system, if the display_name is NULL, 
  57. it defaults to the value of the DISPLAY environment variable. 
  58. .IN "Environment" "DISPLAY"
  59. .\" End marker code here
  60. .LP
  61. The encoding and interpretation of the display name is
  62. implementation dependent.
  63. Strings in the Host Portable Character Encoding are supported;
  64. support for other characters is implementation dependent.
  65. On POSIX-conformant systems,
  66. the display name or DISPLAY environment variable can be a string in the format:
  67. .LP
  68. .\" Start marker code here
  69. .Ds 0
  70. .TA 1i
  71. .ta 1i
  72.     \fIhostname\fP\^:\^\fInumber\fP\^.\^\fIscreen_number\fP
  73. .De
  74. .IP \fIhostname\fP 1i
  75. Specifies the name of the host machine on which the display is physically
  76. attached.
  77. You follow the hostname with either a single colon (:) or a double colon (::).
  78. .IP \fInumber\fP 1i
  79. Specifies the number of the display server on that host machine.
  80. You may optionally follow this display number with a period (.).
  81. A single CPU can have more than one display.
  82. Multiple displays are usually numbered starting with zero.
  83. .IN "Screen"
  84. .IP \fIscreen_number\fP 1i
  85. Specifies the screen to be used on that server.
  86. Multiple screens can be controlled by a single X server.
  87. The screen_number sets an internal variable that can be accessed by
  88. using the 
  89. .PN DefaultScreen 
  90. macro or the 
  91. .PN XDefaultScreen
  92. function if you are using languages other than C (see section 2.2.1).
  93. .\" End marker code here
  94. .LP
  95. For example, the following would specify screen 1 of display 0 on the 
  96. machine named ``dual-headed'':
  97. .LP
  98. .Ds
  99. dual-headed:0.1
  100. .De
  101. .LP
  102. .\" $Header: XOpenDisplay.d,v 1.6 88/08/16 08:38:55 mento Exp $
  103. The
  104. .PN XOpenDisplay
  105. function returns a 
  106. .PN Display 
  107. structure that serves as the
  108. connection to the X server and that contains all the information
  109. about that X server.
  110. .PN XOpenDisplay
  111. connects your application to the X server through TCP 
  112. or DECnet communications protocols,
  113. or through some local inter-process communication protocol.
  114. .IN "Protocol" "TCP"
  115. .IN "Protocol" "DECnet"
  116. If the hostname is a host machine name and a single colon (:)
  117. separates the hostname and display number,
  118. .PN XOpenDisplay
  119. connects using TCP streams.
  120. If the hostname is not specified,
  121. Xlib uses whatever it believes is the fastest transport.
  122. If the hostname is a host machine name and a double colon (::)
  123. separates the hostname and display number,
  124. .PN XOpenDisplay
  125. connects using DECnet.
  126. A single X server can support any or all of these transport mechanisms
  127. simultaneously.
  128. A particular Xlib implementation can support many more of these transport
  129. mechanisms.
  130. .LP
  131. .IN "Display"
  132. If successful, 
  133. .PN XOpenDisplay 
  134. returns a pointer to a 
  135. .PN Display 
  136. structure,
  137. which is defined in 
  138. .Pn < X11/Xlib.h >.
  139. If 
  140. .PN XOpenDisplay 
  141. does not succeed, it returns NULL.
  142. After a successful call to
  143. .PN XOpenDisplay ,
  144. all of the screens in the display can be used by the client.
  145. The screen number specified in the display_name argument is returned 
  146. by the 
  147. .PN DefaultScreen
  148. macro (or the
  149. .PN XDefaultScreen
  150. function).
  151. You can access elements of the
  152. .PN Display
  153. and
  154. .PN Screen
  155. structures only by using the information macros or functions.
  156. For information about using macros and functions to obtain information from 
  157. the
  158. .PN Display 
  159. structure,
  160. see section 2.2.1.
  161. .LP
  162. X servers may implement various types of access control mechanisms
  163. (see section 9.8).
  164. .NH 2
  165. Obtaining Information about the Display, Image Formats, or Screens
  166. .XS
  167. \*(SN Obtaining Information about the Display, Image Formats, or Screens
  168. .XE
  169. .LP
  170. The Xlib library provides a number of useful macros 
  171. and corresponding functions that return data from the 
  172. .PN Display 
  173. structure.
  174. The macros are used for C programming, 
  175. and their corresponding function equivalents are for other language bindings.
  176. This section discusses the:
  177. .IP \(bu 5
  178. Display macros
  179. .IP \(bu 5
  180. Image format macros
  181. .IP \(bu 5
  182. Screen macros
  183. .LP
  184. .IN "Display" "data structure" 
  185. All other members of the 
  186. .PN Display 
  187. structure (that is, those for which no macros are defined) are private to Xlib 
  188. and must not be used.
  189. Applications must never directly modify or inspect these private members of the 
  190. .PN Display 
  191. structure.
  192. .NT Note
  193. The
  194. .PN XDisplayWidth ,
  195. .PN XDisplayHeight ,
  196. .PN XDisplayCells ,
  197. .PN XDisplayPlanes ,
  198. .PN XDisplayWidthMM ,
  199. and
  200. .PN XDisplayHeightMM
  201. functions in the next sections are misnamed.
  202. These functions really should be named Screen\fIwhatever\fP 
  203. and XScreen\fIwhatever\fP, not Display\fIwhatever\fP or XDisplay\fIwhatever\fP.
  204. Our apologies for the resulting confusion.
  205. .NE
  206. .NH 3
  207. Display Macros 
  208. .XS
  209. \*(SN Display Macros
  210. .XE
  211. .LP
  212. Applications should not directly modify any part of the
  213. .PN Display
  214. and
  215. .PN Screen
  216. structures.
  217. The members should be considered read-only,
  218. although they may change as the result of other operations on the display.
  219. .LP 
  220. The following lists the C language macros,
  221. their corresponding function equivalents that are for other language bindings,
  222. and what data they both can return.
  223. .LP
  224. .sp
  225. .\" Start marker code here
  226. .FD 0
  227. AllPlanes
  228. .sp
  229. unsigned long XAllPlanes(\^) 
  230. .FN
  231. .\" End marker code here
  232. .LP
  233. .IN "AllPlanes" "" "@DEF@"
  234. .IN "XAllPlanes" "" "@DEF@"
  235. Both return a value with all bits set to 1 suitable for use in a plane argument to
  236. a procedure.
  237. .LP
  238. .sp
  239. Both 
  240. .PN BlackPixel 
  241. and 
  242. .PN WhitePixel 
  243. can be used in implementing a monochrome application.
  244. These pixel values are for permanently allocated entries in the default
  245. colormap.
  246. The actual RGB (red, green, and blue) values are settable on some screens 
  247. and, in any case, may not actually be black or white.
  248. The names are intended to convey the expected relative intensity of the colors.
  249. .\" Start marker code here
  250. .FD 0
  251. BlackPixel\^(\^\fIdisplay\fP\^, \^\fIscreen_number\fP\^)
  252. .sp
  253. unsigned long XBlackPixel\^(\^\fIdisplay\fP\^, \^\fIscreen_number\fP\^)
  254. .br
  255.       Display *\fIdisplay\fP\^;
  256. .br
  257.       int \fIscreen_number\fP\^;
  258. .FN
  259. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  260. .IP \fIdisplay\fP 1i
  261. Specifies the connection to the X server.
  262. .IP \fIscreen_number\fP 1i
  263. Specifies the appropriate screen number on the host server.
  264. .\" End marker code here
  265. .LP
  266. .IN "BlackPixel" "" "@DEF@"
  267. .IN "XBlackPixel" "" "@DEF@"
  268. Both return the black pixel value for the specified screen.
  269. .LP
  270. .sp
  271. .\" Start marker code here
  272. .FD 0
  273. WhitePixel\^(\^\fIdisplay\fP\^, \^\fIscreen_number\fP\^)
  274. .sp
  275. unsigned long XWhitePixel\^(\^\fIdisplay\fP\^, \^\fIscreen_number\fP\^)
  276. .br
  277.       Display *\fIdisplay\fP\^;
  278. .br
  279.       int \fIscreen_number\fP\^;
  280. .FN
  281. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  282. .IP \fIdisplay\fP 1i
  283. Specifies the connection to the X server.
  284. .IP \fIscreen_number\fP 1i
  285. Specifies the appropriate screen number on the host server.
  286. .\" End marker code here
  287. .LP
  288. .IN "WhitePixel" "" "@DEF@"
  289. .IN "XWhitePixel" "" "@DEF@"
  290. Both return the white pixel value for the specified screen. 
  291. .LP
  292. .sp
  293. .\" Start marker code here
  294. .FD 0
  295. ConnectionNumber\^(\^\fIdisplay\fP\^)
  296. .sp
  297. int XConnectionNumber\^(\^\fIdisplay\fP\^)
  298. .br
  299.       Display *\fIdisplay\fP\^;
  300. .FN
  301. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  302. .IP \fIdisplay\fP 1i
  303. Specifies the connection to the X server.
  304. .\" End marker code here
  305. .LP
  306. .IN "ConnectionNumber" "" "@DEF@"
  307. .IN "XConnectionNumber" "" "@DEF@"
  308. Both return a connection number for the specified display.
  309. On a POSIX-conformant system,
  310. this is the file descriptor of the connection.
  311. .LP
  312. .sp
  313. .\" Start marker code here
  314. .FD 0
  315. DefaultColormap\^(\^\fIdisplay\fP\^, \^\fIscreen_number\fP\^)
  316. .sp
  317. Colormap XDefaultColormap\^(\^\fIdisplay\fP\^, \^\fIscreen_number\fP\^)
  318. .br
  319.       Display *\fIdisplay\fP\^;
  320. .br
  321.       int \fIscreen_number\fP\^;
  322. .FN
  323. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  324. .IP \fIdisplay\fP 1i
  325. Specifies the connection to the X server.
  326. .IP \fIscreen_number\fP 1i
  327. Specifies the appropriate screen number on the host server.
  328. .\" End marker code here
  329. .LP
  330. .IN "DefaultColormap" "" "@DEF@"
  331. .IN "XDefaultColormap" "" "@DEF@"
  332. Both return the default colormap ID for allocation on the specified screen.
  333. Most routine allocations of color should be made out of this colormap.
  334. .LP
  335. .sp
  336. .\" Start marker code here
  337. .FD 0
  338. DefaultDepth\^(\^\fIdisplay\fP\^, \^\fIscreen_number\fP\^)
  339. .sp
  340. int XDefaultDepth\^(\^\fIdisplay\fP\^, \^\fIscreen_number\fP\^)
  341. .br
  342.       Display *\fIdisplay\fP\^;
  343. .br
  344.       int \fIscreen_number\fP\^;
  345. .FN
  346. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  347. .IP \fIdisplay\fP 1i
  348. Specifies the connection to the X server.
  349. .IP \fIscreen_number\fP 1i
  350. Specifies the appropriate screen number on the host server.
  351. .\" End marker code here
  352. .LP
  353. .IN "DefaultDepth" "" "@DEF@"
  354. .IN "XDefaultDepth" "" "@DEF@"
  355. Both return the depth (number of planes) of the default root window for the
  356. specified screen.
  357. Other depths may also be supported on this screen (see
  358. .PN XMatchVisualInfo ).
  359. .LP
  360. .sp
  361. .IN "XListDepths" "" "@DEF@"
  362. To determine the number of depths that are available on a given screen, use
  363. .PN XListDepths .
  364. .\" Start marker code here
  365. .FD 0
  366. int *XListDepths\^(\^\fIdisplay\fP, \fIscreen_number\fP, \fIcount_return\fP\^)
  367. .br
  368.       Display *\fIdisplay\fP;
  369. .br
  370.       int \fIscreen_number\fP;
  371. .br
  372.       int *\fIcount_return\fP;
  373. .FN
  374. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  375. .IP \fIdisplay\fP 1i
  376. Specifies the connection to the X server.
  377. .IP \fIscreen_number\fP 1i
  378. Specifies the appropriate screen number on the host server.
  379. .ds Cn depths
  380. .IP \fIcount_return\fP 1i
  381. Returns the number of \*(Cn.
  382. .\" End marker code here
  383. .LP
  384. The
  385. .PN XListDepths
  386. function returns the array of depths 
  387. that are available on the specified screen.
  388. If the specified screen_number is valid and sufficient memory for the array
  389. can be allocated,
  390. .PN XListDepths
  391. sets count_return to the number of available depths.
  392. Otherwise, it does not set count_return and returns NULL.
  393. To release the memory allocated for the array of depths, use
  394. .PN XFree .
  395. .LP
  396. .sp
  397. .\" Start marker code here
  398. .FD 0
  399. DefaultGC\^(\^\fIdisplay\fP\^, \^\fIscreen_number\fP\^)
  400. .sp
  401. GC XDefaultGC\^(\^\fIdisplay\fP\^, \^\fIscreen_number\fP\^)
  402. .br
  403.       Display *\fIdisplay\fP\^;
  404. .br
  405.       int \fIscreen_number\fP\^;
  406. .FN
  407. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  408. .IP \fIdisplay\fP 1i
  409. Specifies the connection to the X server.
  410. .IP \fIscreen_number\fP 1i
  411. Specifies the appropriate screen number on the host server.
  412. .\" End marker code here
  413. .LP
  414. .IN "DefaultGC" "" "@DEF@"
  415. .IN "XDefaultGC" "" "@DEF@"
  416. Both return the default graphics context for the root window of the 
  417. specified screen.
  418. This GC is created for the convenience of simple applications
  419. and contains the default GC components with the foreground and
  420. background pixel values initialized to the black and white
  421. pixels for the screen, respectively.
  422. You can modify its contents freely because it is not used in any Xlib
  423. function.
  424. This GC should never be freed.
  425. .LP
  426. .sp
  427. .\" Start marker code here
  428. .FD 0
  429. DefaultRootWindow\^(\^\fIdisplay\fP\^)
  430. .sp
  431. Window XDefaultRootWindow\^(\^\fIdisplay\fP\^)
  432. .br
  433.       Display *\fIdisplay\fP\^;
  434. .FN
  435. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  436. .IP \fIdisplay\fP 1i
  437. Specifies the connection to the X server.
  438. .\" End marker code here
  439. .LP
  440. .IN "DefaultRootWindow" "" "@DEF@"
  441. .IN "XDefaultRootWindow" "" "@DEF@"
  442. Both return the root window for the default screen.
  443. .LP
  444. .sp
  445. .\" Start marker code here
  446. .FD 0
  447. DefaultScreenOfDisplay\^(\^\fIdisplay\fP\^)
  448. .sp
  449. Screen *XDefaultScreenOfDisplay\^(\^\fIdisplay\fP\^)
  450. .br
  451.       Display *\fIdisplay\fP\^;
  452. .FN
  453. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  454. .IP \fIdisplay\fP 1i
  455. Specifies the connection to the X server.
  456. .\" End marker code here
  457. .LP
  458. .IN "DefaultScreenOfDisplay" "" "@DEF@"
  459. .IN "XDefaultScreenOfDisplay" "" "@DEF@"
  460. Both return a pointer to the default screen.
  461. .LP
  462. .sp
  463. .\" Start marker code here
  464. .FD 0
  465. ScreenOfDisplay\^(\^\fIdisplay\fP, \fIscreen_number\fP\^)
  466. .sp
  467. Screen *XScreenOfDisplay\^(\^\fIdisplay\fP, \fIscreen_number\fP\^)
  468. .br
  469.       Display *\fIdisplay\fP\^;
  470. .br
  471.       int \fIscreen_number\fP\^;
  472. .FN
  473. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  474. .IP \fIdisplay\fP 1i
  475. Specifies the connection to the X server.
  476. .IP \fIscreen_number\fP 1i
  477. Specifies the appropriate screen number on the host server.
  478. .\" End marker code here
  479. .LP
  480. .IN "ScreenOfDisplay" "" "@DEF@"
  481. .IN "XScreenOfDisplay" "" "@DEF@"
  482. Both return a pointer to the indicated screen.
  483. .LP
  484. .sp
  485. .\" Start marker code here
  486. .FD 0
  487. DefaultScreen\^(\^\fIdisplay\fP\^)
  488. .sp
  489. int XDefaultScreen\^(\^\fIdisplay\fP\^)
  490. .br
  491.       Display *\fIdisplay\fP\^;
  492. .FN
  493. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  494. .IP \fIdisplay\fP 1i
  495. Specifies the connection to the X server.
  496. .\" End marker code here
  497. .LP
  498. .IN "DefaultScreen" "" "@DEF@"
  499. .IN "XDefaultScreen" "" "@DEF@"
  500. Both return the default screen number referenced by the 
  501. .PN XOpenDisplay
  502. function. 
  503. This macro or function should be used to retrieve the screen number 
  504. in applications that will use only a single screen.
  505. .LP
  506. .sp
  507. .\" Start marker code here
  508. .FD 0
  509. DefaultVisual\^(\^\fIdisplay\fP\^, \^\fIscreen_number\fP\^)
  510. .sp
  511. Visual *XDefaultVisual\^(\^\fIdisplay\fP\^, \^\fIscreen_number\fP\^)
  512. .br
  513.       Display *\fIdisplay\fP\^;
  514. .br
  515.       int \fIscreen_number\fP\^;
  516. .FN
  517. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  518. .IP \fIdisplay\fP 1i
  519. Specifies the connection to the X server.
  520. .IP \fIscreen_number\fP 1i
  521. Specifies the appropriate screen number on the host server.
  522. .\" End marker code here
  523. .LP
  524. .IN "DefaultVisual" "" "@DEF@"
  525. .IN "XDefaultVisual" "" "@DEF@"
  526. Both return the default visual type for the specified screen.
  527. For further information about visual types,
  528. see section 3.1.
  529. .LP
  530. .sp
  531. .\" Start marker code here
  532. .FD 0
  533. DisplayCells\^(\^\fIdisplay\fP\^, \^\fIscreen_number\fP\^)
  534. .sp
  535. int XDisplayCells\^(\^\fIdisplay\fP\^, \^\fIscreen_number\fP\^)
  536. .br
  537.       Display *\fIdisplay\fP\^;
  538. .br
  539.       int \fIscreen_number\fP\^;
  540. .FN
  541. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  542. .IP \fIdisplay\fP 1i
  543. Specifies the connection to the X server.
  544. .IP \fIscreen_number\fP 1i
  545. Specifies the appropriate screen number on the host server.
  546. .\" End marker code here
  547. .LP
  548. .IN "DisplayCells" "" "@DEF@"
  549. .IN "XDisplayCells" "" "@DEF@"
  550. Both return the number of entries in the default colormap.
  551. .LP
  552. .sp
  553. .\" Start marker code here
  554. .FD 0
  555. DisplayPlanes\^(\^\fIdisplay\fP\^, \^\fIscreen_number\fP\^)
  556. .sp
  557. int XDisplayPlanes\^(\^\fIdisplay\fP\^, \^\fIscreen_number\fP\^)
  558. .br
  559.       Display *\fIdisplay\fP\^;
  560. .br
  561.       int \fIscreen_number\fP\^;
  562. .FN
  563. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  564. .IP \fIdisplay\fP 1i
  565. Specifies the connection to the X server.
  566. .IP \fIscreen_number\fP 1i
  567. Specifies the appropriate screen number on the host server.
  568. .\" End marker code here
  569. .LP
  570. .IN "DisplayPlanes" "" "@DEF@"
  571. .IN "XDisplayPlanes" "" "@DEF@"
  572. Both return the depth of the root window of the specified screen.
  573. For an explanation of depth,
  574. see the glossary.
  575. .LP
  576. .sp
  577. .\" Start marker code here
  578. .FD 0
  579. DisplayString\^(\^\fIdisplay\fP\^)
  580. .sp
  581. char *XDisplayString\^(\^\fIdisplay\fP\^)
  582. .br
  583.       Display *\fIdisplay\fP\^;
  584. .FN
  585. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  586. .IP \fIdisplay\fP 1i
  587. Specifies the connection to the X server.
  588. .\" End marker code here
  589. .LP
  590. .IN "DisplayString" "" "@DEF@"
  591. .IN "XDisplayString" "" "@DEF@"
  592. Both return the string that was passed to 
  593. .PN XOpenDisplay
  594. when the current display was opened. 
  595. On POSIX-conformant systems, 
  596. if the passed string was NULL, these return the value of
  597. the DISPLAY environment variable when the current display was opened.
  598. .IN "POSIX System Call" "fork"
  599. These are useful to applications that invoke the 
  600. .PN fork
  601. system call and want to open a new connection to the same display from the 
  602. child process as well as for printing error messages.
  603. .LP
  604. .sp
  605. .\" Start marker code here
  606. .FD 0
  607. long XMaxRequestSize(\^\fIdisplay\fP\^)
  608.     Display *\fIdisplay\fP\^;
  609. .FN
  610. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  611. .IP \fIdisplay\fP 1i
  612. Specifies the connection to the X server.
  613. .\" End marker code here
  614. .IN "XMaxRequestSize" "" "@DEF@"
  615. .LP
  616. .PN XMaxRequestSize
  617. returns the maximum request size (in 4-byte units) supported by the server.
  618. Single protocol requests to the server can be no longer than this size.
  619. The protocol guarantees the size to be no smaller than 4096 units
  620. (16384 bytes).
  621. Xlib automatically breaks data up into multiple protocol requests
  622. as necessary for the following functions:
  623. .PN XDrawPoints ,
  624. .PN XDrawRectangles ,
  625. .PN XDrawSegments ,
  626. .PN XFillArcs ,
  627. .PN XFillRectangles ,
  628. and 
  629. .PN XPutImage .
  630. .LP
  631. .sp
  632. .\" Start marker code here
  633. .FD 0
  634. LastKnownRequestProcessed\^(\^\fIdisplay\fP\^)
  635. .sp
  636. unsigned long XLastKnownRequestProcessed\^(\^\fIdisplay\fP\^)
  637. .br
  638.      Display *\fIdisplay\fP\^;
  639. .FN
  640. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  641. .IP \fIdisplay\fP 1i
  642. Specifies the connection to the X server.
  643. .\" End marker code here
  644. .IN "LastKnownRequestProcessed" "" "@DEF@"
  645. .IN "XLastKnownRequestProcessed" "" "@DEF@"
  646. .LP
  647. Both extract the full serial number of the last request known by Xlib
  648. to have been processed by the X server.
  649. Xlib automatically sets this number when replies, events, and errors
  650. are received.
  651. .LP
  652. .sp
  653. .\" Start marker code here
  654. .FD 0
  655. NextRequest\^(\^\fIdisplay\fP\^)
  656. .sp
  657. unsigned long XNextRequest\^(\^\fIdisplay\fP\^)
  658. .br
  659.      Display *\fIdisplay\fP\^;
  660. .FN
  661. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  662. .IP \fIdisplay\fP 1i
  663. Specifies the connection to the X server.
  664. .\" End marker code here
  665. .IN "NextRequest" "" "@DEF@"
  666. .IN "XNextRequest" "" "@DEF@"
  667. .LP
  668. Both extract the full serial number that is to be used for the next
  669. request.
  670. Serial numbers are maintained separately for each display connection.
  671. .LP
  672. .sp
  673. .\" Start marker code here
  674. .FD 0
  675. ProtocolVersion\^(\^\fIdisplay\fP\^)
  676. .sp
  677. int XProtocolVersion\^(\^\fIdisplay\fP\^)
  678. .br
  679.       Display *\fIdisplay\fP\^;
  680. .FN
  681. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  682. .IP \fIdisplay\fP 1i
  683. Specifies the connection to the X server.
  684. .\" End marker code here
  685. .LP
  686. .IN "ProtocolVersion" "" "@DEF@"
  687. .IN "XProtocolVersion" "" "@DEF@"
  688. Both return the major version number (11) of the X protocol associated with 
  689. the connected display.
  690. .LP
  691. .sp
  692. .\" Start marker code here
  693. .FD 0
  694. ProtocolRevision\^(\^\fIdisplay\fP\^)
  695. .sp
  696. int XProtocolRevision\^(\^\fIdisplay\fP\^)
  697. .br
  698.       Display *\fIdisplay\fP\^;
  699. .FN
  700. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  701. .IP \fIdisplay\fP 1i
  702. Specifies the connection to the X server.
  703. .\" End marker code here
  704. .LP
  705. .IN "ProtocolRevision" "" "@DEF@"
  706. .IN "XProtocolRevision" "" "@DEF@"
  707. Both return the minor protocol revision number of the X server.
  708. .LP
  709. .sp
  710. .\" Start marker code here
  711. .FD 0
  712. QLength\^(\^\fIdisplay\fP\^)
  713. .sp
  714. int XQLength\^(\^\fIdisplay\fP\^)
  715. .br
  716.       Display *\fIdisplay\fP\^;
  717. .FN
  718. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  719. .IP \fIdisplay\fP 1i
  720. Specifies the connection to the X server.
  721. .\" End marker code here
  722. .LP
  723. .IN "QLength" "" "@DEF@"
  724. .IN "XQLength" "" "@DEF@"
  725. Both return the length of the event queue for the connected display.
  726. Note that there may be more events that have not been read into
  727. the queue yet (see
  728. .PN XEventsQueued ).
  729. .LP
  730. .sp
  731. .\" Start marker code here
  732. .FD 0
  733. RootWindow\^(\^\fIdisplay\fP\^, \^\fIscreen_number\fP\^)
  734. .sp
  735. Window XRootWindow\^(\^\fIdisplay\fP\^, \^\fIscreen_number\fP\^)
  736. .br
  737.       Display *\fIdisplay\fP\^;
  738. .br
  739.       int \fIscreen_number\fP\^;
  740. .FN
  741. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  742. .IP \fIdisplay\fP 1i
  743. Specifies the connection to the X server.
  744. .IP \fIscreen_number\fP 1i
  745. Specifies the appropriate screen number on the host server.
  746. .\" End marker code here
  747. .LP
  748. .IN "Window" "RootWindow"
  749. .IN "RootWindow" "" "@DEF@"
  750. .IN "Window" "XRootWindow"
  751. .IN "XRootWindow" "" "@DEF@"
  752. Both return the root window.
  753. These are useful with functions that need a drawable of a particular screen
  754. and for creating top-level windows.
  755. .LP
  756. .sp
  757. .\" Start marker code here
  758. .FD 0
  759. ScreenCount\^(\^\fIdisplay\fP\^)
  760. .sp
  761. int XScreenCount\^(\^\fIdisplay\fP\^)
  762. .br
  763.       Display *\fIdisplay\fP\^;
  764. .FN
  765. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  766. .IP \fIdisplay\fP 1i
  767. Specifies the connection to the X server.
  768. .\" End marker code here
  769. .LP
  770. .IN "ScreenCount" "" "@DEF@"
  771. .IN "XScreenCount" "" "@DEF@"
  772. Both return the number of available screens.
  773. .LP
  774. .sp
  775. .\" Start marker code here
  776. .FD 0
  777. ServerVendor\^(\^\fIdisplay\fP\^)
  778. .sp
  779. char *XServerVendor\^(\^\fIdisplay\fP\^)
  780. .br
  781.       Display *\fIdisplay\fP\^;
  782. .FN
  783. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  784. .IP \fIdisplay\fP 1i
  785. Specifies the connection to the X server.
  786. .\" End marker code here
  787. .LP
  788. .IN "ServerVendor" "" "@DEF@"
  789. .IN "XServerVendor" "" "@DEF@"
  790. Both return a pointer to a null-terminated string that provides
  791. some identification of the owner of the X server implementation.
  792. If the data returned by the server is in the Latin Portable Character Encoding,
  793. then the string is in the Host Portable Character Encoding.
  794. Otherwise, the contents of the string are implementation dependent.
  795. .LP
  796. .sp
  797. .\" Start marker code here
  798. .FD 0
  799. VendorRelease\^(\^\fIdisplay\fP\^)
  800. .sp
  801. int XVendorRelease\^(\^\fIdisplay\fP\^)
  802. .br
  803.       Display *\fIdisplay\fP\^;
  804. .FN
  805. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  806. .IP \fIdisplay\fP 1i
  807. Specifies the connection to the X server.
  808. .\" End marker code here
  809. .LP
  810. .IN "VendorRelease" "" "@DEF@"
  811. .IN "XVendorRelease" "" "@DEF@"
  812. Both return a number related to a vendor's release of the X server.
  813. .NH 3
  814. Image Format Functions and Macros
  815. .XS
  816. \*(SN Image Format Functions and Macros
  817. .XE
  818. .LP
  819. Applications are required to present data to the X server
  820. in a format that the server demands.
  821. To help simplify applications,
  822. most of the work required to convert the data is provided by Xlib
  823. (see sections 8.7 and 16.8).
  824. .LP
  825. The
  826. .PN XPixmapFormatValues
  827. structure provides an interface to the pixmap format information
  828. that is returned at the time of a connection setup.
  829. It contains:
  830. .LP
  831. .\" Start marker code here
  832. .Ds 0
  833. .TA .5i 3i
  834. .ta .5i 3i
  835. typedef struct {
  836.     int depth;
  837.     int bits_per_pixel;
  838.     int scanline_pad;
  839. } XPixmapFormatValues;
  840. .De
  841. .\" End marker code here
  842. .sp
  843. .LP
  844. To obtain the pixmap format information for a given display, use
  845. .PN XListPixmapFormats .
  846. .IN "XListPixmapFormats" "" "@DEF@"
  847. .\" Start marker code here
  848. .FD 0
  849. XPixmapFormatValues *XListPixmapFormats\^(\^\fIdisplay\fP, \fIcount_return\fP\^)
  850. .br
  851.       Display *\fIdisplay\fP\^;
  852. .br
  853.       int *\fIcount_return\fP\^;
  854. .FN
  855. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  856. .IP \fIdisplay\fP 1i
  857. Specifies the connection to the X server.
  858. .ds Cn pixmap formats that are supported by the display
  859. .IP \fIcount_return\fP 1i
  860. Returns the number of \*(Cn.
  861. .\" End marker code here
  862. .LP
  863. The
  864. .PN XListPixmapFormats
  865. function returns an array of
  866. .PN XPixmapFormatValues
  867. structures that describe the types of Z format images supported
  868. by the specified display.
  869. If insufficient memory is available,
  870. .PN XListPixmapFormats
  871. returns NULL.
  872. To free the allocated storage for the
  873. .PN XPixmapFormatValues
  874. structures, use
  875. .PN XFree .
  876. .LP 
  877. The following lists the C language macros,
  878. their corresponding function equivalents that are for other language bindings,
  879. and what data they both return for the specified server and screen.
  880. These are often used by toolkits as well as by simple applications.
  881. .LP
  882. .sp
  883. .\" Start marker code here
  884. .FD 0
  885. ImageByteOrder\^(\^\fIdisplay\fP\^)
  886. .sp
  887. int XImageByteOrder\^(\^\fIdisplay\fP\^)
  888. .br
  889.       Display *\fIdisplay\fP\^;
  890. .FN
  891. .\" End marker code here
  892. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  893. .IP \fIdisplay\fP 1i
  894. Specifies the connection to the X server.
  895. .LP
  896. .IN "ImageByteOrder" "" "@DEF@"
  897. .IN "XImageByteOrder" "" "@DEF@"
  898. Both specify the required byte order for images for each scanline unit in 
  899. XY format (bitmap) or for each pixel value in 
  900. Z format.
  901. The macro or function can return either
  902. .PN LSBFirst 
  903. or 
  904. .PN MSBFirst .
  905. .LP
  906. .sp
  907. .\" Start marker code here
  908. .FD 0
  909. BitmapUnit\^(\^\fIdisplay\fP\^)
  910. .sp
  911. int XBitmapUnit\^(\^\fIdisplay\fP\^)
  912. .br
  913.       Display *\fIdisplay\fP\^;
  914. .FN
  915. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  916. .IP \fIdisplay\fP 1i
  917. Specifies the connection to the X server.
  918. .\" End marker code here
  919. .LP
  920. .IN "BitmapUnit" "" "@DEF@"
  921. .IN "XBitmapUnit" "" "@DEF@"
  922. Both return the size of a bitmap's scanline unit in bits.
  923. The scanline is calculated in multiples of this value.
  924. .LP
  925. .sp
  926. .\" Start marker code here
  927. .FD 0
  928. BitmapBitOrder\^(\^\fIdisplay\fP\^)
  929. .sp
  930. int XBitmapBitOrder\^(\^\fIdisplay\fP\^)
  931. .br
  932.       Display *\fIdisplay\fP\^;
  933. .FN
  934. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  935. .IP \fIdisplay\fP 1i
  936. Specifies the connection to the X server.
  937. .\" End marker code here
  938. .LP
  939. .IN "BitmapBitOrder" "" "@DEF@"
  940. .IN "XBitmapBitOrder" "" "@DEF@"
  941. Within each bitmap unit, the left-most bit in the bitmap as displayed
  942. on the screen is either the least-significant or most-significant bit in the
  943. unit.
  944. This macro or function can return 
  945. .PN LSBFirst
  946. or 
  947. .PN MSBFirst .
  948. .LP
  949. .sp
  950. .\" Start marker code here
  951. .FD 0
  952. BitmapPad\^(\^\fIdisplay\fP\^)
  953. .sp
  954. int XBitmapPad\^(\^\fIdisplay\fP\^)
  955. .br
  956.       Display *\fIdisplay\fP\^;
  957. .FN
  958. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  959. .IP \fIdisplay\fP 1i
  960. Specifies the connection to the X server.
  961. .\" End marker code here
  962. .LP
  963. .IN "BitmapPad" "" "@DEF@"
  964. .IN "XBitmapPad" "" "@DEF@"
  965. Each scanline must be padded to a multiple of bits returned
  966. by this macro or function.
  967. .LP
  968. .sp
  969. .\" Start marker code here
  970. .FD 0
  971. DisplayHeight\^(\^\fIdisplay\fP\^, \^\fIscreen_number\fP\^)
  972. .sp
  973. int XDisplayHeight\^(\^\fIdisplay\fP\^, \^\fIscreen_number\fP\^)
  974. .br
  975.       Display *\fIdisplay\fP\^;
  976. .br
  977.       int \fIscreen_number\fP\^;
  978. .FN
  979. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  980. .IP \fIdisplay\fP 1i
  981. Specifies the connection to the X server.
  982. .IP \fIscreen_number\fP 1i
  983. Specifies the appropriate screen number on the host server.
  984. .\" End marker code here
  985. .LP
  986. .IN "DisplayHeight" "" "@DEF@"
  987. .IN "XDisplayHeight" "" "@DEF@"
  988. Both return an integer that describes the height of the screen
  989. in pixels.
  990. .LP
  991. .sp
  992. .\" Start marker code here
  993. .FD 0
  994. DisplayHeightMM\^(\^\fIdisplay\fP\^, \^\fIscreen_number\fP\^)
  995. .sp
  996. int XDisplayHeightMM\^(\^\fIdisplay\fP\^, \^\fIscreen_number\fP\^)
  997. .br
  998.       Display *\fIdisplay\fP\^;
  999. .br
  1000.       int \fIscreen_number\fP\^;
  1001. .FN
  1002. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  1003. .IP \fIdisplay\fP 1i
  1004. Specifies the connection to the X server.
  1005. .IP \fIscreen_number\fP 1i
  1006. Specifies the appropriate screen number on the host server.
  1007. .\" End marker code here
  1008. .LP
  1009. .IN "DisplayHeightMM" "" "@DEF@"
  1010. .IN "XDisplayHeightMM" "" "@DEF@"
  1011. Both return the height of the specified screen in millimeters.
  1012. .LP
  1013. .sp
  1014. .\" Start marker code here
  1015. .FD 0
  1016. DisplayWidth\^(\^\fIdisplay\fP\^, \^\fIscreen_number\fP\^)
  1017. .sp
  1018. int XDisplayWidth\^(\^\fIdisplay\fP\^, \^\fIscreen_number\fP\^)
  1019. .br
  1020.       Display *\fIdisplay\fP\^;
  1021. .br
  1022.       int \fIscreen_number\fP\^;
  1023. .FN
  1024. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  1025. .IP \fIdisplay\fP 1i
  1026. Specifies the connection to the X server.
  1027. .IP \fIscreen_number\fP 1i
  1028. Specifies the appropriate screen number on the host server.
  1029. .\" End marker code here
  1030. .LP
  1031. .IN "DisplayWidth" "" "@DEF@"
  1032. .IN "XDisplayWidth" "" "@DEF@"
  1033. Both return the width of the screen in pixels.
  1034. .LP
  1035. .sp
  1036. .\" Start marker code here
  1037. .FD 0
  1038. DisplayWidthMM\^(\^\fIdisplay\fP\^, \^\fIscreen_number\fP\^)
  1039. .sp
  1040. int XDisplayWidthMM\^(\^\fIdisplay\fP\^, \^\fIscreen_number\fP\^)
  1041. .br
  1042.       Display *\fIdisplay\fP\^;
  1043. .br
  1044.       int \fIscreen_number\fP\^;
  1045. .FN
  1046. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  1047. .IP \fIdisplay\fP 1i
  1048. Specifies the connection to the X server.
  1049. .IP \fIscreen_number\fP 1i
  1050. Specifies the appropriate screen number on the host server.
  1051. .\" End marker code here
  1052. .LP
  1053. .IN "DisplayWidthMM" "" "@DEF@"
  1054. .IN "XDisplayWidthMM" "" "@DEF@"
  1055. Both return the width of the specified screen in millimeters.
  1056. .NH 3
  1057. Screen Information Macros
  1058. .XS
  1059. \*(SN Screen Information Macros
  1060. .XE
  1061. .LP
  1062. The following lists the C language macros,
  1063. their corresponding function equivalents that are for other language bindings,
  1064. and what data they both can return.
  1065. These macros or functions all take a pointer to the appropriate screen
  1066. structure.
  1067. .LP
  1068. .sp
  1069. .\" Start marker code here
  1070. .FD 0
  1071. BlackPixelOfScreen\^(\^\fIscreen\fP\^)
  1072. .sp
  1073. unsigned long XBlackPixelOfScreen\^(\^\fIscreen\fP\^)
  1074. .br
  1075.       Screen *\fIscreen\fP\^;
  1076. .FN
  1077. .IP \fIscreen\fP 1i
  1078. Specifies the appropriate 
  1079. .PN Screen
  1080. structure.
  1081. .\" End marker code here
  1082. .LP
  1083. .IN "BlackPixelOfScreen" "" "@DEF@"
  1084. .IN "XBlackPixelOfScreen" "" "@DEF@"
  1085. Both return the black pixel value of the specified screen.
  1086. .LP
  1087. .sp
  1088. .\" Start marker code here
  1089. .FD 0
  1090. WhitePixelOfScreen\^(\^\fIscreen\fP\^)
  1091. .sp
  1092. unsigned long XWhitePixelOfScreen\^(\^\fIscreen\fP\^)
  1093. .br
  1094.       Screen *\fIscreen\fP\^;
  1095. .FN
  1096. .IP \fIscreen\fP 1i
  1097. Specifies the appropriate 
  1098. .PN Screen
  1099. structure.
  1100. .\" End marker code here
  1101. .IN "WhitePixelOfScreen" "" "@DEF@"
  1102. .IN "XWhitePixelOfScreen" "" "@DEF@"
  1103. .LP
  1104. Both return the white pixel value of the specified screen.
  1105. .LP
  1106. .sp
  1107. .\" Start marker code here
  1108. .FD 0
  1109. CellsOfScreen\^(\^\fIscreen\fP\^)
  1110. .sp
  1111. int XCellsOfScreen\^(\^\fIscreen\fP\^)
  1112. .br
  1113.       Screen *\fIscreen\fP\^;
  1114. .FN
  1115. .IP \fIscreen\fP 1i
  1116. Specifies the appropriate 
  1117. .PN Screen
  1118. structure.
  1119. .\" End marker code here
  1120. .LP
  1121. .IN "CellsOfScreen" "" "@DEF@"
  1122. .IN "XCellsOfScreen" "" "@DEF@"
  1123. Both return the number of colormap cells in the default colormap 
  1124. of the specified screen.
  1125. .LP
  1126. .sp
  1127. .\" Start marker code here
  1128. .FD 0
  1129. DefaultColormapOfScreen\^(\^\fIscreen\fP\^)
  1130. .sp
  1131. Colormap XDefaultColormapOfScreen\^(\^\fIscreen\fP\^)
  1132. .br
  1133.       Screen *\fIscreen\fP\^;
  1134. .FN
  1135. .IP \fIscreen\fP 1i
  1136. Specifies the appropriate 
  1137. .PN Screen
  1138. structure.
  1139. .\" End marker code here
  1140. .LP
  1141. .IN "DefaultColormapOfScreen" "" "@DEF@"
  1142. .IN "XDefaultColormapOfScreen" "" "@DEF@"
  1143. Both return the default colormap of the specified screen.
  1144. .LP
  1145. .sp
  1146. .\" Start marker code here
  1147. .FD 0
  1148. DefaultDepthOfScreen\^(\^\fIscreen\fP\^)
  1149. .sp 
  1150. int XDefaultDepthOfScreen\^(\^\fIscreen\fP\^)
  1151. .br
  1152.       Screen *\fIscreen\fP\^;
  1153. .FN
  1154. .IP \fIscreen\fP 1i
  1155. Specifies the appropriate 
  1156. .PN Screen
  1157. structure.
  1158. .\" End marker code here
  1159. .LP
  1160. .IN "DefaultDepthOfScreen" "" "@DEF@"
  1161. .IN "XDefaultDepthOfScreen" "" "@DEF@"
  1162. Both return the depth of the root window.
  1163. .LP
  1164. .sp
  1165. .\" Start marker code here
  1166. .FD 0
  1167. DefaultGCOfScreen\^(\^\fIscreen\fP\^)
  1168. .sp
  1169. GC XDefaultGCOfScreen\^(\^\fIscreen\fP\^)
  1170. .br
  1171.       Screen *\fIscreen\fP\^;
  1172. .FN
  1173. .IP \fIscreen\fP 1i
  1174. Specifies the appropriate 
  1175. .PN Screen
  1176. structure.
  1177. .\" End marker code here
  1178. .LP
  1179. .IN "DefaultGCOfScreen" "" "@DEF@"
  1180. .IN "XDefaultGCOfScreen" "" "@DEF@"
  1181. Both return a default graphics context (GC) of the specified screen,
  1182. which has the same depth as the root window of the screen.
  1183. The GC must never be freed.
  1184. .LP
  1185. .sp
  1186. .\" Start marker code here
  1187. .FD 0
  1188. DefaultVisualOfScreen\^(\^\fIscreen\fP\^)
  1189. .sp
  1190. Visual *XDefaultVisualOfScreen\^(\^\fIscreen\fP\^)
  1191. .br
  1192.       Screen *\fIscreen\fP\^;
  1193. .FN
  1194. .IP \fIscreen\fP 1i
  1195. Specifies the appropriate 
  1196. .PN Screen
  1197. structure.
  1198. .\" End marker code here
  1199. .LP
  1200. .IN "DefaultVisualOfScreen" "" "@DEF@"
  1201. .IN "XDefaultVisualOfScreen" "" "@DEF@"
  1202. Both return the default visual of the specified screen.
  1203. For information on visual types,
  1204. see section 3.1.
  1205. .LP
  1206. .sp
  1207. .\" Start marker code here
  1208. .FD 0
  1209. DoesBackingStore\^(\^\fIscreen\fP\^)
  1210. .sp
  1211. int XDoesBackingStore\^(\^\fIscreen\fP\^)
  1212. .br
  1213.       Screen *\fIscreen\fP\^;
  1214. .FN
  1215. .IP \fIscreen\fP 1i
  1216. Specifies the appropriate 
  1217. .PN Screen
  1218. structure.
  1219. .\" End marker code here
  1220. .LP
  1221. .IN "DoesBackingStore" "" "@DEF@"
  1222. .IN "XDoesBackingStore" "" "@DEF@"
  1223. Both return a value indicating whether the screen supports backing
  1224. stores.
  1225. The value returned can be one of 
  1226. .PN WhenMapped ,
  1227. .PN NotUseful ,
  1228. or
  1229. .PN Always 
  1230. (see section 3.2.4).
  1231. .LP
  1232. .sp
  1233. .\" Start marker code here
  1234. .FD 0
  1235. DoesSaveUnders\^(\^\fIscreen\fP\^)
  1236. .sp
  1237. Bool XDoesSaveUnders\^(\^\fIscreen\fP\^)
  1238. .br
  1239.       Screen *\fIscreen\fP\^;
  1240. .FN
  1241. .IP \fIscreen\fP 1i
  1242. Specifies the appropriate 
  1243. .PN Screen
  1244. structure.
  1245. .\" End marker code here
  1246. .LP
  1247. .IN "DoesSaveUnders" "" "@DEF@"
  1248. .IN "XDoesSaveUnders" "" "@DEF@"
  1249. Both return a Boolean value indicating whether the
  1250. screen supports save unders.
  1251. If
  1252. .PN True ,
  1253. the screen supports save unders.
  1254. If
  1255. .PN False ,
  1256. the screen does not support save unders (see section 3.2.5).
  1257. .LP
  1258. .sp
  1259. .\" Start marker code here
  1260. .FD 0
  1261. DisplayOfScreen\^(\^\fIscreen\fP\^)
  1262. .sp
  1263. Display *XDisplayOfScreen\^(\^\fIscreen\fP\^)
  1264. .br
  1265.       Screen *\fIscreen\fP\^;
  1266. .FN
  1267. .IP \fIscreen\fP 1i
  1268. Specifies the appropriate 
  1269. .PN Screen
  1270. structure.
  1271. .\" End marker code here
  1272. .LP
  1273. .IN "DisplayOfScreen" "" "@DEF@"
  1274. .IN "XDisplayOfScreen" "" "@DEF@"
  1275. Both return the display of the specified screen.
  1276. .LP
  1277. .sp
  1278. .\" Start marker code here
  1279. .IN "XScreenNumberOfScreen" "" "@DEF@"
  1280. .FD 0
  1281. int XScreenNumberOfScreen\^(\^\fIscreen\fP\^)
  1282. .br
  1283.       Screen *\fIscreen\fP\^;
  1284. .FN
  1285. .IP \fIscreen\fP 1i
  1286. Specifies the appropriate 
  1287. .PN Screen
  1288. structure.
  1289. .\" End marker code here
  1290. .LP
  1291. The
  1292. .PN XScreenNumberOfScreen
  1293. function returns the screen index number of the specified screen.
  1294. .LP
  1295. .sp
  1296. .\" Start marker code here
  1297. .FD 0
  1298. EventMaskOfScreen\^(\^\fIscreen\fP\^)
  1299. .sp
  1300. long XEventMaskOfScreen\^(\^\fIscreen\fP\^)
  1301. .br
  1302.       Screen *\fIscreen\fP\^;
  1303. .FN
  1304. .IP \fIscreen\fP 1i
  1305. Specifies the appropriate 
  1306. .PN Screen
  1307. structure.
  1308. .\" End marker code here
  1309. .LP
  1310. .IN "EventMaskOfScreen" "" "@DEF@"
  1311. .IN "XEventMaskOfScreen" "" "@DEF@"
  1312. Both return the event mask of the root window for the specified screen
  1313. at connection setup time.
  1314. .LP
  1315. .sp
  1316. .\" Start marker code here
  1317. .FD 0
  1318. WidthOfScreen\^(\^\fIscreen\fP\^)
  1319. .sp
  1320. int XWidthOfScreen\^(\^\fIscreen\fP\^)
  1321. .br
  1322.       Screen *\fIscreen\fP\^;
  1323. .FN
  1324. .IP \fIscreen\fP 1i
  1325. Specifies the appropriate 
  1326. .PN Screen
  1327. structure.
  1328. .\" End marker code here
  1329. .LP
  1330. .IN "WidthOfScreen" "" "@DEF@"
  1331. .IN "XWidthOfScreen" "" "@DEF@"
  1332. Both return the width of the specified screen in pixels.
  1333. .LP
  1334. .sp
  1335. .\" Start marker code here
  1336. .FD 0
  1337. HeightOfScreen\^(\^\fIscreen\fP\^)
  1338. .sp
  1339. int XHeightOfScreen\^(\^\fIscreen\fP\^)
  1340. .br
  1341.       Screen *\fIscreen\fP\^;
  1342. .FN
  1343. .IP \fIscreen\fP 1i
  1344. Specifies the appropriate 
  1345. .PN Screen
  1346. structure.
  1347. .\" End marker code here
  1348. .LP
  1349. .IN "HeightOfScreen" "" "@DEF@"
  1350. .IN "XHeightOfScreen" "" "@DEF@"
  1351. Both return the height of the specified screen in pixels.
  1352. .LP
  1353. .sp
  1354. .\" Start marker code here
  1355. .FD 0
  1356. WidthMMOfScreen\^(\^\fIscreen\fP\^)
  1357. .sp
  1358. int XWidthMMOfScreen\^(\^\fIscreen\fP\^)
  1359. .br
  1360.       Screen *\fIscreen\fP\^;
  1361. .FN
  1362. .IP \fIscreen\fP 1i
  1363. Specifies the appropriate 
  1364. .PN Screen
  1365. structure.
  1366. .\" End marker code here
  1367. .LP
  1368. .IN "WidthMMOfScreen" "" "@DEF@"
  1369. .IN "XWidthMMOfScreen" "" "@DEF@"
  1370. Both return the width of the specified screen in millimeters.
  1371. .LP
  1372. .sp
  1373. .\" Start marker code here
  1374. .FD 0
  1375. HeightMMOfScreen\^(\^\fIscreen\fP\^)
  1376. .sp
  1377. int XHeightMMOfScreen\^(\^\fIscreen\fP\^)
  1378. .br
  1379.       Screen *\fIscreen\fP\^;
  1380. .FN
  1381. .IP \fIscreen\fP 1i
  1382. Specifies the appropriate 
  1383. .PN Screen
  1384. structure.
  1385. .\" End marker code here
  1386. .LP
  1387. .IN "HeightMMOfScreen" "" "@DEF@"
  1388. .IN "XHeightMMOfScreen" "" "@DEF@"
  1389. Both return the height of the specified screen in millimeters.
  1390. .LP
  1391. .sp
  1392. .\" Start marker code here
  1393. .FD 0
  1394. MaxCmapsOfScreen\^(\^\fIscreen\fP\^)
  1395. .sp
  1396. int XMaxCmapsOfScreen\^(\^\fIscreen\fP\^)
  1397. .br
  1398.       Screen *\fIscreen\fP\^;
  1399. .FN
  1400. .IP \fIscreen\fP 1i
  1401. Specifies the appropriate 
  1402. .PN Screen
  1403. structure.
  1404. .\" End marker code here
  1405. .LP
  1406. .IN "MaxCmapsOfScreen" "" "@DEF@"
  1407. .IN "XMaxCmapsOfScreen" "" "@DEF@"
  1408. Both return the maximum number of installed colormaps supported 
  1409. by the specified screen (see section 9.3).
  1410. .LP
  1411. .sp
  1412. .\" Start marker code here
  1413. .FD 0
  1414. MinCmapsOfScreen\^(\^\fIscreen\fP\^)
  1415. .sp
  1416. int XMinCmapsOfScreen\^(\^\fIscreen\fP\^)
  1417. .br
  1418.       Screen *\fIscreen\fP\^;
  1419. .FN
  1420. .IP \fIscreen\fP 1i
  1421. Specifies the appropriate 
  1422. .PN Screen
  1423. structure.
  1424. .\" End marker code here
  1425. .LP
  1426. .IN "MinCmapsOfScreen" "" "@DEF@"
  1427. .IN "XMinCmapsOfScreen" "" "@DEF@"
  1428. Both return the minimum number of installed colormaps supported 
  1429. by the specified screen (see section 9.3).
  1430. .LP
  1431. .sp
  1432. .\" Start marker code here
  1433. .FD 0
  1434. PlanesOfScreen\^(\^\fIscreen\fP\^)
  1435. .sp
  1436. int XPlanesOfScreen\^(\^\fIscreen\fP\^)
  1437. .br
  1438.       Screen *\fIscreen\fP\^;
  1439. .FN
  1440. .IP \fIscreen\fP 1i
  1441. Specifies the appropriate 
  1442. .PN Screen
  1443. structure.
  1444. .\" End marker code here
  1445. .LP
  1446. .IN "PlanesOfScreen" "" "@DEF@"
  1447. .IN "XPlanesOfScreen" "" "@DEF@"
  1448. Both return the depth of the root window.
  1449. .LP
  1450. .sp
  1451. .\" Start marker code here
  1452. .FD 0
  1453. RootWindowOfScreen\^(\^\fIscreen\fP\^)
  1454. .sp
  1455. Window XRootWindowOfScreen\^(\^\fIscreen\fP\^)
  1456. .br
  1457.       Screen *\fIscreen\fP\^;
  1458. .FN
  1459. .IP \fIscreen\fP 1i
  1460. Specifies the appropriate 
  1461. .PN Screen
  1462. structure.
  1463. .\" End marker code here
  1464. .LP
  1465. .IN "RootWindowOfScreen" "" "@DEF@"
  1466. .IN "XRootWindowOfScreen" "" "@DEF@"
  1467. Both return the root window of the specified screen.
  1468. .NH 2
  1469. Generating a NoOperation Protocol Request
  1470. .XS
  1471. \*(SN Generating a NoOperation Protocol Request
  1472. .XE
  1473. .LP
  1474. To execute a 
  1475. .PN NoOperation 
  1476. protocol request, use
  1477. .PN XNoOp .
  1478. .IN "XNoOp" "" "@DEF@"
  1479. .\" Start marker code here
  1480. .FD 0
  1481. XNoOp\^(\^\fIdisplay\fP\^)
  1482. .br
  1483.       Display *\fIdisplay\fP\^;
  1484. .FN
  1485. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  1486. .IP \fIdisplay\fP 1i
  1487. Specifies the connection to the X server.
  1488. .\" End marker code here
  1489. .LP
  1490. The
  1491. .PN XNoOp
  1492. function sends a 
  1493. .PN NoOperation 
  1494. protocol request to the X server,
  1495. thereby exercising the connection.
  1496. .NH 2
  1497. Freeing Client-Created Data
  1498. .XS
  1499. \*(SN Freeing Client-Created Data
  1500. .XE
  1501. .LP
  1502. To free in-memory data that was created by an Xlib function, use
  1503. .PN XFree .
  1504. .IN "XFree" "" "@DEF@"
  1505. .\" Start marker code here
  1506. .FD 0
  1507. XFree\^(\^\fIdata\fP\^)
  1508. .br
  1509.      void *\fIdata\fP\^; 
  1510. .FN
  1511. .IP \fIdata\fP 1i
  1512. Specifies the data that is to be freed.
  1513. .\" End marker code here
  1514. .LP
  1515. The
  1516. .PN XFree
  1517. function is a general-purpose Xlib routine that frees the specified data.
  1518. You must use it to free any objects that were allocated by Xlib,
  1519. unless an alternate function is explicitly specified for the object.
  1520. .NH 2
  1521. Closing the Display
  1522. .XS
  1523. \*(SN Closing the Display
  1524. .XE
  1525. .LP
  1526. To close a display or disconnect from the X server, use
  1527. .PN XCloseDisplay .
  1528. .IN "XCloseDisplay" "" "@DEF@"
  1529. .LP
  1530. .\" Start marker code here
  1531. .FD 0
  1532. .\" $Header: XCloseDisp.f,v 1.1 88/02/26 09:58:48 mento Exp $
  1533. XCloseDisplay\^(\fIdisplay\fP\^)
  1534. .br
  1535.       Display *\fIdisplay\fP\^;
  1536. .FN
  1537. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  1538. .IP \fIdisplay\fP 1i
  1539. Specifies the connection to the X server.
  1540. .\" End marker code here
  1541. .LP
  1542. .\" $Header: XCloseDisp.d,v 1.6 88/08/16 09:50:19 mento Exp $
  1543. The
  1544. .PN XCloseDisplay
  1545. function closes the connection to the X server for the display specified in the
  1546. .PN Display
  1547. structure and destroys all windows, resource IDs
  1548. .Pn ( Window ,
  1549. .PN Font ,
  1550. .PN Pixmap ,
  1551. .PN Colormap ,
  1552. .PN Cursor ,
  1553. and
  1554. .PN GContext ),
  1555. or other resources that the client has created
  1556. on this display, unless the close-down mode of the resource has been changed
  1557. (see
  1558. .PN XSetCloseDownMode ).
  1559. Therefore, these windows, resource IDs, and other resources should never be 
  1560. referenced again or an error will be generated.
  1561. Before exiting, you should call
  1562. .PN XCloseDisplay
  1563. explicitly so that any pending errors are reported as
  1564. .PN XCloseDisplay
  1565. performs a final
  1566. .PN XSync
  1567. operation.
  1568. .IN "Resource IDs"
  1569. .IN "XCloseDisplay"
  1570. .LP
  1571. .PN XCloseDisplay
  1572. can generate a
  1573. .PN BadGC
  1574. error.
  1575. .sp
  1576. .LP
  1577. Xlib provides a function to permit the resources owned by a client
  1578. to survive after the client's connection is closed.
  1579. To change a client's close-down mode, use
  1580. .PN XSetCloseDownMode .
  1581. .IN "XSetCloseDownMode" "" "@DEF@"
  1582. .\" Start marker code here
  1583. .FD 0
  1584. .\" $Header: XChClsDwnMd.f,v 1.1 88/02/26 09:58:30 mento Exp $
  1585. XSetCloseDownMode\^(\^\fIdisplay\fP, \fIclose_mode\fP\^)
  1586. .br
  1587.       Display *\fIdisplay\fP\^;
  1588. .br
  1589.       int \fIclose_mode\fP\^;    
  1590. .FN
  1591. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  1592. .IP \fIdisplay\fP 1i
  1593. Specifies the connection to the X server.
  1594. .\" $Header: closemode.a,v 1.4 88/05/14 09:00:07 mento Exp $
  1595. .IP \fIclose_mode\fP 1i
  1596. Specifies the client close-down mode.
  1597. You can pass 
  1598. .PN DestroyAll , 
  1599. .PN RetainPermanent , 
  1600. or
  1601. .PN RetainTemporary . 
  1602. .\" End marker code here
  1603. .LP
  1604. .\" $Header: XChClsDwnMd.d,v 1.3 88/08/19 20:35:01 mento Exp $
  1605. The
  1606. .PN XSetCloseDownMode
  1607. defines what will happen to the client's resources at connection close.
  1608. A connection starts in
  1609. .PN DestroyAll
  1610. mode.
  1611. For information on what happens to the client's resources when the
  1612. close_mode argument is
  1613. .PN RetainPermanent
  1614. or
  1615. .PN RetainTemporary ,
  1616. see section 2.6.
  1617. .LP
  1618. .PN XSetCloseDownMode
  1619. can generate a
  1620. .PN BadValue 
  1621. error.
  1622. .NH 2
  1623. X Server Connection Close Operations 
  1624. .XS
  1625. \*(SN X Server Connection Close Operations
  1626. .XE
  1627. .LP
  1628. When the X server's connection to a client is closed
  1629. either by an explicit call to
  1630. .PN XCloseDisplay
  1631. or by a process that exits, the X server performs the following
  1632. automatic operations:
  1633. .IP \(bu 5
  1634. It disowns all selections owned by the client
  1635. (see 
  1636. .PN XSetSelectionOwner ).
  1637. .IP \(bu 5
  1638. It performs an
  1639. .PN XUngrabPointer
  1640. and
  1641. .PN XUngrabKeyboard 
  1642. if the client has actively grabbed the pointer 
  1643. or the keyboard.
  1644. .IP \(bu 5
  1645. It performs an
  1646. .PN XUngrabServer 
  1647. if the client has grabbed the server.
  1648. .IP \(bu 5
  1649. It releases all passive grabs made by the client.  
  1650. .IP \(bu 5
  1651. It marks all resources (including colormap entries) allocated 
  1652. by the client either as permanent or temporary, 
  1653. depending on whether the close-down mode is 
  1654. .PN RetainPermanent
  1655. or
  1656. .PN RetainTemporary .
  1657. However, this does not prevent other client applications from explicitly
  1658. destroying the resources (see 
  1659. .PN XSetCloseDownMode ).
  1660. .LP
  1661. When the close-down mode is
  1662. .PN DestroyAll ,
  1663. the X server destroys all of a client's resources as follows:
  1664. .IP \(bu 5
  1665. It examines each window in the client's save-set to determine if it is an inferior
  1666. (subwindow) of a window created by the client.
  1667. (The save-set is a list of other clients' windows, 
  1668. which are referred to as save-set windows.)
  1669. If so, the X server reparents the save-set window to the closest ancestor so
  1670. that the save-set window is not an inferior of a window created by the client.
  1671. The reparenting leaves unchanged the absolute coordinates (with respect to
  1672. the root window) of the upper-left outer corner of the save-set
  1673. window.
  1674. .IP \(bu 5
  1675. It performs a
  1676. .PN MapWindow
  1677. request on the save-set window if the save-set window is unmapped.
  1678. The X server does this even if the save-set window was not an inferior of 
  1679. a window created by the client.
  1680. .IP \(bu 5
  1681. It destroys all windows created by the client.
  1682. .IP \(bu 5
  1683. It performs the appropriate free request on each nonwindow resource created by
  1684. the client in the server (for example, 
  1685. .PN Font , 
  1686. .PN Pixmap , 
  1687. .PN Cursor , 
  1688. .PN Colormap , 
  1689. and 
  1690. .PN GContext ).
  1691. .IP \(bu 5
  1692. It frees all colors and colormap entries allocated by a client application.
  1693. .LP
  1694. Additional processing occurs when the last connection to the X server closes.
  1695. An X server goes through a cycle of having no connections and having some
  1696. connections.
  1697. When the last connection to the X server closes as a result of a connection
  1698. closing with the close_mode of
  1699. .PN DestroyAll ,
  1700. the X server does the following: 
  1701. .IP \(bu 5
  1702. It resets its state as if it had just been
  1703. started.  
  1704. The X server begins by destroying all lingering resources from
  1705. clients that have terminated in 
  1706. .PN RetainPermanent
  1707. or
  1708. .PN RetainTemporary
  1709. mode.
  1710. .IP \(bu 5
  1711. It deletes all but the predefined atom identifiers.
  1712. .IP \(bu 5
  1713. It deletes all properties on all root windows (see section 4.3).
  1714. .IP \(bu 5
  1715. It resets all device maps and attributes 
  1716. (for example, key click, bell volume, and acceleration) 
  1717. as well as the access control list.
  1718. .IP \(bu 5
  1719. It restores the standard root tiles and cursors.
  1720. .IP \(bu 5
  1721. It restores the default font path.
  1722. .IP \(bu 5
  1723. It restores the input focus to state
  1724. .PN PointerRoot .
  1725. .LP
  1726. However, the X server does not reset if you close a connection with a close-down
  1727. mode set to
  1728. .PN RetainPermanent
  1729. or
  1730. .PN RetainTemporary .
  1731. .bp
  1732.