Document revision date: 19 July 1999
[Compaq] [Go to the documentation home page] [How to order documentation] [Help on this site] [How to contact us]
[OpenVMS documentation]

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:

A value of SMG$M_RETURN_IMMED enables the following:

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

  [Go to the documentation home page] [How to order documentation] [Help on this site] [How to contact us]  
  privacy and legal statement  
5935PRO_035.HTML