The Datafile PD-CD 5/DATAFILE_PDCD5.iso/utilities/r/rapidkeys/!RapidKeys/!Help

Text File | 1994-11-13 | 22.2 KB | 587 lines

                            Function Key Handler
                            ====================

          (c) Copyright Peter Tuson 1992

This product is distributed as public domain. It be reproduced in
whole or part by any means without written permission of the author.

While every care is taken, the author cannot be held responsible for
any errors in this product, or for the loss of any data or
consequential effects from the use of this package.

RISC OS, ARCHIMEDES, DRAW and EDIT are trademarks of Acorn Computers
Limited.

OVATION is a trademark of BEEBUG Limited.

PIPEDREAM is a trademark of Colton Software.

All enquiries should be addressed to:

    Dr. P.R.Tuson
    70, Connaught Road
    Fleet
    Hants.
    GU13 9QY
    United Kingdom.

Release 1.3.4 June 1994 by Dr.P.R.Tuson.
Compatible with RISC OS 3.1 and above.

1.0 Introduction

!RapidKeys is a function key handler for the Acorn Archimedes series
of computers.

The purpose of !RapidKeys is to provide a simple but powerful
interface to the 12 function keys and the Print, Copy, Insert and
Delete keys, allowing them to be defined, displayed on the monitor
screen and activated, using the mouse, within the RISC OS environment.

!RapidKeys is designed to avoid the need for the function key strip
associated with the early series of Archimedes computers.

The keys may be programmed to send key sequences to the current focus
window thus allowing function keys for most applications to be
remapped to the user's requirements and extra functions keys to be
added to the application.

By using !RapidKeys the user may access the full set of function keys
by using one hand to operate the keyboard while the other is operating
the mouse.

1.1 Using !RapidKeys

The function key handler may be installed on the iconbar by double
clicking on the !RapidKeys application icon.

The functions defined within the resource file StdKeyDefs are then
loaded, together with the configuration file. The function keys are
then active.

Selection of the !RapidKeys icon on the iconbar toggles the display of
the function key mnemonics. !RapidKeys may be configured to display
the mnemonics immediately on loading.

The function key mnemonics may be displayed horizontally just above
the iconbar or vertically on the left or right hand side of the
screen. On loading, the default position of the displayed mnemonics is
read from the configuration file.

The !RapidKeys application is controlled by the RapidKeys menu
accessed by pressing the menu button while the mouse pointer is over
the !RapidKeys iconbar icon.

The functions of the menu options are as follows:

  Info provides current information about the application.

  Define opens a dialogue window allowing the operation of any of the
  function keys; F1 to F11, Shift F1 to Shift F11, Ctrl F1 to Ctrl F11
  and Ctrl Shift F1 to Ctrl Shift F11 and the additional keys; Print,
  Insert, Delete and Copy to be defined.

  Display controls the display of the mnemonics. When displayed any
  function key can be operated by selection of the key mnemonic. A
  tick indicates the state of the displayed mnemonics.

  Command opens a dialogue window allowing the entry of * commands, not
  defined by any of the function keys, from the keyboard.

  Configure opens a dialogue box allowing the operation of !RapidKeys
  to be tailored to the user's requirements.

  Save allows all the loaded key definitions to be saved to a file
  using the standard 'Save as' convention used by RISC OS
  applications.

  Quit removes the !RapidKeys application from the Task memory.

Double clicking on a Key Definition file causes the new definitions to
be loaded, the !RapidKeys application will be loaded if not already
resident and RISC OS has 'seen' the !RapidKeys application directory.

Multiple Key Definition files may be loaded.  The !RapidKeys
application will expand its memory requirement, as necessary, to load
additional Key Definition files.

The key definitions and the displayed mnemonics are linked to the task
controlling the current input focus window. Key definitions may be
loaded for all active tasks such that as the input focus is moved
between windows the displayed mnemonics change to reflect the
definitions for the new task.

