Club Amiga de Montreal - CAM/CAM_CD_1.iso/files/229.lha/UtilityManager_v1.1/ReadMe.j

Text File | 1989-04-07 | 23KB | 462 lines

Amigo : UtilityManager 1.1 © 1989 Dennis Janssen

Quick Startup Info:

  To start aum copy the included files ".aum" and "directory2" to your "s:"
directory or assign "s:" to the directory where you placed these files.  Then
change directory to the directory with "aum" in it or copy "aum" to your "c:"
directory. You must always have the DOS command "run" in your "c:" directory to
use any DOS commands from aum. Now type "aum" at a cli or click on the "WB-AUM"
icon. This will open a window with gadgets also there is a menu which can be
seen by using the right mouse (menu) button.

Aum 1.1 ReadMe.i

Contents
  1.Introduction - Feature Overview
     1.1.Brief Feature List
  2.***How to get Aum started***
  3.Using an included example - directory2
  4.Idiosyncrasies of aum: don't use spaces in filenames; path
  5.Purchasing Information - how to get the documentation details
  6.Regarding Version Numbering
  7.Version History
  8.A note on the distribution of aum
  Appendix - interprocess communication for software developers

1. Introduction - Feature Overview

  Aum is a graphical, mouse operated, programmable DOS manager, or shell.  It
allows the user to easily use the elements of the Amiga's graphical interface -
windows, gadgets, menus and requesters - plus key assignments, timers, alarms
and macros to build an operating or programming environment where the main
interaction with DOS is through the mouse while retaining all the power of the
CLI.
  There are also many internal commands and features such as command
history, fast directories, variables, a mouse window manager and timed
screen blanking.
  The operating environment is built with what I call "command objects". These
can be represented graphically by menus or gadgets, or non-graphically by key
assignments, timers, alarms or macros.  The user determines a list of commands
to be associates with each command object.  When a command object is selected or
activated (eg. selecting a menu item or clicking a gadget) the command list
associated with it is sent to aum's command preprocessor and interpreter.
  The preprocessor basically expands variables and breaks up the command list
into individual commands and sends the individual commands to the command
interpreter which is in charge of executing the command. If the command is a
built in command then the command will be executed internally else the command
will be simply passed to DOS for execution as if it were typed at the CLI.
  The command objects are built with the commands _MenuItem, _MenuSubItem,
_Gadget, _StringGadget, _DisplayGadget, _Key, _Timer, _Alarm, and _Macro. These
commands will be referred to as the "command object building commands". The
gadget commands can only be used in a file and they will automatically create a
window (see the section Gadget Positioning).  The other commands can be used in
a file or as a part of other commands.
  To build the initial command objects one puts the desired command object
building commands in the file s:.aum.  Aum automatically reads that file when it
begins. You can have aum read another file when it begins by explicitly giving
it as a command line argument to the aum DOS command. Eg. aum <filename>.

