Really Useful CD 1/ReallyUsefulCD1.iso/extras/utilities/_keywindow/_help

Text File | 1992-04-21 | 17.3 KB | 462 lines

Key Window (v 1.25)
by Richard G. Hallas

This application is Public Domain. The author's own
help text is given below.
____________________________________________________


This program provides an on-screen function keystrip
in a window. It should prove useful to owners of
A3000s, A5000s and A540s who do not have keystrip
holders on their keyboards, but it does more than
that: you can 'press' the keys by clicking on them
with the mouse, and Key Window can keep track of a
list of up to 32 keystrips, opening and closing them
automatically as you load, use & quit applications.

To use:
-------

Load by double-clicking in the usual way. If you are
in the habit of booting up a number of applications
when you switch on, then you might like to include
Key Window near the beginning of your boot-up
sequence so that it can keep track of other
applications starting up, and open keystrips for
them.

Once loaded, clicking SELECT on the icon-bar icon
will open a keystrip window; either the first one
on the list, or the last one shown if you closed a
strip which was opened automatically. (If you ignore
Key Window, and load DeskEdit [for example] a
keystrip will appear anyway, since DeskEdit is
defined as one of the applications for which Key
Window has a keystrip.) The keystrip will appear
behind other windows so that it is inobtrusive, but
you can easily bring it to the front by clicking
its title bar in the usual way.

Pressing the hot-key combination <SHIFT-CTRL-TAB>
or <CTRL-SHIFT-INSERT> will toggle the keystrip
between the front and the back of the desktop.
(The hot-key may not work if an application such
as DeskEdit has the input focus; it is for this
reason that there are two version of the same
hot-key.)

In addition to opening and closing keystrips when
you load and quit applications, Key Window is also
'context sensitive', and will update the contents of
the keystrip window according to whichever program
currently owns the caret. If a program which does
not have a keystrip defined claims the caret, then
the keystrip will be closed, but if the caret is
turned off completely, then the last keystrip used
will continue to be shown.

The icon-bar menu has the usual 'Info' and 'Quit'
options, along with two others: 'Keystrips' and
'Options'. The first of these provides access to an
'Applications' submenu, and choosing an application
from this menu will open a keystrip for it. By
default, the following applications are provided:
DeskEdit, Impression II, Draw Plus, Poster, Edit,
Notate, Rhapsody, Acorn DTP, DisAssem, BASIC Editor
and the Charm Editor. The BASIC Editor is configured
to open with the Data Store's excellent front-end
for the ARMBE BASIC Editor, but can of course do
nothing more than serve as a reminder, since ARMBE
is a single-tasking application which takes over the
whole screen. This is also true of the Charm Editor.

The other icon-bar submenu, 'Options', governs how
the keystrip window will operate. The options are as
follows:

à 'Open at top': If this is ticked, the window will
 always appear at the top of the screen; otherwise
 it will appear just above the icon bar, or wherever
 you put it last.

à 'Auto scroll': This makes the keystrip window
 behave in the same way as the icon bar does when it
 is full; that is, it scrolls sideways automatically
 when the pointer is moved to the left and right
 hand edges.

à 'Scroll bar': This toggles the horizontal scroll
 bar and size icon; if 'Auto scroll' is selected,
 then the scroll bar is unnecessary, but you may
 wish to use it to get from one side to the other
 more quickly.

It is not possible to deselect both 'Auto scroll'
and 'Scroll bar' at the same time, since it would
obviously then be impossible to move from one side
of the keystrip to the other.

The last two options are separated from the others
by a dotted line, and they govern the way the
'context switching' aspects of the program work.

à 'Sense caret': If this option is selected, the
 keystrip will be fully context sensitive, and as
 the input focus moves between windows, the keystrip
 will change to reflect its position. (Note that for
 the sake of simplicity, the program's menu refers
 to the 'caret' when it actually means the 'input
 focus'; there doesn't really have to be a physical
 caret. A good example is of this Draw Plus, which
 only shows a caret when entering text objects; the
 keystrip nevertheless still applies.)

