HP OpenVMS Systems Documentation
OpenVMS/Hanzi RTL Chinese Screen Management (SMG$) Manual
1.2 Virtual Displays
A virtual display is a rectangular part of the terminal screen to which a program writes data using routine calls. Virtual displays are the main focus of the Chinese Screen Management Facility. When you create images to be placed on the screen, you should think in terms of virtual displays rather than in terms of the physical screen. This logical separation of the virtual display from the physical screen allows a main program to reposition virtual displays, so that a subroutine that writes to the virtual display need not be involved with positioning the display on the physical screen.
When a virtual display is associated with a pasteboard, it is said to be pasted. When the display is removed from the pasteboard, it is said to be unpasted. A virtual display is not displayed unless it is pasted to a pasteboard. (See Section 2.1.1 for more information on pasting virtual displays.)
A program can create and maintain any number of virtual displays (limited only by the virtual address space available). A single virtual display can be pasted to more than one pasteboard at a time; thus, a program only needs to maintain the virtual display. Any change to a virtual display is automatically reflected in each pasteboard to which the display is pasted (and its associated terminal screen).
You create a virtual display by calling the SMG$CREATE_VIRTUAL_DISPLAY routine. A call to this routine must specify the number of rows and columns that make up the virtual display. The program can also request certain display and video attributes to be applied to the display.
SMG$CREATE_VIRTUAL_DISPLAY returns a unique virtual display identifier (display-id). This display-id is used to identify the virtual display in subsequent routine calls that modify the display.
A program or subroutine can determine which attributes and dimensions are associated with a virtual display by calling the SMG$GET_DISPLAY_ATTR routine. If you have multiple virtual displays pasted to a pasteboard, you can use SMG$LIST_PASTING_ORDER to determine the order in which the virtual displays are pasted.
The default video characteristics are the characteristics applied to the output when no other attributes have been specified. Renditions are video characteristics that you can turn on or off; they include bolding, blinking, reverse video, and underlined text. Display attributes are the characteristics that specify whether or not the display
The video and display attributes you specify when you create a virtual display can be changed. The SMG$CHANGE_RENDITION routine lets you change video attributes while the SMG$CHANGE_VIRTUAL_DISPLAY routine lets you change both video and display attributes. For example, you can redimension a virtual display with the latter routine. When you redimension a virtual display, the data in it is copied to the redimensioned display; that is, as much of the current contents (starting with row 1, column 1) as will fit in the newly dimensioned display are preserved.
Since a virtual display can be very large, it is not always possible to show the entire display on the screen at one time. You must repaste a large virtual display in order to view a different portion of it. A viewport associated with the virtual display makes this job easier.
Viewporting refers to the process of moving a rectangular viewing area
around on a virtual display in order to view different pieces of the
virtual display. The viewport is associated with the virtual display so
that any output operation that is performed on the virtual display is
reflected on the viewport. You can create, delete, paste, unpaste,
scroll, and move a viewport. See Section 2.2.10 for more information on
A virtual keyboard is a logical structure for input operations, just as a pasteboard is a logical structure for output operations. The advantage of using virtual keyboards is device independence. When using the screen management input routines, you need not worry about the type of terminal being used. For example, your program need not know which line terminators a particular terminal uses; the Chinese screen management routines map the different terminator character sequences into a uniform set of function codes. (See Chapter 3 for more information about terminator codes.)
A virtual keyboard is usually associated with a physical keyboard on a terminal. There is a many-to-one correspondence between virtual keyboards and an input device.
You establish a source for input (a virtual keyboard) by calling the SMG$CREATE_VIRTUAL_KEYBOARD routine. You delete virtual keyboards by calling the SMG$DELETE_VIRTUAL_KEYBOARD routine. Once you have created a virtual keyboard, you can obtain data from it with the SMG$READ_COMPOSED_LINE, SMG$READ_KEYSTROKE, or SMG$READ_STRING routine. SMG$READ_COMPOSED_LINE reads a line composed of ordinary keystrokes and predefined strings associated with keypad and control keys; it provides an easy way to code an interface for command-oriented utilities by providing single-key command capabilities. SMG$READ_KEYSTROKE is used to read one keystroke entered at the keyboard. SMG$READ_STRING reads a string composed of characters and a terminator; this routine is for general purpose and flexible, providing access to many features of the OpenVMS terminal driver.
IF SMG$CURSOR_ROW ( Display-id ) > Max-row THEN BEGIN . . . END
To obtain this information with SMG$RETURN_CURSOR_POS, you would write the following:
CALL SMG$RETURN_CURSOR_POS ( Display-id, Cursor-row, Cursor-column ) IF Cursor-row > Max-row THEN BEGIN . . . END
SMG$RETURN_CURSOR_POS requires you to define two local variables, cursor-row and cursor-column, which you might not need except to perform this test. However, this routine yields both the row and column in a single routine call.
Two routines are provided to delete parts of a virtual display.
SMG$DELETE_CHARS deletes one or more characters on a single line. Character positions removed by this routine are replaced with the characters to the right of the deleted characters on the same line. Character positions opened at the end of the line are filled with blanks.
In case of using Chinese characters, if delete operation starts from the right portion of the character, the left portion is treated as an undefined character; and if the delete operation ends at the left portion of the character, the right portion is treated as an undefined character.
SMG$DELETE_LINE deletes one or more entire lines. Lines removed by this
routine are filled by the lines immediately below the deleted lines.
New lines introduced into the bottom of the virtual display are blank.
2.2.3 Erasure Operations
During an erase operation, the erased portion of the virtual display is filled with blanks. No other parts of the virtual display are rearranged.
In case of Chinese characters, this operation may start from the right portion of a character or end at the left portion. If it starts from the right portion of the character, the left portion is treated as an undefined character. If it terminates on the left portion of the character, the right portion is treated as an undefined character.
In case of Chinese characters, this operation may divide a character. In such case, those divided portions of the character are treated as undefined characters.
SMG$INSERT_CHARS deposits the specified string of characters in the indicated starting position. Existing characters in these positions are shifted to the right to make room for each character as it is inserted. Characters shifted beyond the rightmost column are discarded.
SMG$INSERT_LINE inserts the specified line of text in the position
indicated and scrolls existing lines in the virtual display up or down
to make room for the inserted lines. Lines scrolled above the top line
or below the bottom line of the virtual display are discarded.
2.2.5 Writing Operations
The Chinese Screen Management Facility provides two types of
routines for writing text to a virtual display: character-oriented
output and line-oriented output. The following sections describe these
22.214.171.124 Character-Oriented Output
You typically use the character-oriented output routines when using a virtual display as a direct-access device. In this mode of operation, the program explicitly sets the cursor in the virtual display and deposits text there. Since the next output operation usually has no spatial relationship to the previous one, you need to control the cursor position and display scrolling explicitly.
This operation may overwrite a portion of a Chinese character. In this case, the portion left is treated as an undefined character.
Note that you cannot mix different types of characters on a single line
in a virtual display.
126.96.36.199 Line-Oriented Output
In contrast to the character-oriented output routines, the line-oriented routines treat a terminal as a sequential device. In this mode of operation, the program typically writes one line of information after another. Conceptually, this action corresponds to copying a stream of information (for example, a file) to a virtual display. Each routine call leaves the cursor at column 1 of the next row after the operation is complete.
This operation may start in the middle of a Chinese character. In such case, the left portion of the character is treated as an undefined character.
When you create a virtual display with the SMG$CREATE_VIRTUAL_DISPLAY routine, you specify a default rendition for all text that appears in the virtual display. You can change the rendition for an existing virtual display by calling either the SMG$CHANGE_VIRTUAL_DISPLAY or SMG$CHANGE_RENDITION routines.
The SMG$CHANGE_VIRTUAL_DISPLAY routine lets you change display attributes as well as video attributes for the entire display; the SMG$CHANGE_RENDITION routine can be used to change the video rendition of text already in the virtual display. For example, a program may maintain on the screen a list of values that change cyclically. When a number first changes, it can be displayed in reverse video to highlight it as a change on that cycle. On the next cycle, the same number must be displayed, but the reverse video should be removed, since the value of the number did not change. SMG$CHANGE_RENDITION provides an easy way to perform such changes.
Another use for the SMG$CHANGE_RENDITION routine is in implementing menus. Menu choices can be painted on the screen and the current choice highlighted by some video attribute, such as blinking characters or reverse video. As the user moves a cursor to change the selection, the rendition of a menu item can be altered so that the current selection is always highlighted. Such changes in rendition can be made independently of the text contained in the menu choices.
To specify the default rendition for a virtual display, you use bit masks to set bits in the display attributes argument. The following bits can be set:
|SMG$M_BLINK||Specifies blinking characters.|
|SMG$M_BOLD||Specifies characters in higher-than-normal intensity.|
|SMG$M_REVERSE||Specifies characters in reverse video; that is, the opposite of the current rendition of the virtual display.|
|SMG$M_UNDERLINE||Specifies underlined characters.|
|SMG$M_INVISIBLE||Specifies invisible characters; that is, the characters exist in the virtual display but do not appear on the pasteboard.|
|Specifies a user-defined rendition.|
In order to use one of the user-defined renditions SMG$M_USER1 through SMG$M_USER8, you must provide an appropriate definition in the file TERMTABLE.TXT, using STRING_2 capabilities. The TERMTABLE definitions and STRING_2 capabilities are discussed in Chapter 5.
Any or all of the characteristics listed previously can be specified in the rendition of a virtual display. To specify more than one video attribute, you use the logical OR of these characteristics. For example, to specify underlined characters in reverse video as the default for a virtual display, you assign the logical OR of the appropriate bit masks to the display-attributes argument:
Display_attributes = ( SMG$M_REVERSE OR SMG$M_UNDERLINE )
You then pass this display-attributes argument in the call to the SMG$CREATE_VIRTUAL_DISPLAY routine.
Chinese Screen management output routines let you override the default rendition so that you need not change the default each time you want to write text in some other rendition. Two arguments provide the means to override the default rendition: rendition-set and rendition-complement. The scheme for setting video attributes in these arguments is the same as that for setting the video attributes when you are creating a virtual display.
The default video attributes, the rendition-set argument, and the rendition-complement argument together specify the output rendition according to the following scheme:
The results of this scheme are shown in the following table.
|0||0||Attribute set to default|
|0||1||Attribute set to complement of default setting|