|
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
The initial output generated by this Fortran program is shown in
Figure SMG-29.
Figure SMG-29 Output Generated Before the Call to
SMG$INSERT_LINE
The output generated after the call to SMG$INSERT_LINE is shown in
Figure SMG-30.
Figure SMG-30 Output Generated After the Call to
SMG$INSERT_LINE
SMG$INVALIDATE_DISPLAY
The Mark a Display as Invalid routine marks a display as invalid and
causes the entire display to be redrawn.
Format
SMG$INVALIDATE_DISPLAY 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 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$INVALIDATE_DISPLAY marks a display as invalid and redraws the
entire display. You would normally use this routine after you determine
that output has been written to the display without benefit of the
Screen Management Facility.
This routine redraws the virtual display by invalidating the pasteboard
contents of the virtual display's "footprint." If the display
is occluded, only the occluded portion of the occluding virtual display
is redrawn; the entire display is not redrawn.
Condition Values Returned
|
SS$_NORMAL
|
Normal successful completion.
|
|
SMG$_INVDIS_ID
|
Invalid
display-id.
|
SMG$KEYCODE_TO_NAME
The Translate a Key Code into a Key Name routine translates the key
code of a key on the keyboard into its associated key name.
Format
SMG$KEYCODE_TO_NAME key-code ,key-name
RETURNS
| OpenVMS usage: |
cond_value |
| type: |
longword (unsigned) |
| access: |
write only |
| mechanism: |
by value |
Arguments
key-code
| OpenVMS usage: |
word_unsigned |
| type: |
word (unsigned) |
| access: |
read only |
| mechanism: |
by reference |
Specifies the key code to translate into a key name. The
key-code argument is the address of an unsigned word
that contains the key code.
The key code is returned by SMG$READ_COMPOSED_LINE, SMG$READ_KEYSTROKE,
SMG$READ_STRING, and SMG$READ_VERIFY in the
word-terminator-code argument.
key-name
| OpenVMS usage: |
char_string |
| type: |
character string |
| access: |
write only |
| mechanism: |
by descriptor |
String containing the name of the key into which
key-code is to be translated. The
key-name argument is the address of a descriptor
pointing to the character string containing the key name. The
key-name argument is simply the name of the key (for
example, COMMA, PERIOD, KP4, and so forth).
Description
SMG$KEYCODE_TO_NAME translates the key code of a key on the keyboard
into its associated key name. This key code is the same code returned
by the SMG$READ_COMPOSED_LINE, SMG$READ_KEYSTROKE, SMG$READ_STRING, and
SMG$READ_VERIFY routines in the word-terminator-code
argument. The form of key-code is SMG$K_TRM_keyname
(for example, SMG$K_TRM_DELETE).
For more information on terminator values, see Table 3-1.
Condition Values Returned
|
SS$_NORMAL
|
Normal successful completion.
|
|
SMG$_INVKEYNAM
|
Invalid
key-name.
|
SMG$LABEL_BORDER
The Label a Virtual Display Border routine supplies a label for a
virtual display's border.
Format
SMG$LABEL_BORDER display-id [,text] [,position-code] [,units]
[,rendition-set] [,rendition-complement] [,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 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.
text
| OpenVMS usage: |
char_string |
| type: |
character string |
| access: |
read only |
| mechanism: |
by descriptor |
The new label for this display's border. The text
argument is the address of a descriptor pointing to the label text. If
this string is supplied, it replaces the current label text for this
border. If omitted, the display is not labeled.
position-code
| OpenVMS usage: |
longword_unsigned |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by reference |
Specifies which of the display's borders contains the label. The
position-code argument is the address of an unsigned
longword that contains the position code.
Valid positions are as follows:
- SMG$K_TOP
- SMG$K_BOTTOM
- SMG$K_RIGHT
- SMG$K_LEFT
If this argument is omitted, the label is displayed on the top border.
units
| OpenVMS usage: |
longword_signed |
| type: |
longword (signed) |
| access: |
read only |
| mechanism: |
by reference |
Specifies the character position at which the label begins within the
border. The units argument is the address of a signed
longword that contains the character position. If omitted, the label is
centered in the specified border.
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
|
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 code. Valid values
are SMG$C_ASCII (the default) and SMG$C_SPEC_GRAPHICS.
Description
SMG$LABEL_BORDER lets you specify text to label a virtual display. If
the specified virtual display does not already have the border display
attribute (SMG$M_BORDER), then this attribute is forced. A display
border, which includes all four sides of the display, can have only one
label. If the label string is supplied, it replaces the current label
text for this border. If you supply an empty (null) label string, the
border is not labeled. If the label text (as positioned within the
border) does not fit within the border, this routine returns
SMG$_INVARG.
The position-code and units arguments
together specify the starting position of the label text within a
border. If position-code is omitted, the default is
the top border. If units is omitted, this routine
chooses a starting position so as to center the text either
horizontally or vertically, depending on the implicit or explicit
position argument. If both position-code and
units are omitted, the text is centered in the top
border.
Note
The label may shift when it is applied to a viewport. This occurs when
the label needs to be moved to appear in a sensible location. For
example, the default location for a label in a virtual display is at
the top of the display and centered. When a viewport is created, that
label may shift to remain in the center of the display.
|
Condition Values Returned
|
SS$_NORMAL
|
Normal successful completion.
|
|
SMG$_INVARG
|
Invalid argument. The combination of
position-code,
units, and
text arguments resulted in a position outside the
border area.
|
|
SMG$_INVDIS_ID
|
Invalid
display-id.
|
|
SMG$_WRONUMARG
|
Wrong number of arguments.
|
Example
|
C+
C This Fortran example program demonstrates the use of SMG$LABEL_BORDER.
C-
C+
C Include the SMG definitions. In particular, we want SMG$M_BORDER,
C SMG$K_TOP, SMG$K_BOTTOM, and SMG$K_RIGHT.
C-
IMPLICIT INTEGER (A-Z)
INCLUDE '($SMGDEF)'
C+
C Call SMG$CREATE_VIRTUAL_DISPLAY to create virtual display number 1.
C Give it a border.
C-
ROWS = 4
COLUMNS = 30
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_VIRTUAL_DISPLAY to create virtual display number 2.
C Give it a border.
C-
ROWS = 3
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 virtual display number 3. Do NOT give it a border.
C-
ROWS = 4
COLUMNS = 35
STATUS = SMG$CREATE_VIRTUAL_DISPLAY
1 (ROWS, COLUMNS, DISPLAY3)
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 Call SMG$PUT_CHARS to put data into the virtual displays.
C-
STATUS = SMG$PUT_CHARS ( DISPLAY1,
1 ' A bordered virtual display.', 2, 1 )
IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))
STATUS = SMG$PUT_CHARS ( DISPLAY2,
1 ' A bordered virtual display.', 1, 1 )
IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))
STATUS = SMG$PUT_CHARS ( DISPLAY3,
1 ' Started as an unbordered display.', 2, 1 )
IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))
C+
C Call SMG$LABEL_BORDER to label the virtual display borders.
C-
STATUS = SMG$LABEL_BORDER ( DISPLAY1, 'Side', SMG$K_RIGHT )
IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))
STATUS = SMG$LABEL_BORDER ( DISPLAY2, 'LABEL Bottom',
1 SMG$K_BOTTOM, 1 )
IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))
STATUS = SMG$LABEL_BORDER ( DISPLAY3, 'Forced bordering ',
1 SMG$K_TOP )
IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))
C+
C Call SMG$PASTE_VIRTUAL_DISPLAY to paste the virtual displays.
C-
STATUS = SMG$PASTE_VIRTUAL_DISPLAY ( DISPLAY1, PASTE1, 2, 10 )
IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))
STATUS = SMG$PASTE_VIRTUAL_DISPLAY ( DISPLAY2, PASTE1, 2, 45 )
IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))
STATUS = SMG$PASTE_VIRTUAL_DISPLAY ( DISPLAY3, PASTE1, 10, 5 )
IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))
END
|
The output generated by this program is shown in Figure SMG-31.
Figure SMG-31 Output Generated by Program Calling
SMG$LABEL_BORDER
SMG$LIST_KEY_DEFS
The List Key Definitions routine returns, one at a time, the
definitions (equivalence strings) associated with specified keys in a
specified key definition table.
Format
SMG$LIST_KEY_DEFS key-table-id ,context [,key-name] [,if-state]
[,attributes] [,equivalence-string] [,state-string]
RETURNS
| OpenVMS usage: |
cond_value |
| type: |
longword (unsigned) |
| access: |
write only |
| mechanism: |
by value |
Arguments
key-table-id
| OpenVMS usage: |
identifier |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by reference |
Specifies the key definition table from which you are extracting a key
definition. The key-table-id argument is the address
of an unsigned longword that contains the key table identifier.
The key definition table identifier is returned by SMG$CREATE_KEY_TABLE.
context
| OpenVMS usage: |
context |
| type: |
longword (unsigned) |
| access: |
modify |
| mechanism: |
by reference |
Provides a means to extract a series of key definitions from a key
definition table. The context argument is the address
of an unsigned longword that contains the context variable. For the
first call to this routine, you should set the context
argument to zero.
The context argument is incremented by the
SMG$LIST_KEY_DEFS routine so that the next call returns the next key
definition.
key-name
| OpenVMS usage: |
char_string |
| type: |
character string |
| access: |
modify |
| mechanism: |
by descriptor |
Identifies the key whose value you are listing. The
key-name argument is the address of a descriptor
pointing to the key name.
if-state
| OpenVMS usage: |
char_string |
| type: |
character string |
| access: |
write only |
| mechanism: |
by descriptor |
Receives the state name which qualifies the next definition in the key
definition table. The if-state argument is the address
of a descriptor pointing to the string into which the state name is
written.
attributes
| OpenVMS usage: |
mask_longword |
| type: |
longword (unsigned) |
| access: |
write only |
| mechanism: |
by reference |
Attributes of this key definition. The attributes
argument is the address of an unsigned longword into which the key
attributes are written.
Possible attributes are as follows:
|
SMG$M_KEY_NOECHO
|
If set, this bit specifies that
equiv_string is not to be echoed when this key is
pressed; if clear,
equiv_string is echoed. If SMG$M_KEY_TERMINATE is not
set, SMG$M_KEY_NOECHO is ignored.
|
|
SMG$M_KEY_TERMINATE
|
If set, this bit specifies that when this key is pressed (as qualified
by
if-state), the input line is complete and more
characters should not be accepted. If clear, more characters may be
accepted.
|
|
SMG$M_KEY_LOCKSTATE
|
If set, and if
state-string is specified, the state name specified by
state-string remains at the current state until
explicitly changed by a subsequent keystroke whose definition includes a
state-string. If clear, the state name specified by
state-string remains in effect only for the next
defined keystroke.
|
|
SMG$M_KEY_PROTECTED
|
If set, this bit specifies that this key definition cannot be modified
or deleted. If clear, the key definition can be modified or deleted.
|
equivalence-string
| OpenVMS usage: |
char_string |
| type: |
character string |
| access: |
write only |
| mechanism: |
by descriptor |
The character string into which the equivalence string is written for
the next key definition. The equivalence-string
argument is the address of a descriptor pointing to the string into
which equivalence-string is written.
state-string
| OpenVMS usage: |
char_string |
| type: |
character string |
| access: |
write only |
| mechanism: |
by descriptor |
A string into which is written the new state name, if any, set by the
next key definition. The state-string argument is the
address of a descriptor pointing to the string into which the state
name is written. If this key definition sets a state, the attributes
flag SMG$M_KEY_SETSTATE is also set.
Description
SMG$LIST_KEY_DEFS, when called repeatedly, lets you examine all the
definitions in a key definition table. These definitions may be used
with the routine SMG$READ_COMPOSED_LINE.
Condition Values Returned
|
SS$_NORMAL
|
Normal successful completion.
|
|
SMG$_INVKEYNAM
|
Invalid
key-name.
|
|
SMG$_INVKTB_ID
|
Invalid
key-table-id.
|
|
SMG$_NOMOREKEYS
|
No more keys in this table.
|
Any condition value returned by LIB$SCOPY_DXDX.