## 11.3 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 guaranteed 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);
    EZ_LabelPixmap *EZ_CreateLabelPixmapFromImageFile(char *fileName);
    EZ_LabelPixmap *EZ_CreateLabelPixmapFromXBitmapFile(char *fileName);
    EZ_LabelPixmap *EZ_CreateLabelPixmapFromXpmData(char **data);
    EZ_LabelPixmap *EZ_CreateLabelPixmapFromXBitmapData(char *data,
                                         int width, int height);
    EZ_LabelPixmap *EZ_CreateLabelPixmapFromXPixmap(Pixmap pixmap, Pixmap shape,
                                         int x, int y, int width, int height, int reuse);

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);
    int EZ_CreateXPixmapFromImageFile(char *fileName,
            int *width_ret, int *height_ret, Pixmap *pixmap_ret);
    int EZ_CreateXPixmapFromBitmapFile(char *fileName, int *width_ret,
            int *height_ret, Pixmap *pixmap_ret, Pixmap *shape_ret);
    int EZ_CreateXPixmapFromXpmData(char **data, int *width_ret,
            int *height_ret, Pixmap *pixmap_ret, Pixmap *shape_ret);

Native X pixmaps created by `EZ_CreateXPixmapFrom***` are retained until one call one of the following.

    void XFreePixmap(EZ_GetDisplay(), pixmap);
    void EZ_FreeXPixmap(Pixmap pixmap);

The next routine returns the information about a LabelPixmap.

    void EZ_GetLabelPixmapInfo(EZ_Pixmap *pix, Pixmap *pix_ret,
                 Pixmap *shape_ret, int w_ret, int h_ret);

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