Document revision date: 30 March 2001

The Change the Viewport Associated with a Virtual Display routine changes the size of an existing viewport in a virtual display. The text currently in the viewport is remapped to fit the new dimensions.

Format

SMG$CHANGE_VIEWPORT display-id [,viewport-row-start] [,viewport-column-start] [,viewport-number-rows] [,viewport-number-columns]

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

Identifier of the virtual display containing the viewport to be changed. The display-id argument is the address of an unsigned longword containing this identifier.

viewport-row-start

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

Optional row number in the virtual display that will become row 1 in the changed viewport. The viewport-row-start argument is the address of a signed longword containing the row number. If omitted, the present viewport-row-start value is used.

viewport-column-start

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

Optional column number in the virtual display that will become column 1 in the changed viewport. The viewport-column-start argument is the address of a signed longword containing the column number. If omitted, the present viewport-column-start value is used.

viewport-number-rows

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

Optional number of rows in the changed viewport. The viewport-number-rows argument is the address of a signed longword containing the number of rows. If omitted, the present viewport-number-rows value is used.

viewport-number-columns

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

Optional number of columns in the changed viewport. The viewport-number-columns argument is the address of a signed longword containing the number of columns. If omitted, the present viewport-number-columns value is used.

Description

SMG$CHANGE_VIEWPORT lets you change the size of an existing viewport in a virtual display. The text currently in this viewport is remapped to fit the new dimensions, starting at the position specified by the viewport-row-start and viewport-column-start arguments. This position also specifies the resulting virtual cursor location.

Condition Values Returned

SS$_NORMAL	Normal successful completion.
SMG$_INVARG	Number of rows or columns is less than zero.
SMG$_INVCOL	Invalid column specified.
SMG$_INVDIS_ID	Invalid display-id.
SMG$_INVROW	Invalid row specified.
SMG$_NO_WINASSOC	No viewport associated with the virtual display.
SMG$_WRONUMARG	Wrong number of arguments.

Example

C+ 
C This Fortran example program demonstrates the use of 
C SMG$CHANGE_VIEWPORT. 
C- 
 
 
 IMPLICIT INTEGER (A-Z) 
 INCLUDE '($SMGDEF)' 
 
C Create the virtual display. Give it a border. 
 
 ROWS = 9 
 COLUMNS = 50 
 
 STATUS = SMG$CREATE_VIRTUAL_DISPLAY 
     1         (ROWS, COLUMNS, DISPLAY1,SMG$M_BORDER ) 
 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 in the virtual display. 
 
 STATUS = SMG$PUT_CHARS ( DISPLAY1, 
 1 'This is row 1 in a virtual display with 9 rows.',1,1) 
 IF (.not. STATUS) CALL LIB$SIGNAL(%val(STATUS)) 
 
 STATUS = SMG$PUT_CHARS ( DISPLAY1, 
 1 'This is row 2 in a virtual display with 9 rows.',2,1) 
 IF (.not. STATUS) CALL LIB$SIGNAL(%val(STATUS)) 
 
 STATUS = SMG$PUT_CHARS ( DISPLAY1, 
 1 'This is row 3 in a virtual display with 9 rows.',3,1) 
 IF (.not. STATUS) CALL LIB$SIGNAL(%val(STATUS)) 
 
 STATUS = SMG$PUT_CHARS ( DISPLAY1, 
 1 'This is row 4 in a virtual display with 9 rows.',4,1) 
 IF (.not. STATUS) CALL LIB$SIGNAL(%val(STATUS)) 
 
 STATUS = SMG$PUT_CHARS ( DISPLAY1, 
 1 'This is row 5 in a virtual display with 9 rows.',5,1) 
 IF (.not. STATUS) CALL LIB$SIGNAL(%val(STATUS)) 
 
 STATUS = SMG$PUT_CHARS ( DISPLAY1, 
 1 'This is row 6 in a virtual display with 9 rows.',6,1) 
 IF (.not. STATUS) CALL LIB$SIGNAL(%val(STATUS)) 
 
 STATUS = SMG$PUT_CHARS ( DISPLAY1, 
 1 'This is row 7 in a virtual display with 9 rows.',7,1) 
 IF (.not. STATUS) CALL LIB$SIGNAL(%val(STATUS)) 
 
 STATUS = SMG$PUT_CHARS ( DISPLAY1, 
 1 'This is row 8 in a virtual display with 9 rows.',8,1) 
 IF (.not. STATUS) CALL LIB$SIGNAL(%val(STATUS)) 
 
 STATUS = SMG$PUT_CHARS ( DISPLAY1, 
 1 'This is row 9 in a virtual display with 9 rows.',9,1) 
 IF (.not. STATUS) CALL LIB$SIGNAL(%val(STATUS)) 
 
