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