HP OpenVMS Systems Documentation

OpenVMS/Hanzi RTL Chinese Screen Management (SMG$) Manual

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

• Is bordered (the border may be labeled)
• Echoes carriage control characters (like form feed, vertical tab, and so on).
• Shows the user a diamond-shaped icon when text extends past the rightmost position in 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.

You can delete a virtual display by calling the SMG$DELETE_VIRTUAL_DISPLAY routine. See Section 2.1.5 for more information on the delete operation.

1.3 Viewports

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 viewports.

1.4 Virtual Keyboards

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.

This chapter discusses the output operations provided by the Screen Management Facility. These output operations are described in terms of composition operations (operations that, in effect, create an image on a terminal screen) and output operations through virtual displays.

2.1 Composition Operations

Composition operations are the routines you use to manipulate virtual displays on a pasteboard and thus to create an image on a terminal screen. These operations include pasting, unpasting, repasting, moving and popping virtual displays, checking virtual displays for occlusion, and listing the pasting order.

2.1.1 Paste Operation

Virtual displays are visible on a physical device only while they are pasted to a pasteboard. You paste a display to a pasteboard by calling SMG$PASTE_VIRTUAL_DISPLAY and specifying the pasteboard coordinates to be used as the origin of the virtual display. (The origin is the top left-hand corner.) The pasteboard itself has no boundaries, but of course the physical screen does. Thus you can paste a display to a pasteboard in such a way that some or all of the display does not appear on the terminal screen.

Pasting virtual displays to a pasteboard is a logical operation that maps the contents of a virtual display to a location on the screen by specifying the row and column of the pasteboard that coincide with row 1 and column 1 of the virtual display. For example, pasting a 6-row virtual display "A" to pasteboard rows 1 through 6 and pasting a second 6-row virtual display "B" to pasteboard rows 7 through 12 places virtual display "B" immediately below virtual display "A" on the screen. See Figure 2-1.

Figure 2-1 Paste Operation

A virtual display can be made to disappear from the physical screen with the SMG$UNPASTE_VIRTUAL_DISPLAY routine. To continue the example in Section 2.1.1, if virtual display "B" is unpasted, the results appear as in Figure 2-2.

Figure 2-2 Unpaste Operation

Unpasting a virtual display does not destroy the virtual display or its contents; it simply removes the display from the pasteboard.

Displays can overlap partially or completely, depending on their size, where they are pasted, and the order in which they are pasted. This overlap is called occlusion. Unpasting the top display causes the underlying display(s) to be visible.

2.1.3 Repaste Operation

You can move a virtual display to a new location on the pasteboard by calling SMG$REPASTE_VIRTUAL_DISPLAY, which prevents the screen from being left blank during the unpaste and repaste operations. Figure 2-3 below shows the effect of repasting the second display farther to the right. Notice that display 2 has been pulled out of its former pasting order and is now uppermost --- hiding part of display 3, which was uppermost before the repasting operation.

Figure 2-3 Repaste Operation

You can also move a virtual display around the pasteboard while preserving its pasting order by calling the SMG$MOVE_VIRTUAL_DISPLAY routine. Figure 2-4 shows the effect of moving the second display to the right. Note the difference between the unpaste and move operations: the pasting order does not change with a move. Thus, display 2 remains partially occluded by display 3.

Figure 2-4 Move Operation

The routine SMG$MOVE_TEXT allows you to move text from one virtual display to another virtual display. Given two points in opposite corners of the rectangle, SMG$MOVE_TEXT determines the desired width and height. The attributes of the first virtual display are moved, and after the rectangle of text is moved, it is erased from the first virtual display.

In case that this operation divides characters, the divided characters are treated as undefined characters.

2.1.5 Delete and Pop Operations

The unpaste, repaste, and move operations shown thus far do not destroy the virtual displays affected. You can remove and delete a virtual display by calling the SMG$DELETE_VIRTUAL_DISPLAY routine. You can also remove a number of virtual displays from a pasteboard and delete them in a single operation by calling SMG$POP_VIRTUAL_DISPLAY. This routine unpastes and deletes the specified virtual display and all other virtual displays that were pasted after the one specified.

The pop operation is useful in a modular environment. For example, you can call a subroutine and pass only the pasteboard-id upon which it is to produce output. The subroutine can then create additional virtual displays and paste them to the indicated pasteboard. When the subroutine returns control to its caller, the subroutine returns the display-id of the first virtual display it has pasted. The calling program can then undo the effects of the subroutine by calling SMG$POP_VIRTUAL_DISPLAY, passing the identifier of the virtual display returned by the subroutine. This technique minimizes the amount of information that needs to be passed between the calling program and its subroutine. Figure 2-5 shows the effects of popping display 2.

Figure 2-5 Pop Operation

