home *** CD-ROM | disk | FTP | other *** search
/ The Fred Fish Collection 1.5 / ffcollection-1-5-1992-11.iso / ff_progs / mouse_ut / mouseaid.lha / MouseAide.Doc < prev    next >
Text File  |  1992-08-19  |  20KB  |  504 lines
  1. MouseAide v5.02a.07.30.92
  2. Copyright (c) 1992 by Thomas J. Czarnecki
  3. All Rights Reserved
  4.  
  5.  
  6.  
  7.     "MouseAide" is a 100% assembly language program that helps the Mouse
  8.     & Keyboard do a whole lot more, with a lot less work by the user!
  9.  
  10.  
  11.                             MouseAide Features:
  12.  
  13.  
  14.     o   An adjustable acceleration of the mouse, with a adjustable threshold
  15.         for fast, and easy precision work.
  16.  
  17.     o   Auto-Activation (SunMouse) of the window that the mouse pointer is
  18.         over.
  19.  
  20.     o   Auto-Key-Activation of the window that the mouse pointer is
  21.         under, when a key is pressed.  Nice feature to have if you use
  22.         the keyboard with multiple windows.  Just point and type!
  23.  
  24.     o   Blanking of the mouse pointer if a key is pressed.  No more trying
  25.         to read behind the mouse pointer, Nice eh?
  26.  
  27.     o   Blanking of the mouse pointer if user input is idle for a set
  28.         number of seconds.
  29.  
  30.         As of this version the mouse blanking is done by switching the pointer's
  31.         'Sprite' with an invisible 'Sprite' which will NOT affect any of the
  32.         other 'Sprites' being used.
  33.  
  34.     o   To save your monitor from image burning: blanking of the screen
  35.         if the user input is idle for a set number of minutes. Nice
  36.         feature for those of us that take a one minute break that runs
  37.         into....
  38.  
  39.     o   Clicking a Window under the mouse pointer to the front (if need be)
  40.         with a adjustable number of left mouse button clicks, that are
  41.         within the time you have set in preferrences.  The clicks to front
  42.         count is reset when the mouse pointer is moved to a new window, making
  43.         unwanted 'Clicks To Front' less likely when using a click count of two
  44.         or more.
  45.  
  46.     o   Clicking a Window under the mouse pointer to the back, by holding the
  47.         left mouse button down while clicking and releasing the right mouse
  48.         button!
  49.  
  50.     o   Clicking the Screen to the back, by doing a doing a Window to back
  51.         sequence, but with the mouse pointer NOT over a Window!
  52.  
  53.     o   Middle Mouse Button (MMB) Window & Screen turning! Pressing the
  54.         middle mouse button while the pointer is over a Window will bring
  55.         that Window to the front, unless the Window is already in the front,
  56.         in which case, the Window will be sent to the back, nice eh?
  57.         To get even more power out of the middle mouse button (MMB) if the
  58.         pointer is NOT over a Window that can be depth arranged "MouseAide"
  59.         will send the front Screen to the back and make the top Window the
  60.         active one!  I wrote this function after replacing my original mouse
  61.         (which did NOT last very long!) with a new third party mouse, which
  62.         had a third button (in the middle of course)  Well, after finding
  63.         that the Amiga did NOT support the middle button in anyway I set out
  64.         and wrote this small GEM of a function!  After using this function
  65.         for just a couple of weeks I would never buy a mouse/trackball
  66.         without the extra button!
  67.  
  68.     o   Turning the windows with the 'Left Amiga-J', & 'Left Amiga-K' keyboard
  69.         sequences.  The top window will become the active one!
  70.  
  71.     o   Turning the screens with the 'Left Amiga-N', & 'Left Amiga-M' keyboard
  72.         sequences.  The top screen will become the active one!
  73.  
  74.     o   If any conflicts arise "MouseAide" can be suspended by the keyboard
  75.         sequence: Left-Amiga-Right-Shift  And restarted with the same sequence!
  76.         This allows you to enter any key/mouse input that "MouseAide" may use,
  77.         without getting the action (Click-to-front, Window/Screen turning...)
  78.  
  79.     o   Can execute a default ('NewShell') or a user defined command with the
  80.         'Left Amiga-Esc' keyboard sequence.  Nice for a quick-pop-up program,
  81.         or a easy CLI/Shell startup.
  82.  
  83.     o   Multi-Icon-Select with just the mouse, No more shift key!  By pressing
  84.         and holding the left mouse button, then pressing and holding the right
  85.         mouse button, and then releasing the left mouse button, you enter the
  86.         Multi-Icon-Select (M.I.S.) mode!  To select multiple Icons just click
  87.         on them with the left mouse button while still holding down the right
  88.         mouse button!  You can enter the M.I.S. mode while selecting your first
  89.         Icon, or, as I find easier, you can enter M.I.S. mode by doing the above
  90.         sequence without an Icon!  It makes it easier to select the first Icon
  91.         without moving it!
  92.  
  93.     o   Better keyboard feedback by producing a 'Clicking' sound when a 'Key'
  94.         is pressed!  This function is handy when you are entering data into
  95.         the computer without looking at the screen much.  I allocate a 'Audio'
  96.         channel at a low enough priority that you can run a music type playing
  97.         program which will steal the channel to play the music and when done
  98.         playing 'MouseAide' will recover its channel for use again!  Nice eh?
  99.         I also let the user set the 'Clicking' volume level and Priority of
  100.         the Key Clicking's audio channel!
  101.  
  102.     o   Automated date generation!  With just a few keystrokes "MouseAide"
  103.         will get the current date, build it to a default, or user format,
  104.         and than output it by the same method that is used when you type
  105.         on the keyboard!  To generate the default formated date all the
  106.         user has to do is press hold down the 'Left-Amiga' key and press
  107.         the 'd' key, easy eh?  To generate the users formated date you do
  108.         the same key-sequence as above, but you also hold down the 'Shift'
  109.         key!  The 'users format' is defined by a string that you pass to
  110.         "MouseAide" at startup that tells the program how you want your
  111.         date to be generated.  The format is quite simple and is explained
  112.         below in the options sections.
  113.  
  114.     o   A simple keyboard 'String' macro function to allow the user to
  115.         assign user defined strings to user defined keys!  When the
  116.         user types a defined 'Key' it will be replaced with their 'String'
  117.         by the same method that is used when you type on the keyboard!
  118.         This program saves the user from the tedious process of hand
  119.         entering commonly typed 'Strings'  I find it useful in all types
  120.         of computing from working in the CLI/Shell to using it for text
  121.         short cuts in editors!  How to define your 'Macros' is explained
  122.         below in the options sections.
  123.  
  124.     o   Closing Windows & Shells/CLIs from the keyboard with the 'ESC' key.
  125.         I close 'Windows' by the same method as if you clicked on the 'Close'
  126.         gadget.  Shells are closed by sending a user defined "String" to the
  127.         'Shell' which would then end the shell.  The default "String" is
  128.         "EndCLI\n" which would close a normal Shell/CLI.  The user can define
  129.         their own 'String' in the 'MA.Keys' file by including a line with the
  130.         following format:
  131.  
  132.             CLIEndString = "String"
  133.  
  134.         Where the "String" is the user definable string that is to send to the
  135.         Shell/CLI to close it!  I made the closing string user definable because
  136.         of programs such as "ParM" which will NOT close if "EndCLI" is used!
  137.  
  138.     o   You can switch which port (1 or 2) that the mouse uses with the key
  139.         sequence: 'Left Amiga-P'  Did you buy a TrackBall for your favorite
  140.         graphics program, but prefer to use the mouse for your non-graphics
  141.         work, well plug the TrackBall in Port2 and switch between the mouse
  142.         and TrackBall on the fly with a few keys!
  143.  
  144.         As of this version the 'Middle Mouse Button' is also switched when you
  145.         swap mouse ports!
  146.  
  147.     o   Workbench Window to Front with the 'Left Amiga-W' (The default for this
  148.         function is: Off, so to use this fuction you must enable  with the '+w'
  149.         switch when installing "MouseAide")  I created this function because
  150.         with just a few open windows on the 'Workbench Screen' I could NOT get
  151.         at the disk icons!  When you activate this function the 'Workbench'
  152.         Window will come to the front, allowing you to open a disk/volume
  153.         icon.  When you open a window or use the 'Left Amiga-W' sequence again
  154.         the 'Workbench' Window will pop back!
  155.  
  156.     o   Freezing of the mouse and keyboard of all input, which if you live with
  157.         small children or a keyboard climbing critter, can be a real life-
  158.         saver!  Just use the 'Left Amiga-Right Amiga-Z' keyboard sequence to
  159.         toggle in/out of the input freezing mode.  When you enter the input
  160.         freezing mode all mouse and keyboard input (except for the key sequence
  161.         to toggle you back) will be frozen, also the mouse and screen will
  162.         blank until you leave this mode.  This fuction is great for those long
  163.         running programs, that you start up and leave alone for a long period
  164.         of time!
  165.  
  166.     o   Can switch the right & left mouse buttons when installed for those left
  167.         handed people out there!  (Use the '+l' option listed below)
  168.  
  169.     o   Any Selected-To-Be-Dragged-Icons will be released, when any window
  170.         manipulation (Window to back, Window to front, Keyboard window cycling)
  171.         is required to prevent a system lockup!  This gets around a Intuition
  172.         bug in the in the 'WindoToFront' and 'WindowToBack' functions.
  173.  
  174.     o   As of this version "MouseAide" will now remember the 'Path' for the
  175.         process that has started it and if that process does NOT have a 'Path'
  176.         will search for a process that has one that it can use!  What all that
  177.         means is that a process started by "MouseAide" (by command execute)
  178.         will also have that 'Path'  Nice eh?
  179.  
  180.     o   "MouseAide" will try opening the "NULL:" device first, and the "NIL:"
  181.         device only if the "NULL:" is NOT mounted.  This make system which have
  182.         the "NULL:" device installed much more reliable when you use the
  183.         'Command' function!
  184.  
  185.     o   Adjustable priority of the 'Input Handler'  The default is: 57, and
  186.         should be fine for most of you.  But if you are using another program
  187.         that also uses a 'Input Handler' than this option maybe nice to have!
  188.  
  189.     o   Easy WorkBench & CLI startup and shutdown!
  190.  
  191.     o   Releases every byte of memory on shutdown.  No dead data, or code is
  192.         left in the system!  Did you ever notice, after running some programs,
  193.         how your free memory seems less?  Well it is!  But, NOT after running
  194.         "MouseAide"  It cleans up after itself!
  195.  
  196.     o   The options can be user defined by Workbench or CLI/Shell
  197.  
  198.     o   Very small in size, about 12K in size, and even smaller with your
  199.         favorite executable compressor (Turbo Imploder, PowerPacker...)
  200.  
  201.     o   Self-detaching,  for ease of startup!
  202.  
  203.     o   Uses advanced (Semaphore locked) static & dynamic memory management
  204.         techniques to reduce memory thrashing, while also keeping memory
  205.         demands low!
  206.  
  207.     o   Uses "good" programing practices!,  Not like most of the "Mouse"
  208.         programs floating around!  No "Intuition" calls are made from the
  209.         high-priority 'Input Handler', a very bad practice that most of the
  210.         "Mouse" programs use!
  211.  
  212.     o   The 'Input Handler' runs at a high priority, but the time wasting
  213.         part of the program run at a low priority
  214.  
  215.     o   The one-shot data & code (start-up, shut-down, etc...) is release
  216.         after start-up to further reduce memory overhead!
  217.  
  218.  
  219.  
  220.     To startup "MouseAide" from WorkBench just double-click on "MouseAide" Icon!
  221.  
  222.     From CLI type: MouseAide<RETURN>
  223.  
  224.         (Note: That the program is self-detaching, do NOT Run it!
  225.                It also sets the correct stack-size and priority, don't
  226.                waste time adjusting them!)
  227.  
  228.     To remove "MouseAide" just start up the program again.
  229.  
  230.  
  231.     All options (switchable, value & command) have a default setting. The value
  232.     defaults are set as following:
  233.  
  234.             Acceleration Factor     -   3
  235.             Threshold Factor        -   2
  236.             Clicks to Front         -   1
  237.             Mouse Blanking          -   5 Seconds
  238.             Screen Blaking          -   5 Minutes
  239.             Input Handler Priority  -   57
  240.             'Clicking' Volume       -   48
  241.             'Clicking' Priority     -   80
  242.  
  243.     The default options can be changed by the user by using the option line.
  244.     By using the '+' & '-' switches, the user can turn ON or OFF any option.
  245.     All the switchable options, but, Left-Handed-Swap and the Workbench
  246.     window to front, are by default: On.
  247.  
  248.     The switchable options are:
  249.  
  250.             "a" -   Auto-Activate
  251.             "f" -   Click to Front
  252.             "b" -   Click to Back
  253.             "m" -   Mouse Blanking
  254.             "s" -   Screen Blanking
  255.             "t" -   Key Turning
  256.             "e" -   Key-Activte
  257.             "k" -   Key-Mouse Blanking
  258.             "i" -   Multi-Icon-Select
  259.             "p" -   Port swapping for the Mouse
  260.             "l" -   Left-Handed-Swap (Off by default)
  261.             "w" -   Workbench Window to Front (Off by default)
  262.             "d" -   Auto-Date generation
  263.             "c" -   Keyboard 'Clicking'
  264.             "u" -   MMB Window/Screen Turning
  265.             "y" -   Key Closing
  266.  
  267.  
  268.  
  269.     Value options are set by an integer number following the Option to be set.
  270.     The value is auto-ranged (limited) to a default value.
  271.  
  272.     The value options are:
  273.  
  274.             "A" -   Acceleration Factor (range:1-11)
  275.             "T" -   Threshold Factor (range:1-11)
  276.             "F" -   Click(s) need for window to Front (range:1-9)
  277.             "M" -   Mouse Blanking time in seconds (range:1-59)
  278.             "S" -   Screen Blanking time in minutes (range:1-59)
  279.             "P" -   Priority of the 'Input Handler' (range: 50-127)
  280.             "V" -   Volume level of the keyboard 'Clicking' (range: 1-64)
  281.             "K" -   Key Clicking's audio channel Priority (range: 1-127)
  282.  
  283.     ------------------------------------------------------------------------
  284.  
  285.     When 'MouseAide' is started up it will look for a file named 'MA.Keys'
  286.     in the current directory (CD) and if NOT found will search the path of
  287.     the process that started 'MouseAide' up!  The file 'MA.Keys' will define
  288.     the users 'Keys' and their 'Strings'  The format of the files is simply
  289.     a line of text that first lists the 'Qualifiers' that have to be held
  290.     down, followed by the 'Key' to be defined, followed by a '=' and then a
  291.     quoted 'String' to be generated!
  292.  
  293.     The 'Qualifiers' defined as:
  294.  
  295.         LSHIFT      for 'Left Shift'
  296.         LALT        for 'Left Alt'
  297.         LAMIGA      for 'Left Amiga'
  298.         CTRL        for 'Ctrl'
  299.         RSHIFT      for 'Right Shift'
  300.         RALT        for 'Right Alt'
  301.         RAMIGA      for 'Right Amiga'
  302.  
  303.     The NON-ASC 'Keys' are defined by these tokens:
  304.  
  305.         TAB
  306.         ESC
  307.         SPACE
  308.         RETURN
  309.         ENTER
  310.         DEL
  311.         BACKSPACE
  312.         HELP
  313.         LEFT
  314.         RIGHT
  315.         UP
  316.         DOWN
  317.         F1
  318.         F2
  319.         F3
  320.         F4
  321.         F5
  322.         F6
  323.         F7
  324.         F8
  325.         F9
  326.         F10
  327.         CLIEndString (Used to define the 'Keyclosing' string!)
  328.  
  329.     To include a 'Return' in a defined string use the '\n' sequence a
  330.     quote is defined by the '\"' sequence, and the '\' charactor is
  331.     the '\\' sequence, simple eh?
  332.  
  333.     Do I here 'what about a few exmaples?' O.K. by me, the line:
  334.  
  335. ralt lshift e="End\n"
  336.  
  337.     Would generate the string:
  338.  
  339. End<Return>
  340.  
  341.     When the 'Right Alt', 'Left Shift' keys are held down, and the 'e'
  342.     key is pressed!  The next line:
  343.  
  344. lamiga f3="MouseAide +w U\".sy\""
  345.  
  346.     Would generate the string:
  347.  
  348. MouseAide +w U".sy"
  349.  
  350.     When the 'Left Amiga' key is held down and the 'F3' key is pressed!
  351.     This last example is my favorite:
  352.  
  353. ; This is it!
  354.  
  355.     Because it does nothing, being a comment line!  A comment may start at
  356.     any point on a line and it runs until the end of that line, use it well!
  357.  
  358.     As you can tell by the above examples the user format is very easy to
  359.     learn and use!  If you need more examples take a look at the 'MA.Keys'
  360.     file I have included, and try them out!
  361.  
  362.     ------------------------------------------------------------------------
  363.  
  364.     The 'Automated Date' generation part of "MouseAide" allows the user to
  365.     design their own formated date generation with the 'U' option string,
  366.     just use the following information to build your own format string:
  367.  
  368.         "d" or "D"  - Stands for DAY
  369.  
  370.         "y" or "Y"  - Stands for YEAR
  371.  
  372.         "m"         - Stands for MONTH as a number
  373.  
  374.         "M"         - Stands for MONTH in writing
  375.  
  376.         "w" or "W"  - Stands for day of the WEEK
  377.  
  378.         "l" or "L"  - Stands for switch to the LONG type, until changed
  379.  
  380.         "s" or "S"  - Stands for switch to the SHORT type, until changed
  381.  
  382.         "'"         - Is to allow any of the above characters to be
  383.                       used as itself
  384.  
  385.             Any character that does NOT match the above ones are used to
  386.         fill in between the ones that are use!  Confused?  Lets try a few
  387.         examples:
  388.  
  389.             - Assume that the date is: June 7, 1992
  390.  
  391.         U"sm.sd.sy"      - Will generate: 06.07.92
  392.  
  393.         U"lm.ld.ly"      - Will generate: 6.7.1992
  394.  
  395.         U"lM ld, ly"     - Will generate: June 7, 1992
  396.  
  397.         U"ld-sM-sy"      - Will generate: 7-Jun-92
  398.  
  399.         U"sm/sd/sy"      - Will generate: 06/07/92
  400.  
  401.         U"sm/d/y"        - Will generate: 06/07/92
  402.  
  403.         U"lm/d/y"        - Will generate: 6/7/1992
  404.  
  405.         U"lm/d/sy"       - Will generate: 6/7/92
  406.  
  407.         U"sd-sm-sy (sw)" - Will generate: 07-06-92 (Sun)
  408.  
  409.         U"sd-sM-sy (sw)" - Will generate: 07-Jun-92 (Sun)
  410.  
  411.         U"lM sd (lw)"    - Will generate: June 07 (Sunday)
  412.  
  413.         U"lM ld (lw)"    - Will generate: June 7 (Sunday)
  414.  
  415.         U"'Date: sm/sy"  - Will generate: Date: 06/92
  416.  
  417.         As you can tell by the above examples the user format is very
  418.         flexible, and easy for anybody to use!
  419.  
  420.     The 'Automated-Date' function also allows the user to use a different
  421.     language then English!  By creating a file name ".DateInfo" that is made
  422.     up of the names of the months followed by the names of the days of the
  423.     week, each on one line, for a total of 19 lines.  When this file is
  424.     then placed in the same directory at startup of "MouseAide", they will
  425.     be used instead of the default English names!  For an example I have
  426.     placed a sample '.DateInfo' file in the directory named 'MiscFiles'
  427.  
  428.  
  429.  
  430.     The last option is the 'C' (command) option.  This option must be the last
  431.     option to be set on the option line!  The syntax is:
  432.  
  433.             C <User defined string>
  434.  
  435.     If you do NOT define a command string the default 'c:NewCLI' will be used!
  436.  
  437.  
  438.     So, a few examples are now in order:
  439.  
  440.         For: No Auto-Activate, Mouse Blanking set to 7 seconds, a Acceleration
  441.         Factor set to 5, the Threshold Factor set to 3,  do Key-Activate and
  442.         Key-Mouse Blanking we would use this option line:
  443.  
  444.             -a M7 A5 T3 +ek
  445.  
  446.         For: No clicking to front, and No Key-Turning, and the command string
  447.         'AShell...' we would use this option line:
  448.  
  449.             -fe CAShell CON:0/11/0/0/MouseAideShell
  450.  
  451.         For: An Acceleration of 2, and a Threshold of 1, with 3 Clicks for a
  452.         Window to front, and the Workbench Window to Front option, we would
  453.         use this option line:
  454.  
  455.             A2 T1 F3 +w
  456.  
  457.  
  458.  
  459.         To use the option line in the CLI, just add it to the end of the line
  460.         on startup. For example:
  461.  
  462.             MouseAide +mstkef A4 T2 F3 M3 S1 CGShell
  463.  
  464.  
  465.         To use the option line from WorkBench, you can do it two ways:
  466.  
  467.             1: Writing "OPTIONS=option line" in the "Tool Types" field of
  468.              "MouseAide" Tool Icon.
  469.  
  470.             2: Writing "OPTIONS=option line" in the "Tool Types" field of
  471.              a Project Icon and 'MouseAide' in the "Default Tool" field.
  472.  
  473.         You can get good examples by Info(ing) the Icons included
  474.  
  475.  
  476.     Hint:  A console window with a lot of output may delay some "MouseAide"
  477.            functions!  A good trick is to hit the shift-key when this delay
  478.            happens.  The Shift key will be like a electric shock to the
  479.            system, breaking the delay.
  480.  
  481.  
  482.  
  483.  
  484.     Tempus Fugit,
  485.  
  486.         Czar
  487.  
  488.  
  489.  
  490.  
  491. If you have any ideas, comments, bugs to report, write me:
  492.  
  493.  Thomas J. Czarnecki
  494.  3526 Republic Avenue
  495.  Racine, WI 53405-3856
  496.  
  497.  
  498.  
  499.  
  500.  
  501.  
  502.  
  503.  
  504.