[an error occurred while processing this directive]

HP OpenVMS Systems Documentation

OpenVMS/Hanzi RTL Chinese Screen Management (SMG$) Manual

SMG$SELECT_FROM_MENU

The Make a Selection from the Menu routine lets you move between the menu choices using the arrow keys and lets you make a selection by pressing the Return key.

Format

SMG$SELECT_FROM_MENU keyboard-id ,display-id ,selected-choice-number [,default-choice-number] [,flags] [,help-library] [,timeout] [,word-terminator-code] [,selected-choice-string] [,rendition-set] [,rendition-complement]

RETURNS

OpenVMS usage cond_value

type longword (unsigned)

access write only

mechanism by value

Arguments

keyboard-id

OpenVMS usage identifier

type longword (unsigned)

access read only

mechanism by reference

Identifier of the virtual keyboard from which the terminal user's responses are read. The keyboard-id argument is the address of an unsigned longword containing this identifier.
display-id

OpenVMS usage identifier

type longword (unsigned)

access read only

mechanism by reference

Identifier of the virtual display in which the choices are displayed. The display-id argument is the address of an unsigned longword containing this display identifier. This virtual display must be pasted to a pasteboard and cannot be batched or occluded.
selected-choice-number

OpenVMS usage word_unsigned

type word (unsigned)

access write only

mechanism by reference

Identification number of the menu item selected. The selected-choice-number argument is the address of an unsigned word that receives this number. The selected-choice-number corresponds to the index of the menu item in the static string array specified in SMG$CREATE_MENU.
default-choice-number

OpenVMS usage word_unsigned

type word (unsigned)

access read only

mechanism by reference

Optional identification number of the default menu item. The default-choice-number argument is the address of an unsigned word that contains the number of the default menu item. The default-choice-number corresponds to the index of the default menu item in the static string array specified in SMG$CREATE_MENU. If omitted, the default choice will be the last menu item already selected, or the first item in the menu if no selections have yet been made.
flags

OpenVMS usage mask_longword

type longword (unsigned)

access read only

mechanism by reference

Optional bit mask indicating behavior when a selection is made. The flags argument is the address of an unsigned longword containing the flag. Valid values are as follows:

SMG$M_RETURN_IMMED Returns control to the user when any key other than an arrow key is entered.

SMG$M_REMOVE_ITEM Causes SMG$SELECT_FROM_MENU to allow each menu item to be selected only once.

help-library

OpenVMS usage char_string

type character string

access read only

mechanism by descriptor

Optional help library to use if the PF2/HELP key is pressed. The help-library argument is the address of a descriptor pointing to this help library name. Note that this argument is ignored if flags specifies SMG$M_RETURN_IMMED. The default is SYS$HELP:HELPLIB.HLB.
If the menu item does not consist of ASCII characters, the menu item is not used to get the help text but just invokes help facility to specify the help topic to get some information.
timeout

OpenVMS usage longword_signed

type longword (signed)

access read only

mechanism by reference

Optional timeout value. The timeout argument is the address of a signed longword that specifies the number of seconds to wait for a selection to be made.
word-terminator-code

OpenVMS usage word_unsigned

type word (unsigned)

access write only

mechanism by reference

Optional unsigned word that receives the code indicating which key terminated the read. The word-terminator-code argument is the address of an unsigned word that receives this terminating key code.
selected-choice-string

OpenVMS usage char_string

type character string

access write only

mechanism by descriptor

Optional string that receives the text of the menu item selected. The selected-choice-string is the address of a descriptor pointing to this string.
rendition-set

OpenVMS usage mask_longword

type longword (unsigned)

access read only

mechanism by reference

Attribute specifier. The optional rendition-set argument is the address of a longword bit mask in which each attribute set causes the corresponding attribute to be set in the display. The following attributes can be specified using the rendition-set argument:

SMG$M_BLINK Displays blinking characters.

SMG$M_BOLD Displays characters in higher-than-normal intensity.

SMG$M_REVERSE Displays characters in reverse video; that is, using the opposite of the default rendition of the virtual display.

