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
|
27KB
|
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.