Volume 7A: XView Programming Manual

14.2.0.3 ICON_MASK_IMAGE

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 specified 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 “filled 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 modified to use this attribute by adding the following code:

image_mask = (Server_image)xv_create(NULL, SERVER_IMAGE,

XV_WIDTH, 64,

XV_HEIGHT, 64,

XV_DEPTH, 1,

SERVER_IMAGE_BITS, closed_image_mask_bits,

NULL);

icon = (Icon)xv_create(frame, ICON,

ICON_IMAGE, closed_image,

ICON_MASK_IMAGE, image_mask,

XV_X, 100,

XV_Y, 100,

NULL);

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 fit, it is clipped by this region. To keep the entire image on the icon and display

the text without writing over the image, define 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. Redefining an icon’s size to include its label

...

Rect image_rect, label_rect;

Server_image image;

Icon icon;

...

*ICON_LABEL is defined to be XV_LABEL in <xview/icon.h>.

344 XView Programming Manual

Example 14-3. Redefining an icon’s size to include its label (continued)

rect_construct(&image_rect, 0, 20, 64, 64);

rect_construct(&label_rect, 0, 0, 64, 20);

icon = xv_create(frame, ICON,

XV_WIDTH, 64,

XV_HEIGHT, 64 + 20,

XV_LABEL, "Sample",

ICON_LABEL_RECT, &label_rect,

ICON_IMAGE, image,

ICON_IMAGE_RECT, &image_rect,

NULL);

xv_set(frame, FRAME_ICON, icon, NULL);

The first thing we do is construct the image and label area by using the rect_

construct() macro found in <xview/rect.h>. The image is positioned at 0, 20 and is a

size of 64x64. The text is positioned at the upperleft corner (0, 0), extends to the width of

the icon and is 20 pixels high. The size of the icon is 64, and the height of the text is 20, so

when we create the icon, we set the height of the icon object using XV_HEIGHT at 64+20.

14.2.2 ICON_TRANSPARENT_LABEL

The ICON_TRANSPARENT_LABEL attribute specifies a string that is drawn into the icon using

the foreground color only. Pixels other than those in the font set are not affected.

Creating, setting, and getting ICON_TRANSPARENT_LABEL is equivalent to creating, setting,

and getting ICON_LABEL, except that the string is drawn in the foreground color only.

14.3 Icon Package Summary

There are no procedures or macros in the ICON package. Table 14-1 shows the attributes for

the ICON package. This information is described fully in the XView Reference Manual.

Table 14-1. Icon Attributes

ICON_FONT ICON_LABEL_RECT

ICON_HEIGHT ICON_MASK_IMAGE

ICON_IMAGE ICON_TRANSPARENT

ICON_IMAGE_RECT ICON_TRANSPARENT_LABEL

ICON_LABEL ICON_WIDTH

XV_LABEL

Icons

Icons 345

This page intentionally left blank

to preserve original page counts.

This page intentionally left blank

to preserve original page counts.