Xlib Reference Manual for Version 11 of the X Window System

K

Xlib Release 3 Update

This appendix is an update to Volume Two, Xlib Reference Manual. It describes the changes to Xlib, and to application writing standards in general, that took place in Release 3. Next, there is a description of corrections to the book based on Release 3 protocol clarifications. Some of these apply to Release 2 as well.

New Routines

Five new routines have been added to Xlib in Release 3. They are all very simple, and in fact four of them could actually have been simple macros. Here are their definitions:

Example K-1. Code for routines added to Xlib in Release 3 Update

long XMaxRequestSize(dpy)
    Display *dpy;
{
    return dpy->max_request_size;
}
char *XResourceManagerString(dpy)
      Display *dpy;
{
      return dpy->xdefaults;
}
unsigned long XDisplayMotionBufferSize(dpy)
    Display *dpy;
{
    return dpy->motion_buffer;
}
XDisplayKeycodes(dpy, min_keycode_return, max_keycode_return)
    Display *dpy;
    int *min_keycode_return, *max_keycode_return;
{
      *min_keycode_return = dpy->min_keycode;
      *max_keycode_return = dpy->max_keycode;
}
VisualID XVisualIDFromVisual(visual)
    Visual *visual;
{
    return visual->visualid;
}

All of these routines were added to allow applications access to members of structures that are intended to be opaque, namely Display and visual. Applications should reference only the pointers to these structures. When applications are coded without direct reference to members of the opaque structures, this allows the X Consortium or an Xlib implementor on a particular system to change the contents of the Display and visual structures if necessary.

XMaxRequestSize tells you the maximum request size on the server, in units of four bytes. This would be used when reading and writing properties, since the maximum property data length that can be stored in a single property is one unit (four bytes) less than the value returned by XMaxRequestSize.

The XResourceManagerString routine accesses the RESOURCE_MANAGER property resource database string that is stored in the server with xrdb, and returned to the client in the Display structure by XOpenDisplay. This is used by applications that use the resource manager routines to merge appropriate program and user defaults. All serious applications will do this.

XDisplayMotionBufferSize tells you whether the server has a motion history buffer, and if it does, how large it is in units of events. Most current servers do not have a motion history buffer, and in that case this function will return 0.

XDisplayKeycodes lets you determine the range of valid keycodes on a particular server. This should not be needed in most applications that use the standard keyboard interface through keysyms. It is only needed if you intend to change the mapping between keycodes and keysyms (server-wide) or perhaps to process key events using keycodes in a nontext application such as for music.

XVisualIDFromVisual is provided for completeness. It should not be necessary in most applications, and certainly not in those that use XGetVisualInfo or XMatchvisualInfo to determine color characteristics, since these routines return the XVisualInfo structure which contains the VisualID.

Command Line Options

The convention until Release 3 has been that any command line argument containing: was a display specification and any argument beginning with = was a geometry specification. These no longer hold, and none of the core clients now operate this way. Applications should require an explicit –display or –geometry option. The = in the geometry specification is now optional.

Fonts

There is no standard that specifies the fonts a server must provide. However, this should not be a portability problem for properly written applications, because fonts should be resources that can be specified by the user or system administrator. You'll probably want to “build in” default font names, either in an app-defaults file or in your code, but your code ought to be robust enough to fall back on the default font in the GC if all else fails.

We bring this up because the font environment provided in the MIT distribution has changed substantially since Release 2. In Release 3, a unified family of fonts has been donated by Adobe, Inc. and BitStream, Inc. These include fonts of various sizes in the Courier, Times Roman, Helvetica, New Century Schoolbook, and Bitstream Charter families in regular weight, bold, and italic, and symbol fonts in various sizes from Adobe/DEC are also provided. Furthermore, font aliasing has been added so that font names in code and resource files can be long enough to fully describe a font, but the actual files containing the fonts may be 14 characters or less for compatibility with System V. An organized font-naming scheme has also been instituted.

The new font names look like this:*

    -adobe-courier-bold-o-normal--10-100-75-75-m-60-iso8859-1

