Club Amiga de Montreal

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

/ Club Amiga de Montreal - CAM / CAM_CD_1.iso / files / 575.lha / Menu_Helper / MenuHelper.doc.pp / MenuHelper.doc

Wrap

Text File | 1991-12-05 | 25.9 KB | 546 lines

MenuHelper ©1991 Ken Lowther MenuHelper is a release 2.0 commodity that allows easier keyboard access to menus than what Intuition provides. Intuition utilizes the Right Amiga-Right Alt key combination along with a cursor key to move the mouse pointer anywhere on the screen. This is a simple yet flexible approach, however, if you have ever tried to use it for menu selection you probably found it to be very cumbersome. Keyboard shortcuts are usually provided to invoke menu selections, but unless you use a particular program a lot its hard to remember all the key combinations from one program to the next. You then find yourself reaching for the mouse to see what menu options are available. With MenuHelper, all you need do is press the 'Activate' key combination and the menu for the currently active window will appear. You may then use the 'Move' key combinations to move through the menu as you choose. When you have reached the menu item you desire you can select it by pressing the 'Select' key combination. If you change your mind and decide not to select an item, the 'Deactivate' key combination may be used to exit the menu without making a selection. MenuHelper remembers the location of the mouse pointer when a menu session is started and repositions the pointer to that location when the session is ended. You can take over the menu session at any time by pressing the right mouse button. This causes MenuHelper to relinquish control of the mouse pointer. Workbench or CLI MenuHelper may be executed from either the workbench or the command line interface (CLI). Regardless of how MenuHelper is started, the tooltypes in MenuHelper's icon are always used to determine MenuHelper's initial configuration settings. Default configuration settings are provided, as described below, if a MenuHelper icon does not exist or if a particular tooltype does not exist in the icon. When executing MenuHelper from the CLI, command line options may be used to override the settings in MenuHelper's icon. These command line options take the same form as the icon tooltypes. Note that options containing embedded spaces must be surrounded by double quotes. For example, the following command could be used to override MenuHelper's icon settings: MenuHelper CX_POPUP=NO "ACTIVATE=ralt help" AUTOWRAP=NO Configuration Window A configuration window is presented upon startup, unless CX_POPUP=NO is specified as a command line option or a tooltype in MenuHelper's icon. It may also be activated by pressing the CX_POPKEY key combination or double clicking on MenuHelper's icon at any time subsequent to startup. This window allows you to alter the configuration settings that control MenuHelper's execution. It is divided into three major sections as follows: Key Definitions This section contains eight string gadgets that allow you to modify the key combinations that MenuHelper uses to activate, deactivate, select and move through menus. To modify a definition, you must activate it's associated string gadget by either clicking on the desired gadget or pressing the keyboard shortcut key defined for that gadget. The keyboard shortcut key is easily identified as it is the only underlined character in the text description of the gadget. Once activated, you may then enter the definition of the key/key combination that you wish to use. Refer to the 'Key Definition Expressions' section below for a description of valid expressions. After you have entered your new definition you must either press the return key to enter it or the tab/shift tab key to advance forward/backward to the next key gadget. Note that you must use one of these keys to exit a modified string gadget otherwise MenuHelper will not see the changes that you have made. Key definitions may be entered for each of the following: Activate - defines the key combination used to start a menu session. Deactivate - defines the key combination used to end a menu session without selecting a menu item. Select - defines the key combination used to select the menu item that you are currently positioned on. Up - defines the key combination used to move up in the menu. Down - defines the key combination used to move down in the menu. Left - defines the key combination used to move left in the menu. Right - defines the key combination used to move right in the menu. Modifier - defines the key combination used to modify the action of the 'Select' and 'Move' keys. Refer to "Modifier Key Definition" below for more information. Options This section contains six option boxes that depict the settings of various MenuHelper options. A checkmark appearing in the option box indicates that the option is 'turned on'. The option is 'turned off' if the option box is empty. You may change the setting of an option by clicking on the option box or pressing the keyboard shortcut key that is defined for the option. Again, the keyboard shortcut key is the underlined character in the text description of the option. The following options are available. Hide Pointer - Causes MenuHelper to turn off sprites whenever a menu session is started. Since Intuition's pointer is a sprite, this has the effect of hiding the pointer from view during the entire menu session. Sprites are turned on again when the menu session is ended. While the pointer is hidden, the only indication that you have as to where you are in the menu is the menu highlighting provided by Intuition. This can become confusing when you activate a menu that contains disabled items because the disabled items do not highlight when you move over them. The 'Skip Disabled' option described below can be used to minimize this problem. Skip Disabled - This option tells MenuHelper to skip over disabled menus, menu items and menu subitems. The following exceptions should be noted. If an entire subitem menu is disabled, MenuHelper will allow you to move into the subitem menu, but you will not be able to move around within subitem menu itself. This allows you to 'step through' the disabled subitem menu to get to the next menu. When starting a menu session, MenuHelper may position you on the menu item/subitem that you were on when the last menu session ended even if that menu item/subitem has been disabled since the last menu session occurred. Refer to the remember mode section below. Use Menu Bar - This option causes MenuHelper to position you in the menu bar when moving left or right from one menu list to the next rather than positioning you on the first available menu item in the list. This allows you to predictably move through the menus without having to step through any subitem lists that you may run into along the way. Auto Wrap - When this option is specified, MenuHelper will move to the opposite extreme when the start/end of a menu list is reached. For example, pressing the 'down' key combination when you are at the bottom of a menu list will move you to the top of the list. Remember Subitems - Tells MenuHelper to extend its remember mode to the subitem level. This means that if you were positioned on a subitem when you ended the last menu session, MenuHelper will reposition you on that subitem when you begin the next menu session. If this option is not specified, you will be positioned on the menu item that contains the subitem list. Note that this option has no effect if MenuHelper's remember mode is set to 'None'. Override RMBTRAP - RMBTRAP is a flag that is set by programs that wish to use the right mouse button for their own purposes rather than dedicating it to menu operations only. A common example of this can be found in most paint programs where the right mouse button is used for drawing in one color and the left mouse button is used for drawing in another. Usually, these type programs force you to move the mouse pointer to a certain area of the window, the title bar for example, if you want to access the menu. When they detect that the pointer is at that at that certain area, they clear the RMBTRAP flag allowing normal menu operations to take place. This option determines what MenuHelper's action will be when you try to activate a menu and it's associated window has the RMBTRAP flag set. If this option is turned off, MenuHelper will not activate the menu. If this option is turned on, MenuHelper will override the program and clear the RMBTRAP flag. This allows MenuHelper to be used with such programs without regard to the mouse pointer's current position in the window. This option should be used with CAUTION. It is impossible to predict how any particular program will react to someone else resetting their RMBTRAP flag. In other words, if you would like to try this option with a particular program, make sure you try it when you have nothing to lose if the program takes serious offense and crashes your machine. Remember Mode This section lists three modes of which only one may be selected. The selected mode defines to MenuHelper how much information to 'remember' about previous menu sessions. To modify MenuHelper's remember mode, you may click on the mode's gadget or press the keyboard shortcut key that is defined for the mode. The keyboard shortcut key can be easily identified as it is the only underlined character in the text description of the mode. When a new mode is selected, the gadget for the currently selected mode is automatically turned off. The three modes available are described as follows: None - With this mode, MenuHelper will not remember anything about previous menu sessions. Whenever a menu session is started, you will ALWAYS be positioned at the top of the leftmost menu. Last Menu - MenuHelper will remember where you were positioned in the last menu only. If you begin another menu session with that same menu, MenuHelper will reposition you in the menu where you were when the previous menu session ended. All Menus - MenuHelper remembers all menus. Whenever you start a subsequent menu session, you will be positioned in the menu where you were when the previous session ended. MenuHelper will remember the menu as long as the screen containing the window and menu remains open. There are four action gadgets placed along the bottom of the configuration window. These are used to convey to MenuHelper what action to take with regard to any modifications that you may have made. To select an action you may click on it's associated gadget or press the keyboard shortcut key that is defined for the action. The keyboard shortcut key can be easily identified as it is the only underlined character in the text description of the action. MenuHelper also provides a project menu containing menu items that correspond exactly to the actions described below. All actions cause the configuration window to be removed from view. The following actions are available: Save - This action causes MenuHelper to save the current configuration as tooltype settings in it's icon. If an icon does not exist for MenuHelper, one will be created. Also, any modifications that you have made to the configuation will take effect immediately. Use - With this action, modifications that you have made to the configuration are put into effect immediately, however, they are not saved in MenuHelper's icon. If MenuHelper is stopped and restarted, your changes will be lost. This action is handy for experimenting with different options and key definitions before deciding on any permanent changes that you would like to make. Cancel - This action causes MenuHelper to ignore any configuration changes that have been made and revert back to the settings that were in effect before the configuration window was activated. Quit - Tells MenuHelper to terminate. As with the 'Cancel' action, any configuration changes that have been made are lost. Key Definition Expressions Key definitions are a textual way of describing to MenuHelper what key/key combinations it should use to perform its functions. MenuHelper employs facilities provided by release 2.0 to parse the definition and determine if it is valid. Actually, release 2.0 allows you to describe all types of input events, i.e. mouse, timer, keyboard, etc. in this manner, but MenuHelper restricts you to specifying only keyboard events. The following discussion will therefore center on the definition of keyboard events only. For a complete description of input events in general, refer to the Commodities documentation provided with release 2.0. Key definitions take the form of a regular expression as follows: [class] ([-](qual|syn))* [[-]upstroke] [highmap|ANSICode] the * means zero or more occurrances of ([-](qual|syn)) where: [class] is an optional value that specifies the class of input event being defined. As stated earlier, MenuHelper only allows you to define keyboard events so you may either omit class altogether or use the keyboard class specification of 'rawkey'. qual is one of the strings in the table below. Each string corresponds to a qualifier key. A dash preceding the qualifier tells MenuHelper not to care if that qualifier is present in the input event. There can be more than one qualifier, or none at all, in the key definition. 'lshift' - left shift key 'rshift' - right shift key 'capslock' - caps lock key 'control' - control key 'lalt' - left alt key 'ralt' - right alt key 'lcommand' - left Amiga key 'rcommand' - right Amiga key 'numericpad' - a key on the numeric pad 'repeat' - a repeated key syn is one of the strings in the table below. These strings act as synonyms for groups of qualifiers. A dash preceding the synonym tells MenuHelper not to care if that qualifier is present in the input event. There can be more than one synonym, or none at all, in the key definition. 'shift' - left shift, right shift keys 'caps' - left shift, right shift and caps lock keys 'alt' - left alt, right alt keys upstroke is the literal string 'upstroke'. If this string is absent, MenuHelper considers only downstrokes. If present alone, MenuHelper considers only upstrokes. If preceded by a dash, MenuHelper considers both upstrokes and downstrokes. highmap is one of the following strings: 'space', 'backspace', 'tab', 'enter', 'return', 'esc', 'del', 'up', 'down', 'right', 'left', 'f1', 'f2', 'f3', 'f4', 'f5', 'f6', 'f7', 'f8', 'f9', 'f10', 'help' A note of caution. You should probably avoid using the help key in any MenuHelper key definitions. Release 2.0 provides what is known as the 'menu help' facility whereby pressing the help key while over a menu item can trigger the application to supply the user with help information about that menu item. This facility would be disabled if you define the help key to be used by MenuHelper for one of its functions. ANSICode is a single character, for example 'a'. The following are some example key definitions: 'rawkey -capslock alt backspace' The backspace key and either alt key pressed with or without the caps lock key. Only the downstroke of the key will be accepted. '-capslock -repeat alt backspace' The backspace key and either alt key pressed with or without the caps lock key. The downstroke of the key as well as any repeated keys (generated by holding the keys down) will be accepted. '-shift -alt -control x' The key that produces an 'x' with or without any shift, alt or control keys pressed. Modifier Key Definition The Modifier key combination provides a way to alter the action of the 'Select' and 'Move' keys. This option can be disabled by removing the modifier key definition in the configuration window or specifying MODIFIER= as a tooltype without a corresponding definition. The modifier key definition, when specified, must consist of only qualifier keys. These qualifiers may then be used in conjunction with the other key definitions as follows: Select - causes MenuHelper to do an extended select of the item you are currently positioned on. It is called an extended select because the item/subitem is selected without ending the menu session. You are then free to move through the menu and either select another menu item or do another extended select. Not all programs support extended selection. Usually programs that don't support extended selection will only honor the first selection that was made during the menu session. Up - causes MenuHelper to position the pointer at the first available item of the current item/subitem list. Down - causes MenuHelper to position the pointer on the last available item of the current item/subitem list. Left - causes MenuHelper to position the pointer on the first available item of the leftmost menu. Right - causes MenuHelper to position the pointer on the first available item of the rightmost menu. Icon Tooltypes A tooltype is defined for each of the definitions/options described in the configuration window. At startup, MenuHelper reads the tooltypes from the icon and alters its configuration settings accordingly. Your favorite settings may be configured using the WorkBench Icon/Information menu item or by simply using the 'Save' action gadget/menu item provided in the configuration window. The tool types that are recognized by MenuHelper are: CX_POPUP=YES|NO Specify whether the configuration window is to be brought up upon startup. CX_POPKEY=<expression> Name of Hot Key to bring up configuration window. See the Commodities documentation for more information. CX_PRIORITY=<number> Priority at which to run MenuHelper. See the Commodities documentation for more information. HIDEPOINTER=YES|NO Refer to the 'Hide Pointer' option above. SKIPDISABLED=YES|NO Refer to the 'Skip Disabled' option above. USEMENUBAR=YES|NO Refer to the 'Use Menu Bar' option above. AUTOWRAP=YES|NO Refer to the 'Auto Wrap' option above. REMEMBERSUBITEMS=YES|NO Refer to the 'Remember SubItems' option above. OVERRIDERMBTRAP=YES|NO Refer to the 'Override RMBTRAP' option above. REMEMBERMODE=NONE|LAST|ALL Refer to the 'Remember Mode' section above. ACTIVATE=<expression> Refer to the 'Key Definitions' section above. DEACTIVATE=<expression> Refer to the 'Key Definitions' section above. SELECT=<expression> Refer to the 'Key Definitions' section above. UP=<expression> Refer to the 'Key Definitions' section above. DOWN=<expression> Refer to the 'Key Definitions' section above. LEFT=<expression> Refer to the 'Key Definitions' section above. RIGHT=<expression> Refer to the 'Key Definitions' section above. MODIFIER=<expression> Refer to the 'Key Definitions' section above. DONOTWAIT This tooltype is actually used by WorkBench. If this option is present WorkBench will not wait for the program to finish. Useful when MenuHelper is moved to the WBStartup drawer for automatic activation when WorkBench is started. Default Configuration MenuHelper will use a default configuration if there is no icon information available for any given tooltype. The default configuration is intended to mimic the configuration of MenuHelper's predecessor, KeyMenu, as close as possible. The default configuration is as follows: ACTIVATE=-capslock alt backspace DEACTIVATE=-capslock esc SELECT=-capslock return UP=-capslock -repeat up DOWN=-capslock -repeat down LEFT=-capslock -repeat left RIGHT=-capslock -repeat right MODIFIER=shift HIDEPOINTER=NO SKIPDISABLED=NO USEMENUBAR=NO AUTOWRAP=YES REMEMBERSUBITEMS=NO OVERRIDERMBTRAP=NO REMEMBERMODE=LAST CX_POPKEY=shift help CX_PRIORITY=0 CX_POPUP=YES Release Information Release 37.1 Initial release Distribution MenuHelper is ©1991 Ken Lowther. It is freely distributable as long as all of it's files are included in their original form without deletions or modifications of any kind and only a nominal fee is charged for its distribution. This software is provided "AS IS" without warranty of any kind either expressed or implied. By using MenuHelper you agree to accept the entire risk as to the quality and performance of the program. Ken Lowther klowther on BIX for comments, criticism, enhancements etc.