C Paste the virtual display. 
 
 STATUS = SMG$COPY_VIRTUAL_DISPLAY(DISPLAY1,DISPLAY2) 
 IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS)) 
 
 STATUS = SMG$LABEL_BORDER (DISPLAY1, 'Full Display',,,SMG$M_BOLD) 
 IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS)) 
 
 STATUS = SMG$LABEL_BORDER (DISPLAY2, 'Viewport',,,SMG$M_BOLD) 
 IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS)) 
 
 STATUS = SMG$PASTE_VIRTUAL_DISPLAY ( DISPLAY1, PASTE1, 2, 10) 
 IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS)) 
 
 STATUS = SMG$PASTE_VIRTUAL_DISPLAY ( DISPLAY2, PASTE1, 13, 10) 
 IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS)) 
 CALL LIB$WAIT (4.0) 
 
 STATUS = SMG$CREATE_VIEWPORT ( DISPLAY2, 2, 1, 5, 21) 
 IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS)) 
 CALL LIB$WAIT (4.0) 
 
 STATUS = SMG$PASTE_VIRTUAL_DISPLAY ( DISPLAY2, PASTE1, 13, 10) 
 IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS)) 
 CALL LIB$WAIT (4.0) 
 
 STATUS = SMG$CHANGE_VIEWPORT ( DISPLAY2, 4, 8, 3, 15) 
 IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS)) 
 call lib$wait (4.0) 
 
 END 
 
 
      

The output generated by this Fortran example is shown in the following figures. In Figure SMG-1, the program has copied the initial virtual display into a second virtual display, labeled "Viewport."

Figure SMG-1 Output Generated After Virtual Displays Are Pasted

After the two identical virtual displays are pasted, the program creates a viewport on the second (copy) virtual display. Once the second display is "repasted," only the portion located in the viewport is visible. This is shown in Figure SMG-2.

Figure SMG-2 Output Generated After the Viewport Is Created

By calling SMG$CHANGE_VIEWPORT, the portion of the virtual display that is visible through the viewport is changed. This is shown in Figure SMG-3.

Figure SMG-3 Output Generated After Calling SMG$CHANGE_VIEWPORT

The Change Virtual Display routine lets you change the dimensions, border, and video attributes of a virtual display.

Format

SMG$CHANGE_VIRTUAL_DISPLAY display-id [,number-of-rows] [,number-of-columns] [,display-attributes] [,video-attributes] [,character-set]

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 whose attributes are to be changed. 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.

number-of-rows

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

Specifies the new number of rows for the virtual display. The number-of-rows argument is the address of a signed longword that contains the number of rows in the virtual display.

number-of-columns

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

Specifies the new number of columns for the virtual display. The number-of-columns argument is the address of a signed longword that contains the number of columns in the virtual display.

display-attributes

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

Specifies the attributes of the virtual display. The display-attributes argument is the address of a longword bit mask that contains the display attributes.

Valid values for display-attributes are as follows:

SMG$M_BORDER	Specifies a bordered display. If omitted, the display is not bordered.
SMG$M_BLOCK_BORDER	Specifies a block bordered display. If omitted, the display is not bordered.
SMG$M_DISPLAY_CONTROLS	Specifies that control characters such as carriage return and line feed are displayed as graphic characters, if your terminal supports them.
SMG$M_TRUNC_ICON	Specifies that an icon (generally a diamond shape) is displayed where truncation of a line exceeding the width of the virtual display has occurred.

video-attributes

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

Specifies the default rendition to be applied to all output in a virtual display, unless overridden by a call to a specific output routine. The video-attributes argument is the address of an unsigned longword that contains the video attributes mask.

For example, a call to SMG$PUT_CHARS with an explicit rendition specified would override the default rendition.