Key definitions may also be linked to a dialogue box controlled by a
task. Again the displayed mnemonics are changed to reflect the new
definitions when the input focus is moved to the dialogue box.
Unfortunately clicking a mouse button outside a dialogue box
normally causes the dialogue box to disappear so the displayed
mnemonic keys cannot be used to send function key events to a dialogue
box.

If no window has the input focus or the task controlling the input
focus window has no key definitions defined or the dialogue box with
the input focus has no key definitions defined then the default key
definitions will be active.

A set of common key definitions may be defined that are common between
all tasks. These may be used to identify the functions of the F12 key
which is reserved for use by RISC OS.

!RapidKeys automatically chooses the optimum size of the displayed key
mnemonics according to the screen mode. The size is updated if the
screen mode is changed for any reason.

2.0 Installation

The !RapidKeys application is supplied on a single disc, the contents
of which are as follows:

   !Boot         RapidKeys !Boot file.
   !Run          RapidKeys !Run file.
   !RunImage     RapidKeys runtime code.
   !Help         Help text file.
   !Sprites      Directory of sprite files for the RapidKeys
                 application.
   Templates     Window and dialogue box templates.
   Resources
     Config      Startup state for !RapidKeys.
     Common      Key definitions used for all tasks.
     Default     Default key definitions.
     Draw        Example key definitions for !Draw.
     Edit        Example key definitions for !Edit.
     Ovation     Example key definitions for !Ovation.
     Pipedream4  Example key definitions for !Pipedream 4.
     Pendown+    Example key definitions for !Pendown+.
     Squirrel    Example key definitions for !Squirrel.
     SrcEdit     Example key definitions for !SrcEdit.
     StdKeyDef   Default Key definitions called up by !Run file.

It is recommended that the !RapidKeys disc is copied either to a hard
drive or to another floppy disc and the original stored in a safe
place.

To copy this application open a directory viewer on the destination
disc within the RISC OS Desktop and drag the !RapidKeys icon to the
destination directory in the normal manner.

Load !RapidKeys by double clicking on the application icon.

2.1 Memory Requirements

    Program Area 128K

2.2 Other Requirements

    RISC OS 3.01 or later.
    CLIB Version 3.99 or later.

3.0 Detailed Operation

On selection of a displayed function key mnemonic with the mouse
button !RapidKeys processes the definition associated with the
function key.

If the definition is null then a key press event is sent to the Task
Manager for onward transmission to the application controlling the
current input focus window.

The Shift and Control keys can be used to modify the action of the
function keys.  The pressing of one or both of these keys results in a
change to the displayed mnemonics.

If a function key is pressed on the keyboard the event is sent, by the
Task Manager, directly to the application controlling the input focus
window. Correctly behaved applications will then pass unrecognised key
presses on for later processing by 'Hot Key' applications. In this
event !RapidKeys will process the definition associated with the
function key, if the definition is null then the key press will be
passed on.

In summary the displayed function key will always be operated on
selection whereas the keyboard function key will only be operated if
the application controlling the current input focus window passes the
key press on for 'Hot Key' applications.

F12 may be given a mnemonic but definition of this key is disabled to
allow RISC-OS full access.

The Define Key dialogue box, accessed by selection of the 'define'
iconbar menu option, allows definition of the keys corresponding to
the task controlling the input focus window. If no window has the
input focus then the default set of key definitions may be entered.

The save iconbar option will save all of the key definitions
previously loaded, in alphabetical order, to the indicated file.

3.1 Configuration

The operation of the !RapidKeys application can be modified by the use
of the Choices menu option.

Currently this allows control of position, visibility and startup.

When the required configuration has been selected then the Set button
will set the configuration for the current invocation. This may result
in a change to the displayed mnemonics.

The Save button will both set the current configuration and save the
configuration within the Resource directory.

3.1.1 Position

