Club Amiga de Montreal - CAM/CAM_CD_1.iso/files/037.lha/conman.doc

Text File | 1987-05-17 | 11.3 KB | 222 lines

==========================================================================
                             ConMan V0.98B
                   Copyright 1987 by William S. Hawes
==========================================================================

ConMan is a replacement console handler that provides line editing and
command line histories.  It runs under AmigaDOS (V1.1 or V1.2) and is
completely transparent to any application program that uses CON: windows.
Version V0.98B also provides support for RAW: windows.

Once installed, any windows opened by AmigaDOS will automatically open
using the ConMan handler.  This includes command windows opened by NEWCLI
as well as any data input/output windows that your program uses.

Features new to this version (0.98B) include two new line-editing options
(CTRL-R and CTRL-Z), default function key assignments to shrink and "zoom"
windows and "dip" the screen, provisions to display and pass through all
control keys not used for editing, and procedural support for function-key
interrupts.  Several minor bugs have been removed (and alas, probably a
few added.)  Support has also been included for several additional DOS
packet types.


Line Editing.
The active (command) line may be edited using the arrow keys for cursor
positioning and the DELETE and BACKSPACE keys in the usual manner.  The
shifted left- and right-arrow keys skip to the beginning or ending of a word,
respectively; this is slightly different from their actions in the previous
release, in which they skipped to the beginning or ending of the line.

ConMan provides both insert and overstrike input modes, which may be
toggled by a CTRL-A.  The default mode inserts characters at the cursor.
CTRL-X deletes the entire line, while CTRL-Y deletes from the cursor position
to the end of the line.  CTRL-Z deletes both the current line and any lines
that have been entered (but not yet read); this is very handy if you want to
completely abandon your previous course of action.  A less drastic recall
is provided by CTRL-R, which removes entered lines one at a time and posts
them back to the command line.

One other control character is recognized:  CTRL-\ sends an end-of-file
(a zero-length block) to the task reading from the handler.

All characters not explicitly required for editing purposes are passed on
to the command line.  In order to provide a consistent display, characters
that might cause interference with the display (e.g. CTRL-L) are displayed
as a caret followed by an uppercase alphabetic.  Miscellaneous non-printable
characters are displayed as a hash mark.


Command History.
Previously-entered lines may be recalled with the up-arrow key.  Lines are
retrieved sequentially; if you go past the one you want, the down-arrow key
will back up one.  The shift up-arrow key recalls the oldest line, and
shift down-arrow recalls the most recent line.

