Polygon 2.04 (14-Jul-03)

Name:     ArtWorks Polygon module
Purpose:  Handling regular polygon and star objects in ArtWorks
Author:   Martin Wrthner
Requires: RISC OS 3.5 or higher, ArtWorks 2
Status:    2003 Martin Wrthner; all rights reserved; see [5] below
WWW:      http://www.mw-software.com/

This module provides a tool which allows you to create regular polygons and
stars. At any time, you can simply change the position, the radius or the
number of sides of any polygon object. By a single mouse-click you can also
turn a polygon into a star and vice versa and you can round its corners. This
tool was inspired by CorelXara's QuickShape tool.

In contrast to earlier versions of Polygon, this module is commercial software,
so you may not pass it on (see [6] below for a more detailed Copyright notice).

1) The Polygon module
---------------------
The Polygon module displays an additional tool, the Polygon tool, in the
ArtWorks tool box. The tool's icon is a hexagon. In order to create polygon
objects, select this tool.

1.1) Creating polygons and stars

While the Polygon tool is selected, the info bar displays the field 'Sides',
'CentreX', 'CentreY' and the option buttons 'Stellated' and 'Rounded'. At the
moment, the most important field is 'Sides'. In this field, you can specify the
number of sides (=number of corners) the polygon is supposed to have. The
fields 'CentreX', 'CentreY' and 'Radius' are empty and can only be used to edit
existing polygon objects.

To create a polygon, simply click inside the document and drag the pointer away
from the position of the click. The click position will become the centre of
the polygon. By dragging further away from the centre, you can increase the
radius of the polygon.

Note that the mouse pointer also determines the position of one of the corners
of the polygon so that you can effectively rotate the polygon while dragging.
If you hold down Ctrl while dragging, the angle of the polygon is constrained
to the current constraint angle (which can be set in the ArtWorks choices
dialogue box).

As soon as you release the mouse buttons, the polygon object is created and it
is rendered as a filled shape.

1.2) Editing polygons and stars

Objects created by the Polygon tool are not simply path objects but belong to a
specific object type "polygon" (similar to the way rectangle, rounded rectangle
or ellipse objects are different from path objects). This means that you can
apply attributes to them (fill colour, line colour, line width, graduated or
radial fill etc.), but you cannot edit single corner points. To do so, you have
to convert the polygon to a path object by choosing "Make shapes" from the
"Lines/Shapes" menu or by pressing Ctrl-N.

The benefit of having a special polygon object is that you can edit the
properties of polygons after they have are created, e.g. you can simply select
the polygon and change its number of sides by selecting the Polygon tool and
entering a new value in the 'Sides' field and pressing Return (or clicking on
the up/down arrows). You can also change its radius or the position of its
centre by entering new values in the corresponding fields. This is very similar
to the way e.g. the ellipse tool works. Also, you can always turn a polygon
into a star and vice versa by selecting or deselecting the 'Stellated' option
button. Of course, when you save a file containing polygons they can still be
edited when you reload the file later.

The 'Rounded' button rounds the corners of the polygon. Additional handles
appear that allow you to control the degree of roundness. Alternatively, you
can fill in a value into the "Roundness" field. This value is a percentage
representing how far the roundness control handle travels from the corner to
the midpoint of the side (or to the inner corner if the object is a star).

1.3) Editing using the polygon handles

A selected polygon object has got a handle at each corner point. If the object
is stellated, each outer corner (i.e. the corners of the corresponding polygon)
and each inner corner has got a handle. By dragging these, you can edit the
polygon. Dragging the polygon corner handles (or the other corners of a star)
allows you to scale and rotate the object quickly. Note that this rotates about
the real centre of the polygon unlike the ArtWorks rotation tool that cannot
know what the real centre of the object is.

If you hold down Ctrl while dragging one of the outer corner handles of a
polygon, the polygon's angle is preserved while dragging (i.e. you change its
radius only). Similarly, if you hold down Shift, the polygon's radius is
preserved (i.e. it is only rotated). As these operations preserve the polygon's
centre, they are to be preferred to using the standard scaling or rotation
tools ArtWorks provides.

