 |
OpenVMS/Hanzi RTL Chinese Screen Management (SMG$)
Manual
SMG$RING_BELL
The Ring the Terminal Bell or Buzzer routine sounds the terminal bell
or buzzer.
Format
SMG$RING_BELL display-id [,number-of-times]
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 for which the bell or buzzer sounds. The
display-id argument is the address of an unsigned
longword that contains the display identifier.
Display-id is returned by SMG$CREATE_VIRTUAL_DISPLAY.
number-of-times
| OpenVMS usage |
longword_signed |
| type |
longword integer (signed) |
| access |
read only |
| mechanism |
by reference |
Specifies the number of times the bell or buzzer is sounded. The
number-of-times argument is the address of a signed
longword integer that contains the number of times the bell or buzzer
is sounded. If number-of-times is omitted, 1 is used.
Description
SMG$RING_BELL sounds the bell or buzzer on each pasteboard to which the
specified virtual display is pasted. The bell or buzzer sounds the
number of times specified; the default number of times is 1.
Condition Values Returned
|
SS$_NORMAL
|
Normal successful completion.
|
|
SMG$_INVDIS_ID
|
Invalid
display-id.
|
Any condition values returned by $QIOW, LIB$GET_VM, LIB$FREE_VM.
SMG$SAVE_PHYSICAL_SCREEN
The Save Physical Screen routine saves the contents of the pasteboard
so that a later call to SMG$RESTORE_PHYSICAL_SCREEN can restore it.
Format
SMG$SAVE_PHYSICAL_SCREEN pasteboard-id ,display-id [,desired-start-row]
[,desired-end-row]
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 whose contents are to be saved. The
pasteboard-id argument is the address of an unsigned
longword that contains the pasteboard identifier.
display-id
| OpenVMS usage |
identifier |
| type |
longword (unsigned) |
| access |
write only |
| mechanism |
by reference |
Receives the display identifier of the display created to contain the
contents of the specified pasteboard. The display-id
argument is the address of an unsigned longword into which the display
identifier is written.
Display-id must be passed to the
SMG$RESTORE_PHYSICAL_SCREEN routine to restore the saved information.
desired-start-row
| OpenVMS usage |
longword_signed |
| type |
longword (signed) |
| access |
read only |
| mechanism |
by reference |
Specifies the first row to be saved. The
desired-start-row argument is the address of a signed
longword that contains the row number. If
desired-start-row is omitted, row 1 of the pasteboard
is used.
desired-end-row
| OpenVMS usage |
longword_signed |
| type |
longword (signed) |
| access |
read only |
| mechanism |
by reference |
Specifies the last row to be saved. The
desired-end-row argument is the address of a signed
longword that contains the row number. If
desired-end-row is omitted, the last row of the
pasteboard is used.
Description
SMG$SAVE_PHYSICAL_SCREEN blanks the screen by creating a virtual
display that is as wide as the specified pasteboard and as high as
specified by the desired-start-row and
desired-end-row arguments. If these two arguments are
omitted, the created virtual display is as high as the specified
pasteboard.
The created virtual display does not have a default character-set, so
that display output to the virtual display should consider its
character-set.
The information saved --- that is, the pasteboard image --- can be
restored by calling the SMG$RESTORE_PHYSICAL_SCREEN routine. When
performing multiple calls to SMG$SAVE_PHYSICAL_SCREEN and
SMG$RESTORE_PHYSICAL_SCREEN, the calls must be performed in a nested
order; that is, the last pasteboard saved must be the first one
restored, and so on.
These routines are useful when calling a procedure that may send output
to the screen without using the Screen Management Facility. Before
calling such a procedure, you save the pasteboard image with
SMG$SAVE_PHYSICAL_SCREEN. After the procedure executes, you restore the
pasteboard image with SMG$RESTORE_PHYSICAL_SCREEN.
Note that the saved region must encompass at least two rows. When you
use SMG$SAVE_PHYSICAL_SCREEN on a terminal that does not support
scrolling regions, you must save and restore the entire pasteboard.
Condition Values Returned
|
SS$_NORMAL
|
Normal successful completion.
|
|
SMG$_INVPAS_ID
|
Invalid
pasteboard-id.
|
|
SMG$_INVROW
|
Invalid row, or range specified does not encompass at least two rows.
|
|
SMG$_WRONUMARG
|
Wrong number of arguments.
|
|
LIB$_INSVIRMEM
|
Insufficient virtual memory.
|
SMG$SAVE_VIRTUAL_DISPLAY
The Save the Virtual Display to a File routine saves the contents of a
virtual display and stores it in a file.
Format
SMG$SAVE_VIRTUAL_DISPLAY display-id [,filespec]
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 saved. The
display-id argument is the address of an unsigned
longword that contains the display identifier.
Display-id is returned by SMG$CREATE_VIRTUAL_DISPLAY.
filespec
| OpenVMS usage |
char_string |
| type |
character string |
| access |
read only |
| mechanism |
by descriptor |
String containing the file specification of the file in which the
specified virtual display is saved. The filespec
argument is the address of a descriptor pointing to the character
string containing the file specification.
A new file is created each time this routine is called. If
filespec is omitted, the default file specification is
SMGDISPLY.DAT.
Description
SMG$SAVE_VIRTUAL_DISPLAY saves the contents of a virtual display and
stores it in a nonprintable file. The text, renditions, character sets,
and all attributes necessary to reconstruct the virtual display are
saved. Menu, viewport, and subprocess context are not saved. The
SMG$LOAD_VIRTUAL_DISPLAY routine restores the virtual display.
Condition Values Returned
|
SS$_NORMAL
|
Normal successful completion.
|
|
SMG$_INVDIS_ID
|
Invalid
display-id.
|
|
RMS$_xxxx
|
Any error returned by $OPEN, $CONNECT, $PUT, $CLOSE.
|
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.
Display-id 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. Note that if you omit either
start-row or start-column, the
default (row 1 and column 1) 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. Note
that if you omit either start-row or
start-column, the default (row 1 and column 1) is used.
In the case that the start-column begins on the right
portion of a Chinese character, the character will become two
undefined characters.
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 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 |
longword_unsigned |
| type |
longword (unsigned) |
| access |
read only |
| mechanism |
by reference |
Specifies the direction to scroll. The direction
argument is the address of an unsigned longword 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.
In the case that the Chinese language character set is used, if
the start-column begins on the right portion of the
Chinese character, the Chinese character will become two
undefined characters. If the right most column of the rectangle region
contains the left portion of the Chinese character, the
Chinese character will become two undefined characters.
Also, if the rectangle region scrolls to the left and the left most
column of the scrolled rectangle region contains the right portion of
the Chinese character, the right portion of the Chinese
character will become an undefined character. If the rectangle region
scrolls to the right and the right most column of the scrolled
rectangle region contains the left portion of the Chinese
character, the left portion of the Chinese character will become
an undefined character.
Condition Values Returned
|
SS$_NORMAL
|
Normal successful completion.
|
|
SMG$_INVARG
|
The defined rectangle is outside the virtual display.
|
|
SMG$_INVDIS_ID
|
Invalid
display-id.
|
|
SMG$_INVCOL
|
Invalid column.
|
|
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 |
longword_unsigned |
| type |
longword (unsigned) |
| access |
read only |
| mechanism |
by reference |
Optional direction specifier. The direction argument
is the address of an unsigned longword that contains the direction code
specifying the scrolling direction. The optional count
argument can be used to specify the number of lines or columns 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 that will 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.
In case Chinese language character set is used, and the left most
column of the viewport contains the right portion of a Chinese
character, the right portion of the character becomes invisible. Also
if the right most column of the viewport contains the left portion of a
Chinese character, the left portion of the character becomes
invisible.
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$_WINTRUFIT
|
Successful completion; however, the viewport associated with the
virtual display has been truncated to fit.
|
|
SMG$_WRONUMARG
|
Wrong number of arguments.
|
Example
|
C This DEC 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 the preceding example, a single virtual display is created and
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
|