The annoying memory-allocation habits of the history buffer have been tamed
in this release.  Rather than giving you a fixed number of history lines
and then allocating memory as required, ConMan now allocates a "pool" for
history lines and then packs in as many strings as will fit.  The default
size is 488 bytes, which should suffice for 20-30 average lines.  This may
be changed by modifiying a field in the library structure, but let me know
if this is too small (or too big; we don't want to waste memory.)


Function Keys.
Four function keys have been assigned default actions.  F1 shrinks the
window to its minimum size, while F2 "zooms" the window to its maximum
size (usually the entire screen.)  Both keys act as "toggles", and shrunken
windows may be zoomed (and vice-versa.)  Key F9 "dips" the screen to 3/4
of the display height, and should be useful if you're working with multiple
screens and need to peek at the one in back.  F10 rearranges a window from
front-to-back, and will act as a toggle provided that you don't deactivate
the window.


Window Definition.
ConMan supports the usual DOS window specification string.  For example,
"CON:160/50/320/100/MyWindow" specifies a window 320x100 pixels in size,
beginning in position (160,50).  The numeric parameters are truncated
against the maximum screen size, so a larger-than-normal window may be
safely specified (for those of you using "morerows").  The default size
is the full screen width and height.

ConMan also accepts a specification in the form "CON:w20480", where the
hex digits following the "w" are the absolute address of an Intuition
window pointer.  If you're writing in 'C', the following sequence would
serve to open a window and attach a DOS console to it:

      window = OpenWindow(&newwindow);   /* get a window          */
      sprintf(buffer,"CON:X%x",window);  /* build the name string */
      file  = Open(buffer,MODE_OLDFILE); /* open a console stream */

Windows may be opened on a custom screen by including the screen pointer
in the specification string, as in CON:s123abc/10/10/300/100/MyWindow.

Various Intuition options and gadgets may be selected by including a list
of attributes after the window title.  Here's how it works:  Put another
slash ('/') after the window title, and follow it with any of the attribute
options below:
   A ==> Activate             (def: no activate)
   B ==> BackDrop             (def: not BackDrop)
   C ==> Close gadget         (def: no gadget) (action not implemented)
   D ==> Depth gadget         (def: depth gadget)
   M ==> Move (drag) gadget   (def: drag gadget)
   N ==> NoBorder             (def: border) (sorry, 'B' was used)
   R ==> Refresh mode         (def: SMART_REFRESH)
   S ==> Sizing gadget        (def: sizing gadget)
   Z ==> Zero-Zero            (def: not GZZ)

Each attribute serves to TOGGLE the corresponding windows flag, so adding
it twice will cancel the effect.  A closing slash is optional.  For those
of you who wanted a slash in your titles:  sorry.

Example: CON:10/10/300/100/Behind/nb/  creates a borderless backdrop window.
         CON:10/10/300/100/Fixed/acm   creates an active window, with a
                                       close gadget, that won't budge.

Installation.
ConMan requires that two files be copied to your SYS: disk (don't worry,
they're both small.)  "My-Handler" (184 bytes) must be placed in
the SYS:L directory, to keep all those bigger handlers company.  The
file "conhandler.library" (5592 bytes) must be placed in the your LIBS:
directory, which is normally SYS:LIBS.  The ARCed files have shortened
names, so be sure to rename "conlib.lib" and "myhandlr."  A simple "install"
script is included to copy the files.

Once these files are present, execute ConMan (956 bytes) to install the
handler.  This file only needs to be run once (e.g. from your
startup-sequence); it allocates 20 bytes of memory for the handler name
string which won't be returned (there is no provision in DOS for removing
a handler, anyway.)  ConMan accepts three command-line arguments:  -c
(the default) patches the CON: node, -r patches the RAW: node, and -q
("quickly") writes the startup message to the standard output stream
instead of opening a window (and delaying so you can read it.)
Example:  conman -c -q

Distribution.
This program is to be distributed as shareware to Amigoid life-forms
everywhere!  Make sure your friends get a copy.  Comments and contributions
will be appreciated and may be sent to:

      William S. Hawes        (bix: whawes)
      P.O. Box 308
      Maynard, MA 01754
      [phone]

Additional documentation and the assembler source code will be available
in the near future.

I will be other releasing other Amiga products, both through shareware and
normal commercial channels.  Watch for:
    ARexx ... the REXX language for the Amiga (June, 1987)
    Mini-Shell ... just enough DOS (August, 1987)


Further Notes.
This is the last Beta version before the "final" (is anything ever final?)
release of ConMan.  Some debugging code still remains here.  Function key
F5 toggles a flag that causes a DisplayBeep everytime a "WaitForChar"
packet is dispatched.  Most programs will not use the "WaitForChar" function,
since a Read to the CON: device will block until characters are available
anyway.  F5 toggles a flag that DisplayBeeps whenever a "break" signal is
passed on (i.e. is applied to your hapless task).  Also, an extraneous
message port (called 'MyCon') will appear in the Ports list.  These testing
features will go away RSN.

The program was developed and tested under V1.2; at least one V1.1
dependency was found and fixed (DoIO to the console device scratched D7).
Let me know if other problems exist.  I spent a lot of time making it
work using the DOS handler-loading mechanism so that it would be backwards
compatible.

A passing note:  The interaction of the "shrink" and "zoom" keys proved
to be a little trickier than it first appeared; I ended up spending the
better part of a day finding state transitions that seemed intuitive.
Anyone who doesn't like the current implementation is invited to submit a
state diagram with the desired transitions ...

One warning with regard to the "shrink" and "zoom":  rapid toggling between
window states will crash the machine.  It seems that Intuition provides no
way to indicate whether a "sizing" or "moving" request is pending, so the
dimensions read from the window structure may not be consistent with the
actual size when the operation is performed.  I'm currently looking for a
reasonable work-around before adopting an ugly kludge.  Until then, take
it easy on the keys, OK?

Function Key Interrupts.
One major addition to this version is the support for function-key interrupts.
The ConHandler library provides functions for maintaining a push-down stack
of function-key contexts.  Whenever a function key event (or more generally,
any raw event) occurs, the console handler first calls the user-supplied
function at the top of the context stack.  Your function is free to "eat"
the event, change it to something else, or take any other action.  Some
restrictions apply (after all, these are asynchronous events), but this
should allow for some interesting programming.  A separate program called
"SideShow" has been included as an example of function-key processing.
The full source code to "SideShow" is available for programmers interested
in using the interrupt facilities.  All you programmers: try this stuff
out, as I'm interested in feedback on it!

The remaining areas of development include:
   -- Does anyone want to pass in a Super-Bitmap pointer?  If so, suggest
      a reasonable syntax that doesn't clash with the conventions already
      in place.

   -- Has anyone tried the method of passing the window pointer to the
      handler as shown in Andy Finkel's Window example?  It should work,
      but I haven't had a chance to try it.

   -- This version has most of the machinery in place to act as a "pipe".
      A few open questions need to be resolved, such as whether the pipe
      should "reblock" the input or dole it out in the same size chunks
      that it came in.  In addition, it might be interesting to allow the
      handler to be opened as a console and then switched into a pipe ...
      allowing the output to be displayed as well as passed through.  Any
      comments in this vein (pipe?) would be welcome.

Special thanks to John Toebes and the Software Distillery for all the great
suggestions, and to everyone who called in with comments or contributions.

                                      WSH (05/10/87)