HP OpenVMS Systems Documentation

OpenVMS RTL Screen Management (SMG$) Manual

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 Fortran example program shows 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 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

SMG$SET_BROADCAST_TRAPPING

The Enable Broadcast Trapping routine enables the trapping of broadcast messages.

Format

SMG$SET_BROADCAST_TRAPPING pasteboard-id [,AST-routine] [,AST-argument]

RETURNS

OpenVMS usage: cond_value

type: longword (unsigned)

access: write only

mechanism: by value

Arguments

pasteboard-id

OpenVMS usage: identifier

type: longword (unsigned)

access: read only

mechanism: by reference

Specifies the pasteboard for which broadcast messages are to be trapped. The pasteboard-id argument is the address of an unsigned longword that contains the pasteboard identifier.
The pasteboard identifier is returned by SMG$CREATE_PASTEBOARD.
AST-routine

OpenVMS usage: ast_procedure

type: procedure value

access: read only

mechanism: by value

The address of an AST routine to be called when a message is received at the pasteboard. The AST-routine argument is the address of the routine's procedure value.
When the AST-routine argument is either omitted or is given a value of 0, the BROADCAST mode is set to synchronize. In this mode, you must periodically call SMG$GET_BROADCAST_MESSAGE to see if any broadcast messages have arrived.
The AST routine is called with five parameters: AST-argument, R0, R1, PC, and PSL (on VAX systems) or PS (on Alpha systems).

AST-argument

OpenVMS usage:	user_arg
type:	longword (unsigned)
access:	read only
mechanism:	by value

A value to be passed to the AST routine. The AST-argument is an unsigned longword that contains the value to be passed to the AST routine.

Description

SMG$SET_BROADCAST_TRAPPING enables the trapping of broadcast messages sent to the specified pasteboard (terminal). When you disable broadcast trapping, any broadcast messages that have been queued to the terminal are lost. If you enable broadcast trapping with SMG$SET_BROADCAST_TRAPPING but do not disable it with SMG$DISABLE_BROADCAST_TRAPPING before the image exits, any messages that have been broadcast to the terminal are lost when the image exits.
The system parameters DEFMBXBUFQUO and DEFMBXMXMSG are used when creating the mailbox that receives broadcast messages.

Condition Values Returned

SS$_NORMAL Normal successful completion.

SMG$_INVPAS_ID Invalid pasteboard-id.

SMG$_NOT_A_TRM Informational message; the pasteboard is not a terminal.

SMG$_WRONUMARG Wrong number of arguments.

Any condition values returned by $DASSGN, $CANCEL, or LIB$ASN_WTH_MBX.

Example

For an example using SMG$SET_BROADCAST_TRAPPING, see the example for SMG$DISABLE_BROADCAST_TRAPPING.

SMG$SET_CURSOR_ABS

The Set Absolute Cursor Position routine moves the virtual cursor to the specified position in a virtual display.

Format

SMG$SET_CURSOR_ABS display-id [,start-row] [,start-column]

RETURNS

OpenVMS usage: cond_value

type: longword (unsigned)

access: write only

mechanism: by value

Arguments

display-id

OpenVMS usage: identifier

type: longword (unsigned)

access: read only

mechanism: by reference

Specifies the virtual display in which to set the virtual cursor position. The display-id argument is the address of an unsigned longword that contains the display identifier.
The display identifier is returned by SMG$CREATE_VIRTUAL_DISPLAY.
start-row

OpenVMS usage: longword_signed

type: longword (signed)

access: read only

mechanism: by reference

Specifies the row position to which the virtual cursor moves. The start-row argument is the address of a signed longword that contains the row number. If omitted, the cursor remains at the current row.
start-column

OpenVMS usage: longword_signed

type: longword (signed)

access: read only

mechanism: by reference

Specifies the column position to which the virtual cursor moves. The start-column argument is the address of a signed longword that contains the column number. If omitted, the virtual cursor remains at the current column.

Description

SMG$SET_CURSOR_ABS moves the virtual cursor to the specified position in the specified virtual display.