Using the inner corner handles of a stellated polygon you can change the inner
radius of the star on its own. This is in contrast to dragging the outer
corners of a star which changes both the outer and the inner radius (scaling
the inner radius proportionally).

You can drag the inner handles of stars to any position, not only towards the
centre or away from it, so you can twist the star. If you want to preserve the
degree of twisting and edit the inner radius only, hold down Ctrl while
dragging the inner handle of the star. By holding down Shift while dragging,
you can force the radius to remain the same, so you change the degree of
twisting only. In order to restore the star to its non-twisted state, click on
the "Stellated" radio button twice or switch to extra mode and click on the
"Reset" button (see [1.4]).

By dragging the inner handle of stars you can create interesting self-
intersecting stars which resemble spirograph shapes.

Note that by dragging the inner corners of a star further away from the centre
than the outer corners of the star, you can turn the star "inside out", i.e.
the inner radius becomes bigger than the outer radius. Conceptually, the former
inner corners still remain "inner corners". This means that for such a polygon,
dragging the handles further away from the centre change the outer radius while
the corners nearer to the centre change both the outer and the inner radius. As
this is slightly irritating, you should avoid dragging the inner corners
further away from the centre than the outer corners.

1.4) Advanced numerical editing

The info bar now works in two modes: Normal mode and extra mode. In normal
mode, there is a button "More..." that switches to extra mode. In extra mode,
the button is labelled "Back..." and takes you back to normal mode if you click
on it. Extra mode is only available when the selected object is a stellated
polygon. It controls the additional properties available for stars.

The info bar in extra mode shows the fields "Inner radius" and "Angular offset"
that behave very much like the other editable fields and the "Rounded interior"
option button. The "50%" button next to the "Inner radius" field sets the inner
radius to half the radius of the polygon (this is also the default when
creating polygons). The "Reset" button next to the "Angular offset" field
resets the angular offset to 0 (this is the default when creating stellated
polygons).

The angular offset is a percentage value where an offset of 100% corresponds to
the angle between two neighbouring outer corners of the polygon, i.e. a polygon
with an angular offset of 100% has its inner corners shifted by one. Sensible
values for the angular offset are up to 100*number of sides, e.g. a pentagon
may have angular offsets in the range 0% .. 500% (where 500% is equivalent to
0%). Polygons created by older version of the Polygon module might have angular
offsets outside this range. However, after each editing operation, Polygon 1.20
will normalise this value, so simply press Return while the caret is in one of
the info bar fields in extra mode to normalise the polygon. It is not
neccessary (nor possible) to enter the percentage character ('%') explicitely.
Polygon will always assume that you are entering percentage values in the
"Angular offset" field.

The 'Rounded interior' button rounds the inner corners of the polygon.
Additional handles appear that allow you to control the degree of roundness.
Alternatively, you can fill in a value into the "Roundness" field. This value
is a percentage representing how far the inner roundness control handle travels
from the inner corner to the outer corner. Note that if both the inner and the
outer corners are rounded, the sum of the roundness values cannot exceed 100%,
so if the outer roundness is 30% and you enter 80% for the inner roundness,
then the outer roundness is reduced to 20% to allow the entered value to take
effect.

Similarly, if both the inner and the outer corners are rounded, you can only
drag the inner roundness control handle as far as to coincide with the outer
roundness control handle. If both handles coincide, you will only see one
handle. In this case, the handle on one side of the star's point controls the
inner roundness and the other one controls the outer roundness. This probably
sounds more complicated than it is and it should be relatively straightforward
to use.

1.5) Saving and exporting

The approach chosen for polygon objects also has disadvantages: As polygons
belong to a new object type, files containing polygons cannot be loaded in
copies of ArtWorks without the Polygon module. More accurately, you can load
the files and they will even be displayed correctly. However, trying to edit
polygon objects without having the Polygon module will result in a number of
anomalies which eventually mean that it should be avoided to load files with
polygons into copies of ArtWorks without the Polygon module.

There are three possible workarounds for this problem:

