FreeBSD Manual Pages
XmtGetBitmap(3) Library Functions Manual XmtGetBitmap(3) NAME XmtGetBitmap(), XmtGetPixmap() - find and return the named bitmap or pixmap. SYNOPSIS #include <Xmt/Pixmap.h> Pixmap XmtGetBitmap(Widget w, String name) Pixmap XmtGetPixmap(Widget w, XmtColorTable table, String name) ARGUMENTS INPUTS w A widget or object that specifies the screen, visual, colormap, and depth of the Pixmap to be returned. table 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. name The name of the bitmap or pixmap to be obtained. RETURNS These functions return None if no bitmap or pixmap data with the specified name is found. Otherwise, XmtGetBitmap() returns a single-plane bitmap, and XmtGetPixmap() returns a multi-plane pixmap with the same depth and screen as w, containing the image specified by name, 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(). DESCRIPTION XmtGetBitmap() and XmtGetPixmap() 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 bitmap data. Because XmtGetPixmap() forms the basis for the Xmt pixmap resource con- verter, 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 with XmtReleasePixmap(). 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 im- age cache. It calls XmtLookupPixmap() (XmtGetBitmap() calls XmtLookup- Bitmap()) to check the cache for XPM data registered with XmtRegisterIm- age() or for XBM data registered with XmtRegisterXbmData(). Unless you have registered pixmap or bitmap data with one of these rela- tively low-level functions, the named pixmap or bitmap will not be found in the image cache. Note however, that whenever XmtGetPixmap() or XmtGet- Bitmap() 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() next checks 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 following pattern: _Pixmaps_.visual.depth.size.language.territory.codeset.name If it does not find pixmap data under _Pixmaps_ in the resource database, then XmtGetPixmap() (as well as XmtGetBitmap()) looks for XBM bitmap data under _Bitmaps_ for a resource that matches the following pattern: _Bitmaps_.size.language.territory.codeset.name The components of these searches are the following: visual The default visual type of the screen. This will be one of the strings ``color'', ``gray'', or ``monochrome''. depth The default depth, in bitplanes, of the screen. Typical values are ``1'' and ``8''. size The size or ``resolution'' of the screen, as determined by the num- ber 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 wide). language The ``language part'' of the language string. territory The ``territory part'' of the language string. codesetThe ``codeset part'' of the language string. name 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 not required. If resources matching either of the above patterns are found in the re- source 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 bitmap. You can convert XPM and XBM files as necessary for inclusion in the re- source database with the xpm2res and xbm2res scripts. 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 XmtGet- Pixmap() looks for the file. Recall that XmtGetBitmap() works in the same way, except that it only looks for XBM data; never XPM pixmap data. The descriptions below assume familiarity with the function XmtFindFile(). Note that when XmtFindFile() is used to look for pixmap data, it is always passed a type of ``pixmaps'' and a suffix of ``.xpm''. When XmtFindFile() is called to look for bitmap data, it is passed a type of ``bitmaps'' and a suffix of ``.xbm''. 1. If the name begins with ``/'', ``./'', or ``../'', then it is as- sumed to be an absolute or relative filename, and no search is re- quired; it is just read directly. 2. 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 XBM- LANGPATH variable that is searched by the Motif function XmGet- Pixmap(). 3. If the XBMLANGPATH environment variable is defined, then XmtFind- File() is used to search that path for an XBM file. This is done for compatibility with the search done by XmGetPixmap(). 4. Next, XmtFindFile() is called again to search for an XPM file in four more places: a. The user path specified by the userConfigPath resource and the XUSERFILESEARCHPATH and XAPPLRESDIR resources (see Chapter 6 for details.) b. The path, if any, specified by the pixmapFilePath application resource. The default for this resource is NULL, so this search is not usually performed. c. The path specified by the configPath application resource. d. The standard system path (see Chapter 6 for details.) 5. Finally, XmtFindFile() is called again, to look for an XBM file in four analogous places: a. The user path. b. The path, if any, specified by the bitmapFilePath application resource. c. The path specified by configPath. d. 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()) can parse a color table specification as part of its supplied name. If 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 syntax.) When a color table is specified in this way, it is created with the speci- fied table as its parent. If no table argument was specified, then the color table is created with the default application color table as its par- ent. In either case the resulting ``chained'' color table is used to lookup all symbolic colors for the pixmap. If XmtGetPixmap() finds XPM data, then the color table is used to look up any symbolic colors in the XPM data. If XmtGetPixmap() finds bitmap 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. SEE ALSO Chapter 5, Using Icons, Chapter 4, Using Color, Chapter 6, Managing Auxiliary Files, XmtLookupBitmap(), XmtLookupBitmask(), XmtLookupPixmap(),' XmtParseXpmData(), XmtParseXpmFile(), XmtRegisterImage(), XmtRegisterXbmData(), XmtReleasePixmap(). Xmt Motif Tools XmtGetBitmap(3)
NAME | SYNOPSIS | ARGUMENTS | DESCRIPTION | SEE ALSO
Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=XmtGetBitmap&sektion=3&manpath=FreeBSD+Ports+15.1.quarterly>