/*

   Filename:   rmSigBox.cc
   Version:    1.01
   Date:       2005/01/17

   For:        dBASE PLUS / dB2K / Visual dBase 7.** 
               Windows 95/98/ME/XP/NT/2000

   Author:     Ronnie MacGregor
   Contact:    SigBoxFeedback@dBASEDeveloper.com
	
   
   Description:

      A Custom Control for the capture of a signature. Designed for use with
      a tablet PC, but works with a drawing tablet or mouse where the only
      difference is the lack of ability to have a break between pen strokes.

      The signature is stored as an emf file in the bin field of a datalinked
      dBASE table.

      From the table the signature can be displayed again in the rmSigBox
      control or if display only is desired, then the rmSigImage control can be
      used.

      The control has the built in ability to inject the signature into a Word
      document.


   Revisions:

      2005 02 05 Version 1.01 /////////////////////////////////////////////////

      Actual drawing of the signature now uses PolyLine instead of LineTo.
      This allows for faster redraws, and gives a smoother appearance especially
      if the image is scaled up.

   
   Methods:

.     function SetDatalink(oDLink)

      This method must be called in order to establish a datalink for the
      control. A reference to the field object concerned must be passed.
      Best done from the onOpen of the control instantiation code as follows :

         this.SIGBOX1 = new RMSIGBOX(this)
         with (this.SIGBOX1)
            onOpen = {; this.SetDatalink(form.q.rowset.fields["Signature"])}
            left = 10
            top = 100
         endwith

      This method also creates an object reference to itself in a custom array
      of the datalinked rowset in preparation for notification of rowset events
      to the control.


.     function onAbandon()
.     function onAppend()
.     function onDelete()
.     function onEdit()
.     function onNavigate()
.     function onSave()

      All of these methods must be fired by the appropriate rowset events.
      This is easy to achieve from form code because each instance of a
      rmCustomControl which is datalinked will add itself to a custom rowset
      array of object references. These references can then be used as follows.

      Sample form rowset_onNavigate code :

         function rowset_onNavigate()
            oRowset = this
            this.parent.parent.RowsetEvent(oRowset, "onNavigate")
         return

      Sample single rowset event function to handle all rowset events :

         function RowsetEvent(oRowset, cEvent)
            // Fire the rowset events for any rmCCs
            try
               for nCount = 1 to oRowset.rmCCArray.size
                  do case
                     case cEvent == "onAbandon"
                        oRowset.rmCCArray[nCount].onAbandon()
                     case cEvent == "onEdit"
                        oRowset.rmCCArray[nCount].onEdit()
                     case cEvent == "onNavigate"
                        oRowset.rmCCArray[nCount].onNavigate()
                     case cEvent == "onSave"
                        oRowset.rmCCArray[nCount].onSave()
                     case cEvent == "onDelete"
                        oRowset.rmCCArray[nCount].onDelete()
                     case cEvent == "onAppend"
                        oRowset.rmCCArray[nCount].onAppend()
                  endcase
               endfor
            catch(exception e)
               // array doesn't exist 
            endtry
         return


.     function SigToWord(oWord)

      This function can be called from anywhere in an OleAutoClient code session
      to inject a signature into the document. An object reference to the Word
      OleAutoClient must be passed, as in this sample line of code :

         form.SigBox1.SigToWord(oWord)


.     function SaveEMF(cName)

      This function can be used to create a disk file in emf format of the
      signature which has just been captured, and is available until the next
      capture is initiated.

      If you want to create a disk file in emf format for a signature stored
      in a table, use the CopyToFile method of the Field object.


         mySigField.copyToFile(cFile)


.     function onClose()

      This function should be called from the onCLose of your form in order to
      ensure that the control's clean up code is run. Unfortunately there is a
      dBASE bug which prevents this being automated. The onClose event of a
      PaintBox does not fire if the PaintBox is in a container.


               
   Properties:

      this.SignGuide = true // Boolean

         Whether a signature boundry guide box is displayed during signature
         entry mode. 

                
      this.SignGuideColour = "C0C0C0" // Six char hex string

         The colour of the signature boundry guide box.

 
      this.BackgroundColour = "FFFFFF" // Six char hex string

         The background colour for the emf signature file.


      this.PenColour = "000000" // Six char hex string

         The colour of ink used for the signature.


      this.PenWidth = 3 // Integer

         The width of the line drawn by the pen. Best results with 2 or 3  
          

      this.Latency = 0.25 // Decimal seconds

         The delay between movement detected on the signature area, and the
         start of actual drawing. 
                 

      this.PauseLimit = 4 // Integer multiple of 0.125 of a second.

         The maximum pause in drawing movement before the control assumes
         completion.


      this.RepaintInterval = 0.01 // Decimal seconds

         The interval between repaints while the signature is being drawn.


   Dependancies:

      None.


   Acknowledgements:

      None.

         
*/