home *** CD-ROM | disk | FTP | other *** search
/ Fish 'n' More 2 / fishmore-publicdomainlibraryvol.ii1991xetec.iso / fish / enhancements / general / keymenu / keymenu.doc < prev    next >
Text File  |  1991-03-10  |  16KB  |  315 lines
  1.  
  2.                                 KeyMenu V1.03                       02Mar91
  3.  
  4.  
  5.   Purpose:
  6.  
  7.     KeyMenu is an alternative to Intuition's method of menu selection via the
  8.     keyboard. Intuition allows you to use the Right Amiga-Right Alt key
  9.     combination along with a cursor key to move the mouse pointer anywhere on
  10.     the screen. This is a simple yet flexible approach, however, if you have
  11.     ever tried to use it you probably found it to be very cumbersome for menu
  12.     selection. Keyboard shortcuts are ususally provided to invoke menu 
  13.     selections, but unless you use a particular program a lot its hard to
  14.     remember all the key combinations from one program to the next. You then
  15.     find yourself reaching for the mouse to see what menu options are
  16.     available.  
  17.  
  18.     With KeyMenu, all you need do is press and release the Right-Alt key and
  19.     the menu for the currently active window will appear. (Note: all keys
  20.     used by KeyMenu are configurable)  You can then use the cursor keys to
  21.     move through the menu as you choose.  When you have reached the menu item
  22.     you desire you can select it by pressing the return key.  If you change
  23.     your mind and decide not to select an item, the escape key can be used to
  24.     get out of the menu without making a selection.
  25.  
  26.  
  27.   Changes from previous version:
  28.  
  29.     - added an option to blank the intuition pointer when activating a menu.
  30.  
  31.     - KeyMenu can now coexist with 'mouse accelerator' programs without regard 
  32.       to what order you install them on the system.  KeyMenu has been tested
  33.       with dmouse, qmouse, mach and AmigaDos release 2.0 mouse accelerators.
  34.  
  35.  
  36.   Features:
  37.  
  38.     - remembers the mouse pointer's location when a menu is activated and 
  39.       repositions the mouse at that location when the menu is exited.
  40.  
  41.     - remembers the menu item that mouse was positioned on the last time the
  42.       menu was exited. When the menu is subsequently activated, you will be
  43.       positioned on that menu item. 
  44.  
  45.     - pressing the right mouse button while KeyMenu has a menu active allows
  46.       you to override KeyMenu and take over menu operations with the mouse.
  47.  
  48.     - Intuition's method of using the keyboard to simulate the mouse is not 
  49.       hindered. In fact, the key combination of left-alt/left-amiga can be
  50.       used to simulate the left mouse button while KeyMenu has a menu active.
  51.  
  52.     - key configuration and options can be changed at any time.
  53.  
  54.     - info option allows you to determine KeyMenu's key configuration and 
  55.       option settings at any time.
  56.  
  57.     - KeyMenu is completely re-entrant (pure).
  58.  
  59.     - compatible with all formal releases of AmigaDOS. 
  60.  
  61.     - qualifier key(s) can be used in conjunction with the move keys to
  62.       move to the first/last menu, menu item or menu subitem.
  63.  
  64.     
  65.   Installation:
  66.  
  67.     Two files are required, KeyMenu and KeyMenu-Handler. KeyMenu expects the 
  68.     KeyMenu-Handler program to be on either the L: directory or the current 
  69.     directory. Other than that there are no restrictions on where these files
  70.     can be placed.
  71.  
  72.  
  73.   Usage:
  74.  
  75.     KeyMenu must be run from the CLI. The first time that KeyMenu is
  76.     executed, it installs the KeyMenu-Handler on the system, processes any
  77.     command line options that may have been specified and returns to the CLI.
  78.     There is no need to use RUNBACK to execute KeyMenu, however, it won't
  79.     hurt anything if you do. Subsequent executions can then be used to either
  80.     change KeyMenu's configuration options or to terminate KeyMenu. The
  81.     following command line options are available:
  82.  
  83.       QUIT   terminates KeyMenu.
  84.  
  85.       ?      provides help information about the command line options
  86.              available.
  87.  
  88.       -i     displays KeyMenu's current key configuration and option
  89.              settings. This option is always processed last, i.e. after any
  90.              other options that may change the configuration have been
  91.              applied.
  92.  
  93.       -b     toggles the blank intuition pointer option.  When this option is
  94.              used, KeyMenu replaces the intuition pointer with a transparent
  95.              pointer whenever a menu is activated.  The pointer is restored 
  96.              to its original condition when the menu is deactivated.  The
  97.              only indication that you have as to where you are in the menu
  98.              is the highlighting provided by intuition.  This can become
  99.              confusing when you select a menu that contains disabled items
  100.              because the disabled items do not highlight when you move over
  101.              them.  This option defaults to OFF.
  102.  
  103.       -t     toggles the clear RMBTRAP flag option. The RMBTRAP flag is set
  104.              by programs that wish to use the right mouse button for their
  105.              own purposes rather than dedicating it to menu operations only.
  106.              A good example of this is DeluxePaint. With DeluxePaint, you can
  107.              use the right mouse button to draw with the background color. To
  108.              do menu operations, you must move the mouse pointer into the
  109.              title bar and then press the right mouse button. When
  110.              DeluxePaint detects that the mouse has moved into the title bar,
  111.              it clears the RMBTRAP flag in its window allowing normal menu
  112.              operations to take place. This option determines what KeyMenu's
  113.              action will be when you try to activate a menu and it's
  114.              associated window has the RMBTRAP flag set. If this option is
  115.              off, KeyMenu will not activate the menu. In the case of
  116.              DeluxePaint, the mouse pointer would have to be positioned in
  117.              the title bar in order to use KeyMenu. If this option is on,
  118.              KeyMenu will clear the RMBTRAP flag in the window before it
  119.              activates the menu. This allows KeyMenu to be used with
  120.              DeluxePaint without regard to the mouse's current position. This
  121.              option should be used with CAUTION. It is impossible to predict
  122.              how any particular program will react to someone else clearing
  123.              the RMBTRAP flag. DeluxePaint doesn't seem to mind. You might
  124.              want to run KeyMenu with this option off until such time that
  125.              you find an application that uses the right mouse button and
  126.              that you really would like to use with KeyMenu. Then try this
  127.              option making sure that you have a way of recovering if the
  128.              affected application crashes.  With DeluxePaint, its debatable
  129.              just how useful KeyMenu is anyway in an application that is so
  130.              mouse oriented. This option defaults to OFF if not specified.
  131.              
  132.       -p#    specifies the priority, in decimal, that should be used when
  133.              adding KeyMenu's input handler to the input device. This option
  134.              only has effect when installing KeyMenu. You cannot change the
  135.              input handler's priority once KeyMenu is installed without
  136.              terminating KeyMenu and re-installing it. Intuition's input
  137.              handler runs at a priority of 50. KeyMenu's input handler must
  138.              be higher than Intuition's so that KeyMenu can receive the input
  139.              events before Intuition does. If this option is not specified,
  140.              KeyMenu's input handler will have a priority of 51. This value
  141.              should be ok in almost all cases. This option is provided only
  142.              for completeness and in the off chance that Intuition's input
  143.              handler priority changes in some future release of AmigaDOS. Any
  144.              value other than 51 should be chosen with great care. Also, see
  145.              the section below about compatiblity with other input handlers.
  146.              
  147.       -q#    defines the qualifier key(s) that can be used in conjunction
  148.              with the move keys to move to the first/last menu, menu item or
  149.              menu subitem where # is a decimal value as follows:
  150.  
  151.                     1 - Left Shift          16 - Left Alt
  152.                     2 - Right Shift         32 - Right Alt
  153.                     4 - Caps Lock           64 - Left Amiga
  154.                     8 - Control            128 - Right Amiga
  155.  
  156.              Any combination of these keys may be specified by adding their
  157.              respective values together or this option can be completely
  158.              turned off by specifying a value of 0. When more than one
  159.              qualifier key is given, KeyMenu will honor either qualifier.
  160.              The various qualifier/move key combinations are interpreted as
  161.              follows:
  162.  
  163.                 Qualifier/Move Left  = move to the first menu in the menu
  164.                                        strip.
  165.                 Qualifier/Move Right = move to the last menu in the menu
  166.                                        strip
  167.                 Qualifier/Move Up    = move to the first menu item in the
  168.                                        current menu or subitem menu.
  169.                 Qualifier/Move Down  = move to the last menu item in the
  170.                                        current menu or subitem menu.
  171.  
  172.              For example, if the mouse is positioned on the 4th item of an
  173.              8 item menu list and a qualifier of 3 was given, pressing
  174.              either the Left-Shift/Cursor up or Right-Shift/Cursor up key
  175.              combination will cause the mouse pointer to move to the first
  176.              menu item in the list. KeyMenu defaults to the RIGHT SHIFT key
  177.              if this option is not specified.
  178.               
  179.       -a#    defines the key that will be used to activate (get into) a menu
  180.              where # is a valid key code taken from the table provided below.
  181.              This key is treated a little differently than the other keys
  182.              used by KeyMenu. To activate a menu, the activate key must be
  183.              pressed and then released without pressing any other intervening
  184.              keys. This allows key combinations involving the activate key to
  185.              be used by other programs without KeyMenu interfering. KeyMenu
  186.              defaults to the RIGHT ALT key if this option is not specified.
  187.  
  188.       -e#    defines the key that will be used to escape from (get out of
  189.              without making a selection) a menu where # is a valid key code
  190.              taken from the table below. KeyMenu defaults to the ESCAPE key
  191.              if this option is not specified.
  192.  
  193.       -s#    defines the key that will be used to select a menu item where #
  194.              is a valid key code taken from the table below. KeyMenu defaults
  195.              to the RETURN key if this option is not specified.
  196.  
  197.       -l#    defines the key that will be used to move left in the menu where
  198.              # is a valid key code taken from the table below. KeyMenu
  199.              defaults to the CURSOR LEFT key if this option is not specified.
  200.         
  201.       -r#    defines the key that will be used to move right in the menu
  202.              where # is a valid key code taken from the table below. KeyMenu
  203.              defaults to the CURSOR RIGHT key if this option is not
  204.              specified.
  205.         
  206.       -u#    defines the key that will be used to move up in the menu where #
  207.              is a valid key code taken from the table below. KeyMenu defaults
  208.              to the CURSOR UP key if this option is not specified.
  209.         
  210.       -d#    defines the key that will be used to move down in the menu where
  211.              # is a valid key code taken from the table below. KeyMenu
  212.              defaults to the CURSOR DOWN key if this option is not specified.
  213.         
  214.   
  215.     Valid key code values are as follows:
  216.  
  217.         Key Code    Key             Key Code    Key
  218.         --------    ---             --------    ---
  219.            0        `                  32       X
  220.            1        1                  33       C
  221.            2        2                  34       V
  222.            3        3                  35       B
  223.            4        4                  36       N
  224.            5        5                  37       M
  225.            6        6                  38       ,
  226.            7        7                  39       .
  227.            8        8                  3a       /
  228.            9        9                  3c       Numeric Pad .
  229.            a        0                  3d       Numeric Pad 7
  230.            b        -                  3e       Numeric Pad 8
  231.            c        =                  3f       Numeric Pad 9
  232.            d        \                  40       Space Bar
  233.            f        Numeric Pad 0      41       Backspace
  234.            10       Q                  42       Tab
  235.            11       W                  43       Numeric Pad Enter
  236.            12       E                  44       Return
  237.            13       R                  45       Escape
  238.            14       T                  46       Delete
  239.            15       Y                  4a       Numeric Pad -
  240.            16       U                  4c       Cursor up
  241.            17       I                  4d       Cursor down
  242.            18       O                  4e       Cursor right
  243.            19       P                  4f       Cursor left
  244.            1a       [                  50       F1
  245.            1b       ]                  51       F2
  246.            1d       Numeric Pad 1      52       F3
  247.            1e       Numeric Pad 2      53       F4
  248.            1f       Numeric Pad 3      54       F5
  249.            20       A                  55       F6
  250.            21       S                  56       F7
  251.            22       D                  57       F8
  252.            23       F                  58       F9
  253.            24       G                  59       F10
  254.            25       H                  5f       Help
  255.            26       J                  60       Left Shift
  256.            27       K                  61       Right Shift
  257.            28       L                  62       Caps Lock
  258.            29       ;                  63       Control
  259.            2a       '                  64       Left Alt      
  260.            2d       Numeric Pad 4      65       Right Alt
  261.            2e       Numeric Pad 5      66       Left Amiga
  262.            2f       Numeric Pad 6      67       Right Amiga
  263.            31       Z
  264.  
  265.  
  266.   Compatablity:
  267.  
  268.     KeyMenu has been tested with various shareware/public domain input
  269.     handlers (such as QMouse, DMouse, Mach, PopCLI and WKeys) and with 
  270.     all versions of AmigaDos including release 2.0.
  271.     
  272.     
  273.   Source:
  274.  
  275.     KeyMenu was written in assembler using Manx Aztec 68k Assembler, version
  276.     5.0d.  Since KeyMenu is being placed in public domain, I tried to keep 
  277.     the source pretty much generic so that anyone with an assembler could
  278.     assemble it. If you try to assemble the source you will have to make
  279.     changes to your intuitionbase.i include file. There are 2 fields in 
  280.     intuitionbase that KeyMenu references, MouseX and MouseY. They exist in
  281.     the C version of the include file, but not in the assembler version. I
  282.     added the following lines after the field ib_FirstScreen:
  283.  
  284.          ULONG   ib_Flags
  285.          WORD    ib_MouseY
  286.          WORD    ib_MouseX
  287.  
  288.     For Manx users, KeyMenu doesn't use any of the routines from c.lib. The
  289.     library is used in the link step only to resolve the _LVO externals. So
  290.     it doesn't matter which library, c.lib or c16.lib, that you use.
  291.     
  292.     The following source files are provided:
  293.  
  294.         keymenu.i           - include file for KeyMenu
  295.         keymenu-handler.i   - include file for KeyMenu and KeyMenu-Handler
  296.         macros.i            - misc. macros for both programs
  297.         keymenu.asm         - source for KeyMenu
  298.         keymenu-handler.asm - source for KeyMenu-Handler
  299.  
  300.  
  301.   Public Domain:
  302.  
  303.     KeyMenu and all of its associated source are public domain. You can do
  304.     what you choose with/to it. I would, however, like to know of any
  305.     problems that you encounter or enhancements that you might like to see.
  306.     Send mail to klowther on BIX if you are so inclined.
  307.     
  308.     I would like to thank the authors of DMouse, WKeys, QMouse etc. for 
  309.     making the source to their programs available. I incorporated many of
  310.     their ideas in the area of input handlers and process creation. Their
  311.     willingness to share their source code made writing this much easier. 
  312.  
  313.  
  314.     Ken Lowther
  315.