à 'Sense apps': If this option is selected, Key
 Window will open and close strips as applications
 are loaded and quit. Since this could potentially
 interfere with the context switching option above,
 then if the 'Sense caret' option is on, the 'Sense
 Apps' option will only work if a keystrip is not
 currently in use.

All this makes Key Window sound very complicated,
but you should find it quite easy and natural to
use.

Regardless of the state of these options, whenever
the window is opened, or the screen mode is changed,
it will appear behind the other windows, and will
resize itself to fit the current width of the
screen. The default settings of these options can be
defined by editing the !Run file; see that file for
details, and also later in this !Help file.

On to the keystrip window itself. Clicking any of
the key definitions with SELECT or ADJUST will
'press' that key. If you are not using the 'context
switching' features you should remember that the
same key is pressed regardless of whatever strip is
showing; you may for example have the keystrip for
Edit on the screen, but if you are currently using
Impression, then clicking on <CTRL-F4> will bring up
the Find/Replace box rather than doing an Indent
Block in Edit.  This seems obvious, but it's easy to
forget. They're the same keys, regardless of how
they're labelled.

Since <CTRL-SHIFT-F12> is a dangerous keystroke (it
normally exits the desktop), I have made the icon as
difficult to click by accident as possible. To
activate it, you must do a Drag-click within the
icon: i.e. click the mouse, hold down the button,
move the mouse a small distance within the icon,
release the button and click again.

The keystrip window has its own menu so you can edit
the strips and create new ones. The menu options are
as follows; I shall deal with them in turn:

à Edit item: this is context-sensitive, and only
 appears when you click over a key label. Enter the
 contents in the submenu leaf; up to 16 characters
 are allowed for each.

à Edit title: this allows you to edit the title of
 the keystrip; the title will be used in the
 keystrip window and in the 'Applications' menu.

à Get strip: this is the same as the 'Keystrips'
 option on the icon-bar menu, and updates the window
 with whichever keystrip you choose. Any unsaved
 contents of the keystrip window will be lost if you
 use this option. The only difference here is that
 the keystrip is opened at the front, whereas it is
 opened at the back when you select a strip from the
 icon-bar menu. You should note that if the 'Sense
 caret' option is on, then using either of these
 application keystrip menus will lose the input
 focus. If it didn't, then the keystrip would change
 back to the one needed for the current application
 as soon as you had selected a different one.

à Clear strip: this blanks the strip to give you a
 fresh start. The two usual functions of F12
 (Command line & Exit desktop) are entered for you
 automatically, but you can delete them if you wish.

à Open with?: entering a taskname (as it appears in
 the Task Display window) into this submenu will
 make that strip open and close automatically when
 you use a particular application. Leave the option
 blank if you do not wish this to happen, but
 remember that this will disable the context switch
 facilities for that particular application.

à Save strip: there are two ways of saving
 keystrips, which you must choose from the submenu
 (clicking on 'Save strip' alone will do nothing).
 Firstly, 'Replace old' will overwrite the existing
 definition with your edited version, so you can
 easily add to a strip or correct it. (This option
 is unavailable if you have used 'Clear strip'.)
 Secondly, 'Create new' will save a totally new
 keystrip and add it to the 'Applications' menu.

Notes on saving new strips
--------------------------

When saving a new strip, the data is saved into a
text file within the 'Data' directory in the
!KeyWindow application directory. If you use the
'Create new' save option, Key Window will save the
file with a numeric filename, starting at number
'0'. If '0' exists, then it uses '1', and so on. If
there are 32 files in the directory, then Key Window
will not allow you to save a new strip, only
overwrite existing ones. When Key Window starts up,
it reads in the contents of all the files in the
'Data' directory, in the order in which they appear
in the directory viewer; this is also the order they
will appear in the 'Applications' menu. If you want
a particular strip to always be first on the
'Applications' list (and therefore be the default
one to use when you click on the icon-bar icon) you
should make sure it is the first to appear in the
directory viewer; using the name '!' should ensure
this. It doesn't actually matter what you call the
files; the program just uses numerics for the sake
of simplicity.

