


XmGetPixmap(3X)						      XmGetPixmap(3X)
OSF/Motif							    OSF/Motif



NAME
  XXmmGGeettPPiixxmmaapp -	A pixmap caching function that generates a pixmap, stores it
  in a pixmap cache, and returns the pixmap

SYNOPSIS


  ##iinncclluuddee <<XXmm//XXmm..hh>>
  PPiixxmmaapp XXmmGGeettPPiixxmmaapp ((_s_c_r_e_e_n, _i_m_a_g_e__n_a_m_e, _f_o_r_e_g_r_o_u_n_d, _b_a_c_k_g_r_o_u_n_d))
       SSccrreeeenn	 **_s_c_r_e_e_n;;
       cchhaarr	 **_i_m_a_g_e__n_a_m_e;;
       PPiixxeell	 _f_o_r_e_g_r_o_u_n_d;;
       PPiixxeell	 _b_a_c_k_g_r_o_u_n_d;;

DESCRIPTION
  XXmmGGeettPPiixxmmaapp uses the parameter data to perform a lookup in the pixmap	cache
  to see if a pixmap has already been generated	that matches the data.	If
  one is found,	a reference count is incremented and the pixmap	is returned.
  Applications should use XXmmDDeessttrrooyyPPiixxmmaapp when the pixmap is no	longer
  needed.

  If a pixmap is not found, _i_m_a_g_e__n_a_m_e is used to perform a lookup in the
  image	cache.	If an image is found, it is used to generate the pixmap,
  which	is then	cached and returned.

  If an	image is not found, the	_i_m_a_g_e__n_a_m_e is used as a	filename, and a
  search is made for an	XX1100 or XX1111 bitmap file.	 If it is found, the file is
  read,	converted into an image, and cached in the image cache.	 The image is
  then used to generate	a pixmap, which	is cached and returned.

  If _i_m_a_g_e__n_a_m_e	has a leading slash (//), it specifies a	full pathname, and
  XXmmGGeettPPiixxmmaapp opens the	file as	specified.  Otherwise, _i_m_a_g_e__n_a_m_e specifies a
  filename.  In	this case XXmmGGeettPPiixxmmaapp looks for	the file along a search	path
  specified by the XXBBMMLLAANNGGPPAATTHH environment variable or by a default search
  path,	which varies depending on whether or not the XXAAPPPPLLRREESSDDIIRR environment
  variable is set.

  The XXBBMMLLAANNGGPPAATTHH environment variable specifies a search path for X bitmap
  files.  It can contain the substitution field	%B, where the _i_m_a_g_e__n_a_m_e
  argument to XXmmGGeettPPiixxmmaapp is substituted for %B.  It can also contain the
  substitution fields accepted by XXttRReessoollvveePPaatthhnnaammee.  The substitution field
  %T is	always mapped to bbiittmmaappss, and %S is always mapped to NULL.

  If XXBBMMLLAANNGGPPAATTHH is not	set but	the environment	variable XXAAPPPPLLRREESSDDIIRR is	set,
  the following	pathnames are searched:

		 %%BB
		 $$XXAAPPPPLLRREESSDDIIRR//%%LL//bbiittmmaappss//%%NN//%%BB
		 $$XXAAPPPPLLRREESSDDIIRR//%%ll//bbiittmmaappss//%%NN//%%BB
		 $$XXAAPPPPLLRREESSDDIIRR//bbiittmmaappss//%%NN//%%BB
		 $$XXAAPPPPLLRREESSDDIIRR//%%LL//bbiittmmaappss//%%BB
		 $$XXAAPPPPLLRREESSDDIIRR//%%ll//bbiittmmaappss//%%BB
		 $$XXAAPPPPLLRREESSDDIIRR//bbiittmmaappss//%%BB
		 $$HHOOMMEE//bbiittmmaappss//%%BB
		 $$HHOOMMEE//%%BB
		 //uussrr//lliibb//XX1111//%%LL//bbiittmmaappss//%%NN//%%BB
		 //uussrr//lliibb//XX1111//%%ll//bbiittmmaappss//%%NN//%%BB
		 //uussrr//lliibb//XX1111//bbiittmmaappss//%%NN//%%BB
		 //uussrr//lliibb//XX1111//%%LL//bbiittmmaappss//%%BB
		 //uussrr//lliibb//XX1111//%%ll//bbiittmmaappss//%%BB
		 //uussrr//lliibb//XX1111//bbiittmmaappss//%%BB
		 //uussrr//iinncclluuddee//XX1111//bbiittmmaappss//%%BB

  If neither XXBBMMLLAANNGGPPAATTHH nor XXAAPPPPLLRREESSDDIIRR is set, the following pathnames are
  searched:

		 %%BB
		 $$HHOOMMEE//%%LL//bbiittmmaappss//%%NN//%%BB
		 $$HHOOMMEE//%%ll//bbiittmmaappss//%%NN//%%BB
		 $$HHOOMMEE//bbiittmmaappss//%%NN//%%BB
		 $$HHOOMMEE//%%LL//bbiittmmaappss//%%BB
		 $$HHOOMMEE//%%ll//bbiittmmaappss//%%BB
		 $$HHOOMMEE//bbiittmmaappss//%%BB
		 $$HHOOMMEE//%%BB
		 //uussrr//lliibb//XX1111//%%LL//bbiittmmaappss//%%NN//%%BB
		 //uussrr//lliibb//XX1111//%%ll//bbiittmmaappss//%%NN//%%BB
		 //uussrr//lliibb//XX1111//bbiittmmaappss//%%NN//%%BB
		 //uussrr//lliibb//XX1111//%%LL//bbiittmmaappss//%%BB
		 //uussrr//lliibb//XX1111//%%ll//bbiittmmaappss//%%BB
		 //uussrr//lliibb//XX1111//bbiittmmaappss//%%BB
		 //uussrr//iinncclluuddee//XX1111//bbiittmmaappss//%%BB

  These	paths are defaults that	vendors	may change.  For example, a vendor
  may use different directories	for //uussrr//lliibb//XX1111 and //uussrr//iinncclluuddee//XX1111.

  The following	substitutions are used in these	paths:

  %%BB   The image name, from the	_i_m_a_g_e__n_a_m_e argument.

  %%NN   The class name of the application.

  %%LL   The display's language string.

  %%ll   The language component of the display's language	string.

  Parameter descriptions are listed below:

  _s_c_r_e_e_n    Specifies the display screen on which the pixmap is	to be drawn.
	    The	depth of the pixmap is the default depth for this screen.

  _i_m_a_g_e__n_a_m_e
	    Specifies the name of the image to be used to generate the pixmap

  _f_o_r_e_g_r_o_u_n_d
	    Combines the image with the	_f_o_r_e_g_r_o_u_n_d color to create the pixmap
	    if the image referenced is a bit-per-pixel image

  _b_a_c_k_g_r_o_u_n_d
	    Combines the image with the	_b_a_c_k_g_r_o_u_n_d color to create the pixmap
	    if the image referenced is a bit-per-pixel image

RETURN VALUE
  Returns a pixmap when	successful; returns XXmmUUNNSSPPEECCIIFFIIEEDD__PPIIXXMMAAPP if the	image
  corresponding	to the _i_m_a_g_e__n_a_m_e cannot be found.




RELATED	INFORMATION
  XXmmDDeessttrrooyyPPiixxmmaapp((33XX)), XXmmGGeettPPiixxmmaappBByyDDeepptthh((33XX)), XXmmIInnssttaallllIImmaaggee((33XX)), and
  XXmmUUnniinnssttaallllIImmaaggee((33XX)).



