www.sbin.org

Xlib Programming Manual (O'Reilly & Associates, Inc.)

Release Notes

Changes from Release 4 to Release 5

Internationalization

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.

X Color Management System

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.

Resource Management

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.

Scalable Font Support

Miscellaneous Xlib Changes

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.

Changes from Release 3 to Release 4

New Routines

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, Xlib Reference Manual.

Existing Interface Changes

XOpenDisplay()

Error Handlers

int (*XSetErrorHandler(handler))()
      int (*handler)(Display *, XErrorEvent *)

int (*XSetIOErrorHandler(handler))()
      int (*handler)(Display *);

Nonstandard Keysyms

XReadBitmapFile()

Resource Specification Syntax

   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">}

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.

XrmParseCommand()

Keyboard Groups

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 KNoSymbol." 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 K3NoSymbol." 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.