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:
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:
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.