The Datafile PD-CD 3/PDCD_3.iso/utilities/utilsf/keywindow/!KeyWindow/!Help

Text File | 1993-05-10 | 23.5 KB | 605 lines

Key Window                                  (v 1.50)
-=-=-=-=-=-

by Richard G. Hallas

(See the end of this file for details of the latest
version. There are a couple of important points.)
____________________________________________________

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.

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.

☓ 'Compress': This option will force the entire
 strip to fit onto the screen. Obviously, since the
 key labels have space for 16 characters, the fully-
 annotated keystrip cannot be fitted on the screen
 (except with very large screen modes indeed). If
 you select this option, the full window will cease
 to scroll, and will be sqaushed to fit whichever
 screen mode you are using. Any key labels which are
 wholly visible will be centred in their slots as
 usual, but labels which overflow their slots will
 be justified to the left, so that you can at least
 see how they begin. In all standard screen modes it
 is possible to see almost 6 characters in a
 compressed strip. If you do happen to be using a
 very large screen mode which can accommodate the
 whold strip without having to scroll, then the
 Compress option will be turned off in that mode,
 and you won't be able to turn it on again (it will
 appear shaded until you select a mode which could
 use it). <F12> and <CTRL-SHIFT-F12> are usually
 automatically given the respective labels "Command
 Line" and "Exit Desktop". In Compress mode, these
 will appear as "* CLI" and "Exit", but if you save
 a strip the full labels will be used. If these two
 keypresses are being used for other purposes, and
 therefore have different labels from standard, the
 new labels will not be affected by the Compress
 mode.

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 click on it with both SELECT
and ADJUST simultaneously. (The easiest way of doing
this is probably to hold down SELECT and then click
ADJUST.)

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, even when the strip is
 compressed (you just won't be able to see all the
 text).

☓ 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.
 Note that if you are entering a strip in Compress
 mode, "Command Line" and "Exit Desktop" will be
 abbreviated to "* CLI" and "Exit". However, this is
 for display purposes only, and if you save a strip
 the full labels will be saved in the file (unless,
 of course, you have replaced them with something
 else).

☓ 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 51' (The value of 51 is
the default if you omit this line or enter an
illegal value). The variable sets the default state
for the six 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 63, 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: Always compress keystrip to fit screen.
   Bit 4: Context sensitive: applications gaining
          the caret will open new strips.
   Bit 5: Load sensitive: applications starting up
          and quitting will open and close strips.

So, for example, if you wanted just 'Open at top' &
'Compress' on by default, you would use the value 9,
since you would be setting bits 0 and 6, and 9 is
the decimal equivalent of binary 1001.

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
!Sprites22
Data
Source
Sprites
Sprites22
Templates

The Data sub-directory should contain a full set of
32 keystrips, numbered 100-131. You should examine
these and delete the ones you don't need in your own
working copy, but if you pass this application on,
please supply all the keystrips. Note that if you
don't delete some of the keystrips Key Window will
not let you add any more, as you can only have a
maximum of 32 available at any one time.

(Note: The default keystrips provided are all for
commercial applications, except for three public
domain items: Draw Plus by Jonathan Marten, Zap by
Dominic Symes and DisAssem by Henrik Pedersen. All
three of these applications are excellent, 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! I try to support all my
programs, and will correct any bugs I know about.
So please send 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.
This was only sensitive to applications loading and
quitting, not to the movement of the caret between
windows. Its only option was 'Open at top'.

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.

Version 1.32: This is the first version to sport the
'Compress' option. Such a feature was suggested by
Rob Sherratt and David Pilling; my thanks to them
for their helpful comments. Minor modifications have
been made to the Templates file in order to avoid
scaling problems in certain modes, and Key Window
will now also justify the text intelligently within
the key labels.

A small bug in the Templates file has also now been
fixed: all the key label icons previously had a
button-type of Click/Drag, and these have now been
changed to just Click, because I found that holding
a mouse button down could cause a click to register
twice, which was quite undesirable. The button-type
Click ensures one click only being registered.
The single exception to this modification is the key
label for <CTRL-SHIFT-F12>, which requires the
Double/Click/Drag button type for its safety
precaution feature to work. This safety feature has
also been changed slightly in this version, from a
sort of double-drag-click within the icon to a click
with both SELECT and ADJUST together. This is safer,
more reliable and less temperamental.

The save routine has been slightly modified in this
version to ensure that if automatic F12 labels are
being used, the full label is saved, rather than the
shorter version used in the Compress mode display.

Version 1.40: I'm supposed to be working on Key
Window 2 at this point, but I'm not being able to
find time to get down to it. Therefore I've fixed
the bugs I knew about in version 1.32, and added
some high resolution sprites for RISC OS 3 users. I
also created some icons for use with the Pinboard.
Full help on menus for RISC OS 3 has been added too.

Three small bugs corrected: trying to open a strip
for a task which doesn't have one defined now sounds
a beep rather than flashing a strip on and off the
screen. Defining a 16-character key label no longer
obliterates the label for the next key along. Strips
now take the size of the title bar into account when
different window tools are in use by RISC OS 3. I
also found a fourth problem which I'm sure wasn't
there under RISC OS 2: the checking of files in the
keystrip data directory wasn't working, and so newly
defined keystrips were overwriting existing ones.
Not a happy situation! I've therefore used a better
checking procedure, and the problem has gone away.
I suspect that results from certain OS_File calls
have changed with RISC OS 3, as this area of Key
Window (which used to work) has not, so far as I can
remember, been changed.

Version 1.50: Prior to this version, Key Window used
to interfere with the auto-save document feature in
Impression, preventing it from working. This was due
to the use of a dummy message to follow which task
owned the caret. However, I have discovered how to
do this a better way, and so the dummy message has
now gone (which is good) and the program no longer
upsets any other applications. You can, therefore,
now rely on Impression's auto-save whilst Key Window
is running. This is the most important, but least
visible, change in this version.

A second change is the addition of 3D templates.
In order to use these, you must have (a) RISC OS 3·1
or later fitted, and (b) have the 'desktop 3D'
option switched on. (This is achieved by setting bit
1 of CMOS RAM byte 140.) There have been a few other
changes to the templates so they work OK with the
new Acorn desktop (with shaded window backgrounds).

Due to some scaling problems with the 3D borders,
the 'compress' options's workings have been modified
slightly, but this should not be noticeable. A small
bug has also been fixed which used to cause the key
label validation strings to sometimes get over-
written; a similar case with the keystrips menu has
also been fixed. I don't think there are any other
bugs left in this version (I hope).

NB There will certainly be a Key Window 2 at some
future point, but finding time to write it is a
major problem. This version (1.50) is therefore a
stop-gap: the new version will have many extra
features, but I don't intend altering Key Window 1
any further now unless I discover any remaining
bugs.

One final point of note is that Key Window is now
supplied with a full 32 keystrips, meaning you can't
add any more without deleting some first. I intend
that Key Window 2 will be able to handle any number
of keystrips (and even have more than one per
application, for applications which directly support
this feature), and they will be stored in a similar
way to fonts in a font directory. Watch this space.

- R.G.H.