Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
XmtGetBitmap(3)		   Library Functions Manual	       XmtGetBitmap(3)

       XmtGetBitmap(),	XmtGetPixmap()	-  find	and return the named bitmap or

       #include	<Xmt/Pixmap.h>

       Pixmap XmtGetBitmap(Widget w, String name)

       Pixmap XmtGetPixmap(Widget w, XmtColorTable table, String name)


       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.


       These functions return None if no bitmap	or pixmap data with the	speci-
       fied 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().

       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 bit-
       map and pixmap data in a	number of different places:

       o the image cache,

       o the resource database,	and

       o 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.  XmtGet-
       Bitmap()	 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 ref-
       erence  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()  (XmtGetBitmap() calls Xmt-
       LookupBitmap()) to check	the cache for XPM data registered with XmtReg-
       isterImage() or for XBM data registered with XmtRegisterXbmData().

       Unless you have registered pixmap or bitmap data	with one of these rel-
       atively low-level functions, the	named pixmap or	 bitmap	 will  not  be
       found in	the image cache. Note however, that whenever XmtGetPixmap() or
       XmtGetBitmap() find named image data elsewhere, they register that data
       in  the	cache  by  name	so that	it will	be found quickly by subsequent

       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:

       If  it  does not	find pixmap data under _Pixmaps_ in the	resource data-
       base, then XmtGetPixmap() (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:

       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
	      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 wide).

	      The ``language part'' of the language string.

	      The ``territory part'' of	the language string.

	      The ``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 cus-
       tomization is not required.

       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 con-
       verted to a pixmap or bitmap.

       You can convert XPM and XBM files as necessary  for  inclusion  in  the
       resource	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 XmtGetPixmap() 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 XmtFind-
       File(). 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
	      assumed to be an absolute	or relative filename, and no search is
	      required;	it is just read	directly.

       2.     If  the  XPMLANGPATH  environment	variable is set, then XmtFind-
	      File() 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 function XmGetPixmap().

       3.     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().

       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  applica-
		   tion	 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 applica-
		   tion	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
       specified table 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.

       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.

       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)


Want to link to this manual page? Use this URL:

home | help