HP OpenVMS Systems Documentation

Content starts here

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

Previous Contents

Note that the effect of this scheme depends on the default attribute setting, not the current rendition of the virtual display. Thus, if you have used screen management output routines that explicitly specify a rendition, the current rendition may not match the default rendition for that virtual display.

2.2.7 Drawing and Removing Drawn Lines and Characters

Three routines provide a simple way to construct horizontal and vertical lines. SMG$DRAW_LINE constructs either horizontal or vertical lines, given the end points of those lines. SMG$DRAW_RECTANGLE draws a rectangle given the position of the upper left-hand corner and the lower right-hand corner. SMG$DRAW_CHAR draws one line-drawing character.

If you want to erase a line drawn with SMG$DRAW_LINE or SMG$DRAW_RECTANGLE, use SMG$REMOVE_LINE. This routine removes the line but preserves the line-drawing characters at any line intersections.

Like all Chinese screen management routines, these are device independent. If the resulting line is to be drawn on a VT100 terminal, the VT100 line-drawing character set is used. If the same line is drawn on a VT52 (which does not have this hardware capability) terminal, the lines will automatically be approximated by the use of the plus sign (+), the vertical bar (|), and the dash (--). Your program does not have to supply different character codes for different types of terminals.

In addition, these routines automatically provide an appropriate character at the intersection of two lines. For example, if a program writes a horizontal line directly to the screen and then writes a vertical line that intersects the horizontal line, you would normally see what appears in Figure 2-7:

Figure 2-7 Lines Drawn Without SMG$DRAW_LINE

If these same lines are drawn using SMG$DRAW_LINE, the screen shows what appears in Figure 2-8:

Figure 2-8 Lines Drawn with SMG$DRAW_LINE

2.2.8 Displaying External Text

Two routines provide a way to output "external" text to the virtual display or terminal.

The routine SMG$PUT_HELP_TEXT outputs the help text for the specified topic in the virtual display provided.

The routine SMG$PUT_STATUS_LINE outputs a line of text to the terminal's hardware status line. Some terminals have a hardware status line at the bottom (25th line) of the screen. If this line has been set as "host writable", you can use this routine to output a line of text in reverse video to the status line.

2.2.9 Reading from a Virtual Display

The SMG$READ_FROM_DISPLAY routine is provided to make it easy to obtain text from a virtual display. This routine might be used in applications that present menu items on the screen by way of a virtual display. The application might allow the user to move the cursor among the menu items and then select one (by pressing the Return key, for example). At this point, the program can read characters from the display at the current cursor position and determine which menu item was selected. Note that this routine also provides a way to read characters written with the SMG$M_INVISIBLE attribute.

2.2.10 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. The user 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 performed on the virtual display is reflected on the viewport. Creating a Viewport

The SMG$CREATE_VIEWPORT routine creates a viewport associated with a particular virtual display. The virtual display must be created before the viewport can be created, and you can only create one viewport for each virtual display. In order to make the viewport visible, you have to paste the virtual display by calling the SMG$PASTE_VIRTUAL_DISPLAY routine; only the portion of the virtual display that falls inside the viewport is visible. Deleting a Viewport

You delete a viewport with the SMG$DELETE_VIEWPORT routine. When you invoke this routine, the viewport is automatically unpasted from any pasteboards to which it is pasted. It is important to note, however, that the virtual display associated with the viewport has not been deleted. You can make the virtual display visible by calling SMG$PASTE_VIRTUAL_DISPLAY. Pasting and Unpasting a Viewport

The routine SMG$PASTE_VIRTUAL_DISPLAY pastes either a viewport or a virtual display to a pasteboard. Once you have associated a viewport with a virtual display, any call to SMG$PASTE_VIRTUAL_DISPLAY uses the viewport instead of the virtual display. That is, once a viewport for a virtual display is created, the only part of that virtual display that you can view is the rectangular region contained in the viewport. To unpaste a viewport without deleting it, you can invoke SMG$UNPASTE_VIRTUAL_DISPLAY.

If you create a viewport when the associated virtual display is already pasted, the viewport will not be visible. A call to SMG$PASTE_VIRTUAL_DISPLAY will unpaste the virtual display and paste the viewport in its place. Scrolling and Moving a Viewport

A viewport associated with a virtual display may be situated entirely or partially on the pasteboard, or totally off the pasteboard. However, a viewport cannot extend beyond its associated virtual display. If you try to extend a viewport beyond the boundaries of its virtual display, the Chinese Screen Management Facility automatically truncates the viewport to fit into the virtual display.

In order to "scroll" a viewport, you scroll the virtual display associated with the viewport. You do this by calling SMG$SCROLL_VIEWPORT. In actuality, the coordinates of the viewport are changing as it moves over the virtual display to simulate scrolling; however, the location of the viewport on the screen does not change. With the SMG$SCROLL_VIEWPORT routine, you can specify the direction (up, down, left, or right) that you want to scroll.

