ShapeFX
-------
 Data Store Software 1991

ShapeFX creates border designs by reproducing a
shape repetitively around a 'frame', which can be
rectangular or elliptical. The user has control
over the size of the rectangle or ellipse, the
number of copies of the shape placed around it,
the size of the gap between the shapes (or amount
of overlap if required), and whether the shape
should be rotated as they are placed around the
frame, or left upright. In addition, when a
rectangular frame is selected, the user can
specify which sides of the rectangle are included,
and whether the corners should be filled or not.

Running ShapeFX
---------------
ShapeFX requires no special configuration of the
computer, nor the presence of any additional
software to that contained within the standard
RISC OS ROM set. Simply double-click on the
ShapeFX icon to run the application, and the icon
will appear on the icon bar. The icon bar menu
contains the options 'Info', giving some
information about the program version number and
also giving access to this manual, and 'Quit',
which is self-explanatory. Click SELECT on this
icon to open the ShapeFX control window.

The Control Window
------------------
The control window is divided into two sections:
the top section displays the current shape, and
the lower section shows the current options and
settings. The settings are:

  Selection of frame shape, either rectangular or
    elliptical

  Height and width of the frame, in mm.

  Number of copies of the shape to be placed
    around the frame

  Size of the gap between shapes, expressed as a
    percentage of the width of the shape. Entering
    a negative value creates an overlap of one
    shape on its predecessor.

  Selection of rotated or upright shape.

Altering the settings in the lower section is
achieved by clicking with the mouse over the
option buttons, or clicking in one of the writable
areas and typing in the required value. 

To change the current shape, just drag a drawfile
into the ShapeFX control window. Any drawfile can
be used, but if it contains a sprite or text,
these items will be ignored. Alternatively, you
can select a shape from a 'Library' file. These
are collections of shapes stored in a single file,
and can be created by a public domain drawing
package called 'Draw Plus' by Jonathan Marten,
which is widely available. A default library file
is supplied with ShapeFX. containing a variety of
shapes. If you wish to select a shape from the
current library, click MENU over the control
window, and then select 'Library' from the menu
(for details of the other menu options, see
below). A scrollable window will appear with the
names of all the shapes in the library listed
within it. To select a shape, click on the
appropriate name. If you wish to load a new
library, just drag the library file into the
control window.

The Main Menu
-------------
Apart from the 'Library' option described
immediately above, the main menu contains four
other items:

Clicking on 'Options' will open a window of
special options relevent when the user has chosen
a rectangular frame shape. If an elliptical shape
has been chosen, 'Options' will be greyed out. The
special options window allows the user to choose
whether the corners of the frame should be filled,
and which sides of the rectangle should be
included. 

Clicking on 'Create' starts the actual process of
creating the border. An hourglass will appear if
the process is likely to take some time. When the
border has been created, you will need to save it,
so a save box appears automatically, from which
you can drag the drawfile icon into a directory
viewer to save the border. Alternatively, you can
type a valid pathname into the writeable icon and
click on 'OK'. As an additional option, clicking
on 'OK' WITHOUT entering a valid pathname will
attempt to transfer the border straight into Draw.
This can be achieved if either (a) Draw is already
running or (b) the computer knows where Draw is on
your disc system and can therefore go and run it
before loading your border.

