- find and return the named bitmap
Pixmap XmtGetBitmap(Widget w, String name)
Pixmap XmtGetPixmap(Widget w, XmtColorTable
table, String name)
- A widget or object that specifies the screen, visual, colormap, and depth
of the Pixmap to be returned.
- For XmtGetPixmap(), this argument defines symbolic colors to be
used in converting XPM data to a pixmap. If you specify NULL, the value of
the colorTable application resource will be used.
- The name of the bitmap or pixmap to be obtained.
These functions return None
if no bitmap or pixmap data with the
specified name is found. Otherwise, XmtGetBitmap()
single-plane bitmap, and XmtGetPixmap() returns a multi-plane pixmap with the
same depth and screen as w
, containing the image specified by
, with colors set according to the visual and colormap of w
and according to table
. The returned bitmap or pixmap should be freed
when no longer needed with XmtReleasePixmap()
look up and return named bitmaps
or pixmaps. These functions are very flexible; they form the basis of the Xmt
String-to-Bitmap and String-to Pixmap converters, and look for bitmap and
pixmap data in a number of different places:
• the image cache,
• the resource database, and
• the application's auxiliary files.
The subsections below explain how these functions search each of those places.
The descriptions below explain how XmtGetPixmap()
searches for XPM
pixmap data or XBM bitmap data to convert to a pixmap. XmtGetBitmap()
works in exactly the same way, except that it only performs the searches for
forms the basis for the Xmt pixmap resource
converter, the name
argument to that function may also specify a a
color table for use in the conversion. This will be explained below.
Note that any bitmap or pixmap returned by these functions will be cached in the
XmtImage cache. When they will no longer be needed they should be released
. This will decrement a reference count, and
when that count reaches zero, the bitmap or pixmap will be destroyed.
Searching the Image Cache
The first place XmtGetPixmap()
looks for the named pixmap is in the Xmt
image cache. It calls XmtLookupPixmap()
) to check the cache for XPM data registered with
or for XBM data registered with
Unless you have registered pixmap or bitmap data with one of these relatively
low-level functions, the named pixmap or bitmap will not be found in the image
cache. Note however, that whenever XmtGetPixmap()
find named image data elsewhere, they register that data
in the cache by name so that it will be found quickly by subsequent searches.
Searching the Resource Database
If data is not found in the image cache, then XmtGetPixmap()
the resource database for a definition of the named pixmap or bitmap. First,
it looks for XPM data specified as the value of a resource that matches the
If it does not find pixmap data under _Pixmaps_
in the resource database,
(as well as XmtGetBitmap()
) looks for XBM
bitmap data under _Bitmaps_
for a resource that matches the following
The components of these searches are the following:
- The default visual type of the screen. This will be one of the strings
``color'', ``gray'', or ``monochrome''.
- The default depth, in bitplanes, of the screen. Typical values are ``1''
- The size or ``resolution'' of the screen, as determined by the number of
pixels. This will be one of the strings ``small'' (screen is less than 750
pixels wide), ``medium'', or ``large'' (screen is more than 1150 pixels
- The ``language part'' of the language string.
- The ``territory part'' of the language string.
- The ``codeset part'' of the language string.
- The name argument.
Note that the visual type and depth are not used when search ing for bitmap
data-bitmaps do not include color data, and so this kind of customization is
If resources matching either of the above patterns are found in the resource
database their values are assumed to be XPM or XBM data. This data is parsed,
registered by name in the image cache, and then converted to a pixmap or
You can convert XPM and XBM files as necessary for inclusion in the resource
database with the xpm2res
Searching Auxiliary Files
If the searches of the image cache and resource database fail, then name
is assumed to be the name of a file. The following list explains how
looks for the file. Recall that XmtGetBitmap()
works in the same way, except that it only looks for XBM data; never XPM
The descriptions below assume familiarity with the function
. Note that when XmtFindFile()
is used to look for
pixmap data, it is always passed a type
of ``pixmaps'' and a
of ``.xpm''. When XmtFindFile()
is called to look for
bitmap data, it is passed a type
of ``bitmaps'' and a suffix
- If the name begins with ``/'', ``./'', or ``../'', then it is assumed to
be an absolute or relative filename, and no search is required; it is just
- If the XPMLANGPATH environment variable is set, then
XmtFindFile() is used to search this path for an XPM file with the
specified name. XPMLANGPATH is an Xmt environment variable that is
analogous to XBMLANGPATH variable that is searched by the Motif
- If the XBMLANGPATH environment variable is defined, then
XmtFindFile() is used to search that path for an XBM file. This is
done for compatibility with the search done by XmGetPixmap().
- Next, XmtFindFile() is called again to search for an XPM file in
four more places:
- The user path specified by the userConfigPath resource and the
XUSERFILESEARCHPATH and XAPPLRESDIR resources (see Chapter 6
- The path, if any, specified by the pixmapFilePath application
resource. The default for this resource is NULL, so this search is
not usually performed.
- The path specified by the configPath application resource.
- The standard system path (see Chapter 6 for details.)
- Finally, XmtFindFile() is called again, to look for an XBM file in
four analogous places:
- The user path.
- The path, if any, specified by the bitmapFilePath application
- The path specified by configPath.
- The system path.
If an XPM or XBM file is found in any of these searches, then it is read in, and
its data is parsed and stored by name in the image cache. Then the data is
used to create a pixmap or bitmap which is returned.
Specifying a Color Table
As mentioned earlier, XmtGetPixmap()
(but not XmtGetBitmap()
parse a color table specification as part of its supplied name
contains a `:', the part before the colon (with whitespace
removed) is taken to be the pixmap name, and the part after the colon is taken
to be a color table specification, and is parsed by the Xmt color table
resource converter. (See Chapter 4, Using Color
, for the
When a color table is specified in this way, it is created with the specified
as its parent. If no table
argument was specified, then
the color table is created with the default application color table as its
parent. In either case the resulting ``chained'' color table is used to lookup
all symbolic colors for the pixmap.
finds XPM data, then the color table is used to look up
any symbolic colors in the XPM data. If XmtGetPixmap()
data, then the symbolic colors ``foreground'' and ``background'' are looked up
and used as the foreground and background colors for the pixmap created from
this bitmap data.
Chapter 5, Using Icons
Chapter 4, Using Color
Chapter 6, Managing Auxiliary Files