1.1.Brief Feature List
    ------------------
    1.Menus : multiple switchable menu strips with optional subitems
    2.Gadgets
        2.1.Boolean Gadgets
        2.2.String Gadgets : with optional command history functions
    3."File requester" gadgets that are resizeable, can display directories,
        command history and the internal directory list.  They also have
        programmable toggle commands for each list.
    4.Fast Directories : Fast internal directory lists for practically
        instantaneous redisplaying of a directory once you've gotten that
        directory making for quick re-traversal of the directory tree of
        multiple volumes; with updating if and only if necessary.
    5.Command History : Multiple simultaneous history string gadgets are fully
        supported.  The associated command history lists can be preset,
        deleted from, displayed and operated on or executed from a display
        gadget.
    6.Multiple Windows
    7.Key assignment of command lists, 8 optional qualifiers, 256 possibilities
        per key
    8.Timers : assignment of command lists to a count down timer
    9.Alarms : assignment of command lists to specific times
   10.Macros : aliases
   11.Forty six built-in commands : including a simple debugger and a
        conditional (_if, _else), screen blanking, auto window moving and
        resizing, ipc, 46 in all.
   12.Variables : 3 types of string variable including one to refer to a set of
        selected files that has an implicit ("while") loop type control function
   13.Automatic Requester commands ("?") for inserting user choice points in
        command lists
   14.Interprocess Communication : Aum accepts commands from other processes
        through a separate program "send" (an executable included with the
        released files). It also can send commands to any process that is
        ready to receive its messages. Details for programmers about
        receiving aum commands is given in the Appendix.
   15.Input Handler : on/off switch for entire handler if you'd rather use a
        different one
      13.1.Programmable Mouse Accelerator : on/off and speed limit
      13.2.Window Activation : "Sun Mouse" - on/off
      13.3.Left mouse button - window to front if in a window and window is in
             any way covered by another layer, screen to front if on screen
      13.4.Left+Rignt mouse button - window to back if in a window, screen to
             back if on a screen
   16.Command preprocessor
   17.Control Table : every reasonable variable of the system is controlled by
        a control table which is in turn user controlled ; 66 variables
        including colors, sizes, special characters of preprocessor, etc.
   18.Error Codes for internal errors

2. **** How to get Aum started ****

  Aum reads an initial "startup-file" which can be set as an argument the
default is "s:.aum". In this file the user should place lists of his/her
most used commands assigned to command objects as exemplified in the
included files and explained in the documentation. After aum is activated
the user then works in this environment activating the preset commands with
the mouse through the command objects. In most cases, you shouldn't have to
type commands for DOS once your most used commands have been preset in a
"aum file". You may want to edit an existing command for fine tuning -
changing options, etc.- this can be done in a  history gadget and again the
history can be preset. You can also build commands from displayed strings
using string gadgets and the options of the built-in _Variable command .

   **** How to get Aum started the first time ****

  To start aum copy the included files ".aum" and "directory2" to your "s:"
directory or assign "s:" to the directory where you placed these files.
Then change directory to the directory with "aum" in it or copy "aum" to
your "c:" directory. You must always have the DOS command "run" in your
"c:" directory to use any DOS commands from aum. Now type "aum" at a cli or
click on the "WB-AUM" icon. This will open a window with gadgets also there
is a menu which can be seen by using the right mouse (menu) button.

   **** How to get Aum started in general ****

  So in general to start aum from a CLI you can simply type "aum" or add as
an argument any filename you wish to use as an alternate initialization
file - "aum <filename>".
  WB-AUM, an included executable file, is necesary for Workbench startups.
It is simply a slightly modified version of the regular DOS 1.3 CLI command
- it doesn't read "s:cli-startup" but instead starts aum.

Note: Again, you must always have the DOS command "run" in your "c:"
directory to use any DOS commands from aum.

3.Using the included example files

    Included with this release are a number of files which are adapted to
  my paticular pattern of computer use.  You should modify them according
  to your own individual needs.  This section is a explanation so you will
  get an idea of some of the uses of Aum before you get the documentation.
  Details of the meaning of each command, it's arguments, options and
  special features are given in the documentation obtained by mail from me
  as explained in the Purchasing section.  Below is a description of the
  function of the different gadgets in the file "directory2".  This file is
  read by the aum internal command "_read s:directory2" which is given in
  the startup file "s:.aum".

    This window contains two large "display gadgets" also called file
  requesters or directory gadgets, three string gadgets and a number of
  other regular (boolean) gadgets.  Beneath each display gadget is an
  associated string gadget which is used to display information related to
  it's respective display gadget such as the currently displayed directory,
  the number of total bytes/blocks of the selected files, the number of
  free blocks on the current drive, or other user selected values.  Below
  both of these string gadgets is another string gadget that is set up to
  work as a "history gadget".  By hitting the up arrow key you get a
  "previous" history, by hitting a down arrow you get a "next" history.
  These can be and have been preset by the directory2 file. Whatever you
  type there and hit return after (like a normal cli command) will be
  executed and added to the history.
    Note that these functions are not "set in concrete", they have been set
  by the files read at startup and all can be modified to your own special
  uses as explained in the documentation.  The number of gadgets, their
  positions, names and corresponding functions are set by the files.
  Similarly with the menus and keys (up and down arrow keys).

  Below is a list of the "names" of the gadget - the character symbols that
  appear on the gadget - and a description of the command associated with
  clicking on the gadget.  This information can also be obtained by examining
  the files with the help of the documentation.  Some of the gadgets are not
  listed since they are easy to understand from the ones listed, eg. "Delete1".

