Replicate 1.14 (24-Sep-03)

Name:     ArtWorks Replicate module
Purpose:  ArtWorks module for object replication
Author:   Martin Wrthner
Requires: RISC OS 3.1 or higher, ArtWorks 2
Status:    2003 Martin Wrthner; all rights reserved; see [4] below
WWW:      http://www.mw-software.com/

The Replicate tool allows you to replicate arbitrary ArtWorks objects in
regular patterns many times without consuming any extra memory. The six
patterns provided are Matrix, Matrix outline, Matrix chequered, Diagonal,
Diamond and Diamond outline. You can change the replication type, the number
of replications and the offset between the replications at any time. Undo and
exporting are fully supported.

1) The Replicate tool
-------------------
1.1) Creating replications
--------------------------
The Replicate module displays an additional tool, the Replicate tool, in the
ArtWorks tool box. The Replicate tool looks like four blue circles arranged in
a two by two grid. Clicking Select on the tool selects it as the current tool.

The Replicate tool allows you to create objects of a new type: replicate
objects. A replicate object contains some other ArtWorks object and displays
multiple copies of it in some regular pattern.

In order to create a replicate object, select any single ArtWorks object (if
you want to replicate several objects together, group them first), then select
the Replicate tool.

If all buttons in the Replicate info bar are shaded, then you have probably
forgotten to select an object or you might have selected more than an object.
If there is exactly one selected object, the button labelled "Replicate" is
available. Clicking on it opens a menu with the different replication patterns
that are provided.

These are:
a) Matrix
   A rectangular array of objects. You can change the number of replications
   in both directions. The first of the two numbers to enter is the number
   of columns, the second is the number of rows. You can either enter a new
   value in the writable field or use the up/down arrows to change the values.
   The replication types Vertical and Horizontal offered by some other drawing
   program can be easily simulated using the value 1 for the first or second
   value respectively.
b) Matrix outline
   As a), but only the outline of the array. This allows you to create frames
   easily. The interpretation of the two values is the same as with a).
c) Matrix chequered
   As a) but every other object is left out, resulting in a chequered pattern
   of objects.
d) Diagonal
   A diagonal arrangement of objects starting with the original object in the
   bottom left-corner. This type has only one parameter that is simply the
   resulting number of objects.
e) Diamond
   Like a matrix, but turned by 45 degrees. Diamond replicates always have the
   same number of rows and columns, so there is only one parameter to enter. If
   the number of rows/columns is odd, the corners are one object wide,
   otherwise the corners are two objects wide to keep the symmetry.
f) Diamond outline
   As e), but only the outline of the diamond.

The field next to the "Replicate" button is called the Replicate type field. It
shows the type of replication that has been applied to the currently selected
object. If the currently selected object is not a replicate object, the field
shows a dash "-".

1.2) Changing the replication type and removing replications
------------------------------------------------------------
If the currently selected object is a replicate object, then you can change the
replication type of the object by clicking menu over the Replicate type field
or by clicking on the adjacent pop-up menu icon labelled "Change ". This opens
the a menu with the title "Change type".

