home *** CD-ROM | disk | FTP | other *** search
/ Programmer 7500 / MAX_PROGRAMMERS.iso / PASCAL / BININT.ZIP / BININT.DOC next >
Encoding:
Text File  |  1988-10-23  |  8.7 KB  |  187 lines
  1.                                 BININT
  2.           Accessing BINED Internal Information in Event Handlers
  3.                              Version 1.0
  4.                              Kim Kokkonen
  5.  
  6. Overview
  7. ------------------------------------------------------------------------------
  8. BININT is a small unit that may be used in programs based on the binary
  9. editor, BINED, from Borland's Editor Toolbox. It removes a drawback of BINED,
  10. which is that accurate information about the cursor position (within the
  11. current line and text buffer) is not available to event handlers. As such,
  12. event handlers are limited in what they can do.
  13.  
  14. When accurate information is available to a BINED event handler, new
  15. horizons open up for using the binary editor. We developed this unit in
  16. order to add limited mouse support to BINED, which required knowing the
  17. cursor position relative to the overall file size. Another popular request
  18. is to add word-wrap to BINED -- knowing the information provided by BININT, an
  19. event handler could be written to add word wrap.
  20.  
  21. BININT is a dirty little unit, peeking into the BINED code segment to read
  22. certain offsets of data items that it needs to compute accurate information
  23. for use by an event handler. Even so, BININT is very careful to assure that
  24. the information it uses is correct. If BININT can't find the appropriate
  25. offsets, it will fail gracefully, but in this case an event handler won't
  26. have the information it needs. So far this isn't much of a concern since to
  27. our knowledge Borland has released only a single version of BINED. BININT is
  28. designed to adjust itself automatically whenever possible, even if BINED is
  29. changed in the future.
  30.  
  31. In the following, we assume you know what is meant by a BINED "event handler".
  32. See Borland's documentation, or the supplied example TEST.PAS, for background.
  33.  
  34.  
  35. Using BININT
  36. ------------------------------------------------------------------------------
  37. Just add BININT to your USES list, after BINED itself. (BININT depends on
  38. BINED.) Then your application can call any of the following procedures and
  39. functions.
  40.  
  41. procedure FindInternals(EdData : EdCB; var E : EdIntRec);
  42.  
  43.   Call FindInternals any time after calling Borland's InitBinaryEditor
  44.   routine, but before calling UseBinaryEditor. This routine initializes the
  45.   record parameter E to hold information needed to track the specified edit
  46.   window EdData. The program must declare a global variable of type EdIntRec
  47.   to store the binary editor internals information for use by the event
  48.   handler. Note that you will need a separate EdIntRec variable for each
  49.   BINED edit window.
  50.  
  51.   If for some reason BININT cannot find the appropriate locations in BINED, it
  52.   will return all fields of the EdIntRec set to zero. This may be considered
  53.   a critical error for any program using BININT even though the rest of
  54.   BININT's functions are designed to return safe values in this case. You can
  55.   test for correct operation of FindInternals with the following statement:
  56.  
  57.     if E.EditSeg = 0 then
  58.       {Critical error, unknown BINED version} ;
  59.  
  60. The remaining BININT functions are intended for use within an event handler.
  61. Each of them requires a parameter of type EdIntRec, previously initialized by
  62. a call to FindInternals.
  63.  
  64. function CurrLineOfs(var E : EdIntRec) : Word;
  65.  
  66.   This routine returns the byte offset within BinEd's text buffer of the first
  67.   character on the current line. For example, if the cursor is on the first
  68.   line of a text file, CurrLineOfs will return 0. If the first line has 10
  69.   characters (counting CR and LF), then CurrLineOfs will return 10 when the
  70.   cursor is on the second line of the file. When the cursor is moved to the
  71.   end of the file, CurrLineOfs returns the same value as EdData.EOtext. If the
  72.   EdIntRec was not correctly initialized, CurrLineOfs returns $FFFF.
  73.  
  74.   Note that CurrLineOfs does not vary when the cursor is moved within a given
  75.   line. The LinePos function provides that information.
  76.  
  77. function CurrChar(var E : EdIntRec) : Char;
  78.  
  79.   CurrChar returns the ASCII character associated with the current cursor
  80.   position in the file. If the cursor is beyond the end of the current line,
  81.   CurrChar returns a blank (#32). CurrChar will not return a CR (#13), LF
  82.   (#10), or EOF (#26) unless the text file is corrupt. If the EdIntRec was not
  83.   correctly initialized, CurrChar returns #255.
  84.  
  85. function LinePos(var E : EdIntRec) : Byte;
  86.  
  87.   LinePos returns the position of the cursor in the current line. It returns 1
  88.   for the first character in the line. The highest value normally returned
  89.   will be 249. If the EdIntRec was not correctly initialized, LinePos returns
  90.   255.
  91.  
  92.   Note that you can't add LinePos to CurrLineOfs and obtain an offset that
  93.   means anything. BINED copies the current line to a separate buffer for
  94.   editing and recopies it to the main text buffer only when the cursor leaves
  95.   the line. Hence, the contents of the text buffer beyond CurrLineOfs are not
  96.   guaranteed to be up to date. Use the CurrLine function to get the contents
  97.   of the current text line.
  98.  
  99. function LineLen(var E : EdIntRec) : Byte;
  100.  
  101.   Returns the length of the current line. The length is defined as the number
  102.   of characters up to and including the last non-blank character in the line.
  103.   Note that the cursor is allowed to move beyond this position, and thus you
  104.   will have situations where LinePos > LineLen. If the EdIntRec was not
  105.   correctly initialized, LineLen returns 255.
  106.  
  107. function CurrLine(var E : EdIntRec) : string;
  108.  
  109.   Returns the current text line as a string. There's no need to call LineLen
  110.   if you call CurrLine since the length of the returned string equals LineLen.
  111.   If the EdIntRec was not correctly initialized, CurrLine returns an empty
  112.   string.
  113.  
  114. function EditOptions(var E : EdIntRec) : Byte;
  115.  
  116.   Returns the current value of the editor options (which may have been changed
  117.   by the user since the edit session started). See the constants near the top
  118.   of BINED.PAS (EdOptInsert and so on) for masks to decode this bit-mapped
  119.   byte.
  120.  
  121. Note that BININT is not designed to let you _modify_ any of the data that it
  122. provides. Within an event handler, it is not safe to change the cursor
  123. position, or directly modify the line buffer.
  124.  
  125. If modification of the text stream is desired (as would be the case when
  126. adding word wrap to BINED), the appropriate action is to poke characters into
  127. the keyboard buffer. For this reason, BININT provides two more procedures:
  128.  
  129. procedure ClearKbd(var E : EdIntRec);
  130.  
  131.   Before poking a character, it is best to call this routine. ClearKbd clears
  132.   not only the BIOS keyboard buffer, but also an internal single byte buffer
  133.   used by BINED to hold extended keystrokes.
  134.  
  135. procedure StuffKey(W : Word);
  136.  
  137.   This stuffs one character (ASCII value with scan code) into the keyboard
  138.   buffer. If the character is not extended (like <F1> or <Left>) it is alright
  139.   to call StuffKey as follows:
  140.  
  141.     StuffKey(Ord(CharToStuff));
  142.  
  143.   For example
  144.  
  145.     StuffKey(Ord(^M));
  146.  
  147.   puts a carriage return into the keyboard buffer, to be acted upon by BINED
  148.   when the event handler returns.
  149.  
  150.   For an extended character, pass the appropriate word value. For example
  151.  
  152.     StuffKey($4B00);
  153.  
  154.   stuffs a <Left> arrow into the keyboard buffer.
  155.  
  156.   Remember that the keyboard buffer normally holds only 16 characters. If the
  157.   buffer is full when StuffKey is called, it does nothing.
  158.  
  159.  
  160. Examples
  161. ------------------------------------------------------------------------------
  162. The supplied program TEST1.PAS is a tiny example of using BININT. It allows
  163. you to browse through a file while continuously showing a status report of the
  164. information offered by BININT. Just compile TEST1.PAS and run it by specifying
  165. a text file to browse on the command line:
  166.  
  167.    TEST1 FileToBrowse
  168.  
  169. Press ^KD to quit. No changes will be saved.
  170.  
  171. TEST2 is a frivolous example of modifying the text stream by stuffing
  172. characters into the keyboard buffer. Compile and run it just like TEST1. In
  173. TEST2, whenever the cursor is positioned over a space within a text line, the
  174. event handler breaks the text onto the next line, leading to a
  175. semi-interactive "one word per line" filter. If the editor is in overwrite
  176. mode, the event handler does nothing. Like TEST1, TEST2 does not allow you to
  177. save the resulting file.
  178.  
  179.  
  180. Disclaimer
  181. ------------------------------------------------------------------------------
  182. The BININT unit was written by Kim Kokkonen of TurboPower Software. It is
  183. hereby released to the public domain. We accept no liability for the use of
  184. this software, and make no guarantees as to its performance. Good luck! We'd
  185. like to hear from the first person to develop a word-wrapping event handler
  186. for BINED.
  187.