Volume 7A: XView Programming Manual

Figure 7-13. Sample panel with scrolling list

7.11.1 Displaying List Items

You can use either text strings or server images to display the choice to the user; you can

even intermix them. You specify the choices either one at a time or in a group. To set only

one choice, use PANEL_LIST_STRING or PANEL_LIST_GLYPH. When creating a new string

or glyph entry, if the index into the list specified is larger than the total number of entries,

then the new item is added to the end of the list. Use

PANEL_LIST_STRINGS or

PANEL_LIST_GLYPHS to set all the choices in a group. If no items exist in the list, the appro-

priate number of rows are created to fit all of the items. If the list already contains items,

then the first n rows of items are replaced by the newly specified strings or glyphs (where n is

the number of strings or glyphs specified).

The width of the list item can be set to explicit pixel values using

PANEL_LIST_WIDTH. The

minimum value for this attribute is 25. This reserves enough space for the list’s borders and

margins. Setting PANEL_LIST_WIDTH to -1 extends the width of the scrolling list box to the

edge of the panel. Setting PANEL_LIST_WIDTH to 0 sets the width to that of the widest row

in the scrolling list. Alternatively, the number of rows that are displayed in the list item can

be controlled through the value of the PANEL_LIST_DISPLAY_ROWS attribute. This value

governs the height, in rows, of the list item.

The default panel font for a scrolling list is the default font for the panel. To specify a partic-

ular font for a scrolling list row, use PANEL_LIST_FONT, which takes two arguments, a row

number and a font. To set the fonts for multiple rows, use

PANEL_LIST_FONTS. Note that

the font specification using either PANEL_LIST_FONT or PANEL_LIST_FONTS should follow

the creation of the rows (for example, by

PANEL_LIST_STRINGS).

By default, a scrolling list does not have a title. To add a title to a scrolling list, use

PANEL_LIST_TITLE as in the following code segment:

xv_set(panel_list_item, PANEL_LIST_TITLE, "Patterns", NULL);

The title appears above the list items. The package makes a copy of the string passed to the

PANEL_LIST_TITLE attribute. The package also will free the string when the title string is

no longer needed.

The height of each row in the list may be set using PANEL_LIST_ROW_HEIGHT. All rows

have the same height. If the items in the list are glyphs, then the height of each row must be

specified by at least the height of the tallest glyph in the list. This should be determined be-

fore the list of glyphs is set in the list item. Entries in the list can be either glyphs or strings;

178 XView Programming Manual

an entry containing both a string and a glyph will display both. The glyph will be on the left

and the string will be on the right. Consider the program in Example 7-3.

Example 7-3. The list_glyphs.c program

/*

* list.c -- show a scrolling list with three items in it.

* Each item is an icon (a pattern) and a string.

*/

#include <xview/xview.h>

#include <xview/panel.h>

#include <xview/svrimage.h>

#define gray1_width 16

#define gray1_height 16

static char gray1_bits[ ] = {

0x55, 0x55, 0xaa, 0xaa, 0x55, 0x55, 0xaa, 0xaa, 0x55, 0x55,

0xaa, 0xaa, 0x55, 0x55, 0xaa, 0xaa, 0x55, 0x55, 0xaa, 0xaa,

0x55, 0x55, 0xaa, 0xaa, 0x55, 0x55, 0xaa, 0xaa, 0x55, 0x55,

0xaa, 0xaa

};

#define gray2_width 16

#define gray2_height 16

static char gray2_bits[ ] = {

0x11, 0x11, 0x00, 0x00, 0x44, 0x44, 0x00, 0x00, 0x11, 0x11,

0x00, 0x00, 0x44, 0x44, 0x00, 0x00, 0x11, 0x11, 0x00, 0x00,

0x44, 0x44, 0x00, 0x00, 0x11, 0x11, 0x00, 0x00, 0x44, 0x44,

0x00, 0x00

};

#define gray3_width 16

#define gray3_height 16

static char gray3_bits[ ] = {

0x22, 0x22, 0xee, 0xee, 0x33, 0x33, 0xee, 0xee, 0x22, 0x22,

0xee, 0xee, 0x33, 0x33, 0xee, 0xee, 0x22, 0x22, 0xee, 0xee,

0x33, 0x33, 0xee, 0xee, 0x22, 0x22, 0xee, 0xee, 0x33, 0x33,

0xee, 0xee

};

main(argc, argv)

int argc;

char *argv[ ];

{

Frame frame;

Panel panel;

Server_image gray1, gray2, gray3;

extern void exit(), which_glyph();

xv_init(XV_INIT_ARGS, argc, argv, NULL);

gray1 = (Server_image)xv_create(NULL, SERVER_IMAGE,

XV_WIDTH, gray1_width,

XV_HEIGHT, gray1_height,

SERVER_IMAGE_BITS, gray1_bits,

NULL);

gray2 = (Server_image)xv_create(NULL, SERVER_IMAGE,

Panels

Panels 179

Example 7-3. The list_glyphs.c program (continued)

XV_WIDTH, gray2_width,

XV_HEIGHT, gray2_height,

SERVER_IMAGE_BITS, gray2_bits,

NULL);

gray3 = (Server_image)xv_create(NULL, SERVER_IMAGE,

XV_WIDTH, gray3_width,

XV_HEIGHT, gray3_height,

SERVER_IMAGE_BITS, gray3_bits,

NULL);

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

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

(void) xv_create(panel, PANEL_BUTTON,

PANEL_LABEL_STRING, "quit",

PANEL_NOTIFY_PROC, exit,

NULL);

(void) xv_create(panel, PANEL_LIST,

PANEL_LIST_ROW_HEIGHT, 16,

PANEL_LIST_GLYPHS, gray1, gray2, gray3, NULL,

PANEL_LIST_STRINGS, "Pattern1", "Pattern2", "Pattern3", NULL,

PANEL_LIST_CLIENT_DATAS, 1, 2, 3, NULL,

PANEL_NOTIFY_PROC, which_glyph,

NULL);

window_fit(panel);

window_fit(frame);

xv_main_loop(frame);

}