If you wish to create your function key files in
DeskEdit, say, and not with Key Window itself, the
file format is as follows:

à The first line is the title of the application
 (max. 20 characters) to appear in the window title
 and 'Applications' menu.

à The second line is either blank or a taskname
 (max. 19 characters) for the strip to open
 automatically.

à The remainder of the file has up to 12 lines, one
 for each key. If a line is blank, that key will
 have no labels. Not all 12 keys need to be defined:
 you use only as many lines as the keystrip
 requires.

 Each line has up to four entries, separated by
 commas: for the key alone, and in conjunction with
 Shift, Ctrl and Ctrl-Shift. You need only enter as
 many labels as necessary, so you can finish a line
 before Ctrl-Shift, for example. Each line should
 therefore contain 0 to 3 commas. Note that if, say,
 a particular key has no function alone, but has a
 function in conjunction with Shift, the definition
 line should start with a comma.

Note also that although spurious commas are not
necessary, they do not matter, and indeed if you
save a definition file from the program, every line
it produces will contain three commas.

Setting options with <KeyWindow$Flags>
--------------------------------------

Key Window can be made to start up every time with a
certain combination of options already in effect.
You must edit the !Run file in the application
directory to achieve this. Alter the number in the
line 'Set KeyWindow$Flags 27' (The value of 27 is
the default if you omit this line or enter an
illegal value). The variable sets the default state
for the five settings which can be temporarily
toggled on and off in the 'Options' submenu.

The <KeyWindow$Flags> variable is a decimal number
in the range 0 to 31, which is calculated from the
following set of bits, which mean, when they are
set:

   Bit 0: Always open keystrip at top of screen.
   Bit 1: Scroll strip when pointer reaches edges.
   Bit 2: Show horizontal scroll bar, along with a
          resize icon and a toggle size icon.
   Bit 3: Context sensitive: applications gaining
          the caret will open new strips.
   Bit 4: Load sensitive: applications starting up
          and quitting will open and close strips.

So, for example, if you wanted just 'Open at top' &
'Scroll bar' on by default, you would use the value
5, since you would be setting bits 0 and 2, and 5 is
the decimal equivalent of binary 101.

Do note that the bits are in descending order:
namely, bit 0 is the one on the right.

Note also that any values with bits one and two both
set to zero are invalid, since they would mean that
both the 'Auto scroll' and the 'Scroll bar' options
were off, and the program will not allow this. The
smallest value you may use is 2, and if you try to
use an illegal value the program will automatically
turn on 'Auto scroll' for you.

If you examine the !Run file further, you will find
another variable, <KeyWindow$DummyMessage>. This is
a message number for internal use. It should always
be an unassigned message; if at some point in the
future this message is assigned a use, it will be
necessary to amend this variable to avoid conflicts.
This is very unlikely, though.

Finally
-------

So there you have it - what I hope is a useful
program! This is PUBLIC DOMAIN SOFTWARE and as such
may be distributed quite freely, just as long as it
is not modified or tampered with in any way, and all
the associated files are kept together unmodified.

The !KeyWindow directory should contain the
following files:

!Boot
!Help  (This file)
!Run
!RunImage
!Sprites
Data
Source
Sprites
Templates

The Data sub-directory should contain at least the
files numbered '100'-'110' for DeskEdit,
Impression II, Draw Plus, Poster, Edit, Notate,
Rhapsody, Acorn DTP, DisAssem, the BASIC Editor and
the Charm Editor. These files may be modified if
necessary, and added to as required.

