CALCULATOR()
 On-screen Full-Function Calculator
------------------------------------------------------------------------------

 Syntax

    CALCULATOR( [<nInitialValue>,] [<lAutoGrabAndPaste>] )  -> nResult

 Arguments

    <nInitialValue> is a numeric value which becomes the initial value
      to display in the calculator.
      Defaults to zero, unless called from a READMODAL numeric variable.

    <lAutoGrabAndPaste> is a logical value; if set to true, will attempt
      to grab from a numeric variable (if called from one) and will paste
      if exited by pressing Ctrl-Enter.  If, however, you have reason to
      prevent the numeric grabbing and the paste-back, set it to false.
      Defaults to whether (1) called from a numeric variable or (2) a numeric
      value was passed in <nInitialValue>.

 Returns

      A numeric result of the calculations.  If the user presses Ctrl-Enter
      to exit the Calculator, the keyboard will also be stuffed with the
      result.

 Description

      At its most basic use (SET KEY ... TO CALCULATOR) the calculator
      will pop up on screen (with a numeric if called from a get) allowing
      calculations, percentages, parenthesized calculations, memory (static),
      printing, fixed decimals, and a help screen.  When pressing
      Ctrl-Enter to exit, it will paste the result to your variable.

      In its more advanced use, you may set keys to do your own special
      functions and calculations (SET KEY K_F9 TO FINANCIAL), or train
      the calculator to search for and change to a separate color scheme,
      or call a special procedure before entering the calculator, or
      call the calculator as a function and return the result.

 Requirements

      You must call CalcReg( <nRegistration> ) to bypass the copyright screen.
      SEE CALCREG()

 Examples

   ** Example 1

      #include "inkey.ch"

      CalcReg(12345)                 // example registration number
      Set Key K_ALT_O to Calculator

      n1:=5
      c1:=Space(8)

      @ 5,5 Get n1
      @ 6,5 Get c1
      READ                            // press ALT_O for calculator

     -----------------------------------------------------------------------

   ** Example 2

      #include "inkey.ch"

      CalcReg(12345)

    // F5 will multiply n by 2 and return it (from calculator)
      SetKey(K_F5,{|p,l,v,n| If( p="CALCULATOR", n*2, NIL ) })

    // F6 will automatically keyboard any character returns,
    //  in this case, setting fixed decimals to 2
      SetKey(K_F6,{|p| If( p="CALCULATOR", "F2", NIL) })

    // F1 will call the calculator's help
      SetKey(K_F1,{|p| If( p="CALCULATOR", "H", NIL) })

      nResult := Calculator(5)        // pops up with a 5, returns a result


 Notes  (FOR ADVANCED USE)

      SETKEY PROCEDURES

         When it calls your set key procedure, it will pass five parameters:

         . Procedure name (always CALCULATOR)
         . Version number (always 16 in version 1.6)
         . The variable name when the Calculator hotkey was pressed or NIL
         . Numeric representation of the current display
         . Character representation of the current display

         When you return a result, it may be numeric, character, or other:

         . If you return a numeric, it will become the current display

         . If you return a character, it will be "keyboarded" as if the
           user typed it himself (be aware of your current SET TYPEAHEAD)

         . If you return any other value, it will be ignored

 Keys Available:

           KEY    OPERATION

         .  0-9   (standard numeric keys)
         .  +,-,/,*  (standard arithmetic keys)
         .  %     Perform percentage calculation
         .  (     Begin a sub-calculation (may be nested)
         .  )     End a sub-calculation
         .  =     End a calculation (and all sub-calculations)
         .[Enter] End a calculation (and all sub-calculations)
         .[Bksp]  backup, erase last keystroke
         .  AC    Clear all (except memory)
         .  C     Clear Entry
         .  H     Display calculator help.
         .  P     Toggle printing; if printing is used, upon exit of the
                  calculator, a form feed will occur.
         .  F n   Set fixed decimals to (n).  0-9 to fix, other key for
                  floating point.
         .  M+    Add to memory  (static - will keep throughout program)
         .  M-    Subtract from memory
         .  M*    Multiply to memory
         .  M/    Divide into memory
         .  MR    Recall memory
         .  MC    Clear memory
         . [Ctrl-Left / Ctrl-Right] Move Calculator

         . [Esc]  Exit calculator (do not paste)
         . [Ctrl-Enter]   Exit calculator (PASTE RESULT TO FIELD)
                          (applicable when called from a variable, or
                           when first parameter is numeric and second
                           parameter is true)

 Files: CALC.LIB

 Author: Touchstone Business Creations          CompuServe ID: 73670,2561
         28613 River Glen Ct. #1
         Menifee, CA 92584-8987 USA

         (909) 679-3364

 Owner : (c) Copyright, 1991,92,93 Touchstone Business Creations.