You can move a viewport by calling SMG$CHANGE_VIEWPORT. This routine lets you specify a new starting location and size for the viewport. By changing the starting location and size of the viewport, you can, in effect, move the window around the virtual display. Changing Viewport Characteristics

The routine SMG$GET_VIEWPORT_CHAR lets you retrieve the current characteristics of a viewport. The characteristics of a viewport consist of the starting and ending row and column positions for the viewport. You can use this routine in conjunction with the SMG$CHANGE_VIEWPORT routine, which lets you change the starting and ending positions of an existing viewport.

If you want to change any characteristic of a viewport other than its starting or ending position, you should use the SMG$CHANGE_VIRTUAL_DISPLAY routine. Any change you make to a virtual display will be reflected in its associated viewport.

For example, if a virtual display has a border, so does the associated viewport. If the virtual display does not have a border, then neither does the viewport. If you want to add or delete a border to a viewport, add or delete the border to the virtual display using the SMG$CHANGE_VIRTUAL_DISPLAY routine. This change is automatically reflected on the viewport.

2.2.11 Menus

The Chinese Screen Management Facility provides the capability to create and make selections from a menu. The menu can be a block menu, a vertical menu, or a horizontal menu. A block menu is a two-dimensional array of items and is the main type of menu provided. A vertical menu displays the menu choices in a single column, while a horizontal menu displays the choices in a single row. Any menu items that do not fit within the bounds of the viewport are not displayed until they are scrolled into view. Creating a Menu

The routine SMG$CREATE_MENU creates a menu in the scrolling region of a specified virtual display. (By default, the scrolling region is the entire virtual display. You can use the routine SMG$SET_DISPLAY_SCROLL_REGION to change the scrolling region.) You specify a format for the menu (block, vertical, or horizontal) when you create it.

A block menu is the default format for a menu. The items in the menu are passed to the routine in the form of a static array of character strings. The menu choices are single spaced by default, but you can request double spacing. Four spaces separate each menu item horizontally. In addition, you can request that the menu choices be displayed in fixed format columns, where the width of the column is equal to the size of the fixed-length strings being passed.

It is important to note that each virtual display can only contain one menu. Also, after calling SMG$CREATE_MENU, you must not output any characters to the display that disturb the area containing the menu; otherwise, the results are unpredictable. The menu is output in the scrolling region of the virtual display. Deleting a Menu

You delete a menu by a call to SMG$DELETE_MENU. This routine discontinues access to the menu choices in the specified virtual display. Additionally, you can request that SMG$DELETE_MENU remove all menu choices from the display when the menu is deleted. Selecting from a Menu

Once you have created a menu, you can select items from that menu using the SMG$SELECT_FROM_MENU routine. When you move around the menu items, the currently selected item is highlighted in reverse video by default. You can specify a default selection that is highlighted and becomes the current item when you call SMG$SELECT_FROM_MENU. If you do not specify a default selection item, the previously selected item remains highlighted.

SMG$SELECT_FROM_MENU provides three modes of operation; you can switch between these modes using the flags parameter. Each mode is described in the following sections. Default Mode

The default mode of operation for the SMG$SELECT_FROM_MENU routine is invoked by omitting the flags parameter. In this mode, you can move around the menu items using the arrow keys, and after selecting an item, you can continue making additional selections. The default mode also lets you "reselect" items that were already selected. RETURN_IMMED Mode

Specifying the SMG$M_RETURN_IMMED value for the flags parameter of the SMG$SELECT_FROM_MENU routine allows you to move around the menu choices with the arrow keys; however, pressing any other key returns control to the user. Ctrl/Z selects the current item and returns SMG$_EOF. Any other key entered selects the current item.

Use SMG$M_RETURN_IMMED mode if you want key definitions other than those provided by the default mode. REMOVE_ITEM Mode

If you specify the SMG$M_REMOVE_ITEM value for the flags parameter of SMG$SELECT_FROM_MENU, you cannot "reselect" an item in the menu, although the item remains in the menu. It appears in the default rendition for the virtual display containing the menu.

If you specify a default selection item while in this mode, and that item has already been selected, the first "selectable" item in the menu is highlighted. If none of the items is selectable, an error is returned.

2.2.12 Saving a Virtual Display

The routine SMG$SAVE_VIRTUAL_DISPLAY saves the contents of a virtual display in a file. The text, renditions, and all the attributes needed to reconstruct the virtual display are saved, but menu, viewport, and subprocess contexts are not saved. You cannot print the resulting file. To restore the virtual display, you can use SMG$LOAD_VIRTUAL_DISPLAY, which creates a new virtual display and loads it with the saved contents of the display. The new virtual display is not pasted to any pasteboard.

2.2.13 Changing Terminal Characteristics

The routine SMG$SET_TERM_CHARACTERISTICS changes or retrieves the terminal characteristics for a given pasteboard. With this routine, you can control multiple terminal characteristics in a single routine call.

2.2.14 Setting the Default Character Set of a Virtual Display

