|
Document revision date: 30 March 2001
|
![[Compaq]](../../images/compaq.gif) |
![[Go to the documentation home page]](../../images/buttons/bn_site_home.gif)
![[How to order documentation]](../../images/buttons/bn_order_docs.gif)
![[Help on this site]](../../images/buttons/bn_site_help.gif)
![[How to contact us]](../../images/buttons/bn_comments.gif)
|
![[OpenVMS documentation]](../../images/ovmsdoc_sec_head.gif)
|
OpenVMS RTL Screen Management (SMG$) Manual
SMG$DRAW_RECTANGLE
The Draw a Rectangle routine draws a rectangle.
Format
SMG$DRAW_RECTANGLE display-id ,start-row ,start-column ,end-row
,end-column [,rendition-set] [,rendition-complement]
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 on which the rectangle is to be drawn.
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 number of the top left corner of the rectangle. The
start-row argument is the address of a signed longword
that contains the row number of the top left corner of the rectangle.
start-column
| OpenVMS usage: |
longword_signed |
| type: |
longword (signed) |
| access: |
read only |
| mechanism: |
by reference |
Specifies the column number of the top left corner of the rectangle.
The start-column argument is the address of a signed
longword that contains the column number of the top left corner of the
rectangle.
end-row
| OpenVMS usage: |
longword_signed |
| type: |
longword (signed) |
| access: |
read only |
| mechanism: |
by reference |
Specifies the row number of the bottom right corner of the rectangle.
The end-row argument is the address of a signed
longword that contains the row number of the bottom right corner of the
rectangle.
end-column
| OpenVMS usage: |
longword_signed |
| type: |
longword (signed) |
| access: |
read only |
| mechanism: |
by reference |
Specifies the column number of the bottom right corner of the
rectangle. The end-column argument is the address of a
signed longword that contains the column number of the bottom right
corner of the rectangle.
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_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.
|
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 of the 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$DRAW_RECTANGLE draws a rectangle in a virtual display, given the
position of the upper left corner and the lower right corner. Note that
this routine does not change the virtual cursor position. The
characters used to draw the lines making up the rectangle depend on the
type of terminal. If possible, SMG$ uses the terminal's line-drawing
character set. If that is not available, SMG$ uses the plus sign (+),
minus sign (--), and vertical bar (|) to draw the lines.
Condition Values Returned
|
SS$_NORMAL
|
Normal successful completion.
|
|
SMG$_INVCOL
|
Invalid column number. The specified column is outside the virtual
display.
|
|
SMG$_INVDIS_ID
|
Invalid
display-id.
|
|
SMG$_INVROW
|
Invalid row number. The specified row is outside the virtual display.
|
|
SMG$_WRONUMARG
|
Wrong number of arguments.
|
Example
|
C+
C This Fortran example program demonstrates the use of
C SMG$DRAW_RECTANGLE.
C
C This routine creates a virtual display and uses SMG$DRAW_RECTANGLE
C to draw a rectangle inside the bordered virtual display.
C-
C+
C Include the SMG definitions. In particular, we want SMG$M_BORDER.
C-
INCLUDE '($SMGDEF)'
INTEGER SMG$CREATE_VIRTUAL_DISPLAY, SMG$CREATE_PASTEBOARD
INTEGER SMG$PASTE_VIRTUAL_DISPLAY, SMG$DRAW_RECTANGLE
INTEGER DISPLAY1, PASTE1, ROWS, COLUMNS, STATUS
C+
C Create a virtual display with a border by calling
C SMG$CREATE_VIRTUAL_DISPLAY.
C-
ROWS = 7
COLUMNS = 50
STATUS = SMG$CREATE_VIRTUAL_DISPLAY
1 (ROWS, COLUMNS, DISPLAY1, SMG$M_BORDER)
IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))
C+
C Use SMG$CREATE_PASTEBOARD to create the pasteboard.
C-
STATUS = SMG$CREATE_PASTEBOARD (PASTE1)
IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))
C+
C Using SMG$DRAW_RECTANGLE, draw a rectangle inside the bordered region.
C-
STATUS = SMG$DRAW_RECTANGLE (DISPLAY1, 2, 10, 6, 20)
IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))
C+
C Paste the virtual display by calling SMG$PASTE_VIRTUAL_DISPLAY.
C-
STATUS = SMG$PASTE_VIRTUAL_DISPLAY ( DISPLAY1, PASTE1, 4, 15)
IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))
END
|
The output generated by this Fortran example is shown in Figure SMG-18.
Figure SMG-18 Output Generated by Fortran Program Calling
SMG$DRAW_RECTANGLE
SMG$ENABLE_UNSOLICITED_INPUT
The Enable Unsolicited Input routine detects unsolicited input and
calls an AST routine in response.
Format
SMG$ENABLE_UNSOLICITED_INPUT 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 unsolicited input is being enabled.
The pasteboard-id argument is the address of an
unsigned longword that contains the pasteboard identifier.
The pasteboard identifier is returned by SMG$CREATE_VIRTUAL_PASTEBOARD.
AST-routine
| OpenVMS usage: |
ast_procedure |
| type: |
procedure value |
| access: |
read only |
| mechanism: |
by value |
AST routine to be called upon receipt of unsolicited input at the
terminal. The AST-routine argument contains the
routine's procedure value. SMG$ENABLE_UNSOLICITED_INPUT detects the
presence of unsolicited input and calls the AST routine with six
arguments: the pasteboard-id, the
AST-argument, R0, R1, PC, and PSL (on VAX systems) or
PS (on Alpha systems). The AST routine arguments are shown in
Figure SMG-19.
Figure SMG-19 AST Routine Arguments
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 argument contains the value to be passed
to the AST routine.
Description
SMG$ENABLE_UNSOLICITED_INPUT detects the presence of unsolicited input
and calls an AST routine in response.
Note that this routine does not read any input characters; it merely
calls an AST routine to "notify" the application that it
should issue a read operation with SMG$READ_COMPOSED_LINE,
SMG$READ_KEYSTROKE, SMG$READ_STRING or SMG$READ_VERIFY. It is up to you
to read the unsolicited input.
SMG$ENABLE_UNSOLICITED_INPUT establishes a mailbox that receives
messages when terminal-related events occur that require the attention
of the user image. This mailbox carries status messages, not terminal
data, from the driver to the user program. This status message is sent
to the mailbox when there is unsolicited data in the type-ahead buffer.
In this case, the user process enters into a dialogue with the terminal
after an unsolicited data message arrives. Once this dialogue is
complete, the Screen Management Facility reenables the unsolicited data
message function on the last I/O exchange. Only one message is sent
between read operations. (The SYSGEN parameters DEFMBXBUFQUO and
DEFMBXMXMSG are used when creating the mailbox.)
Condition Values Returned
|
SS$_NORMAL
|
Normal successful completion.
|
|
SMG$_INVPAS_ID
|
Invalid
pasteboard-id.
|
|
SMG$_WRONUMARG
|
Wrong number of arguments.
|
Any condition values returned by $QIOW.
Example
For an example using SMG$ENABLE_UNSOLICITED_INPUT, see the example for
the SMG$DISABLE_BROADCAST_TRAPPING routine.
SMG$END_DISPLAY_UPDATE
The End Display Update routine ends update batching for a virtual
display.
Format
SMG$END_DISPLAY_UPDATE display-id
RETURNS
| OpenVMS usage: |
cond_value |
| type: |
longword (unsigned) |
| access: |
write only |
| mechanism: |
by value |
Argument
display-id
| OpenVMS usage: |
identifier |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by reference |
Specifies the virtual display to be affected. 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.
Description
SMG$END_DISPLAY_UPDATE and SMG$BEGIN_DISPLAY_UPDATE work together to
control the batching of output operations on a given virtual display.
Each call to SMG$BEGIN_DISPLAY_UPDATE increments a batch count. Each
call to SMG$END_DISPLAY_UPDATE decrements this count. When the batch
count reaches 0, the virtual display is updated with all operations
done under batching, and written to the pasteboard if the virtual
display is pasted.
Calling SMG$END_DISPLAY_UPDATE when the batch count is zero is a valid
operation; therefore a success status is returned.
Condition Values Returned
|
SS$_NORMAL
|
Normal successful completion.
|
|
SMG$_BATSTIPRO
|
Successful completion. Note that batching is still in progress.
|
|
SMG$_BATWASOFF
|
Successful completion. Note that batching was already off.
|
|
SMG$_INVDIS_ID
|
Invalid
display-id.
|
|
SMG$_WRONUMARG
|
Wrong number of arguments.
|
SMG$END_PASTEBOARD_UPDATE
The End Pasteboard Update routine ends update batching for a pasteboard.
Format
SMG$END_PASTEBOARD_UPDATE pasteboard-id
RETURNS
| OpenVMS usage: |
cond_value |
| type: |
longword (unsigned) |
| access: |
write only |
| mechanism: |
by value |
Argument
pasteboard-id
| OpenVMS usage: |
identifier |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by reference |
Specifies the pasteboard on which the batch count is to be decremented.
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. If the
batch count reaches 0, all buffered output for the specified pasteboard
is written out.
Description
SMG$END_PASTEBOARD_UPDATE and SMG$BEGIN_PASTEBOARD_UPDATE work together
to control the batching of output operations on a given pasteboard.
Each call to SMG$BEGIN_PASTEBOARD_UPDATE increments a batch count. Each
call to SMG$END_PASTEBOARD_UPDATE decrements this count. When the batch
count reaches 0, the pasteboard is written to the screen.
Calling SMG$END_PASTEBOARD_UPDATE when the batch count is 0 is a valid
operation; a success status is returned.
Condition Values Returned
|
SS$_NORMAL
|
Normal successful completion.
|
|
SMG$_BATSTIPRO
|
Successful completion. Note that batching is still in progress.
|
|
SMG$_BATWASOFF
|
Successful completion. Note that batching was already off.
|
|
SMG$_INVDIS_ID
|
Invalid
display-id.
|
|
SMG$_WRONUMARG
|
Wrong number of arguments.
|
SMG$ERASE_CHARS
The Erase Characters routine erases characters in a virtual display by
replacing them with blanks.
Format
SMG$ERASE_CHARS display-id ,number-of-characters ,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 from which characters will be erased. 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-characters
| OpenVMS usage: |
longword_signed |
| type: |
longword (signed) |
| access: |
read only |
| mechanism: |
by reference |
Specifies the number of characters to be replaced with blanks. The
number-of-characters argument is the address of a
signed longword that contains the number of characters to be replaced
with blanks.
start-row
| OpenVMS usage: |
longword_signed |
| type: |
longword (signed) |
| access: |
read only |
| mechanism: |
by reference |
Specifies the row on which the erase operation begins. The
start-row argument is the address of a signed longword
that contains the number of the row at which the erasure is to begin.
start-column
| OpenVMS usage: |
longword_signed |
| type: |
longword (signed) |
| access: |
read only |
| mechanism: |
by reference |
Specifies the column on which the erase operation begins. The
start-column argument is the address of a signed
longword that contains the number of the column at which the erasure is
to begin.
Description
SMG$ERASE_CHARS erases characters in a virtual display by replacing
them with blanks. The remaining text in the display is not moved. An
erase operation is limited to the specified line. If
number-of-characters is greater than the number of
characters remaining in the line, all characters from the specified
starting position to the end of the line are erased. This routine
leaves the virtual cursor at the position of the first character erased.
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.
|
Example
|
C+
C This Fortran example demonstrates the use of SMG$ERASE_CHARS.
C
C Include the SMG definitions. In particular, we want SMG$M_BORDER.
C-
IMPLICIT INTEGER (A-Z)
INCLUDE '($SMGDEF)'
C+
C Create a virtual display with a border by calling
C SMG$CREATE_VIRTUAL_DISPLAY.
C-
ROWS = 7
COLUMNS = 50
STATUS = SMG$CREATE_VIRTUAL_DISPLAY
1 (ROWS, COLUMNS, DISPLAY1, SMG$M_BORDER)
IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))
C+
C Call SMG$CREATE_PASTEBOARD to create the pasteboard.
C-
STATUS = SMG$CREATE_PASTEBOARD (PASTE1)
IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))
C+
C Using SMG$PUT_CHARS, put data in the virtual display.
C-
STATUS = SMG$PUT_CHARS ( DISPLAY1,
1 ' This virtual display has 7 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.', 4, 1)
IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))
STATUS = SMG$PUT_CHARS ( DISPLAY1,
1 ' SMG$PUT_CHARS puts data in this virtual display.', 6, 1)
IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))
C+
C Call 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))
C+
C Erase 4 characters on row 4 starting from character (column) 14 by
C calling SMG$ERASE_CHARS. This will remove the characters "rder"
C from the word "bordered".
C-
STATUS = SMG$ERASE_CHARS ( DISPLAY1, 4, 4, 14)
IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))
END
|
The initial output generated by this Fortran example program is shown
in Figure SMG-20.
Figure SMG-20 Output Before the Call to SMG$ERASE_CHARS
The output generated after the call to SMG$ERASE_CHARS is shown in
Figure SMG-21.
Figure SMG-21 Output After the Call to SMG$ERASE_CHARS