SMG$M_UNDERLINE Displays underlined characters.

SMG$M_USER1 through
SMG$M_USER8 Displays user-defined attributes.

The display-id argument must be specified when you use the rendition-set argument.
rendition-complement

OpenVMS usage mask_longword

type longword (unsigned)

access read only

mechanism by reference

Attribute complement specifier. The optional rendition-complement argument is the address of a longword bit mask in which each attribute set causes the corresponding attribute to be complemented in the display. All attributes that can be specified with the rendition-set argument can be complemented with the rendition-complement argument. The display-id argument must be specified when you use the rendition-complement argument.
The optional arguments rendition-set and rendition-complement let the user control the attributes of the virtual display. The rendition-set argument sets certain virtual display attributes, while rendition-complement complements these attributes. If the same bit is specified in both the rendition-set and rendition-complement parameters, rendition-set is evaluated first, followed by rendition-complement. By using these two parameters together, the user can control each virtual display attribute in a single procedure call. On a single-attribute basis, the user can cause the following transformations:

Set Complement Action

0 0 Attribute set to default

1 0 Attribute on

0 1 Attribute set to complement of default setting

1 1 Attribute off

Description

SMG$SELECT_FROM_MENU lets you make a selection from the items in the menu. Note that the routine SMG$CREATE_MENU must be called before calling SMG$SELECT_FROM_MENU.
You can move between the various menu items using the arrow keys, and you make a selection by pressing the Return key. Typing a Ctrl/Z selects the current choice and returns the value SMG$_EOF. Note that if there are more menu choices than can be displayed, the display is scrolled, the appropriate arrow key is typed, and the additional menu choices become visible.
The current selection is indicated in reverse video (or in the rendition specified) and by the physical cursor. The selected choice is returned to the caller in the selected-choice-number argument. In addition, the selected item will be removed from the remaining menu items if SMG$M_REMOVE_ITEM is specified for the flags parameter.
SMG$SELECT_FROM_MENU has two modes of operation that are specified using the flags argument. A value without SMG$M_RETURN_IMMED (the default) causes the following behavior:

The user can move among the choices using the arrow keys.
The only keys that select the current item are the following:
Return
DO
SELECT
Enter

HELP or PF2 outputs help for the current item.
Ctrl/W refreshes the screen by calling SMG$REPAINT_SCREEN.
Ctrl/Z selects the current item and returns a value of SMG$_EOF.
PF1/UP_ARROW selects the first item in the menu.
PF1/DOWN_ARROW selects the last item in the menu.
PF1/LEFT_ARROW selects the first item in the current row.
PF1/RIGHT_ARROW selects the last item in the current row.
All other keys are ignored.

A value of SMG$M_RETURN_IMMED enables the following:

The user can move among the menu choices using the arrow keys.
Ctrl/Z selects the current item and returns SMG$_EOF.
Any other key entered selects the current item.

In either case, the following key substitutions can be made:

The LF key can be used in place of Down Arrow.
The BACKSPACE key can be used in place of Left Arrow.
The TAB key can be used in place of Right Arrow.

The SMG$K_TRM_keyname code for the terminating key is returned in the optional word-terminator-code argument. Multiword menu items are allowed.
When the menu items are not ASCII characters, the user can not display the help text for the menu items by the PF2/HELP key, but just invoke the help facility.

Condition Values Returned

SS$_NORMAL Normal successful completion.

SMG$_EOF End of file.

SMG$_NOTPASTED The virtual display is not pasted.

SMG$_INVDIS_ID The display-id is invalid, does not contain a menu, or contains a viewport.

SMG$_ILLBATFNC The virtual display or pasteboard is batched.

SMG$_INVARG Invalid argument or none of the menu items is selectable.

LIB$_xxxx Any completion status returned by LIB$SCOPY.

SMG$_xxxx Any completion status returned by
SMG$CHANGE_RENDITION, SMG$SET_CURSOR_ABS, SMG$BEGIN_DISPLAY_UPDATE, SMG$END_DISPLAY_UPDATE, SMG$READ_KEYSTROKE, SMG$PUT_HELP_TEXT, SMG$SAVE_PHYSICAL_SCREEN, or SMG$RESTORE_PHYSICAL_SCREEN.

