Motif Programmer's Guide Migration Version

Motif 2.1 Programmer's Guide

Using Pixmaps

Motif uses pixmaps supplied by the application or the user for widget borders, backgrounds, labels, shadows, focus highlights, and button arming or selection indicators. Motif also uses other pixmaps that the application or user can supply for more specific purposes: as application icons, drag icons, CascadeButton menu indicators, MessageBox symbols, and labels for insensitive buttons.

Motif provides facilities for an application to install and cache images and pixmaps. Motif also has string-to-pixmap resource converters that retrieve pixmaps from the cache or install them from files in X bitmap format or in X pixmap format. Because of these converters, both applications and users can specify pixmaps as resource values from resource files or the command line.

An application can use XmGetPixmapByDepth to retrieve or create a pixmap with a specified name, screen, foreground, background, and depth. XmGetPixmapByDepth finds or creates a pixmap in the following way:

It searches the pixmap cache for a pixmap matching the specified name, screen, foreground, background, and depth. If it finds a matching pixmap, it returns the pixmap.

If it does not find a matching pixmap in the cache, it searches the image cache for an image matching the specified name. If it finds a matching image, it creates and caches a pixmap of the specified depth on the specified screen, transfers the image to the pixmap, and returns the pixmap.

If it does not find a matching image in the cache, it uses XtResolvePathname to search for a file of the specified name. The search path comes from the environment variable XBMLANGPATH or, if XBMLANGPATH is not set, from a default search path. Performance is usually better when XBMLANGPATH is set to a short list of directories than when the system uses the default search path. If it finds such a file, it assumes that the file is in X bitmap format, reads the file, and creates and caches an image in XYBitmap format. It then creates and caches a pixmap of the specified depth on the specified screen, transfers the image to the pixmap, and returns the pixmap. (Since images are cached after they are found, the performance improvement from setting XBMLANGPATH only affects the initial search for an image.)

If it does not find a matching X bitmap file, it returns XmUNSPECIFIED_PIXMAP.

Motif preinstalls a number of images in the image cache. The names and characteristics of these images are documented in the XmInstallImage(3) reference page. Motif offers two ways for an application to provide its own image as the source for a pixmap to be created by XmGetPixmapByDepth:

The application can create its own image, usually by using XCreateImage or XGetImage. The image can be of any depth. The application can then call XmInstallImage to install the image in the image cache by name.

The application or user can create a file in X bitmap format and install the file under an appropriate name in a directory that is in the search path used by XmGetPixmapByDepth. For a description of the X bitmap format, see Xlib--C Language X Interface.

Both of these mechanisms have advantages and disadvantages. An application using XmInstallImage can create an image of any depth. However, if it intends to use the image name in a resource specification, it must be sure to call XmInstallImage before creating any widgets that use the image.

An application using an X bitmap file is limited to creating an image of depth 1. However, the image is always available for use by a resource converter, and the application can use the search path mechanism of XtResolvePathname for such purposes as supplying different images for different locales.

XmInstallImage does not make a copy of the image when it caches it. The application must not destroy the image until it removes the image from the cache, using XmUninstallImage. An application can use XmDestroyPixmap to free a pixmap cached by XmGetPixmapByDepth. XmDestroyPixmap does not actually destroy the pixmap until all references to it are freed.