### 2.5.9 About Pixmap Labels

The EZwgl library keeps a hash table for pixmaps used in an application. Each entry in the hash table has a reference count. When the reference count reaches 0, the entry is de-allocated and the relevent X resources are released. If an application uses lots of pixmaps and needs to switch constantly between different pixmaps, chances are that these pixmaps are allocated and de-allocated frequently. As a result, the performance may not be optimal since allocating pixmaps, especially creating pixmaps from images are expensive. For this situation, one may explicitly allocate the pixmaps first and then use the internal pixmaps. Explicitly allocated pixmaps are quaranteed to be cached until being explicitly freed.

The following code segment demonstrates this usage.

     EZ_LabelPixmap *pixmap1 = EZ_CreateLabelPixmapFromImageFile("file1");
     EZ_LabelPixmap *pixmap2 = EZ_CreateLabelPixmapFromImageFile("file2");

     ...

     if(condition1) /* use the first pixmap */
       EZ_ConfigureWidget(widget, EZ_LABEL_PIXMAP, pixmap1, 0);
     else /* use the second pixmap */
       EZ_ConfigureWidget(widget, EZ_LABEL_PIXMAP, pixmap2, 0);

     ...

There are five rountines in EZwgl that allow an application to create internal pixmaps from different sources.

`EZ_LabelPixmap *EZ_CreateLabelPixmapFromXpmFile(char *fileName)`

This function creates an internal pixmap from an xpm image file.

`EZ_LabelPixmap *EZ_CreateLabelPixmapFromImageFile(char *fileName)`

This function creates an internal pixmap from an image file. Currently, EZwgl only recognize images in xpm, ppm and gif formats.

`EZ_LabelPixmap *EZ_CreateLabelPixmapFromXBitmapFile(char *fileName)`

This function creates an internal pixmap from an X11 bitmap file.

`EZ_LabelPixmap *EZ_CreateLabelPixmapFromXpmData(char **data)`

This function creates an internal pixmap from xpm data.

`EZ_LabelPixmap *EZ_CreateLabelPixmapFromXBitmapData(char *data`

`int width, int height)`

This function creates an internal pixmap from X bitmap data.

To free an internal label pixmap, use

`void EZ_FreeLabelPixmap(EZ_LabelPixmap *IPixmap)`

Another situation is when an application needs to use part of an image to label a widget. EZwgl provides an indirect way to achieve this goal. One first creates a native X pixmap by using `EZ_CreateXPixmapFrom***`, or `XCreatePixmap`, then uses the `EZ_X_PIXMAP` configuration option to set the label.

The following code segement is an example.

      Pixmap pixmap;
      int    width, height;

      if(EZ_CreateXPixmapFromImageFile("file",&width, &height, &pixmap))
        {
           /* use the upper left quarter of the image to label widget */
           EZ_ConfigureWidget(widget,
                              EZ_X_PIXMAP, pixmap, 0, 0, width/2, height/2,
                              0);

           /* if there are no other use of pixmap, free it */
           EZ_FreeXPixmap(pixmap);
         }

       ...

Besides the Xlib function `XCreatePixmap`, the following five functions may also be used to create native pixmaps from various sources.

`int EZ_CreateXPixmapFromXpmFile(char *fileName, int *width_ret`

`int *height_ret, Pixmap *pixmap_ret, Pixmap *shape_ret)`

This function creates a native X pixmap from an xpm image file. It returns 1 upon success and 0 otherwise.

`int EZ_CreateXPixmapFromImageFile(char *fileName,`

`int *width_ret, int *height_ret, Pixmap *pixmap_ret)`

This function creates a native X pixmap from an image file. It returns 1 on success and 0 otherwise.

EZwgl only recognizes images in xpm, ppm and gif formats.

`int EZ_CreateXPixmapFromBitmapFile(char *fileName, int *width_ret,`

`int *height_ret, Pixmap *pixmap_ret, Pixmap *shape_ret)`

This function creates a native X pixmap from an X bitmap file. It returns 1 on success and 0 on failure.

`int EZ_CreateXPixmapFromXpmData(char **data, int *width_ret,`

`int *height_ret, Pixmap *pixmap_ret, Pixmap *shape_ret)`

This function creates a native X pixmap from an xpm image data. It returns 1 on success and 0 on failure.

Native X pixmaps created by `EZ_CreateXPixmapFrom***` are retained until one call

`XFreePixmap(EZ_GetDisplay(), pixmap)`

or

`void EZ_FreeXPixmap(Pixmap pixmap)`

HTML Documentation Maintainance:`Arturo Espinosa <arturo@nuclecu.unam.mx>`