.page size 63,84 .lm 1.rm 84 .no fill.no justify .flags bold.flags accept ~.flags substitute ` .figure 15 .center; ^*SCREEN MANAGEMENT SUBROUTINE SYSTEM\* .skip .center; Ken Messer .center; Allied Electronics .skip .center; ``date .page .lm 5.rm 75 .layout 1,2 .fill.justify .style headers 3,1,6,7,7,2,1,7,2 .require "smgdoc.rnt" .title ^*^&Screen Management System Subroutines\&\* .header level 1 ^*^&Introduction\&\* These subroutines have been designed to take advantage of the screen management library routines. All subroutines reference the common definition file (SMG.DFN) shown below. Programs calling the subroutines need not reference this common area. .skip .literal !---------------------------------------------------------------& ! & ! SMG.DFN & ! & ! Screen management system common information & ! & ! These variables are all set in SMG_OPEN. In addition, the & ! number of virtual displays is modified in the virtual display & ! creation routine, SMG_ADD_VIRTUAL_DISPLAY. The number of & ! pasteboards is modified in SMG_ADD_PASTEBOARD. & ! & !---------------------------------------------------------------& MAP (SMG) LONG Pasteboard_ID(3), & Current_pasteboard_id, & Keyboard_ID(3), & Current_keyboard_id, & Display_ID(19), & Err_display_ID, & Input_function_modifier1, & Input_function_modifier2, & Input_display_attr, & Term_set_mask(3), & Number_virtual_displays, & Number_pasteboards, & STRING Paint_char = 1, & Del_seq = 3 MAP (TERM) WORD Term_set_mask_size, & Unused, & LONG Term_set_mask_loc MAP (TERM) LONG Term_set_mask_desc(1) .end literal .skip This common area is loaded by the SMG_OPEN routine. The purpose of each variable is described below: .skip ^*Pasteboard_ID()\* .skip Identifiers for the pasteboards. A default pasteboard is created in SMG_OPEN. Additional pasteboards can be created with SMG_ADD_PASTEBOARD. Note that only one pasteboard can be associated with a given device or file. .skip ^*Current_pasteboard_id\* .skip This is equal to the Pasteboard_id() that has been made the "current" pasteboard. This is set to number zero initially, but may be changed using SMG_SWITCH_PASTEBOARDS provided other pasteboard(s) exist. .skip ^*Keyboard_ID()\* .skip Identifiers for virtual keyboards. A default virtual keyboard is created in SMG_OPEN and is associated with the default pasteboard. .skip ^*Current_keyboard_id\* .skip This works the same way as current_pasteboard_id. Note that one virtual keyboard exists for each additional pasteboard and their numbers match. .skip ^*Display_ID()\* .skip Identifiers for virtual displays. At present there is a maximum of twenty, but this can be expanded as needed. .skip ^*Err_display_ID\* .skip Identifier for the error message virtual display, created in SMG_OPEN. .skip ^*Input_function_modifier1 - Input_function_modifier2\* .skip I/O function modifiers used in the input routines. .skip ^*Input_display_attr\* .skip Video attribute code used in input routines. The virtual display used for input is changed to this attribute prior to taking input. .skip ^*Term_set_mask\* .skip Bit mask used in input routines to specify terminator characters. .skip ^*Paint_char\* .skip User-supplied character used in input routines to mark the area where input is to take place on the physical screen. .skip ^*Del_seq\* .skip Sequence of characters to be output when the delete key is struck during input. This sequence is composed of a backspace character followed by the paint character plus another backspace. .skip ^*Term_set_mask_size - Term_set_mask_loc - Term_set_mask_desc(1)\* .skip Terminator set descriptor used by the SMG$ input routines. .page .header level 1 ^*^&Conventions\&\* The SMG_OPEN routine MUST be called before any other routine is called. This routine does the following: .list,"o" .le; Creates a 24 X 80 pasteboard (number 0) and associates it with the user's terminal. .le; Creates a 24 X 80 virtual display (virtual display number 0) and pastes it. .le; Creates a 1 X 80 error message virtual display. .le; Creates a virtual keyboard (number 0) and associates it with the user's terminal. .le; Places the keypad in numeric mode. .le; Establishes the input routine paint character (passed in as an argument). .le; Establishes the set of input terminators and the video attributes and I/O function modifiers used in the input routines. Also sets the value of the character sequence to be output when the delete key is struck during input (backspace + paint character + backspace). .end list .skip Note that the user must create all other virtual displays as needed. This is done with SMG_ADD_VIRTUAL_DISPLAY. It is important to remember that the first such display is virtual display number 1, the second is number 2, and so on. This number is used as a subscript to the common area variable Display_ID(). It must be passed as an argument in almost every routine in the system, so it is up to the user to keep track of each display's number and attributes. It is highly recommended that this information be documented in the user program. .skip Additional pasteboards and virtual keyboards can be created with SMG_ADD_PASTEBOARD. These are numbered just as virtual displays are. A virtual keyboard is created in this routine to match the pasteboard. The pasteboard number is used as a subscript to the common area variables Pasteboard_id() and Keyboard_id(). .skip The user should NEVER call any SMG RTL routine that creates or deletes a virtual display, keyboard, or pasteboard. .skip If a pasteboard is associated with a file rather than a terminal, the keyboard cannot be used. To avoid passing pasteboard identifiers as parameters, a routine called SMG_SWITCH_PASTEBOARDS must be called prior to any I/O for the specified pasteboard. The pasteboard number is passed to this routine, which makes the desired pasteboard/keyboard combination the current ones. SMG routines can then be called normally. This system allows a program to control more than one terminal. .skip The SMG_CLOSE routine should be called at the end of the user program. This routine "cleans up" by deleting all virtual displays, the virtual keyboard, and the pasteboard. While the RTL documentation states that this clean-up process is not an absolute necessity, it is recommended that it be done. .skip It is imperative that the user read the Screen Management Guidelines section in the Run-Time Library manual (volume 5C-chapter 3) prior to using the routines. Of special concern are the relationships between a virtual display and a pasteboard, and a virtual display and other virtual displays. Also important is the concept of video renditions. While it may be confusing at first, the use of a rendition set/rendition complement system is actually a very clever method of controlling video attributes. In the SMG subroutine system, all renditions may be controlled with one bit mask argument. .page .header level 1 ^*^&Input Routines\&\* All input routines take user input as a character string from a virtual display. While each routine has its own unique characteristics, all have the following in common: .skip.list ,"o" .le; The user may specify a prompt and a row/column for that prompt. One space is left between the last character of the prompt and the point of input. If no prompt is specified (i.e., the prompt parameter is null), input will take place at the row/column position specified. .le; Prior to accepting input, the input field is drawn on the display in reverse video. This field consists of a number of paint characters equal to the length of the field (specified by the user). In order to protect the rest of the display, the cursor may not be moved outside this field. The terminal bell will ring if an attempt is made to do this. .le; A timeout value may be supplied if desired. If input is not completed within TIMEOUT seconds, input will terminate and the timeout parameter will be returned as a -1. Any characters entered prior to the timeout will be returned in the input string. .skip It is important to note that the timeout parameter is zeroed by the routine if no timeout takes place. This being the case, the user MUST reset the timeout parameter each time a routine is called. This was done so the user could check the timeout parameter variable as a boolean TRUE/FALSE after each input routine call. .skip If no timeout is desired, a value of zero MUST be used. .le; Entering control keys, function keys and application-mode keypad keys will cause input to terminate and will return specific values (listed below) in the input string. Note that this will take place ONLY if no other input was entered first, that is, if this was the first key pressed. If one of these keys is pressed AFTER other characters have been entered, the terminal bell will ring and the routine will continue to wait for valid input. Note also that some control keys (C,Y,T,Q,S) will not pass through to an application program unless appropriate settings have been made on the terminal line. Further, control-W has been set aside in all input routines for the specific purpose of repainting the pasteboard in the event of non-SMG screen interruption. Values returned by the function keys are: .break.skip.literal Key(s) Value Returned ------------ ------------------- CTRL/A - /Z ~ + CTRL_ + letter + ~ (ex. CTRL/A = ~CTRL_A~) PF1 - PF4 ~ + PF + number + ~ (ex. PF1 = ~PF1~) KP0 - KP9 ~ + KP + number + ~ (ex. KP0 = ~KP9~) F7 - F20 ~ + F + number + ~ (ex. F20 = ~F20~) Keypad minus ~MINUS~ Keypad comma ~COMMA~ Keypad enter ~ENTER~ Keypad period ~PERIOD~ HELP ~HELP~ FIND ~FIND~ INSERT HERE ~INSERT HERE~ REMOVE ~REMOVE~ SELECT ~SELECT~ PREV SCREEN ~PREV SCREEN~ NEXT SCREEN ~NEXT SCREEN~ UP ARROW ~UP~ DOWN ARROW ~DOWN~ LEFT ARROW ~LEFT~ RIGHT ARROW ~RIGHT~ .end literal.end list.skip Further information on each routine may be found in the next section of this document. .page .header level 1 ^*^&Subroutines\*\& The letter in parenthesis to the left of each argument indicates the data type. All subroutines should be declared in the user program to facilitate error checking. The file SMGDECLARE.INC may be included in any VAX BASIC program to accomplish this. .header level 2 ^*SMG_ADD_PASTEBOARD\* .lm +5 Create a new pasteboard and a virtual keyboard to go with it. If the output device is a file, the keyboard exists but cannot be used for obvious reasons. If the output device is a terminal, it must be available (i.e. not logged in). .skip Arguments: .skip .literal (S) Output_device A valid terminal or file name. If a file is used, RMS controls the I/O. .end literal .lm -5 .header level 2 ^*SMG_ADD_VIRTUAL_DISPLAY\* .lm +5 Create a new virtual display. .skip Arguments: .skip .literal (L) Rows Number of rows the display contains. (L) Columns Number of columns the display contains. (L) Video_attributes Default video attributes for the display. Expressed as a bit mask where: 1 = Blink 2 = Bold 4 = Reverse video 8 = Underline Any combination of these is acceptable. (L) Border_flag Border the display. 0 = no 1 = yes .end literal .lm -5 .header level 2 ^*SMG_BEGIN_DISPLAY_BATCHING\* .lm +5 Turn on batching for a virtual display. This routine should not be called unless the display has already been pasted. .skip Arguments: .skip (L) Virtual_display_number .lm -5 .header level 2 ^*SMG_BEGIN_PB_BATCHING\* .lm +5 Turn on batching for the current pasteboard. .skip .literal Arguments: NONE .end literal .lm -5 .header level 2 ^*SMG_BOX\* .lm +5 Draw a rectangle on a virtual display. .skip Arguments: .skip .literal (L) Top_left_row Coordinates for upper left (L) Top_left_column and lower right corners (L) Bottom_right_row of the box. (L) Bottom_right_column (L) Rendition Bit mask indicating the display rendition. See SMG_CHANGE_RENDITION for details. (L) Virtual_display_number .end literal .lm -5 .header level 2 ^*SMG_CHANGE_DEF_ATTR\* .lm +5 Change the default video attributes of a virtual display. All future text output to the display will have the new attributes. Existing text will not be affected. .skip Arguments: .skip .literal (L) Video_attributes Default video attributes. See SMG_ADD_VIRTUAL_DISPLAY. (L) Virtual_display_number .end literal .lm -5 .header level 2 ^*SMG_CHANGE_PASTEBOARD\* .lm +5 Change a pasteboard's size and/or background color. Valid sizes are 24 X 80 (normal) and 24 X 132 (wide). Valid colors are dark and light. Color graphics are not supported by the SMG RTL routines at this time. .skip Arguments: .skip .literal (L) Size 0 = 24 X 80 1 = 24 X 132 (L) Background 0 = dark 1 = light .end literal .lm -5 .header level 2 ^*SMG_CHANGE_RENDITION\* .lm +5 Change the video attributes of all or part of a virtual display. Existing text in the area specified will be changed to the new rendition immediately. .skip Arguments: .skip .literal (L) Start_row Starting row to receive new rendition. (L) Start_column Starting column to receive new rendition. (L) Rows Number of rows to receive new rendition. (L) Columns Number of columns to receive new rendition. (L) Rendition New video rendition. Expressed as a bit mask where: 1 = Blink set 2 = Bold set 4 = Reverse video set 8 = Underline set 16 = Blink complement 32 = Bold complement 64 = Reverse video complement 128 = Underline complement (L) Virtual_display_number .end literal .lm -5 .header level 2 ^*SMG_CHANGE_VIRTUAL_DISPLAY\* .lm +5 Change the default attributes of a virtual display. Existing text will be remapped at position 1,1 and the cursor will be moved home. Text may be truncated or padded on the right with spaces depending on the nature of the change. If a labeled border falls outside of the display area after the change has been made, the label (not the border itself) will be deleted. .skip Arguments: .skip .literal (L) New_rows Number of rows in the display. (L) New_columns Number of columns in the display. (L) Display_attributes Border the display. 0 = no 1 = yes (L) Video_attributes Default video attributes. See SMG_ADD_VIRTUAL_DISPLAY. (L) Virtual_display_number .end literal .lm -5 .header level 2 ^*SMG_CLEAR\* .lm +6 Clear all or a portion of a line or a virtual display. .skip Arguments: .skip .literal (L) Entity 0 Clear display 1 Clear line (L) Portion 0 Cursor to end of entity 1 Cursor to beginning of entity 2 Entire entity (L) Virtual_display_number .end literal .lm -6 .header level 2 ^*SMG_CLOSE\* .lm +6 Delete all virtual displays, keyboards, and pasteboards. .skip Arguments: .skip .literal (L) Clear_screen_flag 1 clear screen 0 do not clear screen .end literal .lm -6 .header level 2 ^*SMG_CURSOR_ON_OFF\* .lm +6 Turn the current pasteboard's cursor on or off. .skip Arguments: .skip .literal (S) Cursor control command ON Turn the cursor on OFF Turn the cursor off .end literal .lm -6 .header level 2 ^*SMG_DEF_INPUT\* .lm +6 Display a prompt at a specific cursor location in a virtual display and input a character string of specified length. A default response (passed in via the input string argument) is displayed at the input point. The default response is taken if a carriage return is typed, otherwise, the routine will accept normal input. The default response will be redisplayed if the user enters his own data, then backs up to the beginning of the input field with the delete key. If a timeout value is specified and no input is done during the timeout period, the subroutine will exit with a timeout value of -1, thus the user program should always check this value. If no timeout occurs, the timeout argument is zeroed. Note that the input variable is preserved if a timeout occurs. .skip Arguments: .skip .literal (S) Prompt_string Prompt string. (L) Row Prompt string row position. (L) Column Prompt string column position. (L) Length Input string maximum length. (S) Input_string Input variable - default input value is passed in via this variable - desired input is passed out. (L) Timeout Timeout value in seconds. (L) Virtual_display_number .end literal .lm -6 .header level 2 ^*SMG_DEF_INPUT_CLR\* .lm +6 Same as SMG_DEF_INPUT plus clear line after input. .lm -6 .header level 2 ^*SMG_DEF_ONE_CHAR\* .lm +6 A combination of ^*SMG_DEF_INPUT\* and ^*SMG_ONE_CHAR\*. The default response (passed in via the input variable) is taken if a carraige return is typed. .skip Arguments: .skip .literal (S) Prompt_string Prompt string. (L) Row Prompt string row position. (L) Column Prompt string column position. (S) Input_string Input variable. (L) Timeout Timeout value in seconds. (L) Echo_flag 0 = do not echo input character -1 = echo (L) Virtual_display_number .end literal .lm -6 .header level 2 ^*SMG_DEF_ONE_CHAR_CLR\* .lm +6 Same as SMG_DEF_ONE_CHAR plus clear line after input. Note that the Echo_flag parameter is omitted. .lm -6 .header level 2 ^*SMG_DELETE_CHARS\* .lm +6 Delete characters from a specified line in a virtual display. All characters to the right of the deleted character(s) shift left to occupy the vacated space. .skip Arguments: .skip .literal (L) Number_chars Number of characters to delete. (L) Row Start row position. (L) Column Start column position. (L) Virtual_display_number .end literal .lm -6 .header level 2 ^*SMG_DELETE_LAST_VIRTUAL_DISPLAY\* .lm +6 Delete the most recently created virtual display. If the display is pasted, it will be removed from the pasteboard. Note that virtual display number zero (created in SMG_OPEN) CANNOT be deleted with this routine. .skip .literal Arguments: NONE .end literal .lm -6 .header level 2 ^*SMG_DELETE_LINES\* .lm +6 Delete line(s) from a virtual display. Lines below the deleted line(s) scroll up to fill the vacated space. Blank lines fill the bottom of the display. .skip Arguments: .skip .literal (L) Start_line Start row position. (L) Number_lines Number of lines to delete. (L) Virtual_display_number .end literal .lm -6 .header level 2 ^*SMG_DISP\* .lm +6 Display a character string at a specified position in a virtual display. .skip Arguments: .skip .literal (S) Character_string Text to display. (L) Row Display row position. (L) Column Display column position. (L) Rendition Bit mask indicating display rendition. See SMG_CHANGE_RENDITION for details. (L) Virtual_display_number .end literal .lm -6 .header level 2 ^*SMG_DISP_CLR\* .lm +6 Same as SMG_DISP plus clear to end of line after displaying text. .lm -6 .header level 2 ^*SMG_DISP_HIGH_WIDE\* .lm +6 Display a character string in double-height double-width characters at a specified position in a virtual display. .skip Arguments: .skip .literal (S) Character_string Text to display. (L) Row Display row position. (L) Column Display column position. (L) Rendition Bit mask indicating display rendition. See SMG_CHANGE_RENDITION for details. (L) Virtual_display_number .end literal .lm -6 .header level 2 ^*SMG_DISP_WIDE\* .lm +6 Display a character string in double-width characters at a specified position in a virtual display. .skip Arguments: .skip .literal (S) Character_string Text to display. (L) Row Display row position. (L) Column Display column position. (L) Rendition Bit mask indicating display rendition. See SMG_CHANGE_RENDITION for details. (L) Virtual_display_number .end literal .lm -6 .header level 2 ^*SMG_DISP_SCROLL\* .lm +6 Write a line to a virtual display at the current line. Scrolling takes place in the specified direction once the text reaches the top or bottom (depending on direction) of the scrolling region. If no text is supplied, a blank line will be opened. Note that this routine cannot be used to insert a line in the middle of a display (SMG_INSERT_LINE should be used for this). Note also that the user program is responsible for positioning the cursor to the proper line before calling this routine. .skip Arguments: .skip .literal (S) Text (L) Direction 0 = Up 1 = Down (L) Lines_to_scroll Number of lines to scroll after output. (L) Rendition Bit mask indicating display rendition. See SMG_CHANGE_RENDITION for details. (L) Virtual_display_number .end literal .lm -6 .header level 2 ^*SMG_END_DISPLAY_BATCHING\* .lm +6 Turn off batching for a virtual display. This routine should not be called unless the display has already been pasted. .skip Arguments: .skip .literal (L) Virtual_display_number .end literal .lm -6 .header level 2 ^*SMG_END_PB_BATCHING\* .lm +6 Turn off batching for the current pasteboard. .skip .literal Arguments: NONE .end literal .lm -6 .header level 2 ^*SMG_ERRMSG\* .lm +6 Ring the terminal bell and display an error message on the bottom line (24) of the pasteboard. The message is displayed on its own one line virtual display for three seconds and is then removed. Any text which was pasted on another virtual display on line 24 of the pasteboard will not be affected. .skip Arguments: .skip .literal (S) Error_message (L) Video_attributes Display video attributes. See SMG_ADD_VIRTUAL_DISPLAY. .end literal .lm -6 .header level 2 ^*SMG_GET_CHAR\* .lm +6 Return the ASCII value of the character at the specified pasteboard (screen) position. If the screen management system has not written anything to this position, the value returned will be hex FF. Note that this routine sets the physical cursor to the specified position before obtaining the character. .skip Arguments: .skip .literal (L) Row Physical screen row. (L) Column Physical screen column. (B) Character_code ASCII of character at given location. .end literal .lm -6 .header level 2 ^*SMG_GET_DISPLAY_ATTR\* .lm +6 Obtain the attributes of a given virtual display. This information may be useful if it becomes necessary to save current attributes, change them, then restore them later. .skip Arguments: .skip .literal (L) Number_Rows Number of rows in the display. (L) Number_Columns Number of columns in the display. (L) Display_Attributes Current display attributes (i.e. bordered) (L) Video_Attributes Current video attributes (blink, bold, etc.) (L) Virtual_display_number .end literal .lm -6 .header level 2 ^*SMG_GET_PASTING_INFO\* .lm +6 Obtain pasting information about a virtual display. Note that the display should not be batched at the time this routine is called as the results may be unpredictable. If the display is not pasted, all parameters will be returned as zero. .skip Arguments: .skip .literal (L) Pasteboard_row Row at which the display is pasted. (L) Pasteboard_column Column at at which the display is pasted. (L) Pasted_flag 0 = display not pasted 1 = display pasted (L) Occlusion_status 0 = display not occluded 1 = display occluded (L) Virtual_display_number .end literal .lm -6 .header level 2 ^*SMG_INPUT\* .lm +6 Display a prompt at a specific cursor location in a virtual display and input a character string of specified length. See SMG_DEF_INPUT for an explanation of the timeout argument. .skip Arguments: .skip .literal (S) Prompt_string Prompt string. (L) Row Prompt string row position. (L) Column Prompt string column position. (L) Length Input string maximum length. (S) Input_string Input variable. (L) Timeout Timeout value in seconds. (L) Virtual_display_number .end literal .lm -6 .header level 2 ^*SMG_INPUT_CLR\* .lm +6 Same as SMG_INPUT plus clear line after input. .lm -6 .header level 2 ^*SMG_INSERT_CHARS\* .lm +6 Insert characters into a line at a specified point in a virtual display. All text to the right of the insertion point shifts right as new text is inserted. Characters which overflow the right boundary of the virtual display are discarded. .skip Arguments: .skip .literal (S) Insertion_text Characters to be inserted. (L) Row Insertion row. (L) Column Insertion column. (L) Rendition Bit mask indicating display rendition. See SMG_CHANGE_RENDITION for details. (L) Virtual_display_number .end literal .lm -6 .header level 2 ^*SMG_INSERT_LINE\* .lm +6 Insert a line of text into a virtual display at a location OTHER THAN THE FIRST OR LAST LINE. Existing lines are scrolled in the specified direction to create an open space. The open space is then filled with user-supplied text, or is left blank if no text is provided. If text is supplied and does not span the display width, it is padded on the right with spaces. Use SMG_DISP_SCROLL to insert lines at the first or last line of a virtual display. .skip Arguments: .skip .literal (S) Insertion_text Text to be written on the new line. (L) Row Row at which text is inserted. (L) Direction 0 = up 1 = down (L) Rendition Bit mask indicating display rendition. See SMG_CHANGE_RENDITION for details. (L) Virtual_display_number .end literal .lm -6 .header level 2 ^*SMG_LABEL_BORDER\* .lm +6 Label the border of a virtual display. If the display is not bordered, force this attribute first. A null label causes the border to be unlabeled. If the border is already labeled, the new label replaces the old. If another border is already labeled, it will become unlabeled prior to labeling the selected border. If the label supplied will not fit, the border will be unlabeled. .skip Arguments: .skip .literal (S) Label Label text. (L) Position_flag 0 = top 1 = bottom 2 = left 3 = right (L) Start_position Starting character position for the label. If zero, the label is centered in the border. (L) Rendition Bit mask indicating display rendition. See SMG_CHANGE_RENDITION for details. (L) Virtual_display_number .end literal .lm -6 .header level 2 ^*SMG_LINE\* .lm +6 Draw a line on a virtual display. .skip Arguments: .skip .literal (L) Start_row (L) Start_column (L) End_row (L) End_column (L) Rendition Bit mask indicating display rendition. See SMG_CHANGE_RENDITION for details. (L) Virtual_display_number .end literal .lm -6 .header level 2 ^*SMG_MOVE_VIRTUAL_DISPLAY\* .lm +6 Relocate a virtual display on the pasteboard and preserve the pasting order. .skip Arguments: .skip .literal (L) New_pb_row Pasteboard coordinates at which row 1, (L) New_pb_column column 1 of the virtual display is pasted. (L) Virtual_display_number .end literal .lm -6 .header level 2 ^*SMG_ONE_CHAR\* .lm +6 Functions like SMG_INPUT but allows only one character of input. No carriage return is necessary after entering the single character. Echo of the input character is optional. See SMG_DEF_INPUT for an explanation of the timeout argument. .skip Arguments: .skip .literal (S) Prompt_string Prompt string. (L) Row Prompt string row position. (L) Column Prompt string column position. (S) Input_string Input variable. (L) Timeout Timeout value in seconds. (L) Echo_flag 0 = do not echo input character -1 = echo (L) Virtual_display_number .end literal .lm -6 .header level 2 ^*SMG_ONE_CHAR_CLR\* .lm +6 Same as SMG_ONE_CHAR plus clear line after input. Note that the Echo_flag parameter is omitted. .lm -6 .header level 2 ^*SMG_OPEN\* .lm +6 Loads the SMG common area (SMG.DFN), creates the pasteboard, one virtual display (number 0), the error message virtual display, and the virtual keyboard. Allows the user to establish the paint character for the input routines. The virtual display is pasted for the user's convenience. See the introduction and system conventions sections of this document for further information. .skip Arguments: .skip .literal (S) Paint_character Input routine paint character. (L) Clear_screen_flag 1 = Clear screen 0 = do not clear screen .end literal .lm -6 .header level 2 ^*SMG_PASTE\* .lm +6 Places a virtual display on the pasteboard, making it visible. .skip Arguments: .skip .literal (L) Pasteboard_row Pasteboard coordinates at which row 1, (L) Pasteboard_column column 1 of the virtual display is pasted. (L) Virtual_display_number .end literal .lm -6 .header level 2 ^*SMG_POS\* .lm +6 Position the cursor on a virtual display. Note that this position has NOTHING TO DO with physical screen coordinates. .skip Arguments: .skip .literal (L) Row Virtual display row. (L) Column Virtual display column. (L) Virtual_display_number .end literal .lm -6 .header level 2 ^*SMG_POS_CLEAR\* .lm +6 Position the cursor on a virtual display and then clear the line or display as in SMG_CLEAR. .skip Arguments: .skip .literal (L) Row Virtual display row. (L) Column Virtual display column. (L) Entity 0 Clear display 1 Clear line (L) Portion 0 Cursor to end of entity 1 Cursor to beginning of entity 2 Entire entity (L) Virtual_display_number .end literal .lm -6 .header level 2 ^*SMG_READ_FROM_DISPLAY\* .lm +6 Read all or part of a line of text from a virtual display. If a terminator string is used, the user must position the cursor himself and the row argument must be zero. The terminator string argument is ignored if the row argument is used. The user should refer to the RTL manual section which describes SMG$READ_FROM_DISPLAY for more details. .skip Arguments: .skip .literal (L) Row Virtual display row. (S) Terminator_string List of terminators for "back-searching". (S) Returned string Returned text. (L) Virtual_display_number .end literal .lm -6 .header level 2 ^*SMG_REPASTE\* .lm +6 Unpaste and repaste a virtual display on the pasteboard. The pasting order is NOT preserved. .skip Arguments: .skip .literal (L) Pasteboard_row Pasteboard coordinates at which row 1, (L) Pasteboard_column column 1 of the virtual display is pasted. (L) Virtual_display_number .end literal .lm -6 .header level 2 ^*SMG_RESTORE_SCREEN\* .lm +6 Restore the physical screen to it's condition prior to some non-SMG event. The screen must have been saved previously by calling SMG_SAVE_SCREEN. .skip .literal Arguments: NONE .end literal .lm -6 .header level 2 ^*SMG_RETURN_CURSOR_POSITION\* .lm +6 Return the cursor coordinates in a virtual display. .skip Arguments: .skip .literal (L) Row Virtual display (L) Column cursor coordinates. (L) Virtual_display_number .end literal .lm -6 .header level 2 ^*SMG_SAVE_SCREEN\* .lm +6 Save the physical screen. This would normally be done prior to non-SMG I/O. The screen may be restored by calling SMG_RESTORE_SCREEN. .skip .literal Arguments: NONE .end literal .lm -6 .header level 2 ^*SMG_SCROLL\* .lm +6 Scroll the display area in a virtual display a specified number of lines or columns in the desired direction. If the height argument is zero, the scrolling region will default to that set by SMG_SET_SCROLL. If no scrolling region has been set and the height argument is zero, the scrolling region will default to the height of the virtual display. If the width argument is zero, the width of the virtual display is used. Any text that is scrolled off the display cannot be recovered. .skip Arguments: .skip .literal (L) Start_row Starting virtual display row. (L) Start_column Starting virtual display column. (L) Height Number of rows in the scrolling region. (L) Width Number of columns in the scrolling region. (L) Direction 0 = up 1 = down 2 = left 3 = right (L) Number_of_lines Number of lines or columns to scroll (L) Virtual_display_number .end literal .lm -6 .header level 2 ^*SMG_SET_KP_MODE\* .lm +6 Set the current keyboard's keypad to either numeric or applications mode. .skip Arguments: .skip .literal (L) New_mode 0 = numeric mode 1 = applications mode .end literal .lm -6 .header level 2 ^*SMG_SET_SCROLL\* .lm +6 Set the scrolling region in a virtual display. .skip Arguments: .skip .literal (L) Top_row Top row of the scrolling region. (L) Bottom_row Bottom row of the scrolling region. (L) Virtual_display_number .end literal .lm -6 .header level 2 ^*SMG_SWITCH_PASTEBOARDS\* .lm +6 Change the "current" pasteboard/keyboard combination. This allows the SMG routines to do I/O to different devices/files. One program may control multiple terminals using this method. The user must first create a new pasteboard/keyboard with SMG_ADD_PASTEBOARD. .skip Arguments: .skip .literal (L) Pasteboard_number The number of the pasteboard/keyboard to be made the current ones. The pasteboard/keyboard created by SMG_OPEN is number 0. Additional ones are numbered 1,2,3... in the order they are created. .end literal .lm -6 .header level 2 ^*SMG_TITLE\* .lm +6 Write a title at the top of a virtual display, as well as the current date and time on line three and a solid horizontal line on line four. The title is centered in double-height double-width characters provided the terminal line has the DEC_CRT characteristic set and the title is 40 characters or less in length. If the title is longer than 40 characters or if the terminal line does not have the DEC_CRT characteristic set, the title is centered on line one. It is assumed that the virtual display is 80 columns wide, contains at least 4 rows, and is pasted at row 1, column 1 of an 80 by 24 pasteboard. No provision is made for terminals that partially emulate a VT100 (and thus would have the DEC_CRT characteristic set) but are unable to produce double-height double-width characters. .skip Arguments: .skip .literal (S) Title The title text. (L) Virtual_display_number .end literal .lm -6 .header level 2 ^*SMG_UNPASTE\* .lm +6 Remove a virtual display from a pasteboard, thus removing it from the terminal screen. The virtual display itself is not altered in any way. .skip Arguments: .skip .literal (L) Virtual_display_number .end literal .lm -6 .header level 1 ^*^&Functions\*\& .header level 2 ^*SMG_YES_NO\* .lm +6 Input function which accepts either Y or N in response to a prompt requiring a yes or no answer. A boolean true or false default response is passed in, and the letter Y or N is echoed on the display as the default answer in a fashion similar to SMG_DEF_INPUT. A response of Y or N (regardless of case) will terminate input without a carriage return (as in SMG_ONE_CHAR). A carriage return will terminate input and cause the function to return the default value. .skip ^&^*VERY IMPORTANT:\&\*##The function will return the default value if a timeout occurs (the timeout argument will return a value of -1 in this case), thus the user program should ^*ALWAYS\* check this when handling the default response. .skip.literal Function value: LONG Will be either true (-1) or false (0). .end literal.skip Arguments: .skip .literal (S) Prompt_string Prompt string. (L) Row Prompt string row position. (L) Column Prompt string column position. (L) Default_response Boolean true or false (-1 or 0). (L) Timeout Timeout value in seconds. (L) Virtual_display_number .end literal .lm -6