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.

REQ_NEXT_ITEM: move to next item
REQ_PREV_ITEM: move to previous item
REQ_FIRST_ITEM: move to first item
REQ_LAST_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.

REQ_LEFT_ITEM: move left to item
REQ_RIGHT_ITEM: move right to item
REQ_UP_ITEM: move up to item
REQ_DOWN_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.

REQ_SCR_DLINE: scroll menu down a line
REQ_SCR_ULINE: scroll menu up a line
REQ_SCR_DPAGE: scroll menu down a page
REQ_SCR_UPAGE: 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.

REQ_TOGGLE_ITEM: 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

by calling set_menu_pattern (described below)
by passing the menu driver printable ASCII characters one at a time.

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.

REQ_CLEAR_PATTERN: clear pattern buffer
REQ_BACK_PATTERN: delete last character from pattern buffer
REQ_NEXT_MATCH: move to next pattern match
REQ_PREV_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