Volume 7A: XView Programming Manual

14

Icons

A user may close an application to save space on the display. The program is still running

and it may even be active, but it is not receiving input from the user. In order to represent the

application in its closed state, an icon is used. An icon is a small picture that represents the

application, as shown in Figure 14-1 from the OPEN LOOK GUI Specification Guide.

Figure 14-1. Three bordered default icons

The graphic image that icons use may be used for other purposes and, therefore, may be

shared among other objects in the application. But the icon image should be designed to eas-

ily identify the application while in a closed state. Icons may also have text associated with

them. Space is limited, so the text is usually the name of the application.

14.1 Creating and Destroying Icons

To use the ICON package, include the header file <xview/icon.h>. Figure 14-2 shows the

class hierarchy for the ICON package.

The form for creating an icon is:

Icon icon;

icon = (Icon)xv_create(owner, ICON,

attributes

, NULL);

The owner of an icon is a base frame, but it may be created with a NULL owner. Once an

icon is assigned to a frame, the owner of the icon is changed to that frame. This is another

example of delayed binding.

Icons

Icons 339

Generic

Object

(Drawable) Window Icon

Figure 14-2. Icon package class hierarchy

When destroying an icon, the server image associated with the icon is not destroyed—it is

your responsibility to free the server image and the pixmap associated with the icon if

needed.

14.2 The Icon’s Image

The most important thing about the icon is its graphic representation, so you will also need to

be familiar with the SERVER_IMAGE package described in Chapter 15, Nonvisual Objects.

Once an image is created, you can create an icon and assign it to a frame. This chapter does

not discuss the creation of server images for icons, whether they originate from filenames or

from the actual data.

The program in Example 14-1 creates two server images—it uses open.icon as the image for

the panel button and closed.icon for the application’s icon.* Pressing the panel button causes

the application to close to its iconic state. You must use a window manager function to open

the application back up again.

Example 14-1. The icon_demo.c program

/*

* icon_demo.c -- demonstrate how an icon is used. Create a server

* image and create an icon object with the image as the ICON_IMAGE.

* Use the icon as the frame’s icon.

*/

#include <xview/xview.h>

#include <xview/panel.h>

#include <xview/svrimage.h>

#include <xview/icon.h>

short open_bits[ ] = {

#include "open.icon"

};

short closed_bits[ ] = {

#include "closed.icon"

};

main(argc, argv)

*The files open.icon and closed.icon are not included in this book due to their length and complexity. They are bit-

map files represented in ASCII hex notation. The files are included with the XView distribution.

340 XView Programming Manual

Example 14-1. The icon_demo.c program (continued)

int argc;

char *argv[ ];

{

Frame frame;

Panel panel;

Server_image open_image, closed_image;

Icon icon;

void close_frame();

xv_init(XV_INIT_ARGC_PTR_ARGV, &argc, argv, NULL);

frame = (Frame)xv_create(XV_NULL, FRAME, NULL);

panel = (Panel)xv_create(frame, PANEL, NULL);

open_image = (Server_image)xv_create(NULL, SERVER_IMAGE,

XV_WIDTH, 64,

XV_HEIGHT, 64,

SERVER_IMAGE_BITS, open_bits,

NULL);

closed_image = (Server_image)xv_create(NULL, SERVER_IMAGE,

XV_WIDTH, 64,

XV_HEIGHT, 64,

SERVER_IMAGE_BITS, closed_bits,

NULL);

(void) xv_create(panel, PANEL_MESSAGE,

PANEL_LABEL_IMAGE, open_image,

PANEL_NOTIFY_PROC, close_frame,

NULL);

icon = (Icon)xv_create(frame, ICON,

ICON_IMAGE, closed_image,

XV_X, 100,

XV_Y, 100,

NULL);

xv_set(frame, FRAME_ICON, icon, NULL);

window_fit(panel);

window_fit(frame);

xv_main_loop(frame);

}

void

close_frame(item, event)

Panel_item item;

Event *event;

{

Frame frame = (Frame)xv_get(xv_get(item,

PANEL_PARENT_PANEL), XV_OWNER);

xv_set(frame, FRAME_CLOSED, TRUE, NULL);

}

Icons

Icons 341

The callback routine for the panel button, close_frame(), makes a call to an XView rou-

tine which sends window manager requests from the client to the window manager. In this

case, we set the frame’s FRAME_CLOSED attribute to TRUE to request that the window man-

ager iconify the application associated with the frame parameter.*

The position of the image with respect to the icon is set using the attribute

ICON_IMAGE_RECT, which takes as its value a pointer to a Rect structure. The r_top and

r_left fields of the structure indicate the offset from the upperleft corner of the icon where

the image is placed. The r_width and r_height fields describe the size of the image. If

the icon is going to be a different size from the size of the icon’s image, or if there is going to

be text used with this icon, then the ICON_IMAGE_RECT attribute should be used. Section

14.2.1, “The Icon Text,” has an example.

14.2.0.1 Color icons

You can make color icons in several ways. You can create a color server image and use that

as the ICON_IMAGE. You can set the foreground and background colors for a monochrome

image (1-bit deep image) and change the colormap of the icon. For example:

Icon icon;

unsigned long foreground_index, background_index;

Server_image image; /* assume 1-bit deep monochrome image */

Cms cms;

icon = (Icon)xv_create(frame, ICON,

ICON_IMAGE, image,

WIN_CMS, cms,

WIN_FOREGROUND_COLOR, foreground_index,

WIN_BACKGROUND_COLOR, background_index,

NULL);

The icon created assumes that the colormap object, cms, has been created. The foreground

and background colors are indices into the colormap (see Chapter 21, Color, for more infor-

mation on colormap segments). Also see the program x_draw.c in Appendix F, Example Pro-

grams.

Example 14-2. Color cursors

#include <xview/xview.h>

#include <xview/svrimage.h>

#include <xview/cms.h>

/* Icon data */

static unsigned short icon_bits[ ] = {

#include "cardback.icon"

};

main(argc,argv)

int argc;

char *argv[ ];

{

*Window manager functions are discussed in Chapter 4, Frames.

342 XView Programming Manual

Example 14-2. Color cursors (continued)

Frame frame;

Icon icon;

unsigned long foreground_index, background_index;

Server_image image; /* assume 1-bit deep monochrome image */

Cms cms;

xv_init(XV_INIT_ARGC_PTR_ARGV, &argc, argv, NULL);

frame = xv_create(NULL,FRAME,NULL);

image = (Server_image)xv_create(NULL, SERVER_IMAGE,

XV_WIDTH, 64,

XV_HEIGHT, 64,

SERVER_IMAGE_DEPTH, 1,

SERVER_IMAGE_BITS, icon_bits,

NULL);

foreground_index = 2;

background_index = 0;

cms = (Cms)xv_create(NULL,CMS,

CMS_SIZE, 3,

CMS_NAMED_COLORS, "green","red","blue",NULL,

NULL);

icon = (Icon)xv_create(frame, ICON,

ICON_IMAGE, image,

WIN_CMS, cms,

WIN_FOREGROUND_COLOR, foreground_index,

WIN_BACKGROUND_COLOR, background_index,

NULL);

xv_set(frame, FRAME_ICON, icon, NULL);

xv_main_loop(frame);

}

14.2.0.2 ICON_TRANSPARENT

If the

ICON_TRANSPARENT attribute is set to TRUE (it’s FALSE by default), the icon’s back-

ground color is set to the background color of the root window. This may give the effect that

the icon is transparent in the case where the root window is a solid color. However, be care-

ful when the root window has a backing bitmap pattern or a different colormap from the icon.

Icons

Icons 343