Because the font names that applications and users must specify are now so long, wildcards are now permitted as arguments to the Xlib routines XLoadFont, XQueryFont, and XLoadQueryFont. They were already permitted for the routines XListFonts and XListFontsWithInfo.

To specify a font, you specify only the fields that are important to you. For example, if you wanted to use a 12 point Roman Courier font for an xterm, you could use the either of the following names:

    -adobe-courier-medium-r-normal--12-120-75-75-m-70-iso8859-l
    *-courier-*-r-*-l20-*

Note that you should match the point size field which is measured in tenths of a point (the 120 in this example) rather than the pixel size field (the 12). This allows your defaults to work properly on tubes of different resolution. For example, to specify a 24 point, normal italic Charter,

    *-charter-medium-i-*-240-*

will match either:

    -bitstream-charter-medium-i-normal--25-240-75-75-p-136-iso8859-l
    -bitstream-charter-medium-i-normal--33-240-100-100-p-179-iso8859-l

depending on whether the 75 dpi or 100 dpi font directory comes first in your font path. This example also demonstrates why the pixel size should not be used when wildcarding. On a 75 dpi monitor, a 24 point font will be 25 pixels tall; on a 100 dpi monitor, it will be 33 pixels tall.

If your application depends on the Release 2 fonts, they can be used with a Release 3 server by placing the Release 2 fonts in a directory and allowing users to add it to their font path (see the mkfontdir man page). If you have particular fonts that you want to use, and you have them in source (BDF) form, then most server vendors should supply a font compiler with their server, allowing you to import fonts.

Internal and Invisible Changes to Xlib

Xlib has been modified internally so that it will compile and run on Cray machines. This does not change the programming interface. Untested support for Mips computers has also been contributed.

Other internal changes include improvements to Graphics Context cache flushing. The region code was improved, including fix for overflow on complex regions.

Small Interface Changes

The routines XChangeProperty and XGetWindowProperty now take care of converting arrays of chars, shorts, and longs to and from the formats required by the protocol (8-bit, 16-bit, and 32-bit signed integers respectively). XGetWindowProperty now always mallocs space for its return data even if the data has zero elements.

XLookupString now has list of key bindings per display, can cope with modifier mapping changes, handles upper and lower case of all Latin-1 keysyms, doesn't convert nonLatin-1 keysyms, understands Control 2-8 and /, and uses the preferred protocol definition for CapsLock.

XrmPutFileDatabase will write file with proper special char quoting.

Server Fixes

Some problems that existed in sample server code affected application programming under Release 2. You may wish to inspect programs for workarounds for these problems. We cannot list and explain all the bugs that were found and fixed; see the CHANGES file in the appropriate directory of the X distribution. However, the following changes to the device-independent (dix) part of the server were among the most likely to affect client programming:

• The AllocColorPlanes request has been fixed to allow allocation of all planes at once.
• Delayed/Buffered writes for client events implemented. Delayed writes are simply a performance improvement; the server now queues all events generated by a single request for greater network efficiency. Buffered writes fix a bug that appeared when reading long properties from the server. Client connections would be severed when the client refused or was slow in reading a long message from the server.
• SelectionClear events are now sent to the selection owner (set by XSetSelectionOwner, not the window creator.
• Font routines and color name lookup routines now fold upper case in names to lower case. Case is no longer significant in the color database, and items in the database differing only in case have been removed.
• Save under support has been added to the device-independent portion of the server. This code supplies save unders to any server which has backing store but not save unders implemented in the device-dependent portion.
• Mixing window gravity and bit gravity has been fixed.
• Many other specious requests also generate Value errors now.

The Xmu library

A new miscellaneous utilities library has been placed on the X distribution tape. This library is not part of the Xlib standard. It contains routines which only use public interfaces so that it may be layered on top of any proprietary implementation of Xlib or Xt.

It is intended to support clients in the MIT distribution; vendors may choose not to distribute this library if they wish. Therefore, applications developers who depend on this library should be prepared to treat it as part of their software base when porting.

The following routines apply to Xlib (there are a few not described here that are for use with the X Toolkit):

• Routines to cache atoms, avoiding multiple server round-trips. XmuMakeAtom creates and initializes an opaque AtomRec. XmuInternAtom fetches an atom from cache or server. XmuInternStrings fetches multiple atoms as strings. XmuGetAtomName returns name of an atom. XmuNameOfAtom returns name from an AtomPtr.
• XmuCreatePixmapFromBitmap routine converts a bitmap to a pixmap. The routine uses XCopyPlane).
• XmuConvertStandardSelection converts a known selection into the appropriate target type.
• XmuPrintDefaultErrorMessage prints a nice error that looks like the usual message. Returns 1 if the caller should consider exiting, else 0.
• XmuDrawRoundedRectangle draws a rounded rectangle, x, y, w, h are the dimensions of the rectangle, ew and eh are the sizes of a bounding boxes that each corner is drawn inside of.
• XmuReadBitmapDataFromFile reads X10 or X11 format bitmap files and return data.

