Document revision date: 30 March 2001

## OpenVMS RTL Screen Management (SMG$) Manual

Previous | Contents | Index

## SMG$SCROLL_DISPLAY_AREA

> The Scroll Display Area routine scrolls a rectangular region of a virtual display.

### Format

> SMG$SCROLL_DISPLAY_AREA display-id [,start-row] [,start-column] [,height] [,width] [,direction] [,count]

### 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 scrolling takes place. 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 first row of the scrolling region. The start-row argument is the address of a signed longword that contains the starting row.

> If start-row is omitted, row 1 of the specified virtual display is used.

> #### start-column

> OpenVMS usage: | longword_signed
> type: | longword (signed)
> access: | read only
> mechanism: | by reference

> Specifies the first column of the scrolling region. The start-column argument is the address of a signed longword that contains the starting column.

> If omitted, column 1 of the specified virtual display is used.

> #### height

> OpenVMS usage: | longword_signed
> type: | longword (signed)
> access: | read only
> mechanism: | by reference

> Specifies the number of rows in the scrolling region. The height argument is the address of a signed longword that contains the number of rows.

> If omitted, this value defaults to either the height of the virtual scrolling region (if one has been explicitly set with SMG$SET_DISPLAY_SCROLL_REGION) or the height of the specified virtual display.

> When scrolling a portion of a virtual display that contains double-height, double-width (highwide) characters, it is recommended that you scroll the display an even number of times.

> #### width

> OpenVMS usage: | longword_signed
> type: | longword (signed)
> access: | read only
> mechanism: | by reference

> Specifies the number of columns in the scrolling region. The width argument is the address of a signed longword that contains the number of columns.

> If omitted, this value defaults to the width of the specified virtual display.

> #### direction

> OpenVMS usage: | mask_longword
> type: | longword (unsigned)
> access: | read only
> mechanism: | by reference

> Specifies the direction to scroll. The direction argument is the address of a longword bit mask that contains the direction code.

> Valid values are SMG$M_UP, SMG$M_DOWN, SMG$M_RIGHT, and SMG$M_LEFT. SMG$M_UP is the default.

> #### count

> OpenVMS usage: | longword_signed
> type: | longword (signed)
> access: | read only
> mechanism: | by reference

> Specifies the number of lines or columns to scroll. The count argument is the address of a signed longword that contains the number of units (lines or columns) to scroll. If omitted, one unit is scrolled.

### Description

> SMG$SCROLL_DISPLAY_AREA scrolls a rectangular region of the specified virtual display. It scrolls the region a specified number of lines or columns in the specified direction. After the scroll, the cursor is left at the start-row, start-column position.

### Condition Values Returned

> SS$_NORMAL | Normal successful completion.
> SMG$_INVARG | The defined rectangle is outside the virtual display.
> SMG$_INVCOL | Invalid column.
> SMG$_INVDIS_ID | Invalid display-id.
> SMG$_INVROW | Invalid row.
> SMG$_WRONUMARG | Wrong number of arguments.

## SMG$SCROLL_VIEWPORT

> The Scroll a Display Under a Viewport routine scrolls a virtual display under its associated viewport.

### Format

> SMG$SCROLL_VIEWPORT display-id [,direction] [,count]

### 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

> Display identifier of the virtual display to be scrolled. The display-id argument is the address of an unsigned longword containing this identifier.

> #### direction

> OpenVMS usage: | mask_longword
> type: | longword (unsigned)
> access: | read only
> mechanism: | by reference

> Optional direction specifier. The direction argument is the address of a longword bit mask that contains the direction code specifying the scrolling direction. The optional count argument can be used to specify the number of lines to scroll in the specified direction. Valid values for direction are as follows:

> SMG$M_UP | Scroll count lines upward.
> SMG$M_DOWN | Scroll count lines downward.
> SMG$M_RIGHT | Scroll count columns to the right.
> SMG$M_LEFT | Scroll count columns to the left.

> SMG$M_UP is the default.

> #### count

> OpenVMS usage: | longword_signed
> type: | longword (signed)
> access: | read only
> mechanism: | by reference

> Optional number of rows or columns to be scrolled. The default is 1.

### Description

> SMG$SCROLL_VIEWPORT scrolls a virtual display under its associated viewport. The viewport is actually changing its coordinates as it moves over the virtual display to simulate scrolling; however, it does not change its physical location on the screen. The size of the viewport could change if the viewport moves off the virtual display. To restore the size of the viewport, use SMG$CHANGE_VIEWPORT.

### Condition Values Returned

> SS$_NORMAL | Normal successful completion.
> SMG$_INVARG | The value of count is less than zero.
> SMG$_INVDIS_ID | Invalid display-id.
> SMG$_NO_WINASSOC | No viewport is associated with the specified virtual display.
> SMG$_WINTRUNCFIT | Successful completion; however, the viewport associated with the virtual display has been truncated to fit.
> SMG$_WRONUMARG | Wrong number of arguments.

