\labelsubsec:AboutPixmapLabels
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)
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)