void

which_glyph(item, string, client_data, op, event, row)

Panel_item item; /* panel list item */

char *string;

caddr_t client_data;

Panel_list_op op;

Event *event;

int row;

{

printf("item = %s (#%d), op = %d0, string, client_data, op);

}

The output produced by list_glyphs.c is shown in Figure 7-14.

The height of each row in the list is determined by the height of the scrolling list font. If

glyphs are used, the programmer is responsible for row height. In the example, all the glyphs

are the same height (16 pixels), so the calculation is easy: PANEL_LIST_ROW_HEIGHT is set

to 16. If a glyph exceeds the row height, then a warning is printed and the glyph is ignored.

The use of the notify procedure is discussed in Section 7.11.4, “List Notification.”

180 XView Programming Manual

Figure 7-14. Output of program list_glyphs.c

7.11.2 Adding and Deleting List Entries

List entries are denoted by row number. The first entry is row 0. Entries are added and delet-

ed from the list at run time. Several attributes enable you to add and delete entries in a list

item. The attributes that let you delete list entries are:

PANEL_LIST_DELETE,

PANEL_LIST_DELETE_ROWS, and PANEL_LIST_DELETE_SELECTED_ROWS. Using

PANEL_LIST_DELETE, the attribute value specifies a single list item to delete. The string

and/or image resources are deallocated and the list is updated appropriately.*

The attribute PANEL_LIST_DELETE_ROWS deletes multiple list item rows. This attribute

takes two integer arguments. The first argument is the starting row number, the second argu-

ment is the number of rows to delete. In the following example, rows 6 through 8 in

panel_list_item are removed. Row 0 is the first row.

xv_set(panel_list_item,

PANEL_LIST_DELETE_ROWS, 6, 2,

NULL);

If you use PANEL_LIST_DELETE to delete multiple list items, you need to delete list items in

descending order. When a row is deleted, the row numbers are adjusted to a sequential order.

For example, to delete rows 1 through 5:

int row;

for (row = 5; row >=1; row--)

xv_set(panel_list_item, PANEL_LIST_DELETE, row, NULL);

To add to a scrolling list, starting at a particular row, you can use PANEL_LIST_IN-

SERT_STRINGS

or PANEL_LIST_INSERT_GLYPHS. PANEL_LIST_INSERT_STRINGS inserts

strings into a specified scrolling list before a specified row. PANEL_LIST_INSERT_GLYPHS

inserts glyphs into a specified scrolling list before a specified row.

*See Appendix D for a description of an improved list insertion method that is available in XView Version 3.2. and

newer releases.

Panels

Panels 181

To add a new row, PANEL_LIST_INSERT is used in the same way as PANEL_LIST_DELETE.

When adding a new row in this manner, all the succeeding row numbers are incremented and

the list size grows by one. Space for a new item is created, and a new string or glyph may be

added. These are all done at the time the attribute is evaluated, so they may be combined into

one xv_set() call. You can move a row by deleting it from its old location and reassign-

ing it to a new location. Look at the following code:

char *buf[128];

strcpy(buf, xv_get(list_item, PANEL_LIST_STRING, 4));

xv_set(list_item,

PANEL_LIST_DELETE, 4,

PANEL_LIST_INSERT, 8,

PANEL_LIST_STRING, 8, buf,

NULL);

The value for the string must be copied because as soon as the list item is deleted, the data is

freed.

If a panel list may not contain duplicate entires,

PANEL_LIST_INSERT_DUPLICATE needs to

be set to FALSE. The default value for this attribute is TRUE, which allows duplicate strings

to be inserted.

7.11.3 List Selection

Items in the list are selected by using the SELECT mouse button while pointing at an item or

by dragging the pointer over the list items, or with the attribute PANEL_LIST_SELECT. When

PANEL_LIST_SELECT is used to select an item that is currently visible, then the list may be

scrolled when PANEL_LIST_SELECT is set. To disable the scrolling, set XV_SHOW to FALSE

for the scrolling list before the specified row is selected with PANEL_LIST_SELECT.

Selected choice(s) can be set at list creation or later by using PANEL_LIST_SELECT. For ex-

ample:

PANEL_LIST_SELECT, 3, TRUE,

will select row three. If the list item is nonexclusive, you can set more than one choice at one

time. For example:

PANEL_LIST_SELECT, 3, TRUE,

PANEL_LIST_SELECT, 13, TRUE,

PANEL_LIST_SELECT, 14, TRUE,

will select rows 3, 13, and 14.

To determine if a row is selected, use:

xv_get(list_item, PANEL_LIST_SELECTED, i);

182 XView Programming Manual