Volume 7A: XView Programming Manual

Figure 7-10. Sample panel with nonexclusive choices

Figure 7-10 represents a panel item that has two choices set, the first and the third. The rea-

son for this is that the panel’s value is set to 5, which is a mask that represents the first and

third bits. For example, 5 in binary is . . . 00101.* In the binary representation, the first and

third bits from the right are 1’s. This means that the first and third choices are selected. This

is how the value is interpreted on calls to xv_set() or xv_create(), and how it is re-

turned for calls to xv_get().

To get the image for a choice item’s current choice (assuming the choice item is a

Server_image choice):

Server_image image;

image = (Server_image)xv_get(item, PANEL_CHOICE_IMAGE,

xv_get(item, PANEL_VALUE));

For choice items whose

PANEL_CHOOSE_NONE value is TRUE, a PANEL_VALUE of -1 may be

set or returned, indicating that no choices are set for that item.

Setting PANEL_CHOOSE_NONE allows choice items to have no currently selected item. This

attribute is not applicable if PANEL_CHOOSE_ONE is FALSE.

7.10.3 Abbreviated Choices

Abbreviated choices are exclusive choices that either display no value or only the current

value. A menu is used to display all the choices. To implement abbreviated choice items, the

macro PANEL_CHOICE_STACK is used. This macro creates an abbreviated choice item that

displays only the current value. It is defined as:

PANEL_CHOICE, PANEL_DISPLAY_LEVEL, PANEL_CURRENT

To create an abbreviated choice item that does not display the current value, use the PAN-

EL_ABBREV_MENU_BUTTON

package and set PANEL_DISPLAY_LEVEL to PANEL_NONE (refer

to Section 7.9.4, “Abbreviated Menu Buttons,” for details). The following example demon-

strates creating an abbreviated choice item that displays the current value:

xv_create(panel, PANEL_CHOICE_STACK,

PANEL_LAYOUT, PANEL_VERTICAL,

*The value for nonexclusive choice items is stored as an unsigned int and the maximum number of nonex-

clusive choice items is 32.

Panels

Panels 173

PANEL_LABEL_STRING, "Abbreviated Choice",

PANEL_CHOICE_STRINGS, "One", "Two", "Three", "Four", NULL,

PANEL_NOTIFY_PROC, selected,

PANEL_VALUE, 1,

NULL);

The panel item created by this code is shown in Figure 7-11.

Figure 7-11. Sample panel with abbreviated choice (unselected and selected)

Here, since only the current selection is visible, the only way to make other choices in the

item is to bring up a menu. The value of the panel item is the same as for an exclusive PAN-

EL_CHOICE

item.

7.10.4 Checkbox Choices

Checkboxes are nonexclusive choices that use checkmarks to indicate the selected choices.

Unselected choices have empty checkboxes. The following example demonstrates check-

boxes:

xv_create(panel, PANEL_CHECK_BOX,

PANEL_LAYOUT, PANEL_HORIZONTAL,

PANEL_LABEL_STRING, "Choices",

PANEL_CHOICE_STRINGS, "One", "Two", "Three", "Four", NULL,

PANEL_NOTIFY_PROC, selected,

PANEL_VALUE, 5,

NULL);

The panel item created by this code is shown in Figure 7-12.

174 XView Programming Manual

Figure 7-12. Sample panel with checkbox

All of the choices can be selected in the same way as a PANEL_TOGGLE.

7.10.5 Choice Selection and Notification

The user can make a selection from a choice item by selecting the desired choice directly

with the SELECT mouse button.

The procedure specified via the attribute PANEL_NOTIFY_PROC will be called when any of its

choices are selected. If a choice item’s current selection or value changes as a result of a call

to xv_set() from somewhere else, then the notify procedure is not called. The choice

notify procedure is passed the item, the current value of the item, and the event that caused

notification:

void

choice_notify_proc(item, value, event)

Panel_item item;

int value;

Event *event;

Like the button’s notify procedure, the choice notify procedure is also a void function. If the

function fails to perform its task, you should set the item’s PANEL_NOTIFY_STATUS to

XV_ERROR.

For exclusive choices, the value passed to the notify procedure is the ordinal number corre-

sponding to the current choice (the choice that the user has just selected). The first choice

has ordinal number zero. For nonexclusive choices, the value is a mask of the currently se-

lected choices in the list (see Section 7.11.3, “List Selection”).

The event is the event that caused the notify procedure to be called. For these types of

choices, the event action will probably be ACTION_SELECT.

7.10.6 Foreground Color in Choice Items