a) Convert the polygons to shapes before saving the file (after saving
   you can reconvert them to polygon objects using UNDO). To do this,
   select all polygon objects and press Ctrl-N or choose "Make shapes"
   from the "Lines/Shapes" menu.

Generally, a) is an absolutely safe approach. If you convert all polygons you
create to shapes, you maintain absolute file compatibility with the original
version of ArtWorks (but once you have done that, you can no longer use the
editing facilities of the Polygon module).

b) Make sure you give away a copy of the Polygon module with every file
   containing polygon objects. There are ShareWare versions of the Polygon
   module, but these cannot edit polygons or stars with rounded corners.

c) Export as ArtWorks EPS. This will have the following effect:
   * copies of ArtWorks which have the Polygon module installed will be able
     to load the polygons as polygon objects - older versions of Polygon (e.g.,
     the ShareWare versions) may fail to load the file if it contains a polygon
     with rounded corners
   * copies of ArtWorks without the Polygon module will load the polygons
     as path objects

   The EPS import function of Polygon before version 1.20 had a bug that
   prevented the use of EPS for this purpose. The problem was that imported
   polygon objects did not have any attributes applied (although they were
   displayed OK), so the fill colour tool would tell you that the Polygon was
   Black irrespective of its actual fill colour. Note that this affected
   importing only so any EPS files you might have created using Polygon 1.17
   or earlier are correct. This also means that exporting to other applications
   and exporting for PostScript printing purposes was not affected.
   This bug has been fixed in version 1.20 of Polygon.

Note that programs which only display ArtWorks files usually cope with polygon
objects very well: OvationPro, Impression and Thumbnail happily display polygon
objects.

Note that polygons created with version 1.10 or later of the Polygon module are
incompatible with older version of the module. Therefore when transferring
files you must make sure that the destination copy of ArtWorks has Polygon 1.10
(or higher) installed.

Polygons with rounded corners as created by Polygon 2 can be loaded and
displayed by copies of ArtWorks with Polygon 1, but when editing such polygons,
their roundness is lost and they revert to having sharp corners.


2) Other features
-----------------
2.1) Undo

The module fully supports the Undo system of ArtWorks. The name of the
operation is 'polygon', so the Menu will show 'Undo polygon' if your last
operation was to create a polygon and 'Undo alter polygon' if your last
operation was to change the properties of a polygon.

2.2) EPS export

The module fully supports exporting polygon objects as ArtWorks EPS. This also
means that all other export formats are supported as well, e.g. Illustrator and
Corel Draw EPS. Note that if you reimport ArtWorks EPS real polygon objects are
created if you have the Polygon module. If you do not have the Polygon module
installed, only paths are created but no error is reported. The EPS generated
by Polygon 2 is fully compatible with that of Polygon 1, but when importing the
EPS generated for a rounded polygon, the Polygon 1 module creates a polygon
with sharp corners.

2.3) Object angle

For each object, ArtWorks keeps track of its current angle. This angle is
displayed next to 'Rotate to' in the info bar while the Rotation tool is
selected. This makes it easy to rotate the polygon to an exact angle. If a
polygon is at 0, then one corner is to the right of the centre and aligned
vertically with the centre. In other words, a straight line from the centre to
one of the corners is at 0 with respect to the x-axis.

So, if you want to rotate a star in such a way that one of its corners points
to the top of the page, then simply rotate it to 90. This will force one of
the corners to a position where a straight line from the centre to it is at an
angle of 90 with respect to the x-axis - which means that it points to the
top.

2.4) Scaling

There is also a rather unexpected feature (which some people might call a bug):
Scaling a polygon with the scaling aspect other than 100% does not work. That
is, you can scale a polygon by any scaling factor, but you cannot scale
differently in x- and y-direction. You are not prevented from doing so but the
result is no longer a polygon, and as soon as you change any its properties
(e.g. the radius), it will revert to a 1:1 aspect.


3) History
----------
Version 2.04 (14-Jul-03):
- fields accept pix units
- inner handle drag snaps to grid if neither angle nor radius constraint is
  active

Version 2.03 (16-Jun-03):
- added help message for Polygon tool

