Media Share 9

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

/ Media Share 9 / MEDIASHARE_09.ISO / pascal / tpmagic.zip / MAGIC.DOC < prev next >

Wrap

Text File | 1992-01-18 | 132KB | 3,189 lines

PASCAL MAGIC Magic Unit Reference File An Add-in For Turbo Pascal, Version 6.0 Copyright 1991, Jeff Napier & Another Company What Magic will do for you: * Make professional multi-color, shadowed pop-up help, warnings, dialog, general text boxes and lightbar menus instantly without wasting your time 're-inventing the wheel'. * Incorporate .BGI graphics drivers and .CHR fonts into your .EXE programs by typing a single word! * Gain mouse support without writing a mouse driver. * Gain color control without writing color control code. * Many Turbo Pascal procedures greatly simplified. * Write graphics-based programs as easily as text-based. * Disk file handling is done automatically. * Enlarged cursor available for your programs for use with laptop LCD displays. * Add sound effects to your program effortlessly. Notice: This is shareware. Feel free to copy and distribute without modification. If you use any portion of the Magic Unit in your programs then registration is a legal necessity. Send $29.95 to Another Company. Complete, well-documented easy-to-understand source code is available. For registration + registration, send $59.90. Send US funds drawn on a US bank to: Another Company P.O. Box 298 Applegate, OR 97530 USA 503-846-7884 Even though this seems quite bug-free to me, it is version 1.0 and you may find a surprise or two. I make no warranty. Please feel free to submit bug reports, and I will try to incorporate appropriate fixes. (If you are new to Pascal, or if you would like a step-by-step guide, you are looking at the wrong file. Please see Tutorial.txt first.) Note: Fonts.tpu, Video.tpu, and Borland's Graph.tpu must be in the same sub-directory in which you keep your tpu files. ALPHABETICALLY ARRANGED REFERENCE TO ALL THE FEATURES AVAILABLE IN MAGIC UNIT NOTE: All procedures, functions and global variables work identically in text and all graphics modes unless otherwise stated. ************************************************************* Answer - Global Variable Uses Magic Declaration: (example) teststring := answer Description: Answer is a string which is returned by the procedure Dialog. You can also use answer as a general purpose global string variable. Considerations: Maximum size of answer is 76 characters. See also: Dialog Example: program test; uses agic; begin sent[1] := 'Write your answer here'; dialog(1,1); if copy(answer,1,2) = 'I ' then User_Started_With_I; . . end. Performance of example: A dialog box pops up and the user types an answer. The string typed by the user is contained in the string, answer. A test is made to see if the first two characters of answer are 'I ' and if so, an imaginary procedure, User_Started_With_I is called. ************************************************************* BarBack - Global Variable Uses Magic Declaration: BarBack := color Description: This sets the background color for lightbar backgrounds in menus, where 'color' is an integer from 0 to 7, in graphics mode or 0 to 15 in text mode, or a color constant as defined by Borland. The colors 0 - 7 are the same in both text and graphics modes. Considerations: May not have the expected effect when used with the limited palettes of 4-color CGA (mode 0,1 or 2), 2-color CGA or Hercules. See also: BarText, BoxBack, BoxText Example: program test; uses magic; begin sent[1] := 'First Thing'; sent[2] := 'Second Thing'; sent[3] := 'Quit'; mc := 1; BarBack := Red; menu(-1,-1); . . end. Performance of example: Three strings are declared. The menu bar will start by highlighting sent[1] when the menu is displayed. Because of the preceding change to BarBack, the background of the highlighted menu item will be in red. ************************************************************* BarText - Global Variable Uses Magic Declaration: BarText := color Description: This sets the color for lightbar text in menus, where 'color' is an integer from 0 to 15 or a color constant as defined by Borland. Colors are the same in graphics and text modes. Considerations: May not have the expected effect when used with the limited palettes of 4-color CGA (mode 0,1 or 2), 2-color CGA or Hercules. See also: BarBack, BoxBack, BoxText Example: program test; uses magic; begin sent[1] := 'First Thing'; sent[2] := 'Second Thing'; sent[3] := 'Quit'; mc := 1; BarText := red; menu(-1,-1); . . end. Performance of example: Three strings are declared. The menu bar will start by highlighting sent[1] when the menu is displayed. Because of the preceding change to BarText, the highlighted menu text will be displayed in red. ************************************************************* BestVideo - Procedure Uses Magic Declaration: Bestvideo Description: By simply declaring BESTVIDEO, the program detects the graphics card present and switches to the best graphics mode possible for that card. When the program is compiled all video drivers (*.BGI files) are automatically built into the .EXE file. The compiled program will therefore run on any standard graphics-equipped system, but will be large in size. Video.Tpu must be available until after compilation. Considerations: Must add Graph, Video, Magic to Uses statement. See also: CgaVideo, EgaVideo, HercVideo, VgaVideo, all Borland Graph procedures & functions. Example: program test; uses crt,graph,video,magic; begin BestVideo; line(0,0,getmaxx,getmaxy); repeat until keypressed; CleanUp; end. Performance of example: Initializes best graphics mode, draws a diagonal line from the upper left corner to the lower right corner of the screen, waits until a key is pressed, then terminates gracefully. Crt must be in the uses line because keypressed is a procedure within the Crt unit (Turbo.tpl). ************************************************************* BigCursor - Procedure Uses Magic Declaration: BigCursor Description: After a call to BigCursor, the cursor in text mode will be a block the size of a whole character instead of an underline. This is particularly useful in programs designed for LCD laptop screens. Unless a specific call is made to SmallCursor before the end of the program, the big cursor will remain in effect at the DOS prompt and within most other programs. Considerations: Has no effect in graphics modes, but will resume as a large cursor when returned to text mode. Example: program test; uses magic; begin BigCursor; write('Big cursor at the end of this line!'); end. Performance of Example: This program will write 'Big cursor at the end of this line', then quit. If run from the IDE, nothing will seem to happen, but if compiled and run from DOS, after execution, the cursor will become large and stay that way. ************************************************************* Border - Global Variable Uses Magic Declaration: border := color; Description: Color is represented with an integer from 0 to 15 or a pre-defined color constant (Borland). Changing the value of border will affect the color of borders drawn around pop-up text boxes, dialog boxes and menus. Colors are the same in text and graphics mode. Considerations: May not have the expected effect when used with the limited palettes of 4-color CGA (mode 0,1 or 2), 2-color CGA or Hercules. See Also: Shadow, MainBack, MainText, Boxback, Boxtext, Barback, Bartext. Example: Program Test; uses magic; begin border := white; sent[1] := 'Do you like this border color?'; GetAnyKey(-1,-1); end. Performance of example: The border color is set to white. A box will appear on the screen asking a silly question. The box will have a white border. When a key is pressed, the program quits. ************************************************************* Boxback - Global Variable Uses Magic Declaration: BoxBack:= color; Description: Color is represented with an integer from 0 to 15 or a pre-defined color constant (Borland). Changing the value of BoxBack will affect the background color of pop-up boxes, text boxes, dialog boxes and menus. Considerations: Do not use background colors above 7 in text mode. May not have the expected effect when used with the limited palettes of 4-color CGA (mode 0,1 or 2), 2-color CGA or Hercules. See Also: MainBack, MainText, Boxtext, Barback, Bartext. Example: Program Test; uses magic; begin BoxBack := magenta; sent[1] := 'Do you like this background color?'; getanykey(-1,-1); end. Performance of example: The box background color is set to magenta. A box will appear on the screen asking a silly question. The box will have a magenta background. When a key is pressed, the program quits. ************************************************************* BoxText - Global Variable Uses Magic Declaration: BoxBack:= color; Description: Color is represented with an integer from 0 to 15 or a pre-defined color constant (Borland). Changing the value of BoxText will affect the text color in pop-up boxes, text boxes, dialog boxes and menus. Colors are the same in text and graphics modes. Considerations: May not have the expected effect when used with the limited palettes of 4-color CGA (mode 0,1 or 2), 2-color CGA or Hercules. See Also: MainBack, MainText, Boxtext, Barback, Bartext. Example: Program Test; uses magic; begin BoxText := black; sent[1] := 'Do you like this text color?'; getanykey(-1,-1); end. Performance of example: The box text color is set to black. A box will appear on the screen asking a silly question. The box will contain black text. ************************************************************* Bx, By - Global Variables Uses Magic Declaration: (example) gotoxy(bx,by) Description: These are global integer variables used to locate the upper left corner of pop-up boxes. Bx represents the horizontal position and By is the vertical position. In text mode the upper left corner is 1,1 and the very lower right corner would be 80,25. In graphics modes, the upper left corner is 0,0 and the lower right varies with the current graphics mode. In VGA 640 x 480, for instance, the lower right corner is called 639,479. Considerations: In most applications within the Magic unit, when a negative number is assigned to Bx or to By, that number will be igored or overwritten a new number, and the pop-up box will be centered on the screen in that dimension. When overwritten, the new number becomes the center of the screen minus half the size of the pop-up box. See Also: Pop, GetAnyKey, GetYN, Dialog, Menu, DoubleMenu {Magic} GetMaxX, GetMaxY, WhereX, Wherey {Borland} Example: Program Test; uses magic; begin sent[1] := 'Write message below:'; dialog(-1,3); . . end. Performance of example: A box pops up in the center of the screen containing one line of text and a blank line in which the user can type an answer. The box is centered on the screen horizontally, and the upper edge is three rows from the top of the screen. ************************************************************* CenterJustify - Global Variable Uses Magic Declaration: (example) CenterJustify := true Description: If you set the boolean global CenterJustify to true all subsequent calls to Pop, Dialog, GetYN, GetAnyKey, Menu and DoubleMenu will contain centered text. Considerations: When a program starts, CenterJustify is false. If you change CenterJustify to true all subsequent uses of it will remain true until you specifically change it back to false. On 4.77 mhz computers (older models) this can slow menu and pop-up generation slightly. Works the same in text and graphics modes. See Also: Pop, GetAnyKey, GetYN, Dialog, Menu, Double Menu. Example: Program Test; uses magic; begin centerjustify := true; sent[1] := 'This is a very long line of text to display'; sent[2] := 'This is short'; GetAnyKey(-1,-1); end. Performance of example: Two lines of text will pop up on the screen and wait until a user presses any key. The second line will be centered under the first. ************************************************************* CGAVideo - Procedure Uses Magic Declaration: CGAVideo Description: This initializes the system in CGA graphics mode. CGA video driver will be automatically compiled into the .EXE program file, eliminating the need for external CGA.BGI file. Considerations: Will not work on Hercules-equipped computers. Graphmode is initially set to 0 (see Borland manual for more details). In this mode, with default colors, some LCD laptops may be unreadable. To repair, switch to another graphics mode with SetGraphMode {Borland manual}. The resulting .EXE file is much smaller than one compiled after a call to BestVideo. This must be called only once during a program. Video.Tpu must be available until after compilation. Must add Graph, Magic to Uses statement. See Also: BestVideo, HercVideo, EGAVideo, VGAVido, SetGraphMode {Borland} Example: Program Test; uses crt,graph, video, magic; begin CGAVideo; rectangle(10,10,310,190); repeat until keypressed; CleanUp; end. Performance of example: The system is put in CGA graphics mode. A large rectangle is displayed until any key is pressed. The program then terminates gracefully. The colors used for this example may not be easily distinguished on a laptop LCD display. Crt must be in the Uses line because keypressed is a procedure within the Crt unit (Turbo.tpl). ************************************************************* CleanUp - Procedure Uses Magic Declaration: CleanUp Description: This procedure clears the screen, releases memory held for video applications, returns to standard text and background colors in text mode, saves and closes open automatic text files, resulting in a graceful return to DOS. Considerations: Call CleanUp as the last line executed in a program. Works in graphics and text modes. Example: Program Test; uses crt, graph, video, magic; begin CGAVideo; rectangle(10,10,310,190); repeat until keypressed; CleanUp; end. Performance of example: The system is put in CGA graphics mode. A large rectangle is displayed until any key is pressed. The program then terminates gracefully to the DOS prompt. Crt must be in the Uses statement because keypressed is a procedure within the Crt unit (Turbo.tpl). ************************************************************* Dialog - Procedure Uses Magic Declaration: Dialog(x,y : integer) Description: Dialog requires two integers, an x (horizontal) and y (vertical) to establish the position of the upper left corner of the dialog box on the screen. In text mode, the upper left corner is 1,1, and the lower right is 80,25. In graphics mode the upper left is 0,0, and the lower right is variable, depending on the current graphics card and mode. You can force Dialog to pop-up in the center of the screen by using a negative number for the x and the y positions. Dialog will pop up a box on the screen containing lines of text and one blank line at the bottom of the box. The user is prompted to type an answer in that bottom line. The lines that will be displayed are predeclared as the array: sent[1..19]. To use Dialog, you must first assign the text to the array. Use as many lines as you like up to 19, as in the example below. Dialog will automatically ignore lines beyond those which contain your text. When the user presses [Enter] or clicks the left mouse button, the dialog box disappears. A new string exists called answer, which contains what the user typed. The sent[1..19] array is cleared. The user can type an answer string as long as the longest sent[] in the dialog box. To get a longer answer string, pad any sent[] string with spaces to make the dialog box wider. Dialog works in text or graphics mode. Considerations: See above. In graphics modes, must use default font. (#0, bit-mapped) See also: sent[], Pop, GetYN, GetAnyKey, Menu Example: Program Test; uses magic; var teststring : string; begin sent[1] := ' How would you answer this question? '; sent[2] := ' Any answer will do.'; dialog(-1,5); teststring := answer; . . end. Performance of example: Only the first two strings from the array sent[] are filled with text. Dialog is called and pops a box onto the screen containing only those two sent[]s, plus an empty line at the bottom. The program then waits for the user to type an answer in the empty line then press [Enter] or click the left mouse button. The dialog box is wider than the questions because they have been padded with spaces. This allows the user room for a long answer. Since the first number in the variables passed to Dialog is a -1, the box is centered horizontally on the screen. After the user finishes typing, the dialog box disappears, leaving a string called answer. The TestString is a copy of answer and the program can go on to process it as desired. ************************************************************* DoubleMenu - Procedure Uses Magic Declaration: DoubleMenu(x,y : integer) Description: DoubleMenu is like Menu, but puts a wider pop-up menu box on the screen showing the menu choices (sent[]s) in two columns, thereby accommodating up to 36 menu choices. Two integer parameters are required, the first indicates the horizontal position of the upper left corner and the second is for the vertical position. If either integer is a negative number, that integer will be ignored and the menu will be centered on the screen in that dimension. Before calling DoubleMenu, a byte variable, mc should be given a value. mc is the current MenuChoice, meaning the sent[] corresponding to mc is the one highlighted. If you state: mc := 1 then the first item on the menu will be highlighted. If you forget to assign mc, a random menu choice will be highlighted with your first call to DoubleMenu. DoubleMenu is very much like a regular pop-up box, in that it will contain the sent[]s in the manner you have declared them. But additionally, the item corresponding to mc will be highlighted. While the user uses the arrow keys or moves the mouse, the highlight bar will move from one to another of the sent[]s. When the user presses any non-arrow key or clicks a left mouse button, the pop-up DoubleMenu disappears, all sent[]s are set to '', and U will have a char value corresponding to the key pressed. If the left mouse button was clicked U will be char #174, and if the right button was pressed, U will be #175. You can then use U or mc to perform operations related to your user's choice. To have the menu return to the screen, sent[]s must be refilled with your strings and DoubleMenu must be called again. The usual way to use DoubleMenu is to put it into a repeat loop as shown in the example below. Considerations: Maximum sent[]s : 36; Should assign a value to mc of at least one and less than the maximum sent[]. Must re-fill the sent[]s for subsequent calls to DoubleMenu. If in a graphics mode, you must use DefaultFont (0) with DoubleMenu. In graphics modes, must use Borland DefaultFont (#0, bit-mapped) See also: sent[], Pop, GetYN, GetAnyKey, Menu Example: Program Test; uses magic; begin mc := 1; repeat sent[1] := 'Do Thing One'; sent[2] := 'Do Thing Two'; sent[3] := 'Do Thing tHree'; sent[4] := 'Do Thing Four'; sent[5] := 'Do Thing fiVe'; sent[6] := 'Do Thing Six'; sent[7] := ' Quit '; DoubleMenu(10,-1); if (u = #174) or (u = #13) then case mc of 1 : Procedure1; 2 : Procedure2; 3 : Procedure3; 4 : Procedure4; 5 : Procedure5; 6 : Procedure6; 7 : u := #175; end; {case mc} u := upcase(u); case u of 'O' : Procedure1; 'T' : Procedure2; 'H' : Procedure3; 'F' : Procedure4; 'V' : Procedure5; 'S' : Procedure6; 'Q' : u := #175; #27: u := #175; end; {case u} until U = #175; CleanUp; end. Performance of example: Mc is set to 1 so when the menu pops up, the first item will be highlighted. Seven sent[]s are given strings. The DoubleMenu pops up and the user presses a key or operates the mouse. Then if U is #174, (because the left mouse button has been pressed) or U is #13, (the [Enter] key) then a case statement figures out what to do with the user's menu choice. If mc is between 1 and 6, one of the procedures is called. Of course, these procedures can do anything you wish, based upon what menu item the user has selected. The last menu choice (sent[7]) is 'Quit' and will cause this program to fall through and terminate. U is changed into an uppercase letter so that the following case will work whether the user presses a capital or small letter. This second case checks to see whether the user selected a menu item based upon the capitalized letter hints. You can also use function keys here. The #0 has already been stripped off, so if you get a ';' then the user pressed [F1] and probably wants 'help.' There is a boolean variable called Functkey which will now be true if the user pressed a function key, such as an arrow or [F1]. If the user actually pressed [;] then Functkey will be false. Assuming the user did not select 'Quit' or press #27 (the [Escape] key) or the right mouse button, the menu process will repeat. When the user finally does choose to quit, the CleanUp procedure returns to DOS gracefully. ************************************************************* DumpMaps - Procedure Uses Magic Declaration: DumpMaps Description: DumpMaps will release all memory held for screen images, without restoring the images. Works the same in graphics or text modes. Considerations: In graphics modes, it is easy to fill all available RAM with unused screen images. This seldom-needed procedure will help you clear that out. See also: Restore, Pop, GetAnyKey, GetYN, Dialog, Menu, DoubleMenu, XClear, CleanUp Example: Program Test; uses video, graph, magic; begin BestVideo; sent[1] := 'An example string'; sent[2] := 'Another example string'; pop(10,10); sent[1] := 'An example string'; sent[2] := 'Another example string'; pop(0,0); sent[1] := 'An example string'; sent[2] := 'Another example string'; pop(getmaxx div 2,160); sent[1] := 'This is becoming a messy screen'; pop(40,getmaxy - 40); WaitForUser; DumpMaps; . . end. Performance of example: The screen is cluttered with a bunch of pop-up boxes. When the user presses a key, the memory held for the replacement of those boxes disappears, but he boxes remain pictured on the screen. ************************************************************* EGAVideo - Procedure Uses Magic Declaration: EGAVideo Description: This initializes the system in EGA graphics mode. EGA video driver will be automatically compiled into the .EXE program file, eliminating the need for external EGAVGA.BGI file. Considerations: The resulting .EXE file is much smaller than one compiled after a call to BestVideo. BestVideo builds all graphics drivers into the .EXE file, but EGAVideo builds in only the EGAVGA driver. This must be called only once during a program. Video.Tpu must be available until after compilation. Must add Graph, Video, Magic to Uses statement. There are several graphmodes available for EGA. See the Borland manuals. The magic unit allows for more screen saves when using multiple pop-up boxes, GetYN's, etc than RAM can hold. If you go to far, stacking up too many pop-ups, the IDE will report a memory error. See Also: BestVideo, HercVideo, CGAVideo, VGAVido {Magic}; SetGraphMode, Setcolor, etc. {Borland} Example: Program Test; uses crt, graph, video, magic; begin EGAVideo; rectangle(10,10,20,20); repeat until keypressed; CleanUp; end. Performance of example: The system is put in EGA graphics mode. A small rectangle is displayed in the upper left corner of the screen until any key is pressed. The program then terminates gracefully. Crt must be in the Uses line because Keypressed is a procedure within the Crt unit (Turbo.tpl). ************************************************************* FileRead - Procedure Uses Magic Declaration: character variable := FileRead Description: Fileread is a function that automatically reads one character from a pre-declared text file. Opening and closing the textfile is automatic. Only one character is read and the next call to FileRead will get the next character in the file. To get the very first character in the file, Reset the file before calling Fileread. Considerations: The file is called 'Infile' within the program, but must have an external name under which it will be stored on disk. You must first call NameInFile, before using FileRead, or else the program will try to read a file with the default external name of 'NoName.' If there is an error, such as trying to read past the end of the file, or reading a file that does not exist, FileRead will return a char #0. See Also: NameInFile, FileReadLn, problem {Magic} Reset, EOF {Borland} Example: Program Reader; uses magic; var a : integer; begin XClear; NameInFile('sample.doc'); for a := 1 to 1000 do write(fileread); end. Performance of example: The screen is cleared. The file to read will be 'Sample.Doc'. Assuming the file exists, the first 1000 characters from that file will be displayed on the screen, then the program ends. ************************************************************* FileReadln - Procedure Uses Magic Declaration: string variable := FileRead Description: Filereadln is a function that automatically reads one line from a pre-declared text file. Opening and closing the textfile is automatic. Only one line is read and the next call to FileReadln will get the next line in the file. To get the very first line in the file, Reset the file before calling Fileread. A line is defined as having carriage return/linefeed at the end (char #13,#10). Considerations: The file is called 'Infile' within the program, but must have an external name under which it will be stored on disk. You must first call NameInFile, before using FileReadln, or else the program will try to read a file with the default external name of 'NoName.' If there is an error, such as trying to read past the end of the file, or reading a file that does not exist, FileReadln will return a char #0. See Also: NameInFile, FileReadLn, problem {Magic} Reset, EOF {Borland} Example: Program Reader; uses magic; var a : integer; begin XClear; NameInFile('sample.doc'); for a := 1 to 10 do writeln(FileReadLn); end. Performance of example: The screen is cleared. The file to read will be 'Sample.Doc'. Assuming the file exists, the first 10 lines from that file will be displayed on the screen, then the program ends. ************************************************************* FileWrite - Procedure Uses Magic Declaration: Filewrite(xstring : string) Description: Filewrite will write a string into the standard text output file. Opening and closing the file is handled automatically. If the file exists, the string will be appended to the end. If the file does not exist it will be created. Carriage return/linefeed is not added to the end of the string. Considerations: The standard text output file is called 'OutFile' within Pascal, , but must have an external name under which it will be stored on disk. You must first call NameOutFile, before using FileWrite, or else the program will write to file with the default external name of 'NoName.' If there is an error, nothing will be written to disk and the boolean variable, Problem will be true. Only one string or character can be written to the output file with a single call to FileWrite. No numerical values can be written unless they are first converted to a string. See Also: NameOutFile, FileWriteLn, Problem {Magic} Str {Borland} Example: Program Writer; uses magic; begin NameOutFile('sample.doc'); FileWrite('This is a sample text file.'); FileWrite('This is a second string of text.'); end. Performance of example: The standard text file is renamed 'Sample.Doc.' Two strings are written to the file then the program ends. If there was no previous file by that name, Sample.Doc is created, otherwise the line is appended to the end of the other text in the file. If you look at Sample.Doc with a word processor or text editor or Turbo Pascal IDE, you will see the last line in the file is: 'This is a sample text file. This is a second string of text.' ************************************************************* FileWriteLn - Procedure Uses Magic Declaration: FilewriteLn(xstring : string) Description: FilewriteLn will write a string into the standard text output file. Opening and closing the file is handled automatically. If the file exists, the string will be appended to the end. If the file does not exist it will be created. Carriage return/linefeed is added to the end of the string. Considerations: The standard text output file is called 'OutFile' within Pascal, , but must have an external name under which it will be stored on disk. You must first call NameOutFile, before using FileWrite, or else the program will write to file with the default external name of 'NoName.' If there is an error, nothing will be written to disk and the boolean variable, Problem will be true. Only one string or character can be written to the output file with a single call to FileWriteLn. No numerical values can be written unless they are first converted to a string. See Also: NameOutFile, FileWrite, Problem {Magic} Str {Borland} Example: Program Writer; uses magic; begin NameOutFile('sample.doc'); FileWriteLn('This is a sample text file.'); FileWriteLn('This is a second string of text.'); end. Performance of example: The standard text file is renamed 'Sample.Doc.' Two strings are written to the file then the program ends. If there was no previous file by that name, Sample.Doc is created, otherwise the line is appended to the end of the other text in the file. If you look at Sample.Doc with a word processor or text editor or Turbo Pascal IDE, you will see the last lines in the file are: 'This is a sample text file. This is a second string of text.' ************************************************************* FunctAscii - Function Uses Magic Declaration: var x : char; x := FunctAscii Description: Returns a character value representing the ASCII value of a function key or an extended key ([Alt] + x, for example) has been pressed. Returns 0 if a standard key has been pressed. Considerations: If you want to know which function key has been pressed you must call FunctAscii before any further uses of the global variable U or the function XReadKey. See Also: XReadKey, Menu, DoubleMenu, U Example: Program test; uses crt, magic; var hold : char; begin repeat u := readkey; clrscr; hold := FunctAscii; if hold = #0 then write(U) else write('Function key: ',hold); until u = #27; end. Performance of example: Everytime a key is pressed the screen is cleared and the character value of the key is written on the screen. If the key is an extended key, the value of the key is preceded by "Function key:" When the user presses the [Esc] key (#27) the program ends. ************************************************************* FunctKey - Global Variable Uses Magic Declaration: (example) if FunctKey then Description: FunctKey is returned with calls to Menu or DoubleMenu. If the user presses a key which is a function key, the ASCII equivalent of that key is assigned to U and FunctKey is true. If the key pressed was not a function key, FunctKey is false. This is useful for differentiating when a user presses an [F] (function) key instead of an alphanumeric key. Considerations: FunctKey is reset to false at the start of each call to Menu or DoubleMenu. See Also: Menu, DoubleMenu. Example: Program Test; uses magic; begin mc := 1; repeat sent[1] := 'Do Something'; sent[2] := 'Do Something Else'; menu(-1,-1); if u = #13 then begin if mc = 1 then DoSomething; if mc = 2 then DoTheOtherThing; end; if (u = ';') and (FunctKey) then DisplayHelp; until u = #27; end. Performance of example: A menu is displayed with only two options. If the user presses [Enter] while the highlight bar is on the first option, procedure DoSomething is executed, and if the second option is highlighted then procedure DoTheOtherThing is executed. This repeats until the user presses the [Esc] key (ASCII #27). There is one other option. If the user presses the [F1] key then FunctKey is true and U is ';.' In this case procedure DisplayHelp will run. ************************************************************* Gd - Global Variable Uses Magic Declaration: (example) gd := 2 Description: Gd is a global integer variable for GraphDetect. Considerations: See Borland manual for more information. See Also: Initgraph {Borland} ************************************************************* GetAnyKey - Procedure Uses Magic Declaration: GetAnyKey(x,y : integer) Description: This is for pop-up notices. A message pops up on the screen then waits for the user to press any key or click a mouse button. You must write strings for the array of sent[]s before calling this procedure. After the user presses a key, all traces of the pop-up and the sent[]s disappear. GetAnyKey requires two integer variables, the first determines the horizontal position on the screen, and the second is the vertical coordinate. If either number is negative, the pop-up message will be centered on the screen in the corresponding dimension. Considerations: Maximum sentc array size: 18. Make sure to add something to this effect to every message to avoid confusing your users: "Press any key to continue..." See Also: Menu, DoubleMenu, Pop, Dialog, GetYN, sent[]. Example: Program Test; uses magic; begin . . sent[1] := 'You have selected an option available only'; sent[2] := 'to registered users. Please send money!!!'; sent[3] := 'Press any key to continue...'; GetAnyKey(-1,-1); . . end. Performance of example: A box pops up on the screen containing three lines, then disappears without a trace when the user presses any key or clicks a mouse button. ************************************************************* GetYN - Procedure Uses Magic Declaration: GetYN(x,y : integer) Description: A message pops up on the screen then waits for the user to press 'Y' or 'N' or click a mouse button. You must write strings for the array of sent[]s before calling this procedure. After the user presses a key, all traces of the pop-up and the sent[]s disappear. GetYN requires two integer variables, the first determines the horizontal position on the screen, and the second is the vertical coordinate. If either number is negative, the pop-up message will be centered on the screen in the corresponding dimension. GetYN sets the global string, answer, to 'Y' or 'N'. Also, the global char U is set to 'Y' or 'N.' Considerations: Maximum sent array size: 18. Make sure to add something to this effect to every message to avoid confusing your users: "Press [Y] or [N]..." GetYN is not case sensitive. The user can type upper or lower case [y] or [n]. If the left mouse button is clicked answer is set to 'Y' and if the right mouse button is clicked answer = 'N'. See Also: Menu, DoubleMenu, Pop, Dialog, GetYN, sent[], answer, u. Example: Program Test; uses magic; begin . . sent[1] := 'Exit to Dos? (Y/N)'; GetYN(-1,1); if answer = 'Y' then begin CleanUp; halt; end; . . end. Performance of example: A box pops up on the screen containing one line and waits for the user to press a key. Until the key pressed is upper or lower case 'Y' or 'N', or until the user clicks a mouse key, the box remains. Then the global string, answer, is set to 'Y' or 'N.' If answer = 'N' then the program terminates cleanly. ************************************************************* Gm - Global Variable Uses Magic Declaration: (example) gm := 0 Description: Gm is a global integer variable for GraphMode. Considerations: See Borland manual for more information. See Also: Initgraph, SetGraphMode {Borland} ************************************************************* Gothic - Procedure Uses Magic Declaration: Gothic Description: Calling the procedure Gothic makes the Borland Gothic font available to graphic-based programs. This font will be compiled into the .EXE file. GOTHIC.CHR does not have to accompany the finished product. Considerations: Compiled .EXE size increases by about 17k. Must put Fonts, Graph, Video, Magic in Uses statement. Do not use with Pop, GetAnyKey, GetYN, Dialog, Menu or DoubleMenu. To use type: SetTextStyle(GothicFont,d,x) where d is the direction (0 is horizontal) and x is an integer from 1 to 10 representing the relative size of the text. See Also: BestVideo, CGAVideo, EGAVideo, VGAVideo, SansSerif, Triplex, Small {Magic} SetTextStyle {Borland} Example: Program Test; uses crt, fonts, graph, video, magic; begin BestVideo; Gothic; SetTextStyle(GothicFont,0,2); outtextxy(100,90,'Test'); repeat until keypressed; end. Performance of example: Gothic font information is compiled into the .EXE file. The highest resolution graphics mode is selected. GothicFont is selected for output, then the word 'Test' is written on the screen. When the user presses a key, the program terminates. Crt must be in the Uses line because Keypressed is a procedure within the Crt unit (Turbo.tpl). ************************************************************* HercVideo - Procedure Uses Magic Declaration: HercVideo Description: This initializes the system in Hercules graphics mode. Hercules video driver will be automatically compiled into the .EXE program file, eliminating the need for external Herc.BGI file. Considerations: The resulting .EXE file is much smaller than one compiled after a call to BestVideo. BestVideo builds all graphics drivers into the .EXE file, but HercVideo builds in only the Herc.BGI driver. This must be called only once during a program. Video.Tpu must be available until after compilation. There is only one GraphMode for Hercules, which is 0. Must add Graph, Video, Magic to Uses statement. With many VGA cards, you must leave Turbo Pascal, specifically run the video card software to set it to Hercules mode, then compile and run your program. See Also: BestVideo, CGAVideo, EGAVideo, VGAVido {Magic}; SetGraphMode, Setcolor, etc. {Borland} Example: Program Test; uses crt, Graph, Video, Magic; begin HercVideo; rectangle(10,10,20,20); repeat until keypressed; CleanUp; end. Performance of example: The system is put in Hercules graphics mode. A small rectangle is displayed in the upper left corner of the screen until any key is pressed. The program then terminates gracefully. Crt must be in the Uses line because Keypressed is a procedure within the Crt unit (Turbo.tpl). ************************************************************* HideCursor - Procedure Uses Magic Declaration: HideCursor Description: This makes the cursor disappear until it is moved to another screen location. Generally, use it after writing to the screen when the user is not to type input. Considerations: For text mode only, has no effect in graphics. Example: Program Test; uses magic; begin write('There is no cursor at the end of this line.'); hidecursor; u := xreadkey; end. Performance of example: A line of text appears on the screen, but there is no cursor at the end of the line. ************************************************************* InFile - Global Variable Uses Magic Declaration: (example) assign(InFile,'Things.Doc') Description: InFile is declared globally as a file of type Text. It is used for importing information into your program with the automatic procedures FileRead and FileReadLn. Considerations: InFile is for text only. Numeric values will be represented as strings in InFile. You can override the automatic use of InFile with standard Turbo Pascal techniques such as Assign, ReWrite and Close. See Also: FileWrite, FileWriteLn, NameInFile, OutFile {Magic}; Assign, ReWrite, ReSet, Append, Write, WriteLn, Read, ReadLn, Rename, Erase, Close {Borland} Example: Program Test; uses magic; begin NameInFile('TestFile.Txt'); ReWrite(InFile); close(InFile); end. Performance of example: This nasty little program makes sure that if there is a file called 'TestFile.Txt' it will contain no information, since ReWriting a file wipes out any previous version of that file. ************************************************************* Left - Global Variable Uses Magic Declaration: (example) if left = false then Description: Left is a global boolean variable used to record the status of the left mouse button. If left = true then the left mouse button has been pressed. Considerations: The status of left will change with every call to Poll, Waste, WasteMouse, ResetMouse or procedures within Magic which handle text or pop up boxes. See Also: Poll, Waste, WasteMouse, ResetMouse, Right Example: Program Test; uses magic; var x, y : word; begin sent[1] := 'Nothing will change until you click the'; sent[2] := 'left mouse button'; Pop(-1,-1); WasteMouse; repeat poll(x,y,left,right) until left; end. Performance of example: A box containing two lines of text will stay on the screen until the user clicks the left mouse button. The program will then terminate. ************************************************************* LittleCursor - Procedure Uses Magic Declaration: LittleCursor Description: After a call to LittleCursor, the cursor in text mode will be a block the size of an underline instead of a large block. The little cursor size is the DOS default cursor. Therefore, this procedure is generally used as an antidote to BigCursor. Considerations: Will have no effect in graphics mode, but will resume as a little cursor when returned to text mode. See also: BigCursor. Example: program test; uses magic; begin . . BigCursor; . . LittleCursor; CleanUp; end. Performance of Example: This program will switch to a block size cursor, then just before ending, it returns the cursor to the default size. ************************************************************* MainBack - Global Variable Uses Magic Declaration: MainBack := color Description: This sets the background color for the main portion of the screen, outside of pop-up boxes. 'Color' is an integer from 0 to 15 or a color constant as defined by Borland. Do not use colors above 7 in text mode. Considerations: May not have the expected effect when used with the limited palettes of 4-color CGA (mode 0,1 or 2), 2-color CGA or Hercules. In text mode, since this is a background color, only 8 colors are available: 0 - 7. See also: BarBack BarText, BoxBack, BoxText, MainText, Border, shadow Example: program test; uses magic; begin sent[1] := 'First Thing'; sent[2] := 'Second Thing'; sent[3] := 'Quit'; mc := 1; MainBack := Red; XClear; Menu(-1,-1); . . end. Performance of example: Three strings are declared, and a menu pops up. Because of the preceding change to MainBack, then the call to XClear, the main background around the menu is red. ************************************************************* MainText - Global Variable Uses Magic Declaration: MainText := color Description: This sets the text color for the main portion of the screen, outside of pop-up boxes. 'Color' is an integer from 0 to 15 or a color constant as defined by Borland. Colors are the same in graphics and text modes. Considerations: May not have the expected effect when used with the limited palettes of 4-color CGA (mode 0,1 or 2), 2-color CGA or Hercules. No procedures in the Magic unit use this color directly. See also: BarBack BarText, BoxBack, BoxText, MainBack, border, shadow Example: program test; uses magic; begin MainText:= LightGreen; textcolor(MainText); gotoxy(1,25); write('My Program, Copyright 1991, Your Company'); sent[1] := 'First Thing'; sent[2] := 'Second Thing'; sent[3] := 'Quit'; mc := 1; Menu(-1,-1); . . end. Performance of example: MainText is used as a variable to hold "red." The text foreground color is set to MainText (red) and then a string is written on the bottom line of the screen: "My Program, Copyright 1991, Your Company." Then a menu pops up. ************************************************************* MakeBox - Procedure Uses Magic Declaration: MakeBox(x,y,x1,y1 : integer) Description: MakeBox is a rather simple procedure which generates a box on the screen. The box will appear in BoxBack color, with a border of border color. x and y are the integer coordinates of the upper left corner, and x1 and y1 mark the lower right corner. If in text mode the upper left corner of the screen is 1,1 and the lower right is 80,25. In graphics modes the upper left is 0,0 and the lower right varies with the current graphics mode. In VGA 640 x 480, for instance, the lower right corner coordinates are 639,479. Considerations: Unlike the other pop-ups, this one does not save what is displayed under the box. There is no way to get rid of a MakeBox other than writing something else over it, or regenerating the screen from scratch. If you want a pop-up box that saves the previous image, use Pop and Restore, GetYN or GetAnyKey instead, but if you want an empty box, declare some sent[]s as strings of spaces. A range check error will occur if you pass coordinates that are not legal for the current video mode. For a centered box, you must pre-calculate the coordinates, there is no automatic centering. See Also: Pop, Restore. In text mode, not use background colors above 7. Example: program test; uses crt,magic; begin makebox(20,10,60,15); repeat until keypressed; XClear; . . end. Performance of Example: An empty box will appear until a key is pressed. Crt must be in the Uses line because Keypressed is a procedure within the Crt unit (Turbo.tpl). ************************************************************* Menu - Procedure Uses Magic Declaration: Menu(x,y : integer) Description: Menu pops a box on the screen showing lines of text from the array sent[1..18]. One of the lines is highlighted and a user can move the highlight to any of the other items by moving the mouse or pressing the up or down arrow keys. When the user presses [Enter] or clicks the left mouse button, the currently highlighted item number is assigned to the global byte variable mc. The pop-up box disappears and the array of strings, sent[1..18] is cleared. Two integer parameters are required, the first indicates the horizontal position of the upper left corner and the second is for the vertical position. If either integer is a negative number, that integer will be ignored and the menu will be centered on the screen in the corresponding dimension. Before calling Menu, a byte variable, mc should be given a value. Mc is the current MenuChoice, meaning the sent[] corresponding to mc is the one highlighted. If you state: mc := 1 then the first item on the menu will be highlighted. If you forget to assign mc, a random menu choice will be highlighted with your first call to Menu. When the user presses any non-arrow key or clicks a left mouse button, the pop-up Menu disappears, all sent[]s are set to '', and U will have a char value corresponding to the key pressed. If the left mouse button was clicked U will be char #174, and if the right button was pressed, U will be #175. You can then use u or mc to perform operations related to your user's choice. To have the menu return to the screen, sent[]s must be refilled with your strings and DoubleMenu must be called again. The usual way to use Menu is to put it into a repeat loop as shown in the example below. Considerations: Maximum sent[]s : 18; Should assign a value to mc of at least one and less than the maximum sent[]. Must reassign text to the sent[]s for subsequent calls to Menu. If in a graphics mode, you must use DefaultFont (0). In text mode, do not use background colors above 7. See also: sent[], Pop, GetYN, GetAnyKey, DoubleMenu Example: Program Test; uses magic; begin mc := 1; repeat sent[1] := 'Do Thing One'; sent[2] := 'Do Thing Two'; sent[3] := 'Do Thing tHree'; sent[4] := 'Do Thing Four'; sent[5] := 'Do Thing fiVe'; sent[6] := 'Do Thing Six'; sent[7] := ' Quit '; Menu(-1,-1); if (u = #174) or (u = #13) then case mc of 1 : Procedure1; 2 : Procedure2; 3 : Procedure3; 4 : Procedure4; 5 : Procedure5; 6 : Procedure6; 7 : u := #175; end; {case mc} u := upcase(u); case u of 'O' : Procedure1; 'T' : Procedure2; 'H' : Procedure3; 'F' : Procedure4; 'V' : Procedure5; 'S' : Procedure6; 'Q' : u := #175; #27: u := #175; end; {case u} until u = #175; CleanUp; end. Performance of example: Mc is set to 1 so when the menu pops up, the first item will be highlighted. Seven sent[]s are given strings. The Menu pops up and the user presses a key or operates the mouse. Then if U is #174, (because the left mouse button has been pressed) or U is #13, (the [Enter] key) then a case statement figures out what to do with the user's menu choice. If mc is between 1 and 6, one of the procedures is called. Of course, these procedures can do anything you wish, based upon what menu item the user has selected. The last menu choice (sent[7]) is 'Quit' and will cause this program to fall through and terminate. U is changed into an uppercase letter so that the following case will work whether the user presses a capital or small letter. This second case checks to see whether the user selected a menu item based upon the capitalized letter hints. You can also use function keys here. The #0 has already been stripped off, so if you get a ';' then the user pressed [F1] and probably wants 'help.' There is a boolean variable called Functkey which will now be true if the user pressed a function key, such as an arrow or [F1]. If the user actually pressed [;] then Functkey will be false. If you want to know what function key (or ALT + key) was pressed, call the function FunctAscii, which will return the extended ASCII character. Assuming the user did not select 'Quit' or press #27 (the [Escape] key) or the right mouse button, the menu process will repeat. When the user finally does choose to quit, the CleanUp procedure returns to DOS gracefully. ************************************************************* MouseInstalled - Function Uses Magic Declaration: (example) if MouseInstalled then Description: This boolean function returns true if a mouse and its driver are installed. See Also: Poll, SetMouseRows, SetMouseColumns Example: program test; uses video, graph, magic; begin if MouseInstalled = false then sent[1] := 'Mouse not found' else begin BestVideo; sent[1] := 'A mouse is present'; end; GetAnyKey(10,10); end. Performance of Example: If there is no mouse then MouseInstalled will be false and 'Mouse not found' will pop up in text mode; If there is a mouse, then 'A mouse is present' will appear in graphics mode. When the user presses a key, the program ends. ************************************************************* MusicOn - Global Variable Uses Magic Declaration: MusicOn := true; Description: This boolean variable controls whether the sound effects are allowed to play. The default for MusicOn is true. When MusicOn is set to false, calls to Pink, Twinkle, SoundUp, and SoundDown will be ignored until it is again set to true. Considerations: SPECIAL NOTE: The Turbo.tpl file supplied by Borland with Turbo Pascal Version 6.0 has a glitch in the built-in Delay procedure, which is used in the generation of sound effects. On machines faster than 30 mhz, Delay does not always work right. Borland has a free patch for this problem so your animations, sound effects and other uses of Delay will work properly on all standard IBM-compatibles. I have copied the patch files from Borland's BBS for you and they are on this disk. The patch is performed by Delaypat.Bat and to find out how to use it, read Delaypat.DOC. This Borland read-only BBS is a source of many wonderful bits of source code, and it is all free, except long-distance phone charges. With your modem, dial 1-408-439-9096. See Also: Pink, Twinkle, SoundUp, SoundDown. Example: program test; uses magic; begin sent[1] := 'Do you want sound effects? (Y/N)'; GetYN(-1,-1); if u = 'Y' then MusicOn := true else MusicOn := false; twinkle; end. Performance of Example: The user will be asked to press 'Y' or 'N' for sound effects. If the user selects 'Y' then MusicOn will be true and Twinkle will play. If the user selects 'N' then no twinkle will be heard. ************************************************************* OutFile - Global Variable Uses Magic Declaration: (example) assign(OutFile,'Things.Doc') Description: OutFile is declared globally as a file of type Text. It is used for sending text information from your program to disk using the automatic procedures File and FileWriteLn. Considerations: OutFile is for text only. Numeric values must be represented as strings for OutFile. You can override the automatic use of OutFile with standard Turbo Pascal techniques such as Assign, ReWrite and Close. As with any output file, make sure to close OutFile before quitting program if you use Turbo Pascal procedures, otherwise data may be lost. All Magic procedures which write to OutFile will automatically close it. See Also: InFile, FileRead, FileReadLn, NameInFile {Magic}; Assign, ReWrite, ReSet, Append, Write, WriteLn, Read, ReadLn, Rename, Erase, Close {Borland} Example: Program Test; uses magic; begin NameOutFile('TestFile.Txt'); rewrite(OutFile); writeln(OutFile,'This is the only string in the file.'); close(OutFile); end. Performance of example: The text file called OutFile within your program is associated with 'TestFile.Txt' on disk. Whether or not it exists, it will be recreated as an empty file with ReWrite. Then one line is written to the file and it is closed. If you were to investigate TestFile.Txt with a word processor you would find only one line of text: "This is the only string in the file." ************************************************************* NameInFile - Procedure Uses Magic Declaration: NameInFile(FileName : string) Description: This procedure automatically closes the present InFile if it is open then renames it to FileName. From this time until another call to NameInFile, the global string variable InFile will carry the name passed to NameInFile as FileName. Considerations: If FileName is a literal, not a string variable, then it must be enclosed in single quotation marks. FileName must be DOS-legal with up to 8 alphanumeric characters, an optional period, then up to a three character extension. InFile is used for text only and is read-only as used by FileRead and FileReadln. FileWrite and FileWriteLn will only work on OutFile. Full drive designator and pathnames are supported up to 76 characters. See Also: FileWrite, Filewriteln, FileRead, FileReadLn, NameOutFile. Example: Program Test; uses crt,magic; begin NameInFile('TestFile.Txt'); answer := FileReadLn; writeln(answer); repeat until keypressed; end. Performance of example: "Testfile.txt" is assigned to InFile. When FileReadLn is called, it looks to the disk for the file called Testfile.txt and reads one line. This line is displayed on the screen. The program terminates when the user presses any key. Crt must be in the Uses line because Keypressed is a procedure within the Crt unit (Turbo.tpl). ************************************************************* NameOutFile - Procedure Uses Magic Declaration: NameOutFile(FileName : string) Description: This procedure automatically closes the present OutFile if it is open then renames it to FileName. From this time until another call to NameOutFile, the global string variable OutFile will carry the name passed to NameOutFile as FileName. Considerations: If FileName is a literal, not a string variable, then it must be enclosed in single quotation marks. FileName must be DOS-legal with up to 8 alphanumeric characters, an optional period, then up to a three character extension. OutFile is used for text only and is write-only as used by FileWrite and FileWriteLn. FileRead and FileReadLn will only work on InFile. Full drive designator and pathnames are supported up to 76 characters. See Also: FileWrite, Filewriteln, FileRead, FileReadLn, NameInFile. Example: Program Test; uses magic; begin NameOutFile('TestFile.Txt'); FileWriteLn('This is a test.'); end. Performance of example: Examination with a word processor would reveal that there is a file on the disk called "Testfile.txt" and the last line in that file (and the only line if it was a new file) is "This is a test." ************************************************************* Number - Function Uses Magic Declaration: (example) i {integer variable} := number Description: This function takes the global string variable, Answer, and returns its contents as an integer variable. If there is any problem, Problem (global boolean variable) becomes true and Number will be 0. This is particularly useful after a call to Dialog, which assigns a string to the global string, Answer. Considerations: Must be within the range of an integer as defined by Turbo Pascal. See Also: Dialog, Answer. Example: program test; begin sent[1] := 'How many do you want?'; dialog(-1,-1); if number < 40 then do_something else do_different_thing; end. Performance of example: The user is presented with a question to which the answer is typed in the dialog box. Number converts the Answer to an integer. In this sample program, if the user typed a number less than 40 then the fictitious procedure do_something is executed, otherwise do_different_thing is executed. ************************************************************* OpenInFile - Procedure Uses Magic Declaration: OpenInFile Description: This seldom-used procedure is automatically called by other procedures within the Magic unit, but can be called manually too. It Opens and resets the InFile. See Also: FileRead, FileReadLn, NameInFile. Example: Program Test; uses crt, magic; begin NameInFile('Example.Doc'); if eof(InFile) then OpenInFile; answer := FileReadLn; write(answer); repeat until keypressed; end. Performance of example: If the last line of the file has been read then eof will be true. Eof is a boolean function returning true if End Of File has been reached. In that case, OpenInFile will reopen the InFile, effectively starting at the beginning. If Eof was true then the line displayed on the screen will be the first line in Example.doc. Crt must be in the Uses line because Keypressed is a procedure within the Crt unit (Turbo.tpl). ************************************************************* Pink - Procedure Uses Magic Declaration: Pink Description: Pink makes a sound typically indicating a key has been pressed or a small action has occurred. Considerations: The boolean Variable MusicOn must be true or Pink will not make a sound. The default status of MusicOn is true. It is possible that this will not work as expected on machines faster than 33mhz or when multitasking under DeskView or MS-Windows. Must put Crt in uses statement. Make sure to read the special note under MusicOn. See Also: MusicOn, Twinkle, SoundUp, SoundDown {Magic} Sound, NoSound, Delay {Borland} Example: Program Test; uses crt, magic; begin xclear; repeat u := readkey; pink; write(u); until (u = #27) or (u = #13); {Escape or Enter key} end. Performance of example: The screen will clear. Then every time a key is pressed, it's character will be shown on the screen and an audible click will be heard until the user presses #27, the [Esc] key. Crt must be in the Uses line because Readkey is a procedure within the Crt unit (Turbo.tpl). ************************************************************* PointerOff - Procedure Uses Magic Declaration: PointerOff Description: Turns off the mouse pointer or arrow. Considerations: See PointerOn. See Also: Poll, PointerOn, ResetMouse Example: Program Test; uses crt, video, graph, magic; var x,y : word; begin x := 0; y := 0; Bestvideo; PointerOff; repeat poll(px,py,left,right); lineto(px,py); x := x; y := y; until left; resetmouse; pointeron; pointertoxy(x,y); waste; repeat poll(x,y,left,right) until (keypressed) or (left) or (right); CleanUp; end. Performance of example: The program will switch to a graphics mode and there will be no mouse pointer. As long as the user moves the mouse, a trail of lines will appear on the screen. When the user clicks the left mouse button, the mouse pointer will reappear and the drawing of lines will cease. When the user presses any key or mouse button the program will terminate gracefully. Crt must be in the Uses line because Keypressed is a procedure within the Crt unit (Turbo.tpl). ************************************************************* PointerOn - Procedure Uses Magic Declaration: PointerOn Description: Turns on the mouse pointer or arrow. Considerations: Many mice require a call to ResetMouse before calling PointerON. You might also want to call PointerToXY to reset the mouse position to the current position. See Also: Poll, PointerOff, ResetMouse Example: Program Test; uses crt, video, graph, magic; var x,y : word; begin x := 0; y := 0; Bestvideo; PointerOff; repeat poll(px,py,left,right); lineto(px,py); x := px; y := py; until left; resetmouse; pointertoxy(x,y); pointeron; waste; repeat poll(x,y,left,right) until keypressed or left or right; CleanUp; end. Performance of example: The program will switch to a graphics mode and there will be no mouse pointer. As long as the user moves the mouse, a trail of lines will appear on the screen. When the user clicks the left mouse button, the mouse pointer will reappear and the drawing of lines will cease. When the user presses any key or mouse button the program will terminate gracefully. Crt must be in the Uses line because Keypressed is a procedure within the Crt unit (Turbo.tpl). ************************************************************* PointerToXY - Procedure Uses Magic Declaration: PointerToXY(x,y : word); Description: Moves the mouse pointer to coordinates x and y. Considerations: If the pointer is turned off (PointerOff) then the (graphics) CP (Current Position) will be moved to x and y. See Also: Poll, PointerOff, Pointeron, ResetMouse. Example: Program Test; uses crt, graph, video, magic; var x,y : word; begin Bestvideo; x := getmaxx div 2; y := getmaxy div 2; PointerOn; PointerToXY(x,y); repeat until keypressed; CleanUp; end. Performance of example: The current position is moved to x and y, which have been assigned the center of the screen. The pointer will appear there. The program waits for the user to press a key, then terminates gracefully. Crt must be in the Uses line because Keypressed is a procedure within the Crt unit (Turbo.tpl). ************************************************************* Pop - Procedure Uses Magic Declaration: Pop(x,y : integer) Description: This is the simplest version of a pop-up text box in the Magic kit. Magic has a pre-declared array of 76-character long strings called sent[]. Before a call to Pop, these strings are all empty. You must assign text to as many strings as you wish to display. They must be in order. The first line displayed will be sent[1], the second line will be sent[2], and so on. Any strings after the last one to which you have assigned a line of text will be ignored by Pop. Pop requires two integers, x and y. X is the horizontal coordinate and y is the vertical coordinate. These coordinates mark the position on the screen where the upper left corner of the pop up box will occur. The whole box is 4 columns wider than the widest sent[] and two rows taller than the total number of sent[]s which contain text. If you are in text mode the upper left corner of the screen is 1,1 and the lower right corner is 80,25. In any of the graphics modes, the upper left corner is 0,0 and the lowest right varies. in CGA, 2-color mode (640 x 200), for instance, the lower right corner is 639,199. In graphics or text mode, if either x or y are a negative integer, the box will be automatically centered on the screen in the corresponding dimension. When Pop starts, it first saves the current contents of the screen to memory. Pop will then place its pop-up box on the screen. There is no wait for user input built in. After a call to Pop, the program will progress immediately to the next step. Therefore, a usual step is to call WaitForUser so the pop-up box will be seen before the program continues. Then call Restore to get rid of the pop-up box and replace the original screen contents. Actually, using Pop may be rare, since Pop, WaitForUser and Restore are automatically incorporated in GetAnyKey, GetYN, Dialog, Menu and DoubleMenu. Considerations: Must not use x or x integers that are beyond the possible range for the current video mode. (except negative integers, which will center the pop-up box) It is advisable to call Restore some time soon after done with Pop. Otherwise 4k of RAM is occupied with the saved screen in text mode, and up to around 300k in VGA graphics mode. There can be up to 10 text screens saved at one time when there is sufficient ram space. If an attempt is made to save more screens than possible, for instance, calling Pop 11 times in a row, only the first screen(s) saved will be available for a Restore. If your pro- gram exceeds available RAM space, the IDE will return an out of memory notice. If in a graphics mode, must use Borland DefaultFont (#0, bit-mapped). In text mode, do not use background colors above 7. See Also: Restore, GetAnyKey, GetYN, Dialog, Menu, DoubleMenu Example: Program Test; uses magic; begin sent[1] := 'This is a line of text'; sent[2] := 'This is another line'; sent[3] := 'This line tells the user to press any key'; pop(1,1); WaitForUser; Restore; end. Performance of example: Since there are 3 sent[]s a text box will pop up that is three lines tall. The third line is the widest, and therefore the box will be just large enough to neatly contain the third, widest line. Pop is given the coordinates of 1,1, so the upper left corner of the pop up box will be in the extreme upper left corner of the screen. WaitForUser will stall the program until the user presses any key or clicks a mouse button. Then Restore restores the screen as it was before the pop-up box appeared, which is silly in this program, because it ends in the next line. ************************************************************* Problem - Global Variable Uses Magic Declaration: (example) if problem then Description: Problem is a global boolean variable that is usually set to false as any graphics or i/o procedure in the Magic unit starts. Then, if a problem occurs, the procedure will handle the problem as cleanly as possible and set Problem to true. For instance, if FileWrite is asked to write a string to a write-protected disk, the program will not crash, but will not write to the disk, and Problem becomes true. You can then use Problem to cause a branch in your program to handle the 'problem.' Considerations: Problem must be checked before a call to any other procedure in the Magic unit because the next procedure will reset Problem. Example: Program Test; uses magic; begin NameOutFile('testfile.txt'); FileWriteLn('This is a line of nonsense.'); if Problem {= true} then begin sent[1] := 'Problem writing to disk'; sent[2] := 'Disk may be full or write-protected'; sent[3] := 'Press any key to continue..'; GetAnyKey(-1,-1); end; . . end. Performance of example: This program tries to write, "This is a line of nonsense" to a disk file called "Testfile.txt." If this proves impossible, then Problem is true and a three-line notice pops up on the screen. ************************************************************* Px - Global Variable Uses Magic Declaration: (example) PutPixel(px,py,white) Description: Px is a global variable defined in magic.tpu as a word (positive integer). The most common use of px is to designate a horizontal screen position. ************************************************************* Py - Global Variable Uses Magic Declaration: (example) PutPixel(px,py,white) Description: Py is a global variable defined in magic.tpu as a word (positive integer). The most common use of py is to designate a vertical screen position. ************************************************************* ResetMouse - Procedure Uses Magic Declaration: ResetMouse Description: This restores the mouse situation to its default parameters. The mouse pointer will be relocated to the center of the screen and the left and right mouse button status will be not pressed. Considerations: Some older mice have glitchy mouse driver software, and frequent calls to ResetMouse will not hurt! Call PointerToXY if you want the mouse position to be as it was before ResetMouse. See also: Poll, PointerToXY, PointerOn, PointerOff ************************************************************* Restore - Procedure Uses Magic Declaration: Restore Description: Restore replaces the screen contents with a picture saved before a call to Pop. GetAnyKey, GetYN, Dialog, Menu, and DoubleMenu call Restore automatically when they finish, but Pop does not. Restore also frees the memory which was held for the saved screen image. Considerations: In graphics mode, it is easily possible to exceed avail- able RAM space. Call Restore as soon as possible to avoid stacking up too many pop- ups. In VGA, one pop-up may occupy all available space! Repeated calls to Restore brings back the image preceding each Pop. Restore is a smart procedure, if called more times than the number of stored screens, it has no effect. See Also Pop, MakeBox. Example; Program Test; uses crt, Magic; begin sent[1] := 'This box is going to'; sent[2] := 'be difficult to read'; Pop(1,1); delay(1000); sent[1] := 'because this screen'; sent[2] := 'is going to cover it up'; sent[3] := 'Press any key to get rid'; sent[4] := 'of this box'; pop(5,2); WaitForUser; Restore; WaitForUser; Restore; delay(1000); CleanUp; end. Performance of example: A box containing two lines of text appears in the extreme upper left corner, then one second later, a four-line box partially covers it up. When the user presses a key, the second box disappears so that the first one can be seen clearly. When the user presses a key again, the first box disappears leaving a blank screen. After a one second delay, the program terminates cleanly. Crt must be in the Uses line because Delay is a procedure within the Crt unit (Turbo.tpl). ************************************************************* Right - Global Variable Uses Magic Declaration: (example) if right = false then Description: Right is a global boolean variable used to record the status of the left mouse button. If right = true then the right mouse button has been pressed. Considerations: The status of Right will change with every call to Poll, Waste, WasteMouse, ResetMouse or procedures within Magic which handle text or pop up boxes. See Also: Poll, Waste, WasteMouse, ResetMouse, left Example: Program Test; uses magic; var x, y : word; begin sent[1] := 'Nothing will change until you click the'; sent[2] := 'right mouse button'; Pop(-1,-1); WasteMouse; repeat poll(x,y,left,right) until right; end. Performance of example: A box containing two lines of text will stay on the screen until the user clicks the right mouse button. The program will then terminate. ************************************************************* SansSerif - Procedure Uses Magic Declaration: SansSerif Description: Calling the procedure SansSerif makes the Borland Sansserif font available to graphic-based programs. This font will be compiled into the .EXE file. SANSSERIF.CHR does not have to accompany the finished product. Considerations: Compiled .EXE size increases by about 17k. Must add Graph, Video, Fonts, Magic to Uses statement. Do not use SansSerif with Pop, GetAnyKey, GetYN, Dialog, Menu or DoubleMenu. To use SansSerif font, type: SetTextStyle(SansSerifFont,d,x) where d represents direction (0 is horizontal), and x represents the size of the text, ranging from 1 to 10. See Also: BestVideo, CGAVideo, EGAVideo, VGAVideo, Small, Gothic, Triplex {Magic} SetTextStyle {Borland} Example: Program Test; uses crt, graph, video, fonts, magic; begin BestVideo; SansSerif; SetTextStyle(3,0,2); {3 is const: SansSerifFont} outtextxy(100,90,'Test'); repeat until keypressed; end. Performance of example: Sansserif font information is compiled into the .EXE file. The highest resolution graphics mode is selected. SansSerifFont is selected for output, then the word 'Test' is written on the screen. When the user presses a key, the program terminates. Crt must be in the Uses line because Keypressed is a procedure within the Crt unit (Turbo.tpl). ************************************************************* SetMouseColumns - Procedure Uses Magic Declaration: SetMouseColumns(max, min : word) Description: You can limit the travel of the mouse on the screen with SetMouseColumns and SetMouseRows. SetMouseColumns needs two integer numbers, the first is the maximum column that the mouse is allowed and the second is the minimum column. Considerations: Text mode is usually based on CGA high-res (640 x 200). To work with a specific text location, divide the mouse x and y coordinates by 8. To place a character in the third column of the second row of the screen (near the upper left corner) you would work at coordinate 16,8. Do not use this procedure unless MouseInstalled. See Also: Poll, PointerToXY, SetMouseRows Example: Program Test; uses video, graph, magic; begin VGAVideo; SetMouseColumns(319,0); SetMouseRows(199,0); PointerOn; repeat poll(px,py,left,right) until left; end. Performance of example: This example sets the video mode to VGA but allows the mouse to move only within the upper left corner of the screen as if working with the more limited resolution of CGA 4-color mode. ************************************************************* SetMouseRows - Procedure Uses Magic Declaration: SetMouseRows(max, min : word) Description: See SetMouseColumns, above. SetMouseRows needs two integer numbers, the first is the maximum row that the mouse is allowed and the second is the minimum row. Considerations: Text mode is usually based on CGA high-res (640 x 200). To work with a specific text location, divide the mouse x and x coordinates by 8. To place a character in the third column of the second row of the screen (near the upper left corner) you would work at coordinate 16,8. Do not use this procedure unless MouseInstalled. See Also: Poll, PointerToXY, SetMouseColumns Example: Program Test; uses video, graph, magic; begin VGAVideo; SetMouseColumns(319,0); SetMouseRows(199,0); PointerOn; repeat poll(px,py,left,right) until left; end. Performance of example: This example sets the video mode to VGA but allows the mouse to move only within the upper left corner of the screen as if working with the more limited resolution of CGA 4-color mode. ************************************************************* Shadow - Global Variable Uses Magic Declaration: (example) shadow := color; Description: This sets the color of shadows at the bottom and right edge of pop-up text boxes, where 'color' is an integer from 0 to 15 or a color constant as defined by Borland. Works in graphics and text mode. Considerations: May not have the expected effect when used with the limited palettes of 4-color CGA (mode 0,1 or 2), 2-color CGA or Hercules. In text mode, only 8 colors are available: 0 - 7, for correct operation (hiding of the cursor). See also: MainText, MainBack, BoxText, BoxBack, BarText, BarBack, border. Example: program test; uses magic; begin sent[1] := 'First Thing'; sent[2] := 'Second Thing'; sent[3] := 'Quit'; mc := 1; shadow := Cyan; Menu(-1,-1); . . end. Performance of example: A menu pops up with a LightCyan shadow. ************************************************************* Small - Procedure Uses Magic Declaration: Small Description: Calling the procedure Small makes the Borland Small font available to graphic-based programs. This font will be compiled into the .EXE file. SMALL.CHR does not have to accompany the finished product. Considerations: Compiled .EXE size increases by about 17k. Must add Graph, Video, Fonts, Magic to Uses statement. Do not use Small for Pop, GetAnyKey, GetYN Dialog, Menu or DoubleMenu. To use Small, type: SetTextStyle(SmallFont,d,x) where d is an integer representing direction (0 is horizontal) and x is an integer from 1 to 10 representing relative size of the text. See Also: BestVideo, CGAVideo, EGAVideo, VGAVideo, SansSerif, Triplex, Gothic {Magic} SetTextStyle {Borland} Example: Program Test; uses crt, fonts, video, graph, magic; begin BestVideo; Small; SetTextStyle(SmallFont,0,2); outtextxy(100,90,'Test'); repeat until keypressed; end. Performance of example: Small font information is compiled into the .EXE file. The highest resolution graphics mode is selected. SmallFont is selected for output, then the word 'Test' is written on the screen. When the user presses a key, the program terminates. Crt must be in the Uses line because Keypressed is a procedure within the Crt unit (Turbo.tpl). ************************************************************* SoundDown - Procedure Uses Magic Declaration: SoundDown Description: SoundDown makes a sound typically indicating a window is being closed or a large action has occurred. Considerations: The boolean Variable MusicOn must be true or SoundDown will not make a sound. The default status of MusicOn is true. It is possible that this will not work as expected when multitasking under DeskView or MS-Windows. Make sure to read the special note under MusicOn. See Also: MusicOn, Twinkle, SoundUp, Pink {Magic} Sound, NoSound, Delay {Borland} Example: Program Test; uses magic; begin sent[1] := 'Sound effect. Press any key...'; SoundUp; GetAnyKey(-1,-1); SoundDown; end. Performance of example: A SoundUp sound will occur. a box pops up on the screen with one line of text. When the user presses any key, a SoundDown will occur and the program terminates. ************************************************************* SoundUp - Procedure Uses Magic Declaration: SoundUp Description: SoundUp makes a sound typically indicating a window is being opened or a large action has occurred. Considerations: The boolean Variable MusicOn must be true or SoundUp will not make a sound. The default status of MusicOn is true. It is possible that this will not work as expected when multitasking under DeskView or MS-Windows. Make sure to read the special note under MusicOn. See Also: MusicOn, Twinkle, SoundDown, Pink {Magic} Sound, NoSound, Delay {Borland} Example: Program Test; uses magic; begin sent[1] := 'Sound effect. Press any key...'; SoundUp; GetAnyKey(-1,-1); SoundDown; end. Performance of example: A SoundUp sound will occur. a box pops up on the screen with one line of text. When the user presses any key, a SoundDown will occur and the program terminates. ************************************************************* TextVideo - Procedure Uses Magic Declaration: TextVideo Description: This returns a program from a graphics video mode to text mode, the default startup condition. The screen is cleared. Considerations: Any memory held for a saved screen from a pop-up box will be released. Will not work a prior call to BestVideo, CGAVideo, HercVideo, EGAVideo, or VGAVideo. See Also: BestVideo, CGAVideo, HercVideo, EGAVideo, VGAVideo. Example: Program Test; uses graph, video, magic; begin BestVideo; sent[1] := 'This is graphics mode'; sent[2] := 'Press any key to see text mode'; GetAnyKey(-1,-1); TextVideo; sent[1] := 'This is text mode'; sent[2] := 'Press any key to quit'; GetAnyKey(-1,-1); end. Performance of example: A box pops up in the best graphics mode the computer can display. When the user presses a key, the computer switches to text video mode and another box appears until the user presses a key again. ************************************************************* Twinkle - Procedure Uses Magic Declaration: Twinkle Description: Twinkle makes a sound typically indicating an action has positively been completed. Considerations: The boolean Variable MusicOn must be true or Twinkle will not make a sound. The default status of MusicOn is true. It is possible that this will not work as expected when multitasking under DeskView or MS-Windows. Make sure to read the special note under MusicOn. See Also: MusicOn, SoundUp, SoundDown, Pink {Magic} Sound, NoSound, Delay {Borland} Example: Program Test; uses magic; begin sent[1] := 'Sound effect. Press any key...'; GetAnyKey(-1,-1); Twinkle; end. Performance of example: A box will pop up containing one line of text. When the user presses any key, the Twinkle sound will occur and then the program will terminate. ************************************************************* Triplex - Procedure Uses Magic Declaration: Triplex Description: Calling the procedure Triplex makes the Borland Triplex font available to graphic-based programs. This font will be compiled into the .EXE file. TRIPLEX.CHR does not have to accompany the finished product. Considerations: Compiled .EXE size increases by about 17k. Must put Graph, Fonts, Video, and Magic in Uses statement. Do not use Triplex with Pop, GetAnyKey, GetYN, Dialog, Menu or DoubleMenu. To use Triplex font type: SetTextStyle(TriplexFont,d,x) where d is an integer representing the direction (0 is horizontal) and x is an integer from 1 to 10 representing the relative size of the text. See Also: BestVideo, CGAVideo, EGAVideo, VGAVideo, SansSerif, Small, Gothic {Magic} SetTextStyle {Borland} Example: Program Test; uses crt, fonts, graph, video, magic; begin BestVideo; Triplex; SetTextStyle(TriplexFont,0,2); outtextxy(100,90,'Test'); repeat until keypressed; end. Performance of example: Triplex font information is compiled into the .EXE file. The highest resolution graphics mode is selected. SmallFont is selected for output, then the word 'Test' is written on the screen. When the user presses a key, the program terminates. Crt must be in the Uses line because Keypressed is a procedure within the Crt unit (Turbo.tpl). ************************************************************* U - Global Variable Uses Magic Declaration: example u := readkey Description: U is a general purpose global char variable declared in the Magic unit for internal use, but available for any use within your program. U originally stood for UserInput. Considerations: U is reset by several of the functions and procedures in the Magic Unit. Do not assume the value of U will remain the same after use of procedures such as Dialog, XReadKey, etc. Example: Program Test; uses magic; begin answer := ''; repeat u := upcase(readkey); if ord(u) > 31 then begin answer := answer + u; write(u); end; until (u = #27) or (u = #13); . . end. Performance of example: This program is a very stripped down way to get input from the keyboard and change it in to an all uppercase string. ************************************************************* VGAVideo - Procedure Uses Magic Declaration: VGAVideo Description: This initializes the system in VGA graphics mode. VGA video driver will be automatically compiled into the .EXE program file, eliminating the need for external EGAVGA.BGI file. Considerations: The resulting .EXE file is much smaller than one compiled after a call to BestVideo. BestVideo builds all graphics drivers into the .EXE file, but VGAVideo builds in only the EGAVGA driver. This must be called only once during a program. Video.Tpu must be available until after compilation. Must put Video, Graph, Magic in Uses statement. There are several graphmodes available for VGA. The default mode for Magic is 640x480 16-color (GraphMode 2). See the Borland manuals. VGA graphics is memory hungry. It is possible to fill all available RAM with concurrent Pops, GetYNs, Menus, etc. In fact two full screen save can entirely fill RAM. Use small pop-ups or call Restore early and frequently when programming for Vga. See Also: BestVideo, HercVideo, CGAVideo, EGAVido {Magic}; SetGraphMode, Setcolor, etc. {Borland} Example: Program Test; uses crt, video, graph, magic; begin VGAVideo; rectangle(10,10,20,20); repeat until keypressed; CleanUp; end. Performance of example: The system is put in VGA graphics mode. A small rectangle is displayed in the upper left corner of the screen until any key is pressed. The program then terminates gracefully. Crt must be in the Uses line because Keypressed is a procedure within the Crt unit (Turbo.tpl). ************************************************************* WaitForUser - Procedure Uses Magic Declaration: WaitForUser Description: This simple procedure stalls the computer until the user presses a key or clicks a mouse button. See Also: Pop, XReadKey Example: Program Test; uses fonts, graph, video, magic; begin BestVideo; Triplex; SetTextStyle(TriplexFont,3,5); outtextxy(100,90,'Press any key'); WaitForUser; CleanUp; end. Performance of example: This program displays the word, "Test" then waits for the user to press a key or click a mouse button. ************************************************************* Waste - Procedure Uses Magic Declaration: Waste Description: This procedure makes sure there is nothing in the keyboard buffer and if a mouse is installed, waits until there are no mouse buttons pressed. U is assigned #126, an uncommon ASCII character. Considerations: WasteMouse is automatically called by Waste. See Also: Pop, XReadKey, WasteMouse Example: Program Test; uses crt, magic; begin writeln('Without Waste, keyboard buffer could cause'); writeln('portions of the program to skid past before'); writeln('the user knows what is happening'); Waste; u := XReadKey; clrscr; writeln('This is a problem when the user holds a key'); writeln('down too long'); Waste; u := XReadKey; clrscr; end. Performance of example: Three lines appear on the screen. The keyboard buffer is cleared out and the program waits until no mouse buttons are pressed. Then the program waits for a key to be pressed. Then the screen is cleared and two more lines of text appear. Again, Waste clears the buffer and waits if a mouse button is pressed, and then waits for the user to do something. Then the screen clears and the program terminates. Crt must be in the Uses statement because clrscr is a procedure within the Crt unit (Turbo.tpl). ************************************************************* WasteMouse - Procedure Uses Magic Declaration: WasteMouse Description: This simple procedure stalls the computer if any mouse buttons are pressed and waits until no mouse buttons are pressed. See Also: Waste Example: Program Test; uses magic; var x,y : word; begin sent[1] := 'Click a mouse button to end this program'; Pop(-1,-1); WasteMouse; repeat poll(x,y,left,right) until left or right; end. Performance of example: A sentence appears on the screen until a mouse button is pressed. ************************************************************* XClear - Procedure Uses Magic Declaration: XClear Description: Clears the screen and sets the background color to MainBack. Considerations: You may not get the effect expected when in CGA or Hercules modes if the selected MainBack color is not one in the current color palette. See Also: BestVideo, HercVideo, CGAVideo, EGAVido {Magic}; SetGraphMode, Setcolor, etc. {Borland} Example: Program Test; uses crt, video, graph, magic; begin VGAVideo; rectangle(10,10,20,20); sent[1] := 'Press any key...'; Pop(30,30); repeat until keypressed; XClear; sent[1] := 'Press any key...'; Pop(400,400); waste; repeat until keypressed; end. Performance of example: A small square appears near the upper left corner of the screen along with a box with a line of text. When a key is pressed, the screen clears and a box containing one line of text appears near the lower right corner. When a key is pressed again, the program ends. Crt must be in the Uses line because Keypressed is a procedure within the Crt Unit (Turbo.tpl). ************************************************************* XReadKey - Function Uses Magic Declaration: (example) u := XReadKey Description: Like Turbo Pascal's ReadKey, this returns a character as soon as a key is struck. Additionally, XReadKey, returns a character if the mouse is moved or a mouse key is pressed. If the mouse is moved to the right by 8 or more pixels, the character returned will be #170, and to the left will return #171. Moving the mouse up by 4 or more pixels will return #173, and down returns character #172. If the left button is pressed then #174 is returned and the right mouse button is #175. Considerations: XReadKey calls Waste before any other action. See Also: XReadLn, Waste {Magic}; ReadKey {Borland} Example: Program Test; uses crt, magic; var i : integer; begin . . repeat u := upcase(XReadKey); if u = #0 then {then it must be a function key} begin u := readkey; {no need for XReadKey here} if u = 'H' then u := #173; {up arrow} if u = 'P' then u := #172; {down arrow} end; case u of #172 : inc(i); #173 : dec(i); 'Z' : do_something_else; end; {case} until (u = #27) or (u = #175); {[Esc] or right button} . . end. Performance of example: Computer waits for user input. If user moves the mouse up (#173) or down (#174) or presses the up or down arrow keys, then the variable i is incremented or decremented. If the user presses 'z' or 'Z' then do_something_else (an imaginary procedure) is called. Z can be upper or lowercase because when XReadKey is assigned to U it is first converted to uppercase by Upcase {Borland}. This repeats until the user presses the [Esc] key (#27) or clicks the right mouse button (#175). Because there is a call to the Borland procedure Readkey, Crt must be in the Uses line (readkey is in the Crt unit (Turbo.tpl), but XReadKey itself would not require Crt in the uses line because Magic.tpu automatically accesses Crt. ************************************************************* XReadLn - Function Uses Magic Declaration: (example) Tempstring := XReadLn(x,y,HowLong) Description: You will find this very useful in database applications where the user has to fill in blanks in a form. Unlike Borland's Readln procedure this allows you to limit the length of a string the user can type. This is similar to Turbo Pascal's Gotoxy combined with readln. XReadLn need three integer variables. The first two are the x and y screen coordinates of the upper left corner of the place where the user's input will be displayed. X is the horizontal position and y is the vertical. In text video mode the upper left corner of the screen is 1,1 and the lower right corner is 80,25. In graphics modes the upper left corner is 0,0 and the lower right varies. In the CGA 320x200 mode, for instance, the lower right corner would be 319,199. The last number required, HowLong, is an integer for the number of characters you will allow in the string. Example: if you have a form in which the user is to type a 4-digit number in a space, you call XReadLn with the x and y position of the start of the space, then 4, to limit the length of the number the user may enter to 4 digits. When the user presses [Esc] or [Enter] or clicks a mouse button, XReadLn is finished. Considerations: XReadKey calls Waste before any other action. Maximum string length is 76 characters. This procedure uses XReadKey, so with wise programming you can answer function key responses and mouse actions within the typing of a string. This function is useful for reading from the keyboard only, not for reading files. Always set textcolor and textbackground before calling XReadLn, because otherwise, it will use the most recently assigned colors, which might be shadow and border, (default black and black!) after a pop-up box. No automatic centering is available. Negative coordinates will have unpredictable results - probably a crash! See Also: XReadLn, Waste {Magic}; Readln, Textcolor, Textbackground {Borland} Example: Program Test; uses crt,magic; var namestring : string; begin gotoxy(1,10); write('What is your name?'); textcolor(white); textbackground(blue); namestring := xreadln(20,10,40); end. Performance of example: At 1,10, "What is your name?" appears on the screen. At the end of this line a cursor appears and the user is expected to type a name. The user's text will be white and the background color will be blue. The user cannot type beyond 40 characters. When the user presses [Enter] or [Esc] or clicks a mouse button, the program ends. Crt must be in the Uses line because GotoXY is a procedure within the Crt unit (Turbo.tpl). ************************************************************* ADVANTAGES OF HAVING THE SOURCE CODE: * With the easy-to-understand source code, you can make modifications to customize it exactly to your needs. * You can learn many 'secret' or hard to find Turbo Pascal programming techniques. * Even though Magic.tpu takes little room and runs quite fast, and even though Turbo Pascal is very smart and only builds code that is actually called in to .EXE files, you can strip down Magic.Tpu for even greater efficiency. * You can use portions of the source code as a frame work, changing this or that, inserting your own stuff, and build amazing programs of your own invention. * You can look at my approach to programming and laugh, possibly commenting under your breath about how you would have done it better. Then, with the source code in your possession, you can do it better! Notice: This is shareware. Feel free to copy and distribute without modification. If you use any portion of the Magic Unit in your programs then registration is a legal necessity. Send $29.95 to Another Company. Complete, well-documented easy-to-understand source code is available. For registration + registration, send $59.90. Send US funds drawn on a US bank to: Another Company P.O. Box 298 Applegate, OR 97530 USA 503-846-7884 Even though this seems quite bug-free to me, it is version 1.0 and you may find a surprise or two. I make no warranty. Thanks for trying this software. Please feel free to submit bug reports, which I will turn into fixes in later versions. - Jeff - October 28, 1991 P.S. If you require technical assistance, you can try to phone me at 503-846-7884. Best bet is 9-5 weekdays, but I'm not always available. P.S. #2 Since you are going to write some wonderful programs, you might as well start making money with them! You won't have to work in an office doing programming for someone else. You can write exactly the kind of programs you want to write, and make money at home! The 'secret' is shareware. Does it work? You bet! You can easily have a small success, making some extra spending money each month, or with some practice, you can have a wild success, and make a fine living! There are some millionaires who make their ever-growing fortune entirely through shareware. ANOTHER COMPANY shows you everything. Besides our own shareware successes, including WRITER'S DREAM, BICYCLE TUNE-UP AND REPAIR, MONEY, BLACKBOARD, BETTER EYESIGHT, WHAT'S IN THAT BOX? and THE UNIVERSAL CONVERTER, we have researched the shareware market, we have interviewed other shareware authors and have learned about all sides of the rapidly expanding shareware business. We show you how to write programs that capture the public's interest, how to make sure your customers 'register', and how to get money by other means through your shareware. We show you more. We show you frequency charts indicating which types of programs sell best, we offer suggestions for programs as yet unwritten, we talk about your on-disk instruction manuals, we even show you how to write user-friendliness into your programs. Can you succeed without SUCCESS WITH SHAREWARE? Yes! But why do it the hard way? We have learned all the super-professional approaches, the pitfalls and the shortcuts. We'll tell you all about it, and then instead of stumbling around for the first couple of years, you'll be a professional from the start! To get your copy of SUCCESS WITH SHAREWARE! (which is not shareware, itself - only available from Another Company), send $19.95. Please specify if you need 3.5" disk size. Thanks, - Jeff Napier - January 9, 1992 You can order products by writing your order on plain paper, or by printing the included ASCII file called Order.frm, or by phoning 1-503-846-7884, generally weekdays between 9 and 5, west coast time.