home *** CD-ROM | disk | FTP | other *** search
/ ARM Club 3 / TheARMClub_PDCD3.iso / hensa / programming / lineed_1 / !LineEdit_CompDoc < prev    next >
Encoding:
Text File  |  1990-09-30  |  5.3 KB  |  126 lines
  1. Filename Completion
  2. -------------------
  3.  
  4. Although I don't use this feature in UN*X (I prefer the * wildcard), a few
  5. people have requested a filename completion feature (double-ESCAPE in UNIX's
  6. csh or ksh). Clearly, I can't use ESCAPE for this facility, so I've opted for
  7. a SINGLE PRESS of the Tab key. This allows a filename to be filled in provided
  8. there's a unique match with the substring already typed in.
  9.  
  10. Completion Rules are as follows :-
  11.  
  12. 1) Filename matches are case insensitive, but if a partial string match is
  13.    found then the partial expansion uses the case of the first filename it
  14.    matched (plus a beep to indicate a multiple match).
  15.  
  16. 2) A beep is emitted if there is no match at all.
  17.  
  18. 3) The cursor can be positioned ANYWHERE along the partial filename before
  19.    Tab is pressed...in fact, anywhere along the entire pathname is acceptable
  20.    too.
  21.  
  22. 4) The cursor will be positioned at the end of the filename after expansion.
  23.  
  24. 5) A special parsing rule comes into effect if:
  25.    a) The entire line edit begins with a * (usually a * command) or
  26.    b) The line edit is at the Supervisor * prompt.
  27.  
  28.    The problem is that abbreviated * commands do NOT require a space after
  29.    the full stop. For example, what does "*Acc.Fred" mean ? The Line Editor
  30.    can't tell whether this is (1) a "*Access Fred" or (2) an attempt to
  31.    execute a file called "Fred" inside a directory called "Acc".
  32.  
  33.    To solve this, the special parsing rule will skip past the first full stop
  34.    if it is present when deciding where the filename actually starts. This
  35.    means that you can't expand case (2) above anymore, but that's going to
  36.    happen far less often than the abbreviated * command, so it's worth the
  37.    sacrifice.
  38.  
  39.    If you still want to expand case (2), there are a couple of solutions:
  40.    a) Put a space after the initial * (OS_CLI skips past this).
  41.    b) Enclose the filename in double quotes.
  42.  
  43. Using the Filename Completion Routines in your own code
  44. -------------------------------------------------------
  45.  
  46. I have designed the "Completion" source code to work as independently as
  47. possible from the rest of the code. Despite this, programmers may still need
  48. guidance through the routines contained inside the source:
  49.  
  50. The init_complete routine
  51. -------------------------
  52.  
  53. On entry: No registers required.
  54.  
  55. On exit:  Nothing returned, but [gbpbbuffer] points to claimed space, if any.
  56.  
  57. Action:   Claims RMA space for filenames that will be returned from OS_GBPB.
  58.  
  59. Failure:  If insufficient RMA, a warning will be displayed and the filename
  60.           completion routines will be disabled (they will just beep if called).
  61.  
  62. Call:     Call from the module initialisation code or somewhere in your
  63.           application's startup code.
  64.  
  65. The exit_complete routine
  66. -------------------------
  67.  
  68. On entry: No registers required, but [gbpbbuffer] points to claimed space.
  69.  
  70. On exit:  Nothing returned.
  71.  
  72. Action:   Frees RMA space if it was claimed by init_complete.
  73.  
  74. Failure:  No errors will be returned.
  75.  
  76. Call:     Call from the module finalisation code or somewhere in the
  77.           application's shutdown code.
  78.  
  79. The checkforgos routine
  80. -----------------------
  81.  
  82. On entry: R0 = Pointer to OS_ReadLine buffer (or your own).
  83.           R1 = Maximum length of the buffer.
  84.  
  85. On exit:  R1 = New maximum length of the buffer (also held in [maxlength]).
  86.           [atgosprompt] holds 1 if at a Supervisor prompt, 0 otherwise.
  87.  
  88. Action:   Checks to see if supplied registers point to a Supervisor input
  89.           buffer. This is used as a special check during filename parsing
  90.           (see documentation). It also reduces the maximum buffer length
  91.           by one if it detects Gos 1.20 (fixes a bug).
  92.  
  93. Failure:  No errors will be returned.
  94.  
  95. Call:     Every time the address of the input buffer changes, this routine
  96.           should be called. For OS_ReadLine buffers, it should be called
  97.           upon entry to your OS_ReadLine replacement routine.
  98.  
  99. The complete_name routine
  100. -------------------------
  101.  
  102. On entry: R0 = Pointer to OS_ReadLine buffer (or your own).
  103.           R1 = Offset of cursor on line (0 = start).
  104.           R2 = Current length of line.
  105.  
  106. On exit:  No registers returned, but in the following locations instead:
  107.           [pendingright]  = Number of right arrows pending buffer insertion.
  108.           [overflag]      = Set to 0 to indicate a switch to Insert mode.
  109.           Keyboard buffer = Enough DELETEs (127) to erase partial filename and
  110.                             add the new (partially ?) completed filename.
  111.  
  112. Action:   Expands the partial filename located in the vicinity of the cursor
  113.           if possible. Because ASCII 137 (right arrow) cannot be forced into
  114.           the keyboard, the number of right arrows required is left in a
  115.           memory location to be picked up before INKEY(0) is scanned. In other
  116.           words, the insertion is 'faked' and a counter is decremented until
  117.           they are all used up, at which point normal keyboard scanning is
  118.           resumed. CHECK THE MAIN SOURCE FILE TO SEE HOW I DID THIS, YOU WILL
  119.           NEED TO IMPLEMENT SOMETHING SIMILAR.
  120.  
  121. Failure:  If a unique match is not found, a beep is sounded.
  122.  
  123. Call:     Set up the registers correctly and call when required (e.g. when
  124.           Tab is pressed). Will not work unless init_complete has already
  125.           been called when the module/application was initialised.
  126.