Prima Shareware 3

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

/ Prima Shareware 3 / DuCom_Prima-Shareware-3_cd1.bin / PROGRAMO / PASCAL / PMAGIC / MAGIC.DOC < prev next >

Wrap

Text File | 1992-11-16 | 139.0 KB | 3,573 lines

PASCAL MAGIC Version 3.01 Magic Unit Reference File An Add-in For Borland Turbo Pascal, Version 7.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. The mouse procedures provide a graphics cursor whether or not a mouse is installed and it can be driven from keyboard or mouse. * Display most .PCX files from within your programs with a single line of code. * Built-in 256-color VGA and Super-VGA 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. * Source code is available so you can study and customize Magic procedures to your needs. * Pascal Magic coexists peacefully with most other programming libraries. 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 $39.95 to Another Company. Complete, well-documented easy-to-understand source code is available. For registration + source code, send $79.90. Send US funds drawn on a US bank to: Another Company P.O. Box 298 Applegate, OR 97530 USA 503-846-7884 Please add $3 US postage ($5-Canada; &7-Overseas) per order. Please add $1 if you need 3.5" disk size. Even though this seems quite bug-free to me, 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.) If you want to become familiar with the look and feel of Pascal Magic, you might want to skim the tutorial file starting at program #6 (prog6). Note: Fonts2.tpu, Fonts.tpu, Video.tpu, and Borland's Graph.tpu must be in the same sub-directory in which you keep your .tpu files. Note: Pascal Magic version 3.0 is not backward compatible with versions 2.0 or 1.0. Note: Pop-up text box routines do not have built-in error checking for size, screen position or memory usage. Note: Borland Pascal with Objects contains three compiler versions to run under DOS real mode, DOS protected mode and Windows. Pascal Magic is for DOS real mode programs only, and will not run properly under the protected mode and Windows compilers. It will run, but there is a small "bug" in the way the other compilers juggle the interrupt vector table, even if compiling in real mode. The result of using any compiler other than TURBO.EXE with MAGIC.TPU is that computers without a mouse will exhibit erratic cursor behavior. NOTE: Because of the heap requiremets of the IDE plus MAGIC.TPU, you must compile to disk. To set this adjustment, select COMPILE from the top menu, then select "COMPILE TO DISK." 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, string[80] 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 80 characters. See also: Dialog Example: program test; uses magic; begin Sent[1] := 'Write your answer here'; Present.Dialog(1,1); if copy(Answer,1,2) = 'I ' then User_Started_With_I; . . end. ************************************************************* BarBack - Global Variable, byte Description: This sets the background color for lightbar backgrounds in menus, where 'color' is an integer from 0 to 7, in text mode or 0 to 15 in most graphics modes, 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. In text mode, because backgrounds are limited to 8 colors, only the values 0 - 7 works as expected. 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; Present.Menu(-1,-1); . . end. ************************************************************* BarText - Global Variable, byte 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; Present.Menu(-1,-1); . . end. ************************************************************* BestVideo - Procedure 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. Considerations: Bestvideo does not auto-detect Super-VGA equipment, and provides VGA-Hi 640 x 480 16-color on Super-VGA systems. See also: CGAHiVideo, CGALoVideo, EgaHiVideo, EGALoVideo, HercVideo, VgaHiVideo, VGALoVideo, SVGAVideo, all Borland Graph procedures & functions. Example: program test; uses crt,graph,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 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. ************************************************************* Bird - Procedure Description: A sound effect. Considerations: Calls to Bird are ignored if MusicOn (global boolean) is false. example: program test; uses magic; begin . . MusicOn := true; Bird; end. ************************************************************* BitMap - Procedure Description: Causes OutText, and OutTextXY to use the "DefaultFont" or the built in (into GRAPH.TPU) 8 x 8 bitmapped font. Considerations: Use this after calls to Triplex, Script, etc or SetTextStyle, to return to 8 x 8 bitmapped font. See Also: Triplex, BitMap, Little, Sansserif, Gothic, Script, Italic, European {Magic} Settextstyle, DefaultFont, SetUserCharSize {Borland} Example: program test; uses graph, magic; begin vgahivideo; triplex; OutTextXY(0,10,'This is Triplex font'); BitMap; OutTextXY(0,40,'This is the Bitmap font'); settextstyle(0,0,4); OutTextXY(0,100,'This is large Bitmap'); BitMap; OutTextXY(0,200,'Back to normal'); WaitForUser; CleanUp; end. ************************************************************* Bold - Procedure Description: Calling the procedure Bold makes the Borland Bold font available to graphic-based programs. This font will be compiled into the .EXE file. Bold.CHR does not have to accompany the finished product. Considerations: Compiled .EXE size increases by about 17k. Dimensions of the Bold font can be changed with SetTextStyle and SetUserCharSize. Bold is font #10 (for use with SetTextStyle). See Also: SansSerif, BitMap, Triplex, Little, Italic, Script, European, Gothic, Simple, Lcom {Magic} SetUserCharSize, SetTextStyle {Borland} Example: Program Test; uses crt, graph, magic; begin BestVideo; Bold; OutTextXY(0,0,'Regular-size Bold'); SetTextStyle(10,0,9); OutTextXY(100,100,'Huge'); WaitForUser; end. ************************************************************* Border - Global Variable 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?'; Present.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 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?'; Present.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. ************************************************************* Boxo - Object Description Boxo is the object level responsible for calculating and management of the pop-up boxes in text and graphics modes. Usually, it's methods are called by instances of it's descendant, Presento (which see). Boxo contains these methods: constructor Init(x,y : integer); procedure textmake(x,y : integer); virtual; procedure make(x,y : integer); virtual; destructor Done; virtual; For more information, look up these methods by name. ************************************************************* BoxText - Global Variable 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?'; Present.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. ************************************************************* Bugle - Procedure Description: A sound effect. Considerations: Calls to Bugle are ignored if MusicOn (global boolean) is false. example: program test; uses magic; begin . . MusicOn := true; Bugle; end. ************************************************************* Center - Global Variable, boolean Description: Center is used to track status of the center mouse button with three-button mice. When true, the center button has been pressed as of the last call to Poll. Considerations: With two-button mice, or when no mouse is installed, Center is always false. example: program test: uses magic; begin . . Poll; if Center then Help_Procedure; . . end. ************************************************************* CenterJustify - Global Variable Description: If you set the boolean global CenterJustify to true all subsequent calls to Present.Init, Dialog, GetYN, GetAnyKey, and Menu 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. Works the same in graphics and text modes. See Also: Present.Init, GetAnyKey, GetYN, Dialog, 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'; Present.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. ************************************************************* CGAHiVideo - Procedure Description: This sets the system in CGA high-resolution (640 x 200, 2-color) 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 4 (see Borland manual for more details). In this mode, with default colors, some LCD laptops may be unreadable. The resulting .EXE file is much smaller than one compiled after a call to BestVideo. Video.Tpu must be available until after compilation. See Also: CGALoVideo, BestVideo, HercVideo, EGALoVideo, EGAHiVideo, Vgahivideo, VGALoVideo, SVGAVideo Example: Program Test; uses crt,graph, magic; begin CGAHiVideo; rectangle(10,10,629,189); repeat until keypressed; CleanUp; end. Performance of example: The system is put in CGA-Hi 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). ************************************************************* CGALoVideo - Procedure Description: This sets the system in CGA low-resolution (320 x 200, 4-color) 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. The resulting .EXE file is much smaller than one compiled after a call to BestVideo. Video.Tpu must be available until after compilation. See Also: CGAHiVideo, BestVideo, HercVideo, EGALoVideo, EGAHiVideo, Vgahivideo, VGALoVideo, SVGAVideo Example: Program Test; uses crt,graph, magic; begin CGALoVideo; rectangle(10,10,309,189); repeat until keypressed; CleanUp; end. Performance of example: The system is put in CGA-Lo 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 Description: This procedure clears the screen, and performs closing functions, 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, magic; begin CGALoVideo; rectangle(10,10,309,189); 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). ************************************************************* ClearSents - Procedure Description: This procedure resets the strings in the global array Sent[] to blanks. It also resets the global byte HowMany to 0, indicating no strings in the array contain text. Considerations: ClearSents is called automatically upon completion by Presento.Menu, Presento.Dialog, Presento.GetYN and Presento.GetAnyKey. However, Presento.Init does not call ClearSents. Use of the procedure Pile should not be done until you have called ClearSents or when the value of HowMany is known. Example: program test; uses magic; begin Pile('This is a line of text'); Pile('This is another line'); Present.Init; ClearSents; Pile('This is Sent[1], starting over'); . . end. ************************************************************* Dialog - Object Method Description: Dialog is a method introduced in the Presento object. The Magic Unit provides a predeclared instance of Presento called Present. Typical use of Dialog is as follows: Present.Dialog(x,y); 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..48]. 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. DIALOG IS NOT A FUNCTION. When it is done, the user's response is in a global variable string called Answer. Considerations: See above. Dialog calls it's own destructor when done, removing all traces of itself from RAM. See also: Sent[], Present, Init, 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.'; Present.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. ************************************************************* Done - Object Destructor Description: Done is usually called automatically by object methods within the Presento and Boxo objects. Done replaces a pop-up box (such as presented by GetAnyKey, GetYN, Dialog and Menu) which what was originally under it on the screen. Done restores all RAM which had been held for the underlying image. Done automatically calls ClearSents. Considerations: Done must be called manually when you use Presento.Init or Boxo.Init. See Also: Init, Present, GetAnyKey, GetYN, Dialog, Menu, ClearSents. Example: program test; uses magic; begin Pile('test'); Present.Init(-1,-1); . . Present.Done; . . end. ************************************************************* EGAHiVideo - Procedure Description: This initializes the system in EGA high-resolution 640 x 350 16-color 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 EGAHiVideo builds in only the EGAVGA driver. This must be called only once during a program. Video.Tpu must be available until after compilation. There are several graphmodes available for EGA. See the Borland manuals. See Also: BestVideo, HercVideo, CGAHiVideo, CGALoVideo, VGAVido, EGALoVideo, SVGAVideo {Magic}; SetGraphMode, Setcolor, etc. {Borland} Example: Program Test; uses crt, graph, magic; begin EGAHiVideo; rectangle(10,10,20,20); repeat until keypressed; CleanUp; end. Performance of example: The system is put in EGA high-resolution 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). ************************************************************* EGALoVideo - Procedure Description: This initializes the system in EGA Low-resolution 640 x 200 16-color 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 EGALoVideo builds in only the EGAVGA driver. This must be called only once during a program. Video.Tpu must be available until after compilation. There are several graphmodes available for EGA. See the Borland manuals. See Also: BestVideo, HercVideo, CGAHiVideo, CGALoVideo, VGAVido, EGAHiVideo, SVGAVideo {Magic}; SetGraphMode, Setcolor, etc. {Borland} Example: Program Test; uses crt, graph, magic; begin EGALoVideo; rectangle(10,10,20,20); repeat until keypressed; CleanUp; end. Performance of example: The system is put in EGA low-resolution 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). ************************************************************* European - Procedure Description: Causes OutText, and OutTextXY to use the "European" stroked font. It builds the font into the .EXE file. Considerations: European is font #9, so you can use SetTextStyle as follows: settextstyle(9,0,size). See Also: Triplex, Little, Sansserif, Gothic, Script, Italic, Bold, Simple, Lcom, BitMap {Magic} Settextstyle, DefaultFont, SetUserCharSize {Borland} Example: program test; uses graph, magic; begin vgahivideo; European; OutTextXY(0,10,'This is European font'); WaitForUser; CleanUp; end. ************************************************************* FigureHowLong - Procedure Description: FigureHowLong determines the width of the longest string in the array Sent[]. First, it calls FigureHowMany to determine how many strings there are, then sets the global integer variable HowLong. If in text mode, HowLong is the number of characters in the longest string. In any graphics mode, HowLong represents the string length in number of pixels (characters * 8). Considerations: FigureHowLong is called automatically by the methods in Presento such as Init, GetYN, GetAnyKey, Dialog, and Menu. See Also: Sent, Dialog, Menu, HowMany, FigureHowMany, Present. Example: program test; uses magic; begin Pile('xxx'); Pile('yyy'); . . FigureHowLong; write('The longest string in Sent[] is ',HowLong,' long'); end. ************************************************************* FigureHowMany - Procedure Description: FigureHowMany counts the number of strings in the global array Sent[] and sets the global byte variable HowMany to that number. Considerations: FigureHowMany is called automatically by the pop-up methods in the Presento object such as Init, Menu, GetAnyKey, Dialog, and GetYN. See Also: FigureHowLong, Present, GetYN, GetAnyKey, Dialog, Menu, Init, HowLong, HowMany. Example: program test; uses magic; begin Pile('xxx'); Pile('yyy'); . . FigureHowMany; writeln(HowMany,' strings will pop-up in the next box.'); end. ************************************************************* FileEcho - Procedure Description: FileEcho writes a string to OutFile and to the monitor. OutFile is a file of type text predeclared in the Magic unit. If not renamed, the default file name for OutFile is Output. Opening and closing of OutFile is handled automatically. If OutFile does not exist on disk, it is created. If it does exist, the string is added to the end of the file. Considerations: FileEcho does not add carriage return/line feed to the end of the string. If the file is unaccessible (write protected, disk full, etc) then the global byte variable Problem becomes greater than 0. See Also: NameOutFile, FileEchoLn, FileWrite, FileWriteLn. Example: program test; uses magic; var t : byte; begin Pile('Line #1'); Pile('Line #2'); Pile('Line #3'); for t := 1 to 3 do FileEcho(Sent[t]); end. Performance of example: This text is written to the monitor and to a file called OUTPUT on disk: Line #1Line #2Line #3 ************************************************************* FileEchoLn - Procedure Description: FileEchoLn writes a string to OutFile and to the monitor. OutFile is a file of type text predeclared in the Magic unit. If not renamed, the default file name for OutFile is Output. Opening and closing of OutFile is handled automatically. If OutFile does not exist on disk, it is created. If it does exist, the string is added to the end of the file. Considerations: FileEchoLn adds a carriage return/line feed to the end of the string. If the file is unaccessible (write protected, disk full, etc) then the global byte variable Problem becomes greater than 0. See Also: NameOutFile, FileEcho, FileWrite, FileWriteLn. Example: program test; uses magic; var t : byte; begin Pile('Line #1'); Pile('Line #2'); Pile('Line #3'); for t := 1 to 3 do FileEchoLn(Sent[t]); end. Performance of example: This text is written to the monitor and to a file called OUTPUT on disk: Line #1 Line #2 Line #3 ************************************************************* FileRead - Function : char 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 'INPUT.' 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, and the global byte variable "Problem" will greater than 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 - Function : string 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 'INPUT.' 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, and the global byte variable, "Problem" will be greater than 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 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 'OUTPUT.' If there is an error, nothing will be written to disk and the global byte variable, Problem will be greater than 0. 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, FileEcho, FileEchoLn, 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 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 'OUTPUT.' If there is an error, nothing will be written to disk and the global byte variable, Problem will be greater than 0. 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, FileEcho, FileEchoLn, 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.' ************************************************************* ForceMode - Global Variable - Byte Description: ForceMode is used by the PutPCX procedure. It tells the procedure how to handle video modes for displaying a .PCX file: ForceMode Action taken by PutPCX ========= ================================================ 0 Set VMode as required by .PCX picture (default) 1 Set VMode to 1, CGA-Hi 640 x 200 2-color 2 Set VMode to 2, CGA-Lo 320 x 200 4-color 3 Set VMode to 3, EGA-Lo 640 x 200 16-color 4 Set VMode to 4, EGA-Hi 640 x 350 16-color 5 Set VMode to 5, Hercules 720 x 348 2-color 6 Set VMode to 6, VGA-Hi 640 x 480 16-color 7 Set VMode to 7, VGA-Lo 320 x 200 256-color 8 Set VMode to 8, Super-VGA 640 x 480 256-color 99 Does not change VMode Considerations: Using 1-8 means you must manually choose a correct video mode, or system may crash. Using 99, means system must already be set to correct video mode or system may crash. See Also: PutPCX, VMode Example: program test; uses magic; begin . . ForceMode := 7; PutPCX('Earth',true); WaitForUser; end. ************************************************************* GetAnyKey - Object Method 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. An instance of the object Presento which contains GetAnyKey, has been precreated in the Magic unit. It's name is Present. Typical use of GetAnyKey is with this pre-created instance as follows: Present.GetAnyKey(-1,-1); Considerations: Maximum Sent array size: 18. Make sure to add something to this effect to every message to avoid confusing your users: "Press any key to continue..." GetAnyKey calls it's own destructor when done, eliminating all traces of itself from RAM when done. See Also: Menu, Present, Init, 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...'; Present.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 - Object Method 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.' GetYN is a method of the object Presento. An instance of Presento, called Present has been precreated in the Magic Unit. 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'. GetYN calls it's own destructor when done, eliminating all traces of itself from RAM. See Also: Menu, Present.Init, Dialog, GetYN, Sent[], Answer, u. Example: Program Test; uses magic; begin . . Sent[1] := 'Exit to Dos? (Y/N)'; Present.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. ************************************************************* Gothic - Procedure 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. Dimensions of the Gothic font can be changed with SetTextStyle and SetUserCharSize. Gothic is font #4 (for use with SetTextStyle). See Also: SansSerif, BitMap, Triplex, Little, Italic, Script, European, Lcom, Simple, Bold {Magic} SetUserCharSize, SetTextStyle {Borland} Example: Program Test; uses crt, graph, magic; begin BestVideo; Gothic; OutTextXY(0,0,'Regular-size Gothic'); SetTextStyle(4,0,9); OutTextXY(100,100,'Huge'); WaitForUser; end. ************************************************************* HercVideo - Procedure 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. Video.Tpu must be available until after compilation. There is only one GraphMode for Hercules, which is 0. 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, CGAHiVideo, CGALoVideo, EGAHiVideo, EGALoVideo, Vgahivideo, VGALoVideo, SVGAVideo {Magic}; SetGraphMode, Setcolor, etc. {Borland} Example: Program Test; uses crt, Graph, Magic; begin HercVideo; rectangle(10,10,20,20); WaitForUser; 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 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. ************************************************************* HowLong - Global Variable - Integer Description: This integer is used to keep track of the width of the longest string in the array Sent[]. HowLong is updated by the procedure FigureHowLong. Considerations: Direct modification of this variable is not recommended. See Also: FigureHowLong, FigureHowMany, HowMany, Sent ************************************************************* HowMany - Global Variable - Byte Description: This integer is used to keep track of the number of strings within the array Sent[] which contain text. HowMany is updated by the procedure FigureHowMany. Considerations: Direct modification of this variable is not recommended. Example: program test; uses magic; begin Pile('xxx'); Pile('yyy'); . . FigureHowMany; if HowMany > 13 then GetAnyKey(-1,-1); end. ************************************************************* InFile - Global Variable 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. InFile is assigned the disk filename of INPUT by default. This may be changed with NameInFile. See Also: FileWrite, FileWriteLn, FileEcho, FileEchoLn, 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. ************************************************************* InFileName - Global Variable - string[60] Description: InFileName is a string to hold the disk filename for the predeclared text file, InFile. See Also: NameInFile, NameOutFile, FileRead, FileReadLn. Example: program test; uses magic; begin Pile('Type name of disk file:'); Present.Dialog(-1,-1); NameInFile(Answer); Answer := FileReadLn; if Problem > 0 then writeln('File does not exist'); WaitForUser; end. ************************************************************* Init - Object Method Description: Init is usually used with the object Presento, and with the predeclared instance Present. Init makes a box on the screen containing whatever text exists in the array of strings Sent[]. Init requires two parameters, an x and y location on the screen. If in text mode, the upper left corner of the screen is 1,1 and the lower right is 80,25. You cannot actually use Present.Init(80,25), because the box itself will require some space. In graphics modes, the upper left screen position is 0,0 and the lower right varies with the video mode. CGA High-resolution, for instance, is 639,199. If you pass any negative integer to Init for an x location, the box will be centered horizontally on the screen, and a negative number for a y coordinate results in a vertically centered box. The destructor Done will make the box disappear, restoring what it had covered up. Considerations: In most cases, using more than 18 strings in Sent[] will result in a box larger than will fit on the screen. (Crash!) In text mode, up to 10 layers of Init, GetYN, GetAnyKey, Menu or Dialog may be placed over each other. When each one is finished, what it covered will be restored. In graphics modes, there is only one layer possible for each instance of Presento. You can create more instances of Presento, but there is a limit to the amount of RAM available. You must be careful not to save so much graphics screen information with several instances that you use up the 640k RAM space. Methods GetAnyKey, GetYn, Dialog and Menu automatically save the graphics text settings before changing them to standardize the output of pop-up boxes. Then they change the graphics text settings back when done. Init does not do that. You should save the settings manually with Settings.Save and Settings.Restore, if you do not want to affect current settings of TextStyle, ViewPort, Text Justification, LineStyle and Color. See Also: Present, GetYN, GetAnyKey, Dialog, Menu, Sent, Settings, Restore, Save Example: program test; uses magic; begin Pile('This is a noisy test'); Present.Init(-1,2); Bugle; Present.Done; end. ************************************************************* Italic - Procedure Description: Calling the procedure Italic makes the Italic font available to graphic-based programs. This font will be compiled into the .EXE file. Considerations: Compiled .EXE size increases by about 17k. Dimensions of the Italic font can be changed with SetTextStyle and SetUserCharSize. Italic is font #7 (for use with SetTextStyle). See Also: SansSerif, Triplex, BitMap, Little, European, Bold, Lcom, Simple, Script, Gothic {Magic} SetUserCharSize, SetTextStyle {Borland} Example: Program Test; uses crt, graph, magic; begin BestVideo; Italic; OutTextXY(0,0,'Regular-size Italic'); SetTextStyle(7,0,9); OutTextXY(100,100,'Huge'); WaitForUser; end. ************************************************************* KeyDetect - Global Variable - byte; Description: KeyDetect is used to determine the nature of a response from the procedure Poll. If KeyDetect = 0 then a the keyboard has not been touched (perhaps a mouse action has occurred). If KeyDetect = 1 then a regular alphanumeric key has been pressed. If KeyDetect = 2 then an extended key has been pressed ([F1] - [F12], etc). Considerations: KeyDetect does not change until Poll is called. See Also: Poll. Example: program help; uses magic; begin . . repeat Poll; if (KeyDetect = 2) and (U = ';') then writeln('[F1] has been pressed.'); until Left; end. ************************************************************* Lcom - Procedure Description: Calling the procedure Lcom makes the Borland Lcom font available to graphic-based programs. This font will be compiled into the .EXE file. Lcom.CHR does not have to accompany the finished product. Considerations: Compiled .EXE size increases by about 17k. Dimensions of the Lcom font can be changed with SetTextStyle and SetUserCharSize. Lcom is font #8 (for use with SetTextStyle). See Also: SansSerif, BitMap, Triplex, Little, Italic, Script, European, Gothic, Simple, Bold {Magic} SetUserCharSize, SetTextStyle {Borland} Example: Program Test; uses crt, graph, magic; begin BestVideo; Lcom; OutTextXY(0,0,'Regular-size Lcom'); SetTextStyle(8,0,9); OutTextXY(100,100,'Huge'); WaitForUser; end. ************************************************************* Left - Global Variable - boolean 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 as of the last call to Poll. Considerations: The status of Left will change with every call to Poll, Waste, ResetMouse or procedures within Magic which handle text or pop-up boxes. See Also: Poll, Waste, ResetMouse, Right, Center Example: Program Test; uses magic; var x, y : word; begin Sent[1] := 'Nothing will change until you click the'; Sent[2] := 'left mouse button'; Present.Init(-1,-1); Waste; repeat Poll; until Left; Present.Done; 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. ************************************************************* Little - Procedure Description: Calling the procedure Little makes the Little font available to graphic-based programs. This font will be compiled into the .EXE file. Considerations: Compiled .EXE size increases by about 17k. Dimensions of the Little font can be changed with SetTextStyle and SetUserCharSize. Italic is font #2 (for use with SetTextStyle). See Also: Lcom, Simple, Bold, SansSerif, BitMap, Triplex, Italic, European, Script, Gothic {Magic} SetUserCharSize, SetTextStyle {Borland} Example: Program Test; uses crt, graph, magic; begin BestVideo; Little; OutTextXY(0,0,'Regular-size Little'); SetTextStyle(2,0,9); OutTextXY(100,100,'Huge'); WaitForUser; end. ************************************************************* LittleCursor - Procedure 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 - byte 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. MainBack is also used as the background color for the procedure NText. 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. After changing a video mode, MainBack will have no effect until a call to XClear. See Also: BarBack BarText, BoxBack, BoxText, MainText, Border, Shadow, NText Example: program test; uses magic; begin Sent[1] := 'First Thing'; Sent[2] := 'Second Thing'; Sent[3] := 'Quit'; Mc := 1; MainBack := Red; XClear; Present.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 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. MainText is also used as the foreground color for the procedure NText. 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 1992, Your Company'); Sent[1] := 'First Thing'; Sent[2] := 'Second Thing'; Sent[3] := 'Quit'; Mc := 1; Present.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 1992, Your Company." Then a menu pops up. ************************************************************* Mc - Global Variable - byte; Description: Mc is used in conjunction with the Menu procedure. When Menu is called, the highlighted item on the menu will be Mc. So, generally, you would set Mc to 1 before calling Menu. When Menu is done, Mc becomes the number of the choice which was highlighted when Menu fell through. Considerations: If you forget to assign a value to Mc before calling Menu, a random choice will be highlighted, within the range possible. See Also: Menu Example: See Menu ************************************************************* Menu - Object Method Description: Menu pops a box on the screen showing lines of text from the array Sent[1..48]. (Actually only about 18 Sent[]s are possible in most video modes.) 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. A string must also be passed to Menu. If the string is blank ('') Menu will work as expected. If the string contains characters, then Menu will fall through if the user presses any key corresponding to any characters in the string. This is how you can have the menu accept user input when the user presses the first letter of a Menu choice. Small case characters in the string will be automatically upcased. 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 which corresponds to a character in the string passed to Menu, or clicks a 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 #13 ([Enter]), and if the right button was pressed, U will be #27 ([Esc]). 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 Menu must be called again. The usual way to use Menu is to put it into a repeat loop as shown in the example below. Menu is a method within the Presento object. An instance of Presento called Present, has been predeclared in the Magic unit, so a typical call to Menu looks like this: Present.Menu(x,y,''); 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. Menu uses the color variables Border, BoxBack, BoxText, BarBack, and BarText. In text mode, BoxBack and BarBack colors above 7 are not supported. See also: Sent[], Present.Init, GetYN, GetAnyKey. 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 '; Present.Menu(-1,-1); if Left then case Mc of 1 : Procedure1; 2 : Procedure2; 3 : Procedure3; 4 : Procedure4; 5 : Procedure5; 6 : Procedure6; 7 : Right := true; end; {case Mc} case u of {must be upper case here} 'O' : Procedure1; 'T' : Procedure2; 'H' : Procedure3; 'F' : Procedure4; 'V' : Procedure5; 'S' : Procedure6; 'Q' : Right := true; end; {case u} until Right; 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 Left is true (because left mouse button or [Enter has been pressed) 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. 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 Description: This boolean function returns true if a mouse and its driver are installed. Considerations: The graphics mouse cursor works from keyboard input whether or not a mouse is installed. See Also: Poll, SetMouseRows, SetMouseColumns Example: program test; uses graph, magic; begin if MouseInstalled = false then Sent[1] := 'Mouse not found' else Sent[1] := 'A mouse is present'; Present.GetAnyKey(10,10); end. Performance of Example: If there is no mouse then MouseInstalled will be false and 'Mouse not found' will pop up; If there is a mouse, then 'A mouse is present' will appear. ************************************************************* MusicOn - Global Variable - boolean; 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. See Also: Pink, Twinkle, SoundUp, SoundDown, SorrySound, Bugle. Example: program test; uses magic; begin Sent[1] := 'Do you want sound effects? (Y/N)'; Present.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. ************************************************************* NameInFile - Procedure Description: Magic provides a standard text file for the input procedures FileRead and FileReadLn. The default disk filename for this is INPUT. You can change it to any DOS-legal filename, with optional drive and path designation up to 60 characters. NameInFile does this for you whether or not the file is currently open. Considerations: If file is open, it will be reset after renaming. See Also: FileRead, FileReadLn Example: program test; uses crt,magic; begin NameInFile('MAGIC.DOC'); repeat Sent[1] := FileReadLn; writeln(Sent[1]); delay(500); until Problem > 0; end. ************************************************************* NameOutFile - Procedure Description: Magic provides a standard text file for the output procedures FileWrite, FileWriteLn, FileEcho, and FileEchoLn. The default disk filename for this is OUTPUT. You can change it to any DOS-legal filename, with optional drive and path designation up to 60 characters. NameOutFile does this for you whether or not the file is currently open. Considerations: If file is open, it will be reset after renaming. See Also: FileWrite, FileWriteLn, FileEcho, FileEchoLn, NameInFile. Example: program test; uses crt,magic; begin NameOutFile('TEST.TXT'); Pile('This is a test'); FileWriteLn(Sent[1]); end. ************************************************************* NText - Procedure Description: This procedure is quite similar to OutTextXY, but it works with only one font, the standard text-mode font. This font will be written using the background color variable MainBack and the foreground variable MainText. It will place the upper left corner of the passed string at the passed coordinates. Considerations: This font is available only in EGA-Hi, EGA-Lo and VGA-Hi graphics modes (VModes 4,3 and 6). For some reason as yet undetermined, FloodFill fails to function after a call to NText. See Also: MainText, MainBack {Magic} OutTextXY, OutText {Borland} Example: program text; uses graphics,magic; begin VGAHiVideo; MainText := LightGray; MainBack := Black; NText(0,0, 'This looks like we''re not in a graphics mode!'); WaitForUser; end. ************************************************************* Number - Function 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?'; Present.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 Description: This procedure tries to open InFile for reading. If successful, the global byte variable Problem = 0. If it is not possible to open the file for reading then Problem will be greater than 0. This is a useful way to check for the existence of a file, and to reset a file to start reading at it's beginning. Considerations: This procedure is automatically called from FileRead and FileReadLn. See Also: FileRead, FileReadLn. ************************************************************* OutFile - Global Variable - file of text 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 FileWrite, FileWriteLn, FileEcho, and FileEchoLn. 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. All Magic procedures which write to OutFile will automatically close it between uses, to insure against lost data in case of power failure, crash, etc. The default filename for OutFile is OUTPUT. This can be changed with the procedure NameOutFile. See Also: InFile, FileWrite, FileWriteLn, FileEcho, FileEchoLn, NameInFile, NameOutFile, {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." ************************************************************* OutFileName - Global Variable - string[60] Description: OutFileName is a string to hold the disk filename for the predeclared text file, OutFile. See Also: NameInFile, NameOutFile, FileWrite, FileWritLn, FileEcho, FileEchoLn. Example: program test; uses magic; begin Pile('Type name of disk file:'); Present.Dialog(-1,-1); NameOutFile(Answer); FileWriteLn('This is a test.'); end. ************************************************************* Pink - Procedure 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 when multitasking under DeskView or MS-Windows. Make sure to read the special note under MusicOn. See Also: MusicOn, Twinkle, Bird, SoundUp, SoundDown, SorrySound, Bugle {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). ************************************************************* Pile - Procedure Description: Pile adds the passed string to the array Sent[] and increments HowMany. Considerations: Pile can be used effectively at the beginning of a program, after any call to GetAnyKey, GetYn, Dialog or Menu, or after ClearSents. Otherwise, it may be confused about which Sent[] to update. See Also: Sent, GetYN, GetAnyKey, Dialog, Menu, Present, HowMany. Example: program test; uses magic; begin Pile('This is the first line'); Pile('This is the second line'); Present.GetAnyKey(-1,-1); end. ************************************************************* PointerOff - Procedure Description: Turns off the mouse pointer or arrow. Considerations: See PointerOn. See Also: Poll, PointerOn, ResetMouse Example: Program Test; uses crt, graph, magic; var x,y : word; begin x := 0; y := 0; BestVideo; PointerOff; repeat Poll; lineto(Px,Py); x := x; y := y; until Left; PointerOn; PointerToXY; Waste; repeat Poll; 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 Description: Turns on the mouse pointer or arrow. Considerations: You might also want to call PointerToXY to reset the mouse position to the current position, before calling PointerOn. See Also: Poll, PointerOff, ResetMouse, PointerToXY; Example: Program Test; uses crt, graph, magic; begin BestVideo; PointerOff; repeat Poll; lineto(Px,Py); until Left; PointerToXY; PointerOn; Waste; repeat Poll; 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 Description: Moves the mouse pointer to coordinates Px and Py. Px and Py are global integer variables. Considerations: If the pointer is turned off (PointerOff) then the (graphics) CP (Current Position) will be moved to Px and Py. See Also: Poll, PointerOff, Pointeron, ResetMouse, SetMouseRows, SetMouseColumns. Example: Program Test; uses crt, graph, magic; begin BestVideo; Px := getmaxx div 2; Py := getmaxy div 2; PointerToXY; PointerOn; repeat until keypressed; CleanUp; end. Performance of example: The current position is moved to Px and Py, 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). ************************************************************* PointerStatus - Global Variable - boolean Description: The global boolean variable PointerStatus is true when the graphics "mouse" cursor is visible. It is used by Magic procedures draw cursor. Considerations: Direct manipulation of this variable is not recommended. See Also: PointerToXY, Poll, PointerOn, PointerOff, ResetMouse ************************************************************* Poll - Procedure Description: Poll updates the global boolean variables Left, Center and Right and the global integer variables Px, and Py. Left, Center and Right are true if a mouse button is pressed during Poll. Center is always false with two-button mice or when no mouse is installed. Px and py are global integers used to represent the x and y graphics cursor position. Poll works whether or not a mouse is installed, and whether or not the cursor is visible. Besides accepting input from the mouse: if [Enter] is pressed, Left becomes true. If [Esc] is pressed, Right becomes true. If the arrow keys, [Page Up], [Page Down], [Home], [End] or the number keys are pressed, the graphics cursor will be moved. Some of these keys cause fine movements while others cause gross movement. Some are diagonal and some are perpendicular. See Also: PointerToXY, SetMouseRows, SetMouseColumns, Left, Center, Right, Px, Py. Example: Program Test; uses crt, graph, magic; begin BestVideo; PointerOff; repeat Poll; lineto(Px,Py); until Left; end. ************************************************************* Present - Instance of object Presento Present is an instance of the object, Presento, pre-declared in the Magic Unit. You can use Present and it's methods without knowledge of OOP. Examples: Present.Init(x,y) {places text in a box on screen} Present.GetYN(x,y) {presents text box, waits for user to press [Y] or [N]} Present.GetAnyKey(x,y) {Presents text box, waits for keypress} Present.Menu(x,y,'abcd') {Presents menu, waits for selection} Present.Dialog(x,y) {Presents text box, waits for answer} Considerations: The array, Sent[], and the variables HowMany and HowLong are external of the object and are reused from one instance to another. Other instances of the Presento object can be declared within procedures for limited lifespan, and duplication of task, as in the following example: procedure xxx; var Present2 : Presento; begin . . Present.Init; . . Present2.Menu; . . Present2.Init; . . Present2.Done; . . Present.Done; . . end; See Also: Init, GetYN, GetAnyKey, Dialog, Menu, Sent, HowMany, HowLong, FigureHowMany, FigureHowLong. ************************************************************* Problem - Global Variable - byte Description: Problem is a global byte variable that is usually set to 0 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 test Problem and 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 to 0 as it starts. Example: Program Test; uses magic; begin NameOutFile('testfile.txt'); FileWriteLn('This is a line of nonsense.'); if Problem > 0 {= 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..'; Present.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 greater than 0 and a three-line notice pops up on the screen. ************************************************************* Px, Py - Global Variables - Integers Description: Px and Py are global variables defined in magic.tpu as integers. The most common use of Px is to designate a horizontal screen position, and Py is used to designate the vertical coordinate. Considerations: Each call to Poll will reset Px and Py. See Also: Poll, PointerToXy, SetMouseRows, SetMouseColumns ************************************************************* PutPCX - Procedure Description: PutPCX requires two passed parameters, the name of a .PCX file and a boolean. PutPCX will then attempt to display that file on screen, overwriting whatever is currently displayed. If successful, Problem is set to 0. If unable to display the .PCX file, Problem will (usually) be greater than 0. The boolean varialble determines whether the color palette is to be reset to the color information contained within the .PCX file. Generally you would use TRUE, but there are some .PCX files (especially scanned photos), which reset the colors to values not useable by the rest of your program. For instance, your mouse arrow or on-screen menus may disappear if reset to the .PCX file's colors. Considerations: There is a global byte variable called ForceMode which can be used to control the power of PutPCX. The default value for ForceMode is 0, which allows PutPCX to change the video mode to the correct one for the desired .PCX picture. In other words, with ForceMode set to 0, if you pass to PutPCX the name of a .PCX file drawn in 256-color VGA-Lo mode, then VMode 7 (256-color VGA-Lo) will be selected and set up. Changing ForceMode to these values will have these effects: ForceMode PutPCX Does ========= ================================================ 0 Reset video mode according to needs of .PCX file 1 Reset video mode to CGA-Hi 640 x 200 2-color 2 Reset video mode to CGA-Lo 320 x 200 4-color 3 Reset video mode to EGA-Lo 640 x 200 16-color 4 Reset video mode to EGA-Hi 640 x 350 16-color 5 Reset video mode to Hercules 720 x 348 2-color 6 Reset video mode to VGA-Hi 640 x 480 16-color 7 Reset video mode to VGA-Lo 320 x 200 256-color 8 Reset video mode to Super-VGA 640 x 480 256-color 99 Does not reset video mode Be careful to avoid forcing mode inappropriately, thereby causing illegible picture or crash. Not all .PCX pictures can be displayed. The .PCX specifications are very flexible, and some image generators are just too weird. Older, version 2.0 .PCX files with an external 256-color palette file (*.PAL) are handled automatically in the same manner as newer files with internal palette information. Example: program test; uses magic; begin PutPCX('Earth',true); WaitForUser; end. ************************************************************* ResetMouse - Procedure Description: This restores the mouse situation to its default parameters. In graphics modes the "mouse" cursor will be relocated to the center of the screen and the left and right mouse button status will be not pressed. The cursor will not be visible. Considerations: ResetMouse is called automatically when the video mode is changed. See also: Poll, PointerToXY, PointerOn, PointerOff ************************************************************* Restore - Object Method Description: Restore restores information about Viewport Settings, Line Style, Text Justification, Text Style, Fill Settings and current color as they were previously captured by a call to Save. This is useful before calls to Presento.Init or other procedures which may temporarily disrupt your graphics text settings. When done with the disruptive procedure, you can then call Restore to reset everything the way it was. GetYN, GetAnyKey, Dialog, and Menu call Save and Restore automatically. Restore is a method of the Settingso object (from which Presento is descended) and can be called without knowledge of OOP (Object Oriented Programming) by simply using the pre-declared settings instance as in the example below. Considerations: Has no effect in text mode. See Also; Settings, Save, Init Example: program test; uses graph,magic; begin Settings.Save; SetTextStyle(1,0,4); SetColor(LightGreen); SetLineStyle(0,0,3); . . Settings.Restore; OutTextXY(0,0,'Everything is back to normal'); . . end; ************************************************************* Right - Global Variable 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, ResetMouse or procedures within Magic which handle text or pop-up boxes. See Also: Poll, Waste, ResetMouse, left, Center. Example: Program Test; uses magic; begin Sent[1] := 'Nothing will change until you click the'; Sent[2] := 'right mouse button'; Present.Init(-1,-1); Waste; repeat Poll; 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 Description: Calling the procedure Sansserif makes the Sansserif font available to graphic-based programs. This font will be compiled into the .EXE file. SANS.CHR does not have to accompany the finished product. Considerations: Compiled .EXE size increases by about 17k. Dimensions of the Sansserif font can be changed with SetTextStyle and SetUserCharSize. Sansserif is font #3 (for use with SetTextStyle). See Also: Gothic, BitMap, Triplex, Little, Bold, Simple, Lcom, Italic, Script, European {Magic} SetUserCharSize, SetTextStyle {Borland} Example: Program Test; uses crt, graph, magic; begin BestVideo; Sansserif; OutTextXY(0,0,'Regular-size Sansserif'); SetTextStyle(3,0,9); OutTextXY(100,100,'Huge'); WaitForUser; end. ************************************************************* Save - Object Method Description: Save captures information about Viewport Settings, Line Style, Text Justification, Text Style, Fill Settings and current color. This is useful before calls to Presento.Init or other procedures which may temporarily disrupt your graphics text settings. When done with the disruptive procedure, you can then call Restore to reset everything the way it was. GetYN, GetAnyKey, Dialog, and Menu call Save and Restore automatically. Save is a method of the Settingso object (from which Presento is descended) and can be called without knowledge of OOP (Object Oriented Programming) by simply using the pre-declared settings instance as in the example below. Considerations: Has no effect in text mode. See Also; Settings, Restore, Init Example: program test; uses graph,magic; begin Settings.Save; SetTextStyle(1,0,4); SetColor(LightGreen); SetLineStyle(0,0,3); . . Settings.Restore; OutTextXY(0,0,'Everything is back to normal'); . . end; ************************************************************* Script - Procedure Description: Calling the procedure Script makes the Script font available to graphic-based programs. This font will be compiled into the .EXE file. Considerations: Compiled .EXE size increases by about 17k. Dimensions of the Script font can be changed with SetTextStyle and SetUserCharSize. Script is font #5 (for use with SetTextStyle). See Also: Bold, Lcom, Simple, Gothic, BitMap, Triplex, Little, Italic, Sansserif, European {Magic} SetUserCharSize, SetTextStyle {Borland} Example: Program Test; uses crt, graph, magic; begin BestVideo; Script; OutTextXY(0,0,'Regular-size Script'); SetTextStyle(5,0,9); OutTextXY(100,100,'Huge'); WaitForUser; end. ************************************************************* Sent - Global Variable - array Description: Sent is a global array of 48 strings, each with up to 80 characters. Sent is used to hold strings for display by Init, GetYN, GetAnyKey, Dialog and Menu. Considerations: Although there are 48 strings available in Sent[], most instances of pop-up boxes cannot display that many on-screen at one time. See Also: Pile, Init, GetYN, GetAnyKey, Dialog, Menu, ClearSents ************************************************************* SetMouseColumns - Procedure Description: SetMouseColumns limits the horizontal range of the mouse cursor. This procedure requires 2 integers, representing the maximum horizontal location in which the mouse is allowed, followed by the mininum location. Considerations: Limits beyond the range of the current video mode have unpredictable results. In text mode, SetMouseColumns uses CGA-Hi resolution, 640 pixels (divided by 8 for character positions). See Also: ResetMouse, PointerToXY, PointerOn, PointerOff, SetMouseRows Example: Program Test; uses crt,magic; begin VGAHiVideo; SetMouseColumns(639,320); pointeron; repeat poll; until left; cleanup; end. Performance of example: Program initializes VGA high resolution mode, and the mouse arrow is visible. The pointer's movement is restricted to the right half of the screen. The pointer can be moved by the user (within the right side only) until the left mouse button is pressed. ************************************************************* SetMouseRows - Procedure Description: SetMouseRows limits the vertical range of the mouse cursor. This procedure requires 2 integers, representing the maximum vertical location in which the mouse is allowed, followed by the mininum location. Considerations: Limits beyond the range of the current video mode have unpredictable results. In text mode, SetMouseRows uses CGA-Hi resolution, 200 pixels (divided by 8 for character positions). See Also: ResetMouse, PointerToXY, PointerOn, PointerOff, SetMouseColumns Example: Program Test; uses crt,magic; begin VGAHiVideo; SetMouseRows(239,0); pointeron; repeat poll; until left; cleanup; end. Performance of example: Program initializes VGA high resolution mode, and the mouse arrow is visible. The pointer's movement is restricted to the upper half of the screen. The pointer can be moved by the user (within the top half only) until the left mouse button is pressed. ************************************************************* Settings - Object Instance of Settingso Description: Settingso is a simple object which simply saves and restores an assortment of settings pertaining to text in graphics modes. Settings is an instance of Settingso pre-declared in the Magic unit. See Also: Save, Restore Example: See Save ************************************************************* SetVMode - Procedure Description: SetVMode will reset the video mode to the number: VMode Action ==== ====== 0 Reset video mode to text video 1 Reset video mode to CGA-Hi 640 x 200 2-color 2 Reset video mode to CGA-Lo 320 x 200 4-color 3 Reset video mode to EGA-Lo 640 x 200 16-color 4 Reset video mode to EGA-Hi 640 x 350 16-color 5 Reset video mode to Hercules 720 x 348 2-color 6 Reset video mode to VGA-Hi 640 x 480 16-color 7 Reset video mode to VGA-Lo 320 x 200 256-color 8 Reset video mode to Super-VGA 640 x 480 256-color See Also: TextVideo, BestVideo, CGAHiVideo, CGALoVideo, EGAHiVideo, EGALoVideo, HercVideo, VGAHiVideo, VGALoVideo, SVGAVideo, VMode. Example: program test; uses magic,graph; begin SetVMode(2); line(0,0,319,199); WaitForUser; end. ************************************************************* Shadow - Global Variable - byte 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; Present.Menu(-1,-1); . . end. Performance of example: A menu pops up with a LightCyan shadow. ************************************************************* Simple - Procedure Description: Calling the procedure Simple makes the Borland Simple font available to graphic-based programs. This font will be compiled into the .EXE file. Simp.CHR does not have to accompany the finished product. Considerations: Compiled .EXE size increases by about 17k. Dimensions of the Simple font can be changed with SetTextStyle and SetUserCharSize. Simple is font #6 (for use with SetTextStyle). See Also: SansSerif, BitMap, Triplex, Little, Italic, Script, European, Gothic, Bold, Lcom {Magic} SetUserCharSize, SetTextStyle {Borland} Example: Program Test; uses crt, graph, magic; begin BestVideo; Simple; OutTextXY(0,0,'Regular-size Simple'); SetTextStyle(6,0,9); OutTextXY(100,100,'Huge'); WaitForUser; end. ************************************************************* SorrySound - Procedure Description: A sound effect. Considerations: The global boolean Variable MusicOn must be true or SorrySound 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, Bugle {Magic} Sound, NoSound, Delay {Borland} Example: Program Test; uses magic; begin SorrySound; end. ************************************************************* SoundDown - Procedure Description: SoundDown makes a sound typically indicating a window is being closed or a large action has occurred. Considerations: The global 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, Bugle, SorrySound {Magic} Sound, NoSound, Delay {Borland} Example: Program Test; uses magic; begin SoundDown; end. ************************************************************* SoundUp - Procedure Description: SoundUp makes a sound typically indicating a window is being opened or a large action has occurred. Considerations: The global 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, Bugle, SorrySound {Magic} Sound, NoSound, Delay {Borland} Example: Program Test; uses magic; begin SoundDown; end. ************************************************************* SVGAVideo - Procedure Description: This initializes the system in Super-VGA 640 x 480 256-color graphics mode. Super-VGA video driver will be automatically compiled into the .EXE program file, eliminating the need for an external 256-color .BGI file. Considerations: There are several other graphmodes available for Super-VGA. The default graph mode is 2, but can be set from 0 to 4. 0 = 320 x 200 256-color, and 4 = 1024 x 768 256-color. These other graphics modes are not supported by Pascal Magic routines. Borland's ImageSize function may not work properly with the other graph modes. To reset to another graph mode follow this exmaple which results in 1024 x 768 256-color: SVGAVideo; SetGraphMode(4); See Also: BestVideo, HercVideo, CGAHiVideo, CGALoVideo, EGAHiVideo, EGALoVideo, VGAHiVideo, VGALoVideo {Magic}; SetGraphMode, Setcolor, etc. {Borland} Example: Program Test; uses graph, magic; begin SVGAVideo; setcolor(53); rectangle(10,10,20,20); WaitForUser; CleanUp; end. Performance of example: The system is put in VGA low-resolution graphics mode. A small light-blue 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). ************************************************************* TextVideo - Procedure 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. See Also: BestVideo, CGAHiVideo, CGALoVideo, HercVideo, EGAHiVideo, EGALoVideo, VGAHiVideo, VGALoVideo, SVGAVideo Example: Program Test; uses graph, magic; begin BestVideo; Sent[1] := 'This is graphics mode'; Sent[2] := 'Press any key to see text mode'; Present.GetAnyKey(-1,-1); TextVideo; Sent[1] := 'This is text mode'; Sent[2] := 'Press any key to quit'; Present.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. ************************************************************* Triplex - Procedure Description: Calling the procedure Triplex makes the Borland Triplex font available to graphic-based programs. This font will be compiled into the .EXE file. TRIP.CHR does not have to accompany the finished product. Considerations: Compiled .EXE size increases by about 17k. Dimensions of the Triplex font can be changed with SetTextStyle and SetUserCharSize. Triplex is font #1 (for use with SetTextStyle). See Also: BitMap, SansSerif, Gothic, Little, Bold, Simple, Lcom, Italic, Script, European {Magic} SetUserCharSize, SetTextStyle {Borland} Example: Program Test; uses crt, graph, magic; begin BestVideo; Triplex; OutTextXY(0,0,'Regular-size Triplex'); SetTextStyle(1,0,9); OutTextXY(100,100,'Huge'); WaitForUser; end. ************************************************************* Twinkle - Procedure Description: Twinkle makes a sound typically indicating an action has positively been completed. Considerations: The global 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, Bird, Pink, Bugle, SorrySound {Magic} Sound, NoSound, Delay {Borland} Example: Program Test; uses magic; begin Twinkle; end. ************************************************************* U - Global Variable - char 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. ************************************************************* VGAHiVideo - Procedure Description: This initializes the system in VGA high-resolution 640 x 480 16-color 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 VGAHiVideo builds in only the EGAVGA driver. Video.Tpu must be available until after compilation. There are several graphmodes available for VGA. See the Borland manuals. See Also: BestVideo, HercVideo, CGAHiVideo, CGALoVideo, EGAHiVideo, EGALoVideo, VGALoVideo, SVGAVideo {Magic}; SetGraphMode, Setcolor, etc. {Borland} Example: Program Test; uses graph, magic; begin VGAHiVideo; rectangle(10,10,20,20); WaitForUser; CleanUp; end. Performance of example: The system is put in VGA high-resolution graphics mode. A small rectangle is displayed in the upper left corner of the screen until any key is pressed. ************************************************************* VMode - Global Variable - byte Description: VMode is used by the Magic unit to keep track of which video mode is currently being used. These are the options: VMode Which is: Procedure to get: ===== ============================ ================= 0 text video TextVideo 1 CGA-Hi 640 x 200 2-color CGAHiVideo 2 CGA-Lo 320 x 200 4-color CGALoVideo 3 EGA-Lo 640 x 200 16-color EGALoVideo 4 EGA-Hi 640 x 350 16-color EGAHiVideo 5 Hercules 720 x 348 2-color HercVideo 6 VGA-Hi 640 x 480 16-color VGAHiVideo 7 VGA-Lo 320 x 200 256-color VGALoVideo 8 Super-VGA 640 x 480 256-color SVGAVideo Considerations: Manually changing VMode is not recommended. ************************************************************* WaitForUser - Procedure Description: This simple procedure stalls the computer until the user presses a key or clicks a mouse button. See Also: Present.Init, XReadKey Example: Program Test; uses graph, magic; begin BestVideo; Triplex; OutTextXY(100,90,'Press any key'); WaitForUser; CleanUp; end. ************************************************************* Waste - Procedure 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: Waste is automatically called by Dialog, Menu, GetYN, and GetAnyKey. See Also: Present.Init, XReadKey. 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. ************************************************************* XClear - Procedure 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. Background is always set to black when switching to another video mode. You can call XClear after such a switch. See Also: BestVideo, HercVideo, CGAHiVideo, CGALoVideo, EGAVido {Magic}; SetGraphMode, Setcolor, etc. {Borland} Example: Program Test; uses crt, graph, magic; begin VGAHiVideo; rectangle(10,10,20,20); Sent[1] := 'Press any key...'; Present.Init(30,30); MainBack := Red; repeat until keypressed; XClear; Sent[1] := 'Press any key...'; Present.Init(400,400); Waste; WaitForUser; end. ************************************************************* XReadLn - Function 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 75 characters. 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). ************************************************************* Zx, Zy - Global Variables - integers Description: Zx and Zy are global integer variables which essentially replace getmaxx and getmaxy. Example: program test; uses graph,magic; begin BestVideo; SetTextJustify(CenterText,CenterText); OutTextXY((Zx div 2,Zy div 2, 'This text is centered on the screen'); WaitForUser; end. ************************************************************* 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. * You can modify Pascal Magic to suit your OOP needs. * 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 $39.95 to Another Company. Complete, well-documented easy-to-understand source code is available. For registration plus registration, send $79.90. Please add $3 for US postage, ($5-Canada; $7-Overseas). If you require 3.5" disk size, please add $1. 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 2.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 - November 11, 1992 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, THE MULTIMEDIA WORKSHOP, BETTER EYESIGHT, WHAT'S IN THAT BOX?, 21ST CENTURY ALMANAC, 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 $29.95 plus postage ($3-US, $5-Canada, $7-Overseas). Please add $1 if you need 3.5" disk size. 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.