Examples

! +
! This VAX Pascal program demonstrates the use of SMG$CREATE_MENU and
! SMG$SELECT_FROM_MENU.  This program creates a block menu
! and allows the user to make selections from the menu.
! -

[INHERIT ('SYS$LIBRARY:STARLET')]
PROGRAM BLOCK_MENU (INPUT,OUTPUT);

CONST
   NULL = 0;

TYPE
   CHAR_STRING = VARYING [20] OF CHAR;
   WORD = [WORD] 0..65535;
   FIXED_STRING = PACKED ARRAY[1..9] OF CHAR;

VAR
   OPTIONS : ARRAY[1..9] OF FIXED_STRING;
   I : INTEGER;
   RET_STATUS : UNSIGNED;
   SELECTED : FIXED_STRING;
   NUMBER, DEF_NUMBER : WORD;
   PB_ID, KB_ID, DISPLAY1, DISPLAY2 : UNSIGNED;
   TERM : WORD;

[EXTERNAL] FUNCTION SMG$CREATE_PASTEBOARD(
                     VAR PASTEBOARD_ID : UNSIGNED
                     ) : INTEGER; EXTERN;


[EXTERNAL] FUNCTION SMG$CREATE_VIRTUAL_KEYBOARD(
                     VAR KEYBOARD_ID : UNSIGNED
                     ) : INTEGER; EXTERN;

[EXTERNAL] FUNCTION SMG$CREATE_VIRTUAL_DISPLAY(
                     NUM_ROWS : INTEGER;
                     NUM_COLS : INTEGER;
                     VAR DISPLAY_ID : UNSIGNED;
                     ATTRIBUTES : UNSIGNED
                     ) : INTEGER; EXTERN;

[EXTERNAL] FUNCTION SMG$PASTE_VIRTUAL_DISPLAY(
                     DISPLAY_ID : UNSIGNED;
                     PASTEBOARD_ID : UNSIGNED;
                     ROW : INTEGER;
                     COL : INTEGER
                     ) : INTEGER; EXTERN;

[EXTERNAL] FUNCTION SMG$CREATE_MENU(
                     DISPLAY_ID : UNSIGNED;
                     CHOICES : ARRAY[A..B : INTEGER] OF FIXED_STRING;
                     MENU_TYPE : UNSIGNED;
                     MENU_FLAGS : UNSIGNED;
                     ROW : INTEGER := %IMMED 0;
                     REND_SET : UNSIGNED := %IMMED 0;
                     REND_COMP : UNSIGNED
                     ) : INTEGER; EXTERN;

[EXTERNAL] FUNCTION SMG$SELECT_FROM_MENU(
                     KEYBOARD_ID : UNSIGNED;
                     DISPLAY_ID : UNSIGNED;
                     VAR SELEC_NUM : WORD;
                     DEFAULT_NUM : WORD;
                     MENU_FLAGS : UNSIGNED;
                     HELP_LIBR : CHAR_STRING := %IMMED 0;
                     TIMEOUT : INTEGER := %IMMED 0;
                     VAR TERM_CODE : WORD;
                     VAR SELEC_STR : FIXED_STRING
                     ) : INTEGER; EXTERN;

[EXTERNAL] FUNCTION SMG$PUT_LINE(
                     DISPLAY_ID : UNSIGNED;
                     TEXT : CHAR_STRING
                     ) : INTEGER; EXTERN;

[EXTERNAL] FUNCTION SMG$DELETE_MENU(
                     DISPLAY_ID : UNSIGNED
                     ) : INTEGER; EXTERN;


[EXTERNAL] FUNCTION LIB$STOP(
                     CONDITION_STATUS : [IMMEDIATE,UNSAFE] UNSIGNED
                     ) : INTEGER; EXTERN;


BEGIN

DEF_NUMBER := 5;