The mnemonic function keys may be displayed horizontally, just above
the iconbar, or vertically, on the left or right hand side of the
screen. This corresponds to the 'Bottom', 'Left' and 'Right' options
within the Position box in the lower portion of the dialogue box.

3.1.2 Visibility

The visibility is controlled by the buttons within the Cover box and
allows the function key mnemonics and iconbar to remain visible when
windows are grown to full screen.

Visibility control is enabled when the on/off button is depressed.

One of 'Raise Focus Window' or 'Lower Key Mnemonics' may be activated.

The 'Raise Focus Window' control may be used in whatever position the
function key mnemonics are currently displayed but the action depends
on the position.

If the mnemonics are displayed horizontally, above the iconbar, then
the !RapidKeys application will move the bottom boundary of any window
opened to the full screen extent to just above the position of the
mnemonics.

If the mnemonics are displayed vertically, on the left or right, then
the !RapidKeys application will move the bottom boundary of any window,
opened to the full screen extent, to just above the iconbar and the
left or right boundary of the window to the right or left of the
mnemonics.

The 'Lower Key Mnemonics' control is only applicable when the
mnemonics are displayed horizontally, above the iconbar. In this case
the function key mnemonics are then moved to the bottom of the screen
and the bottom boundary of the window to just above the position of
the mnemonics. When the window is returned to a smaller size the
function key mnemonics are returned to their normal position above the
iconbar.

Note that visibility control will not effect fully open windows that
do not cover the full screen size, or any other window, that may be
positioned over the function key mnemonics.

3.1.3 Startup

The startup control is activated when the 'Startup' button on the
right hand side of the configuration box is depressed.

Startup control causes the function key mnemonics to be displayed
immediately on initiation of the !RapidKeys application.

3.1.4 Popup

The popup control is activated when the 'Popup' button on the
right hand side of the configuration box is depressed.

When Popup is enabled the entry of a keyboard character causes a
command entry dialogue box to be opened on the screen to allow
entry and operation of a command string.

3.2 3-D Interface

The function key mnemonics appear on 3 dimensional buttons that
depress when the mouse select button is clicked, similar to the
!Impression interface and now supported by RISC OS 3.

This 3 dimensional look and feel is carried across to all windows
controlled by !RapidKeys.

3.3 Defining Key Functions

The mnemonic and action of function keys may be defined using the
define dialogue box.

The dialogue box is used to define the mnemonic and action of function
keys for the task controlling the window with the input focus. If no
window has the input focus then the dialogue box is used to define
function keys for the 'Default' task.

The right and left arrow icons can be used to sequence through the
function keys.

Alternatively, and more conveniently, any function key can be
identified by pressing the corresponding keyboard function key (in
conjunction with the shift and control keys as necessary).  The
dialogue box will then show the current definition for that function
key.

While the function key is identified in the dialogue box it can be
given a definition or redefined.

    Enter the mnemonic for the function key in the name field, this
    accepts a string of up to fourteen characters.

    Enter the action for the function key in the function field, this
    accepts a string of up to 255 characters.

Both the name and function fields provide full editing features for
the entered string, as follows:

  Delete      delete character to the left of caret.
  Copy        delete character to the left of caret.
  <-          move caret left one character.
  ->          move caret right one character.
  Shift Copy  delete word (forwards).
  Shift <-    move left one word.
  Shift ->    move right one word.
  Ctrl Copy   delete to end of line (forwards).
  Ctrl <-     move to left end of line.
  Ctrl ->     move to right end of line.

Definition of a function key can be aborted by selecting the CANCEL
icon.

The definition of the identified function key is actioned by selecting
the Define icon or pressing the <CR> key at the end of the function field.

The function key definition is then loaded, the displayed mnemonics
may change.

If the Define icon is actioned with the ADJUST button then the define
dialogue box will remain displayed so that additional function keys
may be defined.

3.4 Mnemonic Format

In order to take advantage of the increased number of characters
available within the displayed mnemonic on higher definition screen
modes the '_' and '.' characters can be used to delimit optional
sections of the mnemonic text.