Version 2.02 (01-Apr-03):
- first 32-bit compatible version for ArtWorks 2

Version 2.01 (05-Mar-03):
- corrected bounding box computation for inner rounded inside-out stars, so the
  selection polygon lines and drag blobs are redrawn correctly

Version 2.00 (05-Mar-03):
- fixed dragging of roundness handles for twisted stars - the roundness control
  points now follow the mouse pointer exactly
- fixed minor bug that randomly twisted a star when dragging its inner radius
  handles for the first time after loading ArtWorks
- updated and restructured documentation

Version 1.30 (25-Feb-03):
- corners and inner corners can be rounded - the roundness can be controlled
  conveniently by dragging handles
- requires the wider info bar introduced with Crystal
- other fixes, e.g., Polygon is happy to be the start-up tool

Version 1.23 (28-Mar-02):
- added support for Alpha attribute (Crystal tool)
- fixed problems with attribute inheritance that sometimes caused the colour
  tool to report the wrong colour (black instead of the actual colour of the
  polygon)

Version 1.22 (20-May-01):
- increased maximum number of sides to 400

Version 1.21 (21-Apr-01):
- minor internal fix (Method_DescribeAngle)
- corrected behaviour with Envelopes and Perspectives - you could still
  edit enveloped polygons by dragging their corners leading to inconsistent
  bounding boxes

Version 1.20c (29-09-00):
- German resources update

Version 1.20b (27-07-00):
- documentation update

Version 1.20 (26-06-97):
- extra mode info bar added: numeric editing of inner radius and angular
  offset paramters of stellated polygons, "Reset" and "50%" buttons
- angular offsets are always normalised
- major EPS import problem fixed: correct attributes are now applied to
  Polygon objects

Version 1.17 (05-05-97):
- Fixed problems with 'Make shapes' and blends if Polygon objects were
  inside groups.
- Fixed undo problem: If several Polygon objects were selected while editing
  a Polygon object (using the object handles), undo did not work correctly.
  Thanks to Daniel Krmer for pointing this out.
- new Netherland messages

Version 1.16 (05-04-97):
- fixed bug introduced with version 1.15 (pressing Return after having
  changed the number of sides caused the application to crash)

Version 1.15c (21-03-97):
- added information about PathUtils module to this file

Version 1.15b (17-03-97):
- thanks to Richard G Hallas for improved sprites

Version 1.15 (25-02-97):
- polygons with a radius of 0mm cannot be created any more
- better user interface: when pressing Return, all values are read from
  the info bar
- included version 1.01 of the Intersect tutorial
- updated cheque payment details in [7] yet again
- added section about object angle in [3]

Version 1.14 (05-02-97):
- fixed bug which caused stars to be twisted in a random manner at the
  beginning of an inner handle drag using the Select tool
- further improvement of info bar for German messages

Version 1.13 (14-01-97):
- tidied info bar (looked ugly with German messages)

Version 1.12 (17-12-96):
- Adjust click on up/down arrows implemented
- Shift constrains inner drags as well
- "Germany" and "Netherland" messages files included

Version 1.11 (05-12-96):
- using gadget base &5500 now as Precision is using &5400 although this
  base has in fact been allocated to me
- added cheque details in section [7]

Version 1.10 (23-11-96):
- Corrected spelling mistake ("poygons" instead of "polygons")
- fixed half of an EPS import bug (allows attribute handlers to apply their
  attributes now); so imported polygons have the correct line colour now
  but their fill colour is still not set correctly (note that this only
  applies to the colour displayed when you select the fill colour tool,
  the polygons are still displayed and printed correctly)
- change of licence, see [7] below
- included Intersect tutorial
- the angular offset of stars can be edited by dragging any inner handle

Version 1.01 (15-10-96):
- Fixed bug with perspective and envelope. These should work now as
  expected

Version 1.00 (06-10-96):
- First version released to the public


4) 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/


5) Copyright
------------
The ArtWorks Polygon 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 Polygon
module and its related files, now.

CorelXARA is a Trademark of Corel Corporation and Xara Ltd.
