CP/M

home *** CD-ROM | disk | FTP | other *** search

/ CP/M / CPM_CDROM.iso / lambda / soundpot / p / windoman.lbr / WINDOW.DZC / WINDOW.DOC

Wrap

Text File | 1993-10-25 | 76.8 KB | 4,884 lines

Window Management Services Version 1.0 User's Guide Window Management Services Version 1.0 User's Guide (c) Copyright 1984 Timothy E. Ide - All rights reserved Turbo Pascal is a trademark of Borland International, Inc. Kaypro II is a trademark of Kaypro Corporation. Perfect Writer is a trademark of Perfect Software, Inc. Window Management Services Version 1.0 Table of Contents Chapter 1 Introduction 1 Chapter 2 Windows 2 2.1 Definition 2 2.2 Attributes 2 2.2.1 Number 3 2.2.2 Origin 3 2.2.3 Width 3 2.2.4 Height 3 2.2.5 Border 4 2.2.6 Columns 4 2.2.7 Rows 4 2.2.8 Contents 4 2.3 Window Control Block 5 Chapter 3 Window Management 6 3.1 Creating and deleting windows 6 3.1.1 Opening windows 6 3.1.2 Closing windows 6 3.2 Modifying window position 7 3.2.1 Setting position to Home 7 3.2.2 Setting position to column and row 7 3.2.3 Retrieving window position 7 3.3 Modifying the window origin 7 3.3.1 Setting window origin 8 3.3.2 Retrieving window origin 8 3.4 Modifying window contents 8 3.4.1 Clearing window contents 8 3.4.2 Inserting window lines 8 3.4.3 Deleting window lines 9 3.4.4 Clearing to end of line 9 3.4.5 Changing the border 9 Window Management Services Version 1.0 3.5 Window output 9 3.5.1 Storing character strings 10 3.5.2 Writing character strings 10 3.5.3 Displaying window contents 11 3.5.4 Erasing window areas 11 3.6 Window input 11 3.6.1 Retrieving character strings 12 3.6.2 Reading character strings 12 3.7 Status variables 13 3.7.1 wi_status - service success status 13 3.7.2 wi_eoln - end of line 14 3.7.3 wi_eow - end of window 14 Chapter 4 Using the services 15 4.1 Including the services 15 4.2 Naming conventions 15 4.3 Memory requirements 15 4.4 Demonstration program 16 Chapter 5 The Services 17 5.1 User services 17 5.1.1 wi_open - create window 19 5.1.2 wi_close - delete window 21 5.1.3 wi_insln - insert line 22 5.1.4 wi_delln - delete line 23 5.1.5 wi_clreol - clear to end of line 24 5.1.6 wi_clear - clear window 25 5.1.7 wi_home - set position to home 26 5.1.8 wi_border - set window border 27 5.1.9 wi_setpos - set position 28 5.1.10 wi_getpos - get position 29 5.1.11 wi_setorg - set origin 30 5.1.12 wi_getorg - get origin 31 5.1.13 wi_put - store character string 32 5.1.14 wi_putln - store character string 34 5.1.15 wi_get - retrieve character string 36 5.1.16 wi_getln - retrieve character string 38 5.1.17 wi_write - write character string through window 40 5.1.18 wi_writeln - write character string Window Management Services Version 1.0 through window 42 5.1.19 wi_read - read character string through window 44 5.1.20 wi_readln - read character string through window 46 5.1.21 wi_show - display window on screen 48 5.1.22 wi_erase - erase window area on screen 49 5.2 Internal Services 50 5.2.1 _wi_find - find window control block 51 5.2.2 _wi_stb - build a character string 52 5.2.3 _wi_bord1 - store window border 53 5.2.4 _wi_bord2 - store border in window 55 5.2.5 _wi_out - store string in window; optionally, write to screen 56 5.2.6 _wi_outln - store string in window; optionally, write to screen, advance position to next line 58 5.2.7 _wi_inp - retrieve string from window; optionally, read string from keyboard 60 5.2.8 _wi_inpln - retrieve string from window; optionally, read string from keyboard, advance position to next line 62 5.2.9 _wi_getst - get string from keyboard 64 5.2.10 _wi_sher - display on or erase window from screen 66 Window Management Services Version 1.0 Chapter 1 Introduction Window Management Services are a group of software tools for terminal screen management developed for use with Turbo Pascal Version 2.0 on a Kaypro II micro-computer system. The Window Management Services were developed as an experiment in screen manipulation tool development and as a Turbo Pascal learning exercise. (This document is the result of an experiment into the capabilities of Perfect Writer). A demonstration program is provided that supports interactive experimentation with the services. The demonstration program was used to verify the functioning of each of the services. The potential user is warned that problems may still exist and that the prudent user will verify that each of the services that he or she may want to use is suitable for the intended application. Although development was on and for a Kaypro II, the services are coded to use the screen manipulation functions of Turbo Pascal and may be expected to run on any system that supports Turbo Pascal screen manipulation functions. Since the Kaypro II used for development does not support advanced video features (e.g. half-intensity, inverse video), neither do the Window Management Services. Chapter 2 describes the windows managed by the services. Chapter 3 discusses the operations on windows supported by the Window Management Services. Chapter 4 provides information on using the services and describes the demonstration program. Chapter 5 documents the user interface to and the operation of each of the services. - 1 - Window Management Services Version 1.0 Chapter 2 Windows 2.1 Definition Windows managed by the Window Management Services are probably best defined as virtual terminal screens which may be displayed at any position on the screen of a video display terminal. 2.2 Attributes A window is described by several attributes: - Number - Origin - Width - Height - Border - Contents - Columns - Rows - 2 - Window Management Services Version 1.0 Each of these attributes is discussed below. 2.2.1 Number A window number is a user assigned value (0-255) that uniquely identifies a window to the Window Management Services. The window number is a required input argument to each service. 2.2.2 Origin The window origin is the screen position of the top-left corner of the window. The origin is expressed as screen column and row numbers. The window origin must be specified when the window is created. Subsequently, the window origin may be changed and retrieved. Screen column and row numbers need not specify an actual screen position. The window may be positioned completely or partially on or off the terminal display screen. Of course, if a window is positioned such that no part of it could appear on the screen, the window contents cannot be displayed. 2.2.3 Width The window width is the horizontal dimension of a window expressed in number of screen columns or line length. The width is defined when a window is created and cannot be changed. The Window Management Services permit a window width in the range 1 through 80. 2.2.4 Height - 3 - Window Management Services Version 1.0 The window height is the vertical dimension of a window expressed in number of rows or lines. The height is defined when a window is created and cannot be changed. The Window Management Services require window height to be defined in the range 1 through 23. 2.2.5 Border The window border is optionally specified when a window is created. A window border is one character wide. It is selected by specifying a 1 to 4 character string that defines the contents of the window border when the window is created. The border characters (which may be spaces) fill the top and bottom rows and the left and right columns of the window. The window border characters may be changed. However, a border cannot be added or removed from a window after it is created. 2.2.6 Columns The columns attribute is the number of accessible columns available for character storage. When a window is created without a border, columns equals width. If a window is created with a border, columns equals width minus 2. 2.2.7 Rows The rows attribute is the number of accessible rows available for character storage. When a window is created without a border, rows equals height. If a window is created with a border, rows equals height minus 2. 2.2.8 Contents - 4 - Window Management Services Version 1.0 A content storage array is maintained for each window. The array contains window height times window width characters. The optional window border, when selected, is stored in the content array. Although the window border is stored as window contents, the border is transparent to the window content manipulation services. The only impact that the window border has on the window content is the reduction of the user accessible window area. The majority of the Window Management Services support manipulation of window contents. 2.3 Window Control Block For each window, the Window Management Services create and maintain a Window Control Block in dynamic memory. Since windows may vary in size, the window control block is also variable length. The memory allocated to store a window control block is de-allocated when the window is deleted. Each of the window attributes described above is stored in the window control block. In addition, other control information required by the Window Management Services is also stored in the window control block. - 5 - Window Management Services Version 1.0 Chapter 3 Window Management 3.1 Creating and deleting windows The first operation that may be performed on a window is window creation. When a window is no longer required it may be deleted. 3.1.1 Opening windows The open service, wi_open, creates a window. When the window is created it must be assigned an unique identification number. The window origin, height, and width must be specified. The window border may be specified. A window control block is allocated for the window. The window position is set to window home: window column 1 and row 1. The window contents are cleared to spaces. 3.1.2 Closing windows The close service, wi_close, deletes a previously opened window. Memory allocated for the window control block when the window was opened is de-allocated. The window number may be re-used. - 6 - Window Management Services Version 1.0 3.2 Modifying window position For each window, a window position or "cursor" is maintained in the window control block. The window position may be set and retrieved. 3.2.1 Setting position to Home The home window position service, wi_home, sets the window position to window column 1 and row 1. 3.2.2 Setting position to column and row The set window position service, wi_setpos, sets the window to a specified window column and row. The specified row and column may not exceed the accessible window width and height, respectively. 3.2.3 Retrieving window position The get window position service, wi_getpos, retrieves the window position column and row. 3.3 Modifying the window origin A screen origin column and row is maintained in each window control block. The window origin must be specified when the window is created. The window origin may subsequently be set and retrieved. - 7 - Window Management Services Version 1.0 3.3.1 Setting window origin The set window origin service, wi_setorg, sets the window screen origin to a screen origin column and row. The screen origin value may be set to values outside of the actual screen boundaries to move the window partially or completely off the screen. 3.3.2 Retrieving window origin The get window origin service, wi_getorg, retrieves the current window origin display screen column and row. 3.4 Modifying window contents The contents of a window are maintained in the window control block. Window contents are set to spaces when the window is opened. Many services are available to manipulate window contents. 3.4.1 Clearing window contents The clear window service, wi_clear, clears the window contents to spaces and sets the window position to home. 3.4.2 Inserting window lines The insert window line service, wi_insln, inserts a blank line at the indicated window row. The contents of the indicated row and following rows except for the last are shifted down one line. The last window row is deleted. - 8 - Window Management Services Version 1.0 When the row indicated for insertion is greater than the number of accessible rows in the window, all window rows are shifted up 1 line. The top row is deleted. A blank line is inserted on the bottom accessible row of the window. The window position is set to the beginning of the inserted line. 3.4.3 Deleting window lines The delete window line service, wi_delln, deletes a window line in the indicated window row. Lines below the deleted line are shifted up one row. A blank line is inserted in the last row of the window. The window position is set to the beginning of the deleted row. 3.4.4 Clearing to end of line The clear to end of window line service, wi_clreol, replaces the contents of the current window row with spaces from the current window column to the end of the row. The window position is not modified. 3.4.5 Changing the border The set window border service, wi_border, sets the contents of the window border. The contents of the window are unchanged. This service will operate only on windows originally created with borders. 3.5 Window output The following output services support storing of character strings to windows, writing of character strings through windows, displaying window contents on the terminal screen, and erasing window areas from the screen. - 9 - Window Management Services Version 1.0 3.5.1 Storing character strings The two put character string services, wi_put and wi_putln, store character strings into a window beginning at the current window position. When end of line is reached before all characters of a string are stored, the remaining string characters are ignored. The wi_put and wi_putln services differ in the way in which they modify window position. wi_put sets the window position to the next character following the stored string. When the last character of the stored string is the last column in the row, wi_put sets the window position to the first column of the next row. wi_putln sets the window position to the first column of the row following the row containing the stored string. Window position is set to end of window after wi_put stores a character in the last column of the last window row and after wi_putln stores a character string in the last row. When window position is at end of window and either the wi_put or wi_putln services are invoked, the window is scrolled by deleting the first row of the window, shifting the remaining lines up one row, and storing blanks into the bottom row of the window, before storing the string in that row. 3.5.2 Writing character strings The two write character string services, wi_write and wi_writeln, store character strings into a window beginning at the current window position and write the character strings to the display screen. The output position of the character string on the screen is the sum of the window origin and the window position minus one on each dimension. When a computed output position for a character falls outside the boundaries of the display screen, the character is stored in the window, but not displayed. - 10 - Window Management Services Version 1.0 The wi_write and wi_writeln services differ in way in which they modify window position. wi_write sets the window position to the next character following the stored string. When the last character of the stored string is the last column in the row, wi_write sets the window position to the first column of the next row. wi_writeln sets the window position to the first column of the row following the row containing the stored string. Window position is set to end of window after wi_write stores a character in the last column of the last window row and after wi_writeln stores a character string in the last row. When window position is at end of window and either the wi_write or wi_writeln services is invoked, the window is scrolled by deleting the first row of the window, shifting the remaining lines up on line, and storing blanks into the bottom row of the window, before the string is stored into that row and written to the screen. 3.5.3 Displaying window contents The show window content service, wi_show, writes the contents of a window to the terminal display screen. Only that portion of the window which falls within the screen boundaries is displayed. 3.5.4 Erasing window areas The erase window area service, wi_erase, erases that portion of the display screen on which a given window could be displayed. 3.6 Window input - 11 - Window Management Services Version 1.0 The following input services support retrieving of character strings from windows and reading of character strings from the keyboard through windows. 3.6.1 Retrieving character strings The two get character string services, wi_get and wi_getln support the retrieval of character strings from a window beginning at the current window position. When end of line is reached before all characters of a string are retrieved, the remaining string characters are ignored. The wi_get and wi_getln services differ in way in which they modify window position. wi_get sets the window position to the next character following the stored string. When the last character of the stored string is the last column in the row, wi_get sets the window position to the first column of the next row. wi_getln sets the window position to the first column of the row following the row containing the retrieved string. Window position is set to end of window after wi_get retrieves a character in the last column of the last window row and after wi_getln retrieves a character string in the last row. When window position is at end of window and either the wi_get or wi_getln service is invoked, the retrieval is not performed and the services return a failure status. 3.6.2 Reading character strings The read character string services, wi_read and wi_readln read a character string from the keyboard, store the input character string in the window, and retrieve the stored string. The input position of the character string on the screen is the sum of the window origin and the window position minus one for each dimension. These services do not perform any input through a window that cannot be fully displayed on the terminal display screen as indicated by its screen origin and dimensions. - 12 - Window Management Services Version 1.0 Character string input is read character by character until terminated by a carriage return. The services will not accept input past end of line or end of string. The delete and backspace keys may be used to delete previously keyed string characters. It is not possible to delete past beginning of string. The wi_read and wi_readln services differ in way in which they modify window position. wi_read sets the window position to the next character following the stored string. When the last character of the stored string is the last column in the row, wi_read sets the window position to the first column of the next row. wi_readln sets the window position to the first column of the row following the row containing the stored string. Window position is set to end of window after wi_read reads a character into the last column of the last window row and after wi_readln reads a character string into the last row. When window position is at end of window and either the wi_read or wi_readln services is invoked, the read is not performed and the services return a failure status. 3.7 Status variables The Window Management Services communicate status to user programs through three boolean status variables: - wi_status - wi_eoln - wi_eow 3.7.1 wi_status - service success status The wi_status variable is set by each of the user service - 13 - Window Management Services Version 1.0 procedures to indicate the success or failure of the service. A true value indicates success. False indicates failure. 3.7.2 wi_eoln - end of line wi_eoln is set to true when end of window line is encountered during an input or output service. wi_eoln is set or reset only by the wi_put, wi_putln, wi_write, wi_writeln, wi_get, wi_getln, wi_read, and wi_readln services. 3.7.3 wi_eow - end of window wi_eow is set to true when end of window is encountered during an input or output service. When wi_eow is true, wi_eoln is also true. wi_eow is set or reset only by the wi_put, wi_putln, wi_write, wi_writeln, wi_get, wi_getln, wi_read, and wi_readln services. - 14 - Window Management Services Version 1.0 Chapter 4 Using the services 4.1 Including the services The file WINDOW.PAS contains the Turbo Pascal Version 2.0 source code for the Window Management Services. Turbo Pascal programs that use the services must include WINDOW.PAS. The Turbo Pascal compiler directive to include the Window Management Services is {$I WINDOW.PAS}. 4.2 Naming conventions To avoid naming conflicts with the programs that use the window management services, global procedure names begin "wi_" for user services and "_wi" for internal services; global variable names begin "wi_" for user variables and "_w" for global variables required by the internal services. 4.3 Memory requirements The Window Management Services require a little less than 7K - 15 - Window Management Services Version 1.0 bytes of memory for code and static data structures. Dynamic memory is allocated for a window control block when a window is created and de-allocated when a window is closed. Window control block memory requirements vary depending on the size of the window. A window control block requires 80 bytes plus the product of the window width times the window height. Memory requirements may be reduced by using the Turbo Pascal Version 2.0 overlay feature. Several services which may be handled as overlays are identified with commented overlay procedure definitions in WINDOW.PAS. Memory requirements can be further reduced by deleting source code for unused services from a copy of WINDOW.PAS and compiling only those services that are actually used. 4.4 Demonstration program The files DEMO.PAS, DEMO1.PAS, and DEMO2.PAS contain source for a Window Management Services demonstration program. The demonstration is menu driven and supports execution of each of the user services. Two additional options support clearing the screen and exiting from the program. The demonstration program must be compiled with the "Com-file" compiler option. The demonstration program permits a user to experiment with the services without having to write programs to try them out. Since the demonstration program uses the Window Management Services extensively to implement terminal screen input and output, the Turbo Pascal source code in DEMO.PAS, DEMO1.PAS and DEMO2.PAS also provides programming examples. - 16 - Window Management Services Version 1.0 Chapter 5 The Services This chapter contains descriptions of each of the user and internal Window Management Services. Each service is described by its procedure or function header, input arguments, output arguments, action, and status settings. 5.1 User services The following sections describe the Window Management Services that support window creation, deletion, and manipulation: - wi_open - create window - wi_close - delete window - wi_insln - insert line - wi_delln - delete line - wi_clreol - clear to end of line - wi_clear - clear window - wi_home - set position to home - wi_border - set window border - wi_setpos - set position - wi_getpos - get position - wi_setorg - set origin - 17 - Window Management Services Version 1.0 - wi_getorg - get origin - wi_put - store character string - wi_putln - store character string, advance position to next line - wi_get - retrieve character string - wi_getln - retrieve character string, advance position to next line - wi_write - write character string through window - wi_writeln - write character string through window, advance position to next line - wi_read - read character string through window - wi_readln - read character string through window, advance position to next line - wi_show - display window on screen - wi_erase - erase window area on screen - 18 - Window Management Services Version 1.0 5.1.1 wi_open - create window procedure wi_open (window_number, origin_column, origin_row, window_width, window_height : integer; border_chars : string[4]); Input arguments: window_number - User assigned window identification number origin_column - Display screen column to contain left column of window origin_row - Display screen row to contain top row of window window_width - The window width expressed as number of columns window_height - The window height expressed as number of rows border_chars - Window border character string Output arguments: None Action: If window_width and window_height are within range and window_number is unique, the service attempts to allocate dynamic memory for a window control block. If sufficient dynamic memory is not available to allocate a window control block, a Turbo Pascal run-time error results. The service initializes the window control block to specified input values. Window contents are - 19 - Window Management Services Version 1.0 cleared. The window border, if specified, is stored. Status: wi_status - True if operation successful. False if window_width or window_height out of range, or if window control block with the same window_number exists. - 20 - Window Management Services Version 1.0 5.1.2 wi_close - delete window procedure wi_close (window_number : integer); Input arguments: window_number - Window identification number Output arguments: None Action: If the window is open, the service de-allocates the dynamic memory required to store the window control block. Status: wi_status - True if close operation is successful. False if window is not open. - 21 - Window Management Services Version 1.0 5.1.3 wi_insln - insert line procedure wi_insln (window_number, window_row : integer); Input arguments: window_number - Window identification number window_row - Window row number for line insert Output arguments: None Action: If the window is open and window_row is in range, the window line at window_row and following lines are shifted down one row. The last user accessible line in the window is deleted. A blank line is inserted into the window at window_row. Window position is set to the first column of window_row. The window border, if present, is unchanged. If the window is open and window_row is greater than the number of accessible rows, window lines are shifted up one row. The top user accessible line in the window is deleted. A blank line is inserted into the window on the last user accessible row. Window position is set to the first column of the inserted row. The window border, if present, is unchanged. Status: wi_status - False if window is not open or window_row is less than 1; otherwise, true. - 22 - Window Management Services Version 1.0 5.1.4 wi_delln - delete line procedure wi_delln (window_number, window_row : integer); Input arguments: window_number - Window identification number window_row - Window row number for line delete Output arguments: None Action: If the window is open and window_row is within range, the window line at window_row is deleted and following rows are shifted up one row. A blank line is inserted at the bottom of the window. Window position is set to the beginning of window_row. The window border, if present, is unchanged. Status: wi_status - False if window is not open or window_row is out of range; otherwise, true. - 23 - Window Management Services Version 1.0 5.1.5 wi_clreol - clear to end of line procedure wi_clreol (window_number : integer); Input arguments: window_number - Window identification number Output arguments: None Action: If the window is open and window position is not at end of window, window content from current window position to end of row is set to spaces. Window position is not modified. Status: wi_status - False if window is not open of window position is at end of window when service is invoked; otherwise, true. - 24 - Window Management Services Version 1.0 5.1.6 wi_clear - clear window procedure wi_clear (window_number : integer); Input arguments: window_number - Window identification number Output arguments: None Action: If the window is open, window contents are set to spaces. The window border is restored. Window position is set to home: window column 1, row 1. Status: wi_status - False if window is not open; otherwise, true. - 25 - Window Management Services Version 1.0 5.1.7 wi_home - set position to home procedure wi_home (window_number : integer); Input arguments: window_number - Window identification number Output arguments: None Action: Window position is set to home: window column 1, row 1. Status: wi_status - False if window is not open; otherwise, true. - 26 - Window Management Services Version 1.0 5.1.8 wi_border - set window border procedure wi_border (window_number : integer, border_chars : string[4]); Input arguments: window_number - Window identification number border_chars - Window border character string Output arguments: None Action: If window is open and a window border was selected when the window was created, the border_chars window border is stored in the window control block. Status: wi_status - False if window is not open or was not opened with window border selected; otherwise, true. - 27 - Window Management Services Version 1.0 5.1.9 wi_setpos - set position procedure wi_setpos (window_number, window_column, window_row : integer); Input arguments: window_number - Window identification number window_column - Window column number window_row - Window row number Output arguments: None Action: If the window is open and if window_column and window_row are in range, window position is set to window_column and window_row. Status: wi_status - False if window is not open or window_row or window_column are out of range; otherwise, true. - 28 - Window Management Services Version 1.0 5.1.10 wi_getpos - get position procedure wi_getpos (window_number, var window_column, window_row : integer); Input arguments: window_number - Window identification number Output arguments: window_column - Window column number window_row - Window row number Action: If the window is open, the current window position column and row values are returned in window_column and window_row. Note that window_column and window_row may point to end of window: one row greater than the last accessible window row. Status: wi_status - False if window is not open or window_row or window_column are out of range; otherwise, true. - 29 - Window Management Services Version 1.0 5.1.11 wi_setorg - set origin procedure wi_setorg (window_number, screen_column, screen_row : integer); Input arguments: window_number - Window identification number screen_column - Screen column number screen_row - Screen row number Output arguments: None Action: If window is open and screen_column and screen_row are valid, the window origin column and origin row are set to screen_column and screen_row, respectively. Status: wi_status - False if window is not open or screen_row or screen_column are not in range; otherwise, true. - 30 - Window Management Services Version 1.0 5.1.12 wi_getorg - get origin procedure wi_getorg (window_number, var screen_column, screen_row : integer); Input arguments: window_number - Window identification number Output arguments: screen_column - Screen column number screen_row - Screen row number Action: If the window is open, the current window origin column and origin row values are returned in screen_ column and screen_row, respectively. Status: wi_status - False if window is not open; otherwise, true. - 31 - Window Management Services Version 1.0 5.1.13 wi_put - store character string procedure wi_put (window_number : integer; output_string : string[80]); Input arguments: window_number - Window identification number output_string - Output character string Output arguments: None Action: If the window is open, output_string is stored in the window content array at the current window position. As many characters as fit on the current window row up to the length of output_string are stored; remaining characters are ignored. wi_eoln is set to true whenever window position is advanced past end of row. wi_eow is set to true whenever window position is advanced to end of window. If at entry, window position is at end of window, the window is scrolled by deleting the first row, shifting the remaining rows up one row, and storing blanks into the bottom row. Window position is set to the first column of the bottom row. At exit, window position is set to the next character within the window following the last character of the output string. When the last character of the output string is the last column in the row, window position is set to the first column of the next row and wi_eoln is set to true. wi_eow is set to true when the next row is greater than the maximum number of accessible rows in the window. - 32 - Window Management Services Version 1.0 Status: wi_status - False if window is not open; otherwise, true. wi_eoln - True if end of row is encountered while storing output_string; otherwise, true. wi_eow - True if window position is advanced to end of window; otherwise, false. - 33 - Window Management Services Version 1.0 5.1.14 wi_putln - store character string procedure wi_putln (window_number : integer; output_string : string[80]); Input arguments: window_number - Window identification number output_string - Output character string Output arguments: None Action: If the window is open, output_string is stored in the window content array at the current window position. As many characters as fit on the current window row up to the length of output_string are stored; remaining characters are ignored. If at entry, window position is at end of window, the window is scrolled by deleting the first row, shifting the remaining rows up one row, and storing blanks into the bottom row. Window position is set to the first column of the bottom row. At exit, window position is set to the beginning of the next window row. wi_eoln is set to true. wi_eow is set to true if next row is beyond the last accessible row in the window. Status: wi_status - False if window is not open; otherwise, true. - 34 - Window Management Services Version 1.0 wi_eoln - True wi_eow - True if window position is advanced to end of window; otherwise, false. - 35 - Window Management Services Version 1.0 5.1.15 wi_get - retrieve character string procedure wi_get (window_number, input_length : integer; var input_string : string[80]); Input arguments: window_number - Window identification number input_length - Input string maximum length Output arguments: input_string - Input character string Action: If the window is open, an input_string of length input_length is retrieved from the window content array beginning at the current window position. If end of row is encountered before retrieving input_length characters, input_string is truncated. wi_eoln is set to true whenever window position is advanced past end of row. wi_eow is set to true whenever window position is advanced to end of window. At exit, window position is set to the next character within the window following the last character of the output string. When the last character of the output string is the last column in the row, window position is set to the first column of the next row and wi_eoln is set to true. wi_eow is set to true when the next row is greater than the maximum number of accessible rows in the window. Status: - 36 - Window Management Services Version 1.0 wi_status - False if window is not open or if at entry window position is at end of window; otherwise, true. wi_eoln - True if end of row is encountered while retrieving input_string; otherwise, false. wi_eow - True if window position is advanced to end of window; otherwise, false. - 37 - Window Management Services Version 1.0 5.1.16 wi_getln - retrieve character string procedure wi_getln (window_number, input_length : integer; var input_string : string[80]); Input arguments: window_number - Window identification number input_length - Input string maximum length Output arguments: input_string - Input character string Action: This service is similar to wi_get, differing only in the manner of setting window position at end of retrieval. If the window is open, an input string of length input_length is retrieved from the window content array beginning at the current window position. If end of row is encountered before retrieving input_length characters, input_string is truncated. At exit, window position is set to the beginning of the next window row. wi_eoln is set to true. wi_eow is set to true when next row is beyond the last accessible row in the window. Status: wi_status - False if window is not open or if at entry window position is at end of window; otherwise, true. - 38 - Window Management Services Version 1.0 wi_eoln - True wi_eow - True if window position is advanced to end of window; otherwise, false. - 39 - Window Management Services Version 1.0 5.1.17 wi_write - write character string through window procedure wi_write (window_number : integer; output_string : string[80]); Input arguments: window_number - Window identification number output_string - Output character string Output arguments: None Action: If the window is open, output_string is stored in the window content array at the current window position and written to the terminal display screen. As many characters as fit on the current window row up to the length of output_length are stored; remaining characters are ignored. The beginning position of output_string on the terminal display screen is window position plus screen origin minus one for each dimension. When the computed screen position for a character falls outside the boundaries of the display screen, the character is not displayed. If at entry, window position is at end of window, the window is scrolled by deleting the first row, shifting the remaining rows up one row, and storing blanks into the bottom row. Window position is set to the first column of the bottom row. At exit, window position is set to the next character within the window following the last character of the output string. When the last character of the output string is the last column in the row, window position is set to the first column of the next row and wi_eoln - 40 - Window Management Services Version 1.0 is set to true. wi_eow is set to true when the next row is greater than the maximum number of accessible rows in the window. Status: wi_status - False if window is not open; otherwise, true. wi_eoln - True if end of row is encountered while storing output_string; otherwise, false. wi_eow - True if window position is advanced to end of window; otherwise, false. - 41 - Window Management Services Version 1.0 5.1.18 wi_writeln - write character string through window procedure wi_writeln (window_number : integer; output_string : string[80]); Input arguments: window_number - Window identification number output_string - Output character string Output arguments: None Action: This service is similar to wi_out, differing only in the manner of setting window position at end of output. If the window is open, output_string is stored in the window content array at the current window position and written to the terminal display screen. As many characters as fit on the current window row up to the length of output_length are stored; remaining characters are ignored. The beginning position of output_string on the terminal display screen is window position plus screen origin minus one for each dimension. When the computed screen position for a character falls outside the boundaries of the display screen, the character is not displayed. If at entry, window position is at end of window, the window is scrolled by deleting the first row, shifting the remaining rows up one row, and storing blanks into the bottom row. Window position is set to the first column of the bottom row. At exit, window position is set to the beginning of the - 42 - Window Management Services Version 1.0 next window row. wi_eoln is set to true. wi_eow is set to true when next row is beyond the last accessible row in the window. Status: wi_status - False if window is not open; otherwise, true. wi_eoln - True wi_eow - True if window position is advanced to end of window; otherwise, false. - 43 - Window Management Services Version 1.0 5.1.19 wi_read - read character string through window procedure wi_read (window_number, input_length : integer; var input_string : string[80]); Input arguments: window_number - Window identification number input_length - Input string maximum length Output arguments: input_string - Input character string Action: If the window is open, window position is not at end of window, and the window origin values permit the window to be displayed on the terminal screen, a character string of input_length characters is read from the keyboard, stored in the window content array, and returned in input_string. Character string input is read character by character until terminated by a carriage return. The service will not accept input, other than a return, past end of line or end of string. The delete and backspace keys may be used to delete previously keyed string characters. It is not possible to delete past beginning of string. At exit, window position is set to the next character within the window following the last character of the input string. When the last character of the input string is the last column in the row, window position is set to the first column of the next row and wi_eoln is set to true. wi_eow is set to true when the next row is greater than the maximum number of accessible rows in the window. - 44 - Window Management Services Version 1.0 Status: wi_status - False if window is not open or if at entry window position is at end of window; otherwise, true. wi_eoln - True if end of row is encountered while storing input_string; otherwise, false. wi_eow - True if window position is advanced to end of window; otherwise, false. - 45 - Window Management Services Version 1.0 5.1.20 wi_readln - read character string through window procedure wi_readln (window_number, input_length : integer; var input_string : string[80]); Input arguments: window_number - Window identification number input_length - Input string maximum length Output arguments: input_string - Input character string Action: This service is similar to wi_read, differing only in the manner of setting window position at end of read. If the window is open, window position is not at end of window, and the window origin values permit the window to be displayed on the terminal screen, a character string of input_length characters is read from the keyboard, stored in the window content array, and returned in input_string. Character string input is read character by character until terminated by a carriage return. The service will not accept input, other than a return, past end of line or end of string. The delete and backspace keys may be used to delete previously keyed string characters. It is not possible to delete past beginning of string. At exit, window position is set to the first character of the row following the row containing the input string. wi_eoln is set to true. wi_eow is set to true when the next row is greater than the maximum number of accessible rows in the window. - 46 - Window Management Services Version 1.0 Status: wi_status - False if window is not open or if at entry window position is at end of window; otherwise, true. wi_eoln - True if end of row is encountered while storing input_string; otherwise, false. wi_eow - True if window position is advance to end of window; otherwise, false. - 47 - Window Management Services Version 1.0 5.1.21 wi_show - display window on screen procedure wi_show (window_number : integer); Input arguments: window_number - Window identification number Output arguments: None Action: If the window is open, the service attempts to display the window contents on the terminal screen. However, since it is possible to set the window origin column and row such that the window is completely outside of the terminal display screen boundaries, this service may have no visible effect. Status: wi_status - False if window is not open; otherwise, true. - 48 - Window Management Services Version 1.0 5.1.22 wi_erase - erase window area on screen procedure wi_erase (window_number : integer); Input arguments: window_number - Window identification number Output arguments: None Action: If the window is open, that portion of the terminal screen onto which the window maps is set to spaces. Since it is possible to set the window origin row and column such that the window is completely outside of the terminal display screen boundaries, this service may have no visible effect. Status: wi_status - False if window is not open; otherwise, true. - 49 - Window Management Services Version 1.0 5.2 Internal Services The following sections describe the Window Management Services internal services which support many of the user services described in the previous sections: - _wi_find - find window control block - _wi_stb - build a character string - _wi_bord1 - store window border - _wi_bord2 - store border in window - _wi_out - store string in window; optionally, write to screen - _wi_outln - store string in window; optionally, write to screen; advance position to next line - _wi_inp - retrieve string from window; optionally, read string from keyboard - _wi_inpln - retrieve string from window; optionally, read string from keyboard; advance position to next line - _wi_getst - get string from keyboard - _wi_sher - display on or erase window from screen - 50 - Window Management Services Version 1.0 5.2.1 _wi_find - find window control block function _wi_find (window_number : integer) : boolean; Input arguments: window_number - Window identification number Output arguments: None Action: This service searches through the list of window control blocks for the control block for the specified window_number. Status: wi_status - False if window is not open; otherwise, true. - 51 - Window Management Services Version 1.0 5.2.2 _wi_stb - build a character string procedure _wi_stb (var first_char; length : integer; var char_string[80]); Input arguments: first_char - the first position of a contiguous string of characters length - the length of the required string Output arguments: char_string - Output character string built by service Action: This internal service formats an output character string of length bytes containing the string of characters beginning at location first_char. Status: None - 52 - Window Management Services Version 1.0 5.2.3 _wi_bord1 - store window border procedure _wi_bord1 (var border_chars : string[4]); Input arguments: border_chars - border character string Output arguments: None Action: This internal service formats and stores a four byte border character string in the current window control block. When border_chars length is 4 bytes, border_chars is stored unchanged. If border_chars is less than 4 bytes, the service stores the following strings in the window control block: - When the length of border_chars is 0, a border string of all spaces is stored. - When the border_chars length is 1 byte, a border string of all border_chars[1] is stored. - When border_chars length is 2 bytes, a string of border_chars[1..2]+border_chars[1..2] is stored. - When the length of border_chars is 3 bytes, a string of border_chars[1..3]+border_chars[2] is stored. Status: None - 53 - Window Management Services Version 1.0 - 54 - Window Management Services Version 1.0 5.2.4 _wi_bord2 - store border in window procedure _wi_bord2; Input arguments: None Output arguments: None Action: This internal service stores the window border in the window content array of the current window control block. The border lines are stored in the following sequence: left column, right column, top row, followed by bottom row. Status: None - 55 - Window Management Services Version 1.0 5.2.5 _wi_out - store string in window; optionally, write to screen procedure _wi_out (var window_number : integer; var output_string : string[80]; output_flag : boolean); Input arguments: window_number - Window identification number Output arguments: None Action: If the window is open, this internal service stores output_string into the window content array at the current window position. As many characters as fit on the current window row up to the length of output_length are stored; remaining characters are ignored. When output_flag is true, the stored output_string characters are also written to the terminal display screen at a screen position beginning at window position plus screen origin minus one for each dimension. When the computed screen position for a character falls outside the boundaries of the display screen, the character is not displayed. If at entry, window position is at end of window, the window is scrolled by deleting the first row, shifting the remaining rows up one row, and storing blanks into the bottom row. Window position is set to the first column of the bottom row. At exit, window position is set to the next character within the window following the last character of the output string. When the last character of the output - 56 - Window Management Services Version 1.0 string is the last column in the row, window position is set to the first column of the next row and wi_eoln is set to true. wi_eow is set to true when the next row is greater than the maximum number of accessible rows in the window. Status: wi_status - False if window is not open; otherwise, true. wi_eoln - True if end of row is encountered while storing output_string; otherwise, false. wi_eow - True if window position is advanced to end of window; otherwise, false. - 57 - Window Management Services Version 1.0 5.2.6 _wi_outln - store string in window; optionally, write to screen, advance position to next line procedure _wi_outln (var window_number; var output_string : string[80]; output_flag : boolean); Input arguments: window_number - Window identification number output_flag - Output select flag Output arguments: output_string - Output character string Action: This service is similar to wi_out, differing only in the manner of setting window position at end of output. If the window is open, this internal service stores output_string into the window content array at the current window position. As many characters as fit on the current window row up to the length of output_length are stored; remaining characters are ignored. When output_flag is true, the stored output_string characters are also written to the terminal display screen at a screen position beginning at window position plus screen origin minus one for each dimension. When the computed screen position for a character falls outside the boundaries of the display screen, the character is not displayed. If at entry, window position is at end of window, the window is scrolled by deleting the first row, shifting the remaining rows up one row, and storing blanks into - 58 - Window Management Services Version 1.0 the bottom row. Window position is set to the first column of the bottom row. At exit, window position is set to the beginning of the next window row. wi_eoln is set to true. wi_eow is also set to true when next row is beyond the last accessible row in the window. Status: wi_status - False if window is not open; otherwise, true. wi_eoln - True wi_eow - True if window position is advanced to end of window; otherwise, false. - 59 - Window Management Services Version 1.0 5.2.7 _wi_inp - retrieve string from window; optionally, read string from keyboard procedure _wi_inp (var window_number, input_length : integer; var input_string : string[80]; input_flag : boolean); Input arguments: window_number - Window identification number input_length - Input string maximum length input_flag - Input source flag Output arguments: input_string - Character string retrieved from window Action: If the window is open, this internal service, when input_flag is true, reads an input string of input_length characters from the keyboard, stores the input string in the window, and returns the string in input_string; or when input_flag is false, retrieves a string of input_length characters from the window. This service does not attempt to read from the keyboard when any portion of the window maps to a position, based on the current values of window origin and position, which falls outside the video display terminal screen. Character string input is read character by character until terminated by a carriage return. The service will not accept input, other than a return, past end of line or end of string. The delete and backspace keys may be used to delete previously keyed string characters. It is not possible to delete past - 60 - Window Management Services Version 1.0 beginning of string. If at entry, window position is set to end of window, input is not attempted and wi_status is set to false. At exit, window position is set to the next character within the window following the last character of the input string. When the last character of the input string is the last column in the row, window position is set to the first column of the next row and sets wi_eoln to true and also set wi_eow to true when the next row is greater than the maximum number of accessible rows in the window. Status: wi_status - False if window is not open or if at entry window position is at end of window; otherwise, true. wi_eoln - True if end of row is encountered while storing input_string; otherwise, false. wi_eow - True if window position is advanced to end of window; otherwise, false. - 61 - Window Management Services Version 1.0 5.2.8 _wi_inpln - retrieve string from window; optionally, read string from keyboard, advance position to next line procedure _wi_inpln (var window_number, input_length : integer; var input_string : string[80]; input_flag : boolean); Input arguments: window_number - Window identification number input_length - Input string maximum length input_flag - Input source flag Output arguments: input_string - Character string retrieved from window Action: This internal service is similar to _wi_inp differing only in the manner of setting window position at end of input. If the window is open, this internal service, when input_flag is true, reads an input string of input_length characters from the keyboard, stores the input string in the window, and returns the string in input_string; or when input_flag is false, retrieves a string of input_length characters from the window. This service does not attempt to read from the keyboard when any portion of the window maps to a position, based on the current values of window origin and position, which falls outside the video display terminal screen. - 62 - Window Management Services Version 1.0 Character string input is read character by character until terminated by a carriage return. The service will not accept input, other than a return, past end of line or end of string. The delete and backspace keys may be used to delete previously keyed characters. It is not possible to delete past beginning of string. At exit, window position is set to the first character of the row following the row containing the input string. wi_eoln is set to true. wi_eow is also set to true when the next row is greater than the maximum number of accessible rows in the window. Status: wi_status - False if window is not open or if at entry window position is at end of window; otherwise, true. wi_eoln - True if end of row is encountered while storing input_string; otherwise, false. wi_eow - True if window position is advanced to end of window; otherwise, false. - 63 - Window Management Services Version 1.0 5.2.9 _wi_getst - get string from keyboard procedure _wi_getst (input_length, screen_column, screen_row : integer; var input_string : string[80]); Input arguments: input_length - Input string maximum length screen_column - Screen cursor horizontal position screen_row - Screen cursor vertical position Output arguments: input_string - Character string read from keyboard Action: This internal service reads an input string of length input_length printable characters from the keyboard. Input from the keyboard is character by character. If the character read from the keyboard is 20 hex through 7E hex, the character is stored into input_string and echoed to the terminal display screen. The terminal display begins at the screen position indicated by screen_column and screen_row. If the character read from the keyboard is a delete (7F hex) or backspace (08 hex), the previously entered character is deleted from input_string and erased from the display screen. Character input from the keyboard is terminated by the return key (13 hex). The service writes the bell (07 hex) character to the terminal whenever a delete or backspace is entered as the first character of the input string or when input_length characters have been read or when end of row is reached and the character read from the keyboard - 64 - Window Management Services Version 1.0 is not a return (13 hex). Status: None - 65 - Window Management Services Version 1.0 5.2.10 _wi_sher - display on or erase window from screen procedure _wi_sher (var window_number : integer; show_erase_flag : boolean); Input arguments: window_number - Window identification number show_erase_flag - Show or erase function selector Output arguments: None Action: When the window is open and show_erase_flag is true, this internal service attempts to display the window contents on the terminal screen at a position determined by the currently set values of window origin and position. Only those window contents which map to terminal display screen locations are displayed. When the window is open and show_erase_flag is false, the service attempts to erase, set to spaces, the positions on the terminal display screen that could contain the window contents. The positions are computed from the currently set values of window origin and position. Only those positions which map to terminal display screen locations are cleared. Since window origin column and row values may be set such that no portion of the window contents will map unto the terminal display screen, this service may have no visible effect. Status: wi_status - False if window is not open; otherwise, true. - 66 - Window Management Services Version 1.0 Window Management Services Version 1.0 Index accessible columns 4 accessible rows 4 accessible window area 5 changing the window border 9 clearing to end of line 9 clearing window contents 8 closing windows 6 content array 5 creating windows 6 deleting window lines 9 deleting windows 6 DEMO.PAS 16 DEMO1.PAS 16 DEMO2.PAS 16 demonstration program 16 displaying window contents 11 erasing window areas 11 including WINDOW.PAS 15 inserting window lines 8 internal services 50 memory allocation 16 memory de-allocation 16 memory requirements 15 modifying window contents 8 naming conventions 15 opening windows 6 overlays 16 reading strings 12 retrieving strings 12 retrieving window origin 8 retrieving window position 7 setting window origin 7, 8 setting window position 7, 7 storing strings 10 user services 17 window "cursor" 7 window attributes 2 window border 4 window columns 4 window contents 5 window control block 5 window definition 2 window height 4 window home 7 window input 11, 12, 12 Window Management Services Version 1.0 window number 3 window origin 3 window output 9, 10, 10, 11, 11 window position 7 window rows 4 window status 13 window width 3 WINDOW.PAS 15 wi_border 9, 27 wi_clear 8, 25 wi_close 6, 21 wi_clreol 9, 24 wi_delln 9, 23 wi_eoln 14 wi_eow 14 wi_erase 11, 49 wi_get 12, 36 wi_getln 12, 38 wi_getorg 8, 31 wi_getpos 7, 29 wi_home 7, 26 wi_insln 8, 22 wi_open 6, 19 wi_put 10, 32 wi_putln 10, 34 wi_read 12, 44 wi_readln 12, 46 wi_setorg 8, 30 wi_setpos 7, 28 wi_show 48 wi_status 13 wi_write 10, 40 wi_writeln 10, 42 writing strings 10 _wi_bord1 53 _wi_bord2 55 _wi_find 51 _wi_getst 64 _wi_inp 60 _wi_inpln 62 _wi_out 56 _wi_outln 58 _wi_sher 66 _wi_stb 52