NAME    [Toc]    [Back]

       XmGetPixmapByDepth - A pixmap caching function that generates
 a pixmap, stores it in a pixmap  cache,  and  returns
       the pixmap

SYNOPSIS    [Toc]    [Back]

       #include <Xm/Xm.h>

       Pixmap XmGetPixmapByDepth (screen, image_name, foreground,
       background, depth)
               Screen *screen;
               char *image_name;
               Pixel foreground;
               Pixel background;
               int depth;

DESCRIPTION    [Toc]    [Back]

       XmGetPixmapByDepth 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 XmDestroyPixmap when the pixmap is
       no longer needed.

       If  a  matching pixmap is not found, image_name 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, image_name is used  as  a  filename,
  and a search is made for an X10 or X11 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 image_name has a leading slash (/), it specifies a full
       pathname,  and XmGetPixmapByDepth opens the file as specified.
 Otherwise, image_name specifies a filename. In  this
       case  XmGetPixmapByDepth looks for the file along a search
       path specified by the XBMLANGPATH environment variable  or
       by  a  default  search  path,  which  varies  depending on
       whether or not the  XAPPLRESDIR  environment  variable  is
       set.

       The  XBMLANGPATH  environment  variable specifies a search
       path for X bitmap files. It can contain  the  substitution
       field  %B, where the image_name argument to XmGetPixmapByDepth
 is substituted for %B. It can also contain the  substitution
  fields  accepted by XtResolvePathname. The substitution
 field %T is always mapped to bitmaps, and %S  is
       always mapped to NULL.

       If  XBMLANGPATH  is  not set, but the environment variable
       XAPPLRESDIR is set, the following pathnames are searched:
               %B
               $XAPPLRESDIR/%L/bitmaps/%N/%B
               $XAPPLRESDIR/%l/bitmaps/%N/%B
               $XAPPLRESDIR/bitmaps/%N/%B
               $XAPPLRESDIR/%L/bitmaps/%B
               $XAPPLRESDIR/%l/bitmaps/%B
               $XAPPLRESDIR/bitmaps/%B
               $HOME/bitmaps/%B
               $HOME/%B
               /usr/lib/X11/%L/bitmaps/%N/%B
               /usr/lib/X11/%l/bitmaps/%N/%B
               /usr/lib/X11/bitmaps/%N/%B
               /usr/lib/X11/%L/bitmaps/%B
               /usr/lib/X11/%l/bitmaps/%B
               /usr/lib/X11/bitmaps/%B
               /usr/include/X11/bitmaps/%B

       If neither XBMLANGPATH nor XAPPLRESDIR is set, the following
 pathnames are searched:
               %B
               $HOME/%L/bitmaps/%N/%B
               $HOME/%l/bitmaps/%N/%B
               $HOME/bitmaps/%N/%B
               $HOME/%L/bitmaps/%B
               $HOME/%l/bitmaps/%B
               $HOME/bitmaps/%B
               $HOME/%B
               /usr/lib/X11/%L/bitmaps/%N/%B
               /usr/lib/X11/%l/bitmaps/%N/%B
               /usr/lib/X11/bitmaps/%N/%B
               /usr/lib/X11/%L/bitmaps/%B
               /usr/lib/X11/%l/bitmaps/%B
               /usr/lib/X11/bitmaps/%B
               /usr/include/X11/bitmaps/%B

       These  paths  are  defaults  that  vendors may change. For
       example,  a  vendor  may  use  different  directories  for
       /usr/lib/X11 and /usr/include/X11.

       The  following  substitutions are used in these paths: The
       image name, from the image_name argument The class name of
       the application The display's language string The language
       component of the display's language string

       Parameter descriptions are  listed  below:  Specifies  the
       display  screen  on which the pixmap is to be drawn Specifies
 the name of the image to  be  used  to  generate  the
       pixmap  Combines  the  image  with the foreground color to
       create the pixmap if the image referenced  is  a  bit-perpixel
  image  Combines the image with the background color
       to create the pixmap if the image referenced is a bit-perpixel
 image Specifies the depth of the pixmap

RETURN VALUE    [Toc]    [Back]

       Returns  a  pixmap  when  successful;  returns  XmUNSPECIFIED_PIXMAP
 if the image corresponding to image_name  cannot
 be found.

SEE ALSO    [Toc]    [Back]

       XmDestroyPixmap(3X),   XmInstallImage(3X),  XmUninstallImage(3X)



                                           XmGetPixmapByDepth(3X)