The attribute ICON_MASK_IMAGE may be used to clip all drawing into the pixmap to the bits
set in the Pixmap or Server_image speciﬁed here. Therefore, this image should be a
1-bit deep bitmap. The image used as the icon mask is usually a “shadow” of the icon’s nor-
mal image. That is, it is the same image “ﬁlled in,” resulting in a totally black 1-bit deep
icon that has the same shape as the icon’s image.
Example 14-2 can be modiﬁed to use this attribute by adding the following code:
image_mask = (Server_image)xv_create(NULL, SERVER_IMAGE,
icon = (Icon)xv_create(frame, ICON,
When used in conjunction with the ICON_TRANSPARENT attribute, it may be possible to cre-
ate an icon that appears to have a shape other than a square.
14.2.1 The Icon Text
Each icon can have text associated with it. This text is not part of the icon’s image; it is ren-
dered on top of the image after the image is rendered. To specify the text displayed in the
icon, use the generic attribute
ICON_LABEL.* By default, the text is displayed at the bottom
of the icon area. This may overlap the icon’s image. You can change the position in which
the text is rendered by using the attribute ICON_LABEL_RECT. The value of the attribute
describes a rectangular region in which the text will overwrite anything underneath it. If the
text does not ﬁt, it is clipped by this region. To keep the entire image on the icon and display
the text without writing over the image, deﬁne your icon to be large enough to include both
the image and the extents of the text without these regions overlapping. This might make
your icon a nonstandard size, however. (The size of an icon is typically 64x64 pixels.)
The code fragment in Example 14-3 implements added sizes to compensate for text while
preserving enough area to display the entire icon.
Example 14-3. Redeﬁning an icon’s size to include its label
Rect image_rect, label_rect;
*ICON_LABEL is deﬁned to be XV_LABEL in <xview/icon.h>.
344 XView Programming Manual