It is sometimes useful to determine whether a display is occluded, as pasted on a given pasteboard. You can find this out by calling the SMG$CHECK_FOR_OCCLUSION routine. For example, in the configuration represented in Figure 2-6, displays 1 and 2 would be reported as being occluded, while displays 3 and 4 would be reported as not occluded. Note that this test cannot be used to determine which display is pasted uppermost on the pasteboard; it can determine only whether or not the display, as pasted, is occluded.

Figure 2-6 Occlusion Check

If you have multiple virtual displays pasted to a pasteboard, you can use SMG$LIST_PASTING_ORDER to determine the order in which virtual displays are pasted. This routine returns the identifier of the first, or bottommost, virtual display pasted. You call SMG$LIST_PASTING_ORDER in a loop until the identifiers of all the succeeding pasted virtual displays are returned.

The routine SMG$LIST_PASTEBOARD_ORDER gives you the inverse of the information returned by SMG$LIST_PASTING_ORDER. SMG$LIST_PASTEBOARD_ORDER returns the identifier of the first, or bottommost, pasteboard to which the specified virtual display is pasted.

2.2 Output Through Virtual Displays

This section describes the Chinese screen management routines used to perform output through virtual displays.

Writing to a virtual display is similar to writing directly to the terminal. However, writing to a virtual display is done entirely by calling screen management routines. Erasing the screen, setting the cursor position, and scrolling output text are typical operations provided by the Chinese Screen Management Facility. Text is arranged in the virtual display's buffer, so the display need not be pasted before it can receive output. When you write to the physical screen, you are limited by the physical boundaries of the screen. Similarly, Chinese screen management output operations are confined to the boundaries of the virtual display: you cannot write text beyond the last column of a virtual display.

Remember that changes to a virtual display are not seen on the screen unless the virtual display is pasted to the part of the pasteboard that is visible on the screen. If the virtual display is not pasted, or if it is pasted in a position that is not visible, such changes are reflected only in the internal database that represents the virtual display.

2.2.1 Cursor Position

When a virtual display is first created, the virtual cursor is positioned at row 1, column 1 of the virtual display. Various output operations to the virtual display move the virtual cursor, just as output operations do on a physical terminal.

The position of the virtual cursor in a virtual display should not be confused with the position of the physical cursor on the screen. There may be many virtual displays pasted to a pasteboard and hence visible at the same time on the physical screen. Although each virtual display has an associated virtual cursor position, only one of the virtual cursor positions for all these displays corresponds to the physical cursor---usually the cursor position of the virtual display that has been modified most recently.

You can determine the current position of the virtual cursor within a virtual display by calling the SMG$RETURN_CURSOR_POS routine. This routine returns the current virtual cursor row and column.

For programming convenience, this information can also be obtained through two separate routines, SMG$CURSOR_ROW and SMG$CURSOR_COLUMN, which operate as functions. These two routines make it easy to code constructions like this:

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.

The three following routines are available to set the virtual cursor position in a virtual display:

• The SMG$SET_CURSOR_ABS routine sets the virtual cursor to the specified position in the virtual display.
• The SMG$SET_CURSOR_REL routine sets the virtual cursor position to the specified offset from the current display cursor position.
• The SMG$HOME_CURSOR routine sets the virtual cursor to the virtual display's home position (row 1, column 1).

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.

Four routines are provided to erase parts of a virtual display:

• SMG$ERASE_CHARS erases a specified number of columns within a given line.
• SMG$ERASE_COLUMN erases the specified portion of the virtual display from the given position to the end of the column.
• SMG$ERASE_LINE erases characters in a line from the specified starting position to the end of the line.
• SMG$ERASE_DISPLAY erases all or part of a virtual display.

Two routines are provided to insert text into a virtual display.

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 routines.

2.2.5.1 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.

There are four character-oriented output routines:

• SMG$PUT_CHARS writes normal characters to a virtual display.
• SMG$PUT_CHARS_WIDE writes double-width characters to a virtual display.
• SMG$PUT_CHARS_HIGHWIDE writes double-width, double-height characters to a virtual display.
• SMG$PUT_CHARS_MULTI writes characters with multiple renditions to the virtual display.

Note that you cannot mix different types of characters on a single line in a virtual display.

2.2.5.2 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.

There are four line-oriented output routines:

• SMG$PUT_LINE writes lines of text to a virtual display.
• SMG$PUT_LINE_WIDE writes lines of double-width text to a virtual display.
• SMG$PUT_LINE_HIGHWIDE writes lines of double-width, double-height text to a virtual display.
• SMG$PUT_LINE_MULTI writes lines with multiple renditions to the virtual display.

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:

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:

1. The logical or bitwise OR operation is performed on the mask containing the default video attributes and the rendition-set argument.
2. The logical or bitwise EXCLUSIVE OR operation is performed on the result of the previous OR operation and the rendition-complement argument.

The results of this scheme are shown in the following table.