The minimum width available to a mnemonic in any mode is 5 characters.

This is best explained by use of a example.

F3S is commonly used to insert a file at the cursor position.  The
mnemonic for this can be defined as 'Ins_e.rt_File'.

As a minimum the _e. and _File will both be ignored at the displayed
mnemonic will be 'Insrt', i.e. no more than 5 characters.

In a higher definition mode 9 characters may be available, in this
case the first optional text will be accepted and the displayed
mnemonic will be 'Insert'.

Finally in screen modes where 10 or more characters are available the
displayed mnemonic will be 'InsertFile'.

The actual mnemonic, most suitable for the current screen mode, is
found by scanning the definition and inserting optional text from left
to right until additional insertion would result in an oversized
mnemonic.

Optional text is identified by an '_' character at the start and a '.'
or ' ' character at the end, the '.' character must be used if there
is following text.

3.5 Command Format

Commands use the standard command line syntax of RISC OS and may be
followed by one or more parameters.

The defined action of a function key may consist of one or more
commands separated by the ';' character.

!RapidKeys processes the commands Echo, Eval and Menu internally, all
other commands are passed to RISC OS for action.

  Echo causes the following character string to be translated using
  OS_GSTrans and then output to the task controlling the window with
  the input focus.  This is equivalent to the *Echo command.

  Eval causes the following character string to be translated using
  OS_EvaluateExpression and then output to the task controlling the
  window with the input focus.  This is equivalent to the *Eval
  command.

  Menu causes the following character string to be transmitted to the
  task controlling the input focus window as a 'Menu Selection' event.
  This is equivalent to selected a pop up menu option within the input
  focus window. In this case the character string consists of a
  sequence of comma separated numbers, the first number identifies the
  selected item in the main menu (starting from 0), the second the
  selected item in the first submenu and so on. Thus the full path to
  the required item can be specified.

After translating the Echo and Eval commands the RapidKeys application
interprets some characters internally.

  & following by 3 hexadecimal characters is encoded into a single
    character before being output to the controlling task.

  @ stores the index position of the cursor in the input focus
    window assuming that the system font is being used.

  % outputs the previously stored index position as a string of
    characters to the controlling task.

The characters &, @ and % can be output to the contolling task by
preceding with &, e.g. &@ will output @.

The delimiter character ';' can be output by enclosing the character
string in quotes, e.g "abd;de".

In order to pass the commands *Echo and *Eval to the operating system
use the lower case form, i.e. echo and eval.

3.5.1 Example

As an example consider the 'C' KeyDefs file provided, this contains
the lines.

    task Edit
    key F1SC   ©               Echo Copyright Dr.P.R.Tuson <Sys$Year>
    key F2SC   Date            Echo <Sys$Date> <Sys$Year>
    key F3SC   Time            Echo <Sys$Time>
    key F4SC   Year            Echo <Sys$Year>
    key F5SC   if              Echo "&196@if()
                                    {|M&186}|M&186&1A4&1AC&1AB%|M&196"
    key F6SC   for             Echo "&196@for (;;)
                                    {|M&186}|M&186&1A4&1AC&1AB%|M&196"
    key F7SC   while           Echo "&196@while ()
                                    {|M&186}|M&186&1A4&1AC&1AB%|M&196"
    key F8SC   proc            Echo static void procname ()|M{|M}|M

The first line indicates that these key definitions are intended for
windows controlled by the !Edit application.  This name must be
identical to the task name used by the application, this can be
identified using the Task display window from the Task Manager. If the
task name contains embedded spaces then these should be replaced by
the non-blank space with HEX code A0, this can be typed using the key
sequence 160 with the Alt key pressed down.

The remaining lines program the function keys Ctrl Shift F1 to Ctrl
Shift F8.  When this file is loaded into the !RapidKeys application
these definitions will be added to any definitions for the !Edit
application already defined. If one or more of the function keys have
already been defined then the new definition will replace the older.

