*****************************************************************************

       FormEd 3.59 -  by Acorn Computers, the RISC squad, and D. Salt

*****************************************************************************

 For a description of updates from v2.00 to v3.02, combined, take a look at
!FormEd.!Updates. As this version is rather different, see the section below
on "How to use". For details referred to older versions (eg. "see 2.87"),
read the relevant part of the !Updates file; also see this file for anything
not mentioned below.


 HOW TO USE
 
 The templates window, loading and saving templates, loading sprites
 - see <= v3.00


 Editing a template
 
 The first thing you will notice is the new editing window. This will be
opened and linked to your template when you open it. Its title bar contains
the template name and (if applicable) the number of the icon being edited.

 Initially, the editing window will open at the lower left, in icon mode and
with no icon selected for editing.

 Clicking on any blank space in the editing window (or the pane open within
it) will bring it to the front.

 We need a few terms defined:
 - the "current icon" is the icon last selected for editing;
 - the "current window" is the window last selected for editing, and always
   contains the current icon.

 All editing actions affect the current window unless otherwise stated.


 The icon editing window
 
 The top four icons select which attributes of the icon are to be edited, by
controlling which pane is opened when one clicked on.

 The icon marked "Selection" determines whether editing affects whether the
selected icons are affected as well as the current icon. Certain editing
functions affect only the current icon - they are described as such.
"Selection" means this icon.

 The icon "(De)select" allows you to select or deselect groups of icons.
Click SELECT to open for selecting, or ADJUST for deselecting. The window
opened by clicking here works as previously, except for the two new icons at
the top which control whether icons will be selected or deselected, and a
button "All" which selects or deselects all icons in the current window.

 "Create" opens an icon creation menu which works as in v3.02, except for
the addition of a "Library" entry which contains some commonly-used icons -
see 'Other info' below for more details. Once the icon has been defined, you
need to place it somewhere: click MENU where you want to put it. The
newly-created icon becomes the current icon. (For those who are confused
about the 'NewLook' arrow icons, remember they are supplied as standard with
RISC OS >=3.12, and with the !NewLook application for older versions.)

 "Tidy icons" works exactly as in older versions - it deletes icons which
are outside the logical work area of the current window.

 "Delete" will delete either the current icon OR the selected icons - never
both (unless the current icon is also selected).

 "Edit window" closes the icon editing window and opens the window editing
window.

 To select an icon for editing, click MENU over it - this becomes the
current icon, and the window it is in becomes the current window. It is
possible to have no current icon by clicking MENU over the window
background.

MENU clicked while holding Shift, Ctrl or Alt or a combination of these
still works as described for v3.00-v3.02, except that it is affected by the
"Selection" flag.

 Selecting an icon for editing causes the last selected pane (initially
"Contents") to open in the editing window. You can change which pane is in
use by clicking on one of the four radio icons to its left.

 The "Contents" pane
 
 Everything in this pane affects only the current icon.

 The icons from top to bottom:
 - the icon text (or sprite name);
 - the 'text' flag;
 - the 'sprite' flag;
 - the 'indirected' flag, and (to its right) the buffer length;
 - the validation string.

 The buffer length is only editable when the icon is indirected; the
validation string is only editable when the icon is indirected and has its
text flag set.

 Setting the buffer length to 0 will actually set it to the minimum required
for the icon text (which is 1 plus the length of the text).

 The "Flags" pane
 
 Most of the icons are just flags which can be toggled on or off. If
"Selection" is set, then the appropriate bits of the selected icons are set
to the same as the current icon - eg. if you give the current icon a border,
the selected icons also gain a border whether they had one or not.

 Clicking on "Anti-aliased" selects system font (on the RISC PC, it selects
the default font); to select an outline font, or to change the font used or
the size, click on the menu button to its right. (Note that what you don't
change is preserved.)
 The menu has a 'size lock' option - when this is ticked, setting the size
sets both height and width, otherwise just the width is set. This is saved
in the options file.

 To set the foreground or background colour, or the button type, click on
the relevant menu button (to the right of the required item) to open a menu,
then select from that menu.

 The ESG number is adjusted by using the arrows either side of the number.

 Other contents: justification flags, border, filled, half size sprite,
allow ADJUST selection, needs help.

 The "Position" pane
 
 When "Selection" is set, moving (or copying) the current icon causes the
selected icons to be moved (or copied), maintaining their positions relative
to the current icon (or its copy).

 The "Move" box allows you to move the current icon to a new position. The