The first entry, "Remove" allows you to remove the replicate object leaving you
with the original object that was replicated. The other entries allow you
change the replication type of the currently selected object. If you choose one
of the bottom three types ("Diagonal", "Diamond" or "Diamond outline", then the
second parameter (number of rows) is forced to the same value as the first
parameter (number of columns).

1.3 Handling replicate objects
------------------------------
Replicate objects behave like any other single ArtWorks object, so you can
move them, rotate them and scale them.

Replicate objects support non-uniform scaling operations (i.e. those where the
"Lock" option in the Scale tool info bar is switched off). If you first rotate
the replicate, then scale it non-uniformly, you can effectively skew the object
so that the replication is no longer a rectangle but a parallelogram. Note that
even in this distorted state, you can still change the number of replications
or the offset between the replications (see 1.4).

You can also apply attributes to replicate objects, e.g. line or fill colours.
When applying graduated/radial fills please note that the result is as if the
fill had been applied to the original object. All other objects then reflect
the way the original object looks. The original object is usually the one in
the bottom left corner (for a matrix-type replicate) or the bottom object for
the Diamond replication types.

Please note that cannot put replicate objects into perspectives or envelopes.
Unfortunately, the Replicate tool cannot prevent you from doing so to begin
with. However, if you accidentially create an envelope or perspective
containing a replicate object, ArtWorks will display an error message. You
should then remove the envelope/perspective immediately. This will result in
yet the same error message again, but do not worry, things should be alright
then. The only way to envelope/perspectivise replicates is to turn them into
individual objects first by clicking on "Make objects" (see 1.4).

As of version 1.5, even blend objects can be replicated. This did not work with
earlier versions of the module.

1.4) Advanced features
----------------------
By clicking on Setup... the info bar changes to display some more parameters:
The fields OffsetX and OffsetY contain the offsets between objects in both
directions. The default value for OffsetX is the width of the replicated
object, the default for OffsetY is the height of the replicated object.

Simply enter a new value and press Return to change OffsetX or OffsetY.

To reset the values to the width/height of the replicated object, click on the
button labelled "As object" next to the relevant writable field.

By clicking on "Back", the info bar changes to the standard display with the
Replicate type field etc.

The button "Make objects" allows you to turn the replicate into static objects
that can be edited individually. Of course, each of these objects will then
consume memory in contrast to replicate objects that do not take any extra
memory.

"Make objects" may sound similar to the menu entry "Make shapes" that is
available from the "Lines/Shapes" sub-menu. However, the difference is that
"Make objects" will only create editable copies of the replicated object and
will *not* turn the object itself into shapes. In contrast, "Make shapes" will
turn everything into shapes. So, if you create a replication of an ellipse,
"Make objects" will leave you with several ellipses while "Make shapes" will
turn all the ellipses into path objects as well.

1.5) Exporting and using replicate objects in Impression etc.
-------------------------------------------------------------
ArtWorks EPS export and Draw export are supported. In both cases, replicate
objects are simply exported as individual objects. If the ArtWorks EPS file
is imported later, it contains the individual objects as a group. The replicate
object is *not* recreated.

Please note that Impression, Ovation Pro and other programs that claim to
render ArtWorks files are only able to render replicate objects if version 1.50
or higher of AWRender (the ArtWorks rendering module) is installed. AWRender is
part of the free AWViewer utility that can be downloaded from:
  http://www.mw-software.com/software/awmodules/awrender.html#download

The original version of AWRender as published by Computer Concepts only copes
with the object types that were known to ArtWorks 1.1, so if such an old
version of AWRender is installed, Impression and other applications do not
display replicate objects. More precisely, they will render the original
object, but not the replications. If you want to make sure that replicate
objects are always displayed correctly in other applications irrespective of
the version of AWRender that is installed, you have to use Draw export.
However, this has several drawbacks and it should not normally be necessary
because it should be easy enough to make sure that AWRender 1.50 or higher is
installed.

If required, you can create an equivalent ArtWorks file without replicate
objects by selecting each replicate object in turn and turn it into individual
objects by clicking on "Make objects". Then, after saving the file with the
expanded replicates, use Undo to recreate the replicate objects.

1.6) Bugs, limitations deficiencies
-----------------------------------
Old copies of ArtWorks without the Replicate module will only render one copy
of the object and miss the replications. If you want to transfer files to old
copies of ArtWorks, the workaround is to use "Make objects" or to use Draw
export (see 1.4).

Due to a slight lack in foresight at CC, there is no way an object handler can
tell the Mould tool that some object does not want to be enveloped or
perspectivised. The Mould tool "knows" that it cannot deal with Sprites,
Envelopes and Perspectives but this knowledge is hard-wired into the module.
So, the Replicate tool will only notice that you attempt to envelope or
perspectivise a replicate object when it is too late and there is no way it
could abort the operation.

