Power-Programmierung

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

/ Power-Programmierung / CD1.mdf / pascal / library / dos / menu / overdriv / topascii.doc < prev next >

Wrap

Text File | 1988-04-24 | 75.1 KB | 1,864 lines

TOP Turbo Overdrive Package A Collection of Turbo Pascal 4.0 Procedures and Functions Version 1.0 (C) Copyright 1988 by Nescatunga Software All Rights Reserved TURBO OVERDRIVE PACKAGE TABLE OF CONTENTS Introduction What is TOP..............................................4 License and Registration.................................5 Registration Fee.........................................6 What's on the TOP Disk...................................6 How to use TOP Units.....................................7 Unit IOSTUFF MoveToScreen.............................................9 MoveFromScreen...........................................9 SaveScreen..............................................11 RestoreScreen...........................................11 SavePartScreen..........................................13 RestorePartScreen.......................................13 SetColor................................................15 WriteSt.................................................17 WriteCh.................................................18 WriteManyCh.............................................19 FillScr.................................................20 ReadFromScr.............................................21 GetCh...................................................22 Border..................................................23 SBorder.................................................23 Beep....................................................23 LineCursor..............................................24 BigCursor...............................................24 HideCursor..............................................25 ShowCursor..............................................25 Unit DIR ShowDir.................................................26 ChangePath..............................................27 PickFile................................................28 Unit GETCOLOR ChooseColor.............................................29 SetChooseColor..........................................29 Unit POPASCII ChooseASCII.............................................30 SetChooseASCII..........................................30 Unit GETLINE GetStr..................................................31 Unit DRAWBOX Box.....................................................33 Unit MENUBOX SetMenuBox..............................................34 PickMenuBox.............................................36 ResetBox................................................38 TURBO OVERDRIVE PACKAGE TABLE OF CONTENTS (Continued) Unit MENU123 SetMenu123..............................................39 PickMenu123.............................................40 Reset123................................................42 Unit MENUPULL SetMain.................................................43 SetSub..................................................43 PickMain................................................46 PickSub.................................................46 RestoreWorkScreen.......................................48 SaveWorkScreen..........................................48 WriteMain...............................................50 WritSub.................................................50 ============================================================ TURBO OVERDRIVE PACKAGE - INTRODUCTION Page 4 ============================================================ WHAT IS TOP The Turbo Overdrive Package (TOP) is a collection of over 40 procedures and functions that you can incorporate in your own Turbo Pascal 4.0 programs for the IBM and IBM-Compatible PC. With the TOP routines you can: Pop-up a color selection smorgasbord Pop-up an ASCII character selector Save and restore screens Hide the cursor and change its shape Edit and read a string from the screen Draw boxes with the arrow keys Install Pop-up box menus Generate Lotus-123 style menus Use sophisticated two-level pull-down menus In addition to these unique functions TOP also brings a different philosophy. TOP is written almost exclusively in standard Turbo Pascal with as little inline machine code as is possible. And TOP is modular so that you don't have to use the entire package if you only like one piece. Many other Turbo Pascal subroutine packages suffer from two shortcomings. First, much or all of the code of these packages is written in assembler and translated to Turbo Pascal inline machine code. The big problem with inline code is that if you're not an expert on the Intel microprocessor architecture then there are parts of your program you don't understand. This puts you in the awkward position of not being able to change or update your program when you need to. For example when Borland brought out version 4.0 of Turbo Pascal, many inline routines written for 3.0 wouldn't work. Of course there is a place for machine code because it is fast and allows you to go beyond the limits of Turbo Pascal. However with release 4.0 Borland has remedied the slow screen IO and most of the other weak areas in the compiler so that only a few functions now absolutely require inline code. To reduce the inline-code-problem, the Turbo Overdrive Package contains only two short inline routines (which move chunks of data to and from the screen without generating snow on the CGA). A few of the low level routines in IOSTUFF take advantage of the services provided in the computer's BIOS. But all other code is standard Turbo Pascal, generously commented and written as simply and ============================================================ TURBO OVERDRIVE PACKAGE - INTRODUCTION Page 5 ============================================================ directly as possible so that you can understand it and change it. The second problem with some other Pascal packages is that the higher order functions are so interrelated with the low order functions that they force you to include a bunch of code you don't necessarily want to use. I call this the all-or-nothing effect. To use these packages it seems you have to subordinate your own way of doing things to theirs. TOP's answer to the all-or-nothing problem is to make each unit as self contained as possible. There's no complex interrelationship between the various Units. So, for example, if you decide you want to use the pull-down menus in TOP you need only two Units: MENUPULL and IOSTUFF. Unit IOSTUFF, which is small, contains the input/output routines used by all other TOP Units. LICENSE AND REGISTRATION The programs in the Turbo Overdrive Package are not public domain. Rather they are being distributed under the User Supported Software concept. TOP has been copyrighted by the author who reserves all rights. You are granted a limited license to use and copy the program according to the terms below. As an individual you may freely copy the TOP disk for your evaluation and the evaluation of others so long as no price or other consideration is charged. Shareware distribution organizations may copy the TOP diskette and share it with their members so long as no price is charged other than a reasonable distribution fee not to exceed the cost of a diskette and handling. The TOP Units, associated demonstration files and documentation must always be distributed together. The contents of the TOP disk including the documentation may not be modified. You may not reproduce the program manual in any way. If you are a registered user, you may include the TOP routines in any programs you write. If TOP source code is included in any program you sell or distribute please credit the Turbo Overdrive Package and Nescatunga Software. Schools are granted permission by the author to copy TOP as many times as needed and use TOP routines freely so long as the registration fee has been paid for each building the ============================================================ TURBO OVERDRIVE PACKAGE - INTRODUCTION Page 6 ============================================================ program will be used in. REGISTRATION FEE If you find the TOP routines useful we ask that you register as a user by sending $20.00 to: Nescatunga Software Box 5942 Katy, TX 77450 For registering you will receive a printed copy of the TOP documentation and a disk with the latest TOP version. The TOP version available from Nescatunga will generally be at least one level more current than the version available from shareware distributors and bulletin boards. TOP represents many hours of work. We can continue to enhance TOP and develop other shareware products ONLY if you support the product and the shareware concept. WHAT'S ON THE TOP DISK The TOP disk contains 20 files organized into three categories: The Turbo Overdrive Package Units IOSTUFF.PAS General IO, screen and cursor GETCOLOR.PAS Pop-up color selection POPASCII.PAS Pop-up ASCII char. selection GETLINE.PAS Edited string input DRAWBOX.PAS Draw boxes with cursor keys MENUBOX.PAS Pop-up menus MENU123.PAS Lotus-123 menus MENUPULL.PAS Two tiered pull-down menus Demonstration Programs IOSTUFF.DEM Demonstrates Unit IOStuff GETCOLOR.DEM Demonstrates Unit GetColor POPASCII.DEM Demonstrates Unit PopASCII GETLINE.DEM Demonstrates Unit GetLine DRAWBOX.DEM Demonstrates Unit DrawBox MENUBOX.DEM Demonstrates Unit MenuBox MENU123.DEM Demonstrates Unit Menu123 MENUPULL.DEM Demonstrates Unit MenuPull BIGDEMO.DEM Demonstrates all Units ============================================================ TURBO OVERDRIVE PACKAGE - INTRODUCTION Page 7 ============================================================ TOP Documentation files TOPEPSON.DOC Epson FX format TOPASCII.DOC ASCII Format READ.ME Late breaking news HOW TO USE TOP UNITS To utilize a TOP Unit in one of your programs simply include a reference to the Unit in the USES clause at the top of your program. For example if in your program MY_PROJECT you elect to utilize pop-up menus from TOP's Unit MenuBox then include the following statements: PROGRAM MY_PROJECT; USES MenuBox; {you also will likely use unit CRT} BEGIN { Calls to MenuBox } ... END. Compile and run your program just as you always do. When Turbo Pascal compiles your program it will look for the file MenuBox.Pas in order to include its code in your program. To make sure Turbo Pascal can find the TOP Units, copy all the TOP Unit (*.PAS) files to the same floppy disk or hard disk directory as your program. To copy all the TOP Units to directory \PAS on drive C: C:>COPY A:*.PAS C:\PAS If you don't want to take up unneeded space by copying all the TOP *.PAS files then you may selectively copy only the Units you need. If your computer has a hard disk then simply put the TOP disk in the A: drive and copy the file(s) containing the unit(s) you want to use into the same directory or onto the same disk as your Turbo Pascal program. For example if you are working on a program called PROJECT.PAS in directory \PAS on drive C: and you want to incorporate pop-up menus from TOP's Unit MenuBox then simply put the TOP disk in drive A: and copy two files to C:\PAS as shown below: C:>Copy A:MENUBOX.PAS C:\PAS C:>Copy A:IOSTUFF.PAS C:\PAS ============================================================ TURBO OVERDRIVE PACKAGE - INTRODUCTION Page 8 ============================================================ If your computer only has floppy disks and you are working on a program called PROJECT.PAS thats in the B: drive and you want to use the TOP MenuBox Unit then put the TOP disk in drive A: and copy the files to the B: drive as shown below: B:>Copy A:MENUBOX.PAS B: B:>Copy A:IOSTUFF.PAS B: You must always include file IOSTUFF.PAS even if you are not using any of the input/output routines directly because all of the other seven TOP Units reference Unit IOSTUFF. Unit DIR also uses Unit GETLINE. ============================================================ TURBO OVERDRIVE PACKAGE - UNIT IOSTUFF Page 9 ============================================================ Unit IOSTUFF contains the low level screen, input/output and cursor procedures and functions used by the other main units. Some of these procedures are similar to procedures found in other packages but I think you will find these less cumbersome to use. MoveToScreen -- Move data to CGA video buffer MoveFromScreen -- Move data from CGA video buffer These two procedures move large chunks of data to and from the CGA video buffer directly without causing snow. The procedures accomplish this feat by moving the characters only while the CRT is in video retrace. Turbo Pascal 4.0's Write and Writeln procedures have been rewritten to use direct video buffer addressing rather than BIOS calls. Turbo Pascal's procedures are now so fast that the programmer no longer needs his own direct video buffer addressing routines to write on the screen. There remains a need, however, for fast, snow-free moves of portions of or all of a screen in order to store or restore the screen's contents. It should be noted that MoveToScreen and MoveFromScreen are not string writing routines. The data moved must be in the format used by the video buffer, i.e. pairs of character/attribute bytes. The Type declarations for Unit IOSTUFF provide Types Map and Screen to define variables for storing video buffer contents. Variable CS (for Color Screen) in IOSTUFF resides at the absolute address of the color video buffer ($B800) and thus may be used in any program that USES IOSTUFF to refer to the color screen as it is in the example below. Similarly variable MS (for Monochrome Screen) resides at the absolute address ($B000) of the monochrome video buffer. CALLING SEQUENCE: PROCEDURE MoveToScreen(Var Source,Dest; Len: Integer); PROCEDURE MoveFromScreen(Var Source,Dest; Len: Integer); Source : Data which will be moved. Dest : Target location to move data. Len : Length in bytes to be moved. In MoveFromScreen Source will be the actual color video buffer (see variable CS described below). Conversely, in MoveToScreen Dest is the actual color video buffer. Remember in setting Len that there are two bytes for each character. So for an entire screen Len would be 4000. ============================================================ TURBO OVERDRIVE PACKAGE - UNIT IOSTUFF Page 10 ============================================================ EXAMPLES: To save an entire screen in variable Screenhold and then restore the screen: VAR ScreenHold : Screen; { See IOSTUFF for Screen } MoveFromScreen(CS,ScreenHold,4000); . . MoveToScreen(ScreenHold,CS,4000); To save and restore just row 5 of the screen in variable OneLine: VAR OneLine : Array[1..80] of Map; {See IOSTUFF for Map} MoveFromScreen(CS[5,1],OneLine,160); . . MoveToScreen(OneLine,CS[5,1],160); ============================================================ TURBO OVERDRIVE PACKAGE - UNIT IOSTUFF Page 11 ============================================================ SaveScreen -- Save the current screen image RestoreScreen -- Restore a previously saved screen image These two procedures save and restore screen images. SaveScreen will make a copy of the screen just the way it looks when SaveScreen is called. And RestoreScreen will bring that saved screen back to the display. CALLING SEQUENCE: PROCEDURE SaveScreen(NS:Integer); PROCEDURE RestoreScreen(NS:Integer); NS : Screen number (0 - 5) of saved screen. Each time SaveScreen is called NS must be supplied to identify the screen for later restoration. As the procedures are currently written NS must be in the range 0 to 5. With minor modifications however, this limitation could easily be increased or decreased. Screen Number 0 is reserved for use by the SavePartScreen and RestorePartScreen procedures described below. So don't use the statement SaveScreen(0); unless you are purposely saving a screen image for use by the RestorePartScreen procedure described later. SaveScreen and RestoreScreen have no code to ensure the NS you provide is in range. If your program contains the statement SaveScreen(S); and S := 6 the effect will be equivalent to an elephant tromping through a flower garden. So if your use of the SaveScreen routine is dynamic (you don't know how many screens will be saved) SaveScreen and RestoreScreen are not the right way to go. As written, SaveScreen saves the six 4000 byte screen images in array ScreenHold in Turbo Pascal's data area. If your program needs all the data area it can get, these screen images could easily be stored on the heap using procedures New or GetMem (which, incidentally, is also the right way to handle the dynamic number of screens problem described above). However, if you can spare the data space and will be saving a predetermined number of screens, I think it is cleaner and more straightforward to store the screens right in the data space as these procedures do. EXAMPLES: In this example the programmer saves the screen's contents in bucket 2, writes a message and then restore the screen: ============================================================ TURBO OVERDRIVE PACKAGE - UNIT IOSTUFF Page 12 ============================================================ SaveScreen(2); WriteSt('====================================',5,5); WriteSt(' Write some stuff over the screen ',5,6) WriteSt('====================================',5,7); . . RestoreScreen(2); ============================================================ TURBO OVERDRIVE PACKAGE - UNIT IOSTUFF Page 13 ============================================================ SavePartScreen -- Save a portion of the screen RestorePartScreen -- Restore a portion of the screen Anything that can be accomplished with SavePartScreen and RestorePartScreen can generally be accomplished more directly with SaveScreen and RestoreScreen. But, because the later procedures save and restore the entire screen they may be a touch too slow for some applications (like pull- down menus for example). A rough rule of thumb is that if you need to save and restore less than a quarter of the screen it is better to do it with the SavePartScreen and RestorePartScreen procedures. If you need to restore anything larger than a quarter of the screen use SaveScreen and RestoreScreen. As mentioned in the documentation for SaveScreen, Screen Number 0 is reserved for use by the RestorePartScreen Procedure. You can take advantage of this relationship by saving an entire screen with SaveScreen(0) and restoring various parts of it later using RestorePartScreen. This approach is an alternate to using matched pairs of SavePartScreen and RestorePartScreen. See example 2 below for this useful technique. CALLING SEQUENCE: PROCEDURE SavePartScreen(X1,Y1,X2,Y2:Integer); PROCEDURE RestorePartScreen(X1,Y1,X2,Y2:Integer); X1,Y1,X2,Y2 : Coordinates of the area to be saved X1,Y1 are the coordinates of the upper left hand corner of the block and X2,Y2 are the coordinates of the lower right hand corner of the block. EXAMPLES: Example 1 below saves the portion of the screen from column 5, row 2 to column 10, row 6 and later restores the same area: SavePartScreen(5,2,10,6); . . RestorePartScreen(5,2,10,6); In Example 2 below the programmer takes advantage of the relationship of SaveScreen(0) with RestorePartScreen. First the entire screen is saved then portions of it are later restored: ============================================================ TURBO OVERDRIVE PACKAGE - UNIT IOSTUFF Page 14 ============================================================ SaveScreen(0); WriteSt('==========',1,1); WriteSt('Some Stuff',1,2); WriteSt('==========',1,3); . . RestorePartScreen(1,1,10,3); WriteSt('==========',5,5); WriteSt('More Stuff',5,6); WriteSt('==========',5,7); . . RestorePartScreen(5,5,15,7); ============================================================ TURBO OVERDRIVE PACKAGE - UNIT IOSTUFF Page 15 ============================================================ SetColor -- Set foreground and background colors This procedure sets the foreground and background color attributes so that any subsequent writes will be in the colors indicated. The statement SetColor(Cyan,Black); is roughly equivalent to the two statements TextColor(Cyan); TextBackground(Black); The only difference is the way SetColor handles blink. If the background color is set to any of the intense colors greater than 7 (White, Yellow, LightCyan, etc.) SetColor will cause the foreground to blink. This approach duplicates the way the actual color attributes work and simplifies the awkward handling of the blink bit in Turbo Pascal. SetColor uses the Turbo Pascal variable TextAttr, which is defined in CRT. TextAttr is the attribute used for Turbo Pascal writes. CALLING SEQUENCE: PROCEDURE SetColor(F,B:integer); F : Foreground color B : Background color For the colors you may use numbers between 0 and 15 or the color constants listed below from Unit CRT. If you call SetColor with a background color greater than 7 (one of the intense colors such as white or yellow) the foreground will blink. Number Color Number Color 0 Black 8 DarkGray 1 Blue 9 LightBlue 2 Green 10 LightGreen 3 Cyan 11 LightCyan 4 Red 12 LightRed 5 Magenta 13 LightMagenta 6 Brown 14 Yellow 7 LightGray 15 White ============================================================ TURBO OVERDRIVE PACKAGE - UNIT IOSTUFF Page 16 ============================================================ EXAMPLES: To set the foreground color to red and the background color to black: SetColor(Red,Black); {or SetColor(4,0);} To Set the foreground color to blinking red and the background to black: SetColor(Red,DarkGray); {or SetColor(4,8);} ============================================================ TURBO OVERDRIVE PACKAGE - UNIT IOSTUFF Page 17 ============================================================ WriteSt -- Write a string This procedure writes a string starting at column X, Row Y on the screen. WriteSt is nothing more than a GoToXY and a Write, but it saves bushels of GoToXY statements. In previous versions of the Turbo Overdrive Package, WriteSt was a direct video write using inline machine code statements. Because Turbo Pascal 4.0 now uses fast direct video writes, our inline WriteSt procedure is no longer needed and has been repaced by this simple procedure. CALLING SEQUENCE: PROCEDURE WriteSt(St:AnyStr;X,Y:Integer); St : String to be written X,Y : Coordinates of first character EXAMPLE: To write an error message on line 25: WriteSt('Error message 1000',1,25); ============================================================ TURBO OVERDRIVE PACKAGE - UNIT IOSTUFF Page 18 ============================================================ WriteCh -- Write one character This Procedure writes a character at column X, row Y on the screen. The procedure uses service 9 of interrupt 10 to write the character. This approach circumvents the usual problems with writing some of the low order ASCII characters which cause beeps, backspaces and linefeeds. CALLING SEQUENCE: PROCEDURE WriteCh(Ch:Char;X,Y:Integer); Ch : Character to be written X,Y : Coordinates of character EXAMPLE: To write character 7 (which normally will produce a beep) at column 1, row 5: WriteCh(Chr(07),1,5); ============================================================ TURBO OVERDRIVE PACKAGE - UNIT IOSTUFF Page 19 ============================================================ WriteManyCh -- Write the same character multiple times This procedure is like WriteCh described above except that the character is repeated Num times. The procedure is useful for writing the top and bottom borders of boxes. CALLING SEQUENCE: PROCEDURE WriteManyCh(Ch:Char;X,Y,Num:Integer); Ch : Character to be written X,Y : Coordinates of first character Num : Number of times to repeat the character EXAMPLE: To write 20 copies of character # starting at column 1, row 5: WriteManyCh('#',1,5,20); ============================================================ TURBO OVERDRIVE PACKAGE - UNIT IOSTUFF Page 20 ============================================================ FillScr -- Fills the screen with a single character This procedure fills the screen with the chosen character. It is useful for filling the screen with backgrounds. CALLING SEQUENCE: PROCEDURE FillScr(Ch:Char); Ch : character to fill the screen. EXAMPLE: To fill the screen with a plus signs: FillScr('+'); ============================================================ TURBO OVERDRIVE PACKAGE - UNIT IOSTUFF Page 21 ============================================================ ReadFromScr -- Read a string from the screen This function uses service 8 of Interrupt 10 to read a string from the screen. To prevent a flicker effect, the cursor is turned off during the read. Trailing blanks are truncated and the returned string's length is set to the last non-blank character. CALLING SEQUENCE: FUNCTION ReadFromScr(X,Y,Len:Integer):AnyStr; X,Y : coordinates of the beginning of the string to be read. Len : length of the field to be read. EXAMPLE: To read a string at location column 4, row 6, 10 characters long: VAR TempStr : AnyStr; TempStr := ReadFromScr(4,6,10); ============================================================ TURBO OVERDRIVE PACKAGE - UNIT IOSTUFF Page 22 ============================================================ GetCh -- Reads a character from the screen GetCh returns a single character from the screen at location X,Y. CALLING SEQUENCE: FUNCTION GetCh(X,Y:Integer):Char; X,Y : coordinates of character to be read EXAMPLE: To read the character at column 6, row 10: Ch := GetCh(6,10); ============================================================ TURBO OVERDRIVE PACKAGE - UNIT IOSTUFF Page 23 ============================================================ Border -- Draw a double-line box SBorder -- Draw a single-line box These two procedures draw boxes on the screen with an optional title centered at the top. Border draws a double- line box and SBorder draws a single-line box. CALLING SEQUENCE: PROCEDURE Border(X1,Y1,X2,Y2: Integer; Header:AnyStr); PROCEDURE SBorder(X1,Y1,X2,Y2: Integer; Header:AnyStr); X1,Y1 : Coordinates of upper left hand corner of box. X2,Y2 : Coordinates of lower right hand corner of box. Header : Title for the box. If no title is desired use the null string (''); To draw a double-line box from column 5, row 6 to column 30, row 20 with title 'Menu Choices': Border(5,6,30,20,'Menu Choices'); PROCEDURE Beep; Beep, as its name implies produces a beep on the speaker. EXAMPLE: If Ch in ['y','Y'] then beep; ============================================================ TURBO OVERDRIVE PACKAGE - UNIT IOSTUFF Page 24 ============================================================ Linecursor -- Make the cursor shape a line BigCursor -- Make the cursor shape a block These two procedures change the shape of the cursor. LineCursor produces a normal two-line cursor. BigCursor produces a large block cursor. The cursor on the monochrome adapter has more scan lines than the cursor on the color adapter. The procedures recognize the differences in adapters and compensates with the right number of scan lines in both the line and big cursors. CALLING SEQUENCE: PROCEDURE Linecursor; PROCEDURE BigCursor; EXAMPLES: To produce a block cursor: BigCursor; To restore the block cursor to the normal line shape: LineCursor; ============================================================ TURBO OVERDRIVE PACKAGE - UNIT IOSTUFF Page 25 ============================================================ HideCursor -- Hide the cursor ShowCursor -- Show the cursor HideCursor makes the cursor invisible by flipping bit 5 of the top scan line on. ShowCursor reverses the process to make the cursor visible again. CALLING SEQUENCE: PROCEDURE HideCursor; PROCEDURE ShowCursor; EXAMPLES: To make the cursor invisible: HideCursor; To restore the cursor and make it visible: ShowCursor; ============================================================ TURBO OVERDRIVE PACKAGE - UNIT DIR Page 26 ============================================================ The main function in Unit DIR is PickFile. This function pops up a list of files on the current path and allows the user to select the file he wants with a point and shoot cursor. ShowDir and ChangPath are two procedures used by PickFile that are also pretty handy on their own. ShowDir -- Display a directory of files ShowDir prints a directory of files from the current logged path. Files are displayed 6 to a line in a horizontal format. The maximum number of files that can be displayed is 120. CALLING SEQUENCE: PROCEDURE ShowDir; EXAMPLE: To display the files from the current path: ShowDir; ============================================================ TURBO OVERDRIVE PACKAGE - UNIT DIR Page 27 ============================================================ ChangePath -- Change the drive and directory ChangePath allows the user to change the current path by entering a new drive/directory. ChangePath does not display a directory of files so use ShowDir to display the files in the changed directory. CALLING SEQUENCE: PROCEDURE ChangePath: EXAMPLE: To display the current directory, allow the user to change paths and then display the directory of the new path: ShowDir; ChangePath; ShowDir; ============================================================ TURBO OVERDRIVE PACKAGE - UNIT DIR Page 28 ============================================================ PickFile -- Point-and-shoot file selector PickFile returns a user-selected file name. The function displays a directory of the current logged drive and allows the user to pick the file using a point-and-shoot reverse- video cursor. The user may change paths during the selection by hitting the F2 key. If he does change paths, a directory of the new path is displayed. CALLING SEQUENCE: FUNCTION PickFile:AnyStr; EXAMPLE: To select a file and open it: VAR FileName : Text; . . Assign(FileName,PickFile); ReWrite(FileName); . . Close(FileName); ============================================================ TURBO OVERDRIVE PACKAGE - UNIT GETCOLOR Page 29 ============================================================ ChooseColor -- Pop-up color selector smorgasbord SetChooseColor -- Set location of color selector ChooseColor is a pop-up color smorgasbord that allows the user to choose his foreground and background colors from the smorgasbord. A sample of the current chosen colors is displayed to the right of the smorgasbord to show the user how the combination will look. The smorgasbord also allows the user to select blinking text. ChooseColor does not change the colors, it only allows the user to select them. To set the chosen colors follow the ChooseColor call with a call to SetColor. SetChooseColor is an optional procedure to change the location of the pop-up color selection smorgasbord. The default position for the smorgasbord if SetChooseColor is not called is column 20, row 5. The smorgasbord (including the color sample) is 30 characters wide and 8 characters tall. CALLING SEQUENCE: PROCEDURE ChooseColor(VAR Fore,Back : Integer); Fore : Foreground color chosen by the user Back : Background color chosen by the user Before calling ChooseColor set Fore and Back to the default colors so that when the smorgasbord is displayed it will show the correct current colors. PROCEDURE SetChooseColor(X,Y : Integer); X,Y : coordinates of the top left corner of the smorgasbord. EXAMPLE: To pop-up the color selector at column 20, row 3, allow the user to select colors and set the colors: VAR Fore,Back : Integer; Fore := Cyan; Back := Black; SetChooseColor(20,3); ChooseColor(Fore,Back); SetColor(Fore,Back); ============================================================ TURBO OVERDRIVE PACKAGE - UNIT POPASCII Page 30 ============================================================ ChooseASCII -- Pop-up ASCII character selector SetChooseASCII -- Set location of ASCII character selector ChooseASCII pops up an ASCII character selector and returns the character chosen by the user. When the selector first pops up, the first 64 ASCII characters are displayed. The user may scroll down one line at a time or page down to display all 256 ASCII characters 64 at a time. The user selects the ASCII character by moving a selector box around the screen with the arrow keys and hitting enter when the selector box surrounds the chosen character. If the user hits the escape key during the selection process the ASCII character #0 is returned. SetChooseASCII is an optional procedure that changes the location of the pop-up ASCII character selector in ChooseASCII to column X, row Y. The default position for the ASCII selector if SetChooseASCII is not called is column 20, row 5. The selector box is 18 characters wide and 18 characters tall. CALLING SEQUENCE: FUNCTION ChooseASCII:Char; PROCEDURE SetChooseASCII(X,Y:Integer); X,Y : coordinates of top left corner of selector box. EXAMPLE: To position the ASCII character selector box at column 3, row 4 and select an ASCII character: VAR Ch : Char; SetChooseASCII(3,4); Ch := ChooseASCII; ============================================================ TURBO OVERDRIVE PACKAGE - UNIT GETLINE Page 31 ============================================================ GetStr -- input a user-edited string This function allows the user to enter and edit a string on the screen. When he is through, the function reads the string off the screen and returns it to be processed further. The functionality of GetStr that takes it beyond a Pascal Read statement is that all of the normal editing keys are functional including the left and right arrow, backspace, insert and delete keys. Ctrl-backspace erases the string and positions the cursor at the start of the string. The insert key toggles on an insert mode whereby all characters to the right of the cursor are pushed to the right when characters are entered. The programmer may provide a default string to the function. The default string will be displayed on the screen with the cursor positioned after the last character in the default string. If the user hits any editing key first (backspace, left arrow, etc.) the function assumes that the user wants to edit the default string. If, on the other hand, the user enters a character as the first keystroke, the function assumes that the user doesn't want to use the default string but rather wants to type in an entire new string from scratch. In this case the function erases the default string. This set of assumptions follows the current trend exemplified by most commercial programs including Turbo Pascal. The assumptions may be easily removed or modified if they are bothersome. The string that is returned from function GetStr will be truncated. All trailing blanks will be lopped off and the string's length will be shortened accordingly. CALLING SEQUENCE: FUNCTION GetStr(XF,YF,Len:Integer;Default:AnyStr) : AnyStr; X,Y : Coordinates of beginning of string to be read Len : Maximum length of string (field size) Default : Default string to be written in field It may be convenient to think X and Y as the field location and Len as the field size. EXAMPLE: To allow the user to edit and enter a 12 character string at location column 4, row 5 with default "Noname.doc": ============================================================ TURBO OVERDRIVE PACKAGE - UNIT GETLINE Page 32 ============================================================ VAR Filename : AnyStr; Filename := GetStr(4,5,12,'Noname.Doc'); ============================================================ TURBO OVERDRIVE PACKAGE - UNIT DRAWBOX Page 33 ============================================================ Box -- Box drawing The Box procedure enables the user to draw double-line boxes and lines on the screen with the arrow keys. If Box were to be incorporated in an editor or word processor, the programmer would, no doubt, add similar procedures for drawing single-line and combination-single-and-double-line boxes. Box does show one box-drawing technique which can easily be expanded to other styles of box-drawing. CALLING SEQUENCE: PROCEDURE Box(VAR X,Y:Integer); X,Y : Beginning cursor location. Box drawing will start at the initial column and row passed to the procedure. The location of the cursor when drawing was terminated is returned through variables X and Y. EXAMPLE: To allow the user to draw a box on the screen starting at column 5, row 2: Box(5,2); ============================================================ TURBO OVERDRIVE PACKAGE - UNIT MENUBOX Page 34 ============================================================ SetMenuBox -- initialize menu choices for box menu SetMenuBox is the initialization procedure for PickMenuBox, a pop-up menu procedure. SetMenuBox locates the menu on the screen, initializes the menu choices to be displayed and writes the menu on the screen. The menu will pop-up on the screen at the location you pick. If you want to restore the screen to its pre-menu appearance be sure to save the screen image with SaveScreen or SavePartScreen before you call SetMenuBox. CALLING SEQUENCE: PROCEDURE SetMenuBox(X,Y:Integer;MenuStr:AnyStr); X,Y : coordinates of upper left hand corner of menu box. MenuStr : string which contains the menu choices. In building MenuStr the rules are that each seperate menu choice must begin with an unique capital letter and be terminated by a slash (/) delimiter. For example the string 'Walk/Run/Fly/' would set up three menu choices: | Walk | | Run | | Fly | An unique first capital letter in each menu choice is important because that letter will become the shortcut keystroke for choosing the menu item directly. So be sure you don't have two menu choices beginning with the same letter. The slash delimiter is used by the parsing routine in SetMenuBox to break apart the substrings within the string. If you forget the last slash get ready to use your computer's big red switch because the parsing logic gets lost and wanders in circles. True, I could have put in a check for this condition, but once you get your menus working the check would become meaningless overhead. In positioning the menu on the screen with X and Y remember that the box will be two lines longer than the number of menu choices and four characters wider than the longest menu choice. EXAMPLE: To initialize a box menu with the Choices: | Load | ============================================================ TURBO OVERDRIVE PACKAGE - UNIT MENUBOX Page 35 ============================================================ | Save | | Edit | | Quit | at location column 5, row 4 on the screen: SetMenuBox(5,4,'Load/Save/Edit/Quit/'); ============================================================ TURBO OVERDRIVE PACKAGE - UNIT MENUBOX Page 36 ============================================================ PickMenuBox -- returns user's choice from a box menu The function PickMenuBox allows the user to play with a menu that was initialized with SetMenuBox. When the user makes his pick and hits enter, PickMenuBox returns a unique character to the calling routine so that it can branch to the processing logic which performs the user's menu pick. PickMenuBox will highlight the current menu pick with a Lotus-123 reverse-video bar cursor. The user may move the cursor up and down to various menu picks with the up and down arrow keys. The user may select a choice on the menu by hitting the enter key or by hitting the key that is the first letter of his choice. So if the menu choices were | Walk | | Run | | Fly | the user could choose Run in one of two ways; 1) placing the cursor on Run and hitting enter or 2) simply hitting R, the first letter in Run. The character returned from the function is the first letter (always capitalized) of the chosen menu item. For example if the user chooses Run from the menu example above, PickMenuBox will return the character R. If the user hits the escape key during operation of the menu the character #0 will be returned. It is good practice to test for this character and provide escape logic if it is returned. PickMenuBox was designed to be conveniently used in a case statement that parallels the logic of the menu as shown in the examples below. However it certainly could be used in other constructs. CALLING SEQUENCE: FUNCTION PickMenuBox : Char; EXAMPLES: To allow the user to pick his choice from a menu which includes: | Load | | Save | | Edit | | Quit | ============================================================ TURBO OVERDRIVE PACKAGE - UNIT MENUBOX Page 37 ============================================================ include the following statements: SetMenuBox(5,4,'Load/Save/Edit/Quit/'); Case PickMenuBox of 'L': Begin {Load logic here} End; 'S': Begin {Save logic here} End; 'E': Begin {Edit logic here} End; #0,'Q': Begin {Quit and abort logic here} End; End; {Case PickMenuBox} The example above will execute the menu one time and then fall through to other processing. This may or may not be what you want. If you want to trap the user in the menu until he indicates he wants to quit by selecting Quit or hitting escape you should use the Repeat Case construct to achieve the desired result as shown below. Note how the boolean variable ExitMenu is used as a trap release when the user decides to Quit. VAR ExitMenu : Boolean; SetMenuBox(5,4,'Load/Save/Edit/Quit/'); ExitMenu := false; Repeat Case PickMenuBox of 'L': Begin {Load logic here} End; 'S': Begin {Save logic here} End; 'E': Begin {Edit logic here} End; 'Q',#0: Begin ExitMenu := true; End; End; {Case PickMenuBox} Until ExitMenu; ============================================================ TURBO OVERDRIVE PACKAGE - UNIT MENUBOX Page 38 ============================================================ ResetBox -- rewrites box menu ResetBox simply rewrites the menu text that was established with the last call to SetMenuBox. Think of ResetBox as a repair kit to use whenever you have cleared the screen or written over the menu during the processing of your program. CALLING SEQUENCE: Procedure ResetBox; EXAMPLE: The example below shows how to use ResetBox to rewrite the menu after the screen has been cleared: SetMenuBox(5,4,'Clear Screen/Junk/More Junk/'); Case PickMenuBox of 'C': Begin ClrScr; ResetBox; End; 'J': Begin {Junk logic here} End; 'M': Begin {More Junk logic here} End; End; {Case PickMenuBox} ============================================================ TURBO OVERDRIVE PACKAGE - UNIT MENU123 Page 39 ============================================================ SetMenu123 -- Initialize menu choices for 123 menu SetMenu123 is the initialization procedure for PickMenu123, a Lotus 123 style horizontal, reverse-video-bar-cursor menu procedure. SetMenu123 locates the menu on the screen, initializes the menu choices to be displayed and writes the menu on the screen. The menu will be displayed horizontally on the line you pick. CALLING SEQUENCE: PROCEDURE SetMenu123(X,Y:Integer;MenuStr:AnyStr); X,Y : Coordinates of the menu location MenuStr : String which contains the menu choices In building MenuStr remember that each menu choice must begin with an unique capital letter and be terminated by a slash (/) delimiter. For example the string 'Walk/Run/Fly/' would set up three menu choices: [ Walk Run Fly ] The first capital letter in each menu choice is important because that letter will become the shortcut keystroke for choosing the menu item directly. So be sure you don't have two menu choices beginning with the same letter. The slash delimiter is important to the parsing routine in SetMenu123. Just as with the SetMenuBox strings described above, if you forget the last slash get ready to use the big red switch. EXAMPLES: To initialize a 123 menu with the Choices: [ Load Save Edit Quit ] at location column 5, row 1 on the screen: SetMenu123(5,1,'Load/Save/Edit/Quit/'); ============================================================ TURBO OVERDRIVE PACKAGE - UNIT MENU123 Page 40 ============================================================ PickMenu123 -- returns user's choice from a 123 menu The function PickMenu123 allows the user to play with a menu initialized previously with SetMenu123 and returns the user's menu pick in the form of a unique character. PickMenu123 will highlight the current menu pick with a Lotus-123 reverse-video bar cursor. The user may move the cursor left and right to various menu picks with the left and right arrow keys. The user may select a choice on the menu by placing the cursor on a choice and hitting the enter key or by hitting the key that is the first letter of his choice. So for the menu choices [ Walk Run Fly ] the user could choose Run by placing the cursor on Run and hitting enter or he could simply hit the letter R. The character returned from the function is the first letter (always capitalized) of the chosen menu item. For example if the user chooses Run from the menu example above, PickMenu123 will return the character R. If the user hits escape key during operation of the menu the character #0 will be returned. Always test for this character and provide processing logic if it is returned. PickMenu123 is designed to be conveniently used in a case statement as shown in the examples below. CALLING SEQUENCE: FUNCTION PickMenu123 : Char; EXAMPLE: To allow the user to pick his choice from a menu of: [ Load Save Edit Quit ] include the following statements: SetMenu123(5,1,'Load/Save/Edit/Quit/'); Case PickMenu123 of 'L': Begin {Load logic here} End; 'S': Begin {Save logic here} End; 'E': Begin ============================================================ TURBO OVERDRIVE PACKAGE - UNIT MENU123 Page 41 ============================================================ {Edit logic here} End; #0,'Q': Begin {Quit logic here} End; End; {Case PickMenu123} The example above will execute the menu one time and then fall through to other processing which is not normally what you want. Most commercial menus trap the user in the menu until he indicates he wants to quit by selecting Quit or hitting escape. To achieve this effect use the Repeat Case construct as shown in the example below. Note how the variable ExitMenu traps the user in the Repeat loop until he selects Quit: VAR ExitMenu : Boolean; SetMenu123(5,1,'Load/Save/Edit/Quit/'); ExitMenu := false; Repeat Case PickMenu123 of 'L': Begin {Load logic here} End; 'S': Begin {Save logic here} End; 'E': Begin {Edit logic here} End; 'Q',#0: Begin ExitMenu := true; End; End; {Case PickMenu123} Until ExitMenu; ============================================================ TURBO OVERDRIVE PACKAGE - UNIT MENU123 Page 42 ============================================================ Reset123 -- Rewrites 123 menu Reset123 simply rewrites the menu text that was established with the last call to SetMenu123. Think of Reset123 as a repair kit to use whenever you have cleared the screen or written over the menu during the processing of your program. CALLING SEQUENCE: Procedure Reset123; EXAMPLE: The example below shows how to use Reset123 to rewrite the menu after the screen has been cleared: SetMenu123(5,4,'Clear Screen/Junk/More Junk/'); Case PickMenu123 of 'C': Begin ClrScr; Reset123; End; 'J': Begin {Junk logic here} End; 'M': Begin {More Junk logic here} End; End; {Case PickMenu123} ============================================================ TURBO OVERDRIVE PACKAGE - UNIT MENUPULL Page 43 ============================================================ Unit MenuPull is a comprehensive set of pull-down menu routines. The pull-down menus have two components that work separately but with each other. The main menu component is a horizontal bar menu that operates on the top line of the screen. The sub-menu components are little box menus that pop-up under the main menu choices as the user browses the main choices. While the user is browsing the main menu the secondary menus are displayed but are inactive. If the user makes a choice from the main menu then the sub-menu becomes active and the user may make a choice from that menu. The operation of pull-down menus is complex and does require careful attention to detail in the calling program so that processing is transferred from the main menu to the sub- menus at the right time. Don't be intimidated however. These routines are as powerful and as easy to use as any menuing routines you will find. SetMain -- Intialize main menu choices SetSub -- Initialize sub-menu choices SetMain and SetSub are the initialization procedures for PickMain and PickSub, a two-level pull-down menu interface that works much like the interface for Turbo Pascal 4.0. As the user browses the main menu, which is a horizontal menu of choices on the top line of the screen, sub-menus are displayed under each of the main menu picks. If the user hits enter to select a main menu choice, the reverse-video cursor jumps down into the sub-menu to allow him to make a choice there. SetMain initializes the main menu choices to be displayed and SetSub initializes the sub-menu choices under each main menu choice. SetSub must be called several times, once for each main menu choice that has sub-menu choices. The sub-menu choices are associated with the main menu choices through the variable Sub. CALLING SEQUENCE: PROCEDURE SetMain(MenuStr:AnyStr); PROCEDURE SetSub(Sub:Integer;SubStr:AnyStr); MenuStr : String containing main menu choices SubStr : String containing sub-menu choices Sub : Sub-menu to main menu association number The format of MenuStr and SubStr are identical and follow the same format established in MenuBox and Menu123 procedures. Each menu choice given in the string must begin with a capital letter and be terminated by the delimiter ============================================================ TURBO OVERDRIVE PACKAGE - UNIT MENUPULL Page 44 ============================================================ slash (/). For example if MenuStr were given the value 'Save/Load/Quit/' SetMain would set up three main menu choices: [ Save Load Quit ] The first capital letter in each menu choice is important because that letter will become the shortcut keystroke for choosing the menu item directly. So don't begin two menu choices with the same letter. The slash delimiter is used by the parsing routine in SetMain and SetSub. A final reminder; don't forget the last slash in the string. The variable Sub, which is an argument passed to SetSub, provides the association of sub-menus to main menu choices. For example the statement: SetSub(2,'Compile/Link/Run/Quit/'); associates the sub-menu with main menu pick number 2. EXAMPLES: To initialize a main menu and sub-menus that looks something like this: [ Fish Birds Mammals Quit ]; | Trout | | Bass | | Walleye | | Catfish | include the following statements in your program: SetMain('Fish/Birds/Mammals/Quit/'); SetSub(1,'Trout/Bass/Walleye/Catfish/'); SetSub(2,'Robin/Sparrow/Hawk/'); SetSub(3,'Fox/Cow/Armadillo/Mouse/'); Note that there is one SetSub call for each main menu choice that has a sub-menu. The above example included the menu setup string right in the call statement. In many instances it may be more convenient to assign the strings to variables and pass the string through the variable. Also you may wish to make your code more readable by staggering sub-strings on different lines joined with a + as in the example below: ============================================================ TURBO OVERDRIVE PACKAGE - UNIT MENUPULL Page 45 ============================================================ VAR Menu3 : String[80]; Menu3 := 'Fox/'+ 'Cow/'+ 'Armadillo/'+ 'Mouse/'; SetSub(3,Menu3); ============================================================ TURBO OVERDRIVE PACKAGE - UNIT MENUPULL Page 46 ============================================================ PickMain -- Returns user's choice from main menu PickSub -- Returns user's choice from sub menu PickMain and PickSub are the functions that allow the user to play with the menus and make his choice. When the user makes a menu choice by hitting the enter key or hitting the first letter of a pick, the functions will terminate and return to the calling program the first letter (always capitalized) of the chosen menu item. For example if the user picks Fox from a sub-menu made up of | Fox | | Cow | | Armadillo | | Mouse | PickSub would return the character F. PickMain and PickSub will return the character #0 if the user hits escape during operation of the menu. It is a good idea to processing for #0 in the case statements. CALLING SEQUENCE: FUNCTION PickMain : Char; FUNCTION PickSub(Sub:Integer) : Char; EXAMPLE: PickMain and PickSub are intended to be used in a nested case structure that looks like this: ExitMenu := false; Repeat Case PickMain of 'A': Case PickSub(1) of 'P': ... 'Q': ... 'B': Repeat Case PickSub(2) of 'R': ... 'S': ... 'C': Case PickSub(3) of 'T': ... 'U': ... Until MenuExit; The idea here is that each of the sub-menu cases is contained within a large main menu case. If the menus are ============================================================ TURBO OVERDRIVE PACKAGE - UNIT MENUPULL Page 47 ============================================================ used in this way they will interact correctly (with a little help from the programmer). You may wish to use the Repeat Case construct shown in the example and discussed with the MenuBox and Menu123 procedures to trap the user inside a sub-menu or main menu until he signals his intention to quit by hitting escape or selecting Quit from the menu. Most commercial products use this trapped-user approach. If you want more detailed examples for reference, see programs BigDemo.Dem and MenuPull.Dem on the TOP disk. ============================================================ TURBO OVERDRIVE PACKAGE - UNIT MENUPULL Page 48 ============================================================ RestoreWorkScreen -- Restore screen to pre-menu appearance SaveWorkScreen -- Save current screen and rewrite menus These two procedures come into play if you clear the screen or write over the menus during normal processing. The WorkScreen is the screen image the way it looks before any menus are written on it. An original snapshot of WorkScreen is taken in procedure SetMain. So whatever the screen looks like when you call SetMain is important. You may restore the screen to its original look at any time during processing by calling RestoreWorkScreen. SaveWorkScreen takes a new snapshot of the screen. So if your program's logic is fiddling with the screen's contents you will undoubtedly want to save your screen fiddling progress by calling SaveWorkScreen periodically. Remember not to call SaveWorkScreen with the menus on the screen. To prevent messing up your snapshot, first do a RestoreWorkScreen (to erase the menus), write on the screen then finish with a SaveWorkScreen before returning to the control of the menus. SaveWorkScreen sets a flag in the menu routines so that the routines will know to reconstruct all the menus on the new screen. All this sounds complicated but there are only two simple rules to remember: 1. SetMain will take a snapshot of the screen the way it looks when it is called. Any time you call RestoreWorkScreen, the screen will be restored to this original snapshot. 2. If you have updated the screen and want to replace the original snapshot with a new snapshot first get the screen like you want it and then call SaveWorkScreen. CALLING SEQUENCE: PROCEDURE RestoreWorkScreen; PROCEDURE SaveWorkScreen; EXAMPLE: In this example the use has picked "Edit" from sub-menu 1 under main menu pick "File". To restore the work screen, allow the user to edit the screen and return to the control of the menus include the following statements: Repeat Case PickMain of ============================================================ TURBO OVERDRIVE PACKAGE - UNIT MENUPULL Page 49 ============================================================ 'F': Case PickSub(1) of 'E': Begin RestoreWorkScreen; ... { Do user edit stuff } SaveWorkScreen; End; 'Q': ... 'B': ... See BIGDEMO.DEM on the TOP disk for other examples of proper SaveWorkScreen and RestoreWorkScreen usage. ============================================================ TURBO OVERDRIVE PACKAGE - UNIT MENUPULL Page 50 ============================================================ PROCEDURE WriteMain; PROCEDURE WriteSub(Sub:Integer); WriteMain and WriteSub are procedures that do nothing more than rewrite the menus on the screen. WriteMain writes the main menu established by SetMainMenu and WriteSub writes the sub-menu established by SetSubMenu. Unlike the SaveWorkScreen and RestoreWorkScreen procedures described above which allow for complicated screen management, these two procedures are simple repair kits for rewriting the menus on the screen whenever needed. PickSub and PickMain do a good job of figuring out when to write on and restore parts of the screen so WriteMain and WriteSub are not normally needed. CALLING SEQUENCE: PROCEDURE WriteMain; PROCEDURE WriteSub(Sub:Integer); EXAMPLE: In this example the programmer wants to clear the screen and write the menu texts on the cleared screen. However he doesn't want to officially save the new screen image (with SaveWorkScreen): Repeat Case PickMain of 'F': Case PickSub(1) of 'E': Begin ClrScr; ... { Do more stuff to screen } WriteMain; WriteSub; End; 'Q': ... 'B': ... ----------------end-of-author's-documentation--------------- Software Library Information: This disk copy provided as a service of The Public (Software) Library We are not the authors of this program, nor are we associated with the author in any way other than as a distributor of the program in accordance with the author's terms of distribution. Please direct shareware payments and specific questions about this program to the author of the program, whose name appears elsewhere in this documentation. If you have trouble getting in touch with the author, we will do whatever we can to help you with your questions. All programs have been tested and do run. To report problems, please use the form that is in the file PROBLEM.DOC on many of our disks or in other written for- mat with screen printouts, if possible. The P(s)L cannot de- bug programs over the telephone. Disks in the P(s)L are updated monthly, so if you did not get this disk directly from the P(s)L, you should be aware that the files in this set may no longer be the current versions. For a copy of the latest monthly software library newsletter and a list of the 1,000+ disks in the library, call or write The Public (Software) Library P.O.Box 35705 - F Houston, TX 77235-5705 (713) 721-6104 or (713) 721-5205