P  gets the Parent directory of the current directory
U  Updates the current directory (any non-internal commands that changes a
     directory may require an update for accuracy)
T  Toggles all the lines in the display
b  displays the total Bytes/blocks of the selected files
d  displays the number of blocks available on the Device associated with the current
     directory; helpful if you want to know if a disk has enough room for a copy of
     the selected files
List displays the internal List of directories
Free frees an internal directory freeing the associated memory
V directory of VD0:
R directory of RAD:
0 directory of DF0:
1 directory of DF1:
r Directory of RAM:
Apd sets a variable to "-a" (append). This variable is used to control the mode
  of the _Variable command used in the gadgets "v" and "vv" so that they will
  append the contents of their associated string gadgets to the contents of the
  central string gadget. (See Documentation for the _Variable command modes)
Ins sets a variable to "-i" . This variable is used to control the mode
  of the _Variable command used in the gadgets "v" and "vv" so that they will
  insert the contents of their associated string gadgets at the cursor into the
  central string gadget. (See Documentation for the _Variable command modes)
Rep sets a variable to "-r" (replace). This variable is used to control the mode
  of the _Variable command used in the gadgets "v" and "vv" so that they will replace
  the contents of the central string gadget with the contents of their associated
  string gadgets. (See Documentation for the _Variable command modes)
Db+ switchs to Debug mode
-   switchs back from debug mode
Abt Abort the current command list
v copies the value of the string gadget to the string gadget below using the mode
    value (set above)
vv copies the value of the string gadget + the first selected file name to the
    string gadget below using the mode value (set above)
+ adds the value in the string gadget to its history list
- deletes the value of the string gadget from the history list
v sets the string gadget to the next position in the history list
^ sets the string gadget to the previous position in the history list
"Copy1 %" copies the selected files of the first list display gadget to the directory
  that is displayed in the center string gadget
"Copy1 2" copies the selected files of the first list display gadget to the directory
  that is displayed in the right upper string gadget
- resizes the gadget window to normal size
| resizes the gadget window larger
W brings the cli output window to the front
. resizes the cli output window to a point at 0 0
= resizes the cli output window brings it back to original size and position
+ resizes the cli output window adjusts to full screen size
Histry>1 displays the history list of the center string gadget and sets the "toggle
    command" (see documentation) to allow execution of any displayed command by
    simply selecting it with the left mouse button
Histry>2 displays the history list of the center string gadget and sets the "toggle
    command" (see documentation) to simply copy the command to the center
    string gadget; from there it can be edited and/or executed
1 executes the commands selected in first display gadget
"Run(1) 2" runs the commands selected in the first display gadget using as
    arguments the filenames selected in the second list display gadget

Key assignments:

F1 If an aum window is active the F1 function key is set to close the aum
windows, when hit again it reopens the windows and it will continue this cycle.
This key has no function when other program window are active.

UP DOWN  (arrow keys) The up and down arrow keys adjust the command history list
of the central string gadget when the gadget is activated by the left mouse
button.  Note: These functions are not set if the CAPS LOCK or any other
qualifier is active.

The file directory1 is a smaller version of directory2.

Please note that many features of aum do not have an example in the included files.

9.Idiosyncrasies of aum: spaces in filenames; path ; current directory;
"run" in you c:directory
  Currently aum will not handle spaces in filenames.  This means you must change
