This appendix describes the changes between recent releases of X Version 11. It begins with the changes in the most recent version and works back. There were no changes in the underlying X protocol.
The major additions in Release 5 were support for internationalization and support for device-independent color (the X Color Management System). There were also a few new resource management functions added mainly to support the R5 changes in the Xt Intrinsics.
The largest new part of X11R5 is the support for writing internationalized programs. An internationalized application is one that runs, without changes to the binary, in any given “locale.” Among other things, this means that a program must display all text in the user's language, accept input of all text in that same language, and display times, dates, and numbers in the user's accustomed format.
The internationalization of terminal-based programs is a problem that has been satisfactorily solved where terminals exist that can display and accept input for a particular language. The ANSI-C library contains mechanisms for this terminal-based internationalization, and X11R5 internationalization is based on these mechanisms. Internationalized text input is based on the concept of an “input method,” which is a specialized program that allows user input of a particular language. Input methods are essential for Asian languages where there are more symbols than can appear on a keyboard.
Before beginning, note that the internationalization features of X11R5 are not self contained, and therefore may not work on all systems. If your system does not have the ANSI-C internationalization features, you may be able to make do with alternatives provided with the Xlib sample distribution and by contributed libraries, but these have not been thoroughly tested and you may encounter difficulties. In ANSI-C internationalization, the C library reads a “localization database” customized for each locale. Many systems (systems sold in the U.S., at least) support ANSI-C internationalization, but do not ship databases for any but a default locale.
Xlib now provides:
Simple locale management functions.
Routines for internationalized text-drawing.
Font set handling functions.
Font set metric and string measuring functions.
String drawing functions.
Respecification of many Xlib functions to clarify their handling of strings in internationalized applications.
New functions to support internationalized window manager and text properties for interclient communication.
New resource manager functions to support localized databases.
Respecifications of many resource manager functions to make their behavior in internationalized applications clear.
New support for internationalized text input through input methods.
Two sample implementations of all the new Xlib internationalization functions.
The X11R5 distribution provides two different implementations of the new internationalization functions. The default implementation is named “Xsi” and is from the OMRON Corporation; the MIT distribution builds Xsi by default on all but Sony machines. Sony systems build the “Ximp” implementation from Fujitsu, Sony, and others. Both “Xsi” and “Ximp” implement the same specification, [63] but are mutually incompatible. In particular, the localization files they read are in very different formats.
Xcms defines a new syntax for the color strings used throughout Xlib, and provides a programming interface that allows extremely precise control over the allocation of colors. One feature of Xcms is the provision for a database that maps color names to device-independent color specifications. This database is read by Xlib rather than by the X server. No sample Xlib-side database is provided in the MIT distribution. There is also a new part of the ICCCM, the X Device Color Characterization Conventions (XDCCC), which are a standard format for new root window properties that contains the information about the physical characteristics of the screen necessary to support the conversion of device-independent color specifications into device-dependent values.
Several existing Xlib functions were modified to support this new standard syntax for color strings. The syntax allows color specification in several international standard color spaces including CIElab, CIEluv, and a simple color space called TEKhvc. RGB is also still supported.
The character ? may now be used in resource files to wildcard a single component of a resource name. This allows greater flexibility in the specification of resources.
Resource files may now include other files with a C-like #include syntax.
A new function, XrmSetDatabase(), associates a resource database with a display, and another new function, XrmGetDatabase(), queries the database of a display.
A function, XrmLocaleOfDatabase(), returns the locale of a resource database.
Two new functions, XrmCombineDatabase() and XrmCombineFileDatabase(), merge the contents of two resource databases. They are more flexible than the existing XrmMergeDatabase.
A new function, XrmEnumerateDatabase(), iterates through the items in a resource database.
A new type, XPointer, has been defined to replace caddr_t, which is not a standard type and is therefore not necessarily portable. (The type XtPointer was added to the X11R4 X Toolkit for the same reason.) An XPointer is a typedef for a char *, and occurs most noticeably in the XrmValue and XrmOptionDescRec structures.
The X11R5 distribution installs the file XKeysymDB in /usr/lib/X11. This file contains a list of vendor-private keysyms names and their corresponding values. It is required for the correct operation of many Motif applications and any application that wants to make use of vendor-specific keys on a keyboard. This file was in the X11R4 distribution, but was not installed by default.
A new function, XFlushGC(), forces Xlib to write its cached GC changes to the X server. For efficiency, Xlib combines multiple GC changes into a single server request whenever multiple changes to a GC occur before a use of that GC. It is possible for extensions to X to use GCs in ways that Xlib is not aware of, and this can mean that requests made by the extension client library may not operate with the expected contents of the GC. XFlushGC() is provided to address this problem.
The XErrorEvent structure used by Xlib contains only 32 bits of data specific to the error, which is usually used to return a resource ID. This is sufficient for all core X errors, but may not be enough for extensions (notably PEX). There is plenty of room in the protocol error structure that is transmitted between server and client, but Xlib truncates this information when converting the protocol error into an XErrorEvent structure. Since the XErrorEvent structure is smaller than the XEvent union of which it is a part, an XErrorEvent can be cast into a larger structure with more room for error values, and the workaround provided by X11R5 takes advantage of this fact. X11R5 provides two new functions, XESetWireToError() and XESetPrintErrorValues(), which allow an extension library to register a function to convert a protocol error into some type longer than an XErrorEvent, and to display an error message that makes use of the additional data in the special error message.
We will begin by describing the new functions, and then we will describe the small existing interface changes.
Because of the adoption of the ICCCM (Inter-Client Communication Conventions Manual) as an X Consortium standard, several Xlib structures had to be changed, and therefore, several of the R3 routines are now superceded by new routines. All R3 routines are still supported, but the superseded routines should not be used in new applications because they do not meet the current conventions. Table H-1 lists the old and new routines.
Table H-1. Superseded R3 Routines and New R4 Routines
Superseded Routine | New Routine | Change |
|---|---|---|
XSetStandardProperties | XSetWMProperties | Added WM_HINTS and WM_CLASS , format changes |
XSetNormalHints | XSetWMNormalHints | New fields in XSizeHints |
XGetNormalHints | XGetWMNormalHints | New fields in XSizeHints |
XSetZoomHints | (No replacement) | No longer part of ICCCM |
XGetZoomHints | (No replacement) | No longer part of ICCCM |
XSetSizeHints | XSetWMSizeHints | New fields in XSizeHints |
XGetSizeHints | XGetWMSizeHints | New fields in XSizeHints |
XStoreName | XSetWMName | Property format change |
XFetchName | XGetWMName | Property format change |
(No R3 equivalent) | XGetCommand | Convenience routine for XGetWindowProperty |
XSetIconName | XSetWMIconName | Property format change |
XGetIconName | XGetWMIconName | Property format change |
XGeometry | XWMGeometry | New fields and arguments |
XGetStandardColormap | XGetRGBColormaps | New fields in XStandardColormap |
XSetStandardColormap | XSetRGBColormaps | New fields in XStandardColormap |
XSetWMProperties() is the new interface for setting all required window manager properties. This function now sets the WM_HINTS and WM_CLASS properties, in addition to the properties set under R3 by XSetStandardProperties(). Furthermore, the window name and icon name arguments are now XTextProperty structures that can be filled with the new function XStringListToTextProperty(), described below.
All string properties to be set for the window manager have been changed to use XTextProperty structures so that they can use non-Western encodings (which require more than the eight bits of data provided in the R3 STRING property). For this reason, XGetWMIconName() replaces XGetIconName(), XSetWMIconName() replaces XSetIconName(), XGetWMName() replaces XFetchName(), and XSetWMName() replaces XStoreName().
XGetCommand() was added to make it easier for window managers to read the XA_WM_COMMAND property. In R3, XSetCommand() was provided but no XGetCommand().
Three new fields have been added to the XSizeHints structure. Two, base_width and base_height, basically supercede the min_width and min_height fields. The x, y, width, and height fields of XSizeHints are no longer used. Instead these values are simply set when creating the top-level window (and the window manager gets these values through substructure redirection in CreateNotify and MapNotify events). The other new field, win_gravity, allows an application to specify that some other portion of the window is to be placed when the window manager allows the user to place windows. The purpose of this, for example, is to allow users that display languages that read from right to left to position the top-right corner of these terminals instead of their top-left corner.
XWMGeometry replaces XGeometry. XWMGeometry calculates geometry values for the top-level window, given a possibly incomplete user-specified geometry string and a complete application default geometry specified using an XSizeHints structure. XWMGeometry also returns a win_gravity value based on which corner of the top-level window the user or application specified, suitable for setting into the XSizeHints structure.
New fields have been added to the XStandardColormap structure to return the visual associated with the colormap and also to provide information about who is allowed to delete the colormap. To use the new fields, XGetStandardColormap() is superceded by XGetRGBColormaps() and XSetStandardColormap() is superceded by XSetRGBColormaps().
The following routines are completely new in R4.
XSetWMClientMachine() is used by clients to set a new property to be read with XGetWMClientMachine() by window or session managers. The property stores the name of the machine on which the client is running, as seen from the server, so that the session manager can stop and restart the client on the right machine. See Chapter 12, “Interclient Communication”
XSetWMProtocols() is used by clients to set a new property to be read with XGetWMProtocols() by the window manager. This property indicates which of a number of window manager-client protocols the client would like to take part in. Under these protocols, the window manager sends synthetic events to the client to notify the client of certain impending conditions, such as that the client has been granted the keyboard focus or is about to have one of its windows destroyed or that the entire client is about to be killed. See Chapter 12, “Interclient Communication”
XSetWMColormapWindows() is used by clients to set a new property to be read with XGetWMColormapWindows() by the window manager. This property tells the window manager that certain subwindows of the client have custom colormaps that will need installing. See Chapter 12, “Interclient Communication”
Five new routines are provided that allocate and zero the fields of structures used in setting the window manager hints: XAllocClassHint(), XAllocIconSize(), XAllocSizeHints(), XAllocStandardColormap(), and XAllocWMHints(). When using these routines, an application declares only a pointer to the structure and then uses one of these routines to allocate the memory. The purpose of doing this is to avoid having compiled-in structure sizes, so that fields can be added to these structures in later releases without causing binary incompatibility. See Chapter 12, “Interclient Communication”
XGetGCValues() reads most GC component values out of Xlib's local cache. It does not read the dash list or clip mask. See Chapter 5, “The Graphics Context”
XIconifyWindow() is to be called by the client to tell the window manager to iconify a window. Similarly, XWithdrawWindow() tells the window manager to unmap a window without iconifying it. These two routines were added to simplify compliance with the new ICCCM. XReconfigureWMWindow() is used by clients to reconfigure top-level windows--it works like XConfigureWindow() except that it handles stacking order changes correctly even if the window or some of its siblings have been reparented. See Chapter 12, “Interclient Communication”
As mentioned above, all of the R3 functions that write or read string properties have been superceded by R4 functions that provide a more flexible property format. All these new functions use the XTextProperty structure. Several routines that manipulate these structures are now provided: XFreeStringList(), XGetTextProperty(), XSetTextProperty(), XStringListToTextProperty(), and XTextPropertyToStringList(). See Chapter 12, “Interclient Communication”
XListDepths() and XListPixmapFormats() extract information from the Display structure. These are useful when you want to create a window or a pixmap that is not the default depth and not a depth of one plane.
XrmDestroyDatabase() destroys a resource database, a function that was missing in earlier releases.
The XScreenNumberOfScreen() function has also been added. It simply returns the screen integer corresponding to the specified pointer to a Screen structure. This function is listed with the macros in Appendix C, Macros, of Volume Two.
The following sections describe the changes in the areas of XOpenDisplay(), error handlers, nonstandard keysyms and keyboard groups, XReadBitmapFile(), resource specification syntax, and XrmParseCommand().
The use of unix as a hostname in the DISPLAY environment variable read by XOpenDisplay() is no longer part of the specification (for trademark reasons); use an empty hostname. In other words, setting DISPLAY to “:0.0” will instruct Xlib to make the best local connection to the server running on the same system as this client.
XSetErrorHandler() and XIOSetErrorHandler now return the previous error handler.
int (*XSetErrorHandler(handler))()
int (*handler)(Display *, XErrorEvent *)
int (*XSetIOErrorHandler(handler))()
int (*handler)(Display *);
|
In XGetErrorDatabaseText(), for an extension request, the extension name (as given by XInitExtension()) followed by a period (.) and the minor request protocol number is used for the message argument.
Keysyms that are not part of the Xlib standard can now be obtained by using XStringToKeysym() and XKeysymToString(). Note that the set of keysyms that are available in this manner and the mechanisms by which Xlib obtains them is implementation-dependent. (In the MIT sample implementation, the resource file /usr/lib/X11/XKeysymDB is used starting in R4. The keysym name is used as the resource name, and the resource value is the keysym value in uppercase hexadecimal.)
In XReadBitmapFile(), the ability to read X10 format is no longer required of an implementation. The ability to read other than the standard format is implementation-dependent.
As of R4, the BNF notation of a resource specification is now specified:
ResourceLine = Comment|ResourceSpec
Comment = "!" string|<empty line>
ResourceSpec = WhiteSpace ResourceName WhiteSpace ":" WhiteSpace value
ResourceName = [Binding] ComponentName {Binding ComponentName}
Binding = "."|"*"
WhiteSpace = {""|"Tab"}
ComponentName = {"a"-"z"|"A"-"Z"|"0"-"9"|"_"|"-"}
value = string
string = {<any character not including "\n">}
|
Note that elements enclosed in curly braces ({...}) indicate zero or more occurrences of the enclosed elements.
To allow values to contain arbitrary octets, the four-character sequence \nnn, where n is a digit in the range of 0 through 7 is recognized and replaced with a single byte that contains this sequence interpreted as an octal number. For example, a value containing a NULL byte can be stored by specifying \000.
In XrmParseCommand(), a new value, XrmoptionSkipNArgs, has been added to the XrmOptionKind enum. Note that XrmoptionSkipArg is equivalent to XrmoptionSkipNArgs with the XrmOptionDescRec.value field containing the value one. Note also that the value zero for XrmoptionSkipNArgs indicates that only the option itself is to be skipped.
In R4, the concept of keyboard groups has been introduced, and XLookupString() implements new semantics to support keyboard groups. Keyboard groups support having two complete sets of keysyms for a keyboard. Which set will be used can be toggled using a particular key. This is implemented by using the first two keysyms in the list for a key as one set and the next two keysyms as the second set.
The standard rules for obtaining a keysym from a KeyPress event make use of only the Group 1 and Group 2 keysyms; no interpretation of other keysyms in the list is given here. Which group to use is determined by modifier state. Switching between groups is controlled by the keysym named MODE SWITCH, by attaching that keysym to some keycode and attaching that keycode to any one of the modifiers Mod1 through Mod5. This modifier is called the “group modifier.” For any keycode, Group 1 is used when the group modifier is off and Group 2 is used when the group modifier is on.
Within a group, which keysym to use is also determined by modifier state. The first keysym is used when the Shift and Lock modifiers are off. The second keysym is used when the Shift modifier is on, when the Lock modifier is on and the second keysym is uppercase alphabetic, or when the Lock modifier is on and is interpreted as Shift Lock. Otherwise, when the Lock modifier is on and is interpreted as Caps Lock, the state of the Shift modifier is applied first to select a keysym, but if that keysym is lowercase alphabetic, then the corresponding uppercase keysym is used instead.
If the list of Keysyms (ignoring trailing NoSymbol entries) is a single keysym “K,” then the list is treated as if it were the list “K NoSymbol K NoSymbol.” If the list (ignoring trailing NoSymbol entries) is a pair of keysyms “K1 K2,” then the list is treated as if it were the list “K1 K2 K1 K2.” If the list (ignoring trailing NoSymbol entries) is a triple of keysyms “K1 K2 K3,” then the list is treated as if it were the list “K1 K2 K3 NoSymbol.” When an explicit “void” element is desired in the list, the value VoidSymbol can be used.
The first four elements of the list are split into two groups of keysyms. Group 1 contains the first and second keysyms; Group 2 contains the third and fourth keysyms. Within each group, if the second element of the group is NoSymbol, then the group should be treated as if the second element were the same as the first element, except when the first element is an alphabetic keysym “K” for which both lowercase and uppercase forms are defined. In that case, the group should be treated as if the first element were the lowercase form of “K” and the second element were the uppercase form of “K.”
No spatial geometry of the symbols on the key is defined by their order in the keysym list, although a geometry might be defined on a vendor-specific basis. The X server does not use the mapping between keycodes and keysyms. Rather it stores it merely for reading and writing by clients.
The modifier named Lock is intended to be mapped to either a Caps Lock or a Shift Lock key, but which one is left as application-specific and/or user-specific. However, it is suggested that the determination be made according to the associated keysym(s) of the corresponding keycode.