www.sbin.org

[PreviousSection] [Back to Table of Contents] [Next Section]

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

The Xmu Library

The Xmu library provides a number of functions that combine Xlib functions in useful ways. This appendix summarizes the available functions. See Appendix J of Volume Two, Xlib Reference Manual, for detailed reference pages for each function. (After mid-1992, these reference pages may be moved to a new volume, Extensions and Utilities.)

The Xmu Library is a collection of miscellaneous (some might say random) utility functions that have been useful in building various applications and Xt Toolkit widgets. Though not defined by any X Consortium standard, this library is written and supported by MIT in the core distribution and therefore should be available on most machines.

The functions in Xmu are briefly described here in several categories: atom manipulation, error handlers, system utilities, window utilities, cursor utilities, color utilities, pixmap utilities, graphics functions, selection functions, character set functions, compound text functions, close display functions, event queue functions, and standard colormap functions. For detailed calling sequences for these functions, see Appendix J, The Xmu Library, of Volume Two, Xlib Reference Manual.

At each release, the number and variety of functions in this library have increased dramatically. Even if you are familiar with the contents of Xmu in an earlier release, it is worthwhile skimming this appendix.

Each of the groups of functions listed below has its own header file. The Xmu header files are located (by default on UNIX-based systems) in /usr/include/X11/Xmu.

Atom Functions

These functions allow an application to use various properties that do not have predefined atoms, without having to maintain a global variable to store the atom. Instead Xmu handles calling XInternAtom() on the first reference and caches the value for all further references. For example, after initializing Xmu's atom-caching facility (with the arcane invocation XmuInternAtom(display, XmuMakeAtom("NULL"))), you can get the atom for any property that Xmu knows about, such as CLIPBOARD, simply by using the phrase XA_CLIPBOARD(display).

Error Handler Functions

XmuPrintErrorMessage() prints an error message equivalent to Xlib's default error message for protocol errors. It returns a nonzero value if the caller should consider exiting; otherwise, it returns 0. This function can be used when you need to write your own error handler but need to print out an error from within that handler.

XmuSimpleErrorHandler() is an error handler function you can use in place of the default protocol error handler. It ignores BadWindow errors for XQueryTree() and XGetWindowAttributes() and ignores BadDrawable errors for XGetGeometry(); it returns 0 in those cases. Otherwise, it prints the default error message and returns a nonzero value if the caller should consider exiting and 0 if the caller should not exit.

System Utility Functions

XmuGetHostname() provides an operating-system-independent interface for getting the hostname of the system on which the client is running. This is useful for setting the WM_CLIENT_MACHINE property for the window manager.

Window Utility Functions

XmuScreenOfWindow() returns a pointer to the Screen structure that describes the screen on which the window was created.

XmuClientWindow() finds a window at or below the specified window which has a WM_STATE property. If such a window is found, it is returned; otherwise, the argument window is returned. This is used by window managers.

XmuUpdateMapHints() is a convenience routine for setting (by applications) and reading (by the window manager) the XA_WM_NORMAL_HINTS property. It clears the PPosition and PSize flags and sets the USPosition and USSize flags in the hints structure and then stores the hints for the window using XSetWMNormalHints() and returns True. If NULL is passed for the hints structure, then the current hints are read back from the window using XGetWMNormalHints() and are used instead and True is returned; otherwise, False is returned.

Cursor Utility Functions

XmuCursorNameToIndex takes the name of a standard cursor and returns its index in the standard cursor font. The cursor names are formed by removing the XC_ prefix from the symbolic constants for cursors listed in Appendix I, The Cursor Font, of Volume Two, Xlib Reference Manual.

Color Utilities

XmuDistinguishableColors compares two or more sets of RGB values and determines whether the colors are distinguishable.

XmuDistinguishablePixels compares two or more pixel values and determines whether the colors in the corresponding colormap cells are distinguishable.

Pixmap Utilities

XmuLocatePixmapFile creates a pixmap from a file located in a relative or absolute directory, possibly specified in an environment variable.

Graphics Functions

XmuDrawRoundedRectangle draws a rounded rectangle, given x, y, width, height dimensions of the overall rectangle, and ew and eh sizes of a bounding box that the corners are drawn inside of. This function simply calls Xlib's drawing routines.

XmuFillRoundedRectangle simply fills a shape similar to that drawn by XmuDrawRoundedRectangle, in the same way that XFillRectangle() fills.

XmuDrawLogo draws the "official" X Window System logo. The bounding box of the logo is given by x, y, width, and height.

XmuCreateStippledPixmap creates a two- by two-pixel pixmap of specified depth on the specified screen, with the top-left and bottom-right pixels drawn in the foreground pixel value and the other two drawn in the background. The pixmap is cached so that multiple requests share the same pixmap. The pixmap should be freed with XmuReleaseStippledPixmap to maintain correct reference counts.

XmuReadBitmapData reads a standard bitmap file description from the specified stream and returns the parsed data in a format suitable for passing to XCreateBitmapFromData()

XmuReadBitmapDataFromFile reads a standard bitmap file description from the specified file and returns the parsed data in a format suitable for passing to XCreateBitmapFromData().

XmuLocateBitmapFile reads a file in standard bitmap file format, using XReadBitmapFile(), and returns the created bitmap. The filename may be absolute or relative to the global resource named bitmapFilePath with class BitmapFilePath. If the resource is not defined, the default value is the build symbol BITMAPDIR, which is typically /usr/include/X11/bitmaps.

