目录
1.1. Overview of the X Window System
1.5. Naming and Argument Conventions within Xlib
1.6. Programming Considerations
1.7. Character Sets and Encodings
1.1. Overview of the X Window System
1.1 x window 概述
Some of the terms used in this book are unique to X, and other terms that are common to other window systems have different meanings in X. You may find it helpful to refer to the glossary, which is located at the end of the book.
本书中使用的一些术语是X window独有的，其他窗口系统通用的术语在X window中有不同的含义。您可以参考本书末尾的术语表
The X Window System supports one or more screens containing overlapping windows or subwindows. A screen is a physical monitor and hardware, which can be either color, grayscale, or monochrome. There can be multiple screens for each display or workstation. A single X server can provide display services for any number of screens. A set of screens for a single user with one keyboard and one pointer (usually a mouse) is called a display.
X window系统支持一个或多个包含重叠窗口或子窗口的屏幕。屏幕是物理监视器和硬件，可以是彩色、灰度或单色。每个显示器或工作站可以有多个屏幕。单个X server可以为任意数量的屏幕提供显示服务。为一个用户使用一个键盘和一个指针（通常是鼠标）的一组屏幕称为显示器。
All the windows in an X server are arranged in strict hierarchies. At the top of each hierarchy is a root window, which covers each of the display screens. Each root window is partially or completely covered by child windows. All windows, except for root windows, have parents. There is usually at least one window for each application program. Child windows may in turn have their own children. In this way, an application program can create an arbitrarily deep tree on each screen. X provides graphics, text, and raster operations for windows.
X服务中的所有窗口都是按严格的层次结构排列的。在每个层次结构的顶部是一个根窗口，它覆盖了每个显示屏幕。每个根窗口部分或全部被子窗口覆盖。除根窗口外，所有窗口都有父窗口。通常每个应用程序至少有一个窗口，子窗口又可能有自己的子窗口。通过这种方式，应用程序可以在每个屏幕上创建任意深度的树。X为windows提供图形、文本和光栅操作。
A child window can be larger than its parent. That is, part or all of the child window can extend beyond the boundaries of the parent, but all output to a window is clipped by its parent. If several children of a window have overlapping locations, one of the children is considered to be on top of or raised over the others thus obscuring them. Output to areas covered by other windows is suppressed by the window system unless the window has backing store. If a window is obscured by a second window, the second window obscures only those ancestors of the second window, which are also ancestors of the first window.
子窗口可以比其父窗口大。也就是说，子窗口的一部分或全部可以超出父窗口的边界，但窗口的所有输出都被其父窗口剪裁。如果一个窗口的多个子窗口有重叠的位置，则其中一个子窗口被认为位于其他子窗口之上或高于其他子窗口，从而使它们变得模糊。窗口系统禁止输出到其他窗口覆盖的区域，除非该窗口有后备存储器。如果一个窗口被第二个窗口遮住，那么第二个窗口只会遮住第二个窗口的祖先，这些祖先也是第一个窗口的祖先。
A window has a border zero or more pixels in width, which can be any pattern (pixmap) or solid color you like. A window usually but not always has a background pattern, which will be repainted by the window system when uncovered. Child windows obscure their parents, and graphic operations in the parent window usually are clipped by the children.
窗口有宽度为零或多个像素边框，可以是您喜欢的任何图案（pixmap）或纯色。一个窗口通常（但不总是）有一个背景图案，当打开时，窗口系统将重新绘制该图案。子窗口使其父窗口变得模糊，父窗口中的图形操作通常被子窗口剪切。
Each window and pixmap has its own coordinate system. The coordinate system has the X axis horizontal and the Y axis vertical with the origin [0, 0] at the upper-left corner. Coordinates are integral, in terms of pixels, and coincide with pixel centers. For a window, the origin is inside the border at the inside, upper-left corner.
每个窗口和pixmap都有自己的坐标系。坐标系的X轴水平，Y轴垂直，原点[0，0]位于左上角。坐标是完整的，以像素为单位，并且与像素中心重合。对于窗口，原点在左上角的边框内。
X does not guarantee to preserve the contents of windows. When part or all of a window is hidden and then brought back onto the screen, its contents may be lost. The server then sends the client program an Expose event to notify it that part or all of the window needs to be repainted. Programs must be prepared to regenerate the contents of windows on demand.
X不保证保留windows的内容。当窗口的一部分或全部被隐藏，然后又回到屏幕上时，它的内容可能会丢失。然后，服务器向客户机程序发送一个公开事件，通知它需要重新绘制部分或全部窗口。程序必须准备好按需重新生成windows的内容。
X also provides off-screen storage of graphics objects, called pixmaps. Single plane (depth 1) pixmaps are sometimes referred to as bitmaps. Pixmaps can be used in most graphics functions interchangeably with windows and are used in various graphics operations to define patterns or tiles. Windows and pixmaps together are referred to as drawables.
X windows还提供图形对象的屏幕外存储，称为pixmaps。单平面（深度1）像素贴图有时也称为位图。Pixmaps可以在大多数图形功能中与windows互换使用，并用于各种图形操作来定义图案或分幅。Windows和pixmap一起被称为drawables。
Most of the functions in Xlib just add requests to an output buffer. These requests later execute asynchronously on the X server. Functions that return values of information stored in the server do not return (that is, they block) until an explicit reply is received or an error occurs. You can provide an error handler, which will be called when the error is reported.
Xlib中的大多数函数只是将请求添加到输出缓冲区。这些请求稍后在X服务器上异步执行。返回存储在服务器中的信息值的函数在收到显式答复或发生错误之前不会返回（即，它们会阻塞）。您可以提供一个错误处理程序，当报告错误时将调用该处理程序。
If a client does not want a request to execute asynchronously, it can follow the request with a call to XSync() , which blocks until all previously buffered asynchronous events have been sent and acted on. As an important side effect, the output buffer in Xlib is always flushed by a call to any function that returns a value from the server or waits for input.
如果客户机不希望请求异步执行，它可以在请求之后调用XSync（），该调用将阻塞，直到所有先前缓冲的异步事件都已发送并对其执行操作。作为一个重要的副作用，Xlib中的输出缓冲区总是通过调用任何从服务器返回值或等待输入的函数来刷新。
Many Xlib functions will return an integer resource ID, which allows you to refer to objects stored on the X server. These can be of type Window, Font, Pixmap, Colormap, Cursor, and GContext, as defined in the file <X11/X.h>. These resources are created by requests and are destroyed (or freed) by requests or when connections are closed. Most of these resources are potentially sharable between applications, and in fact, windows are manipulated explicitly by window manager programs. Fonts and cursors are shared automatically across multiple screens. Fonts are loaded and unloaded as needed and are shared by multiple clients. Fonts are often cached in the server. Xlib provides no support for sharing graphics contexts between applications.
许多Xlib函数将返回一个整数资源ID，这允许您引用存储在X服务器上的对象。这些类型可以是Window、Font、Pixmap、Colormap、Cursor和GContext，如文件<X11/X.h>中所定义的。这些资源由请求创建，并在请求或连接关闭时销毁（或释放）。这些资源中的大多数都可能在应用程序之间共享，实际上，窗口是由窗口管理器程序显式地操作的。字体和光标在多个屏幕上自动共享。根据需要加载和卸载字体，并由多个客户端共享。字体通常缓存在服务器中。Xlib不支持在应用程序之间共享图形上下文。
Client programs are informed of events. Events may either be side effects of a request (for example, restacking windows generates Expose events) or completely asynchronous (for example, from the keyboard). A client program asks to be informed of events. Because other applications can send events to your application, programs must be prepared to handle (or ignore) events of all types.
向客户端程序通知事件。事件可能是请求的副作用（例如，重新生成windows 暴露的事件），也可能是完全异步的（例如，通过键盘）。客户端程序要求通知事件。因为其他应用程序可以向您的应用程序发送事件，所以程序必须准备好处理（或忽略）所有类型的事件。
Input events (for example, a key pressed or the pointer moved) arrive asynchronously from the server and are queued until they are requested by an explicit call (for example, XNextEvent() or XWindowEvent()). In addition, some library functions (for example, XRaiseWindow()) generate Expose and ConfigureRequest events. These events also arrive asynchronously, but the client may wish to explicitly wait for them by calling XSync() after calling a function that can cause the server to generate events.
输入事件（例如，按下键或移动指针）从服务器异步到达，并在队列中等待显式调用（例如，XNextEvent（）或XWindowEvent（））。此外，一些库函数（例如，XRaiseWindow（））生成公开和配置请求事件。这些事件也会异步到达，但客户机可能希望在调用可导致服务器生成事件的函数后，通过调用XSync（）显式地等待它们。
1.2. Errors
1.2 错误状态
Some functions return Status, an integer error indication. If the function fails, it returns a zero. If the function returns a status of zero, it has not updated the return arguments. Because C does not provide multiple return values, many functions must return their results by writing into client-passed storage. By default, errors are handled either by a standard library function or by one that you provide. Functions that return pointers to strings return NULL pointers if the string does not exist.
有些函数返回状态，一个整数错误指示。如果函数失败，则返回零。如果函数返回的状态为零，则它没有更新返回参数。由于C不提供多个返回值，许多函数必须通过写入客户端传递的存储来返回结果。默认情况下，错误由标准库函数或您提供的库函数来处理。如果字符串不存在，返回指向字符串指针的函数将返回空指针。
The X server reports protocol errors at the time that it detects them. If more than one error could be generated for a given request, the server can report any of them.
X服务器在检测到协议错误时报告这些错误。如果一个给定的请求可能产生多个错误，服务器可以报告其中任何一个错误。
Because Xlib usually does not transmit requests to the server immediately (that is, it buffers them), errors can be reported much later than they actually occur. For debugging purposes, however, Xlib provides a mechanism for forcing synchronous behavior (see "Enabling or Disabling Synchronization"). When synchronization is enabled, errors are reported as they are generated.
因为Xlib通常不会立即将请求传输到服务器（也就是说，它会缓冲这些请求），所以报告错误的时间可能比实际发生的时间晚得多。但是，出于调试目的，Xlib提供了一种强制同步行为的机制（请参阅“Enabling or Disabling Synchronization”）。启用同步时，会在生成错误时报告错误。
When Xlib detects an error, it calls an error handler, which your program can provide. If you do not provide an error handler, the error is printed, and your program terminates.
当Xlib检测到错误时，它调用一个错误处理程序，您的程序可以提供这个处理程序。如果不提供错误处理程序，则会打印错误，并终止程序
1.3. Standard Header Files
1.3 标准头文件
The following include files are part of the Xlib standard:
- X11/Xlib.h
This is the main header file for Xlib. The majority of all Xlib symbols are declared by including this file. This file also contains the preprocessor symbol XlibSpecificationRelease. This symbol is defined to have the 6 in this release of the standard. (Release 5 of Xlib was the first release to have this symbol.)
- X11/X.h
This file declares types and constants for the X protocol that are to be used by applications. It is included automatically from X11/Xlib.h, so application code should never need to reference this file directly.
- X11/Xcms.h
This file contains symbols for much of the color management facilities described in "Color Management Functions". All functions, types, and symbols with the prefix ``Xcms'', plus the Color Conversion Contexts macros, are declared in this file. X11/Xlib.h must be included before including this file.
- X11/Xutil.h
This file declares various functions, types, and symbols used for inter-client communication and application utility functions, which are described in "Inter-Client Communication Functions" and "Application Utility Functions". X11/Xlib.h must be included before including this file.
- X11/Xresource.h
This file declares all functions, types, and symbols for the resource manager facilities, which are described in "Resource Manager Functions". X11/Xlib.h must be included before including this file.
- X11/Xatom.h
This file declares all predefined atoms, which are symbols with the prefix ``XA_''.
- X11/cursorfont.h
This file declares the cursor symbols for the standard cursor font, which are listed in X Font Cursors. All cursor symbols have the prefix ``XC_''.
- X11/keysymdef.h
This file declares all standard KeySym values, which are symbols with the prefix ``XK_''. The KeySyms are arranged in groups, and a preprocessor symbol controls inclusion of each group. The preprocessor symbol must be defined prior to inclusion of the file to obtain the associated values. The preprocessor symbols are XK_MISCELLANY, XK_LATIN1, XK_LATIN2, XK_LATIN3, XK_LATIN4, XK_KATAKANA, XK_ARABIC, XK_CYRILLIC, XK_GREEK, XK_TECHNICAL, XK_SPECIAL, XK_PUBLISHING, XK_APL, XK_HEBREW, XK_THAI, and XK_KOREAN.
- X11/keysym.h
This file defines the preprocessor symbols XK_MISCELLANY, XK_LATIN1, XK_LATIN2, XK_LATIN3, XK_LATIN4, and XK_GREEK and then includes X11/keysymdef.h.
- X11/Xlibint.h
This file declares all the functions, types, and symbols used for extensions, which are described in Extensions. This file automatically includes X11/Xlib.h.
- X11/Xproto.h
This file declares types and symbols for the basic X protocol, for use in implementing extensions. It is included automatically from X11/Xlibint.h, so application and extension code should never need to reference this file directly.
- X11/Xprotostr.h
This file declares types and symbols for the basic X protocol, for use in implementing extensions. It is included automatically from X11/Xproto.h, so application and extension code should never need to reference this file directly.
- X11/X10.h
This file declares all the functions, types, and symbols used for the X10 compatibility functions, which are described in Compatibility Functions.
1.4. Generic Values and Types
1.4 泛型值和类型
The following symbols are defined by Xlib and used throughout the manual:
- Xlib defines the type Bool and the Boolean values True and False .
- None is the universal null resource ID or atom.
- The type XID is used for generic resource IDs.
- The type XPointer is defined to be char* and is used as a generic opaque pointer to data.
1.5. Naming and Argument Conventions within Xlib
1.5 Xlib中的命名和参数约定
Xlib follows a number of conventions for the naming and syntax of the functions. Given that you remember what information the function requires, these conventions are intended to make the syntax of the functions more predictable.
Xlib遵循许多函数的命名和语法约定。假设您记住了函数需要什么信息，这些约定旨在使函数的语法更加可预测。
The major naming conventions are:
主要的命名约定是：
- To differentiate the X symbols from the other symbols, the library uses mixed case for external symbols. It leaves lowercase for variables and all uppercase for user macros, as per existing convention.
-
为了区分X符号和其他符号，库对外部符号使用混合大小写。根据现有惯例，变量保留小写，用户宏保留大写。
- All Xlib functions begin with a capital X.
-
所有Xlib函数都以大写X开头
- The beginnings of all function names and symbols are capitalized.
-
所有函数名和符号的开头都大写。
- All user-visible data structures begin with a capital X. More generally, anything that a user might dereference begins with a capital X.
-
所有用户可见的数据结构都以大写的X开头。更一般地说，用户可能取消引用的任何内容都以大写X开头。
- Macros and other symbols do not begin with a capital X. To distinguish them from all user symbols, each word in the macro is capitalized.
-
宏和其他符号不以大写X开头。为了与所有用户符号区分开来，宏中的每个单词都大写。
- All elements of or variables in a data structure are in lowercase. Compound words, where needed, are constructed with underscores (_).
- The display argument, where used, is always first in the argument list.
- All resource objects, where used, occur at the beginning of the argument list immediately after the display argument.
- When a graphics context is present together with another type of resource (most commonly, a drawable), the graphics context occurs in the argument list after the other resource. Drawables outrank all other resources.
- Source arguments always precede the destination arguments in the argument list.
- The x argument always precedes the y argument in the argument list.
- The width argument always precedes the height argument in the argument list.
- Where the x, y, width, and height arguments are used together, the x and y arguments always precede the width and height arguments.
- Where a mask is accompanied with a structure, the mask always precedes the pointer to the structure in the argument list.
1.6. Programming Considerations
1.6 编程注意事项
The major programming considerations are:
- Coordinates and sizes in X are actually 16-bit quantities. This decision was made to minimize the bandwidth required for a given level of performance. Coordinates usually are declared as an int in the interface. Values larger than 16 bits are truncated silently. Sizes (width and height) are declared as unsigned quantities.
- Keyboards are the greatest variable between different manufacturers' workstations. If you want your program to be portable, you should be particularly conservative here.
- Many display systems have limited amounts of off-screen memory. If you can, you should minimize use of pixmaps and backing store.
- The user should have control of his screen real estate. Therefore, you should write your applications to react to window management rather than presume control of the entire screen. What you do inside of your top-level window, however, is up to your application. For further information, see "Inter-Client Communication Functions" and the Inter-Client Communication Conventions Manual.
1.7. Character Sets and Encodings
1.7 字符集和编码
Some of the Xlib functions make reference to specific character sets and character encodings. The following are the most common:
- X Portable Character Set .IP A basic set of 97 characters, which are assumed to exist in all locales supported by Xlib. This set contains the following characters:
a..z A..Z 0..9 !"#$%&'()*+,-./:;<=>?@[\\]^_`{|}~ <space>, <tab>, and <newline>
This set is the left/lower half of the graphic character set of ISO8859-1 plus space, tab, and newline. It is also the set of graphic characters in 7-bit ASCII plus the same three control characters. The actual encoding of these characters on the host is system dependent.
- Host Portable Character Encoding
The encoding of the X Portable Character Set on the host. The encoding itself is not defined by this standard, but the encoding must be the same in all locales supported by Xlib on the host. If a string is said to be in the Host Portable Character Encoding, then it only contains characters from the X Portable Character Set, in the host encoding.
- Latin-1
The coded character set defined by the ISO8859-1 standard.
- Latin Portable Character Encoding
The encoding of the X Portable Character Set using the Latin-1 codepoints plus ASCII control characters. If a string is said to be in the Latin Portable Character Encoding, then it only contains characters from the X Portable Character Set, not all of Latin-1.
- STRING Encoding
Latin-1, plus tab and newline.
- POSIX Portable Filename Character Set
The set of 65 characters, which can be used in naming files on a POSIX-compliant host, that are correctly processed in all locales. The set is:
a..z A..Z 0..9 ._-
1.8. Formatting Conventions
1.8 格式惯例
Xlib --- C Language X Interface uses the following conventions:
- This HTML version of the manual uses formatting conventions that are slighty different of the original (troff) manual:
Global symbols are either printed in bold, either hyperlinked or both. Functions name are printed in bold, suffixed with () and hyperlinked to their definition page. Symbols define in include files are rendered with a bold typeface. Structure names are printed in regular type and are hyperlinked to their definition. When declared and defined, function arguments are printed in bold, and also in the following explanatory text.
- Each function is introduced by a general discussion that distinguishes it from other functions. The function declaration itself follows, and each argument is specifically explained. Although ANSI C function prototype syntax is not used, Xlib header files normally declare functions using function prototypes in ANSI C environments. General discussion of the function, if any is required, follows the arguments. Where applicable, the last paragraph of the explanation lists the possible Xlib error codes that the function can generate. For a complete discussion of the Xlib error codes, see "Using the Default Error Handlers".
- To eliminate any ambiguity between those arguments that you pass and those that a function returns to you, the explanations for all arguments that you pass start with the word specifies or, in the case of multiple arguments, the word specify. The explanations for all arguments that are returned to you start with the word returns or, in the case of multiple arguments, the word return. The explanations for all arguments that you can pass and are returned start with the words specifies and returns.
- Any pointer to a structure that is used to return a value is designated as such by the _return suffix as part of its name. All other pointers passed to these functions are used for reading only. A few arguments use pointers to structures that are used for both input and output and are indicated by using the _in_out suffix.