(Note: The default keystrips provided are all for
commercial applications, except for two public
domain items: Draw Plus by Jonathan Marten and
DisAssem by Henrik Pedersen. Both these applications
are excellent pieces of software, and are readily
available through public domain libraries.)

I hope you like this program and find it useful. If
you do, send me a disc with some PD software on it,
and I'll return your disc with the other PD things
I've written on it, and the latest version of this
program if it has been updated. Remember to let me
know which version number you have, and if you find
any bugs, please TELL ME! Letters, discs, bug
reports and suggestions (none too rude, please!) to
the following address:

Richard G. Hallas,
31 Skelton Crescent,
Crosland Moor,
Huddersfield,
West Yorkshire,
HD4 5PN
ENGLAND

Version revisions:
-=-=-=-=-=-=-=-=-=-

The following versions have been made available in
the public domain:

Version 1.00: First release version, sent to APDL.

Version 1.06: this provides the additional hot-key
<CTRL-SHIFT-INSERT> (duplicating <CTRL-SHIFT-TAB>),
since DeskEdit 1.20 now uses <CTRL-SHIFT-TAB> for
one of its own features. The hot-key now toggles the
window between front and back, rather than just
bringing it to the front as in version 1.00.

Version 1.06 also corrects a small bug which caused
the window to reopen upon a mode change or return to
the desktop, when it had previously been closed by
the user.

Clicking on the icon with Adjust does the same as
Select, but also provides a little animation! (This
has always happened, but was undocumented for
version 1.00.) I like these little touches!

Version 1.07: Small cosmetic changes have been made
to the Keystrip menu to bring it in line with normal
RISC OS standards. The two Edit submenus used to
have red borders and no titles, and the Save strip
submenu also used to have no title bar. Thanks to
Mark Moxon of RISC Developments for his comments.

Version 1.12: There are numerous modifications in
this version: the system variable <KeyWindow$Flags>
replaces <KeyWindow$Top> in previous versions, and
provides two more options, 'Auto scroll' and 'Scroll
bar'. The 'Open at top' option on the main icon-bar
menu has been replaced by, and moved onto, a new
'Options' submenu, which also contains the two other
options provided by the <KeyWindow$Flags> variable.

(All the menu items are now at the correct 44 OS
units height, whereas they were previously only 40
units high.)

The Keystrip window itself now behaves more sensibly
in that it can scroll itself when the pointer pushes
up to its edges, in the same way as the icon-bar. It
is meant to mimic the icon-bar, and will 'sense' the
pointer at a similar horizontal position.

For this reason, the horizontal scroll bar is much
less necessary, and can now be toggled on and off.
In the default state, the program leaves it switched
off, which looks neater and saves a little space on
the desktop.

Key-combination labels have been added to the right
hand edge of the window, and are identical to the
ones at the left.

My thanks must go to Henrik Pedersen for his very
useful and helpful suggestions, some of which are
implemented in version 1.12, notably the 'Auto
scroll' feature. I can't imagine why I didn't think
of this myself! Other suggestions will have to wait
for a later version, when I have time to think about
them.

Version 1.25: Credit must once again go to Henrik
Pedersen, this time for showing me how to read the
taskname of the application owning the caret. It's
actually very easy to do, but I had managed to miss
it every time I had consulted the PRM! Version 1.25
represents a completely new way of operating for Key
Window, and this is the way I wanted it to work in
the first instance. The facility to read the caret
owner's taskname enables it to be wholly context
sensitive, whereas previous versions simply opened
and closed strips as applications were loaded and
quit.

The <KeyWindow$Flags> system variable and the
'Options' submenu have both been extended to take
account of the new context options. Also, a very
small but perfectly formed bug which has been around
since the first version, and which meant that the
strip didn't resize upon a mode change if it was
closed, has finally been killed, and a very minor
deficiency (not exactly a bug) concerning reopening
the same strip has been corrected from previous
versions.

- R.G.H.