C MAGIC Version 1.5 Reference Manual An Add-in For Borland C/C++ Products Copyright 1992, Jeff Napier & Another Company What C Magic will do for you: * Create 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 directly into your .EXE programs with only a few lines of code. * Write graphics-based programs as easily as text-based. * Everything you need to write programs to run on 256-color VGA. * Gain mouse support without writing a mouse driver. In graphics modes, whether or not end user has a mouse, pointer is generated and can also be moved with arrow/number keys. * Gain color control without writing color control code. * Many Borland/Turbo C functions greatly simplified. * Disk file handling is done automatically. * Enlarged cursor available for your programs for use with laptop LCD displays. * Add sound effects to your program effortlessly. Notice: This is shareware. Feel free to copy and distribute the shareware version without modification. If you use any portion of the C Magic library 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 Include $3 postage (USA); $5 - Canada; or $7 - all other countries. If you require 3.5" disk size, please add $1.00. Even though this seems quite bug-free to me, it is version 1.5 and you may find a surprise or two. I make no warranty. Please feel free to submit bug reports, and I will attempt to incorporate appropriate fixes. (If you are new to C, or if you would like a step-by-step guide, you are looking at the wrong file. Please see TUTOR.DOC first.) Note: MAGIC.LIB should be in your \LIB subdirectory. MAGIC.H should be in your \INCLUDE subdirectory. MAGIC.LIB must be included in your project list. For newer Borland compilers press [Alt] + [p], then [o] to open a project. Then [i] to include the main source file name, and then MAGIC.LIB. For older Borland compilers, press [F3] to create a .PRJ file. Call it anything you like up to 8 letters, with .PRJ extension. On the first line of the .PRJ file, type the name of your source code file(s). On the second line, type MAGIC.LIB, and on the third line type GRAPHICS.LIB. IMPORTANT NOTES: GRAPHICS.LIB (supplied by Borland) must also be available. Include in project list, or press [Alt] + [O] then [L], then [L]. Check the GRAPHICS.LIB check box. You MUST use LARGE memory model. The Magic library wont' work with smaller memory models. ************************************************************* ALPHABETICALLY ORDERED REFERENCE TO ALL THE FEATURES AVAILABLE IN MAGIC LIBRARY NOTE: All functions and global variables work identically in text and all graphics modes unless otherwise stated except for one difference: In text mode, up to 10 pop-up boxes may be on screen at once, and the image underneath is restored when the boxes disappear. Graphics modes allow only one layer. NOTE: Text mode operation is designed specifically for standard 80 x 25 text display. Results may be unpredictable if used in other text resolutions. NOTE: The functions in this library are designed for use with standard IBM-compatible equipment and are not portable to other systems. ************************************************************* char[81] answer - Global Variable Usage: /* example */ strcpy(answer,"test") Description: Answer is a string which is returned by the function dialog(). You can also use answer as a general purpose global string variable. Answer is null terminated (ASCII #0) and therefore one character longer than nominal string length. Considerations: Maximum size of answer is 80 characters. See also: dialog() Example: #include #include void main(){ magic_setup(); strcpy(sent[1],"Write your answer here"); dialog(1,1); if (answer[0] = 'I') User_Started_With_I(); . . } Performance of example: A dialog box pops up and the user types an answer. The string typed by the user is contained in the string, answer. A test is made to see if the first two characters of answer are 'I ' and if so, an imaginary function, User_Started_With_I() is called. ************************************************************* int b1,b2,b3,b4 - Global Variable Usage: Internal use by Magic.lib, not recommend for direct manipulation. Description: These four integers are used by Magic.lib to keep track of the corners of pop-up text boxes in both graphics and text modes. ************************************************************* char barback - Global Variable Usage: BarBack = color 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 graphics modes, or a color constant as defined by Borland in CONIO.H or GRAPHICS.H. The colors 0 - 7 are the same in both text and graphics modes. Considerations: May not have the expected effect when used with the limited palettes of 4-color CGA (mode 0,1 or 2), 2-color CGA or Hercules. See also: bartext, boxback, boxtext Example: #include #include #include void main(){ magic_setup(); strcpy(sent[1],"First Thing"); strcpy(sent[2],"Second Thing"); strcpy(sent[3],"Quit"); mc := 1; barback = RED; menu(-1,-1); . . } Performance of example: Three strings are declared. The menu bar will start by highlighting sent[1] when the menu is displayed. Because of the change to barback, the background of the highlighted menu item will be in red. ************************************************************* char bartext - Global Variable Usage: BarText := color Description: This sets the color for lightbar text in menus, where 'color' is an integer from 0 to 15 or a color constant as defined in CONIO.H or GRAPHICS.H. 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: #include #include #include void main(){ magic_setup(); strcpy(sent[1],"First Thing"); strcpy(sent[2],"Second Thing"); strcpy(sent[3],"Quit"); mc := 1; bartext = RED; menu(-1,-1); . . } Performance of example: Three strings are declared. The menu bar will start by highlighting sent[1] when the menu is displayed. Because of the preceding change to bartext, the highlighted menu text will be displayed in red. ************************************************************* void bestvideo(void) - function Usage: bestvideo() Description: By simply calling bestvideo(), the program detects the graphics card present and switches to the best graphics mode possible for that card. Considerations: Before calling bestvideo(), you must call magic_setup() which gets the magic library ready to work in a graphics mode. Bestvideo() incorporates only the video driver used for your computer. If you write a program using bestvideo() on a VGA system, it will not run on a CGA system, for instance. See also: cgalovideo(), cgahivideo(), egahivideo(), egalovideo() hercvideo(), vgalovideo(), vgahivideo() and textvideo(), cleanup(). Example: #include #include void main() { magic_setup(); bestvideo(); line(0,0,getmaxx,getmaxy); waitforuser(); cleanup(); } 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. ************************************************************* void bigcursor(void) - function Usage: bigcursor() Description: After a call to bigcursor(), the cursor in text mode will be a block the size of a whole character instead of an underline. This is particularly useful in programs designed for LCD laptop screens. Unless a specific call is made to littlecursor() 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. See Also: littlecursor(), hidecursor() Example: #include magic_setup(); void main(){ bigcursor(); printf("Big cursor at the end of this line!"); } 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. ************************************************************* void bitmap(void) - function Usage: bitmap() Description: This function causes outtext() and outtextxy() to generate text in the DEFAULT_font (Bitmapped 8 x 8 font). It is nearly the same as settextstyle(0,0,1); Considerations: Use of bitmap() does not appreciably increase RAM requirement or enlarge program size. See Also: triplex(), little(), gothic(), sansserif(), script(), italic(), complex(), simple(), bold(), european() Example: #include #include void main(){ magic_setup(); bestvideo(); triplex(); outtextxy(0,0,"Triplex font"); bitmap(); outtextxy(0,50,"Bitmap font"); waitforuser(); cleanup(); } Performance of example: Program writes "Triplex font" on screen using the Triplex font. Below that, it writes "Bitmap font" using the default font - Bitmap. ************************************************************* void bold(void) - function Usage: bold() Description: This function causes outtext() and outtextxy() to generate text in the "bold" stroked font. Considerations: BOLD.CHR is linked into .EXE file and RAM usage and disk space requirements increase. This font will not work with older versions of Turbo C. See Also: triplex(), little(), gothic(), sansserif(), script(), italic(), complex(), simple(), bitmap(), european() Example: #include #include void main(){ magic_setup(); bestvideo(); bold(); outtextxy(0,0,"Bold font"); waitforuser(); cleanup(); } Performance of example: Program writes "Bold font" on screen using the "bold" font. ************************************************************* char border - Global Variable Usage: border = color Description: Color is represented with an integer from 0 to 15 or a pre-defined color constant from CONIO.H or GRAPHICS.H. 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: #include void main() { magic_setup(); border = 15; /* WHITE */ pile("Do you like this border color?"); getanykey(-1,-1); } 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. ************************************************************* char boxback - Global Variable Usage: boxback = color; Description: Color is represented with an integer from 0 to 15 or a pre-defined color constant enumerated in CONIO.H or GRAPHICS.H. 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: #include #include void main() { magic_setup(); boxback := MAGENTA; pile("Do you like this background color?"); getanykey(-1,-1); } 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. ************************************************************* char boxtext - Global Variable Usage: boxback = color; Description: Color is represented with an integer from 0 to 15 or a pre-defined color constant enumerated in CONIO.H or GRAPHICS.H. 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: #include #include void main() { magic_setup(); boxtext := BLACK; pile("Do you like this background color?"); getanykey(-1,-1); } 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. ************************************************************* void bugle(void) - function Usage: bugle() Description: Bugle() plays a short tune like a bugle at the horse races. Considerations: The global variable musicon must be greater than 0 or bugle() will not make a sound. See Also: musicon, twinkle(), pink(), soundup(), sounddown(), sorry() {Magic} sound(), nosound(), delay() {Borland} Example: include void main() { magic_setup(); musicon = 0; pile("Do you want to hear the bugle?"); getanykey(-1,-1); if (u == 'Y') musicon = 1; bugle(); } Performance of example: If the user answers the question affirmatively, bugle() will play it's sound effect. ************************************************************* char center - Global Variable Usage: /* example */ if (center) break; Description: Center is a global char variable used to record the status of the center mouse button. If center = 1 then the center mouse button has been pressed, otherwise center = 0. If there is no mouse, or if the mouse has only two buttons, center is always 0. Considerations: If a three-button mouse is installed, the status of center 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, right Example: #include void main() { magic_setup(); waste(); pile("Nothing will change until you click the"); pile("center mouse button"); pop(-1,-1); do poll; while (!center); } Performance of example: A box containing two lines of text will stay on the screen until the user clicks the center mouse button. The program will then terminate. ************************************************************* char centerjustify - Global Variable Usage: /* example */ CenterJustify = 1 Description: If you set centerjustify to 1 all subsequent calls to pop(), dialog(), getyn(), getanykey(), menu() will contain centered text. Default is 0, left justification. Considerations: When a program starts, centerjustify is 0. If you change centerjustify to 1 all the functions that use it will center text until you specifically change it back to 0. On 4.77 mhz computers (older models) this can slow menu and pop-up generation slightly. Works the same in text and graphics modes. See Also: pop(), getanykey(), getyn(), dialog(), menu(). Example: #include void main() { magic_setup(); centerjustify := 1; pile("This is a very long line of text to display"); pile("This is short"); getanykey(-1,-1); } 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. ************************************************************* void cgahivideo(void) - function Usage: cgahivideo() Description: This initializes the system in CGA graphics mode. CGA video driver will be automatically compiled into the .EXE program file, eliminating the need for external CGA.BGI file. Graphics mode is set to 4 - 640 x 200 resolution, 2 colors. Considerations: Will not work on Hercules-equipped computers. Graphmode is initially set to 4 (see Borland manual for more details). See Also: bestvideo(), cgalovideo, hercvideo(), egalovideo() egahivideo(), vgalovideo(), vgahivideo(), textvideo(), cleanup() {Magic} setgraphmode() {Borland} Example: #include #include void main() { magic_setup(); cgahivideo(); rectangle(10,10,629,189); waitforuser(); cleanup(); } Performance of example: The system is put in CGA 2-color graphics mode. A large rectangle is displayed until any key is pressed. The program then terminates gracefully. ************************************************************* void cgalovideo(void) - function Usage: cgalovideo() Description: This initializes the system in CGA graphics mode. CGA video driver will be automatically compiled into the .EXE program file, eliminating the need for external CGA.BGI file. Graph mode is set to 0, 320 x 200 resolution, 4 colors. Considerations: Will not work on Hercules-equipped computers. Graphmode is initially set to 0 (see Borland manual for more details). In this mode, with default colors, some LCD laptops may be unreadable. To repair, switch to another graphics mode with setgraphmode() (see Borland manual). See Also: bestvideo(), cgahivideo, hercvideo(), egalovideo() egahivideo(), vgahivideo(), vgalovideo(), textvideo(), cleanup() {Magic} setgraphmode() {Borland} Example: #include #include void main() { magic_setup(); cgavideo(); rectangle(10,10,310,190); waitforuser(); cleanup(); } Performance of example: The system is put in CGA graphics mode. A large rectangle is displayed until any key is pressed. The program then terminates gracefully. The colors used for this example may not be easily distinguished on a laptop LCD display. ************************************************************* void cleanup(void) - function Usage: cleanup() Description: This procedure clears the screen, releases memory held for video applications, returns to standard text and background colors in text mode, saves and closes open automatic files, and quits, 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: #include #include void main() { magic_setup(); cgavideo(); rectangle(10,10,310,190); waitforuser(); cleanup(); } 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. ************************************************************* void clearsents(void) - function Usage: clearsents() Description: After a call to pop() or anytime you want to reset all the strings in the array, sent[], to empty strings, use this function. The global int variable "howmany" is reset to 0. Considerations: See Also: pop(), restore(), sent[], getanykey(), getyn(), dialog(), menu() Example: #include void main() { magic_setup(); pile("This is a demo"); pile("This is more text"); pop(1,4); clearsents(); pile("This is another text box"); getanykey(-1,-1); . . } Performance of example: Two strings of text are assigned to sent[] and then displayed with pop(). These strings are cleared to null with clearsents(), then the first string is reused to display "This is another text box". ************************************************************* void complex(void) - function Usage: complex() Description: This function causes outtext() and outtextxy() to generate text in the "complex" stroked font. Considerations: COMP.CHR is linked into .EXE file and RAM usage and disk space requirements increase. This font is not available with early versions of Turbo C. See Also: triplex(), little(), gothic(), sansserif(), script(), italic(), bold(), simple(), bitmap(), european() Example: #include #include void main(){ magic_setup(); bestvideo(); bold(); outtextxy(0,0,"Bold font"); waitforuser(); cleanup(); } Performance of example: Program writes "Bold font" on screen using the "bold" font. ************************************************************* char *cursormap - Global Variable Usage: Internal usage by Magic.lib. Not recommended for direct manipulation. Description: Used to store bitmap area occupied by arrow in graphics modes. ************************************************************* void dialog(int x, int 5) - function Usage: dialog(x,y) Description: Dialog() requires two integers, an x (horizontal) and y (vertical) to establish the position of the upper left corner of the dialog box on the screen. In text mode, the upper left corner is 1,1, and the lower right is 80,25. In graphics mode the upper left is 0,0, and the lower right is variable, depending on the current graphics card and mode. You can force dialog() to pop-up in the center of the screen by using a negative number for the x and/or the y positions. Dialog() will pop up a box on the screen containing lines of text plus 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[81][46]. To use dialog(), you must first assign the text to the array. Use as few or 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 in the global variable answer, which contains what the user typed. The sent[81][46] array is cleared. The user can type an answer string as long as the longest sent[] in the dialog box. To get a longer answer string, pad any sent[] string with spaces to make the dialog box wider. Dialog() works in text or graphics mode. Considerations: See above. In graphics modes, default bitmap font will be used. Do not attempt to exceed the limits of sent[81][46] or unpredictable results will occur. Colors, font choices and linestyle from main program will be unaffected. There is a limit to the maximum size of a dialog() box. For instance, in VGA-HI graphics mode, the limit is about 20 lines of text with the longest line being about 40 characters long. See also: sent[], pop(), getyn(), getanykey(), menu() Example: #include #include void main () { char teststring[81]; magic_setup(); pile(" How would you answer this question? "); pile(" Any answer will do."); dialog(-1,5); strcpy(teststring,answer); . . } 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. ************************************************************* void dumpmaps(void) - function Usage: dumpmaps() Description: Dumpmaps() will release all memory held for screen images, without restoring the images. Works the same in graphics or text modes. Considerations: In graphics modes, it is easy to fill all available RAM with unused screen images. This seldom-needed procedure will help you clear that out. See also: restore(), pop(), getanykey(), getyn(), dialog(), menu(), xclear(), cleanup() Example: #include #include void main() { magic_setup(); strcpy(sent[1],"An example string"); strcpy(sent[2],"Another example string"); pop(10,10); strcpy(sent[1],"An example string"); strcpy(sent[2],"Another example string"); pop(1,1); strcpy(sent[1],"An example string"); strcpy(sent[2],"Another example string"); pop(30,10); strcpy(sent[1],"This is becoming a messy screen"); pop(36,12); waitforuser(); dumpmaps(); . . } Performance of example: The screen is cluttered with a bunch of pop-up boxes. When the user presses a key, the memory held for the replacement of those boxes disappears, but he boxes remain pictured on the screen. ************************************************************* void dumpmapsg(void) Usage: For internal use by Magic.lib only. Not for direct manipulation. Description: This is a sub-routine used when in graphics modes. ************************************************************* void egahivideo() - function Usage: egahivideo() Description: This initializes the system in EGA graphics mode. EGA video driver will be automatically compiled into the .EXE program file, eliminating the need for external CGA.BGI file. Program will use 640 x 350 resolution, 16 colors. Considerations: Will not work on CGA or Hercules-equipped computers. Graphmode is initially set to 0 (see Borland manual for more details). See Also: bestvideo(), cgalovideo(), cgahivideo(), hercvideo(), egalovideo(), vgahivideo(), vgalovideo(), textvideo(), cleanup() {Magic} setgraphmode() {Borland} Example: #include #include void main() { magic_setup(); egahivideo(); rectangle(10,10,629,339); waitforuser(); cleanup(); } Performance of example: The system is put in EGA graphics mode. A large rectangle is displayed until any key is pressed. The program then terminates gracefully. ************************************************************* void egalovideo() - function Usage: egalovideo() Description: This initializes the system in EGA graphics mode. EGA video driver will be automatically compiled into the .EXE program file, eliminating the need for external CGA.BGI file. Program will use 640 x 200 resolution, 16 colors. Considerations: Will not work on CGA or Hercules-equipped computers. Graphmode is initially set to 0 (see Borland manual for more details). See Also: bestvideo(), cgalovideo(), cgahivideo, hercvideo(), egahivideo(), vgahivideo(), vgalovideo(), textvideo(), cleanup() {Magic} setgraphmode() {Borland} Example: #include #include void main() { magic_setup(); egalovideo(); rectangle(10,10,629,189); waitforuser(); cleanup(); } Performance of example: The system is put in EGA-lo graphics mode. A large rectangle is displayed until any key is pressed. The program then terminates gracefully. ************************************************************* void european(void) Usage: european() Description: This function causes outtext() and outtextxy() to generate text in the "european" stroked font. Considerations: EURO.CHR is linked into .EXE file and RAM usage and disk space requirements increase. See Also: triplex(), little(), gothic(), sansserif(), script(), italic(), complex(), simple(), bitmap(), bold() Example: #include #include void main(){ magic_setup(); bestvideo(); european(); outtextxy(0,0,"European font"); waitforuser(); cleanup(); } Performance of example: Program writes "European font" on screen using the "European" font. ************************************************************* int figurehowlong(void) - function Usage: /* example */ number = figurehowlong(); Description: Figurehowlong() works the global character array variable sent[81][46] and returns the global int variable howlong. Howlong is the length of the longest string currently in the array. If in text mode, howlong will represent the number of characters in the longest string. If in a graphics mode, it will represent the length in pixels using the currently selected font and font proportions. Figurehowlong() also calls figurehowmany(). If centerjustify > 0 then figurehowlong() also pads any strings shorter than the longest one with spaces for center justification. Considerations: Figurehowlong() is called automatically by pop() and functions that use pop() such as getanykey(), getyn(), dialog() and menu(). See Also figurehowmany(), howmany, howlong, sent[] Example: #include #include void main(){ char userstring_1[80],userstring_2[80]; magic_setup(); . . pile(userstring_1); pile(userstring_2); figurehowlong(); if (howlong < 76) getanykey(-1,-1); } Performance of example: The program somehow gets two strings of characters and they are assigned to sent[]. If they are short enough, less than 76 characters, they are displayed. ************************************************************* int figurehowmany(void) - function Usage: /* example */ number = figurehowmany(); Description: Figurehowmany() works the global character array variable sent[81][46] and returns the global int variable howmany. Howmany is the number of strings which will be displayed by pop() and the functions which use pop(). As you know, strings are assigned from the lowest number to the highest, and any unused strings contain no text. Figurehowlong() starts at the maximum possible string (46) and decrements howlong until text is encountered. Considerations: Figurehowmany() is called automatically by figurehowlong(). See Also figurehowlong(), howmany, howlong, sent[] Example: #include #include void main(){ char userstring[81][20]; magic_setup(); . . . pile(userstring[x]); pile(userstring[x + 1]); figurehowmany(); if (howmany < 12) getanykey(-1,-1); else getanykey(-1,1); } Performance of example: The program somehow gets several strings of characters and they are assigned to sent[]. If the total number of strings is less than 12 then getanykey() pops up in the center of the screen. If there are more than 11 strings, then getanykey() pops up at the top of the screen. ************************************************************* void fileread(void) - function Usage: fileread() Description: Fileread() is a function that automatically reads one character from the pre-declared Magic file called infile. Opening and closing the file is automatic. Only one character is read and the next call to fileread() will get the next character in the file. The global char variable "u" contains the character read. Considerations: The file is called 'Infile' within the program, but must have an external name under which it will be stored on disk. You may 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 set the global char variable "problem" to 1. Otherwise problem will be 0. See Also: nameinfile(), filereadln(), problem {Magic} reset(), feof() {Borland} Example: #include #include void main() { magic_setup(); xclear(); nameinfile("sample.doc"); for (a = 0; a <= 1000; a++) { fileread(); if (problem) break; printf("%c",u); } } 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. If the file is shorter than 1000 characters, problem will become 1 and the program will end prematurely. ************************************************************* void filereadln(void) - function Usage: filereadln() Description: Filereadln() is a function that automatically reads one line of text from the pre-declared Magic file called infile. Opening and closing the file is automatic. Only one line (string) is read and the next call to filereadln() will get the next string in the file. The global char array variable "answer" contains the character read. Considerations: The file is called 'Infile' within the program, but must have an external name under which it will be stored on disk. You may 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 set the global char variable "problem" to 1. Otherwise problem will be 0. Lines of text in a file are considered terminated with the character pair #13 followed by #10 (carriage return/linefeed). Answer follows the C convention of null termination (#0), and the carriage return/linefeed pair is stripped off. See Also: nameinfile(), fileread(), problem {Magic} reset(), feof() {Borland} Example: #include #include void main() { magic_setup(); xclear(); nameinfile("sample.doc"); do { filereadln(); printf("%s",answer); } while (!problem); } Performance of example: The screen is cleared. The file to read will be 'Sample.Doc'. Assuming the file exists, each line from that file will be displayed on the screen, then the program ends. ************************************************************* void filewrite(unsigned char character) - function Usage: filewrite(thing) Description: Filewrite() will write a character into the standard output file. Opening and closing the file is handled automatically. If the file exists, the character will be appended to the end. If the file does not exist it will be created. Considerations: The standard text output file is called "outfile" within Magic, but must have an external name under which it will be stored on disk. You may 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 int variable, problem will be 1. If all is ok problem is 0. Only one 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 character. See Also: nameoutfile(), filewriteln(), problem {Magic} all the string handling functions {Borland} Example: #include void main() { magic_setup(); nameoutfile("sample.doc"); filewrite("T"); } Performance of example: The standard text file is renamed "SAMPLE.DOC". A single character is 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 with the IDE, you will see the file contains only: T. ************************************************************* void filewriteln(unsigned char *string) - function Usage: filewrite(thing) Description: Filewriteln() will write a string into the standard 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. Considerations: The standard text output file is called "outfile" within Magic, but must have an external name under which it will be stored on disk. You may first call nameoutfile, before using filewriteln(), 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 int variable, problem will be 1. If all is ok problem is 0. Only one string can be written to the output file with a single call to filewriteln(). The C standard null termination (ASCII #0) will be removed and an ASCII standard carriage return and linefeed will be added (ASCII #13,#10). No numerical values can be written unless they are first converted to a string. See Also: nameoutfile(), filewrite(), problem {Magic} all the string handling functions {Borland} Example: #include #include void main() { magic_setup(); nameoutfile("sample.doc"); strcpy(sent[1],"This is a test."); strcpy(sent[2],"This is the second line of test."); filewriteln(sent[1]); filewriteln(sent[2]); } 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 lines are 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 with the IDE, you will see the file contains: This is a test. This is the second line of test. ************************************************************* void getanykey(int x, int y) - function Usage: getanykey(x,y) 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. When done, getanykey() assigns the value of the key pressed to the global unsigned char variable "u." If a mouse button was clicked, the global char variable "keydetect" will be 0. If an alphanumeric key was pressed keydetect will be 1 and if an extended key (such as [f2] or [Page Down]) keydetect will be 2. 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..." There is a limit to the maximum size of a getanykey() box. For instance, in VGA-HI graphics mode, the limit is about 20 lines of text with the longest line being about 40 characters long. See Also: menu(), pop(), dialog(), getyn(), sent[]. Example: #include void main (){ magic_setup(); . . pile("You have selected an option available only"); pile("to registered users. Please send money!!!"); pile("Press any key to continue..."); getanykey(-1,-1); . . } 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. ************************************************************* Continued in file: MAGIC.2 (This file is split into three parts because some older versions of Turbo C cannot display files larger than 64k. If you have a newer compiler which supports large files, you may want to recombine these three parts.)