home *** CD-ROM | disk | FTP | other *** search
/ World of Shareware - Software Farm 2 / wosw_2.zip / wosw_2 / CPROG / CMAGIC.ZIP / MAGIC.TXT < prev    next >
Text File  |  1992-09-06  |  53KB  |  1,366 lines
  1.  
  2.                                     C MAGIC
  3.                                   Version 1.5
  4.  
  5.                                Reference Manual
  6.  
  7.  
  8.                      An Add-in For Borland C/C++ Products
  9.  
  10.                  Copyright 1992, Jeff Napier & Another Company
  11.  
  12.  
  13.          What C Magic will do for you:
  14.  
  15.          *  Create  professional  multi-color,  shadowed  pop-up help,
  16.          warnings, dialog,  general  text  boxes  and  lightbar  menus
  17.          instantly without wasting your time 're-inventing the wheel'.
  18.  
  19.          *  Incorporate  .BGI graphics drivers and .CHR fonts directly
  20.          into your .EXE programs with only a few lines of code.
  21.  
  22.          * Write graphics-based programs as easily as text-based.
  23.  
  24.          *  Everything  you need to write programs to run on 256-color
  25.          VGA.
  26.  
  27.          * Gain mouse support without  writing  a  mouse  driver.   In
  28.          graphics  modes, whether or not end user has a mouse, pointer
  29.          is generated and can also be moved with arrow/number keys.
  30.  
  31.          * Gain color control without writing color control code.
  32.  
  33.          * Many Borland/Turbo C functions greatly simplified.
  34.  
  35.          * Disk file handling is done automatically.
  36.  
  37.          * Enlarged cursor available for your programs  for  use  with
  38.            laptop LCD displays.
  39.  
  40.          * Add sound effects to your program effortlessly.
  41.  
  42.  
  43.          Notice:  This  is shareware. Feel free to copy and distribute
  44.          the shareware version without modification.  If you  use  any
  45.          portion  of  the  C  Magic  library  in  your  programs  then
  46.          registration is a legal necessity.  Send  $39.95  to  Another
  47.          Company.  Complete, well-documented easy-to-understand source
  48.          code  is  available.  For  registration  +  source code, send
  49.          $79.90.
  50.  
  51.          Send US funds drawn on a US bank to:
  52.  
  53.                                 Another Company
  54.                                  P.O. Box 298
  55.                               Applegate, OR 97530
  56.                                       USA
  57.                                  503-846-7884
  58.  
  59.          Include  $3  postage  (USA);  $5  - Canada; or $7 - all other
  60.          countries.
  61.  
  62.          If you require 3.5" disk size, please add $1.00.
  63.  
  64.          Even though this seems quite bug-free to me,  it  is  version
  65.          1.5  and  you may find a surprise or two. I make no warranty.
  66.          Please feel free to submit bug reports, and I will attempt to
  67.          incorporate appropriate fixes.
  68.  
  69.          (If  you  are  new  to C, or if you would like a step-by-step
  70.          guide, you  are  looking  at  the  wrong  file.   Please  see
  71.          TUTOR.DOC first.)
  72.  
  73.          Note: MAGIC.LIB should be in your \LIB subdirectory.  MAGIC.H
  74.          should be in your \INCLUDE subdirectory.  MAGIC.LIB  must  be
  75.          included in your project list.
  76.  
  77.          For  newer  Borland  compilers press [Alt] + [p], then [o] to
  78.          open a project.  Then [i] to include  the  main  source  file
  79.          name, and then MAGIC.LIB.
  80.  
  81.          For  older  Borland  compilers,  press  [F3] to create a .PRJ
  82.          file.  Call it anything you like up to 8 letters,  with  .PRJ
  83.          extension.  On the first line of the .PRJ file, type the name
  84.          of  your  source  code  file(s).   On  the  second line, type
  85.          MAGIC.LIB, and on the third line type GRAPHICS.LIB.
  86.  
  87.                                IMPORTANT NOTES:
  88.  
  89.          GRAPHICS.LIB (supplied by Borland) must  also  be  available.
  90.          Include  in project list, or press [Alt] + [O] then [L], then
  91.          [L].  Check the GRAPHICS.LIB check box.
  92.  
  93.          You MUST use LARGE memory model.   The  Magic  library  wont'
  94.          work with smaller memory models.
  95.  
  96.  
  97.          *************************************************************
  98.  
  99.                        ALPHABETICALLY ORDERED REFERENCE
  100.                 TO ALL THE FEATURES AVAILABLE IN MAGIC LIBRARY
  101.  
  102.          NOTE: All functions and global variables work identically  in
  103.          text  and  all  graphics modes unless otherwise stated except
  104.          for one difference: In text mode, up to 10 pop-up  boxes  may
  105.          be  on  screen  at once, and the image underneath is restored
  106.          when the boxes disappear.   Graphics  modes  allow  only  one
  107.          layer.
  108.  
  109.          NOTE:   Text mode  operation  is  designed  specifically  for
  110.          standard  80 x 25 text display.  Results may be unpredictable
  111.          if used in other text resolutions.
  112.  
  113.          NOTE:  The functions in this library  are  designed  for  use
  114.          with  standard  IBM-compatible equipment and are not portable
  115.          to other systems.
  116.  
  117.          *************************************************************
  118.          char[81] answer - Global Variable
  119.  
  120.          Usage: /* example */ strcpy(answer,"test")
  121.  
  122.          Description:
  123.             Answer  is  a  string  which  is  returned by the function
  124.          dialog(). You can also use answer as a general purpose global
  125.          string variable. Answer is null  terminated  (ASCII  #0)  and
  126.          therefore one character longer than nominal string length.
  127.  
  128.          Considerations:
  129.             Maximum size of answer is 80 characters.
  130.  
  131.          See also: dialog()
  132.  
  133.          Example:
  134.  
  135.          #include <magic.h>
  136.          #include <string.h>
  137.          void main(){
  138.             magic_setup();
  139.             strcpy(sent[1],"Write your answer here");
  140.             dialog(1,1);
  141.             if (answer[0] = 'I') User_Started_With_I();
  142.             .
  143.             .
  144.          }
  145.  
  146.          Performance of example:
  147.          A dialog box pops up and the user types an answer. The string
  148.          typed  by the user is contained in the string, answer. A test
  149.          is made to see if the first two characters of answer are 'I '
  150.          and if so, an imaginary  function,  User_Started_With_I()  is
  151.          called.
  152.  
  153.          *************************************************************
  154.          int b1,b2,b3,b4 - Global Variable
  155.  
  156.          Usage: Internal use by Magic.lib, not  recommend  for  direct
  157.          manipulation.
  158.  
  159.          Description:
  160.          These  four  integers  are used by Magic.lib to keep track of
  161.          the corners of pop-up text boxes in both  graphics  and  text
  162.          modes.
  163.          *************************************************************
  164.          char barback - Global Variable
  165.  
  166.          Usage: BarBack = color
  167.  
  168.          Description:
  169.          This  sets  the  background color for lightbar backgrounds in
  170.          menus, where 'color' is an integer from 0 to 7, in text  mode
  171.          or  0 to 15 in graphics modes, or a color constant as defined
  172.          by Borland in CONIO.H or GRAPHICS.H. The colors  0  -  7  are
  173.          the same in both text and graphics modes.
  174.  
  175.          Considerations:
  176.          May  not  have the expected effect when used with the limited
  177.          palettes of 4-color CGA (mode  0,1  or  2),  2-color  CGA  or
  178.          Hercules.
  179.  
  180.          See also: bartext, boxback, boxtext
  181.  
  182.          Example:
  183.          #include <magic.h>
  184.          #include <string.h>
  185.          #include <conio.h>
  186.          void main(){
  187.             magic_setup();
  188.             strcpy(sent[1],"First Thing");
  189.             strcpy(sent[2],"Second Thing");
  190.             strcpy(sent[3],"Quit");
  191.             mc := 1;
  192.             barback = RED;
  193.             menu(-1,-1);
  194.             .
  195.             .
  196.          }
  197.  
  198.          Performance of example:
  199.          Three  strings  are  declared.   The  menu  bar will start by
  200.          highlighting sent[1] when the menu is displayed.  Because  of
  201.          the change to barback, the background of the highlighted menu
  202.          item will be in red.
  203.  
  204.          *************************************************************
  205.          char bartext - Global Variable
  206.  
  207.          Usage: BarText := color
  208.  
  209.          Description:
  210.          This sets the color for lightbar text in menus, where 'color'
  211.          is  an integer from 0 to 15 or a color constant as defined in
  212.          CONIO.H or GRAPHICS.H. Colors are the same  in  graphics  and
  213.          text modes.
  214.  
  215.          Considerations:
  216.          May  not  have the expected effect when used with the limited
  217.          palettes of 4-color CGA (mode  0,1  or  2),  2-color  CGA  or
  218.          Hercules.
  219.  
  220.          See also: barback, boxback, boxtext
  221.  
  222.          Example:
  223.          #include <magic.h>
  224.          #include <string.h>
  225.          #include <conio.h>
  226.          void main(){
  227.             magic_setup();
  228.             strcpy(sent[1],"First Thing");
  229.             strcpy(sent[2],"Second Thing");
  230.             strcpy(sent[3],"Quit");
  231.             mc := 1;
  232.             bartext = RED;
  233.             menu(-1,-1);
  234.             .
  235.             .
  236.          }
  237.  
  238.          Performance of example:
  239.          Three  strings  are  declared.   The  menu  bar will start by
  240.          highlighting sent[1] when the menu is displayed.  Because  of
  241.          the  preceding  change  to bartext, the highlighted menu text
  242.          will be displayed in red.
  243.  
  244.          *************************************************************
  245.          void bestvideo(void) - function
  246.  
  247.          Usage:  bestvideo()
  248.  
  249.          Description:
  250.              By  simply  calling  bestvideo(), the program detects the
  251.          graphics card present and switches to the best graphics  mode
  252.          possible for that card.
  253.  
  254.          Considerations:
  255.          Before calling bestvideo(), you must call magic_setup() which
  256.          gets  the  magic  library  ready  to work in a graphics mode.
  257.          Bestvideo() incorporates only the video driver used for  your
  258.          computer.   If you write a program using bestvideo() on a VGA
  259.          system, it will not run on a CGA system, for instance.
  260.  
  261.          See also:
  262.          cgalovideo(),    cgahivideo(),   egahivideo(),   egalovideo()
  263.          hercvideo(),  vgalovideo(),  vgahivideo()  and   textvideo(),
  264.          cleanup().
  265.  
  266.          Example:
  267.          #include <magic.h>
  268.          #include <graphics.h>
  269.          void main() {
  270.             magic_setup();
  271.             bestvideo();
  272.             line(0,0,getmaxx,getmaxy);
  273.             waitforuser();
  274.             cleanup();
  275.          }
  276.  
  277.          Performance of example:
  278.          Initializes best graphics mode, draws a  diagonal  line  from
  279.          the  upper  left  corner  to  the  lower  right corner of the
  280.          screen,  waits  until  a  key  is  pressed,  then  terminates
  281.          gracefully.
  282.  
  283.          *************************************************************
  284.          void bigcursor(void) - function
  285.  
  286.          Usage: bigcursor()
  287.  
  288.          Description:
  289.          After  a call to bigcursor(), the cursor in text mode will be
  290.          a  block  the  size  of  a  whole  character  instead  of  an
  291.          underline.  This  is particularly useful in programs designed
  292.          for LCD laptop screens.  Unless a specific call  is  made  to
  293.          littlecursor()  before the end of the program, the big cursor
  294.          will remain in effect at the DOS prompt and within most other
  295.          programs.
  296.  
  297.          Considerations:
  298.             Has  no  effect  in  graphics  modes, but will resume as a
  299.          large cursor when returned to text mode.
  300.  
  301.          See Also:
  302.          littlecursor(), hidecursor()
  303.  
  304.          Example:
  305.          #include <magic.h>
  306.          magic_setup();
  307.          void main(){
  308.             bigcursor();
  309.             printf("Big cursor at the end of this line!");
  310.          }
  311.  
  312.          Performance of Example:
  313.          This program will write 'Big cursor at the end of this line',
  314.          then quit. If run from the IDE, nothing will seem to  happen,
  315.          but if compiled and run from DOS, after execution, the cursor
  316.          will become large and stay that way.
  317.  
  318.          *************************************************************
  319.          void bitmap(void) - function
  320.  
  321.          Usage: bitmap()
  322.  
  323.          Description:
  324.          This  function  causes  outtext() and outtextxy() to generate
  325.          text in the DEFAULT_font (Bitmapped 8  x  8  font).    It  is
  326.          nearly the same as settextstyle(0,0,1);
  327.  
  328.          Considerations:
  329.              Use   of  bitmap()  does  not  appreciably  increase  RAM
  330.          requirement or enlarge program size.
  331.  
  332.          See Also:
  333.              triplex(),  little(),  gothic(),  sansserif(),  script(),
  334.          italic(), complex(), simple(), bold(), european()
  335.  
  336.          Example:
  337.          #include <magic.h>
  338.          #include <graphics.h>
  339.          void main(){
  340.             magic_setup();
  341.             bestvideo();
  342.             triplex();
  343.             outtextxy(0,0,"Triplex font");
  344.             bitmap();
  345.             outtextxy(0,50,"Bitmap font");
  346.             waitforuser();
  347.             cleanup();
  348.          }
  349.  
  350.          Performance of example:
  351.          Program writes "Triplex font" on  screen  using  the  Triplex
  352.          font.  Below  that, it writes "Bitmap font" using the default
  353.          font - Bitmap.
  354.  
  355.          *************************************************************
  356.          void bold(void) - function
  357.  
  358.          Usage: bold()
  359.  
  360.          Description:
  361.          This function causes outtext() and  outtextxy()  to  generate
  362.          text in the "bold" stroked font.
  363.  
  364.          Considerations:
  365.              BOLD.CHR  is linked into .EXE file and RAM usage and disk
  366.          space  requirements  increase.   This font will not work with
  367.          older versions of Turbo C.
  368.  
  369.          See Also:
  370.              triplex(),  little(),  gothic(),  sansserif(),  script(),
  371.          italic(), complex(), simple(), bitmap(), european()
  372.  
  373.          Example:
  374.          #include <magic.h>
  375.          #include <graphics.h>
  376.          void main(){
  377.             magic_setup();
  378.             bestvideo();
  379.             bold();
  380.             outtextxy(0,0,"Bold font");
  381.             waitforuser();
  382.             cleanup();
  383.          }
  384.  
  385.          Performance of example:
  386.          Program writes "Bold font" on screen using the "bold" font.
  387.  
  388.          *************************************************************
  389.          char border - Global Variable
  390.  
  391.          Usage: border = color
  392.  
  393.          Description:
  394.          Color is represented with an  integer  from  0  to  15  or  a
  395.          pre-defined   color  constant  from  CONIO.H  or  GRAPHICS.H.
  396.          Changing the value of border will affect the color of borders
  397.          drawn around pop-up  text  boxes,  dialog  boxes  and  menus.
  398.          Colors are the same in text and graphics mode.
  399.  
  400.          Considerations:
  401.          May  not  have the expected effect when used with the limited
  402.          palettes of 4-color CGA (mode  0,1  or  2),  2-color  CGA  or
  403.          Hercules.
  404.  
  405.          See Also:
  406.          shadow,  mainback,  maintext,  boxback,   boxtext,   barback,
  407.          bartext.
  408.  
  409.          Example:
  410.          #include <magic.h>
  411.          void main() {
  412.             magic_setup();
  413.             border = 15; /* WHITE */
  414.             pile("Do you like this border color?");
  415.             getanykey(-1,-1);
  416.          }
  417.  
  418.          Performance of example:
  419.          The  border  color  is set to white. A box will appear on the
  420.          screen asking a silly question. The box  will  have  a  white
  421.          border. When a key is pressed, the program quits.
  422.  
  423.          *************************************************************
  424.          char boxback - Global Variable
  425.  
  426.          Usage: boxback = color;
  427.  
  428.          Description:
  429.          Color is represented with an  integer  from  0  to  15  or  a
  430.          pre-defined   color   constant   enumerated   in  CONIO.H  or
  431.          GRAPHICS.H. Changing the value of  boxback  will  affect  the
  432.          background  color  of  pop-up boxes, text boxes, dialog boxes
  433.          and menus.
  434.  
  435.          Considerations:
  436.             Do not use background colors above 7 in text mode. May not
  437.          have the expected effect when used with the limited  palettes
  438.          of 4-color CGA (mode 0,1 or 2), 2-color CGA or Hercules.
  439.  
  440.          See Also:
  441.          mainback, maintext, boxtext, barback, bartext.
  442.  
  443.          Example:
  444.          #include <magic.h>
  445.          #include <conio.h>
  446.          void main() {
  447.             magic_setup();
  448.             boxback := MAGENTA;
  449.             pile("Do you like this background color?");
  450.             getanykey(-1,-1);
  451.          }
  452.  
  453.          Performance of example:
  454.          The  box  background  color  is  set  to  magenta. A box will
  455.          appear on the screen asking a silly question.  The  box  will
  456.          have  a  magenta  background.   When  a  key  is pressed, the
  457.          program quits.
  458.  
  459.          *************************************************************
  460.          char boxtext - Global Variable
  461.  
  462.          Usage: boxback = color;
  463.  
  464.          Description:
  465.          Color  is  represented  with  an  integer  from  0 to 15 or a
  466.          pre-defined  color  constant   enumerated   in   CONIO.H   or
  467.          GRAPHICS.H.  Changing  the  value  of boxtext will affect the
  468.          text color in pop-up boxes,  text  boxes,  dialog  boxes  and
  469.          menus.  Colors are the same in text and graphics modes.
  470.  
  471.          Considerations:
  472.          May  not  have the expected effect when used with the limited
  473.          palettes of 4-color CGA (mode  0,1  or  2),  2-color  CGA  or
  474.          Hercules.
  475.  
  476.          See Also:
  477.          mainback, maintext, boxtext, barback, bartext.
  478.  
  479.          Example:
  480.          #include <magic.h>
  481.          #include <conio.h>
  482.          void main() {
  483.             magic_setup();
  484.             boxtext := BLACK;
  485.             pile("Do you like this background color?");
  486.             getanykey(-1,-1);
  487.          }
  488.  
  489.          Performance of example:
  490.          The  box text color is set to black. A box will appear on the
  491.          screen asking a silly question.  The box will  contain  black
  492.          text.
  493.  
  494.          *************************************************************
  495.          void bugle(void) - function
  496.  
  497.          Usage: bugle()
  498.  
  499.          Description:
  500.              Bugle()  plays  a  short  tune  like a bugle at the horse
  501.          races.
  502.  
  503.          Considerations:
  504.             The  global  variable  musicon  must  be greater than 0 or
  505.          bugle() will not make a sound.
  506.  
  507.          See Also:
  508.          musicon,  twinkle(),  pink(), soundup(), sounddown(), sorry()
  509.          {Magic} sound(), nosound(), delay() {Borland}
  510.  
  511.          Example:
  512.          include <magic.h>
  513.          void main() {
  514.             magic_setup();
  515.             musicon = 0;
  516.             pile("Do you want to hear the bugle?");
  517.             getanykey(-1,-1);
  518.             if (u == 'Y') musicon = 1;
  519.             bugle();
  520.          }
  521.  
  522.          Performance of example:
  523.              If  the  user   answers   the   question   affirmatively,
  524.          bugle() will play it's sound effect.
  525.  
  526.          *************************************************************
  527.          char center - Global Variable
  528.  
  529.          Usage: /* example */ if (center) break;
  530.  
  531.          Description:
  532.             Center is a global char variable used to record the status
  533.          of the center mouse button.  If center = 1  then  the  center
  534.          mouse  button  has  been  pressed,  otherwise center = 0.  If
  535.          there is no mouse, or if the  mouse  has  only  two  buttons,
  536.          center is always 0.
  537.  
  538.          Considerations:
  539.             If  a  three-button  mouse  is  installed,  the  status of
  540.          center will  change  with  every  call  to  poll(),  waste(),
  541.          resetmouse()  or procedures within Magic which handle text or
  542.          pop up boxes.
  543.  
  544.          See Also: poll(), waste(), ResetMouse(), left, right
  545.  
  546.          Example:
  547.          #include <magic.h>
  548.          void main() {
  549.             magic_setup();
  550.             waste();
  551.             pile("Nothing will change until you click the");
  552.             pile("center mouse button");
  553.             pop(-1,-1);
  554.             do poll; while (!center);
  555.          }
  556.  
  557.          Performance of example:
  558.             A box containing two lines of text will stay on the screen
  559.          until the user clicks the center mouse button.   The  program
  560.          will then terminate.
  561.  
  562.          *************************************************************
  563.          char centerjustify - Global Variable
  564.  
  565.          Usage: /* example */ CenterJustify = 1
  566.  
  567.          Description:
  568.          If you set centerjustify to 1 all subsequent calls to  pop(),
  569.          dialog(),  getyn(), getanykey(), menu() will contain centered
  570.          text. Default is 0, left justification.
  571.  
  572.          Considerations:
  573.             When  a program starts, centerjustify is 0.  If you change
  574.          centerjustify to 1 all the functions that use it will  center
  575.          text  until you specifically change it back to 0. On 4.77 mhz
  576.          computers (older  models)  this  can  slow  menu  and  pop-up
  577.          generation  slightly.   Works  the  same in text and graphics
  578.          modes.
  579.  
  580.          See Also:
  581.          pop(), getanykey(), getyn(), dialog(), menu().
  582.  
  583.          Example:
  584.          #include <magic.h>
  585.          void main() {
  586.             magic_setup();
  587.             centerjustify := 1;
  588.             pile("This is a very long line of text to display");
  589.             pile("This is short");
  590.             getanykey(-1,-1);
  591.          }
  592.  
  593.          Performance of example:
  594.          Two  lines of text will pop up on the screen and wait until a
  595.          user presses any key. The second line will be centered  under
  596.          the first.
  597.  
  598.          *************************************************************
  599.          void cgahivideo(void) - function
  600.  
  601.          Usage: cgahivideo()
  602.  
  603.          Description:
  604.          This  initializes  the system in CGA graphics mode. CGA video
  605.          driver will be automatically compiled into the  .EXE  program
  606.          file,   eliminating  the  need  for  external  CGA.BGI  file.
  607.          Graphics mode is set to 4 - 640 x 200 resolution, 2 colors.
  608.  
  609.          Considerations:
  610.          Will not work on Hercules-equipped  computers.  Graphmode  is
  611.          initially set to 4 (see Borland manual for more details).
  612.  
  613.          See Also:
  614.          bestvideo(),    cgalovideo,     hercvideo(),     egalovideo()
  615.          egahivideo(),    vgalovideo(),   vgahivideo(),   textvideo(),
  616.          cleanup() {Magic} setgraphmode() {Borland}
  617.  
  618.          Example:
  619.          #include <magic.h>
  620.          #include <graphics.h>
  621.          void main() {
  622.             magic_setup();
  623.             cgahivideo();
  624.             rectangle(10,10,629,189);
  625.             waitforuser();
  626.             cleanup();
  627.          }
  628.  
  629.          Performance of example:
  630.          The  system  is  put  in  CGA  2-color graphics mode. A large
  631.          rectangle is displayed until any key is pressed.  The program
  632.          then terminates gracefully.
  633.  
  634.          *************************************************************
  635.          void cgalovideo(void) - function
  636.  
  637.          Usage: cgalovideo()
  638.  
  639.          Description:
  640.          This  initializes  the system in CGA graphics mode. CGA video
  641.          driver will be automatically compiled into the  .EXE  program
  642.          file, eliminating the need for external CGA.BGI  file.  Graph
  643.          mode is set to 0, 320 x 200 resolution, 4 colors.
  644.  
  645.          Considerations:
  646.          Will not work on Hercules-equipped  computers.  Graphmode  is
  647.          initially set to 0 (see Borland manual for more details).  In
  648.          this  mode,  with  default  colors,  some  LCD laptops may be
  649.          unreadable. To repair, switch to another graphics  mode  with
  650.          setgraphmode()  (see Borland  manual).
  651.  
  652.          See Also:
  653.          bestvideo(),    cgahivideo,     hercvideo(),     egalovideo()
  654.          egahivideo(),    vgahivideo(),   vgalovideo(),   textvideo(),
  655.          cleanup() {Magic}  setgraphmode() {Borland}
  656.  
  657.          Example:
  658.          #include <magic.h>
  659.          #include <graphics.h>
  660.          void main() {
  661.             magic_setup();
  662.             cgavideo();
  663.             rectangle(10,10,310,190);
  664.             waitforuser();
  665.             cleanup();
  666.          }
  667.  
  668.          Performance of example:
  669.          The  system is put in CGA graphics mode. A large rectangle is
  670.          displayed   until  any  key  is  pressed.  The  program  then
  671.          terminates gracefully. The colors used for  this  example may
  672.          not be easily distinguished on a laptop LCD display.
  673.  
  674.          *************************************************************
  675.          void cleanup(void) - function
  676.  
  677.          Usage: cleanup()
  678.  
  679.          Description:
  680.          This procedure clears the screen, releases  memory  held  for
  681.          video  applications,  returns to standard text and background
  682.          colors  in  text  mode,  saves  and  closes   open  automatic
  683.          files, and quits, resulting in a graceful return to DOS.
  684.  
  685.          Considerations:
  686.          Call  cleanup() as the last line executed in a program. Works
  687.          in graphics and text modes.
  688.  
  689.          Example:
  690.          #include <magic.h>
  691.          #include <graphics.h>
  692.          void main() {
  693.             magic_setup();
  694.             cgavideo();
  695.             rectangle(10,10,310,190);
  696.             waitforuser();
  697.             cleanup();
  698.          }
  699.  
  700.          Performance of example:
  701.          The  system is put in CGA graphics mode. A large rectangle is
  702.          displayed   until  any  key  is  pressed.  The  program  then
  703.          terminates  gracefully  to the DOS prompt.
  704.  
  705.          *************************************************************
  706.          void clearsents(void) - function
  707.  
  708.          Usage: clearsents()
  709.  
  710.          Description:
  711.              After a call to pop() or anytime you want  to  reset  all
  712.          the  strings in the array, sent[], to empty strings, use this
  713.          function. The global int variable "howmany" is reset to 0.
  714.  
  715.          Considerations:
  716.  
  717.          See Also:
  718.              pop(), restore(), sent[], getanykey(), getyn(), dialog(),
  719.          menu()
  720.  
  721.          Example:
  722.          #include <magic.h>
  723.          void main() {
  724.             magic_setup();
  725.             pile("This is a demo");
  726.             pile("This is more text");
  727.             pop(1,4);
  728.             clearsents();
  729.             pile("This is another text box");
  730.             getanykey(-1,-1);
  731.             .
  732.             .
  733.          }
  734.  
  735.          Performance of example:
  736.              Two strings of text  are  assigned  to  sent[]  and  then
  737.          displayed with pop().  These strings are cleared to null with
  738.          clearsents(),  then  the  first  string  is reused to display
  739.          "This is another text box".
  740.  
  741.          *************************************************************
  742.          void complex(void) - function
  743.  
  744.          Usage: complex()
  745.  
  746.          Description:
  747.          This function causes outtext() and  outtextxy()  to  generate
  748.          text in the "complex" stroked font.
  749.  
  750.          Considerations:
  751.              COMP.CHR  is linked into .EXE file and RAM usage and disk
  752.          space requirements increase.  This font is not available with
  753.          early versions of Turbo C.
  754.  
  755.          See Also:
  756.              triplex(),  little(),  gothic(),  sansserif(),  script(),
  757.          italic(), bold(), simple(), bitmap(), european()
  758.  
  759.          Example:
  760.          #include <magic.h>
  761.          #include <graphics.h>
  762.          void main(){
  763.             magic_setup();
  764.             bestvideo();
  765.             bold();
  766.             outtextxy(0,0,"Bold font");
  767.             waitforuser();
  768.             cleanup();
  769.          }
  770.  
  771.          Performance of example:
  772.          Program writes "Bold font" on screen using the "bold" font.
  773.  
  774.          *************************************************************
  775.          char *cursormap - Global Variable
  776.  
  777.          Usage:  Internal  usage  by  Magic.lib.   Not recommended for
  778.          direct manipulation.
  779.  
  780.          Description:
  781.             Used to store bitmap area occupied by  arrow  in  graphics
  782.          modes.
  783.  
  784.          *************************************************************
  785.          void dialog(int x, int 5) - function
  786.  
  787.          Usage: dialog(x,y)
  788.  
  789.          Description:
  790.              Dialog() requires two integers, an x (horizontal)  and  y
  791.          (vertical) to establish the position of the upper left corner
  792.          of  the  dialog  box  on the screen.  In text mode, the upper
  793.          left corner is 1,1, and the lower right is 80,25. In graphics
  794.          mode the upper left is 0,0, and the lower right is  variable,
  795.          depending on the current graphics card and mode.
  796.              You can force dialog() to pop-up in  the  center  of  the
  797.          screen  by  using  a  negative  number for the x and/or the y
  798.          positions.
  799.              Dialog() will pop up a box on the screen containing lines
  800.          of  text  plus  one blank line at the bottom of the box.  The
  801.          user is prompted to type an answer in that bottom line.   The
  802.          lines  that  will  be displayed are predeclared as the array:
  803.          sent[81][46].
  804.              To  use  dialog(),  you must first assign the text to the
  805.          array.   Use as few or as many lines as you like up to 19, as
  806.          in the example below. Dialog will automatically ignore  lines
  807.          beyond  those  which contain your text. When the user presses
  808.          [Enter] or clicks the  left  mouse  button,  the  dialog  box
  809.          disappears.  A  new  string  exists  in  the  global variable
  810.          answer, which contains what the user typed.  The sent[81][46]
  811.          array is cleared.
  812.              The user can type an answer string as long as the longest
  813.          sent[]  in the dialog box. To get a longer answer string, pad
  814.          any sent[] string with spaces to make the dialog box wider.
  815.              Dialog() works in text or graphics mode.
  816.  
  817.          Considerations:
  818.              See  above.   In graphics modes, default bitmap font will
  819.          be used. Do not attempt to exceed the limits of  sent[81][46]
  820.          or unpredictable results will occur.   Colors,  font  choices
  821.          and linestyle from main program will be unaffected. There  is
  822.          a  limit to the maximum size of a dialog() box. For instance,
  823.          in VGA-HI graphics mode, the limit is about 20 lines of  text
  824.          with the longest line being about 40 characters long.
  825.  
  826.          See also: sent[], pop(), getyn(), getanykey(), menu()
  827.  
  828.          Example:
  829.          #include <magic.h>
  830.          #include <string.h>
  831.          void main () {
  832.             char teststring[81];
  833.             magic_setup();
  834.             pile("    How would you answer this question?   ");
  835.             pile("            Any answer will do.");
  836.             dialog(-1,5);
  837.             strcpy(teststring,answer);
  838.             .
  839.             .
  840.          }
  841.  
  842.          Performance of example:
  843.          Only  the  first two strings from the array sent[] are filled
  844.          with text.  Dialog() is called and pops a box onto the screen
  845.          containing only those two sent[]s, plus an empty line at  the
  846.          bottom.   The  program  then  waits  for  the user to type an
  847.          answer in the empty line then press [Enter] or click the left
  848.          mouse button. The dialog box  is  wider  than  the  questions
  849.          because  they  have  been padded with spaces. This allows the
  850.          user room for a long answer. Since the first  number  in  the
  851.          variables  passed  to  Dialog  is  a  -1, the box is centered
  852.          horizontally on the screen. After the user  finishes  typing,
  853.          the  dialog  box  disappears, leaving a string called answer.
  854.          The teststring is a copy of answer and the program can go  on
  855.          to process it as desired.
  856.  
  857.          *************************************************************
  858.          void dumpmaps(void) - function
  859.  
  860.          Usage: dumpmaps()
  861.  
  862.          Description:
  863.             Dumpmaps() will release all memory held for screen images,
  864.          without  restoring  the images. Works the same in graphics or
  865.          text modes.
  866.  
  867.          Considerations:
  868.              In  graphics  modes, it is easy to fill all available RAM
  869.          with unused screen images. This seldom-needed procedure  will
  870.          help you clear that out.
  871.  
  872.          See  also:  restore(), pop(), getanykey(), getyn(), dialog(),
  873.          menu(), xclear(), cleanup()
  874.  
  875.          Example:
  876.          #include <magic.h>
  877.          #include <string.h>
  878.          void main() {
  879.             magic_setup();
  880.             strcpy(sent[1],"An example string");
  881.             strcpy(sent[2],"Another example string");
  882.             pop(10,10);
  883.             strcpy(sent[1],"An example string");
  884.             strcpy(sent[2],"Another example string");
  885.             pop(1,1);
  886.             strcpy(sent[1],"An example string");
  887.             strcpy(sent[2],"Another example string");
  888.             pop(30,10);
  889.             strcpy(sent[1],"This is becoming a messy screen");
  890.             pop(36,12);
  891.             waitforuser();
  892.             dumpmaps();
  893.             .
  894.             .
  895.          }
  896.  
  897.          Performance of example:
  898.             The screen is cluttered with a bunch of pop-up boxes. When
  899.          the user presses a key, the memory held for  the  replacement
  900.          of  those  boxes  disappears, but he boxes remain pictured on
  901.          the screen.
  902.  
  903.          *************************************************************
  904.          void dumpmapsg(void)
  905.  
  906.          Usage:  For  internal  use by Magic.lib only.  Not for direct
  907.          manipulation.
  908.  
  909.          Description:
  910.              This is a sub-routine used when in graphics modes.
  911.  
  912.          *************************************************************
  913.          void egahivideo() - function
  914.  
  915.          Usage: egahivideo()
  916.  
  917.          Description:
  918.          This initializes the system in EGA graphics mode.  EGA  video
  919.          driver  will  be automatically compiled into the .EXE program
  920.          file, eliminating the need for external CGA.BGI file. Program
  921.          will use 640 x 350 resolution, 16 colors.
  922.  
  923.          Considerations:
  924.          Will  not  work  on  CGA  or   Hercules-equipped   computers.
  925.          Graphmode  is initially set to 0 (see Borland manual for more
  926.          details).
  927.  
  928.          See Also:
  929.          bestvideo(),   cgalovideo(),    cgahivideo(),    hercvideo(),
  930.          egalovideo(),    vgahivideo(),   vgalovideo(),   textvideo(),
  931.          cleanup() {Magic} setgraphmode() {Borland}
  932.  
  933.          Example:
  934.          #include <magic.h>
  935.          #include <graphics.h>
  936.          void main() {
  937.             magic_setup();
  938.             egahivideo();
  939.             rectangle(10,10,629,339);
  940.             waitforuser();
  941.             cleanup();
  942.          }
  943.  
  944.          Performance of example:
  945.          The  system is put in EGA graphics mode. A large rectangle is
  946.          displayed   until  any  key  is  pressed.  The  program  then
  947.          terminates gracefully.
  948.  
  949.          *************************************************************
  950.          void egalovideo() - function
  951.  
  952.          Usage: egalovideo()
  953.  
  954.          Description:
  955.          This initializes the system in EGA graphics mode.  EGA  video
  956.          driver  will  be automatically compiled into the .EXE program
  957.          file, eliminating the need for external CGA.BGI file. Program
  958.          will use 640 x 200 resolution, 16 colors.
  959.  
  960.          Considerations:
  961.          Will  not  work  on  CGA  or   Hercules-equipped   computers.
  962.          Graphmode  is initially set to 0 (see Borland manual for more
  963.          details).
  964.  
  965.          See Also:
  966.          bestvideo(),    cgalovideo(),    cgahivideo,     hercvideo(),
  967.          egahivideo(),    vgahivideo(),   vgalovideo(),   textvideo(),
  968.          cleanup() {Magic} setgraphmode() {Borland}
  969.  
  970.          Example:
  971.          #include <magic.h>
  972.          #include <graphics.h>
  973.          void main() {
  974.             magic_setup();
  975.             egalovideo();
  976.             rectangle(10,10,629,189);
  977.             waitforuser();
  978.             cleanup();
  979.          }
  980.  
  981.          Performance of example:
  982.          The  system is put in EGA-lo graphics mode. A large rectangle
  983.          is displayed until any key  is  pressed.   The  program  then
  984.          terminates gracefully.
  985.  
  986.          *************************************************************
  987.          void european(void)
  988.  
  989.          Usage: european()
  990.  
  991.          Description:
  992.          This function causes outtext() and  outtextxy()  to  generate
  993.          text in the "european" stroked font.
  994.  
  995.          Considerations:
  996.              EURO.CHR  is linked into .EXE file and RAM usage and disk
  997.          space requirements increase.
  998.  
  999.          See Also:
  1000.              triplex(),  little(),  gothic(),  sansserif(),  script(),
  1001.          italic(), complex(), simple(), bitmap(), bold()
  1002.  
  1003.          Example:
  1004.          #include <magic.h>
  1005.          #include <graphics.h>
  1006.          void main(){
  1007.             magic_setup();
  1008.             bestvideo();
  1009.             european();
  1010.             outtextxy(0,0,"European font");
  1011.             waitforuser();
  1012.             cleanup();
  1013.          }
  1014.  
  1015.          Performance of example:
  1016.          Program  writes  "European  font"   on   screen   using   the
  1017.          "European" font.
  1018.  
  1019.          *************************************************************
  1020.          int figurehowlong(void) - function
  1021.  
  1022.          Usage: /* example */ number = figurehowlong();
  1023.  
  1024.          Description:
  1025.              Figurehowlong() works the global character array variable
  1026.          sent[81][46] and returns the  global  int  variable  howlong.
  1027.          Howlong  is the length of the longest string currently in the
  1028.          array. If in text mode, howlong will represent the number  of
  1029.          characters  in the longest string.  If in a graphics mode, it
  1030.          will represent  the  length  in  pixels  using  the currently
  1031.          selected font and font proportions.
  1032.              Figurehowlong() also calls figurehowmany().
  1033.              If  centerjustify  > 0 then figurehowlong() also pads any
  1034.          strings shorter than the longest one with spaces  for  center
  1035.          justification.
  1036.  
  1037.          Considerations:
  1038.          Figurehowlong()   is   called   automatically  by  pop()  and
  1039.          functions  that  use  pop()  such  as  getanykey(),  getyn(),
  1040.          dialog() and menu().
  1041.  
  1042.          See Also
  1043.          figurehowmany(), howmany, howlong, sent[]
  1044.  
  1045.          Example:
  1046.          #include <magic.h>
  1047.          #include <string.h>
  1048.          void main(){
  1049.             char userstring_1[80],userstring_2[80];
  1050.             magic_setup();
  1051.             .
  1052.             .
  1053.             pile(userstring_1);
  1054.             pile(userstring_2);
  1055.             figurehowlong();
  1056.             if (howlong < 76) getanykey(-1,-1);
  1057.          }
  1058.  
  1059.          Performance of example:
  1060.          The  program  somehow gets two strings of characters and they
  1061.          are assigned to sent[].  If they are short enough, less  than
  1062.          76 characters, they are displayed.
  1063.  
  1064.          *************************************************************
  1065.          int figurehowmany(void) - function
  1066.  
  1067.          Usage: /* example */ number = figurehowmany();
  1068.  
  1069.          Description:
  1070.              Figurehowmany() works the global character array variable
  1071.          sent[81][46] and returns the  global  int  variable  howmany.
  1072.          Howmany   is the number of strings which will be displayed by
  1073.          pop() and the functions which use pop(). As you know, strings
  1074.          are assigned from the lowest number to the highest,  and  any
  1075.          unused  strings  contain  no text.  Figurehowlong() starts at
  1076.          the maximum possible string (46) and decrements howlong until
  1077.          text is encountered.
  1078.  
  1079.          Considerations:
  1080.          Figurehowmany() is called automatically by figurehowlong().
  1081.  
  1082.          See Also
  1083.          figurehowlong(), howmany, howlong, sent[]
  1084.  
  1085.          Example:
  1086.          #include <magic.h>
  1087.          #include <string.h>
  1088.          void main(){
  1089.             char userstring[81][20];
  1090.             magic_setup();
  1091.             .
  1092.             .
  1093.             .
  1094.             pile(userstring[x]);
  1095.             pile(userstring[x + 1]);
  1096.             figurehowmany();
  1097.             if (howmany < 12) getanykey(-1,-1);
  1098.             else getanykey(-1,1);
  1099.          }
  1100.  
  1101.          Performance of example:
  1102.          The program somehow gets several strings  of  characters  and
  1103.          they  are assigned to sent[].  If the total number of strings
  1104.          is less than 12 then getanykey() pops up in the center of the
  1105.          screen.  If there are more than 11 strings, then  getanykey()
  1106.          pops up at the top of the screen.
  1107.  
  1108.          *************************************************************
  1109.          void fileread(void) - function
  1110.  
  1111.          Usage: fileread()
  1112.  
  1113.          Description:
  1114.             Fileread() is a  function  that  automatically  reads  one
  1115.          character  from  the  pre-declared  Magic file called infile.
  1116.          Opening and closing the file is automatic. Only one character
  1117.          is read and the next call to fileread()  will  get  the  next
  1118.          character in the file. The global char variable "u"  contains
  1119.          the character read.
  1120.  
  1121.          Considerations:
  1122.          The file is called 'Infile' within the program, but must have
  1123.          an external name under which it will be stored on disk.   You
  1124.          may  first  call nameinfile(), before using fileread, or else
  1125.          the program will try to read a file with the default external
  1126.          name of "INPUT". If there is an error, such as trying to read
  1127.          past the end of the file, or reading a  file  that  does  not
  1128.          exist, fileread() will set the global char variable "problem"
  1129.          to 1. Otherwise problem will be 0.
  1130.  
  1131.          See Also:
  1132.          nameinfile(),  filereadln(),  problem {Magic} reset(), feof()
  1133.          {Borland}
  1134.  
  1135.          Example:
  1136.          #include <magic.h>
  1137.          #include <stdio.h>
  1138.          void main() {
  1139.             magic_setup();
  1140.             xclear();
  1141.             nameinfile("sample.doc");
  1142.             for (a = 0; a <= 1000; a++) {
  1143.                fileread();
  1144.                if (problem) break;
  1145.                printf("%c",u);
  1146.             }
  1147.          }
  1148.  
  1149.          Performance of example:
  1150.          The screen is cleared. The file to read will be 'Sample.Doc'.
  1151.          Assuming  the  file  exists,  the  first 1000 characters from
  1152.          that file will be displayed on the screen, then  the  program
  1153.          ends.  If  the  file is shorter than 1000 characters, problem
  1154.          will become 1 and the program will end prematurely.
  1155.  
  1156.          *************************************************************
  1157.          void filereadln(void) - function
  1158.  
  1159.          Usage: filereadln()
  1160.  
  1161.          Description:
  1162.             Filereadln() is a function that  automatically  reads  one
  1163.          line  of text from the pre-declared Magic file called infile.
  1164.          Opening and closing the file is  automatic.   Only  one  line
  1165.          (string)  is  read and the next call to filereadln() will get
  1166.          the next string in the file.  The global char array  variable
  1167.          "answer"  contains the character read.
  1168.  
  1169.          Considerations:
  1170.          The file is called 'Infile' within the program, but must have
  1171.          an external name under which it will be stored on disk.   You
  1172.          may first call nameinfile(), before using filereadln, or else
  1173.          the program will try to read a file with the default external
  1174.          name of "INPUT". If there is an error, such as trying to read
  1175.          past the end of the file, or reading a  file  that  does  not
  1176.          exist,   filereadln()  will  set  the  global  char  variable
  1177.          "problem" to 1. Otherwise problem will be 0.  Lines  of  text
  1178.          in  a  file are considered terminated with the character pair
  1179.          #13  followed  by  #10   (carriage  return/linefeed).  Answer
  1180.          follows the C convention of null termination  (#0),  and  the
  1181.          carriage return/linefeed pair is stripped off.
  1182.  
  1183.          See Also:
  1184.          nameinfile(), fileread(),  problem  {Magic}  reset(),  feof()
  1185.          {Borland}
  1186.  
  1187.          Example:
  1188.          #include <magic.h>
  1189.          #include <stdio.h>
  1190.          void main() {
  1191.             magic_setup();
  1192.             xclear();
  1193.             nameinfile("sample.doc");
  1194.             do {
  1195.                filereadln();
  1196.                printf("%s",answer);
  1197.             }
  1198.             while (!problem);
  1199.          }
  1200.  
  1201.          Performance of example:
  1202.          The screen is cleared. The file to read will be 'Sample.Doc'.
  1203.          Assuming  the  file  exists, each line from that file will be
  1204.          displayed on the screen, then the program ends.
  1205.  
  1206.          *************************************************************
  1207.          void filewrite(unsigned char character) - function
  1208.  
  1209.          Usage: filewrite(thing)
  1210.  
  1211.          Description:
  1212.              Filewrite()  will  write  a  character  into the standard
  1213.          output  file.   Opening  and  closing  the  file  is  handled
  1214.          automatically.   If  the  file  exists, the character will be
  1215.          appended to the end. If the file does not exist  it  will  be
  1216.          created.
  1217.  
  1218.          Considerations:
  1219.          The standard text output  file  is  called  "outfile"  within
  1220.          Magic,  but must have an external name under which it will be
  1221.          stored on disk.  You may first call nameoutfile, before using
  1222.          filewrite(), or else the program will write to file with  the
  1223.          default  external  name  of  "OUTPUT".  If there is an error,
  1224.          nothing will be written to disk and the global int  variable,
  1225.          problem  will  be  1.   If  all is ok problem is 0.  Only one
  1226.          character can be written to the output  file  with  a  single
  1227.          call  to  filewrite().   No  numerical  values can be written
  1228.          unless they are first converted to a character.
  1229.  
  1230.          See Also:
  1231.          nameoutfile(), filewriteln(), problem {Magic} all the  string
  1232.          handling functions {Borland}
  1233.  
  1234.          Example:
  1235.          #include <magic.h>
  1236.          void main() {
  1237.             magic_setup();
  1238.             nameoutfile("sample.doc");
  1239.             filewrite("T");
  1240.          }
  1241.  
  1242.          Performance of example:
  1243.          The  standard  text  file  is  renamed "SAMPLE.DOC". A single
  1244.          character is written to the file then the program  ends.   If
  1245.          there  was  no  previous  file  by  that  name, SAMPLE.DOC is
  1246.          created, otherwise the line is appended to  the  end  of  the
  1247.          other text in the file. If you look at SAMPLE.DOC with a word
  1248.          processor  or  text  editor or with the IDE, you will see the
  1249.          file contains only: T.
  1250.  
  1251.          *************************************************************
  1252.          void filewriteln(unsigned char *string) - function
  1253.  
  1254.          Usage: filewrite(thing)
  1255.  
  1256.          Description:
  1257.              Filewriteln()  will  write  a  string into the standard
  1258.          output  file.   Opening  and  closing  the  file  is  handled
  1259.          automatically.   If  the  file  exists, the string will be
  1260.          appended to the end. If the file does not exist  it  will  be
  1261.          created.
  1262.  
  1263.          Considerations:
  1264.          The standard text output  file  is  called  "outfile"  within
  1265.          Magic,  but must have an external name under which it will be
  1266.          stored on disk.  You may first call nameoutfile, before using
  1267.          filewriteln(), or else the program will write  to  file  with
  1268.          the default external name of "OUTPUT".  If there is an error,
  1269.          nothing  will be written to disk and the global int variable,
  1270.          problem will be 1.  If all is ok  problem  is  0.   Only  one
  1271.          string  can  be written to the output file with a single call
  1272.          to filewriteln().  The C standard null termination (ASCII #0)
  1273.          will be removed and an ASCII  standard  carriage  return  and
  1274.          linefeed  will be added (ASCII #13,#10).  No numerical values
  1275.          can be written unless they are first converted to a string.
  1276.  
  1277.          See Also:
  1278.          nameoutfile(),  filewrite(),  problem  {Magic} all the string
  1279.          handling functions {Borland}
  1280.  
  1281.          Example:
  1282.          #include <magic.h>
  1283.          #include <string.h>
  1284.          void main() {
  1285.             magic_setup();
  1286.             nameoutfile("sample.doc");
  1287.             strcpy(sent[1],"This is a test.");
  1288.             strcpy(sent[2],"This is the second line of test.");
  1289.             filewriteln(sent[1]);
  1290.             filewriteln(sent[2]);
  1291.          }
  1292.  
  1293.          Performance of example:
  1294.          The  standard text file is renamed "SAMPLE.DOC".  Two strings
  1295.          are written to the file then the program ends.  If there  was
  1296.          no  previous  file  by  that  name,  SAMPLE.DOC  is  created,
  1297.          otherwise the lines are appended to the end of the other text
  1298.          in the file. If you look at SAMPLE.DOC with a word  processor
  1299.          or  text  editor  or  with  the  IDE,  you  will see the file
  1300.          contains:
  1301.              This is a test.
  1302.              This is the second line of test.
  1303.  
  1304.          *************************************************************
  1305.          void getanykey(int x, int y) - function
  1306.  
  1307.          Usage: getanykey(x,y)
  1308.  
  1309.          Description:
  1310.              This is for pop-up notices. A  message  pops  up  on  the
  1311.          screen  then  waits  for the user to press any key or click a
  1312.          mouse button. You must write strings for the array of sent[]s
  1313.          before  calling this procedure. After the user presses a key,
  1314.          all traces of the pop-up and the sent[]s disappear.
  1315.              Getanykey()  requires  two  integer  variables, the first
  1316.          determines the horizontal position on  the  screen,  and  the
  1317.          second  is  the  vertical  coordinate.   If  either number is
  1318.          negative, the pop-up message will be centered on  the  screen
  1319.          in the corresponding dimension.
  1320.              When  done,  getanykey()  assigns  the  value  of the key
  1321.          pressed to the global unsigned char variable "u." If a  mouse
  1322.          button was clicked, the global char variable "keydetect" will
  1323.          be 0.  If an alphanumeric key was pressed keydetect will be 1
  1324.          and  if  an  extended  key  (such  as  [f2]  or  [Page Down])
  1325.          keydetect will be 2.
  1326.  
  1327.          Considerations:
  1328.             Maximum sent array size: 18. Make sure to add something to
  1329.          this effect to every message to avoid confusing  your  users:
  1330.          "Press any key to continue..."
  1331.             There is a limit to the maximum size of a getanykey() box.
  1332.          For  instance, in VGA-HI graphics mode, the limit is about 20
  1333.          lines of text with the longest line being about 40 characters
  1334.          long.
  1335.  
  1336.          See Also:
  1337.          menu(),  pop(), dialog(), getyn(), sent[].
  1338.  
  1339.          Example:
  1340.          #include <magic.h>
  1341.          void main (){
  1342.             magic_setup();
  1343.             .
  1344.             .
  1345.             pile("You have selected an option available only");
  1346.             pile("to registered users. Please send money!!!");
  1347.             pile("Press any key to continue...");
  1348.             getanykey(-1,-1);
  1349.             .
  1350.             .
  1351.          }
  1352.  
  1353.          Performance of example:
  1354.              A box pops up on the screen containing three lines,  then
  1355.          disappears  without  a trace when the user presses any key or
  1356.          clicks a mouse button.
  1357.  
  1358.          *************************************************************
  1359.  
  1360.                           Continued in file: MAGIC.2
  1361.  
  1362.          (This  file  is  split  into  three  parts because some older
  1363.          versions  of Turbo C cannot display files larger than 64k. If
  1364.          you have a newer compiler which supports large files, you may
  1365.          want to recombine these three parts.)
  1366.