Condition Values Returned

SS$_NORMAL Normal successful completion.

SMG$_INVCOL Invalid column.

SMG$_INVDIS_ID Invalid display-id.

SMG$_INVROW Invalid row.

SMG$_WRONUMARG Wrong number of arguments.

SMG$SET_CURSOR_MODE

The Set the Cursor Mode routine turns the physical cursor on or off and selects jump or smooth scrolling.

Format

SMG$SET_CURSOR_MODE pasteboard-id ,flags

RETURNS

OpenVMS usage: cond_value

type: longword (unsigned)

access: write only

mechanism: by value

Arguments

pasteboard-id

OpenVMS usage: identifier

type: longword (unsigned)

access: read only

mechanism: by reference

Pasteboard identifier. The pasteboard-id argument is the address of an unsigned longword that contains the pasteboard identifier.
flags

OpenVMS usage: mask_longword

type: longword (unsigned)

access: read only

mechanism: by reference

Optional bit mask that specifies scrolling and cursor attributes. The flags argument is the address of an unsigned longword that contains the flag. The flags argument accepts the following values:

SMG$M_CURSOR_OFF Clears physical cursor.

SMG$M_CURSOR_ON Displays physical cursor.

SMG$M_SCROLL_JUMP Jump scrolls.

SMG$M_SCROLL_SMOOTH Smooth scrolls.

Description

SMG$SET_CURSOR_MODE turns the cursor on or off and selects jump or smooth scrolling. If your terminal does not have these capabilities defined, this routine has no effect.

Condition Values Returned

SS$_NORMAL Normal successful completion.

SMG$_INVARG Invalid argument.

SMG$_INVPAS_ID Invalid pasteboard-id.

SMG$_WRONUMARG Wrong number of arguments.

SMG$SET_CURSOR_REL

The Move Cursor Relative to Current Position routine moves the virtual cursor the specified number of rows and columns from the current virtual cursor position in a virtual display.

Format

SMG$SET_CURSOR_REL display-id [,delta-row] [,delta-column]

RETURNS

OpenVMS usage: cond_value

type: longword (unsigned)

access: write only

mechanism: by value

Arguments

display-id

OpenVMS usage: identifier

type: longword (unsigned)

access: read only

mechanism: by reference

Specifies the virtual display in which to move the virtual cursor. The display-id argument is the address of an unsigned longword that contains the display identifier.
The display identifier is returned by SMG$CREATE_VIRTUAL_DISPLAY.
delta-row

OpenVMS usage: longword_signed

type: longword (signed)

access: read only

mechanism: by reference

Specifies the number of rows to move the virtual cursor. The delta-row argument is the address of a signed longword that contains the number of rows to move. If omitted, the virtual cursor remains at the current row position. If delta-row is positive, the virtual cursor moves downward the specified number of rows. If delta-row is negative, the virtual cursor moves upward the specified number of rows.
delta-column

OpenVMS usage: longword_signed

type: longword (signed)

access: read only

mechanism: by reference

Specifies the number of columns to move the cursor. The delta-column argument is the address of a signed longword that contains the number of columns to move. If omitted, the virtual cursor remains at the current column position. If delta-column is positive, the virtual cursor moves the specified number of columns to the right. If delta-column is negative, the virtual cursor moves the specified number of columns to the left.

Description

SMG$SET_CURSOR_REL moves the virtual cursor the specified number of rows and columns relative to the current virtual cursor position. If the specified delta-row or delta-column causes the cursor to move outside the bounds of the virtual display, SMG$_INVROW or SMG$_INVCOL is returned.

Condition Values Returned

SS$_NORMAL Normal successful completion.

SMG$_INVARG Invalid argument.

SMG$_INVCOL An invalid value of delta-column caused the cursor to move outside the bounds of the virtual display.

SMG$_INVDIS_ID Invalid display-id.

SMG$_INVROW An invalid value of delta-row caused the cursor to move outside the bounds of the virtual display.

SMG$_WRONUMARG Wrong number of arguments.

Contents

Index