home *** CD-ROM | disk | FTP | other *** search
/ InfoMagic Source Code 1993 July / THE_SOURCE_CODE_CD_ROM.iso / X / mit / doc / Xlib / CH01 < prev    next >
Encoding:
Text File  |  1991-08-18  |  19.8 KB  |  595 lines

  1. .EH '\fBXlib \- C Library\fP''\fBX11, Release 5\fP'
  2. .OH '\fBXlib \- C Library\fP''\fBX11, Release 5\fP'
  3. .EF ''\fB % \fP''
  4. .OF ''\fB % \fP''
  5. \&
  6. .sp 1
  7. .ce 3
  8. \s+1\fBChapter 1\fP\s-1
  9.  
  10. \s+1\fBIntroduction to Xlib\fP\s-1
  11. .sp 2
  12. .nr H1 1
  13. .nr H2 0
  14. .nr H3 0
  15. .nr H4 0
  16. .nr H5 0
  17. .na
  18. .LP
  19. .XS
  20. Chapter 1: Introduction to Xlib
  21. .XE
  22. The X Window System is a network-transparent window system
  23. that was designed at MIT.
  24. X display servers run on computers with either monochrome or color
  25. bitmap display hardware.
  26. The server distributes user input to and accepts output requests from various
  27. client programs located either on the same machine or elsewhere in
  28. the network.
  29. Xlib is a C subroutine library that application programs (clients)
  30. use to interface with the window system by means of a stream connection.
  31. Although a client usually runs on the same machine as the X server 
  32. it is talking to, this need not be the case.
  33. .LP
  34. \fIXlib \- C Language X Interface\fP is a reference guide to the low-level 
  35. C language interface to the X Window System protocol.
  36. It is neither a tutorial nor a user's guide to programming the X Window System.
  37. Rather, it provides a detailed description of each function in the library
  38. as well as a discussion of the related background information.
  39. \fIXlib \- C Language X Interface\fP assumes a basic understanding of a graphics 
  40. window system and of the C programming language.
  41. Other higher-level abstractions
  42. (for example, those provided by the toolkits for X)
  43. are built on top of the Xlib library.
  44. For further information about these higher-level libraries,
  45. see the appropriate toolkit documentation.
  46. The \fIX Window System Protocol\fP provides the definitive word on the
  47. behavior of X.
  48. Although additional information appears here,
  49. the protocol document is the ruling document.
  50. .LP
  51. To provide an introduction to X programming,
  52. this chapter discusses:
  53. .IP \(bu 5
  54. Overview of the X Window System
  55. .IP \(bu 5
  56. Errors
  57. .IP \(bu 5
  58. Standard header files
  59. .IP \(bu 5
  60. Naming and argument conventions
  61. .IP \(bu 5
  62. Programming considerations
  63. .IP \(bu 5
  64. Formatting conventions
  65. .LE
  66. .NH 2
  67. Overview of the X Window System
  68. .XS
  69. \*(SN Overview of the X Window System
  70. .XE
  71. .LP
  72. Some of the terms used in this book are unique to X,
  73. and other terms that are common to other window systems 
  74. have different meanings in X.
  75. You may find it helpful to refer to the glossary, 
  76. which is located at the end of the book.
  77. .LP
  78. The X Window System supports one or more screens containing
  79. overlapping windows or subwindows.
  80. A screen is a physical monitor and hardware,
  81. which can be either color, grayscale, or monochrome.
  82. There can be multiple screens for each display or workstation.
  83. A single X server can provide display services for any number of screens.
  84. A set of screens for a single user with one keyboard and one pointer
  85. (usually a mouse) is called a display.
  86. .LP
  87. .IN "Screen"
  88. All the windows in an X server are arranged in strict hierarchies.
  89. At the top of each hierarchy is a root window,
  90. which covers each of the display screens.
  91. Each root window is partially or completely covered by child windows.
  92. All windows, except for root windows, have parents.
  93. There is usually at least one window for each application program.
  94. .IN "Child window"
  95. .IN "Parent Window"
  96. Child windows may in turn have their own children.
  97. In this way, 
  98. an application program can create an arbitrarily deep tree 
  99. on each screen.
  100. X provides graphics, text, and raster operations for windows.
  101. .LP
  102. A child window can be larger than its parent. 
  103. That is, part or all of
  104. the child window can extend beyond the boundaries of the parent,
  105. but all output to a window is clipped by its parent.
  106. .IN "Stacking order"
  107. If several children of a window have overlapping locations, 
  108. one of the children is considered to be on top of or raised over the
  109. others thus obscuring them.
  110. Output to areas covered by other windows is suppressed by the window
  111. system unless the window has backing store.
  112. If a window is obscured by a second window, 
  113. the second window obscures only those ancestors of the second window,
  114. which are also ancestors of the first window.
  115. .LP
  116. .IN "Window" "" "@DEF@"
  117. A window has a border zero or more pixels in width, which can
  118. be any pattern (pixmap) or solid color you like.
  119. A window usually but not always has a background pattern,
  120. which will be repainted by the window system when uncovered.
  121. Child windows obscure their parents,
  122. and graphic operations in the parent window usually
  123. are clipped by the children.
  124. .LP
  125. Each window and pixmap has its own coordinate system.
  126. The coordinate system has the X axis horizontal and the Y axis vertical, 
  127. with the origin [0, 0] at the upper left.
  128. Coordinates are integral,
  129. in terms of pixels,
  130. and coincide with pixel centers.
  131. For a window, 
  132. the origin is inside the border at the inside upper left.
  133. .LP
  134. X does not guarantee to preserve the contents of windows. 
  135. When part or all of a window is hidden and then brought back onto the screen,
  136. its contents may be lost. 
  137. The server then sends the client program an
  138. .PN Expose
  139. event to notify it that part or all of the window needs to be repainted.
  140. Programs must be prepared to regenerate the contents of windows on demand.
  141. .LP
  142. .IN "Pixmap"
  143. .IN "Drawable"
  144. .IN "Tile"
  145. .IN "Bitmap"
  146. X also provides off-screen storage of graphics objects,
  147. called pixmaps.
  148. Single plane (depth 1) pixmaps are sometimes referred to as bitmaps.
  149. Pixmaps can be used in most graphics functions interchangeably with
  150. windows and are used in various graphics operations to define patterns or tiles.
  151. Windows and pixmaps together are referred to as drawables.
  152. .LP
  153. Most of the functions in Xlib just add requests to an output buffer.
  154. These requests later execute asynchronously on the X server.
  155. Functions that return values of information stored in
  156. the server do not return (that is, they block)
  157. until an explicit reply is received or an error occurs.
  158. You can provide an error handler,
  159. which will be called when the error is reported.
  160. .LP
  161. .IN "XSync"
  162. If a client does not want a request to execute asynchronously, 
  163. it can follow the request with a call to 
  164. .PN XSync , 
  165. which blocks until all previously buffered
  166. asynchronous events have been sent and acted on.
  167. As an important side effect, 
  168. the output buffer in Xlib is always flushed by a call to any function
  169. that returns a value from the server or waits for input.
  170. .LP
  171. .IN "Resource IDs"
  172. .IN "Resource IDs" "Window"
  173. .IN "Resource IDs" "Font"
  174. .IN "Resource IDs" "Pixmap"
  175. .IN "Resource IDs" "Cursor"
  176. .IN "Resource IDs" "GContext"
  177. Many Xlib functions will return an integer resource ID,
  178. which allows you to refer to objects stored on the X server.
  179. These can be of type 
  180. .PN Window , 
  181. .PN Font , 
  182. .PN Pixmap , 
  183. .PN Colormap ,
  184. .PN Cursor , 
  185. and 
  186. .PN GContext ,
  187. as defined in the file
  188. .Pn < X11/X.h >.
  189. These resources are created by requests and are destroyed
  190. (or freed) by requests or when connections are closed.
  191. Most of these resources are potentially sharable between
  192. applications, and in fact, windows are manipulated explicitly by
  193. window manager programs.
  194. Fonts and cursors are shared automatically across multiple screens.
  195. Fonts are loaded and unloaded as needed and are shared by multiple clients.
  196. Fonts are often cached in the server.
  197. Xlib provides no support for sharing graphics contexts between applications.
  198. .LP
  199. .IN "Event"
  200. Client programs are informed of events.
  201. Events may either be side effects of a request (for example, restacking windows
  202. generates 
  203. .PN Expose 
  204. events) or completely asynchronous (for example, from the keyboard).
  205. A client program asks to be informed of events.
  206. Because other applications can send events to your application,
  207. programs must be prepared to handle (or ignore) events of all types.
  208. .LP
  209. Input events (for example, a key pressed or the pointer moved) 
  210. arrive asynchronously from the server and are queued until they are 
  211. requested by an explicit call (for example,
  212. .PN XNextEvent
  213. or
  214. .PN XWindowEvent ).
  215. In addition, some library
  216. functions (for example,
  217. .PN XRaiseWindow )
  218. generate 
  219. .PN Expose
  220. and
  221. .PN ConfigureRequest
  222. events.
  223. These events also arrive asynchronously, but the client may
  224. .IN "XSync"
  225. wish to explicitly wait for them by calling
  226. .PN XSync
  227. after calling a function that can cause the server to generate events.
  228. .NH 2
  229. Errors
  230. .XS
  231. \*(SN Errors
  232. .XE
  233. .LP
  234. Some functions return 
  235. .PN Status , 
  236. an integer error indication.
  237. If the function fails, it returns a zero.
  238. If the function returns a status of zero,
  239. it has not updated the return arguments.
  240. .IN "Status"
  241. Because C does not provide multiple return values, 
  242. many functions must return their results by writing into client-passed storage. 
  243. .IN "Error" "handling"
  244. By default, errors are handled either by a standard library function
  245. or by one that you provide.
  246. Functions that return pointers to strings return NULL pointers if
  247. the string does not exist.
  248. .LP
  249. The X server reports protocol errors at the time that it detects them.
  250. If more than one error could be generated for a given request,
  251. the server can report any of them.
  252. .LP
  253. Because Xlib usually does not transmit requests to the server immediately
  254. (that is, it buffers them), errors can be reported much later than they
  255. actually occur.
  256. For debugging purposes, however,
  257. Xlib provides a mechanism for forcing synchronous behavior 
  258. (see section 11.8.1).
  259. When synchronization is enabled, 
  260. errors are reported as they are generated.
  261. .LP
  262. When Xlib detects an error,
  263. it calls an error handler,
  264. which your program can provide.
  265. If you do not provide an error handler,
  266. the error is printed, and your program terminates.
  267. .NH 2
  268. Standard Header Files
  269. .XS
  270. \*(SN Standard Header Files
  271. .XE
  272. .LP
  273. The following include files are part of the Xlib standard.
  274. .LP
  275. .Pn < X11/Xlib.h >
  276. .IP
  277. This is the main header file for Xlib.  The majority
  278. of all Xlib symbols are declared by including this file.
  279. This file also contains the preprocessor symbol
  280. .PN XlibSpecificationRelease .
  281. .IN "XlibSpecificationRelease" "" "@DEF@"
  282. This symbol is defined to have the ``5'' in this release of the standard.
  283. (Earlier releases of Xlib did not have this symbol.)
  284. .LP
  285. .Pn < X11/X.h >
  286. .IP
  287. This file declares types and constants for the X protocol that are
  288. to be used by applications.
  289. It is included automatically from
  290. .Pn < X11/Xlib.h >,
  291. so application code should never need to reference this file directly.
  292. .LP
  293. .Pn < X11/Xcms.h >
  294. .IP
  295. This file contains symbols for much of the color management facilities
  296. described in chapter 6.
  297. All functions, types, and symbols with the prefix "Xcms",
  298. plus the Color Conversion Contexts macros, are declared in this file.
  299. .Pn < X11/Xlib.h >
  300. must be included before including this file.
  301. .LP
  302. .Pn < X11/Xutil.h >
  303. .IP
  304. This file declares various functions, types, and symbols used for
  305. inter-client communication and application utility functions,
  306. described in chapters 14 and 16.
  307. .Pn < X11/Xlib.h >
  308. must be included before including this file.
  309. .LP
  310. .Pn < X11/Xresource.h >
  311. .IP
  312. This file declares all functions, types, and symbols for the
  313. resource manager facilities, described in chapter 15.
  314. .Pn < X11/Xlib.h >
  315. must be included before including this file.
  316. .LP
  317. .Pn < X11/Xatom.h >
  318. .IP
  319. This file declares all predefined atoms, symbols with prefix ``XA_''.
  320. .LP
  321. .Pn < X11/cursorfont.h >
  322. .IP
  323. This file declares the cursor symbols for the standard cursor font,
  324. listed in appendix B.  All symbols have the prefix ``XC_''.
  325. .LP
  326. .Pn < X11/keysymdef.h >
  327. .IP
  328. This file declares all standard KeySym values, symbols with prefix ``XK_''.
  329. The KeySyms are arranged in groups, and a preprocessor symbol controls
  330. inclusion of each group.  The preprocessor symbol must be defined
  331. prior to inclusion of the file to obtain the associated values.
  332. The preprocessor symbols are:  XK_MISCELLANY, XK_LATIN1, XK_LATIN2,
  333. XK_LATIN3, XK_LATIN4, XK_KATAKANA, XK_ARABIC, XK_CYRILLIC, XK_GREEK,
  334. XK_TECHNICAL, XK_SPECIAL, XK_PUBLISHING, XK_APL, and XK_HEBREW.
  335. .LP
  336. .Pn < X11/keysym.h >
  337. .IP
  338. This file defines the preprocessor symbols
  339. XK_MISCELLANY, XK_LATIN1, XK_LATIN2, XK_LATIN3, XK_LATIN4, and XK_GREEK,
  340. and then includes
  341. .Pn < X11/keysymdef.h >.
  342. .LP
  343. .Pn < X11/Xlibint.h >
  344. .IP
  345. This file declares all the functions, types, and symbols used for
  346. extensions, described in appendix C.
  347. This file automatically includes
  348. .Pn < X11/Xlib.h >.
  349. .LP
  350. .Pn < X11/Xproto.h >
  351. .IP
  352. This file declares types and symbols for the basic X protocol,
  353. for use in implementing extensions.
  354. It is included automatically from
  355. .Pn < X11/Xlibint.h >,
  356. so application and extension code should never need to
  357. reference this file directly.
  358. .LP
  359. .Pn < X11/Xprotostr.h >
  360. .IP
  361. This file declares types and symbols for the basic X protocol,
  362. for use in implementing extensions.
  363. It is included automatically from
  364. .Pn < X11/Xproto.h >,
  365. so application and extension code should never need to
  366. reference this file directly.
  367. .LP
  368. .Pn < X11/X10.h >
  369. .IP
  370. This file declares all the functions, types, and symbols used for the
  371. X10 compatibility functions, described in appendix D.
  372. .NH 2
  373. Generic Values and Types
  374. .XS
  375. \*(SN Generic Values and Types
  376. .XE
  377. .LP
  378. The following symbols are defined by Xlib and used throughout the manual:
  379. .IN "Bool" "" "@DEF@"
  380. .IN "True" "" "@DEF@"
  381. .IN "False" "" "@DEF@"
  382. .IP \(bu 5
  383. Xlib defines the type
  384. .PN Bool
  385. and the boolean values
  386. .PN True
  387. and
  388. .PN False .
  389. .IN "None" "" "@DEF@"
  390. .IP \(bu 5
  391. .PN None
  392. is the universal null resource ID or atom.
  393. .IN "XID" "" "@DEF@"
  394. .IP \(bu 5
  395. The type
  396. .PN XID
  397. is used for generic resource IDs.
  398. .IN "XPointer" "" "@DEF@"
  399. .IP \(bu 5
  400. The type
  401. .PN XPointer
  402. is defined to be ``char *'' and is used as a generic opaque pointer to data.
  403. .NH 2
  404. Naming and Argument Conventions within Xlib
  405. .XS
  406. \*(SN Naming and Argument Conventions within Xlib
  407. .XE
  408. .LP
  409. Xlib follows a number of conventions for the naming and syntax of the functions.
  410. Given that you remember what information the function requires,
  411. these conventions are intended to make the syntax of the functions more 
  412. predictable.
  413. .LP
  414. The major naming conventions are:
  415. .IP \(bu 5
  416. To differentiate the X symbols from the other symbols,
  417. the library uses mixed case for external symbols.
  418. It leaves lowercase for variables and all uppercase for user macros,
  419. as per existing convention.
  420. .IP \(bu 5
  421. All Xlib functions begin with a capital X.
  422. .IP \(bu 5
  423. The beginnings of all function names and symbols are capitalized.
  424. .IP \(bu 5
  425. All user-visible data structures begin with a capital X.
  426. More generally,
  427. anything that a user might dereference begins with a capital X.
  428. .IP \(bu 5
  429. Macros and other symbols do not begin with a capital X.
  430. To distinguish them from all user symbols,
  431. each word in the macro is capitalized.
  432. .IP \(bu 5
  433. All elements  of or variables in a data structure are in lowercase.
  434. Compound words, where needed, are constructed with underscores (_).
  435. .IP \(bu 5
  436. The display argument, where used, is always first in the argument list.
  437. .IP \(bu 5
  438. All resource objects, where used, occur at the beginning of the argument list
  439. immediately after the display argument.
  440. .IP \(bu 5
  441. When a  graphics context is present together with
  442. another type of resource (most commonly, a drawable), the
  443. graphics context occurs in the argument list after the other
  444. resource.
  445. Drawables outrank all other resources.
  446. .IP \(bu 5
  447. Source arguments always precede the destination arguments in the argument list.
  448. .IP \(bu 5
  449. The x argument always precedes the y argument in the argument list.
  450. .IP \(bu 5
  451. The width argument always precedes the height argument in the argument list.
  452. .IP \(bu 5
  453. Where the x, y, width, and height arguments are used together,
  454. the x and y arguments always precede the width and height arguments.
  455. .IP \(bu 5
  456. Where a mask is accompanied with a structure,
  457. the mask always precedes the pointer to the structure in the argument list.
  458. .NH 2
  459. Programming Considerations
  460. .XS
  461. \*(SN Programming Considerations
  462. .XE
  463. .LP
  464. The major programming considerations are:
  465. .IP \(bu 5
  466. Coordinates and sizes in X are actually 16-bit quantities.
  467. This decision was taken to minimize the bandwidth required for a
  468. given level of performance.
  469. Coordinates usually are declared as an ``int'' in the interface.
  470. Values larger than 16 bits are truncated silently.
  471. Sizes (width and height) are declared as unsigned quantities.
  472. .IP \(bu 5
  473. Keyboards are the greatest variable between different
  474. manufacturers' workstations.
  475. If you want your program to be portable,
  476. you should be particularly conservative here.
  477. .IP \(bu 5
  478. Many display systems have limited amounts of off-screen memory.
  479. If you can, you should minimize use of pixmaps and backing
  480. store.
  481. .IP \(bu 5
  482. The user should have control of his screen real estate.
  483. Therefore, you should write your applications to react to window management
  484. rather than presume control of the entire screen.
  485. What you do inside of your top-level window, however,
  486. is up to your application.
  487. For further information,
  488. see chapter 14
  489. and the \fIInter-Client Communication Conventions Manual\fP.
  490. .NH 2
  491. Character Sets and Encodings
  492. .XS
  493. \*(SN Character Sets and Encodings
  494. .XE
  495. .LP
  496. Some of the Xlib functions make reference to specific character sets
  497. and character encodings.  The following ones are the most common:
  498. .LP
  499. \fBX Portable Character Set\fP
  500. .IP
  501. A basic set of 97 characters which are assumed to exist in all
  502. locales supported by Xlib.  This set contains the following characters:
  503. .IP
  504. .Ds 0
  505. .EQ
  506. delim DD
  507. .EN
  508. a..z A..Z 0..9
  509. !"#$%&'()*+,-./:;<=>?@[\\]^_`{|}~
  510. <space>, <tab>, and <newline>
  511. .EQ
  512. delim %%
  513. .EN
  514. .De
  515. .IP
  516. This is the left/lower half
  517. of the graphic character set of ISO8859-1 plus <space>, <tab>, and <newline>.
  518. It is also the set of graphic characters in 7-bit ASCII plus the same
  519. three control characters.
  520. The actual encoding of these characters on the host is system dependent.
  521. .LP
  522. \fBHost Portable Character Encoding\fP
  523. .IP
  524. The encoding of the X Portable Character Set on the host.
  525. The encoding itself is not defined by this standard,
  526. but the encoding must be the same in all locales supported by Xlib on the host.
  527. If a string is said to be in the Host Portable Character Encoding,
  528. then it only contains characters from the X Portable Character Set,
  529. in the host encoding.
  530. .LP
  531. \fBLatin-1\fP
  532. .IP
  533. The coded character set defined by the ISO8859-1 standard.
  534. .LP
  535. \fBSTRING encoding\fP
  536. .IP
  537. Latin-1, plus tab and newline.
  538. .LP
  539. \fBPOSIX Portable Filename Character Set\fP
  540. .IP
  541. The set of 65 characters which can be used in naming files on a POSIX-compliant
  542. host that are correctly processed in all locales.
  543. The set is:
  544. .IP
  545. .Ds 0
  546. a..z A..Z 0..9 ._-
  547. .De
  548. .NH 2
  549. Formatting Conventions
  550. .XS
  551. \*(SN Formatting Conventions
  552. .XE
  553. .LP
  554. \fIXlib \- C Language X Interface\fP uses the following conventions:
  555. .IP \(bu 5
  556. Global symbols are printed in 
  557. .PN this 
  558. .PN special 
  559. .PN font .
  560. These can be either function names,
  561. symbols defined in include files, or structure names.
  562. Arguments are printed in \fIitalics\fP.
  563. .IP \(bu 5
  564. Each function is introduced by a general discussion that 
  565. distinguishes it from other functions.
  566. The function declaration itself follows,
  567. and each argument is specifically explained.
  568. Although ANSI C function prototype syntax is not used,
  569. Xlib header files normally declare functions using function prototypes
  570. in ANSI C environments.
  571. General discussion of the function, if any is required,
  572. follows the arguments.
  573. Where applicable, 
  574. the last paragraph of the explanation lists the possible 
  575. Xlib error codes that the function can generate.
  576. For a complete discussion of the Xlib error codes,
  577. see section 11.8.2.
  578. .IP \(bu 5
  579. To eliminate any ambiguity between those arguments that you pass and those that 
  580. a function returns to you,
  581. the explanations for all arguments that you pass start with the word
  582. \fIspecifies\fP or, in the case of multiple arguments, the word \fIspecify\^\fP.
  583. The explanations for all arguments that are returned to you start with the
  584. word \fIreturns\fP or, in the case of multiple arguments, the word \fIreturn\^\fP.
  585. The explanations for all arguments that you can pass and are returned start
  586. with the words \fIspecifies and returns\^\fP.
  587. .IP \(bu 5
  588. Any pointer to a structure that is used to return a value is designated as 
  589. such by the \fI_return\fP suffix as part of its name.
  590. All other pointers passed to these functions are
  591. used for reading only.
  592. A few arguments use pointers to structures that are used for
  593. both input and output and are indicated by using the \fI_in_out\fP suffix.
  594. .bp
  595.