for example a volume with the name "Workbench 1.3" to something like
"Workbench1.3" or "Workbench_1.3".
  Set the paths you want (using the DOS path) before you execute aum, aum will
not know about new paths that are added after aum is started.
  To change directory you must use the internal command "_cd". The Dos command "cd"
will not be effective.
  You must always have the DOS command "run" in your "c:" directory to use any
DOS commands from aum.

5.Purchasing Information
  The full documentation with all the details and examples regarding the use of
Amigo Utility Manager is obtained by mail. Below is an outline of the
documentation which is about 26 pages long.

          Introduction
          1.Commands
            1.1.Alphabetical Command List
            1.2.Command names
            1.3.Command Name Abbreviation
            1.4.Special syntactic characters in the command format
            1.5.Internal Commands
            1.6.Command Arguments Reference Table
            1.7.Command Error Codes
          2.The Command Preprocessor
          3.Variables
          4.The Comand Interpreter
          5.The Control Tables
          6.Gadget Positioning
          7.The Mouse Handler
          8.Glossary of Special Terms
          9.Idiosyncrasies of aum
          Appendix 1: General aum syntax

  Pricing for version Aum1.1 :

      DOCS:    $9.95 for the documentation (please include the version number
                     you have)
      DISK:   $14.95 for the documentation and the latest version on a disk
      SOURCE: $24.95 for the documentation, source code in C (with a
                     makefile for Manx 3.6a) and the latest version on a disk

  Updates for registered users: DOCS: $5, DISK: $10, SOURCE: $15

  Çalifornia residents add sales tax - 7%
  Outside North America add $2.00 postage and please exchange your currency for
U.S. dollars before you send.
  If you wish to use the aum interface in your product contact me regarding licensing.

Send your order to:

         Dennis Janssen
         2452 Bancroft,#5
         Berkeley,CA 94704

  Questions by interested parties and/or support for registered users is
available by phone at 415-549-2400.

  I am also available for contract programming or consulting.

  Your comments, criticisms, suggestions, etc. are most appreciated but to make
ordering by mail as simple for you as possible just a check is all you need send
if your current address is on the check. Make a note on the check of your
program version number (Aum1.1) and the code from the pricing section above
(DOCS, DISK, or SOURCE) for the package you want.

6.Regarding Version Numbering
  Updates for the program itself will be coded as a version number increase.
When I add new features I will make a change in the first two digits,
corrections and improvements will be marked by changing the third digit.  An
update for the readme of a particular version will be coded as a change in the
appended letter.

7.Version History
  1.0a First released version
  1.01-1.04 Some bug fixes that became apparent when aum was run in different
              environments, e.g. locked hard drives
  1.05-1.06 Internal improvements
  1.07      Fixed so input handler so it will function properly when Workbench is
              loaded - this affected the function of the example F1 key
  1.08      the "-c" option with _Key doesn't work with a String Gadget because
              Intuition swallows all keys - no RAWKEY IDCMP : use "-a" instead.
              This affected the History in the center gadget
  1.1       changed the _AdjustWindow into two commands: _MoveWindow and
            _ResizeWindow, added another option to these commands
  1.11      fixed the problem with some systems having a problem it startup
            using the default filename (s:.aum); added "-n" option to
            _MenuSwitch
  1.12-1.15 fixed a bug in the _resize command; internal restructuring -
            more "object oriented"
  1.16      fixed a bug in the toggle command of 1.15; _ScreenOff now works
            with multiple screens
  1.17      fixed a problem with _closewindow; updated the example files;
            Note : internal changes require use of the new example files
            because the ordering in the command table was changed to
            alphabetical to make it easier to explain and understand- sorry
            about that
  1.18      fixed a problem with _ScreenOff for stubborn screens

8.A note on the distribution of aum.
  Aum and the related files including the ReadMe but not including the
