Fast Keys

by Gary Lee

Version 1.10

for RISC OS 3.1 or later

Fast Keys enables the user to create and maintain hot-key definitions easily, with the added facility of being able to attach menu selection short-cuts to applications which don't already have them. Fast Keys offers the following features:

	 Hot-key definitions held in a script file
	  for easy editing
	 Conditional execution of key-presses
	  depending on the pointer position
	 Key-presses can be made to open menus
	  to any level and choose a selection
	 Key-presses can 'click' on a specified
	  icon in a given open window
	 Flexibility, enabling the user to add
	  commands via the Functions file
	 Some useful pre-defined hot-key
	  definitions are already provided

Getting started
It is advisable to read this file first and then to define your own hot-keys as required. However, a few useful definitions are already provided in the Default file.

The program can be run from the RISC User menu system or by double-clicking on its icon in a filer window. When the application is running it will appear in the task manager display, but no icon appears on the icon bar. Therefore, to quit the program (which shouldn't really be necessary unless you're having technical problems), just click menu over the Fast Keys entry in the task display and choose Quit.

Probably the most frequent type of key definition you will want to use will be to start up an application. For example, if you often suddenly feel the urge to have a game of chess against the computer, then what can be more convenient than to be able to run your favourite chess game on the press of a key instead of having the chore of moving all the windows out of the way and rummaging through the directories? Here is an example of the most simple of key definitions:

	Key=&3
	StartTask("ADFS::4.$.Games.Chess.!Chess")

The first line is the condition line, and simply translates to:

	IF <Ctrl-C> is pressed THEN execute the
	commands on the following lines.

The second line translates to:

	Run "ADFS::4.$.Games.Chess.!Chess" as a task.

The StartTask command is actually one of the predefined functions in the Functions file, and is described below. Therefore, in this case, Chess will start up whenever <Ctrl-C> is pressed.

Note that there are no conditions ensuring the position of the pointer. However, one command in which the pointer conditions are important is the Menu command described below.

How to define or modify a hot-key definition
Open the Keys script file using a text editor and define away!

Each hot-key definition is written as a condition line which contains the key number as returned by the Wimp Key_Pressed (8) event and pointer information, followed by the commands to execute on separate lines. See the Keys file for the full syntax of a hot-key definition. For currently-defined commands and functions, see the Functions file.

Notice that any syntax errors in the condition line will be reported when Fast Keys is run. Any errors in the commands such as mismatched brackets or invalid paramaters will only be reported when attempting to execute them.

Default commands
The following gives details of the pre-defined commands supplied with the release version 1.10 of Fast Keys.

Menu(String$)
This is probably the most useful of all the commands, as it enables a submenu to be opened to any required level and a selection chosen on the press of a key. The only parameter is a string which contains comma-separated numbers indicating the item to choose. The first number gives the item in the main menu (starting from 0), the second number gives the item in the first submenu, and so on to any level.

As an example, the Paint application has no key short-cut for selecting the colour under the pointer; the user must first open two levels of menus, then position the pointer over Select colour and click Select. This command allows a key short-cut to be attached to version 1.61 of Paint. The complete hot-key definition is given thus (NB the first line has been split for clarity):

	Key=&18B,TaskName="Paint",
		WFlags=&FF000002,WColours=&FF070207
	Menu("2,1")

When the user presses the <Copy/End> key (providing that no other application claims it), Fast Keys uses a quick cross-check to an internal bit array to confirm that this key has been defined, and proceeds to check the remaining condition line. If a key is pressed which isn't defined, FastKeys returns immediately and passes the key on via Wimp_ProcessKey.

Then the pointer information is read in. IF the pointer lies over a Paint window and IF that window's flags match &FF000002 (ignoring bits 16 to 21) and IF that window's colours (word at +32 of the window block) match &FF070207, THEN the Menu("2,1") command is executed. The main menu is opened by sending a menu button mouse click message to Paint at the pointer's current position, followed by a menu selection message containing the values 2,1 and the terminating -1. This is actually what also happens from Paint's point of view when the user performs the intended function manually. The menu tree is then closed.

Please note that it's important to give all the necessary pointer conditions before executing the Menu command in order to isolate the applicable window. For example, in this particular case, if the WColours condition is not given, the same command could be sent to Paint's Colours window (if that is where the pointer is) because it has the same window flags; and consequently Paint would receive an innaplicable menu selection message which it might not be able to handle. Another example is that if the task name is missing, then the same menu selection message could be sent to any window that the pointer is over (if the other conditions match), which is really not desirable under any conceivable circumstances.

See ShowPointerInfo below for how to obtain a window's flags for use in a hot-key condition line.

IconClick(Task$,Title$,IconNr%)
This command is generally given without any pointer conditions attached because it enables the user to 'click' on a specified icon in a given task's window with a given title, wherever the pointer may be and as long as the destination window is open.

Task$ contains the name of the task, Title$ contains the title string of the window (so this command won't actually work very well on windows which vary their titles; for example, in a document processor which stores the currently-loaded file's pathname in the title), and IconNr% contains the number of the icon, found using the ShowPointerInfo command.

ShowPointerInfo
This displays appropriate pointer information which can then be used when defining new hot-keys.

StartTask(Command$)
This command executes a *Command as a sub-task, where Command$ is the command string. This is particularly useful for starting up applications: simply give the full application directory pathname as the Command$ (e.g. by shift-dragging the directory into an editor window).

Filer_OpenDir(Directory$)
This command opens a given directory display, which is useful if the user accesses certain directories relatively frequently. It actually calls the StartTask function with "Filer_OpenDir"+Directory$ as the parameter.

Directory$ gives the directory pathname.

ShowInkeys
This is useful to programmers who need to know negative INKEY values.

RestoreWimpMode
This simply changes the desktop mode to the configured value.

LoseCaret
This causes owner of the caret to disown it and therefore to guarantee that all future key-presses will be processed by Fast Keys until the caret is gained again.

It can be useful if, say, an editor's window is open and the user wants to execute a hot-key command. It is sensible to use the F11 key for this command, since F11 is reserved as a user hot-key and so is guaranteed to be available; unless, of course, another hot-key program is running which uses it (or an application which does not conform fully to style guidelines).

Beep
Beep might be used as the last in a list of commands to inform the user that something has happened.

MovePointer
This enables to user to position the mouse pointer precisely, in a similar way to the nudge facilities in Draw.

Adding extra commands
For the ultimate in flexibility, commands are held in a separate Functions file as Basic function definitions.

To add a command, simply edit the Functions file using an appropriate editor such as DeskEdit or Zap, and then add your new command as a function. The name of the function must begin with a '`' (grave accent) followed by the name of the new command. For example, to add a command called Quick with no parameters, the first line of the function definition must be DEFFN`Quick. The function must exit using =0. The reason for the grave character is to avoid accidental duplication of function names with those in the main program.

The new command can now be used in the Keys script file.

How to effect any changes to the Keys or Functions files
Simply re-run Fast Keys; the old copy will quit automatically.

Fast Keys version 1.10
Fast Keys can now cope with badly written/behaved applications such as those which like to send wild key values via Wimp_ProcessKey and those which indirect their window data into 'weird' memory locations.

Copyright  RISC User 1996