home *** CD-ROM | disk | FTP | other *** search
/ Frozen Fish 1: Amiga / FrozenFish-Apr94.iso / bbs / alib / d5xx / d573 / mtoollibrary.lha / MToolLibrary / English / Doc next >
Text File  |  1991-12-22  |  11KB  |  347 lines
  1.  MToolLibrary V 2.20
  2.  © by Rüdiger Dreier 1988-91
  3.  
  4.  
  5.  THE AUTHOR UNDERTAKES NO LIABILITY FOR ANY DAMAGE CAUSED BY THE APPROPRIATE
  6.  OR NOT APPROPRIATE USE OF THIS PROGRAM !
  7.  THE AUTHOR UNDERTAKES NO LIABILITY FOR THE FAULTLESSNESS OF THIS PROGRAM !
  8.  USE IT AT YOUR OWN RISK !
  9.  
  10.  The mtool.library is a shared library  for the Amiga. Copy it to your LIBS:.
  11.  You  also  need mathieeedoubbas.library  and  mathieeedoubtrans.library  in
  12.  LIBS:.
  13.  
  14.  THE NAME
  15.  ========
  16.  
  17.  Until V2.16, this library was called "tool.library", but then I found
  18.  another library of this name... So I called my library "mtool.library"
  19.  and "ToolBase" became "MToolBase". I hope, there will be no one calling
  20.  his/her library "mtool.library", too....
  21.  
  22.  
  23.  FOR PROGRAMERS
  24.  ==============
  25.  
  26.  Every program, that uses the mtool.library must include tool.h.
  27.  Open the library:
  28.                         struct MToolBase *MToolBase; /* Global */
  29.  
  30.                         MToolBase=(struct MToolBase *)OpenLibrary("mtool.library,0");
  31.  
  32.  Struct MToolBase  contains pointers  to the  four libraries  IntuitionBase,
  33.  GfxBase   and  the  two   MathIeee.....Base's.  So,  if   a  program  uses
  34.  mtool.library, you can get access to these other libraries like this:
  35.  
  36.                         IntuitionBase=MToolBase->IntuitionBase;
  37.  
  38.  You  need not to  open them. Perhaps  that is not  legal, but mtool.library
  39.  opens this libraries, so they are in memory. It works and should work with
  40.  newer versions of Kickstart, too.
  41.  
  42.  Attention : On an Amiga with FPU, some functions may not work as supposed,
  43.  when the mathieeedoubbas.library is not opened by the programm itself, e.g.
  44.  the function IEEEDPFix() begins to round...
  45.  So open the two mathe-libraries yourself.....
  46.  
  47.  
  48.  
  49.  
  50.  A short description of the functions:
  51.  
  52.  STRINGS:
  53.  =======
  54.  VOID left (char *Dest,char *Source,LONG Number)(a0,a1,d0)
  55.  VOID right(char *Dest,char *Source,LONG Number)(a0,a1,d0)
  56.  VOID mid  (char *Dest,char *Source,LONG Start,LONG Number)(a0,a1,d0,d1)
  57.  
  58.  These three  functions are  similar to  those in  Basic. Dest  must be  big
  59.  enough.
  60.  
  61.  VOID copy(LONG start,LONG Number,char *Dest,char *source)(d0,d1,d2,d3)
  62.  
  63.  This function is similar to mid, it is here cause of compatibility.
  64.  
  65.  
  66.  LONGcheck (LONG Char1,LONG Char2,LONG Start,LONG End,char *String)
  67.            (d0,d1,d2,d3,a0)
  68.  LONG checkback(LONG Char1, LONG Char2, LONG Start, LONG End, char *String)
  69.                (d0,d1,d2,d3,a0)
  70.  
  71.  This  two functions  are quite  difficult to  explain. They  search for the
  72.  first  appearance of the two  chars (Char1 and Char2).  Therefore, they are
  73.  aware of the brackets. Checkback begins  at the end of the string, check at
  74.  the beginning. Example:
  75.  string:                        1+(2-4) Start:0 End:6
  76.  The - sign is not found, because of the brackets.
  77.  string:                        1+(2-4) Start:3 End:5
  78.  The - sign is found, a 4 is returned.
  79.  
  80.  
  81.  LONG AnzahlKlammern(char *String)(a0)
  82.  
  83.  (Numberofbrackets) Returns the number of open brackets:
  84.  Returns:                0: there is exactly one ( for every )
  85.                         <0: too much )
  86.                         >0: too much (
  87.  
  88.  
  89.  HELP FOR INTUITION AND GRAPHIC
  90.  ==============================
  91.  
  92.  LONG request(char *yes,char *no,char *body)(d0,d1,d2)
  93.  
  94.  Opens an autorequester on the actual screen.
  95.  
  96.  LONG NewRequest(       struct Window *Window,
  97.                                 char *yes,
  98.                                 char *no,
  99.                                 char *body)(a0,d0,d1,d2)
  100.  The same as before, but here you can decide for which window the requester
  101.  appears.
  102.  
  103.  
  104.  LONG EventAbfrage(struct Window *Window,struct info *msginfo)(a0,a1)
  105.  
  106.  You can use this function instead of GetMsg();ReplyMsg();
  107.  
  108.  
  109.  VOID Print(struct RastPort *RP,
  110.             char *text,
  111.             LONG col,
  112.             LONG xpos,
  113.             LONG ypos)(a1,a0,d0,d1,d2)
  114.  
  115.  Displays a text on the RastPort.
  116.  
  117.  
  118.  VOID Center(struct Window *Window,
  119.              char *text,
  120.              LONG Farbe,
  121.              LONG yPos)(a1,a0,d0,d1)
  122.  
  123.  The same, but here the text is automatically centered.
  124.  
  125.  
  126.  VOID Box(struct RastPort *RP,
  127.           LONG x1,y1,x2,y2)(a1,d0,d1,d2,d3)
  128.  
  129.  Draws a box on the RastPort.
  130.  
  131.  
  132.  VOID Gadget_On (struct Gadget *Gadget,struct Window *Window)(a0,a1)
  133.  VOID Gadget_Off(struct Gadget *Gadget,struct Window *Window)(a0,a1)
  134.  
  135.  These two  functions can be used instead  of GadgetOn/Off (from Intuition.
  136.  library). Gadget_On makes sure that the Gadget is not only active but also
  137.  correctly drawn.
  138.  
  139.  
  140.  LONG GetPropPosH(struct Gadget *Gadget,LONG MaxPos)(a0,d0)
  141.  LONG GetPropPosV(struct Gadget *Gadget,LONG MaxPos)(a0,d0)
  142.  VOID SetPropPosH(      struct Gadget *Gadget,
  143.                                 struct Window *Window,
  144.                         LONG MaxPos,
  145.                                 LONG Step,
  146.                                 LONG NewPos)(a0,a1,d0,d1,d2)
  147.  VOID SetPropPosV(      struct Gadget *Gadget,
  148.                                 struct Window *Window,
  149.                                 LONG MaxPos,
  150.                                 LONG Step,
  151.                                 LONG NewPos)(a0,a1,d0,d1,d2)
  152.  
  153.  These four functions are for easier use of the propgadgets.
  154.  MaxPos: maximum number of positions for this gadget
  155.  Step  : number of positions, the knob moves when clicking in the gadget
  156.  NewPos: the new position.
  157.  
  158.  
  159.  LONG PrepareTmpRas(struct RastPort *RP)(a1)
  160.  VOID ClearTmpRas  (struct RastPort *RP)(a1)
  161.  
  162.  To   prepare  a   RastPort  for  the   use  of   the  Flood-function,  use
  163.  PrepareTmpRas. It returns 0 when there was not enough memory or the TmpRas
  164.  was  already installed. Before  exit, you should call  ClearTmpRas to free
  165.  memory.
  166.  
  167.  
  168.  LONG PrepareArea(struct RastPort *RP,LONG MaxPoints)(a1,d0)
  169.  VOID ClearArea  (struct RastPort *RP)(a1)
  170.  
  171.  The Area-functions  need a bit more  of work. So if you  want to use them,
  172.  call PrepareArea.  Do NOT call PrepareTmpRas first !  This call is part of
  173.  PrepareArea. It returns 0 if it failed. To free memory, call ClearArea.
  174.  
  175.  
  176.  To get simple menus very fast, use the following functions:
  177.  DO NOT USE ANY STATIC MENUS !
  178.  struct Menu *AddMenu(struct Menu *menu,
  179.                       char *Title,
  180.                       unsigned short Flags);
  181.  
  182.  This function  adds a menu to  the list. For the first  call, menu must be
  183.  ZERO ! The  return value of the first call is  the "menu" argument for all
  184.  other calls  to  any of  the  Add..functions  ! So  you  have to  save  it
  185.  somewhere. You do not need the return value of the other calls.
  186.  
  187.  struct Item *AddItem(struct Menu *menu,
  188.                       char *Title,
  189.                       unsigned short Flags,
  190.                       char HotKey);
  191.  
  192.  This  function adds an item  to the last menu  in the list. If  Title is a
  193.  pointer to  char, INTUITEXT  must be  set in  Flags. Otherwise,  Title  is
  194.  interpreted as pointer to a Image-struct and an image is displayed. If you
  195.  want to  use a HotKey, also  COMMSEQ must be set in  Flags. The memory for
  196.  the item (and if needed) the intuitext is allocated. BackPen, FrontPen and
  197.  DrawMode are set by using the values from the first item of the first menu
  198.  (if  there is one).  Otherwise some  standart values are  taken. To change
  199.  e.g. the BackPen, use the following:
  200.  struct Item *item;
  201.  struct IntuiText *IT;
  202.  item=AddItem(menu,"TestItem",INTUITEXT,0);
  203.  IT=(struct IntuiText *)item->ItemFill;
  204.  IT->BackPen=....;
  205.  If this item is the first item  of the first menu, this value will be used
  206.  for all items and subitems.
  207.  THERE  IS NO MEMORY  ALLOCATED FOR THE  STRING, FREEING THE  MEMORY OF THE
  208.  STRING MAY CAUSE A GURU !
  209.  
  210.  
  211.  struct Item *AddSub(struct Menu *menu,
  212.                      char *Title,
  213.                      unsigned short Flags,
  214.                      char HotKey);
  215.  
  216.  Add a subitem to the last defined item.
  217.  
  218.  
  219.  VOID NewSetMenuStrip(struct Window *Window,struct Menu *menu);
  220.  
  221.  To make the menu active, use this command instead of SetMenuStrip();
  222.  
  223.  
  224.  VOID ClearMenu(struct Menu *menu);
  225.  
  226.  To  free  the memory  of  the  menu,  use  this function.  You  MUST  call
  227.  ClearMenuStrip(); first !!!!!
  228.  
  229.  
  230.  struct Menu *LastMenu(struct Menu *menu);
  231.  struct MenuItem *LastItem(struct Menu *menu);
  232.  struct MenuItem *LastSub(struct Menu *menu);
  233.  struct Menu *FreeMenu(struct Menu *menu);
  234.  struct MenuItem *FreeItem(struct MenuItem *item);
  235.  
  236.  These functions are used by the other function. If you need them.......
  237.  
  238.  
  239.  MATHEMATICAL FUNCTIONS
  240.  ======================
  241.  
  242.  VOID UmwFtoS(char *Dest,DOUBLE *Number,LONG Nachkomma)(a0,a1,d0)
  243.  
  244.  Converts a DOUBLE to a string. Example:
  245.  DOUBLE a=5.34524352;
  246.  char string[50];
  247.  UmwFtoS(string,&a,3); -> string: 5.345
  248.  UmwFtoS(string,&a,5); -> string: 5.34524
  249.  
  250.  
  251.  VOID UmwStoF(DOUBLE *Dest,char *Source)(a0,a1)
  252.  
  253.  And vice versa.......
  254.  
  255.  
  256.  VOID Fak(DOUBLE *Dest,LONG a)(a0,d0)
  257.  VOID NuK(DOUBLE *Dest,LONG a,LONG b)(a0,d0,d1)
  258.  
  259.  Fak calculates a!, NuK calculates a!/(b!*(b-a)!)
  260.  
  261.  
  262.  APTR Init_Konst()()
  263.  
  264.  Allocates memory for 26 DOUBLEs.
  265.  
  266.  
  267.  LONG Set_Konst_P(APTR Zeiger,LONG Nummer,DOUBLE *Wert)(a0,d0,d1)
  268.  
  269.  You can set one of these 26 DOUBLE to Wert.
  270.  
  271.  VOID GetKonst_P(DOUBLE *Dest,APTR Zeiger,LONG Nummer)(a0,a1,d1)
  272.  
  273.  And read them again...
  274.  
  275.  VOID Free_Konst(APTR Zeiger)(a0)
  276.  
  277.  To free the memory....
  278.  
  279.  
  280.  struct Block *Init_Mem(char *Zeiger)(a0)
  281.  LONG Init_Block(struct Block *Zeiger)(a0)
  282.  LONG PreCalc(struct Block *Zeiger,APTR Konstanten)(d0,d1)
  283.  LONG Calc_P(DOUBLE *Dest,struct Block *Zeiger,DOUBLE *Wert)(a0,a1,a2)
  284.  VOID Free_Block(struct Block *Zeiger)(a0)
  285.  
  286.  Difficult.  Let's say you have  a string STRING="sin(x)". Now  you want to
  287.  know the "value" of the string for x=3. So:
  288.  
  289.  Call Init_Mem:         Start=Init_Mem(STRING);
  290.  Start should be a pointer to Block.
  291.  
  292.  Then:                          Init_Block(Start);
  293.  After  this, STRING is no  longer used. Init_Mem allocates  the memory for
  294.  the first  "Block"  and  Init_Block calculates  a  tree according  to  the
  295.  function in STRING.
  296.  
  297.  Then:                          PreCalc(Start,Const);
  298.  Const should be the pointer you get from Init_Konst() or NULL;
  299.  To get the value of sin(x) for x=3 :
  300.  
  301.                                 DOUBLE x=3.0,Dest;
  302.                                 Calc_P(&Dest,Start,&x);
  303.  Now  you have  the value in  Dest. If  you now want  to know  the same for
  304.  x=3.1:                         x=3.1;
  305.  
  306.                                 Calc_P(&Dest,Start,&x);
  307.  Easy, isn't it ?
  308.  To free the memory, call Free_Block(Start);
  309.  Three of  these functions  return  a LONG,  it  is an  error code.  It  is
  310.  explained in tool.h.
  311.  
  312.  The  string may  consist of: +-*/^,  e(2.7..), pi(3.14..),  a-z (exept e),
  313.  ((a)sin, (a)cos, (a)tan), log, ln,  abs (Absolut), sgn (sign), int and sqr
  314.  and numbers (1; 1.0; .1;1e5;-3d-5). All characters must be lower case !
  315.  Constants must be set with the _Konst functions. If you change a constant,
  316.  you must call PreCalc again.
  317.  
  318.  
  319.  VOID berechnen(DOUBLE *Dest,char *string,
  320.                 DOUBLE *x,
  321.                 struct Konstanten *konstanten,
  322.                 LONG *fehler)(a0,d0,d1,d2,d3)
  323.  
  324.  If you only  want to calculate one value, use  this function: It needs the
  325.  same  parameters and does  everything that is  needed. But if  you want to
  326.  calculate more values for the same function, the long way is faster.
  327.  
  328.  
  329.  If  you  have  hints,  questions (please  add  postage  for  the  answer),
  330.  bug-reports or money for me, here is my address:
  331.  
  332.                 Rüdiger Dreier
  333.                 Gustav-Winkler Str. 40
  334.          W-4800 Bielefeld 18
  335.                 Germany
  336.  
  337.  
  338.  
  339.  
  340.  
  341.  
  342.  
  343.  
  344.  
  345.  
  346.  
  347.