Volume 7A: XView Programming Manual

When a menu button receives an ACTION_MENU down event, the button’s notify procedure is

called before the menu is displayed. This gives you the chance to modify the menu before-

hand. When the menu button is selected by clicking the SELECT button, the button’s notify

procedure is called before the menu’s notify procedure.

Menu buttons contain a triangle pointing in the direction in which the menu will be

displayed.

The btn_menu.c program in Example 7-2 demonstrates how a menu can be attached to a pan-

el button.

Example 7-2. The btn_menu.c program

/*

* btn_menu.c -- display a panel that has an OPEN LOOK menu button.

* The choices displayed are Yes, No and Quit. If Quit is selected

* in the menu, the program exits.

*/

#include <xview/xview.h>

#include <xview/panel.h>

#include <xview/openmenu.h>

main(argc, argv)

int argc;

char *argv[ ];

{

Frame frame;

Panel panel;

Menu menu;

int selected();

void menu_proc();

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

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

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

/* Create the menu _before_ the panel button */

menu = (Menu)xv_create(NULL, MENU,

MENU_NOTIFY_PROC, menu_proc,

MENU_STRINGS, "Yes", "No", "Quit", NULL,

NULL);

(void) xv_create(panel, PANEL_BUTTON,

PANEL_LABEL_STRING, "Y/N/Q",

PANEL_NOTIFY_PROC, selected,

PANEL_ITEM_MENU, menu, /* attach menu to button */

NULL);

window_fit(panel);

window_fit(frame);

xv_main_loop(frame);

}

int

selected(item, event)

Panel_item item;

Event *event;

{

168 XView Programming Manual

Example 7-2. The btn_menu.c program (continued)

printf("%s selected...\n", xv_get(item, PANEL_LABEL_STRING));

return XV_OK;

}

void

menu_proc(menu, menu_item)

Menu menu;

Menu_item menu_item;

{

printf("Menu Item: %s\n", xv_get(menu_item, MENU_STRING));

if (!strcmp((char *)xv_get(menu_item, MENU_STRING), "Quit"))

exit(0);

}

The output produced by this program is shown in Figure 7-7.

7.9.2.1 Destroying menu buttons

XView automatically destroys the menu associated with the button unless there are other ref-

erences to the menu. For each button or any other XView object that references the menu in

question, the menu’s

XV_REF_COUNT is incremented. Thus, if five buttons reference the same

menu, then destroying one button will not destroy the menu, but it will decrement the refer-

ence count by one. If the destruction of the panel item would decrement the menu’s refer-

ence count to 0, then the menu itself is destroyed. Therefore, if you wish to prevent the menu

from being destroyed, you can forcefully increment the menu’s reference count by at least

one more than what it is. That way, no matter how many times the menu is used, its reference

count will always be set to a value greater than zero, and it will never be destroyed by des-

troying panel items that use it. Of course, you can always call xv_destroy() on the menu

explicitly when you want to destroy the menu once and for all.

Figure 7-7. Sample menu button (unselected and selected)

You can use the attributes

XV_INCREMENT_REF_COUNT and XV_DECREMENT_REF_COUNT on

any item.

xv_set(menu, XV_INCREMENT_REF_COUNT, NULL);

Panels

Panels 169

This is not recommended except when you need to circumvent the normal functionality of

XView.

7.9.3 Panel Button Width

The width of a panel button’s string or image is available and can be set with the attribute

PANEL_LABEL_WIDTH. This attribute does not include the width of a panel button’s end caps

or menu marks. PANEL_LABEL_WIDTH has no effect on a PANEL_BUTTON until the panel but-

ton’s PANEL_LABEL_STRING or PANEL_LABEL_IMAGE is set.

To make all the panel buttons the same width for a group of buttons that are not all menu but-

tons or all non-menu buttons, requires three steps:

1. Set the PANEL_LABEL_WIDTH for each button.

2. Find the maximum XV_WIDTH of all the buttons in the group. This value includes the

width of any end caps or menu marks.

3. Finally, add the difference between each button’s

XV_WIDTH and the maximum

