home *** CD-ROM | disk | FTP | other *** search
/ Programmer 7500 / MAX_PROGRAMMERS.iso / PASCAL / DBRWS102.ZIP / DBROWSE.DOC next >
Encoding:
Text File  |  1992-12-11  |  8.4 KB  |  204 lines
  1. DBrowse UNIT for TurboPower Software OPRO/BTREE users
  2.  
  3.  
  4.         Version 1.02 released on 11 December 1992
  5.  
  6.         Written by a guy named Rob Rosenberger (who?)
  7.                                Barn Owl Software
  8.                                P.O. Box 1115
  9.                                O'Fallon, IL 62269-1115
  10.                                CompuServe 74017,1344
  11.  
  12.  
  13.  
  14. REQUIREMENTS:
  15.  
  16.         Borland BP7 or TP7
  17.         TurboPower BTREE 5.4x
  18.         TurboPower OPRO 1.xx
  19.  
  20.                 TurboPower Software
  21.                 P.O. Box 49009
  22.                 Colorado Springs, CO 80949-9009
  23.                 719-260-6641
  24.                 Compuserve 76004,2611
  25.  
  26.  
  27.  
  28. INTRODUCTION:
  29.  
  30. TurboPower Software's FBROWSE unit combines the functionality of their BTREE
  31. Filer toolkit with their OPRO object-oriented toolkit.  FBrowser, the primary
  32. object descendent of the FBROWSE unit, provides immense power for command-
  33. window based ISAM databases.  FBrowser provides a virtual CharHook() routine
  34. so you can "roll your own" incremental-key function, but FBrowser doesn't
  35. itself implement one for you.
  36.  
  37. DBROWSE offers a descendent object called DataDefBrowser for overriding the
  38. FBrowser CharHook() method.  In effect, this object provides a transparent
  39. incremental key capability for your users.
  40.  
  41. Most people can implement an incremental key function in five easy steps:
  42.  
  43.      1. By default, DataDefBrowser descends from the VBrowser object.  If you
  44.         use FBrowser objects instead, you must disable the {$DEFINE VBROWSER}
  45.         directive near the top of the DBROWSE.PAS file.
  46.      2. Include DBROWSE in your USES statement right after FBROWSE.
  47.      3. Change your objects so they descend from DataDefBrowser rather than
  48.         FBrowser.  (BP7 users would do well to learn how the new "inherited"
  49.         reserved word can make life easier when they change ancestors!)
  50.      4. Include one more variable when you call the InitCustom() constructor.
  51.      5. Recompile your program.
  52.  
  53. Ta da!  You now have an incremtal key function.
  54.  
  55. When you call your object's Process() method, each character you type (known
  56. specifically as a ccChar keystroke in OPRO terminology) winds up in a string
  57. for incremental key searching.  The DataDefBrowser object immediately searches
  58. for the closest matching key compared to this string and sets the highlight
  59. bar on it if found.  If it finds no potential match, it throws out the user's
  60. keystroke and calls the RingBell() method to alert the user.
  61.  
  62. If the user makes a typing mistake, he/she can press the backspace key to
  63. erase the last keystroke.
  64.  
  65. By default, DataDefBrowser uses header index #0, the first wFrame.AddHeader()
  66. command you issue, to display the incremental key string.  You can make it use
  67. a different header index by issuing the following commands:
  68.  
  69.     MyDBrowser.wFrame.AddHeader(...);
  70.     MyDBrowser.dbrHdrIndex := MyDBrowser.wFrame.GetLastHeaderIndex;
  71.  
  72. You can disable header updates by setting dbrHdrIndex to a value of 255 or by
  73. simply not adding any headers to the frame.
  74.  
  75.  
  76.  
  77. TYPES:
  78.  
  79.    KeySeriesSet = SET OF 1..MaxNrOfKeys;
  80.  
  81.         A set of all possible keys available in an FBrowser-derived object.
  82.         The MaxNrOfKeys constant appears in the BTREE FILER unit.  NOTE: the
  83.         TurboPower folks set MaxNrOfKeys to 100 by default but allow values
  84.         as high as 254.  (Caution: earlier BTREE versions let you go as high
  85.         as 750.  DBROWSE cannot cope with more than 255 keys, but this won't
  86.         affect many of you out there.)
  87.  
  88.  
  89.    DataDefBrowserPtr = ^DataDefBrowser;
  90.  
  91.         A pointer to a DataDefBrowser object.
  92.  
  93.  
  94.    DataDefBrowser
  95.         {$IFDEF VBROWSER}
  96.           = OBJECT(VBrowser)
  97.         {$ELSE}
  98.           = OBJECT(FBrowser)
  99.         {$ENDIF}
  100.  
  101.         A DataDefBrowser object.  It descends from the VBrowser or FBrowser
  102.         object depending on the state of the {$DEFINE VBROWSER} directive near
  103.         the top of the DBROWSE.PAS file.
  104.  
  105.  
  106.  
  107. METHODS:
  108.  
  109.    CONSTRUCTOR InitCustom(X1          : BYTE;
  110.                           Y1          : BYTE;
  111.                           X2          : BYTE;
  112.                           Y2          : BYTE;
  113.                       VAR Colors      : ColorSet;
  114.                           Options     : LONGINT;
  115.                           IFBPtr      : IsamFileBlockPtr;
  116.                           KeyNum      : INTEGER;
  117.                       VAR DatS;
  118.                           MaxRows     : BYTE;
  119.                           RowsPerItem : BYTE;
  120.                           MaxCols     : WORD;
  121.                           MaxIncLen   : BYTE;
  122.                           IncrKeys    : KeySeriesSet);
  123.  
  124.         Initializes a DataDefBrowser object.  The first 12 items correspond
  125.         exactly to the FBrowser/VBrowser.InitCustom() constructor.
  126.  
  127.         MaxIncLen dictates the maximum length of an incremental key in the
  128.         DataDefBrowser object.  Many people use the Filer constant MaxKeyLen
  129.         for the length of all text-based keys, but in some cases (like mine)
  130.         you'll need shorter keys.  This controls the length of an incremental
  131.         key string so it doesn't exceed the actual size of the key.
  132.  
  133.         IncrKeys comprises a set of keys where incremental key searching can
  134.         take place.  For example, I use six keys in my database but three of
  135.         them sort on numbers, not text.  I pass along [1,2,5] as my IncrKeys
  136.         since key fields #1, #2, and #5 sort on actual text.
  137.  
  138.         Sample calling syntax:
  139.  
  140.                 IF MyDBrowser.InitCustom(....
  141.                                          .... {same as FBrowser.InitCustom}
  142.                                          ....
  143.                                          MaxKeyLen,
  144.                                          [1,2,5])
  145.                  THEN {everything went okay}
  146.                  ELSE {failed to init the object}
  147.  
  148.  
  149.    PROCEDURE Process; VIRTUAL;
  150.  
  151.         Works exactly like the FBrowser/VBrowser.Process() method, but it does
  152.         some essential things for the DataDefBrowser object.
  153.  
  154.  
  155.    PROCEDURE SetCurrentRecordAndPos(Key     : IsamKeyStr;
  156.                                     Ref     : LONGINT;
  157.                                     ItemPos : BYTE);
  158.  
  159.         Similar to the FBrowser/VBrowser.SetCurrentRecord() function, but it
  160.         positions the current record (and the highlight bar) at ItemPos.  The
  161.         DataDefBrowser.CharHook() method calls on it to constantly position
  162.         the highlight bar in the center of the window.  NOTE: ItemPos has no
  163.         effect if the selected Key/Ref record already appears on the screen.
  164.  
  165.  
  166.  
  167. TECHNICAL NOTES:
  168.  
  169. DBrowse's unit initialization code modifies the FBrowserCommands object so it
  170. recognizes the backspace key as a ccChar command.  This lets DBrowse intercept
  171. it via the CharHook() method so the user can correct any typing mistakes.  If
  172. you Load() FBrowserCommands from disk (like I do) or use an alternate command
  173. processor, you must issue an appropriate call to AddCommand() to change the
  174. backspace to a ccChar.  Look near the bottom of the DBROWSE.PAS file for hints
  175. on how I do it.
  176.  
  177. FBrowse's MaxNrOfKeys constant controls the absolute maximum number of keys
  178. you can assign to any one data file.  TurboPower arbitrarily sets it to 100 to
  179. accomodate most BTREE users.  (You can set it as high as 254 keys if needed.)
  180. I personally recompiled it with MaxNrOfKeys set to 10 in order to reclaim a
  181. few hundred bytes of memory in my programs.
  182.  
  183. The DataDefBrowser object contains a BYTE variable called MaxIncKeyLen so it
  184. knows when to stop accepting keystrokes for an incremental key string.  The
  185. InitCustom() method sets it appropriately.  In my case all text-based keys
  186. work out to the same length, so I never have to worry about MaxIncKeyLen.  If
  187. you use different-length keys, you'll have to implement a method to change the
  188. value in MaxIncKeyLen.  I recommend you go into FBROWSE.PAS and make a single
  189. change to the FBrowser object.  Namely, make SetKeyNumber() a VIRTUAL method
  190. so you can override it with the following descendent method:
  191.  
  192.         PROCEDURE YourDescendentDBrowse.SetKeyNumber(KeyNum : INTEGER);
  193.         BEGIN
  194.         DataDefBrowser.SetKeyNumber(KeyNum);
  195.         CASE KeyNum OF
  196.           1 : MaxIncKeyLen := 20;
  197.           2 : MaxIncKeyLen := MaxKeyLen;
  198.           5 : MaxIncKeyLen := 15
  199.          END {CASE}
  200.         END;
  201.  
  202. Who knows, perhaps TurboPower will take my advice and make it a virtual method
  203. in a future version.  <grin>
  204.