purchased documentation and source code may be freely distributed to
friends and to other bulletin boards.

Appendix 1: For programmer's who want to there programs to receive aum
commands.
  Below in Appendix 2 is  aum's internal _Send command the final channel
through which all aum's interprocess communication messages pass.  The
external Send (included) works the same way. As you can kinda see from the
code this command takes as an argument the name of a port on the SysBase
PortList and a command string, the message - _SendMessage <port> <message>.
  To receive messages from aum here's what you do.  First you need to put
your program's named message port on the system PortList with an AddPort()
so aum can find you. Then check your port for a IntuiMessage with class set
to AUM_MESSAGE_CLASS (0x01000000), if you get one, first make a copy of the
command character string pointed to by the IntuiMessage's IAddress then
Reply() the message. That's it.  Now you can do whatever processing you
like with the message.

Example code:

#define AUM_MESSAGE_CLASS 0x01000000
  struct MsgPort CommonPort;
  CommonPort.mp_Node.ln_Name="YourNameHere";
  ...
  AddPort(&CommonPort);

  struct IntuiMessage *imessage ;
  WaitPort(&CommonPort );
  imessage=GetMsg(&CommonPort);
  class=imessage->Class;
  switch(class) {
    ...
    case AUM_MESSAGE_CLASS:
      command=TemporaryCopyOfString(imessage->IAddress);
      break;
  }
  ReplyMsg(imessage);
  ReadEvaluateCommandList (command);

  Before you exit first take your port off the PortList with RemPort() so
no other task can find you and attempt to send you a message while your
exiting. You then need to Reply() to any remaining aum messages on your
port list.

    RemPort(&CommonPort);
    while(imessage=GetMsg(&CommonPort))ReplyMsg(imessage);
    ...
    exit();

Note: because in both my internal "_SendMessage" and external "Send" command
there is a Forbid() before attempting to find the port there is no problems
regarding exit timing.
Aum is not dependent on any other response besides a Reply() but as you can
see below does Wait() for that response before getting back to other
business. Note: Aum always takes responsibility for freeing the message
memory.
  This provides a simple, effective interprocess communication mechanism. I
used the IntuiMessage because many processes use an IÐCMP in their main
input loop and since Intuition already puts those ports on the system
PortList with a generic name ("IDCMP") sometimes all you need do is rename
a Window UserPort.
  As an example, my version of Matt Dillon's DME editor has been modified
to function as described above.   Since dme (version 1.29) doesn't have
command history I map the escape key to sending aum a message to open a
borderless window with a history string gadget that mirrors the built-in
command line mode of dme.  The history gadget has its <RETURN> key command
set to send its contents to dme as a command, add the contents to its
history list and then close the window.  Each time I hit the escape key the
window with the history list is there.

Appendix 2: C Code for developers who want to be able to receive messages from
aum.

long _SendMessage(){
  char *port_name,*message;
  long error_number;
  struct IntuiMessage *our_message;
  long message_length;
  struct MsgPort *receiver_port, *port ;

  port_name=PtrContext->c_Arguments[0];
  message=PtrContext->c_Arguments[1];
  our_message=TemporaryObject(sizeof(struct IntuiMessage)+strlen(message)+1);
  our_message->IAddress=our_message+1;
  our_message->mn_ReplyPort=port=&((struct Process*)CurrentTask)->pr_MsgPort;
  strcpy(our_message->IAddress,message);
  our_message->Class=AUM_MESSAGE_CLASS;
  Forbid();/* can't have the task try to exit while we're doing a PutMsg() */
  receiver_port=FindNameCaseInsensitive(&SysBase->PortList, port_name);
  if(receiver_port)PutMsg(receiver_port,our_message);
  Permit();
  if(receiver_port){
    WaitPort(port);
    GetMsg(port);
    return(OK);
  }
  else return(CANT_FIND_PORT);
}

Amigo : UtilityManager 1.1 © 1989 Dennis Janssen