The "As object" button that sets the offset to the size of the original object
uses the size of the object when the replicate was first created. Further
rotations/scalings are taken into account, but not changes in size that were
caused by applying attributes to the replicate. So, if you apply a thicker line
width, then the change in size is not taken into account for "As object".

There is one slight discrepancy between displaying and exporting replicates
that is normally not noticeable: On screen, the replications reflect the exact
way the original object looks. In contrast, when exporting, what happens is
that the original object is translated to the required position and then
exported. Normally, these two ways cannot be distinguished because the way an
object looks is usually not changed when the object is moved. However, when
using Hatch fills (either with the Hatch module or with HatchPro with the
Transform option off), this can happen. By setting the Replicate offset values
to an exact multiple of the offset value used for the Hatch fill, this problem
can be avoided.

2) History
----------
Version 1.14 (24-Sep-03)
- fixed incorrect Info Bar display when applying a Diamond [outline]
  replication

Version 1.13 (14-Jul-03)
- fixed replication of text with a line colour
- supports pix units
- removed menu symbol from "Change" button

Version 1.12 (17-Jun-03)
- added skew support
- added interactive help for tool

Version 1.11 (05-May-03)
- various minor bug fixes (better error handling when expanding replicates,
  some corrected error checks)
- replicate object angle (as seen in rotate tool) is kept up to date correctly
- help button added to info bar
- 32-bit compatible module for ArtWorks 2

Version 1.09 (12-Aug-02)
- outline matrix with 1 row and more than 2 columns caused ArtWorks to hang -
  fixed
- contains anti-aliased tool sprites by Nobilangelo Ceramalus

Version 1.08 (28-Mar-02)
- completed support for Crystal tool (support for a future attribute)

Version 1.07 (12-Mar-02)
- added support for Alpha attribute (Crystal tool)
- fixed bug (r10 corrupted in Method_Render), only affects Crystal
- added German and Dutch (thanks to Dick Tanis) messages
- fixed some other minor bug (non-aligned offset, did not do any harm)

Version 1.06 (18-Apr-01)
- finally fixed replicate outlines displayed when moving, rotating, scaling,
  etc.: now, the replication outlines are shown as well
- now checks for the required T_Draw version (0.964)

Version 1.05b (25-Aug-00)
- documentation update

Version 1.05 (07-Nov-98)
- replicating blends works correctly now

Version 1.04 (19-Dec-97)
- replicated envelopes and perspectives are rendered correctly

Version 1.03 (16-Dec-97)
- introduced "Replicate" button
- introduced changing of replicate type
- fixed shading/unshading of info bar gadgets

Version 1.02 (01-Dec-97)
- fixed bounding box problems with Diagonal replications
- fixed Draw/EPS export with "Selection" option on
- fixed "Make shapes" with several selected replicate objects

Version 1.01 (28-Nov-97)
- fixed Draw export
- fixed bounding box problems with Diamond replications

Version 1.00 (24-Nov-97)
- first beta release


3) Contacting me
----------------
Martin Wuerthner
Mannheimer Str. 18
67655 Kaiserslautern
Germany

Phone: +49-(0)631-3608205
Fax:   +49-(0)631-3608203

e-mail: martin@mw-software.com
WWW:    http://www.mw-software.com/

4) Copyright
------------
The ArtWorks Replicate module, related documentation and files are  Copyright
2003 by Martin Wrthner. All rights reserved. The software and documentation
may not, in  whole or part, be copied or transmitted by any means without the
explicit written consent of the copyright owner. Unless you have purchased a
site licence for this  software, it may be used on only one stand-alone
computer system at any time.

In order to use this software, you need a licence from the copyright owner. If
you do not have such a licence, you must delete this software, the Replicate
module and its related files, now.
