Club Amiga de Montreal

home *** CD-ROM | disk | FTP | other *** search

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

Wrap

Text File | 1989-04-07 | 22.7 KB | 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