 |
OpenVMS/Hanzi RTL Chinese Screen Management (SMG$)
Manual
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.
Display-id 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
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
SMG$K_RIGHT and SMG$K_LEFT are valid when
character-set argument is either SMG$C_ASCII or
SMG$C_SPEC_GRAPHICS and when SMG$C_ASCII or SMG$C_SPEC_GRAPHICS is
specified in SMG$CHANGE_VIRTUAL_DISPLAY.
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 character set of the label text in text.
The character-set argument is the address of an
unsigned longword that contains the character set code. If this
argument is omitted, the default character set will be the character
set set up by SMG$CREATE_VIRTUAL_DISPLAY or by
SMG$CHANGE_VIRTUAL_DISPLAY.
| Value |
Character Set |
|
SMG$C_ASCII
|
ASCII
|
|
SMG$C_SPEC_GRAPHICS
|
DEC Special Graphics
|
|
SMG$C_HANZI
|
DEC Hanzi
|
1One of DEC supplemental character set and Latin-1 character
set.
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. 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.
Position-code and units 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 that vertical labels are available only for SMG$C_ASCII and
SMG$C_SPEC_GRAPHICS.
Original SMG routines support only ASCII(default) and DEC Special
Graphics, but Chinese SMG will allow users to specify the
Chinese character set to character-set argument
which enables Chinese language to be used.
Condition Values Returned
|
SS$_NORMAL
|
Normal successful completion.
|
|
SMG$_INVDIS_ID
|
Invalid
display-id.
|
|
SMG$_INVARG
|
Invalid argument. The combination of
position-code,
units, and
text arguments resulted in a position outside the
border area.
|
|
SMG$_WRONUMARG
|
Wrong number of arguments.
|
Example
|
C+
C This DEC 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 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 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.
Key-table-id is returned by the SMG$CREATE_KEY_TABLE
routine.
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
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.
Context 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
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_LOCK
|
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 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$COPY_DXDX.
SMG$LIST_PASTEBOARD_ORDER
The Return Pasting Information routine returns the Pasteboard
identifier of the pasteboard to which the specified virtual display is
pasted. Optionally, the pasteboard row 1 and column 1 (origins) of the
virtual display are also returned.
Format
SMG$LIST_PASTEBOARD_ORDER display-id ,context ,pasteboard-id
[,pasteboard-row] [,pasteboard-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 |
Display identifier of the virtual display that is pasted. The
display-id argument is the address of an unsigned
longword containing the identifier of this display.
context
| OpenVMS usage |
context |
| type |
longword (unsigned) |
| access |
modify |
| mechanism |
by reference |
Context to search. The context argument is the address
of an unsigned longword containing this context. On the initial call,
you should set context to zero.
SMG$LIST_PASTEBOARD_ORDER updates the value of
context. The updated value should then be passed on
the subsequent calls to obtain the next pasted display identifier.
pasteboard-id
| OpenVMS usage |
identifier |
| type |
longword (unsigned) |
| access |
write only |
| mechanism |
by reference |
Receives the identifier of the pasteboard on which the virtual display
is pasted. The pasteboard-id argument is the address
of an unsigned longword containing the identifier of this pasteboard.
pasteboard-row
| OpenVMS usage |
longword_signed |
| type |
longword (signed) |
| access |
write only |
| mechanism |
by reference |
Row of the pasteboard that contains row 1 of the specified virtual
display. The optional pasteboard-row argument is the
address of a signed longword containing the number of the pasteboard
row that contains the first row of the virtual display.
pasteboard-column
| OpenVMS usage |
longword_signed |
| type |
longword (signed) |
| access |
write only |
| mechanism |
by reference |
Column of the pasteboard that contains column 1 of the specified
virtual display. The optional pasteboard-column
argument is the address of a signed longword containing the number of
the pasteboard column that contains the first column of the virtual
display.
Description
SMG$LIST_PASTEBOARD_ORDER returns the pasteboard identifier of the
pasteboard to which the specified virtual display is pasted.
Optionally, the pasteboard row 1 and column 1 (origins) of the virtual
displays are also returned.
SMG$LIST_PASTEBOARD_ORDER returns the identifier of the first (or
bottommost) pasteboard to which the specified virtual display is
pasted. Call this routine in a loop, once for each succeeding
pasteboard, until SMG$_NOPASTED is returned.
This routine is useful if, for example, you pasted a display to many
pasteboards and you longer know the pasteboard identifier of a
pasteboard critical to your application.
Condition Values Returned
|
SS$_NORMAL
|
Normal successful completion.
|
|
SMG$_NOPASTED
|
No more displays are pasted.
|
|
SMG$_INVDIS_ID
|
Invalid
display-id.
|
|
SMG$_WRONUMARG
|
Wrong number of arguments.
|
|