upper two writable icons contain the upper right coordinates; the lower two
contain the lower left coordinates. Changing one of these causes the icon to
move to the new position. Clicking on an arrow causes the current icon to
move by one pixel in the indicated direction.

 The "Jump" box allows you to specify where to move or copy the current icon
to, either absolute coordinates for its lower left corner (measured from the
window's LWA origin) if the "Abs" icon is set, or relative to its current
position if the "Rel" icon is set. The coordinates are specified in the two
writable icons; click on "Move" or "Copy" to move or copy the icon.

 The "Arrange icons" box always works on the selected icons, regardless of
the "Selection" setting. It contains a writable icon which determines the
gap (in OS units) between icons, three radio icons, and two action icons.
The radio icons control the icons' alignment - one set of icons for two
functions, eg. the top icon means "left aligned" or "top aligned" depending
on whether you choose to arrange the selection horizontally or vertically.
The lowest-numbered icon in the selection is not moved when you click on
"Horizontally" or "Vertically"; the other selected icons are placed,
respectively, to the right of or below this icon, always in ascending order
of icon number.

 "Renumber as" renumbers the current icon only to the number shown to the
right. This is exactly the same as Ctrl-MENU clicking on the icon.

 The "Size" pane
 
 The main feature is a large box representing the current icon. At each
side, there are two arrow icons; clicking on an arrow pointing away from the
box moves that side of the icon outwards by one pixel, enlarging the icon;
clicking on an arrow pointing towards the box moves that side of the icon
inwards by one pixel, shrinking the icon.

 Below this, there are two writable icons containing the current size. To
their right is a button to fill these in with the current icon's "minimum"
size (which, for MOST icons is accurate); to actually use this size, you
must double-click on it.

 For selection resizing (only applicable if "Selection" is set), you have
the choice of relative or absolute. In relative mode, the size of the
selected icons is adjusted by the difference between the old and new sizes
of the current icon; in absolute mode, they are forced to be the same size
as the current icon.


 The window editing window
 
 The top five icons select which attributes of the current window are to be
edited, by controlling which pane is opened when one clicked on.

 The icon marked "Identifier" allows you to edit the template's name. This
is exactly the same as the "'<template>'.Rename" option in the templates
window menu.

 The icon "Tools" opens a small menu containing Front, Back, Toggle and
Close. Useful if the current window has no title bar, no back icon, no
toggle size icon, or no close icon.

 "Save" allows you to save the current window.
 "Delete" deletes the current window.

 "Edit icons" closes the window editing window and opens the icon editing
window.

 To select a window for editing, click MENU over it - this becomes the
current window (if you clicked over an icon, it becomes the current icon).

 You can change which pane is in use by clicking on one of the five radio
icons to its left.

 Certain impossible choices are prevented: for instance, you cannot have a
close icon without a title bar, or a resize icon without either scroll bar,
or even any window tools (and the "Scrollbar" pane) when the title ink is
transparent.

 The "Title" pane
 
 Contains title bar flags. The writable icons, and the Text, Sprite and
Indirected flags work as described above (the icon "Contents" pane), except
that, of course, they affect the window's title bar.

 At the top, there are flags controlling whether the window has a title bar,
close icon and send to back icon.

 In the "Alignment" box are the text/sprite alignment icons (similar to
those in the icon "Flags" pane).

 In the "Colour" box are the title colour options. Click on the menu icon to
the right of the colour you want to alter, then select from the palette box.
Transparent ink, when selected, shows up as a red T in a light grey box.

 Below this, we have the "Anti-aliased" font option described under the icon
"Flags" pane. It works in much the same way, altering the font used in the
title bar.

 The "Work area" pane
 
 Four flags: Moveable (if the window has a title bar), Auto redraw, Grab
keys, Real colours.

 Two colour settings, use as above. The window background may be transparent
- this setting is best used with program redraw ("Auto redraw" off). Use
with care!

 Button type - use as in the icon "Flags" pane.

 The "Position" pane
 
 This pane works in one of two modes: alter the window position or alter the
scroll bar offsets. Which mode is used is determined by the radio icons
"Window" and "Scroll".

 The "PWA" box contains the current window's physical work area coordinates,
either as "on screen" coordinates in window mode, or relative to its LWA
origin in scroll mode. These values may be altered directly, or by clicking
on the arrow icons (move by one pixel) in the middle - in window mode, the
window will be moved, and in scroll mode, its scroll bars will be moved.

 The "Jump" box moves the window (or its scroll bars) by the specified
amount when OK is clicked on.

 Below this are the position flags - Pane, No bounds, Back, On screen.

 The "Size" pane
 
 The "PWA Absolute" box contains the size of the physical work area. This
can be edited directly or by clicking on the arrows to change the size in
steps of one pixel. It is important to note that the up arrow extends the
size of the PWA downwards - think "up = increase".

 The "PWA Relative" box allows you to adjust the PWA size by a specified
amount. To make the adjustment, click on Set.

 The "LWA" box allows you to set the LWA size. It is arranged as two pairs
of coordinates, which may be edited directly or by using the arrows.
Clicking on the left hand set alters the lower left coordinates; clicking on
the right hand set alters the upper right coordinates. In the middle is an
icon marked "=PWA"; click on it to set the LWA limits to those of the
currently visible part. Below, there is an icon marked "Min:" and a pair of
writable icons to its right, containing the minimum size of the PWA.
Clicking on "Min:" sets the minimum size to the current PWA size.

 The "Scrollbar" pane
 
 Mostly flags. From top to bottom:
 - horizontal scrollbar;
 - vertical scrollbar;
 - "outer" colour (scroll bar range);
 - "inner" colour (scroll bar);
 - toggle size icon;
 - resize icon;
 - user scroll: either debounced or auto-repeat;
 - no right bound;
 - no lower bound.

 The colour options are there for backward compatibility, and will only be
used if you use tool sprites without scrollbar sprites (such as the default
set for RISC OS <= 3.11).

 "No right bound" means that you can carry on resize-dragging to the right
when the window's maximum size is reached; "no lower bound" works similarly
when resize-dragging down.

 If either user scroll flag is set, clicking on the scroll bar arrows will
cause event 10 to be generated, either once (debounced) or until the arrow
icon is "released" (auto-repeat).


 Changes to the Options window since v2.87
 
 The AutoLoad options can now handle lists of files - the first matching
file will be loaded. For example, "Sprites,!Sprites" will cause !FormEd to
check for "Sprites" then, if not found, "!Sprites". Note that the autoload
sprite filenames are treated in the same way as for *IconSprites - various
suffixes are tried depending on the current screen mode; the highest
resolution found is loaded.

 There is an option labelled 'Bring editing window to front'. When selected,
clicking Menu to select an icon or window for editing will bring either the
icon editing or the window editing window to the front (depending on the
current editing mode).

 Also present is an option 'Eliminate repeated strings' which, when selected,
causes FormEd to optimise saved files by, on a per-window basis, pointing
icons using the same strings (or the same latter portions of strings) to the
same bits of text; all this means is that less memory may well be required to
load the templates into.

 The "Country" setting has been removed. This is because FormEd now reads
the configured territory setting and uses that to determine which set of
messages, templates and sprites to load, and which library to use.


 Other info
 
 There's now a library supplied with !FormEd. This is stored in the
resources, one library per territory. The main menu has an option to open
this directory, and to reload the icon definitions should you wish to do so.
The 'open' option is also present in the template file menu.

 You're not allowed to have more than 250 icons in a window. If you try to
have more, you'll be warned about it, and the excess icon(s) won't be
created. Basically, if you MUST have this many icons, think again about your
window structure!


 NOTES
 
* Since I shifted FormEd's sprite pool to the system sprite area, the slot
  size is now 192K; however, 196K is claimed then 4K released to ensure at
  least 4K of workspace. You should make use of !SpriteFS.

* It may actually work in 176K! (Can't be bothered to check.)


 KNOWN BUGS, ETC.
 
* The displayed icon number in the editing window is incorrect if the
  current icon is moved and is consequently renumbered (due to a lower
  numbered icon having been deleted).

* Will crash when fed a template file containing a window with more than 250
  icons.

* Send bug reports, money, or A3010-compatible hardware to:
    Darren Salt, 17, Allendale Crescent, Wansbeck Estate, Stakeford,
    Northumberland, NE62 5YG
  Email: arcsalt@spuddy.mew.co.uk


 POSSIBLE IMPROVEMENTS - if I feel like it ;-)
 
* Restore 'copy left/right/up/down' function, in icon position window

* Fix icon widths (when creating icons) for RISC PC

* Is there anything left? (And you can forget editing multiple files!)