OPTIONS[1] := 'Northwest';
OPTIONS[2] := 'North    ';
OPTIONS[3] := 'Northeast';
OPTIONS[4] := 'West     ';
OPTIONS[5] := 'Equator  ';
OPTIONS[6] := 'East     ';
OPTIONS[7] := 'Southwest';
OPTIONS[8] := 'South    ';
OPTIONS[9] := 'Southeast';


RET_STATUS := SMG$CREATE_PASTEBOARD (PB_ID);
IF NOT ODD(RET_STATUS)
THEN
   LIB$STOP(RET_STATUS);

RET_STATUS := SMG$CREATE_VIRTUAL_KEYBOARD (KB_ID);
IF NOT ODD(RET_STATUS)
THEN
   LIB$STOP(RET_STATUS);

RET_STATUS := SMG$CREATE_VIRTUAL_DISPLAY (3, 12, DISPLAY2, SMG$M_BORDER);
IF NOT ODD(RET_STATUS)
THEN
   LIB$STOP(RET_STATUS);

RET_STATUS := SMG$CREATE_VIRTUAL_DISPLAY (6, 37, DISPLAY1, SMG$M_BORDER);
IF NOT ODD(RET_STATUS)
THEN
   LIB$STOP(RET_STATUS);

RET_STATUS := SMG$PASTE_VIRTUAL_DISPLAY (DISPLAY2, PB_ID, 2, 16);
IF NOT ODD(RET_STATUS)
THEN
   LIB$STOP(RET_STATUS);

RET_STATUS := SMG$PASTE_VIRTUAL_DISPLAY (DISPLAY1, PB_ID, 10, 10);
IF NOT ODD(RET_STATUS)
THEN
   LIB$STOP(RET_STATUS);

RET_STATUS := SMG$CREATE_MENU (DISPLAY1, OPTIONS, SMG$K_BLOCK,
               SMG$M_DOUBLE_SPACE,,, SMG$M_BOLD);
IF NOT ODD(RET_STATUS)
THEN
   LIB$STOP(RET_STATUS);

RET_STATUS := SMG$SELECT_FROM_MENU (KB_ID, DISPLAY1, NUMBER, DEF_NUMBER,
               SMG$M_RETURN_IMMED,,, TERM, %DESCR SELECTED);
IF NOT ODD(RET_STATUS)
THEN
   LIB$STOP(RET_STATUS);

RET_STATUS := SMG$PUT_LINE (DISPLAY2, %DESCR SELECTED);
IF NOT ODD(RET_STATUS)
THEN
   LIB$STOP(RET_STATUS);

END.

The output for this VAX Pascal program is shown in the following figures. In Figure SMG-49, the program is waiting for the user to make a menu selection.
Figure SMG-49 Output Generated Before a Menu Selection Is Made

Because the menu is created using the SMG$M_RETURN_IMMED attribute, once the user makes a selection the menu is terminated, and control returns to the program. The menu item selected by the user is displayed in the upper virtual display. This output is shown in Figure SMG-50.

Figure SMG-50 Output Generated After the User Selects an Item