XmuCreatePixmapFromBitmap creates a pixmap of the specified width, height, and depth on the same screen as the specified drawable and then performs an XCopyPlane() from the specified bitmap to the pixmap, using the specified foreground and background pixel values.

Selection Functions

XmuConvertStandardSelection converts the following standard selections: CLASS, CLIENT_WINDOW, DECNET_ADDRESS, HOSTNAME, IP_ADDRESS, NAME, OWNER_OS, TARGETS, TIMESTAMP, and USER. It returns True if the conversion was successful, else it returns False.

Character Set Functions

XmuCopyISOLatin1Lowered copies a null-terminated string (including the null), changing all Latin-1 uppercase letters to lowercase. XmuCopyISOLatin1Uppered copies a null-terminated string (including the null), changing all Latin-1 lowercase letters to uppercase. XmuCompareISOLatin1 compares two null-terminated Latin-1 strings, ignoring case differences, and returns an integer greater than, equal to, or less than 0, according to whether first is lexicographically greater than, equal to, or less than second. In all three of these routines, the string is assumed to be encoded using ISO 8859-1.

The following functions have the same arguments and function as XLookupString(), except that they convert to keysyms in different sets.
Table F-1 : Character Set Functions
Function Converts To
XmuLookupAPL APL string
XmuLookupArabic Latin/Arabic (ISO 8859-6) or ASCII control
XmuLookupCyrillic Latin/Cyrillic (ISO 8859-5) or ASCII control
XmuLookupGreek Latin/Greek (ISO 8859-7) or ASCII control
XmuLookupHebrew Latin/Hebrew (ISO 8859-8) or ASCII control string
XmuLookupJISX0201 JIS X0201-1976 encoding, including ASCII control
XmuLookupKana Latin-1 (ISO 8859-1) and ASCII control in the Graphics Left half (values 0 to 127) and Katakana in the Graphics Right half (values 128 to 255), using the values from JIS X201-1976.
XmuLookupLatin1 Latin-1 (ISO 8859-1) or ASCII control (synonym for XLookupString)
XmuLookupLatin2 Latin-2 (ISO 8859-2) or ASCII control
XmuLookupLatin3 Latin-3 (ISO 8859-3) or ASCII control
XmuLookupLatin4 Latin-4 (ISO 8859-4) or ASCII control 
 

Compound Text Functions

These functions are for parsing Compound Text strings, decomposing them into individual segments. Four functions are provided for this purpose: XctCreate, XctFree, XctNextItem, XctReset. For more information on these functions, see Appendix J, The Xmu Library, of Volume Two, Xlib Reference Manual.

CloseDisplay Hook Functions

XmuAddCloseDisplayHook adds a function that will be called with the given arguments when XCloseDisplay() is called. XmuRemoveCloseDisplayHook deletes the function that has been added with XmuAddCloseDisplayHook. More than one such function can be added.

XmuLookupCloseDisplayHook determines if a function is installed.

These functions use the Display Queue Functions internally, which are described next.

Display Queue Functions

XmuDQCreate creates and returns an empty XmuDisplayQueue (which is really just a linked list of displays; it is called a queue for historical reasons). The queue is initially empty, but displays can be added using XmuDQAddDisplay. Functions can be added for each display, to be called when the display connection is closed. These are called close callbacks. Functions can also be added to be called when the last display connection is closed. These are called free callbacks. The application is responsible for actually freeing the queue, by calling XmuDQDestroy.

XmuDQAddDisplay does not attempt to prevent duplicate entries in the queue; the caller should use XmuDQLookupDisplay to determine if a display has already been added to a queue. The XmuDQNDisplays macro returns the number of displays in the specified queue. XmuDQRemoveDisplay removes the specified display from the specified queue, without calling its close callbacks. XmuDQDestroy releases all memory associated with the specified queue and optionally calls the close callbacks for each display.

Standard Colormap Functions

XmuAllStandardColormaps creates all of the appropriate standard colormaps for every visual of every screen on a given display. If the property of any standard colormap is already defined, this function will redefine it. This function is intended to be used by window managers or a special client at the start of a session.

XmuVisualStandardColormaps creates all of the appropriate standard colormaps for a given visual on a given screen.

XmuLookupStandardColormap creates a standard colormap if one does not currently exist or replaces the currently existing standard colormap. Given a screen, a visual, and a property, this function will determine the best allocation for the property under the specified visual and whether to create a new colormap or use the default colormap of the screen.

XmuGetColormapAllocation determines the best allocation of reds, greens, and blues in a standard colormap. It is assumed that the visual is appropriate for the colormap property.

XmuStandardColormap creates any one standard colormap, given a visual, a standard colormap atom, and other input, and returns an XStandardColormap structure. XmuCreateColormap creates any one colormap, given an XStandardColormap structure.

All colormaps are created with read-only allocations, with the exception of read-only allocations of colors, which fail to return the expected pixel value, and these are individually defined as read/write allocations. This is done so that all the cells defined in the colormap are contiguous, for use in image processing. This typically happens with White and Black in the default map.

Colormaps of static visuals are considered to be successfully created if the map of the static visual matches the definition given in the standard colormap structure.

XmuDeleteStandardColormap removes any standard colormap property, also releasing any resources used by the colormap(s) specified in the property, if possible.

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