Sliding across 'Save' will give three options. The
first option, 'Border', will be greyed out until
'Create' has been clicked on first. Once this has
taken place, sliding across 'Save  Border '
leads to a standard save box, from which you can
save the last created border (see above for
details of the facilities of the save box.

The next save option is 'Save  Settings ', which
will save a 'script file' of the current settings.
See below for details of script files. The save
box in this case is similar to that for saving
borders, but clicking on 'OK' without a pathname
will attempt to transfer the script file straight
into Edit.

The final save option is 'Defaults'. Clicking on
this option will save the 'Choices' file inside
the ShapeFX directory, which determines the
settings that are current whenever you first run
ShapeFX. If at anytime you want to go back to
these initial settings after changing them, you
can use the final option in the main menu, which
is...

'Reset'.

Script Files
------------
These are files of commands which ShapeFX can
execute to load shapes or libraries, select shapes
from the current library, or set options to
particular values. Normally, the easiest way to
create such a file is to set all the options and
then 'Save  Settings'. However, it is possible to
create a script file manually. To use a
script file, just drag the file icon into the
ShapeFX control window, and all the settings will
be made according to the commands in the script
file. 

The ShapeFX Control Language
---------------------------- 
These are the valid commands and their syntax.
Where parameters are required, they are shown in
angled brackets. Where a parameter is optional, it
is also shown in round brackets. 

\*<textstring> Comment line - has no effect at
               all.

\CE            For rectangular frames, select the
               'empty corners' option.
           
\CF            For rectangular frames, select the
               'filled corners' option.

\CR(<filename>) Create border and pop up the
               save box, optionally inserting
               the <filename> in the save box
               filename field. This command is
               only acted upon when ShapeFX
               detects the end of the script file.

\DE            Defaults. This command restores
               ShapeFX to the special effect
               settings that are set up when you
               first run the program.

\EB            Select an elliptical border. 

\FH <number>   Set the frame height to <number>mm.

\FW <number>   Set the frame width to <number>mm.

\GR <%age>     Set the gap ratio to <%age>%.

\IB            For rectangular frames, include the
               bottom edge of the frame.

\IL            For rectangular frames, include the
               left edge of the frame.

\IR            For rectangular frames, include the
               right edge of the frame.

\IT            For rectangular frames, include the
               top edge of the frame.

\LD <filename> Load the named drawfile as a shape.

\LL <filename> Load the named library file.

\NC <number>   Set the number of copies of the
               shape to be placed around the
               frame.

\RB            Select a rectangular border.

\SR            Select the rotate shape option.

\SU            Select the upright shape option.

\TR(<filename>) Transfer, i.e. create border,
               and immediately save it into a
               file of name <filename>. If no
               filename is given, the drawfile
               will be transferred straight into
               Draw (if it is already running
               or can be located on your discs).
               Like, \CR, this command is only
               executed at the end of the script
               file. 

All relevant commands can be negated by prefixing
the code with an 'X', for example '\XIR'.

Layout of a script file
-----------------------
Script files can be fairly free in format, but the
following rules apply:
  
(i)   All commands must start on a new line.

(ii)  All commands have to be in capital letters,
i.e. \CIT, not \cit.

(iii) Parameters, where given, can either run
straight on from the command, or be separated from
the command by a space, i.e. \GR 10 or \GR10.

(iv)  You should only enter \X$$ commands to
cancel settings if those settings would not
otherwise be cancelled by other commands in your
file. A good idea, if in doubt, is to include the
command \DE at the beginning of each file: this
will ensure that no special effects are left set
by previous usage of ShapeFX to disturb the effect
of the script file.


Potential Problems
------------------
There is a potential problem when creating
rectangular frames which users should be aware of.
If you specify a frame of a particular size, and
that there should be a particular number of shapes
around the frame with a given gap between each,
ShapeFX will try to scale the shapes to fit the
appropriate number of shapes around the frame.
But, and this is the problem, it may not be
possible to scale a shape to fit both the height
and width of the frame exactly. ShapeFX's response
to this will be to adjust the frame size by the
smallest amount possible to achieve the correct
number of identically sized shapes around the
frame. So, for example, if you specified 40 shapes
around a frame 150mm high by 240mm wide, you may
end up with 40 shapes around a frame 146mm high by
242mm wide. It was considered better to do
this, rather than change the number of shapes
or alter the scaling of the shape on the
top/bottom of the frame compared to the
left/right of the frame. The author will be
pleased to receive feedback from users if you have
any better method of accomodating the inherent
impossibilities!     

Another, possibly more damaging, problem, concerns
the very nature of what ShapeFX does. Since it
reproduces a draw object a given number of times,
the amount of memory/disc space required to hold
the created border will be the size of the
original shape times the number of copies.
Therefore, if you start off with a complex shape,
occupying many k of memory, the resulting border
may be very large indeed, and may in fact be
impossible to create because of lack of memory.
This should not cause a crash of the program, but
users should be aware that this problem may arise. 

Following on from the above problem is the
connected one of slow redrawing of complex
borders. If you reproduce a complex shape around a
frame, it may take the computer a fair amount of
time to actually draw it onto the screen. Again,
this is not a fatal problem, but it is one users
should have in mind.    
