SCREEN MANAGEMENT SUBROUTINE SYSTEM SCREEN MANAGEMENT SUBROUTINE SYSTEM Ken Messer Allied Electronics 2 December 1985 CONTENTS 1 INTRODUCTION . . . . . . . . . . . . . . . . . . . . 3 2 CONVENTIONS . . . . . . . . . . . . . . . . . . . . 5 3 INPUT ROUTINES . . . . . . . . . . . . . . . . . . . 7 4 SUBROUTINES . . . . . . . . . . . . . . . . . . . . 9 4.1 SMG_ADD_PASTEBOARD . . . . . . . . . . . . . . . . 9 4.2 SMG_ADD_VIRTUAL_DISPLAY . . . . . . . . . . . . . 9 4.3 SMG_BEGIN_DISPLAY_BATCHING . . . . . . . . . . . . 9 4.4 SMG_BEGIN_PB_BATCHING . . . . . . . . . . . . . . 9 4.5 SMG_BOX . . . . . . . . . . . . . . . . . . . . 10 4.6 SMG_CHANGE_DEF_ATTR . . . . . . . . . . . . . . 10 4.7 SMG_CHANGE_PASTEBOARD . . . . . . . . . . . . . 10 4.8 SMG_CHANGE_RENDITION . . . . . . . . . . . . . . 11 4.9 SMG_CHANGE_VIRTUAL_DISPLAY . . . . . . . . . . . 11 4.10 SMG_CLEAR . . . . . . . . . . . . . . . . . . . 11 4.11 SMG_CLOSE . . . . . . . . . . . . . . . . . . . 11 4.12 SMG_DEF_INPUT . . . . . . . . . . . . . . . . . 12 4.13 SMG_DEF_INPUT_CLR . . . . . . . . . . . . . . . 12 4.14 SMG_DELETE_CHARS . . . . . . . . . . . . . . . . 12 4.15 SMG_DELETE_LAST_VIRTUAL_DISPLAY . . . . . . . . 12 4.16 SMG_DELETE_LINES . . . . . . . . . . . . . . . . 13 4.17 SMG_DISP . . . . . . . . . . . . . . . . . . . . 13 4.18 SMG_DISP_HIGH_WIDE . . . . . . . . . . . . . . . 13 4.19 SMG_DISP_WIDE . . . . . . . . . . . . . . . . . 13 4.20 SMG_DISP_CLR . . . . . . . . . . . . . . . . . . 14 4.21 SMG_DISP_SCROLL . . . . . . . . . . . . . . . . 14 4.22 SMG_END_DISPLAY_BATCHING . . . . . . . . . . . . 14 4.23 SMG_END_PB_BATCHING . . . . . . . . . . . . . . 14 4.24 SMG_ERRMSG . . . . . . . . . . . . . . . . . . . 14 4.25 SMG_GET_CHAR . . . . . . . . . . . . . . . . . . 15 4.26 SMG_INPUT . . . . . . . . . . . . . . . . . . . 15 4.27 SMG_INPUT_CLR . . . . . . . . . . . . . . . . . 15 4.28 SMG_INSERT_CHARS . . . . . . . . . . . . . . . . 15 4.29 SMG_INSERT_LINE . . . . . . . . . . . . . . . . 16 4.30 SMG_LABEL_BORDER . . . . . . . . . . . . . . . . 16 4.31 SMG_LINE . . . . . . . . . . . . . . . . . . . . 16 4.32 SMG_MOVE_VIRTUAL_DISPLAY . . . . . . . . . . . . 17 4.33 SMG_ONE_CHAR . . . . . . . . . . . . . . . . . . 17 4.34 SMG_ONE_CHAR_CLR . . . . . . . . . . . . . . . . 17 4.35 SMG_OPEN . . . . . . . . . . . . . . . . . . . . 17 4.36 SMG_PASTE . . . . . . . . . . . . . . . . . . . 17 4.37 SMG_POS . . . . . . . . . . . . . . . . . . . . 18 4.38 SMG_POS_CLEAR . . . . . . . . . . . . . . . . . 18 4.39 SMG_READ_FROM_DISPLAY . . . . . . . . . . . . . 18 4.40 SMG_REPASTE . . . . . . . . . . . . . . . . . . 18 4.41 SMG_RESTORE_SCREEN . . . . . . . . . . . . . . . 19 4.42 SMG_RETURN_CURSOR_POSITION . . . . . . . . . . . 19 4.43 SMG_SAVE_SCREEN . . . . . . . . . . . . . . . . 19 4.44 SMG_SCROLL . . . . . . . . . . . . . . . . . . . 19 4.45 SMG_SET_KP_MODE . . . . . . . . . . . . . . . . 20 4.46 SMG_SET_SCROLL . . . . . . . . . . . . . . . . . 20 4.47 SMG_SWITCH_PASTEBOARDS . . . . . . . . . . . . . 20 4.48 SMG_TITLE . . . . . . . . . . . . . . . . . . . 20 4.49 SMG_UNPASTE . . . . . . . . . . . . . . . . . . 21 5 FUNCTIONS . . . . . . . . . . . . . . . . . . . . 21 5.1 SMG_YES_NO . . . . . . . . . . . . . . . . . . . 21 2 Screen Management System Subroutines ______ __________ ______ ___________ ______ __________ ______ ___________ Screen Management System Subroutines INTRODUCTION ____________ ____________ 1 INTRODUCTION These subroutines have been designed to take advantage of the new 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. !---------------------------------------------------------------& ! & ! 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. & ! & !---------------------------------------------------------------& COMMON (SMG) LONG Pasteboard_ID(3), & Current_pasteboard_id, & Keyboard_ID(3), & Current_keyboard_id, & Display_ID(9), & Display_rows(9), & Display_cols(9), & Err_display_ID, & Input_function_modifier1, & Input_function_modifier2, & Input_display_attr, & Term_set_mask(3), & BYTE 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) This common area is loaded by the SMG_OPEN routine. The purpose of each variable is described below: Pasteboard_ID() Pasteboard_ID() 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. Current_pasteboard_id Current_pasteboard_id This is equal to the Pasteboard_id() that has been made the "current" pasteboard. This is set to number zero initially. The user may change this using SMG_SWITCH_PASTEBOARDS provided other pasteboard(s) exist. 3 Screen Management System Subroutines ______ __________ ______ ___________ ______ __________ ______ ___________ Screen Management System Subroutines Keyboard_ID() Keyboard_ID() Identifiers for virtual keyboards. A default virtual keyboard is created in SMG_OPEN and is associated with the default pasteboard. Current_keyboard_id Current_keyboard_id This works the same way as current_pasteboard_id. Note that one virtual keyboard exists for each additional pasteboard and their numbers match. Display_ID() Display_ID() Identifiers for virtual displays. At present there is a maximum of ten of these, but this can be expanded as needed. Virtual displays are created in SMG_OPEN and SMG_ADD_VIRTUAL_DISPLAY. Display_rows() - Display_cols() Display_rows() - Display_cols() These contain the number of rows and columns that each virtual display contains. They are set in SMG_OPEN and SMG_ADD_VIRTUAL_DISPLAY. Err_display_ID Err_display_ID Identifier for the error message virtual display, which is created in SMG_OPEN. Input_function_modifier1 - Input_function_modifier2 Input_function_modifier1 - Input_function_modifier2 I/O function modifiers used in the input routines. Input_display_attr Input_display_attr Video attribute code used in input routines. The virtual display used for input is changed to this attribute prior to taking input. Term_set_mask Term_set_mask Bit mask used in input routines to specify terminator characters. Paint_char Paint_char User supplied character used in input routines to mark the area where input is to take place on the physical screen. Del_seq Del_seq 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. Term_set_mask_size - Term_set_mask_loc - Term_set_mask_desc(1) Term_set_mask_size - Term_set_mask_loc - Term_set_mask_desc(1) Used to build the terminator set descriptor in the proper format as required by the SMG$ input routines. 4 Screen Management System Subroutines ______ __________ ______ ___________ ______ __________ ______ ___________ Screen Management System Subroutines CONVENTIONS ___________ ___________ 2 CONVENTIONS The SMG_OPEN routine MUST be called before any other routine is called. This routine does the following: o Creates a 24 by 80 pasteboard (number 0) and associates it with the user's terminal (TT:). o Creates a 24 X 80 virtual display (virtual display number 0) and pastes it. o Creates a 1 X 80 error message virtual display. o Creates a virtual keyboard (number 0) and associates it with the user's terminal (TT:). o Places the keypad in numeric mode. o Establishes the input routine paint character (which is passed in as an argument). o 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). Note that the user must create all other virtual display routines 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 variables, Display_ID(), Display_rows(), and Display_cols(). 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. 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(). The user should NEVER call any SMG RTL routine directly that creates or deletes a virtual display, keyboard, or pasteboard. 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. 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 5 Screen Management System Subroutines ______ __________ ______ ___________ ______ __________ ______ ___________ Screen Management System Subroutines keyboard, and the pasteboard. While the system documentation states that this clean-up process is not an absolute necessity, it is recommended that it be done anyway. 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. 6 Screen Management System Subroutines ______ __________ ______ ___________ ______ __________ ______ ___________ Screen Management System Subroutines INPUT ROUTINES _____ ________ _____ ________ 3 INPUT ROUTINES All input routines take user input as a string value from a virtual display. While each routine has its own unique characteristics, all have the following in common: o 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. o 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. o 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. 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 that the user could check the timeout parameter variable as a boolean TRUE/FALSE after each input routine call. If no timeout is desired, a value of zero MUST be used. o Entering 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. Values returned by the function keys are: Key(s) Value Returned ------------ ------------------- 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~ INSERT HERE ~INSET HERE~ REMOVE ~REMOVE~ SELECT ~SELECT~ PREV SCREEN ~PREV SCREEN~ NEXT SCREEN ~NEXT SCREEN~ 7 Screen Management System Subroutines ______ __________ ______ ___________ ______ __________ ______ ___________ Screen Management System Subroutines UP ARROW ~UP~ DOWN ARROW ~DOWN~ LEFT ARROW ~LEFT~ RIGHT ARROW ~RIGHT~ Further information on each routine may be found in the next section of this document. 8 Screen Management System Subroutines ______ __________ ______ ___________ ______ __________ ______ ___________ Screen Management System Subroutines SUBROUTINES ___________ ___________ 4 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 program to accomplish this. SMG_ADD_PASTEBOARD 4.1 SMG_ADD_PASTEBOARD 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). Arguments: (S) Output_device A valid terminal or file name. If a file is used, RMS controls the I/O. SMG_ADD_VIRTUAL_DISPLAY 4.2 SMG_ADD_VIRTUAL_DISPLAY Create a new virtual display. Arguments: (L) Rows Number of rows the display contains. (L) Columns Number of columns the display contains. (B) 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 four is acceptable. (B) Border_flag Border the display. 0 = no 1 = yes SMG_BEGIN_DISPLAY_BATCHING 4.3 SMG_BEGIN_DISPLAY_BATCHING Turn on batching for a virtual display. This routine should not be called unless the display has already been pasted. Arguments: (B) Virtual_display_number SMG_BEGIN_PB_BATCHING 4.4 SMG_BEGIN_PB_BATCHING Turn on batching for the current pasteboard. Arguments: NONE 9 Screen Management System Subroutines ______ __________ ______ ___________ ______ __________ ______ ___________ Screen Management System Subroutines SMG_BOX 4.5 SMG_BOX Draw a rectangle on a virtual display. Arguments: (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 (W) Rendition Bit mask indicating the display rendition. See SMG_CHANGE_DEF_ATTR for details. (B) Virtual_display_number SMG_CHANGE_DEF_ATTR 4.6 SMG_CHANGE_DEF_ATTR Change the default video rendition of a virtual display. All future text output to the display will have the new rendition. Existing text will not be affected. Arguments: (W) 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 See page 3-13 in the Run-Time Library manual for an explanation of rendition set and complement. (B) Virtual_display_number SMG_CHANGE_PASTEBOARD 4.7 SMG_CHANGE_PASTEBOARD 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. Arguments: (B) Size 0 = 80 X 24 1 = 24 X 132 (B) Background 0 = dark 1 = light 10 Screen Management System Subroutines ______ __________ ______ ___________ ______ __________ ______ ___________ Screen Management System Subroutines SMG_CHANGE_RENDITION 4.8 SMG_CHANGE_RENDITION 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. Arguments: (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. (W) Rendition Bit mask indicating the new rendition. See SMG_CHANGE_DEF_ATTR for details. (B) Virtual_display_number SMG_CHANGE_VIRTUAL_DISPLAY 4.9 SMG_CHANGE_VIRTUAL_DISPLAY Change the default attributes of a virtual display. Existing text will be re-mapped 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. Arguments: (L) New_rows Number of rows in the display. (L) New_columns Number of columns in the display. (B) Border_flag Border the display. 0 = no 1 = yes (B) Video_attributes Default video attributes. See SMG_ADD_VIRTUAL_DISPLAY. (B) Virtual_display_number SMG_CLEAR 4.10 SMG_CLEAR Clear all or a portion of a line or a virtual display. Arguments: (B) Entity 0 Clear display 1 Clear line (B) Portion 0 Cursor to end of entity 1 Cursor to beginning of entity 2 Entire entity (B) Virtual_display_number SMG_CLOSE 4.11 SMG_CLOSE Delete all virtual displays, keyboards, and pasteboards. Arguments: (B) Clear_screen_flag 1 clear screen 0 do not clear screen 11 Screen Management System Subroutines ______ __________ ______ ___________ ______ __________ ______ ___________ Screen Management System Subroutines SMG_DEF_INPUT 4.12 SMG_DEF_INPUT Display a prompt at 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. 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. Arguments: (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. (B) Virtual_display_number SMG_DEF_INPUT_CLR 4.13 SMG_DEF_INPUT_CLR Same as SMG_DEF_INPUT plus clear line after input. SMG_DELETE_CHARS 4.14 SMG_DELETE_CHARS 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. Arguments: (L) Number_chars Number of characters to delete. (L) Row Start row position. (L) Column Start column position. (B) Virtual_display_number SMG_DELETE_LAST_VIRTUAL_DISPLAY 4.15 SMG_DELETE_LAST_VIRTUAL_DISPLAY 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. Arguments: NONE 12 Screen Management System Subroutines ______ __________ ______ ___________ ______ __________ ______ ___________ Screen Management System Subroutines SMG_DELETE_LINES 4.16 SMG_DELETE_LINES 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. Arguments: (L) Start_line Start row position. (L) Number_lines Number of lines to delete. (B) Virtual_display_number SMG_DISP 4.17 SMG_DISP Display a character string at a specified position in a virtual display. Arguments: (S) Character_string Text to display. (L) Row Display row position. (L) Column Display column position. (W) Rendition Bit mask indicating display rendition. See SMG_CHANGE_DEF_ATTR for details. (B) Virtual_display_number SMG_DISP_HIGH_WIDE 4.18 SMG_DISP_HIGH_WIDE Display a character string in double-height double-width characters at a specified position in a virtual display. Arguments: (S) Character_string Text to display. (L) Row Display row position. (L) Column Display column position. (W) Rendition Bit mask indicating display rendition. See SMG_CHANGE_DEF_ATTR for details. (B) Virtual_display_number SMG_DISP_WIDE 4.19 SMG_DISP_WIDE Display a character string in double-width characters at a specified position in a virtual display. Arguments: (S) Character_string Text to display. (L) Row Display row position. (L) Column Display column position. (W) Rendition Bit mask indicating display rendition. See SMG_CHANGE_DEF_ATTR for details. (B) Virtual_display_number 13 Screen Management System Subroutines ______ __________ ______ ___________ ______ __________ ______ ___________ Screen Management System Subroutines SMG_DISP_CLR 4.20 SMG_DISP_CLR Same as SMG_DISP plus clear to end of line after displaying text. SMG_DISP_SCROLL 4.21 SMG_DISP_SCROLL 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. Arguments: (S) Text (B) Direction 0 = Up 1 = Down (W) Rendition Bit mask indicating display rendition. See SMG_CHANGE_DEF_ATTR for details. (B) Virtual_display_number SMG_END_DISPLAY_BATCHING 4.22 SMG_END_DISPLAY_BATCHING Turn off batching for a virtual display. This routine should not be called unless the display has already been pasted. Arguments: (B) Virtual_display_number SMG_END_PB_BATCHING 4.23 SMG_END_PB_BATCHING Turn off batching for the current pasteboard. Arguments: NONE SMG_ERRMSG 4.24 SMG_ERRMSG 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. Arguments: (S) Error_message (B) Video_attributes Display video attributes. See SMG_ADD_VIRTUAL_DISPLAY. 14 Screen Management System Subroutines ______ __________ ______ ___________ ______ __________ ______ ___________ Screen Management System Subroutines SMG_GET_CHAR 4.25 SMG_GET_CHAR 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. Arguments: (L) Row Physical screen row. (L) Column Physical screen column. (B) Character_code ASCII of character at given location. SMG_INPUT 4.26 SMG_INPUT 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. Arguments: (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. (B) Virtual_display_number SMG_INPUT_CLR 4.27 SMG_INPUT_CLR Same as SMG_INPUT plus clear line after input. SMG_INSERT_CHARS 4.28 SMG_INSERT_CHARS 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. Arguments: (S) Insertion_text Characters to be inserted. (L) Row Insertion row. (L) Column Insertion column. (W) Rendition Bit mask indicating display rendition. See SMG_CHANGE_DEF_ATTR for details. (B) Virtual_display_number 15 Screen Management System Subroutines ______ __________ ______ ___________ ______ __________ ______ ___________ Screen Management System Subroutines SMG_INSERT_LINE 4.29 SMG_INSERT_LINE 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. Arguments: (S) Insertion_text Text to be written on the new line. (L) Row Row at which text is inserted. (B) Direction 0 = up 1 = down (W) Rendition Bit mask indicating display rendition. See SMG_CHANGE_DEF_ATTR for details. (B) Virtual_display_number SMG_LABEL_BORDER 4.30 SMG_LABEL_BORDER 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. Arguments: (S) Label Label text. (B) Position_flag 0 = top 1 = bottom 2 = left 3 = right (W) Rendition Bit mask indicating display rendition. See SMG_CHANGE_DEF_ATTR for details. (B) Virtual_display_number SMG_LINE 4.31 SMG_LINE Draw a line on a virtual display. Arguments: (L) Start_row (L) Start_column (L) End_row (L) End_column (W) Rendition Bit mask indicating display rendition. See SMG_CHANGE_DEF_ATTR for details. (B) Virtual_display_number 16 Screen Management System Subroutines ______ __________ ______ ___________ ______ __________ ______ ___________ Screen Management System Subroutines SMG_MOVE_VIRTUAL_DISPLAY 4.32 SMG_MOVE_VIRTUAL_DISPLAY Relocate a virtual display on the pasteboard and preserve the pasting order. Arguments: (L) New_pb_row Pasteboard coordinates at which row 1, (L) New_pb_column column 1 of the virtual display is pasted. (B) Virtual_display_number SMG_ONE_CHAR 4.33 SMG_ONE_CHAR 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. Arguments: (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. (B) Echo_flag 0 = echo input character 1 = do not echo (B) Virtual_display_number SMG_ONE_CHAR_CLR 4.34 SMG_ONE_CHAR_CLR Same as SMG_ONE_CHAR plus clear line after input. SMG_OPEN 4.35 SMG_OPEN 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. Arguments: (S) Paint_character Input routine paint character. (B) Clear_screen_flag 1 = Clear screen 0 = do not clear screen SMG_PASTE 4.36 SMG_PASTE Places a virtual display on the pasteboard, making it visible. Arguments: (L) Pasteboard_row Pasteboard coordinates at which row 1, 17 Screen Management System Subroutines ______ __________ ______ ___________ ______ __________ ______ ___________ Screen Management System Subroutines (L) Pasteboard_column column 1 of the virtual display is pasted. (B) Virtual_display_number SMG_POS 4.37 SMG_POS Position the cursor on a virtual display. Note that this position has NOTHING TO DO with physical screen coordinates. Arguments: (L) Row Virtual display row. (L) Column Virtual display column. (B) Virtual_display_number SMG_POS_CLEAR 4.38 SMG_POS_CLEAR Position the cursor on a virtual display and then clear the line or display as in SMG_CLEAR. Arguments: (L) Row Virtual display row. (L) Column Virtual display column. (B) Entity 0 Clear display 1 Clear line (B) Portion 0 Cursor to end of entity 1 Cursor to beginning of entity 2 Entire entity (B) Virtual_display_number SMG_READ_FROM_DISPLAY 4.39 SMG_READ_FROM_DISPLAY 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. Arguments: (L) Row Virtual display row. (S) Terminator_string List of terminators for "back-searching". (S) Returned string Returned text. (B) Virtual_display_number SMG_REPASTE 4.40 SMG_REPASTE Unpaste and repaste a virtual display on the pasteboard. The pasting order is NOT preserved. Arguments: (L) Pasteboard_row Pasteboard coordinates at which row 1, 18 Screen Management System Subroutines ______ __________ ______ ___________ ______ __________ ______ ___________ Screen Management System Subroutines (L) Pasteboard_column column 1 of the virtual display is pasted. (B) Virtual_display_number SMG_RESTORE_SCREEN 4.41 SMG_RESTORE_SCREEN 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. Arguments: NONE SMG_RETURN_CURSOR_POSITION 4.42 SMG_RETURN_CURSOR_POSITION Return the cursor coordinates in a virtual display. Arguments: (L) Row Virtual display (L) Column cursor coordinates. (B) Virtual_display_number SMG_SAVE_SCREEN 4.43 SMG_SAVE_SCREEN 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. Arguments: NONE SMG_SCROLL 4.44 SMG_SCROLL 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. Arguments: (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. (B) Direction 0 = up 1 = down 2 = left 3 = right (L) Number_of_lines Number of lines or columns to scroll (B) Virtual_display_number 19 Screen Management System Subroutines ______ __________ ______ ___________ ______ __________ ______ ___________ Screen Management System Subroutines SMG_SET_KP_MODE 4.45 SMG_SET_KP_MODE Set the current keyboard's keypad to either numeric or applications mode. Arguments: (B) New_mode 0 = numeric mode 1 = applications mode SMG_SET_SCROLL 4.46 SMG_SET_SCROLL Set the scrolling region in a virtual display. Arguments: (L) Top_row Top row of the scrolling region. (L) Bottom_row Bottom row of the scrolling region. (B) Virtual_display_number SMG_SWITCH_PASTEBOARDS 4.47 SMG_SWITCH_PASTEBOARDS 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. Arguments: (B) 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. SMG_TITLE 4.48 SMG_TITLE 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. Arguments: (S) Title The title text. (B) Virtual_display_number 20 Screen Management System Subroutines ______ __________ ______ ___________ ______ __________ ______ ___________ Screen Management System Subroutines SMG_UNPASTE 4.49 SMG_UNPASTE Remove a virtual display from a pasteboard, thus removing it from the terminal screen. The virtual display itself is not altered in any way. Arguments: (B) Virtual_display_number FUNCTIONS _________ _________ 5 FUNCTIONS SMG_YES_NO 5.1 SMG_YES_NO 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. VERY IMPORTANT: ____ __________ ____ __________ 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 ALWAYS should ALWAYS check this when handling the default response. Function value: BYTE Will be either true (-1) or false (0). Arguments: (S) Prompt_string Prompt string. (L) Row Prompt string row position. (L) Column Prompt string column position. (B) Default_response Boolean true or false (-1 or 0). (L) Timeout Timeout value in seconds. (B) Virtual_display_number 21