The bits that can be set for this argument are as follows:

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, to the opposite of the current default rendition of the virtual display.
SMG$M_UNDERLINE	Displays underlined characters.
SMG$M_INVISIBLE	Specifies invisible characters; that is, the characters exist in the virtual display but do not appear on the pasteboard.
SMG$M_USER1 through SMG$M_USER8	Displays user-defined attributes.

You can specify any combination of attributes in a single call. All other bits are reserved for use by Compaq and must be 0.

character-set

OpenVMS usage:	longword_unsigned
type:	longword (unsigned)
access:	read only
mechanism:	by reference

Specifies the default character set for all text in this virtual display. The character-set argument is the address of an unsigned longword that contains the character set specifier. Valid values are SMG$C_ASCII (the default), and SMG$C_SPEC_GRAPHICS.

Description

SMG$CHANGE_VIRTUAL_DISPLAY lets you change the size or default attributes of an existing virtual display. If the size of the virtual display is changed, the Screen Management Facility attempts to remap the text associated with the display to fit the new dimensions (starting at row 1 and column 1). If the new size of the virtual display is smaller than the old size, text may be truncated. If the new size of the virtual display is larger than the old size, text may be padded on the right with spaces.

When a display is redimensioned, the virtual cursor for the display is moved to row 1 and column 1. If a labeled border applies to the virtual display and does not fit the redimensioned display, the label is deleted.

If a program calls both SMG$CREATE_PASTEBOARD and SMG$CREATE_VIRTUAL_KEYBOARD, make sure SMG$CREATE_PASTEBOARD is called first. The program will not function correctly if SMG$CREATE_VIRTUAL_KEYBOARD is called before SMG$CREATE_PASTEBOARD.

Condition Values Returned

SS$_NORMAL	Normal successful completion.
LIB$_INSVIRMEM	Insufficient virtual memory to reallocate needed buffers.
SMG$_INVARG	Invalid video or display attributes.
SMG$_INVDIS_ID	Invalid display-id.
SMG$_WRONUMARG	Wrong number of arguments.

The Check for Occlusion routine checks to see whether a virtual display is covered (occluded) by another virtual display.

Format

SMG$CHECK_FOR_OCCLUSION display-id ,pasteboard-id ,occlusion-state

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 to be checked. 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.

pasteboard-id

OpenVMS usage:	identifier
type:	longword (unsigned)
access:	read only
mechanism:	by reference

Specifies the pasteboard to be checked. 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.

occlusion-state

OpenVMS usage:	longword_signed
type:	longword (signed)
access:	write only
mechanism:	by reference

Receives the value denoting whether the display is occluded. The occlusion-state argument is the address of a signed longword into which the occlusion state is written. Occlusion-state is set to 1 if the display is occluded or set to 0 if the display is not occluded on the specified pasteboard. If the procedure does not return SS$_NORMAL, the contents of occlusion-state are undefined.

Description

SMG$CHECK_FOR_OCCLUSION determines whether a specified virtual display as pasted to the specified pasteboard is occluded, or covered, by another virtual display.

Condition Values Returned

SS$_NORMAL	Normal successful completion.
SMG$_INVDIS_ID	Invalid display-id.
SMG$_INVPAS_ID	Invalid pasteboard-id.
SMG$_NOTPASTED	Specified virtual display is not pasted to the specified pasteboard.
SMG$_WRONUMARG	Wrong number of arguments.

Example

    
C+ 
C This Fortran example program demonstrates the use of 
C SMG$CHECK_FOR_OCCLUSION. 
C 
C This routine creates a virtual display and writes it to the 
C pasteboard.  Data is placed in the virtual display using SMG$PUT_CHARS. 
C- 
 
        INTEGER SMG$CREATE_VIRTUAL_DISPLAY, SMG$CREATE_PASTEBOARD 
        INTEGER SMG$PASTE_VIRTUAL_DISPLAY,  SMG$PUT_CHARS 
        INTEGER SMG$CHECK_FOR_OCCLUSION 
        INTEGER DISPLAY1, DISPLAY2, PASTE1, PASTE2, ROWS, COLUMNS, BORDER 
        INTEGER OCCLUSION, STATUS 
        CHARACTER*29 TEXT 
 