The function key Ctrl Shift F1 is programmed with the string:

   Echo Copyright Dr.P.R.Tuson <Sys$Year>

The '<>' characters cause Sys$Year to be looked up as a system
variable, so that if this function key is activated the string

   Copyright Dr.P.R.Tuson 1994

may be output to the input focus window.

The function key Ctrl Shift F6 is programmed with the string:

  Echo "&196@for (;;) {|M&186}|M&186&1A4&1AC&1AB%|M&196"

This is intended to output the sequence

   for (;;) {
   }

to the input focus window at the current cursor position.

The echoed string is quoted because it includes the delimiter
character ';', &196 corresponds to Shift F6 which clears any currently
defined block then @ causes the current cursor index position to be
saved.  Next the first line of the string is output - for (;;) {|M.
The start of a block is then marked with the code &186, corresponding
to F6, and the second line is output - }|M.  The end of the block is
then defined with the code &186.

The code &1A4 corresponds to Ctrl F4 and causes !Edit to open the
Insert Window, this becomes the input focus window.  The codes &1AC
&1AB clear the Insert Window of its contents and % inputs the string
for the original cursor index position.  The return code |M actions
the insert and the marked block is indented to the original cursor
position.

The final code &196 clears the marked block.

3.6 Command Entry

Commands may be entered directly, without recourse to the command
line, by using the command entry dialogue box.

If no window has the input focus, i.e. contains the caret, then the
command entry dialogue box will be displayed on entry of the first
character of the required command.  Otherwise the dialogue box can be
opened using the command option in the RapidKeys icon menu.

The dialogue box will accept a command string of up to 255 characters.

Multiple commands can be entered in the command string, separated by
the ';' character.

The dialogue box provides full editing features for the entered
string, as follows:

  Delete      delete character to the left of caret.
  Copy        delete character to the left of caret.
  <-          move caret left one character.
  ->          move caret right one character.
  Shift Copy  delete word (forwards).
  Shift <-    move left one word.
  Shift ->    move right one word.
  Ctrl Copy   delete to end of line (forwards).
  Ctrl <-     move to left end of line.
  Ctrl ->     move to right end of line.

The entered command can be aborted by selecting the CANCEL icon.

The command is actioned by selecting the OK icon or pressing the <CR>
key. Any output text not destined for the input focus window is
displayed within a mode 4 window.  If the OK icon is actioned with the
ADJUST button then the command dialogue box will remain displayed.

4.0 File Types

!RapidKeys recognised standard ASCII text files of type FFF.

5.0 Limitations

Operation with RISC OS 2 has not been checked.

6.0 Modifications
V1.2.0 March 1991
  Copied from !Keys to generate full multi-tasking version by identifying
  window with icon focus and relating back to controlling task.
V1.2.1 January 1992
  Various bug fixes.
V1.2.2 July 1992
  Use of Interface module to provide a 3-Dimensional display.
  Use of higher definition screen modes has been improved by automatic
  scaling of the key mnemonics and by allowing optional sections within
  mnemonic text.
  The Save function now conforms to the RISC OS operation by supplying
  the previous saved filename, on startup this is the StdKeyDefs file.
  A Configuration menu has been added.
  The key mnemonics may be automatically displayed on startup.
  KeyDef files have been moved to the Resources directory.
V1.2.3 December 1992
  Updated to conform to RISC OS 3.1.
V1.3
  Allowed key mnemonics to be on either side or bottom of sceen.
  Added support for Print, Insert, Delete and Copy keys.
V1.3.1
  Introduced Common Task and support for Desktop Boot Files.
  Addition of the Menu command.
V1.3.2
  Changed KeyDefs file type to TEXT.
  Conform to Style Guide.
  Some bug fixes.
V1.3.3
  More bug fixes.
V1.3.4
  Suppress definition of F12.