Release 3 Protocol Clarifications

The following changes are not errors, per se. They reflect clarifications of the protocol specification made in Release 3. These changes, where noted, were also true in Release 2.

Page 36

The return type from XAddPixel is deleted. XAddPixel has its value argument changed from int to long.

Page 53

XChangeActivePointerGrab is capable of generating a BadValue error.

Page 70

XCheckMaskEvent has its mask argument changed from unsigned long to long.

Page 73

XCheckWindowEvent has its mask argument changed from int to long.

Page 77

On the XClearArea page, the first sentence of the third paragraph should end: “ ... the rectangle is tiled with a plane_mask of all 1's, a function of GXcopy, and a subwindow_mode or ClipByChildren.” This should be true in Release 2.

Page 90

XCopyGC now generates a BadValue error when bits outside the set of valid GC mask bits are set.

Page 92

The plane argument of XCopyPlane must be a plane that exists in the source drawable, or a BadValue error is generated.

Page 213

On the second page of XGet Image, the first sentence should say that the source window must be viewable, not just mapped (all its ancestors also must be mapped). The page should also mention that the pointer cursor is not included in the image. This is also true in Release 2.

Page 219

The XTimeCoord structure has its x and y members changed from type unsigned short to short.

Page 248

The XGrabButton page should mention that the call overrides all previous passive grabs by the same client on the same key/button combinations on the same window. This is also true in Release 2.

Page 255

For XGrabPointer, the constant GrabNotViewable is returned for the reasons given at the bottom of the page, but also if the confine_to window is completely outside the root window. This was true in Release 2.

Page 284

The string that XLookupString returns in the buffer argument is in Latin-1 encoding, not necessarily in ASCII. (Latin-1 uses codes 128 to 255 to specify foreign characters, while ASCII uses only up to 127. ASCII is a subset of Latin-1.)

Page 291

The event_mask argument of XMaskEvent changes from unsigned long to long.

Page 349

The XReparentWindow page should say that the reparenting leaves unchanged the absolute coordinates (relative to the root window) of the upper-left outer corner of the window. This was true in Release 2.

Page 391

The event_mask argument of XSelectInput changes from type unsigned long to type long.

Page 393

The event_mask argument of XSendEvent changes from type unsigned long to type long. Also, XSendEvent can now generate a BadValue error if the event type sent is not valid in the core or an extension.

Page 410

The error_code, request_code, and minor_code members of XErrorEvent have been changed from type char to type unsigned char.

Page 429

In the paragraph about server restrictions on the XSetModifierMapping page, it should mention that one restriction may be that it might not be possible to disable auto-repeat on certain keys. This is also true in Release 2.

Page 481, 482

XUngrabButton and XUngrabKey may generate a BadValue error if the button or keycode argument is invalid.

Page 484

The XUngrabPointer pointer should mention that a grab is released automatically if the confine_to window is moved completely outside the root window. This is also true in Release 2.

Page 547

The XClientMessageEvent structure contains a union of three data types. The 1[5] member has been changed from type int to type long.

Page 605

The XTimeCoord structure has its x and y members changed from type unsigned short to short.

Page 643

As described above, the fonts provided in Release 3 are no longer those shown in the book.

*Most of this description of the new font-naming scheme was provided by Jim Fulton of the X Consortium.