
                                    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 <magic.h>
         #include <string.h>
         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 <magic.h>
         #include <string.h>
         #include <conio.h>
         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 <magic.h>
         #include <string.h>
         #include <conio.h>
         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 <magic.h>
         #include <graphics.h>
         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.h>
         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 <magic.h>
         #include <graphics.h>
         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 <magic.h>
         #include <graphics.h>
         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 <magic.h>
         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 <magic.h>
         #include <conio.h>
         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 <magic.h>
         #include <conio.h>
         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 <magic.h>
         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 <magic.h>
         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 <magic.h>
         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 <magic.h>
         #include <graphics.h>
         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 <magic.h>
         #include <graphics.h>
         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 <magic.h>
         #include <graphics.h>
         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 <magic.h>
         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 <magic.h>
         #include <graphics.h>
         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 <magic.h>
         #include <string.h>
         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 <magic.h>
         #include <string.h>
         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 <magic.h>
         #include <graphics.h>
         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 <magic.h>
         #include <graphics.h>
         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 <magic.h>
         #include <graphics.h>
         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 <magic.h>
         #include <string.h>
         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 <magic.h>
         #include <string.h>
         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 <magic.h>
         #include <stdio.h>
         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 <magic.h>
         #include <stdio.h>
         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 <magic.h>
         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 <magic.h>
         #include <string.h>
         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 <magic.h>
         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.)
