home *** CD-ROM | disk | FTP | other *** search
/ Club Amiga de Montreal - CAM / CAM_CD_1.iso / files / 037.lha / conman.doc < prev    next >
Text File  |  1987-05-17  |  12KB  |  222 lines
  1. ==========================================================================
  2.                              ConMan V0.98B
  3.                    Copyright 1987 by William S. Hawes
  4. ==========================================================================
  5.  
  6. ConMan is a replacement console handler that provides line editing and
  7. command line histories.  It runs under AmigaDOS (V1.1 or V1.2) and is
  8. completely transparent to any application program that uses CON: windows.
  9. Version V0.98B also provides support for RAW: windows.
  10.  
  11. Once installed, any windows opened by AmigaDOS will automatically open
  12. using the ConMan handler.  This includes command windows opened by NEWCLI
  13. as well as any data input/output windows that your program uses.
  14.  
  15. Features new to this version (0.98B) include two new line-editing options 
  16. (CTRL-R and CTRL-Z), default function key assignments to shrink and "zoom" 
  17. windows and "dip" the screen, provisions to display and pass through all
  18. control keys not used for editing, and procedural support for function-key
  19. interrupts.  Several minor bugs have been removed (and alas, probably a
  20. few added.)  Support has also been included for several additional DOS
  21. packet types.
  22.  
  23.  
  24. Line Editing.
  25. The active (command) line may be edited using the arrow keys for cursor
  26. positioning and the DELETE and BACKSPACE keys in the usual manner.  The
  27. shifted left- and right-arrow keys skip to the beginning or ending of a word,
  28. respectively; this is slightly different from their actions in the previous
  29. release, in which they skipped to the beginning or ending of the line.
  30.  
  31. ConMan provides both insert and overstrike input modes, which may be
  32. toggled by a CTRL-A.  The default mode inserts characters at the cursor.
  33. CTRL-X deletes the entire line, while CTRL-Y deletes from the cursor position 
  34. to the end of the line.  CTRL-Z deletes both the current line and any lines 
  35. that have been entered (but not yet read); this is very handy if you want to
  36. completely abandon your previous course of action.  A less drastic recall 
  37. is provided by CTRL-R, which removes entered lines one at a time and posts
  38. them back to the command line.
  39.  
  40. One other control character is recognized:  CTRL-\ sends an end-of-file
  41. (a zero-length block) to the task reading from the handler.
  42.  
  43. All characters not explicitly required for editing purposes are passed on
  44. to the command line.  In order to provide a consistent display, characters
  45. that might cause interference with the display (e.g. CTRL-L) are displayed
  46. as a caret followed by an uppercase alphabetic.  Miscellaneous non-printable
  47. characters are displayed as a hash mark.
  48.  
  49.  
  50. Command History.
  51. Previously-entered lines may be recalled with the up-arrow key.  Lines are
  52. retrieved sequentially; if you go past the one you want, the down-arrow key
  53. will back up one.  The shift up-arrow key recalls the oldest line, and 
  54. shift down-arrow recalls the most recent line.
  55.  
  56. The annoying memory-allocation habits of the history buffer have been tamed
  57. in this release.  Rather than giving you a fixed number of history lines
  58. and then allocating memory as required, ConMan now allocates a "pool" for
  59. history lines and then packs in as many strings as will fit.  The default
  60. size is 488 bytes, which should suffice for 20-30 average lines.  This may
  61. be changed by modifiying a field in the library structure, but let me know 
  62. if this is too small (or too big; we don't want to waste memory.)
  63.  
  64.  
  65. Function Keys.
  66. Four function keys have been assigned default actions.  F1 shrinks the 
  67. window to its minimum size, while F2 "zooms" the window to its maximum
  68. size (usually the entire screen.)  Both keys act as "toggles", and shrunken
  69. windows may be zoomed (and vice-versa.)  Key F9 "dips" the screen to 3/4
  70. of the display height, and should be useful if you're working with multiple
  71. screens and need to peek at the one in back.  F10 rearranges a window from
  72. front-to-back, and will act as a toggle provided that you don't deactivate 
  73. the window.
  74.  
  75.  
  76. Window Definition.
  77. ConMan supports the usual DOS window specification string.  For example,
  78. "CON:160/50/320/100/MyWindow" specifies a window 320x100 pixels in size,
  79. beginning in position (160,50).  The numeric parameters are truncated
  80. against the maximum screen size, so a larger-than-normal window may be
  81. safely specified (for those of you using "morerows").  The default size
  82. is the full screen width and height.
  83.  
  84. ConMan also accepts a specification in the form "CON:w20480", where the 
  85. hex digits following the "w" are the absolute address of an Intuition 
  86. window pointer.  If you're writing in 'C', the following sequence would 
  87. serve to open a window and attach a DOS console to it:
  88.  
  89.       window = OpenWindow(&newwindow);   /* get a window          */
  90.       sprintf(buffer,"CON:X%x",window);  /* build the name string */
  91.       file  = Open(buffer,MODE_OLDFILE); /* open a console stream */ 
  92.  
  93. Windows may be opened on a custom screen by including the screen pointer
  94. in the specification string, as in CON:s123abc/10/10/300/100/MyWindow.
  95.  
  96. Various Intuition options and gadgets may be selected by including a list
  97. of attributes after the window title.  Here's how it works:  Put another 
  98. slash ('/') after the window title, and follow it with any of the attribute 
  99. options below:
  100.    A ==> Activate             (def: no activate)
  101.    B ==> BackDrop             (def: not BackDrop)
  102.    C ==> Close gadget         (def: no gadget) (action not implemented)
  103.    D ==> Depth gadget         (def: depth gadget)
  104.    M ==> Move (drag) gadget   (def: drag gadget)
  105.    N ==> NoBorder             (def: border) (sorry, 'B' was used)
  106.    R ==> Refresh mode         (def: SMART_REFRESH)
  107.    S ==> Sizing gadget        (def: sizing gadget)
  108.    Z ==> Zero-Zero            (def: not GZZ)
  109.  
  110. Each attribute serves to TOGGLE the corresponding windows flag, so adding
  111. it twice will cancel the effect.  A closing slash is optional.  For those
  112. of you who wanted a slash in your titles:  sorry.
  113.  
  114. Example: CON:10/10/300/100/Behind/nb/  creates a borderless backdrop window.
  115.          CON:10/10/300/100/Fixed/acm   creates an active window, with a
  116.                                        close gadget, that won't budge.
  117.  
  118. Installation.
  119. ConMan requires that two files be copied to your SYS: disk (don't worry,
  120. they're both small.)  "My-Handler" (184 bytes) must be placed in
  121. the SYS:L directory, to keep all those bigger handlers company.  The
  122. file "conhandler.library" (5592 bytes) must be placed in the your LIBS:
  123. directory, which is normally SYS:LIBS.  The ARCed files have shortened 
  124. names, so be sure to rename "conlib.lib" and "myhandlr."  A simple "install" 
  125. script is included to copy the files.
  126.  
  127. Once these files are present, execute ConMan (956 bytes) to install the 
  128. handler.  This file only needs to be run once (e.g. from your 
  129. startup-sequence); it allocates 20 bytes of memory for the handler name 
  130. string which won't be returned (there is no provision in DOS for removing
  131. a handler, anyway.)  ConMan accepts three command-line arguments:  -c
  132. (the default) patches the CON: node, -r patches the RAW: node, and -q
  133. ("quickly") writes the startup message to the standard output stream 
  134. instead of opening a window (and delaying so you can read it.)
  135. Example:  conman -c -q
  136.  
  137. Distribution.
  138. This program is to be distributed as shareware to Amigoid life-forms 
  139. everywhere!  Make sure your friends get a copy.  Comments and contributions
  140. will be appreciated and may be sent to:
  141.  
  142.       William S. Hawes        (bix: whawes)
  143.       P.O. Box 308
  144.       Maynard, MA 01754
  145.       (617) 568-8695
  146.  
  147. Additional documentation and the assembler source code will be available
  148. in the near future.  
  149.  
  150. I will be other releasing other Amiga products, both through shareware and 
  151. normal commercial channels.  Watch for:
  152.     ARexx ... the REXX language for the Amiga (June, 1987)
  153.     Mini-Shell ... just enough DOS (August, 1987)  
  154.  
  155.  
  156. Further Notes.
  157. This is the last Beta version before the "final" (is anything ever final?)
  158. release of ConMan.  Some debugging code still remains here.  Function key 
  159. F5 toggles a flag that causes a DisplayBeep everytime a "WaitForChar" 
  160. packet is dispatched.  Most programs will not use the "WaitForChar" function,
  161. since a Read to the CON: device will block until characters are available
  162. anyway.  F5 toggles a flag that DisplayBeeps whenever a "break" signal is
  163. passed on (i.e. is applied to your hapless task).  Also, an extraneous
  164. message port (called 'MyCon') will appear in the Ports list.  These testing
  165. features will go away RSN.
  166.  
  167. The program was developed and tested under V1.2; at least one V1.1
  168. dependency was found and fixed (DoIO to the console device scratched D7).
  169. Let me know if other problems exist.  I spent a lot of time making it
  170. work using the DOS handler-loading mechanism so that it would be backwards
  171. compatible.
  172.  
  173. A passing note:  The interaction of the "shrink" and "zoom" keys proved
  174. to be a little trickier than it first appeared; I ended up spending the 
  175. better part of a day finding state transitions that seemed intuitive.  
  176. Anyone who doesn't like the current implementation is invited to submit a 
  177. state diagram with the desired transitions ...
  178.  
  179. One warning with regard to the "shrink" and "zoom":  rapid toggling between
  180. window states will crash the machine.  It seems that Intuition provides no
  181. way to indicate whether a "sizing" or "moving" request is pending, so the
  182. dimensions read from the window structure may not be consistent with the
  183. actual size when the operation is performed.  I'm currently looking for a 
  184. reasonable work-around before adopting an ugly kludge.  Until then, take
  185. it easy on the keys, OK?
  186.  
  187. Function Key Interrupts.
  188. One major addition to this version is the support for function-key interrupts.
  189. The ConHandler library provides functions for maintaining a push-down stack
  190. of function-key contexts.  Whenever a function key event (or more generally, 
  191. any raw event) occurs, the console handler first calls the user-supplied 
  192. function at the top of the context stack.  Your function is free to "eat" 
  193. the event, change it to something else, or take any other action.  Some  
  194. restrictions apply (after all, these are asynchronous events), but this 
  195. should allow for some interesting programming.  A separate program called
  196. "SideShow" has been included as an example of function-key processing.
  197. The full source code to "SideShow" is available for programmers interested
  198. in using the interrupt facilities.  All you programmers: try this stuff
  199. out, as I'm interested in feedback on it!
  200.  
  201. The remaining areas of development include:
  202.    -- Does anyone want to pass in a Super-Bitmap pointer?  If so, suggest
  203.       a reasonable syntax that doesn't clash with the conventions already 
  204.       in place.
  205.  
  206.    -- Has anyone tried the method of passing the window pointer to the 
  207.       handler as shown in Andy Finkel's Window example?  It should work, 
  208.       but I haven't had a chance to try it.
  209.  
  210.    -- This version has most of the machinery in place to act as a "pipe".
  211.       A few open questions need to be resolved, such as whether the pipe
  212.       should "reblock" the input or dole it out in the same size chunks
  213.       that it came in.  In addition, it might be interesting to allow the
  214.       handler to be opened as a console and then switched into a pipe ...
  215.       allowing the output to be displayed as well as passed through.  Any
  216.       comments in this vein (pipe?) would be welcome.
  217.  
  218. Special thanks to John Toebes and the Software Distillery for all the great 
  219. suggestions, and to everyone who called in with comments or contributions.
  220.  
  221.                                       WSH (05/10/87)
  222.