ETI menus

ETI menu requests

ETI menu requests are made by calling function menu_driver with an int value that signifies the request. To appreciate the effects of some requests, bear in mind what a menu page is.

A menu page is the collection of currently visible menu items,
that is, those displayed in the menu subwindow.

A menu page is distinct from a form page, which is a logical portion of a form. Form pages are treated in ``ETI forms''.

Item navigation requests

These requests enable your end user to navigate from item to item whether or not the items are displayed at the moment.

move to next item

move to previous item

move to first item

move to last item
The order of the items in the array originally passed to new_menu or set_menu_items determines the order in which items are visited in response to these requests.

The REQ_NEXT_ITEM and REQ_PREV_ITEM requests are not cyclic. A REQ_NEXT_ITEM request from the last item or a REQ_PREV_ITEM request from the first item returns the value E_REQUEST_DENIED.

Often, a scrolling operation not explicitly requested by the user may nonetheless take place in response to these requests. For example, the REQ_FIRST_ITEM request on a menu that is not currently displaying the first item may scroll to display the menu's first item at the top of the screen.

Directional item navigation requests

These requests enable your end-user to navigate from item to item in different directions.

move left to item

move right to item

move up to item

move down to item
Directional item navigation requests are not cyclic. If there is no item on the current page to the left or right of the current item, the menu driver returns E_REQUEST_DENIED in response to the corresponding request.

On the other hand, if the menu is scrollable and there are more items above or below the current menu page, the corresponding requests REQ_UP_ITEM and REQ_DOWN_ITEM generate an automatic scrolling operation. If not, the menu driver returns E_REQUEST_DENIED.

Menu scrolling requests

These requests enable your users to scroll easily through menus that span more than one menu page.

scroll menu down a line

scroll menu up a line

scroll menu down a page

scroll menu up a page
The current and top items are adjusted by these operations.

Menu scrolling requests are also not cyclic. Attempts to scroll up from the first menu page, or scroll down from the last, return from the menu driver the value E_REQUEST_DENIED.

Multi-valued menu selection request

This request enables your end user to select or deselect an item in a multi-valued menu.

select/deselect item
If the item is currently selected, this request deselects it, and vice versa.

To use this request, the O_ONEVALUE option must be off. (See ``Setting and fetching menu options''.) If the option is on, you have a single-valued menu. In that case, this request fails and E_REQUEST_DENIED is returned from the menu driver.

Pattern buffer requests

The pattern buffer is an area automatically allocated for your menu application programs. It is used to position the current menu item at an item name that matches the pattern. You can modify the pattern buffer

Each non-printable ASCII character that is received by the menu driver is assumed to be a menu request. On the other hand, each printable ASCII character that is received by the menu driver is entered into the pattern buffer. At the same time, the current item advances to the first matching item. If no matching
item is found, the current item remains unchanged, the character is deleted from the pattern buffer, and the menu driver returns E_NO_MATCH.

The following requests enable you to change and read the pattern buffer.

clear pattern buffer

delete last character from pattern buffer

move to next pattern match

move to previous pattern match
Request REQ_CLEAR_PATTERNclears the pattern buffer entirely.

NOTE: Without request REQ_CLEAR_PATTERN, the pattern buffer is automatically cleared after each successful scrolling or item navigation operation. In other words, any time the top item or current item changes, the pattern buffer is cleared automatically.

REQ_BACK_PATTERN deletes the last character from the pattern buffer. This request can be used to support a backspace operation on the pattern buffer.

Sometimes more than one menu item will match the character(s) entered by the user. REQ_NEXT_MATCH moves the user forward on the displayed menu to the next array item that matches the data in the pattern buffer. REQ_PREV_MATCH, on the other hand, moves the user backward on the displayed menu to the previous array item that matches the pattern buffer. In both cases, if no additional match is found, the current item remains unchanged and E_NO_MATCH is returned from the menu driver.

Requests REQ_NEXT_MATCH and REQ_PREV_MATCH are cyclic through all menu items. In addition, these requests generate automatic scrolling requests if the menu is scrollable and the next or previous matching item is not visible.

NOTE: An empty pattern buffer matches all items.

Next topic: Application-defined commands
Previous topic: Sample routine that translates keys into menu requests

© 2004 The SCO Group, Inc. All rights reserved.
UnixWare 7 Release 7.1.4 - 27 April 2004