### Example

    C This Fortran example demonstrates SMG$SCROLL_VIEWPORT.
    C Include the SMG definitions. In particular, we want SMG$M_BORDER.

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

    C Create the Virtual Displays. Give them borders.

            ROWS = 10
            COLUMNS = 22

            STATUS = SMG$CREATE_VIRTUAL_DISPLAY
         1                                (ROWS, COLUMNS, DISPLAY1, SMG$M_BORDER)
            IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))

    C Create viewport

            STATUS = SMG$CREATE_VIEWPORT (DISPLAY1, 2, 2, 3, 10)
            IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))

    C Create the Pasteboard

            STATUS = SMG$CREATE_PASTEBOARD (PASTE1)
            IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))

    C Put data into the Virtual Displays

            STATUS = SMG$PUT_CHARS ( DISPLAY1,'11111111111111', 1, 1)
            IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))
            STATUS = SMG$PUT_CHARS ( DISPLAY1,'This is row 2.', 2, 1)
            IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))
            STATUS = SMG$PUT_CHARS ( DISPLAY1,'33333333333333', 3, 1)
            IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))
            STATUS = SMG$PUT_CHARS ( DISPLAY1,'This is row 4.', 4, 1)
            IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))

            STATUS = SMG$PUT_CHARS ( DISPLAY1,'55555555555555', 5, 1)
            IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))
            STATUS = SMG$PUT_CHARS ( DISPLAY1,'This is row 6.', 6, 1)
            IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))
            STATUS = SMG$PUT_CHARS ( DISPLAY1,'77777777777777', 7, 1)
            IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))
            STATUS = SMG$PUT_CHARS ( DISPLAY1,'This is row 8.', 8, 1)
            IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))
            STATUS = SMG$PUT_CHARS ( DISPLAY1,'99999999999999', 9, 1)
            IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))
            STATUS = SMG$PUT_CHARS ( DISPLAY1,'This is row 10.', 10, 1)
            IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))

    C Paste the Virtual Display

            STATUS = SMG$PASTE_VIRTUAL_DISPLAY ( DISPLAY1, PASTE1, 4, 3)
            IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))

            STATUS = LIB$WAIT (2.0)

            DO 1 I = 1, 3
            STATUS = SMG$SCROLL_VIEWPORT(DISPLAY1,SMG$M_UP,1)
            IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))
            CALL LIB$WAIT (2.0)
    1       CONTINUE

            STATUS = LIB$WAIT (2.0)

     END

> In this example, a single virtual display is created and is associated with a viewport. Since the virtual display is pasted to the pasteboard after it is associated with the viewport, only the portion of the virtual display that falls inside the viewport is visible. This is displayed in Figure SMG-45.

> Figure SMG-45 Output Generated by Pasting the Virtual Display

The call to SMG$SCROLL_VIEWPORT is repeated a total of three times. Figure SMG-46 shows the viewport after the first call to SMG$SCROLL_VIEWPORT.

Figure SMG-46 Output Generated After First Call to SMG$SCROLL_VIEWPORT

Figure SMG-47 shows the contents of the viewport after the second call to SMG$SCROLL_VIEWPORT.

Figure SMG-47 Output Generated After the Second Call to SMG$SCROLL_VIEWPORT

Figure SMG-48 shows the contents of the viewport after the last call to SMG$SCROLL_VIEWPORT.

Figure SMG-48 Output Generated After the Last Call to SMG$SCROLL_VIEWPORT

## 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.

> #### 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. 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 make a selection by pressing the Return key. Pressing Ctrl/Z selects the current choice and returns the value SMG$_EOF. If there are more menu choices than can be displayed, you can scroll the display by pressing the appropriate arrow key, which makes visible additional menu choices.

> 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.

> The SMG$K_TRM_keyname code for the terminating key is returned in the optional word-terminator-code argument. Multiword menu items are allowed.

### Condition Values Returned

> SS$_NORMAL | Normal successful completion.
> SMG$_EOF | End of file.
> SMG$_ILLBATFNC | The virtual display or pasteboard is batched.
> SMG$_INVARG | Invalid argument or none of the menu items is selectable.
> SMG$_INVDIS_ID | The display-id is invalid, does not contain a menu, or contains a viewport.
> SMG$_NOTPASTED | The virtual display is not pasted.
> 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.
> LIB$_ xxxx | Any completion status returned by LIB$SCOPY.

### Examples

#1
    ! +
    ! 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.

> Previous | Next | Contents | Index

> | privacy and legal statement |
> 5935PRO_035.HTML