Colors for panel choice items may be set with the PANEL_CHOICE_COLOR attribute. This at-

tribute sets the foreground color index for specified choices. The following example demon-

strates a choice using the foreground color attribute.

Panels

Panels 175

xv_create(panel, PANEL_TOGGLE,

PANEL_LABEL_STRING, "Choices",

PANEL_CHOICE_STRINGS, "One", "Two", "Three", "Four", NULL,

PANEL_NOTIFY_PROC, selected,

PANEL_VALUE, 5,

PANEL_CHOICE_COLOR, 0, RED, NULL,

PANEL_CHOICE_COLOR, 1, BLUE, NULL,

PANEL_CHOICE_COLOR, 2, RED, NULL,

PANEL_CHOICE_COLOR, 3, BLUE, NULL,

NULL);

7.10.7 Parallel Lists

Parallel lists are lists of values for particular attributes that correspond to each choice in the

panel item. An example of a parallel list is PANEL_CHOICE_XS and PANEL_CHOICE_YS.

These two attributes take as values a NULL-terminated list of coordinates to specify explicit

placement of the choices when they are displayed (assuming

PANEL_ALL is the display for-

mat).

WARNING

The attributes PANEL_CHOICE_XS, PANEL_CHOICE_YS, PANEL_CHOICE_X and

PANEL_CHOICE_Y are provided for SunView1 Compatibility. They are men-

tioned here for explanatory purposes only. Their use allows you to create appli-

cations that may not be

OPEN LOOK-compliant.

These attributes are used to display choices in adjacent rows and columns, as in the following

example:

xv_create(panel, PANEL_CHOICE,

PANEL_CHOICE_STRINGS, "One", "Two", "Three", NULL,

PANEL_CHOICE_XS, 10, 70, 130, NULL,

PANEL_CHOICE_YS, 90, NULL,

PANEL_VALUE, 2,

PANEL_NOTIFY_PROC, notify_proc,

NULL);

The choice item has three choices: the strings “One”, “Two,” and “Three.” We have speci-

fied explicit positioning of the choice items using the attributes

PANEL_CHOICE_XS and

PANEL_CHOICE_YS. These attributes take precedence over PANEL_LAYOUT, so that layout is

ignored if specified. Note that the list

PANEL_CHOICE_YS has only one element. When any

of the parallel lists are abbreviated in this way, the last element given will be used for the re-

mainder of the choices. So, in the example above:

90, NULL,

serves as shorthand for:

90, 90, 90, NULL,

All the choices will appear at y coordinate 90, while the x coordinates for the choices will be

10, 70, and 130, respectively.

176 XView Programming Manual

You cannot specify that a choice appear at x = 0 or y = 0 by using the attributes

PANEL_CHOICE_XS or PANEL_CHOICE_YS. Since these attributes take NULL-terminated lists

as values, the zero would be interpreted as the terminator for the list. You may achieve the

desired effect by setting the positions individually. The attributes PANEL_CHOICE_X or

PANEL_CHOICE_Y take as values the number of the choice followed by the desired position.

The following example demonstrates setting the position of choice items:

Panel_item choice;

int i;

extern char *strings[ ];

choice = (Panel_item)xv_create(panel, PANEL_CHOICE,

PANEL_CHOOSE_ONE, FALSE,

NULL);

for (i = 0; i < sizeof(strings) / sizeof(char *); i++)

xv_set(choice,

PANEL_CHOICE_STRING, i, strings[i],

PANEL_CHOICE_X, i, i*20,

PANEL_CHOICE_Y, i, i*20,

NULL);

After the choice item is created, the x and y positions of the choices are set individually in a

loop.

Once a set of choice items is created, the rectangle that encloses a specified choice may be

returned using the attribute PANEL_CHOICE_RECT. It takes an integer argument representing

the index of the choice whose rect pointer is returned.

7.11 Scrolling Lists

OPEN LOOK’s specification for scrolling lists is implemented by the PANEL_LIST panel item.

List items allow the user to make selections from a scrolling list of choices larger than can be

displayed on the panel at one time. The selections can be exclusive or nonexclusive, like the

choice items outlined in the previous section. The list is made up of strings or images and a

scrollbar that functions like any scrollbar in XView, except that it cannot be split.* List

items are laid out in rows only—one list entry per row. Below is a code fragment for creating

a simple list:

xv_create(panel, PANEL_LIST,

PANEL_LIST_STRINGS, "One", "Two", "Three", "Four", NULL,

NULL);

The list items produced by this code are shown in Figure 7-13.

*See Chapter 10, Scrollbars, for a further description of how scrollbars work.

Panels

Panels 177