home *** CD-ROM | disk | FTP | other *** search
/ World of Shareware - Software Farm 2 / wosw_2.zip / wosw_2 / CPROG / CMAGIC.ZIP / MAGIC.2 < prev    next >
Text File  |  1992-09-06  |  60KB  |  1,524 lines

  1.  
  2.                            Continued from MAGIC.TXT
  3.  
  4.          *************************************************************
  5.          void getinfile(void) - function
  6.  
  7.          Usage: getinfile()
  8.  
  9.          Description:
  10.             This  function  merely  checks  the validity of a file for
  11.          input (into the program) using the  string,  "infilename[50]"
  12.          as  the file name, and opens the file for input.  If the file
  13.          does not exist, or cannot be opened,  then  the  global  char
  14.          variable  "problem"  is  set  to a number greater than 0.  If
  15.          successful, problem = 0.
  16.  
  17.          Considerations:
  18.             Infile is opened as a binary file, conversions to  strings
  19.          are  handled  automatically  by  Magic.   The   default   for
  20.          infilename is "INPUT."
  21.  
  22.          See Also:
  23.          getoutfile(),    nameinfile(),    fileread(),    filereadln()
  24.          infilename
  25.  
  26.          Example:
  27.          #include<magic.h>
  28.          void main(){
  29.             magic_setup();
  30.             nameinfile("testfile.1");
  31.             getinfile();
  32.             if (problem > 0) printf("Problem with testfile.1");
  33.             waitforuser();
  34.          }
  35.  
  36.          Performance of example:
  37.          Program  checks  to see if a disk file named "testfile.1" can
  38.          be opened for reading.  If not, "Problem with testfile.1"  is
  39.          printed to screen.
  40.  
  41.          *************************************************************
  42.          void getoutfile(void) - function
  43.  
  44.          Usage: getoutfile()
  45.  
  46.          Description:
  47.             This  function  merely  checks  the validity of a file for
  48.          output (to disk) using the string, "outfilename[50]"  as  the
  49.          file name, and opens the file for output.  If the file cannot
  50.          be  opened, then the global char variable "problem" is set to
  51.          a number greater than 0.  If successful, problem = 0.
  52.  
  53.          Considerations:
  54.             Outfile  is  opened  as  a  binary  file.   Conversions to
  55.          strings are handled automatically by  Magic  file  functions.
  56.          If  file  already  exists, it is opened for appending.  If it
  57.          does not exist, it is created. The default for outfilename is
  58.          "OUTPUT."
  59.  
  60.          See Also:
  61.          getinfile(),    nameoutfile(),   filewrite(),   filewriteln()
  62.          outfilename
  63.  
  64.          Example:
  65.          #include<magic.h>
  66.          void main(){
  67.             magic_setup();
  68.             nameoutfile("testfile.1");
  69.             getoutfile();
  70.             if (problem > 0) printf("Problem with testfile.1");
  71.             waitforuser();
  72.          }
  73.  
  74.          Performance of example:
  75.          Program checks to see if a disk file named  "testfile.1"  can
  76.          be  opened for writing.  If not, "Problem with testfile.1" is
  77.          printed to screen.
  78.  
  79.          *************************************************************
  80.          char getvmode(void) - function
  81.  
  82.          Usage: x = getvmode()
  83.  
  84.          Description:
  85.              This function returns the current video mode as  per  the
  86.          following chart:
  87.  
  88.          if getvmode = 0 then current video = 80 x 25 text
  89.          if getvmode = 1 then current video = CGA 640 x 200 2-color
  90.          if getvmode = 2 then current video = CGA 320 x 200 4-color
  91.          if getvmode = 3 then current video = EGA-lo 640 x 200 16-color
  92.          if getvmode = 4 then current video = EGA 640 x 350 16-color
  93.          if getvmode = 5 then current video = Hercules Monochrome
  94.          if getvmode = 6 then current video = VGA 640 x 480 16-color
  95.          if getvmode = 7 then current video = VGA 320 x 200 256-color
  96.  
  97.          Considerations:
  98.              This  will work whether or not the Borland/Turbo graphics
  99.          function "initgraph() was used  to  initialize  the  graphics
  100.          mode.
  101.  
  102.          See Also:
  103.          initgraph(), setgraphmode(), getgraphmode() {Borland}
  104.  
  105.          Example:
  106.          #include <magic.h>
  107.          void main() {
  108.             magic_setup();
  109.             .
  110.             .
  111.             if (getvmode == 2) pile("We are in CGA 4-color mode");
  112.             if (getvmode == 0) pile("We are in text mode");
  113.             getanykey(-1,-1);
  114.          }
  115.  
  116.          Performance of example:
  117.          The example shows the user what video mode is in operation if
  118.          the current mode is CGA 4-color or text mode.
  119.  
  120.          *************************************************************
  121.          void getyn(int x, int y) - function
  122.  
  123.          Usage: getyn(x,y)
  124.  
  125.          Description:
  126.               A message pops up on the screen then waits for the  user
  127.          to  press  'Y' or 'N' or click a mouse button. You must write
  128.          strings  for  the  array  of  sent[]s  before  calling   this
  129.          procedure.  After  the  user presses a key, all traces of the
  130.          pop-up and the sent[]s disappear.
  131.              Getyn()   requires   two  integer  variables,  the  first
  132.          determines the horizontal position on  the  screen,  and  the
  133.          second  is  the  vertical  coordinate.   If  either number is
  134.          negative, the pop-up message will be centered on  the  screen
  135.          in the corresponding dimension.
  136.              Getyn() sets the global unsigned char, to 'Y' or 'N'.
  137.  
  138.          Considerations:
  139.             Maximum sent array size: 18. Make sure to add something to
  140.          this  effect  to every message to avoid confusing your users:
  141.          "Press [Y] or [N]..." getyn() is  not  case  sensitive.   The
  142.          user  can  type  upper  or lower case [y] or [n]. If the left
  143.          mouse button is clicked answer is set to 'Y' and if the right
  144.          mouse button is clicked answer = 'N'.  The character returned
  145.          to "u" is always capitalized.
  146.              There  is  a limit to the maximum size of a  getyn() box.
  147.          For instance, in VGA-HI graphics mode, the limit is about  20
  148.          lines of text with the longest line being about 40 characters
  149.          long.
  150.  
  151.          See Also: menu(), pop(), dialog(), getyn(), sent[], u.
  152.  
  153.          Example:
  154.          #include <magic.h>
  155.          void main () {
  156.             magic_setup();
  157.             .
  158.             .
  159.             pile("Exit to Dos? (Y/N)");
  160.             getyn(-1,1);
  161.             if (u == 'Y') cleanup();
  162.             .
  163.             .
  164.          }
  165.  
  166.          Performance of example:
  167.              A box pops up on the screen containing one line and waits
  168.          for the user to press a key. Until the key pressed  is  upper
  169.          or lower case 'Y' or 'N', or until the user  clicks  a  mouse
  170.          button, the box remains. Then the global char u is set to 'Y'
  171.          or 'N.' If answer = 'Y' then the program terminates cleanly.
  172.  
  173.          *************************************************************
  174.          void gothic(void) - function
  175.  
  176.          Usage: gothic()
  177.  
  178.          Description:
  179.          This function causes outtext() and  outtextxy()  to  generate
  180.          text in the "gothic" stroked font.
  181.  
  182.          Considerations:
  183.              GOTH.CHR  is linked into .EXE file and RAM usage and disk
  184.          space requirements increase.
  185.  
  186.          See Also:
  187.              triplex(),  little(),  bold(),  sansserif(),  script(),
  188.          italic(), complex(), simple(), bitmap(), european()
  189.  
  190.          Example:
  191.          #include <magic.h>
  192.          #include <graphics.h>
  193.          void main(){
  194.             magic_setup();
  195.             bestvideo();
  196.             gothic();
  197.             outtextxy(0,0,"Gothic font");
  198.             waitforuser();
  199.             cleanup();
  200.          }
  201.  
  202.          Performance of example:
  203.          Program writes "Gothic font" on  screen  using  the  "gothic"
  204.          font.
  205.  
  206.          *************************************************************
  207.          void hercvideo(void) - function
  208.  
  209.          Usage: hercvideo()
  210.  
  211.          Description:
  212.          This  initializes  the  system  in  Hercules  graphics  mode.
  213.          Hercules video driver will be automatically compiled into the
  214.          .EXE program file, eliminating the need for external HERC.BGI
  215.          file.  Program will use 719 x 348 resolution, monochrome.
  216.  
  217.          Considerations:
  218.          Will  not work on CGA or EGA-equipped computers. Graphmode is
  219.          initially set to 0 (see Borland manual for more details).
  220.  
  221.          See Also:
  222.          bestvideo(),    cgalovideo(),   cgahivideo(),   egahivideo(),
  223.          egalovideo(),   vgahivideo(),   vgalovideo(),    textvideo(),
  224.          cleanup() {Magic} setgraphmode() {Borland}
  225.  
  226.          Example:
  227.          #include <magic.h>
  228.          #include <graphics.h>
  229.          void main() {
  230.             magic_setup();
  231.             hercvideo();
  232.             rectangle(10,10,709,337);
  233.             waitforuser();
  234.             cleanup();
  235.          }
  236.  
  237.          Performance  of  example:  The  system  is  put  in  Hercules
  238.          graphics mode.  A large rectangle is displayed until any  key
  239.          is pressed.  The program then terminates gracefully.
  240.  
  241.          *************************************************************
  242.          void hidecursor(void) - function
  243.  
  244.          Usage: hidecursor()
  245.  
  246.          Description:
  247.          This  makes  the  text  cursor disappear until it is moved to
  248.          another screen location. Generally, use it after  writing  to
  249.          the screen when the user is not expected to type input.
  250.  
  251.          Considerations:
  252.             For   text   mode   only,   has  no  effect  in  graphics.
  253.          Hidecursor()   is   called   automatically   by  getanykey(),
  254.          getyn(), pop() and menu().
  255.  
  256.          See Also: bigcursor(), littlecursor()
  257.  
  258.          Example:
  259.          #include <magic.h>
  260.          #include <stdio.h>
  261.          void main() {
  262.             magic_setup();
  263.             printf("There is no cursor at the end of this line.");
  264.             hidecursor();
  265.             waitforuser();
  266.          }
  267.  
  268.          Performance of example:
  269.             A  line  of  text  appears  on the screen, but there is no
  270.          cursor at the end of the line.
  271.  
  272.          *************************************************************
  273.          char holdingmouse - Global Variable
  274.  
  275.          Usage:   This   is  used  internally  by  Magic.lib.   Direct
  276.          manipulation is  not  recommended,  but  you  can  test  this
  277.          variable  to  see  if  a  mouse  pointer  is  currently being
  278.          displayed.
  279.  
  280.          Description:
  281.              This variable can be checked to see if  a  mouse  pointer
  282.          (arrow)  is  currently  being displayed. When holdingmouse is
  283.          greater than 0, a mouse pointer is being handled.
  284.  
  285.          Considerations:
  286.          Do not change this variable.  Results would be unpredictable.
  287.  
  288.          *************************************************************
  289.          void holdon(void) - function
  290.  
  291.          Usage: holdon()
  292.  
  293.          Description:
  294.              Holdon() stalls any further action until the user presses
  295.          any key or clicks a mouse button.  This function is identical
  296.          to waitforuser().
  297.  
  298.          Considerations:
  299.  
  300.          See Also:
  301.             waitforuser()
  302.  
  303.          Example:
  304.          #include <magic.h>
  305.          void main() {
  306.             magic_setup();
  307.             pile("Test");
  308.             pop(-1,-1);
  309.             holdon();
  310.             restore();
  311.          }
  312.  
  313.          Performance of example:
  314.              A single string  appears  in  a  text  box.   Instead  of
  315.          quitting  immediately,  the  program waits until holdon() has
  316.          been satisfied with a keypress or a mouse click.
  317.  
  318.          *************************************************************
  319.          int howlong - Global Variable
  320.  
  321.          Usage: /* example */ x = howlong
  322.  
  323.          Description
  324.              Howlong is a global int variable used by  Magic  to  keep
  325.          track  of  the length of the longest string within the global
  326.          char array, "sent[]".  Use the  function, figurehowlong()  to
  327.          update howlong.
  328.              Howlong  counts the number of characters in the string if
  329.          in  text mode, but in a graphics mode, it contains the number
  330.          of pixels to display the  longest  string  in  the  currently
  331.          selected    graphics   mode,   font   and   horizontal   font
  332.          magnification.
  333.  
  334.          Considerations:
  335.              Although  you  can directly change this variable, in most
  336.          cases, you should use it only  for  testing,  and  leave  the
  337.          automatic  string handling to the inner workings of the Magic
  338.          library.
  339.  
  340.          See Also:
  341.          howmany, figurehowlong(), figurehowmany(), clearsents()
  342.  
  343.          Example:
  344.          see figurehowlong()
  345.          *************************************************************
  346.          int howmany - Global Variable
  347.  
  348.          Usage: /* example */ y = howmany
  349.  
  350.          Description
  351.              Howmany is a global int variable used by  Magic  to  keep
  352.          track  of  the  number  of strings containing text within the
  353.          char array, "sent[]".  Use the  function, figurehowlong()  to
  354.          update howlong.
  355.  
  356.          Considerations:
  357.             See figurehowmany() for more details.
  358.  
  359.          See Also:
  360.          howlong, figurehowlong(), figurehowmany(), clearsents()
  361.  
  362.          Example:
  363.          see figurehowmany()
  364.  
  365.          *************************************************************
  366.          file* infile - Global Variable
  367.  
  368.          Usage: /* example */ fopen(infile,"Things.Doc","wt")
  369.  
  370.          Description:
  371.             Infile is declared globally as a file pointer. It is  most
  372.          often used for importing information into your  program  with
  373.          the  automatic  procedures  fileread() and filereadln().  The
  374.          default string assigned to infile as the name under which  it
  375.          is  read  from  disk is "INPUT", but this can be changed with
  376.          nameinfile().
  377.  
  378.          Considerations:
  379.          You  can  override  the automatic use of infile in Magic with
  380.          standard Borland/Turbo C techniques such as fopen() fclose(),
  381.          fprintf() and fscanf(). Infile is handled as a  binary  file.
  382.          Conversions  to  strings  are made automatically by the Magic
  383.          functions.
  384.  
  385.          See Also:
  386.          fileread(), filereadln(), nameinfile(), outfile()  {Magic};
  387.          Also all file handling functions {Borland manuals}
  388.  
  389.          Example:
  390.          #include <magic.h>
  391.          void main() {
  392.             magic_setup();
  393.             nameinfile("TESTFILE.TXT");
  394.             filereadln();
  395.             .
  396.             .
  397.             fclose(infile);
  398.             nameinfile("TESTFILE.2");
  399.             filereadln();
  400.             .
  401.             .
  402.          }
  403.  
  404.          Performance of example:
  405.               Nameinfile()  is  used  to  cause  infile  to  be called
  406.          "TESTFILE.TXT" when referenced on disk.  A line  of  text  is
  407.          read  from  it,  then  infile  is  closed.  Infile is renamed
  408.          "TESTFILE.2" and another line of text is  read  from  infile,
  409.          but infile is actually a different file on the disk.
  410.  
  411.          *************************************************************
  412.          char infilename[50] - Global Variable
  413.  
  414.          Usage: /* example */ strcpy(infilename,"testfile.1")
  415.  
  416.          Description:
  417.              Infilename is an array of 50 characters used  to  hold  a
  418.          string   for   identifying   INFILE  (see  above).   Standard
  419.          string character array procedures may be used  to  manipulate
  420.          infilename.  This is the  string  getinfile(),  nameinfile(),
  421.          fileread() and filereadln() use to identify infile.
  422.  
  423.          Considerations:
  424.              The  default  for  infilename  is   "INPUT."    Normally,
  425.          nameinfile() is used to change infilename.
  426.  
  427.          Example:
  428.              #include <magic.h>
  429.              #include <string.h>
  430.              void main() {
  431.                 .
  432.                 .
  433.                 if (strlen(infilename)) < 4)
  434.                    printf("We have a very short file name");
  435.                 .
  436.                 .
  437.               }
  438.  
  439.          Performance of example:
  440.              If  infilename  is  less  than 4 characters long then the
  441.          program prints, "We have a very short file name."
  442.  
  443.          *************************************************************
  444.          void italic(void) - function
  445.  
  446.          Usage: italic()
  447.  
  448.          Description:
  449.          This function causes outtext() and  outtextxy()  to  generate
  450.          text in the "italic" stroked font.
  451.  
  452.          Considerations:
  453.              TSCR.CHR  is linked into .EXE file and RAM usage and disk
  454.          space requirements increase.  This font will  not  work  with
  455.          older versions of Borland compilers.
  456.  
  457.          See Also:
  458.              triplex(),  little(),  gothic(),  sansserif(),  script(),
  459.          bold(), complex(), simple(), bitmap(), european()
  460.  
  461.          Example:
  462.          #include <magic.h>
  463.          #include <graphics.h>
  464.          void main(){
  465.             magic_setup();
  466.             bestvideo();
  467.             italic();
  468.             outtextxy(0,0,"Italic font");
  469.             waitforuser();
  470.             cleanup();
  471.          }
  472.  
  473.          Performance of example:
  474.          Program  writes  "Italic  font"  on screen using the "italic"
  475.          font.
  476.  
  477.          *************************************************************
  478.          char keydetect - Global Variable
  479.  
  480.          Usage: /* example */ if (keydetect == 2) printf("extended key")
  481.  
  482.          Description:
  483.              This  global char  variable  is  updated  every  time the
  484.          Magic library checks for mouse  action  or  a  keypress.   In
  485.          addition  to  updating  the  global unsigned char variable u,
  486.          which will contain the  direct  results  of  the  key  press,
  487.          keydetect  is  updated.   If  keydetect is 0, a mouse key was
  488.          pressed, or no action has occurred.   If  keydetect  is  1  a
  489.          normal, alphanumeric key has been pressed.  If keydetect is 2
  490.          then a function key was pressed.
  491.  
  492.          Considerations:
  493.             See poll() for more details.
  494.  
  495.          See Also:
  496.          poll(), xreadkey(), u
  497.  
  498.          Example:
  499.             see poll();
  500.          *************************************************************
  501.          char left - Global Variable
  502.  
  503.          Usage: /* example */ if (left) break;
  504.  
  505.          Description:
  506.             Left  is  a global char variable used to record the status
  507.          of the left mouse button.  If left = 1 then  the  left  mouse
  508.          button has been pressed, otherwise left = 0.
  509.  
  510.          Considerations:
  511.             The status of left will change with every call to  poll(),
  512.          waste(), resetmouse() or procedures within Magic which handle
  513.          text or pop up boxes.
  514.  
  515.          See Also: poll(), waste(), ResetMouse(), center, right
  516.  
  517.          Example:
  518.          #include <magic.h>
  519.          void main() {
  520.             magic_setup();
  521.             waste();
  522.             pile("Nothing will change until you click the");
  523.             pile("left mouse button");
  524.             pop(-1,-1);
  525.             do poll; while (!left);
  526.          }
  527.  
  528.          Performance of example:
  529.             A box containing two lines of text will stay on the screen
  530.          until the user clicks the left  mouse  button.   The  program
  531.          will then terminate.
  532.  
  533.          *************************************************************
  534.          void little(void) - function
  535.  
  536.          Usage: little()
  537.  
  538.          Description:
  539.          This function causes outtext() and  outtextxy()  to  generate
  540.          text in the "little" stroked font.
  541.  
  542.          Considerations:
  543.              LITT.CHR  is linked into .EXE file and RAM usage and disk
  544.          space requirements increase.
  545.  
  546.          See Also:
  547.              triplex(),   bold(),   gothic(),  sansserif(),  script(),
  548.          italic(), complex(), simple(), bitmap(), european()
  549.  
  550.          Example:
  551.          #include <magic.h>
  552.          #include <graphics.h>
  553.          void main(){
  554.             magic_setup();
  555.             bestvideo();
  556.             little();
  557.             outtextxy(0,0,"Little font");
  558.             waitforuser();
  559.             cleanup();
  560.          }
  561.  
  562.          Performance of example:
  563.          Program writes "Little font" on  screen  using  the  "little"
  564.          font.
  565.  
  566.          *************************************************************
  567.          void littlecursor(void) - function
  568.  
  569.          Usage: littlecursor()
  570.  
  571.          Description:
  572.          After  a call to littlecursor(), the cursor in text mode will
  573.          be a standard underline (DOS default cursor). This is used in
  574.          programs after a call to hidecursor() or bigcursor().
  575.  
  576.          Considerations:
  577.             Has  no  effect  in  graphics  modes, but will resume as a
  578.          small cursor when returned to text mode.
  579.  
  580.          See Also:
  581.          bigcursor(), hidecursor()
  582.  
  583.          Example:
  584.          #include <magic.h>
  585.          void main(){
  586.             magic_setup();
  587.             littlecursor();
  588.             printf("Little underline cursor at the end of this line!");
  589.          }
  590.  
  591.          Performance of Example:
  592.          This program will write 'Little underline cursor at  the  end
  593.          of this line', then quit.
  594.  
  595.          *************************************************************
  596.          void magic_setup(void) - function
  597.  
  598.          Usage: magic_setup()
  599.  
  600.          Description:
  601.              This function should be  called  once  in  every  program
  602.          which  uses  anything from the Magic library.  It initializes
  603.          variables and sets up  "links"  to  functions  in  the  Magic
  604.          library.
  605.  
  606.          Considerations:
  607.               Use of any Magic functions without calling magic_setup()
  608.          within  the  program will have unpredictable results.  Do not
  609.          call magic_setup() twice in one program.
  610.  
  611.          Example:
  612.              #include <magic.h>
  613.              void main(){
  614.                magic_setup();
  615.                .
  616.                .
  617.  
  618.          Performance of example:
  619.              The above program is prepared for whatever you want to do
  620.          with the Magic library.
  621.  
  622.          *************************************************************
  623.          void makemouse(void) - function
  624.  
  625.          Usage: This is for internal use of the Magic Library.  Do not
  626.          use this function independently.
  627.  
  628.          Description:
  629.              This actually draws the mouse arrow on the screen.
  630.  
  631.          Considerations:
  632.              Has no effect in text mode.   Works  with  or  without  a
  633.          mouse  actually  being  present.   Mouse  cursor shape can be
  634.          easily customized if you have purchased the source code.
  635.  
  636.          *************************************************************
  637.          char mainback - Global Variable
  638.  
  639.          Usage: mainback = color;
  640.  
  641.          Description:
  642.          Color is represented with an  integer  from  0  to  15  or  a
  643.          pre-defined   color   constant   enumerated   in  CONIO.H  or
  644.          GRAPHICS.H. Changing the value of mainback  will  affect  the
  645.          main screen background color.
  646.  
  647.          Considerations:
  648.             Do not use background colors above 7 in text mode. May not
  649.          have the expected effect when used with the limited  palettes
  650.          of  4-color  CGA (mode 0,1 or 2), 2-color CGA or Hercules. To
  651.          see effect after changing mainback, call xclear().
  652.  
  653.          See Also:
  654.          boxback, maintext, boxtext, barback, bartext.
  655.  
  656.          Example:
  657.          #include <magic.h>
  658.          #include <conio.h>
  659.          void main() {
  660.             magic_setup();
  661.             mainback := GREEN;
  662.             xclear();
  663.             pile("Do you like this background color?");
  664.             getanykey(-1,-1);
  665.          }
  666.  
  667.          Performance of example:
  668.          The  main background color is set to green. A box will appear
  669.          on the screen asking a silly question.  The  main  background
  670.          will be green.  When a key is pressed, the program quits.
  671.  
  672.          *************************************************************
  673.          char maintext - Global Variable
  674.  
  675.          Usage: maintext = color;
  676.  
  677.          Description:
  678.          Color  is  represented  with  an  integer  from  0 to 15 or a
  679.          pre-defined  color  constant   enumerated   in   CONIO.H   or
  680.          GRAPHICS.H.  Changing  the  value of maintext will affect the
  681.          color of text printed outside of pop-up boxes.
  682.  
  683.          Considerations:
  684.          May not have the expected effect when used with  the  limited
  685.          palettes  of  4-color  CGA  (mode  0,1  or 2), 2-color CGA or
  686.          Hercules.  No Magic functions actually use this variable, but
  687.          you can use it yourself with cprintf() and gotoxy() to  write
  688.          text outside of pop-ups.
  689.  
  690.          See Also:
  691.          boxback, mainback, boxtext, barback, bartext.
  692.  
  693.          Example:
  694.          #include <magic.h>
  695.          #include <conio.h>
  696.          void main() {
  697.             magic_setup();
  698.             xclear();
  699.             maintext := YELLOW;
  700.             gotoxy(42,7);
  701.             cprintf("Do you like this background color?");
  702.             waitforuser();
  703.          }
  704.  
  705.          Performance of example:
  706.          The  main background color is cleared to the default color of
  707.          blue.  A line of text appears in yellow.
  708.  
  709.          *************************************************************
  710.          char mc - Global Variable
  711.  
  712.          Usage:  /* example */ if (mc == 2){..}
  713.  
  714.          Description:
  715.              Mc is a global char variable used to keep track  of  menu
  716.          item selection.  See menu() for more details.
  717.  
  718.          *************************************************************
  719.          char *mem - Global Variable
  720.  
  721.          Usage:  For  internal  use by the Magic library only.  Do not
  722.          manipulate directly.
  723.  
  724.          Description:  Mem is used to point to the starting address of
  725.          the graphics video RAM.
  726.  
  727.          *************************************************************
  728.          void menu(int x, int y) - function
  729.  
  730.          Usage: menu(x,y);
  731.  
  732.          Description:
  733.              Menu() pops a box on the screen  showing  lines  of  text
  734.          from  the array sent[81][46]. One of the lines is highlighted
  735.          and a user can move the highlight to any of the  other  items
  736.          by  moving  the  mouse or pressing the up or down arrow keys.
  737.          When the user  presses  [Enter]  or  clicks  the  left  mouse
  738.          button,  or  presses  any  alphanumeric  key,  the  currently
  739.          highlighted item  number  is  assigned  to  the  global  char
  740.          variable  mc.  Also,  the key pressed will be assigned to the
  741.          char global variable "u". The pop-up box disappears  and  the
  742.          array of strings (sent[81][46]) is cleared.
  743.              Two  integer parameters are required, the first indicates
  744.          the horizontal position of the  upper  left  corner  and  the
  745.          second  is for the vertical position.  If either integer is a
  746.          negative number, that integer will be ignored  and  the  menu
  747.          will   be   centered  on  the  screen  in  the  corresponding
  748.          dimension.
  749.             Before calling menu(), a global char variable, "mc" should
  750.          be given a value.  "Mc" is the  current  MenuChoice,  meaning
  751.          the  sent[]  corresponding  to mc is the one highlighted.  If
  752.          you state: mc = 1 then the first item on  the  menu  will  be
  753.          highlighted.   If  you  forget  to  assign  mc, a random menu
  754.          choice will be highlighted with your first call to menu().
  755.              You can then use u or mc to perform operations related to
  756.          your user's choice.
  757.              Because when menu() is done, the sent[]s are all cleared,
  758.          to have the menu  return  to  the  screen,  sent[]s  must  be
  759.          refilled  with  your strings and menu() must be called again.
  760.          The usual way to use menu() is to put it into a  repeat  loop
  761.          as shown in the example below.
  762.              If the left mouse button is clicked u = 13.  If the right
  763.          mouse button is clicked  u  =  27.   Also,  if  user  presses
  764.          [Enter] left = 1, and if [Esc] right = 1.
  765.  
  766.          Considerations:
  767.              Maximum sent[]s  =  18; Should assign a value to mc of at
  768.          least one  and  less  than  the  maximum  sent[]  used.  Must
  769.          reassign  text to the sent[]s for subsequent calls to menu().
  770.              In text mode, do not use background colors above 7.
  771.              There is a limit to the maximum size of a menu() box. For
  772.          instance, in VGA-HI graphics mode,  the  limit  is  about  20
  773.          lines of text with the longest line being about 40 characters
  774.          long.
  775.  
  776.          See also: sent[], pop(), getyn(), getanykey()
  777.  
  778.          Example:
  779.          #include <magic.h>
  780.          #include <string.h>
  781.          #include <ctype.h>
  782.          void main() {
  783.             magic_setup();
  784.             mc = 1;
  785.             do
  786.                strcpy(sent[1],"Do Thing One");
  787.                strcpy(sent[2],"Do Thing Two");
  788.                strcpy(sent[3],"Do Thing tHree");
  789.                strcpy(sent[4],"Do Thing Four");
  790.                strcpy(sent[5],"Do Thing fiVe");
  791.                strcpy(sent[6],"Do Thing Six");
  792.                strcpy(sent[7],"   Quit   ");
  793.                Menu(-1,-1);
  794.                if (left) {
  795.                   switch (mc) {
  796.                      case 1 : function1(); break;
  797.                      case 2 : function2(); break;
  798.                      case 3 : function3(); break;
  799.                      case 4 : function4(); break;
  800.                      case 5 : function5(); break;
  801.                      case 6 : function6(); break;
  802.                      case 7 : exit(0);
  803.                   } /* end of switch */
  804.                } /* end of "if (left)" */
  805.                switch (toupper(u)) {
  806.                   case 'O' : function1(); break;
  807.                   case 'T' : function2(); break;
  808.                   case 'H' : function3(); break;
  809.                   case 'F' : function4(); break;
  810.                   case 'V' : function5(); break;
  811.                   case 'S' : function6(); break;
  812.                   case 'Q' : exit(0);
  813.                }
  814.             while (u != 27);
  815.             cleanup();
  816.          }
  817.  
  818.          Performance of example:
  819.              Mc is set to 1 so when the menu pops up, the  first  item
  820.          will  be  highlighted.   Seven sent[]s are given strings. The
  821.          menu pops up and the user  presses  a  key  or  operates  the
  822.          mouse.   Then  if  u is 13, (because the left mouse button or
  823.          [Enter] has been pressed), a  switch  statement  figures  out
  824.          what to do with the user's menu choice.
  825.             If mc is between 1 and 6, one of the functions is called.
  826.          Of  course,  these functions can do anything you wish, based
  827.          upon what menu item the user  has  selected.  The  last  menu
  828.          choice  (sent[7])  is  'Quit'  and will cause this program to
  829.          terminate.
  830.             U  is  changed  into  an  uppercase  letter  so  that  the
  831.          following switch will work whether the user presses a capital
  832.          or small letter. This second switch checks to see whether the
  833.          user selected a menu item based upon the  capitalized  letter
  834.          hints.  You  can  also  use  function  keys here.  The #0 has
  835.          already been stripped off, so if you get a ';', for instance,
  836.          then the user pressed [F1]  and  probably  wants  'help.'  To
  837.          determine  whether  the  user  pressed  [;] or [F1] check the
  838.          global  variable  keydetect.   If  an  alphanumeric  key  was
  839.          pressed  keydetect will be 1.  If an extended key, it will be
  840.          set to 2.
  841.              Assuming  the  user  did not select 'Quit' or press [Esc]
  842.          (ASCII #27) or the right mouse button, the menu process  will
  843.          repeat.  When  the  user  finally  does  choose  to quit, the
  844.          cleanup() function returns to DOS gracefully.
  845.  
  846.          *************************************************************
  847.          void menug(void) - function
  848.  
  849.          Usage:  menug() is for internal use  of  the  Magic  library.
  850.          Direct manipulation is not recommended.
  851.  
  852.          Description:
  853.              Menug() is called to display the menu on screen when in a
  854.          graphics mode.
  855.  
  856.          *************************************************************
  857.          char mouseinstalled(void) - function
  858.  
  859.          Usage: /* example */ if (mouseinstalled) printf("Click left...")
  860.  
  861.          Description:
  862.          This function returns  1  if  a  mouse  and  its  driver  are
  863.          installed, and 0 if not.
  864.  
  865.          See Also: poll(), setmouserows(), setmousecolumns()
  866.  
  867.          Example:
  868.          #include <magic.h>
  869.          void main() {
  870.             magic_setup();
  871.             if (!mouseinstalled) pile("Mouse not found");
  872.             else pile("A mouse is present");
  873.             getanykey(10,10);
  874.          }
  875.  
  876.          Performance of Example:
  877.          If there is no mouse then mouseinstalled will be return 0 and
  878.          'Mouse not found' will pop up. If there is a mouse,  then  'A
  879.          mouse  is  present'  will appear on the screen. When the user
  880.          presses a key, the program ends.
  881.  
  882.          *************************************************************
  883.          char musicon - Global Variable
  884.  
  885.          Usage: musicon = 1;
  886.  
  887.          Description:
  888.          This global char variable controls whether the sound  effects
  889.          are  allowed to play.  The default for musicon is 0 resulting
  890.          in no sound effects.  When musicon is  set  to  1,  calls  to
  891.          pink(),   twinkle(),   soundup(),  sounddown(),  sorry()  and
  892.          bugle() will be played.
  893.  
  894.          Considerations:
  895.              Some sound effects are automatically built  in  to  pop()
  896.          and  restore()  which  are  automatically  called  by menu(),
  897.          getanykey(), getyn() and dialog() and will play if musicon is
  898.          set to 1.  The default for musicon is 1.
  899.  
  900.          See Also: pink(), twinkle(), soundup(), sounddown().
  901.  
  902.          Example:
  903.          include <magic.h>
  904.          void main() {
  905.             magic_setup();
  906.             pile("Do you want sound effects? (Y/N)");
  907.             getyn(-1,-1);
  908.             if (u == 'Y') musicon = 1; else musicon = 0;
  909.             twinkle();
  910.          }
  911.  
  912.          Performance of Example:
  913.          The user will be asked to press 'Y' or 'N' for sound effects.
  914.          If the user selects 'Y' then musicon will be 1 and  twinkle()
  915.          will play.  If the user selects 'N' then  no  sound  will  be
  916.          heard.
  917.  
  918.          *************************************************************
  919.          void nameinfile(char *string) - function
  920.  
  921.          Usage: nameinfile(string)
  922.  
  923.          Description:
  924.              This procedure automatically closes the present infile if
  925.          it  is  open  then renames it to string. From this time until
  926.          another call to nameinfile(), the  external  file  associated
  927.          with "infile" will carry the name you have given it.
  928.  
  929.          Considerations:
  930.             If string is a literal, not a  string  variable,  then  it
  931.          must be enclosed in quotation marks. String must be DOS-legal
  932.          with  up  to  8  alphanumeric characters, an optional period,
  933.          then  up  to  a  three  character  extension.    Full   drive
  934.          designator and pathnames are supported up to 50 characters.
  935.  
  936.          See Also:
  937.          filewrite(),   filewriteln(),    fileread(),    filereadln(),
  938.          nameoutfile().
  939.  
  940.          Example:
  941.          include <magic.h>
  942.          include <stdio.h>
  943.          void main() {
  944.             magic_setup();
  945.             nameinfile("TestFile.Txt");
  946.             filereadln();
  947.             printf("%s",answer);
  948.             waitforuser();
  949.          }
  950.  
  951.          Performance of example:
  952.              "Testfile.txt" is assigned to infile.  When  filereadln()
  953.          is  called,  it  looks  to  the  disk  for  the  file  called
  954.          "Testfile.txt" and reads one line. This line is displayed  on
  955.          the  screen. The program terminates when the user presses any
  956.          key.
  957.  
  958.          *************************************************************
  959.          void nameoutfile(char *string) - function
  960.  
  961.          Usage: nameoutfile(string)
  962.  
  963.          Description:
  964.              This procedure automatically closes the present outfile if
  965.          it  is  open  then renames it to string. From this time until
  966.          another call to nameoutfile(), the  external  file  associated
  967.          with "outfile" will carry the name you have given it.
  968.  
  969.          Considerations:
  970.             If string is a literal, not a  string  variable,  then  it
  971.          must be enclosed in quotation marks. String must be DOS-legal
  972.          with  up  to  8  alphanumeric characters, an optional period,
  973.          then  up  to  a  three  character  extension.    Full   drive
  974.          designator and pathnames are supported up to 76 characters.
  975.  
  976.          See Also:
  977.          filewrite(),   filewriteln(),    fileread(),    filereadln(),
  978.          nameinfile().
  979.  
  980.          Example:
  981.          include <magic.h>
  982.          include <stdio.h>
  983.          void main() {
  984.             magic_setup();
  985.             nameoutfile("TestFile.Txt");
  986.             filewriteln("This is a test");
  987.          }
  988.  
  989.          Performance of example:
  990.              "Testfile.txt"   is   assigned    to    outfile.     When
  991.          filewriteln()  is  called,  it looks to the disk for the file
  992.          called "Testfile.txt" or creates a  "Testfile.txt"  and  adds
  993.          one line.
  994.  
  995.          *************************************************************
  996.          file* outfile - Global Variable
  997.  
  998.          Usage: /* example */ fopen(outfile,"Things.Doc","wt")
  999.  
  1000.          Description:
  1001.             Outfile is declared globally as a file pointer. It is most
  1002.          often  used  for exporting information from your program with
  1003.          the automatic procedures filewrite() and filewriteln().   The
  1004.          default string assigned to outfile as the name under which it
  1005.          is  read  from disk is "OUTPUT", but this can be changed with
  1006.          nameoutfile().
  1007.  
  1008.          Considerations:
  1009.          You can override the automatic use of outfile in  Magic  with
  1010.          standard Borland/Turbo C techniques such as fopen() fclose(),
  1011.          fprintf() and fscanf(). Outfile is opened as a  binary  file.
  1012.          String  conversions  are  made  automatically  by  the  Magic
  1013.          functions.
  1014.  
  1015.          See Also:
  1016.          filewrite(), filewriteln(), nameinfile(), outfile()  {Magic};
  1017.          Also all file handling functions {Borland manuals}
  1018.  
  1019.          Example:
  1020.          #include <magic.h>
  1021.          void main() {
  1022.             magic_setup();
  1023.             nameoutfile("TESTFILE.TXT");
  1024.             filewriteln("test");
  1025.             fclose(outfile);
  1026.             nameoutfile("TESTFILE.2");
  1027.             filewriteln("test-2");
  1028.          }
  1029.  
  1030.          Performance of example:
  1031.               Nameoutfile()  is  used  to  cause  outfile to be called
  1032.          "TESTFILE.TXT" when referenced on disk.  A line  of  text  is
  1033.          written  to  it,  then outfile is closed.  Outfile is renamed
  1034.          "TESTFILE.2" and another line of text is written to  outfile,
  1035.          but outfile is actually a different file on the disk.
  1036.  
  1037.          *************************************************************
  1038.          char outfilename[50]
  1039.  
  1040.          Usage: /* example */ strcpy(outfilename,"testfile.1")
  1041.  
  1042.          Description:
  1043.              Outfilename is an array of 50 characters used to  hold  a
  1044.          string  for identifying OUTFILE (see above).  Standard string
  1045.          character  array  procedures  may  be  used   to   manipulate
  1046.          outfilename.  This is the string getoutfile(), nameoutfile(),
  1047.          filewrite() and filewriteln() use to identify outfile.
  1048.  
  1049.          Considerations:
  1050.              The   default  for  outfilename  is  "OUTPUT."  Normally,
  1051.          nameoutfile() is used to change outfilename.
  1052.  
  1053.          Example:
  1054.              #include <magic.h>
  1055.              #include <string.h>
  1056.              void main() {
  1057.                 .
  1058.                 .
  1059.                 if (strlen(outfilename)) < 4)
  1060.                    printf("We have a very short file name");
  1061.                 .
  1062.                 .
  1063.               }
  1064.  
  1065.          Performance of example:
  1066.              If outfilename is less than 4 characters  long  then  the
  1067.          program prints, "We have a very short file name."
  1068.  
  1069.          *************************************************************
  1070.          void pile(unsigned char string[81]) - function
  1071.  
  1072.          Usage: pile(string)
  1073.  
  1074.          Description:
  1075.              Pile()  uses  the  global  char array, "sent[81][46]" and
  1076.          the  global  int  variable howmany.  "Howmany" keeps track of
  1077.          howmany strings of text  from  the  sent[]  array  have  been
  1078.          assigned text.  The next available sent[] is assigned string,
  1079.          and howmany is incremented by one.
  1080.  
  1081.          Consideration:
  1082.              If  starting  a  new  'pile of sent[]s' call clearsents()
  1083.          first, to be sure that all the sent[]s contain no text. Usage
  1084.          of  pile()  must  be  consistent.  In other words, if you use
  1085.          strcat() for sent[1] and sent[2], then use pile(), you may be
  1086.          surprised to find pile will still affect sent[1].  To remedy,
  1087.          you can always call figurehowmany() before using pile().
  1088.              There  is  a  limit  to  the maximum size of pop-up boxes
  1089.          using sent[]s.  For instance, in VGA-HI  graphics  mode,  the
  1090.          limit  is  about 20 lines of text with the longest line being
  1091.          about 40 characters long.
  1092.  
  1093.          See Also:
  1094.              pop(),   getanykey(),    getyn(),    dialog(),    menu(),
  1095.          clearsents(), figurehowmany(), howmany
  1096.  
  1097.          Example:
  1098.          #include<magic.h>
  1099.          void main() {
  1100.             magic_setup();
  1101.             pile("This is the first line of a test");
  1102.             pile("This is the second line.");
  1103.             getanykey(-1,-1);
  1104.          }
  1105.  
  1106.          Performance of example:
  1107.             Two  strings  of  text  are  assigned to the array sent[].
  1108.          Then getanykey() displays those two strings.
  1109.  
  1110.          *************************************************************
  1111.          void pink(void) - function
  1112.  
  1113.          Usage: pink()
  1114.  
  1115.          Description:
  1116.             Pink()  makes  a sound typically indicating a key has been
  1117.          pressed or a small action has occurred.
  1118.  
  1119.          Considerations:
  1120.             The  global  variable  musicon  must  be greater than 0 or
  1121.          pink() will not make a sound.
  1122.  
  1123.          See Also:
  1124.          musicon,  twinkle(),  soundup(), sounddown(), sorry() {Magic}
  1125.          sound(), nosound(), delay() {Borland}
  1126.  
  1127.          Example:
  1128.          include <magic.h>
  1129.          include <stdio.h>
  1130.          void main() {
  1131.             magic_setup();
  1132.             do {
  1133.                musicon = 1;
  1134.                u = getch();
  1135.                pink();
  1136.                printf("%c",u);
  1137.             }
  1138.             while ((u != 13) && (u != 27));
  1139.          }
  1140.  
  1141.          Performance of example:
  1142.              Every time a key is pressed, it's character will be shown
  1143.          on  the  screen  and an audible click will be heard until the
  1144.          user presses [Enter] or [Esc].
  1145.  
  1146.          *************************************************************
  1147.          void pointeroff(void) - function
  1148.  
  1149.          Usage: pointeroff()
  1150.  
  1151.          Description:
  1152.             Turns off the mouse pointer or arrow.
  1153.  
  1154.          Considerations:
  1155.              Will work with or without mouse installed. Graphics modes
  1156.          only.
  1157.  
  1158.          See Also:
  1159.          poll(), pointeron(), resetmouse(), pointertoxy()
  1160.  
  1161.          Example:
  1162.          #include <magic.h>
  1163.          void main() {
  1164.             magic_setup();
  1165.             bestvideo();
  1166.             pointeroff();
  1167.             waste();
  1168.             do {
  1169.                poll();
  1170.                lineto(px,py);
  1171.             }
  1172.             while (!left);
  1173.             waste();
  1174.             pointeron();
  1175.             do poll(); while (!left);
  1176.             cleanup();
  1177.          }
  1178.  
  1179.          Performance of example:
  1180.             The  program will switch to a graphics mode and there will
  1181.          be no mouse pointer.  As long as the user moves the mouse,  a
  1182.          trail  of  lines  will  appear  on  the screen. When the user
  1183.          clicks the left mouse button, the mouse pointer will reappear
  1184.          and the drawing of lines will cease. When  the  user  presses
  1185.          any key or mouse button the program will terminate gracefully.
  1186.  
  1187.          *************************************************************
  1188.          void pointeron(void) - function
  1189.  
  1190.          Usage: pointeron()
  1191.  
  1192.          Description:
  1193.             Turns on the mouse pointer or arrow.
  1194.  
  1195.          Considerations:
  1196.              Will work with or without mouse installed. Graphics modes
  1197.          only.
  1198.  
  1199.          See Also:
  1200.          poll(), pointeroff(), resetmouse(), pointertoxy()
  1201.  
  1202.          Example:
  1203.          #include <magic.h>
  1204.          #include <graphics.h>
  1205.          void main() {
  1206.             magic_setup();
  1207.             bestvideo();
  1208.             pointeroff();
  1209.             waste();
  1210.             do {
  1211.                poll();
  1212.                lineto(px,py);
  1213.             }
  1214.             while (!left);
  1215.             waste();
  1216.             pointeron();
  1217.             do poll(); while (!left);
  1218.             cleanup();
  1219.          }
  1220.  
  1221.          Performance of example:
  1222.             The  program will switch to a graphics mode and there will
  1223.          be no mouse pointer.  As long as the user moves the mouse,  a
  1224.          trail  of  lines  will  appear  on  the screen. When the user
  1225.          clicks the left mouse button, the mouse pointer will reappear
  1226.          and the drawing of lines will cease. When  the  user  presses
  1227.          any key or mouse button the program will terminate gracefully.
  1228.  
  1229.          *************************************************************
  1230.          char pointerstatus - Global Variable
  1231.  
  1232.          Usage : /* example */
  1233.              if (!pointerstatus) outtextxy(x,y,"No arrow")
  1234.  
  1235.          Description:
  1236.              Pointerstatus is a global char variable used by Magic  to
  1237.          keep  track  of  whether  a  mouse  (or arrow key) pointer is
  1238.          visible on screen.  In most cases, changing this variable  is
  1239.          dangerous,  but  testing it is ok. When a pointer is visible,
  1240.          pointerstatus = 1, otherwise it is 0.
  1241.  
  1242.          Considerations:
  1243.             Used in graphics modes only.
  1244.  
  1245.          See Also:
  1246.          pointeron(), pointeroff(), resetmouse()
  1247.  
  1248.          *************************************************************
  1249.          void pointertoxy(void) - function
  1250.  
  1251.          Usage: pointertoxy()
  1252.  
  1253.          Description:
  1254.             Moves the mouse pointer to coordinates designated  by  the
  1255.          global int variables px and py.
  1256.  
  1257.          Considerations:
  1258.             Whether or not the pointer is visible, the  (graphics)  CP
  1259.          (Current Position) will still be moved to px, py.
  1260.  
  1261.          See Also:
  1262.          poll(), pointeroff(), pointeron(), resetmouse().
  1263.  
  1264.          Example:
  1265.          #include <magic.h>
  1266.          void main () {
  1267.             magic_setup();
  1268.             bestvideo();
  1269.             px := getmaxx() / 2; py := getmaxy() / 2;
  1270.             pointeron();
  1271.             pointertoxy();
  1272.             waitforuser();
  1273.             cleanup();
  1274.          }
  1275.  
  1276.          Performance of example:
  1277.             The  current  position  is  moved to px and py, which have
  1278.          been assigned the center of  the  screen.  The  pointer  will
  1279.          appear there.  The program waits for the user to press a key,
  1280.          then terminates gracefully.
  1281.  
  1282.          *************************************************************
  1283.          void poll(void) - function
  1284.  
  1285.          usage: poll()
  1286.  
  1287.          Description:
  1288.              Poll()  is a very versatile function check for user input
  1289.          whether from an optional mouse, or  from  keyboard.   If  any
  1290.          change has occurred, the global unsigned char variable "u" is
  1291.          updated.
  1292.              At the start of poll(), the global unsigned char variable
  1293.          "u"  is  set to #126, an uncommon character.  the global char
  1294.          variables, "left", "center" and "right" are set to 0.
  1295.              If  the left mouse button is clicked, left become 1 and u
  1296.          becomes 13 (emulating the [Enter] key).  If the right  button
  1297.          is  clicked, right becomes 1 and u becomes 27, (emulating the
  1298.          [Esc] key.  If the mouse has a center button, and  if  it  is
  1299.          clicked,  center  becomes 1.  With a two-button mouse, center
  1300.          is always 0.
  1301.              If the [Enter] key is pressed, left becomes  1.   If  the
  1302.          [Esc] key is pressed, right becomes 1.
  1303.              Additionally,  mouse  movement  updates  the  global  int
  1304.          variables px and py which are used  to  represent  horizontal
  1305.          and  vertical  position on the screen.  If a mouse pointer is
  1306.          visible (pointeron()), then the mouse pointer is moved to the
  1307.          new px,py position.
  1308.              Through poll(), the keyboard can also update px,  py  and
  1309.          the  'mouse'  pointer.   Use of the arrow keys, [Home], [Page
  1310.          Up], [End] and [Page Down] cause a change of one pixel  in  a
  1311.          straight  or  diagonal  direction.  If  [Num Lock] is on, the
  1312.          number keys cause a corresponding but larger change of px and
  1313.          py, straight or diagonal of from 8 to 12 pixels.
  1314.  
  1315.          Considerations:
  1316.              Poll() automatically calls pointertoxy()  to  update  the
  1317.          current px,py position.  Poll() can display an  arrow  (mouse
  1318.          pointer) whether or not a mouse is installed.
  1319.  
  1320.          See Also:
  1321.          pointetoxy(),    pointeron(),   pointeroff(),   resetmouse(),
  1322.          xreadkey()
  1323.  
  1324.          Example:
  1325.          #include <magic.h>
  1326.          void main() {
  1327.             magic_setup();
  1328.             pointeron();
  1329.             do {
  1330.                poll();
  1331.             while (!left);
  1332.          }
  1333.  
  1334.          Performance of example:
  1335.          The mouse pointer (text mode) moves  around  until  the  user
  1336.          clicks the left mouse button or presses the [Enter] key.
  1337.  
  1338.          *************************************************************
  1339.          void pop(int x, int y) - function
  1340.  
  1341.          Usage: pop(x,y)
  1342.  
  1343.          Description:
  1344.             This  is  the simplest version of a pop-up text box in the
  1345.          Magic kit.  Magic has a pre-declared  array  of  80-character
  1346.          long strings called sent[].  Before a call to pop(), you must
  1347.          assign  text  to as many strings as you wish to display. They
  1348.          must be in order. The first line displayed will  be  sent[1],
  1349.          the  second  line  will be sent[2], and so on. If the rest of
  1350.          the string array is empty, any strings after the last one  to
  1351.          which  you  have  assigned  a line of text will be ignored by
  1352.          pop().
  1353.             Pop() requires two integers, x and y. X is the  horizontal
  1354.          coordinate   and   y   is  the  vertical  coordinate.   These
  1355.          coordinates mark the position on the screen where  the  upper
  1356.          left corner of the pop up box will occur.  The whole box is 4
  1357.          columns wider than the widest sent[] and two rows taller than
  1358.          the total number of sent[]s which contain text. If you are in
  1359.          text  mode the upper left corner of the screen is 1,1 and the
  1360.          lower right corner is 80,25. In any of  the  graphics  modes,
  1361.          the upper left corner is 0,0 and the lowest right varies.  in
  1362.          CGA,  2-color mode (640 x 200), for instance, the lower right
  1363.          corner is 639,199.
  1364.             In  graphics or text mode, if either x or y are a negative
  1365.          integer, the  box  will  be  automatically  centered  on  the
  1366.          screen in the corresponding dimension.
  1367.             When  pop() starts, it first saves the current contents of
  1368.          the screen to memory. pop() will then place its pop-up box on
  1369.          the screen. There is no wait for user input built in.   After
  1370.          a call to pop(), the program will progress immediately to the
  1371.          next  step. Therefore, a usual step is to call waitforuser(),
  1372.          or some other program step, so the pop-up box  will  be  seen
  1373.          before  the program continues. Then call restore() to get rid
  1374.          of the pop-up box and replace the original  screen  contents.
  1375.          To  clear  out  the  array  of  strings  (sent[81][46]), call
  1376.          clearsents().
  1377.              Actual  use  of  pop()  may   be   rare,   since   pop(),
  1378.          waitforuser(),  clearsents() and  restore() are automatically
  1379.          incorporated in getanykey(), getyn(), dialog(), and menu().
  1380.  
  1381.          Considerations:
  1382.             Must  not use x or x integers that are beyond the possible
  1383.          range for the current video mode. (except negative  integers,
  1384.          which  will  center  the  pop-up box) It is advisable to call
  1385.          restore() some time soon after done with pop(). Otherwise  4k
  1386.          of RAM is occupied with the saved screen in text mode, and up
  1387.          to  around 300k in some graphics modes. There can be up to 10
  1388.          text screens saved at one time when there is  sufficient  RAM
  1389.          space.  If  an  attempt  is  made  to  save more screens than
  1390.          possible,  such  as calling pop() 11 times in a row, only the
  1391.          first screen(s) saved will be available for a  restore().  If
  1392.          your program exceeds available RAM space, the IDE will return
  1393.          an out of memory notice.
  1394.              In text mode, you  cannot  use  strings  longer  than  75
  1395.          characters  and  no more than 21 strings.  In graphics modes,
  1396.          the maximum size of the sent[] array (string array) varies.
  1397.              In  graphics  modes,  there  is  only  one layer of saved
  1398.          screens available.
  1399.              Text mode, does not support background colors above 7.
  1400.              There is a limit to the maximum size of a pop() box.  For
  1401.          instance, in VGA-HI graphics mode,  the  limit  is  about  20
  1402.          lines of text with the longest line being about 40 characters
  1403.          long.
  1404.  
  1405.          See Also:
  1406.          restore(), getanykey(), getyn(),  dialog(),  menu(),  sent[],
  1407.          clearsents(), pile() centerjustify
  1408.  
  1409.          Example:
  1410.          #include <magic.h>
  1411.          #include <string.h>
  1412.          void main() {
  1413.             magic_setup();
  1414.             strcpy(sent[1],"This is a line of text");
  1415.             strcpy(sent[2],"This is another line");
  1416.             strcpy(sent[3],"Press any key...");
  1417.             pop(1,1);
  1418.             waitforuser();
  1419.             restore();
  1420.             waitforuser();
  1421.          }
  1422.  
  1423.          Performance of example:
  1424.             Since there are 3 sent[]s a text box will pop up  that  is
  1425.          three lines tall. The first line is the widest, and therefore
  1426.          the  box  will  be  just  large  enough to neatly contain the
  1427.          first, widest line. Pop is given the coordinates of  1,1,  so
  1428.          the  upper  left  corner  of  the  pop  up box will be in the
  1429.          extreme upper left corner of the screen.  Waitforuser()  will
  1430.          stall  the program until the user presses any key or clicks a
  1431.          mouse button. Restore() restores the screen as it was  before
  1432.          the  pop-up  box  appeared,  which  is silly in this program,
  1433.          because it ends after another waitforuser().
  1434.  
  1435.          *************************************************************
  1436.          void popg(int x, int y) - function
  1437.  
  1438.          Usage:  This is for internal use by the Magic Library. Direct
  1439.          use of this function is not recommended.
  1440.  
  1441.          Description: Called by pop() to pop  up  a  box  in  graphics
  1442.          modes.
  1443.  
  1444.          *************************************************************
  1445.          int problem - Global Variable
  1446.  
  1447.          Usage: /* example */ if (problem) exit(0)
  1448.  
  1449.          Description:
  1450.             Problem  is a global int variable that is usually set to 0
  1451.          as any graphics or i/o procedure in the  Magic  unit  starts.
  1452.          Then,  if  a  problem  occurs,  the procedure will handle the
  1453.          problem as cleanly as possible and set Problem  to  a  number
  1454.          greater than 0, (usually 1).
  1455.             For instance, if filewrite() is asked to write a string to
  1456.          a  write-protected disk, the program will not crash, but will
  1457.          not write to the disk, and problem becomes 1.  You  can  then
  1458.          test  problem  in  your  program  and  branch  to  handle the
  1459.          'problem.'
  1460.  
  1461.          Considerations:
  1462.              Problem  must  be  checked  before  a  call  to any other
  1463.          procedure in the Magic library because the next function  may
  1464.          reset problem for it's own use.
  1465.  
  1466.          Example:
  1467.          #include <magic.h>
  1468.          void main() {
  1469.            magic_setup();
  1470.            nameoutfile("testfile.txt");
  1471.            filewriteln("This is a line of nonsense.");
  1472.            if (problem) {
  1473.               pile("Problem writing to disk");
  1474.               pile("Disk may be full or write-protected");
  1475.               pile("Press any key to continue..");
  1476.               getanykey(-1,-1);
  1477.            }
  1478.          }
  1479.  
  1480.          Performance of example:
  1481.             This  program tries to write, "This is a line of nonsense"
  1482.          to  a  disk  file  called  "Testfile.txt."  If  this   proves
  1483.          impossible, then problem is 1 and a three-line notice pops up
  1484.          on the screen.
  1485.  
  1486.          *************************************************************
  1487.          int px - Global Variable
  1488.  
  1489.          Usage: /* example */ putpixel(px,py,WHITE)
  1490.  
  1491.          Description:
  1492.             Px  is  a global int variable defined in MAGIC.H. The most
  1493.          common  use  of  px  is  to  designate  a  horizontal  screen
  1494.          position.   Px  is  automatically  used  by pointertoxy() and
  1495.          modified by poll().
  1496.  
  1497.          *************************************************************
  1498.          int py - Global Variable
  1499.  
  1500.          Usage: /* example */ putpixel(px,py,WHITE)
  1501.  
  1502.          Description:
  1503.             Py is a global int variable defined in MAGIC.H.  The  most
  1504.          common  use of py is to designate a vertical screen position.
  1505.          Py is automatically used by  pointertoxy()  and  modified  by
  1506.          poll().
  1507.  
  1508.          *************************************************************
  1509.          void replacemouse(void) - function
  1510.  
  1511.          Usage:   This  is  used internally by the Magic Unit.  Direct
  1512.          use of this function is not recommended.
  1513.  
  1514.          Description:   This  function  replaces  the  mouse   pointer
  1515.          (arrow)  with  what  it had covered when it is moved to a new
  1516.          location or pointeroff() is called.
  1517.  
  1518.          *************************************************************
  1519.  
  1520.                            Continued in file MAGIC.3
  1521.  
  1522.          (This file is split  into  three  parts  because  some  older
  1523.          versions of Turbo C cannot display files larger than 64k.)
  1524.