|
HP OpenVMS Systems Documentation |
|
OpenVMS/Hanzi RTL Chinese Screen Management (SMG$) Manual
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.
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 TextTwo 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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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:
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.
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.
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.
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.
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.
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.
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.
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.
|