Document revision date: 19 July 1999

A pasteboard is a logical structure for performing output operations to a terminal screen. You can think of a pasteboard as a two-dimensional area on which you place and manipulate screen displays. A pasteboard is always associated with a physical device or an OpenVMS RMS file, but a pasteboard may be larger or smaller than the physical screen. There can be only one pasteboard for each output device.

Create a pasteboard by calling the SMG$CREATE_PASTEBOARD routine and specifying as an argument the physical device to be associated with the pasteboard. SMG$CREATE_PASTEBOARD returns a unique pasteboard identifier (pasteboard-id), which is used in subsequent routine calls where a pasteboard identifier is needed. For example, use the pasteboard-id to specify the physical terminal screen on which to paste a virtual display. SMG$CREATE_PASTEBOARD also returns as output arguments the numbers of rows and columns available on the associated device. You can use this information to create a virtual display the size of the physical screen. (Virtual displays are discussed in the next section.)

It is useful to think of a pasteboard as a logical coordinate system in which the relative orientation of one or more virtual displays is specified. (The pasteboard itself has no physical boundaries, but the physical screen does.) Figure 1-1 depicts the pasteboard coordinate system.

Figure 1-1 Pasteboard Coordinate System

The origin (cellular position 1,1) corresponds to the upper left-hand corner of the physical screen. The numbering of rows and columns starts from this origin. For example, on a VT200 series terminal, with 24 rows and 80 columns, the first 24 rows and first 80 columns of the pasteboard coordinate system map to the physical screen. Note that you can place a virtual display anywhere in this coordinate system, not only in the quadrant that corresponds to the physical screen. Thus a virtual display, when pasted (that is, positioned on the pasteboard), may be invisible or only partly visible on the physical screen.

Pasteboards are deleted, or disassociated, from a particular device by the SMG$DELETE_PASTEBOARD routine. When a pasteboard is deleted, all virtual displays pasted to it are unpasted.

Once a pasteboard has been created, you can learn about its attributes (particularly its dimensions) by calling SMG$GET_PASTEBOARD_ATTRIBUTES. You can change the characteristics of a pasteboard by calling SMG$CHANGE_PBD_CHARACTERISTICS if the associated physical device allows the change. For example, if the device is a VT100, you can change the width of the pasteboard from 80 columns to 132 columns.

When the pasteboard is created, the Screen Management Facility clears the screen by default; however, you can request that the screen be left as it is. In addition, you can call SMG$ERASE_PASTEBOARD to erase the screen explicitly. You can also call SMG$PRINT_PASTEBOARD to print the contents of the pasteboard on a line printer.

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 Screen Management Facility. When you create images to be placed on the screen, 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 need maintain only 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).

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 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 screen management routines map the different terminator character sequences into a uniform set of function codes. (See Section 3.6 for more information about terminator codes.)

A virtual keyboard is usually associated with a physical keyboard on a terminal, but it may also be any file accessible through OpenVMS RMS. There is a many-to-one correspondence between virtual keyboards and an input device or file.

Establish a source for input (a virtual keyboard) by calling the SMG$CREATE_VIRTUAL_KEYBOARD routine. 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, SMG$READ_STRING, or SMG$READ_VERIFY 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 general purpose and flexible, providing access to many features of the OpenVMS terminal driver. SMG$READ_VERIFY is used for reading formatted input. All types of read operations can be aborted by calling the SMG$CANCEL_INPUT routine.

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

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. 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 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 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, 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 following routines set the virtual cursor position in a virtual display:

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

The following routines 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.
• 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.

During an erase operation, the erased portion of the virtual display is filled with blanks. No other parts of the virtual display are rearranged.

The following routines erase parts of a virtual display:

• SMG$ERASE_CHARS erases a specified number of characters 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.

The following routines insert text into a virtual display:

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

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

The following are 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.

	privacy and legal statement
5935PRO_001.HTML