XV_WIDTH of all the buttons to each button’s PANEL_LABEL_WIDTH:

xv_set(item, PANEL_LABEL_WIDTH,

(int)xv_get(item, PANEL_LABEL_WIDTH) +

max_XV_WIDTH - (int)xv_get(item,XV_WIDTH),

NULL);

7.9.4 Abbreviated Menu Buttons

Abbreviated menu buttons are just like menu buttons. However, they do not display the label

inside the button, but to the left, as shown in Figure 7-8.

Figure 7-8. Sample abbreviated menu button

170 XView Programming Manual

Abbreviated menu items are created using the PANEL_ABBREV_MENU_BUTTON package.

Panel_item item;

extern Menu menu; /* created separately */

item = xv_create(panel, PANEL_ABBREV_MENU_BUTTON,

PANEL_ITEM_MENU, menu,

NULL);

Notification is the same as in full-size menu buttons.

7.10 Choice Items

Choice items provide a list of different choices to the user in which one or more choices may

be selected. There are variations of choice items which implement different OPEN LOOK ob-

jects such as:

• Exclusive and Nonexclusive Choices (or Settings)

• Abbreviated Choice Items

• Checkboxes

Behind the flexibility of presentation lies a uniform structure consisting of a label, a list of

choices and an indication of which choice or set of choices is currently selected. The choices

can be displayed as either text strings (

PANEL_CHOICE_STRINGS) or server images (PAN-

EL_CHOICE_IMAGES

). The number of choices in a choice list is returned by the PAN-

EL_NCHOICES

attribute. This is true for toggle items as well.

7.10.1 Display and Layout of Item Choices

The attribute

PANEL_DISPLAY_LEVEL

determines which of an item’s choices are actually

displayed. The display level may be set to:

PANEL_ALL The default. All choices are shown.

PANEL_CURRENT Only the current choice is shown.

PANEL_NONE No choices are shown.

The choices are laid out either horizontally or vertically next to the label depending on the

value of the item’s value for

PANEL_LAYOUT. By default, this value is PANEL_HORIZONTAL.

Sometimes the number of choices in a choice list can get long and the menu for the item (if

any) may look aesthetically bad or not fit on the screen. You can specify that choices appear

in row and column layout by specifying either the number of rows or the number of columns

with the attributes PANEL_CHOICE_NROWS and PANEL_CHOICE_NCOLS. If both are specified,

the last one specified takes precedence.

Panels

Panels 171

7.10.2 Exclusive and Nonexclusive Choices

When a default choice item is created, its type is an exclusive choice item allowing the user

to select only one choice from the list. The value of the panel item is the currently selected

choice. The index of the first choice is 0. In the following example, we create several choice

items as exclusive settings:

xv_create(panel, PANEL_CHOICE,

PANEL_LABEL_STRING, "Choice - Exclusive",

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

PANEL_NOTIFY_PROC, selected,

PANEL_VALUE, 3,

NULL);

This code fragment produces the panel item shown in Figure 7-9.

Figure 7-9. Sample panel with exclusive choices

Figure 7-9 represents a panel item that has four choices, the fourth of which is set. If the user

makes another choice, the value of the item, and therefore the value of PANEL_VALUE,

changes to the ordinal number of the choice.

The choice item can be made nonexclusive, allowing more than one of the choices to be se-

lected, when the attribute PANEL_CHOOSE_ONE is set to FALSE. The macro PANEL_TOGGLE

has been defined as:

PANEL_CHOICE, PANEL_CHOOSE_ONE, FALSE

This macro affects the panel item in two ways. More than one choice may be set in the visual

feedback, and the value of the item is set as a mask indicating the choices selected. In the

following example, the choice items in the previous example are shown as nonexclusive set-

tings:

xv_create(panel, PANEL_TOGGLE,

PANEL_LABEL_STRING, "Choice - Nonexclusive",

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

PANEL_NOTIFY_PROC, selected,

PANEL_VALUE, 5,

NULL);

This code fragment would produce the panel item shown in Figure 7-10.

172 XView Programming Manual