C+ 
C Include the SMG definitions. In particular, we want SMG$M_BORDER. 
C- 
 
        INCLUDE '($SMGDEF)' 
 
C+ 
C Create two virtual displays using SMG$CREATE_VIRTUAL_DISPLAY. 
C Give them borders. 
C- 
 
        ROWS = 6 
        COLUMNS = 50 
 
        STATUS = SMG$CREATE_VIRTUAL_DISPLAY 
     1          (ROWS, COLUMNS, DISPLAY1, SMG$M_BORDER) 
        IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS)) 
 
        ROWS = 5 
        COLUMNS = 30 
 
        STATUS = SMG$CREATE_VIRTUAL_DISPLAY 
     1          (ROWS, COLUMNS, DISPLAY2, SMG$M_BORDER) 
        IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS)) 
 
C+ 
C Create the pasteboard using SMG$CREATE_PASTEBOARD. 
C- 
 
        STATUS = SMG$CREATE_PASTEBOARD (PASTE1) 
        IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS)) 
 
C+ 
C Use SMG$PUT_CHARS to put data into the virtual displays. 
C- 
 
        STATUS = SMG$PUT_CHARS ( DISPLAY1, 
     1         ' This virtual display has 6 rows and 50 columns.', 2, 1) 
        IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS)) 
 
        STATUS = SMG$PUT_CHARS ( DISPLAY1, 
     1         ' This is a bordered virtual display.', 3, 1) 
        IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS)) 
 
        STATUS = SMG$PUT_CHARS ( DISPLAY1, 
     1         ' SMG$PUT_CHARS puts data in this virtual display.', 4, 
     1          1) 
        IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS)) 
 
        STATUS = SMG$PUT_CHARS ( DISPLAY1, 
     1         ' This text should be partially occluded.', 5, 1) 
        IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS)) 
 
        STATUS = SMG$PUT_CHARS ( DISPLAY1, 
     1         ' So should part of this row.', 6, 1) 
        IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS)) 
 
        STATUS = SMG$PUT_CHARS ( DISPLAY2, ' This is virtual', 3, 1) 
        IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS)) 
 
        STATUS = SMG$PUT_CHARS ( DISPLAY2, 
     1         ' display #2.', 4, 1) 
        IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS)) 
 
        STATUS = SMG$PUT_CHARS ( DISPLAY2, 
     1         ' This is just some more text.', 5, 1) 
        IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS)) 
 
C+ 
C Use SMG$PASTE_VIRTUAL_DISPLAY to paste the virtual display. 
C- 
 
        STATUS = SMG$PASTE_VIRTUAL_DISPLAY ( DISPLAY1, PASTE1, 4, 15) 
        IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS)) 
 
        STATUS = SMG$PASTE_VIRTUAL_DISPLAY ( DISPLAY2, PASTE1, 8, 15) 
        IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS)) 
 
C+ 
C Check the two virtual displays for occlusion by calling 
C SMG$CHECK_FOR_OCCLUSION. 
C- 
 
        TEXT = 'This display is not occluded.' 
 
        STATUS = SMG$CHECK_FOR_OCCLUSION (DISPLAY1, PASTE1, OCCLUSION) 
        IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS)) 
 
        IF (OCCLUSION .EQ. 0) THEN 
                STATUS = SMG$PUT_CHARS (DISPLAY1, TEXT, 1, 1) 
                IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS)) 
        ELSE 
                STATUS = SMG$PUT_CHARS (DISPLAY1, 'Occluded.', 1 , 1) 
                IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS)) 
        END IF 
 
        STATUS = SMG$CHECK_FOR_OCCLUSION (DISPLAY2, PASTE1, OCCLUSION) 
        IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS)) 
 
        IF (OCCLUSION .EQ. 0) THEN 
                STATUS = SMG$PUT_CHARS (DISPLAY2, TEXT, 1, 1) 
                IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS)) 
        ELSE 
                STATUS = SMG$PUT_CHARS (DISPLAY2, 'Occluded.', 1 , 1) 
                IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS)) 
        END IF 
 
        END 
 
      

The output generated by this Fortran program is shown in Figure SMG-4.

Figure SMG-4 Output Generated by Fortran Program Calling SMG$CHECK_FOR_OCCLUSION

	privacy and legal statement
5935PRO_010.HTML