10      !+
        !This VAX BASIC program demonstrates the use of
        !SMG-supported menus. Using SMG$CREATE_MENU and
        !SMG$SELECT_FROM_MENU, this program creates an
        !application that uses a vertical menu and allows
        !the user to make multiple selections.
        !-

        OPTION TYPE = EXPLICIT

        EXTERNAL SUB LIB$STOP (LONG BY VALUE)
        EXTERNAL LONG FUNCTION SMG$CREATE_PASTEBOARD (LONG)
        EXTERNAL LONG FUNCTION SMG$CREATE_VIRTUAL_KEYBOARD (LONG)
        EXTERNAL LONG FUNCTION SMG$CREATE_VIRTUAL_DISPLAY (LONG, LONG, &
                                LONG, LONG, LONG)
        EXTERNAL LONG FUNCTION SMG$PASTE_VIRTUAL_DISPLAY (LONG, LONG, &
                                LONG, LONG)
        EXTERNAL LONG FUNCTION SMG$CREATE_MENU (LONG, STRING DIM(), LONG, &
                                LONG, LONG, LONG, LONG)
        EXTERNAL LONG FUNCTION SMG$SELECT_FROM_MENU (LONG, LONG, WORD, &
                                WORD, LONG, STRING, LONG, WORD, STRING)
        EXTERNAL LONG FUNCTION SMG$PUT_LINE (LONG, STRING)
        EXTERNAL LONG FUNCTION SMG$DELETE_MENU (LONG)

        %INCLUDE "$SMGDEF" %FROM %LIBRARY "SYS$LIBRARY:BASIC$STARLET"

        DECLARE STRING chosen
        MAP (xyz) STRING choice(20) = 16
        DECLARE LONG ret_status, pasteboard_id, display1_id, display2_id, &
                     keyboard_id
        DECLARE WORD number

        choice(0) = "ONE"
        choice(1) = "TWO"
        choice(2) = "THREE"
        choice(3) = "FOUR"
        choice(4) = "FIVE"
        choice(5) = "SIX"
        choice(6) = "SEVEN"
        choice(7) = "EIGHT"
        choice(8) = "NINE"
        choice(9) = "TEN"
        choice(10) = "ELEVEN"
        choice(11) = "TWELVE"
        choice(12) = "THIRTEEN"
        choice(13) = "FOURTEEN"
        choice(14) = "FIFTEEN"
        choice(15) = "SIXTEEN"
        choice(16) = "SEVENTEEN"
        choice(17) = "EIGHTEEN"
        choice(18) = "NINETEEN"
        choice(19) = "TWENTY"
        choice(20) = "Exit"

        ret_status = SMG$CREATE_PASTEBOARD (pasteboard_id)
        IF (ret_status AND 1%) = 0% THEN
           CALL LIB$STOP (ret_status BY VALUE)
        END IF

        ret_status = SMG$CREATE_VIRTUAL_KEYBOARD (keyboard_id)
        IF (ret_status AND 1%) = 0% THEN
           CALL LIB$STOP (ret_status BY VALUE)
        END IF

        ret_status = SMG$CREATE_VIRTUAL_DISPLAY (10, 20, display1_id, &
                      SMG$M_BORDER, SMG$M_BOLD)
        IF (ret_status AND 1%) = 0% THEN
           CALL LIB$STOP (ret_status BY VALUE)
        END IF

        ret_status = SMG$CREATE_VIRTUAL_DISPLAY (6, 20, display2_id, &
                      SMG$M_BORDER,)
        IF (ret_status AND 1%) = 0% THEN
           CALL LIB$STOP (ret_status BY VALUE)
        END IF

        ret_status = SMG$PASTE_VIRTUAL_DISPLAY (display2_id, &
                      pasteboard_id, 17, 20)
        IF (ret_status AND 1%) = 0% THEN
           CALL LIB$STOP (ret_status BY VALUE)
        END IF

        ret_status = SMG$PASTE_VIRTUAL_DISPLAY (display1_id, &
                      pasteboard_id, 4, 20)
        IF (ret_status AND 1%) = 0% THEN
           CALL LIB$STOP (ret_status BY VALUE)
        END IF

        ret_status = SMG$CREATE_MENU (display1_id, choice(), &
                      SMG$K_VERTICAL,,,SMG$M_BOLD, SMG$M_BOLD)
        IF (ret_status AND 1%) = 0% THEN
           CALL LIB$STOP (ret_status BY VALUE)
        END IF

20      ret_status = SMG$SELECT_FROM_MENU (keyboard_id, display1_id, &
                      number,, SMG$M_REMOVE_ITEM,,,,chosen)
        IF (ret_status AND 1%) = 0% THEN
           CALL LIB$STOP (ret_status BY VALUE)
        END IF

        ret_status = SMG$PUT_LINE (display2_id, chosen)
        IF (ret_status AND 1%) = 0% THEN
           CALL LIB$STOP (ret_status BY VALUE)
        END IF

        IF (number <> 20) THEN
           GOTO 20
        END IF

        ret_status = SMG$DELETE_MENU (display1_id)
        IF (ret_status AND 1%) = 0% THEN
           CALL LIB$STOP (ret_status BY VALUE)
        END IF

        END