SMG$CREATE_VIRTUAL_DISPLAY has an optional argument (character-set) for the default character set of the virtual display created. If character-set is omitted, Chinese Screen Management Facility uses the SMG$DEFAULT_CHARACTER_SET logical name to define the default character set. Valid definitions for the SMG$DEFAULT_CHARACTER_SET logical name are as follows:

Table 2-1 Default Character Set Names
Value Character Set
SPEC_GRAPHICS DEC Special Graphics

1One of DEC supplemental character set and Latin-1 character set.

If an invalid character set name is assigned in SMG$DEFAULT_CHARACTER_SET logical name, or if the logical name is not defined, the default character set name is unknown.

2.3 Operational Controls

This section describes the Chinese screen management routines that control special modes of operation: minimal update, buffering, and whether or not tabs are used in updating. These modes let you optimize the manner in which information is actually written to the screen. To invoke these modes, you use the SMG$CONTROL_MODE routine.

Normally, you need not be concerned with these modes; the Chinese Screen Management Facility optimizes output so that characters appear to be displayed on the screen immediately. For some applications, however, you may want to take advantage of these mode settings. The following sections describe these modes of operation.

2.3.1 Minimal Update

By default, the Chinese Screen Management Facility attempts to minimize the number of characters written to the screen by rewriting only the parts of the screen that have changed. However, the Chinese Screen Management Facility also supports nonminimal updating, in which all lines affected by a change are redrawn, beginning at the first changed character and continuing to the end of the line.

2.3.2 Buffering

By default, output operations cause an immediate change on the screen by sending many small, partially filled buffers to the terminal instead of updating the screen when the buffer is full. Minimizing the number of these I/O transactions by enabling buffering mode results in faster program execution.

In buffering mode, the Chinese Screen Management Facility writes the terminal buffer to the screen only when the buffer is full. Thus, several output operations may be performed before the results appear on the screen. Because this delay is not acceptable for many applications, a special routine, SMG$FLUSH_BUFFER, is provided for use with buffering. SMG$FLUSH_BUFFER forces the buffer to be written to the terminal whether or not it is full. This routine is useful for an application that can usually accept delayed output but occasionally requires an immediate screen update. Applications that usually need immediate changes on the screen should not enable buffering.

2.3.3 Tabs

Tabs are used for minimal updating. When you are using tabs, you must ensure that the tab stops are set to the Digital default locations. Do not use tabs if you want to be sure that the application will run regardless of the tab settings the user has set on the terminal.

Any tabs that you output to the screen are converted to eight spaces by SMG$ before being output to the screen. The only exception to this is seen in using SMG$CREATE_VIRTUAL_DISPLAY with the display-attributes argument set to SMG$M_DISPLAY_CONTROLS. Only in this case is the tab character printed rather than interpreted as eight spaces.

2.4 Batching Output Operations

If you want to construct a complex virtual display that requires several scrolling, cursor positioning, and output operations but do not want the interim steps to be visible, you can batch the output operations. Batching a series of operations to a virtual display lets the application hide the interim steps.

You may also want to construct a complex pasteboard image but have it appear on the screen only after the entire picture is complete. Unpasting and repasting leaves the screen blank during the construction process, so in this case you can batch a series of composition operations and let the screen show only the final effect.

The Chinese Screen Management Facility provides a mechanism for batching a series of operations at both the virtual display level and the pasteboard level. These are described in the following sections.

2.4.1 Display Update Batching

The SMG$BEGIN_DISPLAY_UPDATE routine causes output operations to a pasted display to be reflected only in the display's buffers. When all operations to the display are finished, the application can call the SMG$END_DISPLAY_UPDATE routine, which causes the display's buffer to be written to the pasteboard.

The SMG$BEGIN_DISPLAY_UPDATE and SMG$END_DISPLAY_UPDATE routines increment and decrement a counter. When this counter's value is zero, output to the virtual display is immediately sent to the pasteboard. When the counter's value is nonzero, output operations are batched; the display batching level is equal to the counter's value. Notice that the counter mechanism allows a subroutine to request and turn off batching without disturbing the batching level of the calling program.

2.4.2 Pasteboard Update Batching

You accomplish pasteboard batching by calling the SMG$BEGIN_PASTEBOARD_UPDATE routine, performing several composition operations, and finally calling the SMG$END_PASTEBOARD_UPDATE routine. The SMG$BEGIN_PASTEBOARD_UPDATE routine causes output operations to be reflected only in the pasteboard buffer, not on the physical screen. The SMG$END_PASTEBOARD_UPDATE routine causes the pasteboard buffer to be written to the physical screen.

The SMG$BEGIN_PASTEBOARD_UPDATE and SMG$END_PASTEBOARD_UPDATE routines increment and decrement a counter. When this counter's value is zero, output to the pasteboard is immediately sent to the physical screen. When the counter's value is nonzero, output operations are batched; the pasteboard batching level is equal to the value of the counter. Notice that the counter mechanism allows a subroutine to request and turn off batching without disturbing the batching level of the calling program.

Previous Next Contents