The vertical menu generated by this VAX BASIC program is shown in the following figures. The default choice is set to the first item in the menu: "ONE". In Figure SMG-51, the program is waiting for the user to make a selection from the menu.
Figure SMG-51 Output Generated Before the User Selects a Menu Item

Because the menu was created with the SMG$M_REMOVE_ITEM attribute, the user cannot reselect a particular menu item. However, unlike Example 1, the user can make multiple selections. In Figure SMG-52, the user has selected "SIX" and "THIRTEEN", and the program has again highlighted the default menu item and is waiting for the user to make another selection.

Figure SMG-52 Output Generated After Two Selections

In Figure SMG-53, the user has selected "EXIT" and the menu has been deleted, although it still appears on the screen. At this point, no more selections can be made.

Figure SMG-53 Output Generated After EXIT Is Selected


C+
C This DEC Fortran example program illustrates the use of
C SMG$CREATE_MENU, SMG$SELECT_FROM_MENU, and SMG$DELETE_MENU
C to create an application that lets a user make multiple
C selections from a horizontal menu.
C-

        IMPLICIT INTEGER (A-Z)
        INCLUDE '($SMGDEF)'


        CHARACTER*20 c
        CHARACTER*20 a(20) /'One','Two','Three','This is Four','Five',
     1                  'Six','Seven','Eight','Nine','I like ten',
     2                  'Eleven','Twelve','Thirteen','Fourteen',
     3                  'Fifteen','Sixteen','Seventeen','Eighteen',
     4                  'Nineteen','Exit this menu.' /

        s = SMG$CREATE_PASTEBOARD(p_id)
        if (.not. s) call LIB$SIGNAL(%VAL(s))
        s = SMG$CREATE_VIRTUAL_KEYBOARD(k_id)
        if (.not. s) call LIB$SIGNAL(%VAL(s))
        s = SMG$CREATE_VIRTUAL_DISPLAY(6,50, d_id2, SMG$M_BORDER)
        if (.not. s) call LIB$SIGNAL(%VAL(s))
        s = SMG$CREATE_VIRTUAL_DISPLAY(6,50, d_id, SMG$M_BORDER)
        if (.not. s) call LIB$SIGNAL(%VAL(s))

        s = SMG$PASTE_VIRTUAL_DISPLAY(d_id2, p_id, 2,2)
        if (.not. s) call LIB$SIGNAL(%VAL(s))
        s = SMG$PASTE_VIRTUAL_DISPLAY(d_id, p_id, 10,2)
        if (.not. s) call LIB$SIGNAL(%VAL(s))

        s = SMG$CREATE_MENU(d_id,a,SMG$K_HORIZONTAL,,2,SMG$M_REVERSE)
        if (.not. s) call LIB$SIGNAL(%VAL(s))

  20    s = SMG$SELECT_FROM_MENU(k_id, d_id, n,6,,,,,C,SMG$M_BOLD,0)
        if (.not. s) call LIB$SIGNAL(%VAL(s))
        s = SMG$PUT_LINE(d_id2,c)
        if (.not. s) call LIB$SIGNAL(%VAL(s))

        if (n .ne. 20) goto 20

        s = SMG$DELETE_MENU(d_id)
        if (.not. s) call LIB$SIGNAL(%VAL(s))
 END

The horizontal menu generated by this DEC Fortran example program is shown in the following figures. In Figure SMG-54, the program displays all menu items in reverse video except for the default choice. At this point, the program is waiting for the user to make a selection.
Figure SMG-54 Output Generated Before a Menu Item Is Selected

Because no attributes were specified when this menu was created, the items in the menu can be "reselected". Figure SMG-55 shows the screen image after the user has made three selections, two of which are the same.

Figure SMG-55 Output Generated After Three Menu Selections

In Figure SMG-56, the user has selected "Exit this menu" and the program has completed execution.

Figure SMG-56 Output Generated After Program Completion

Contents