Polygon 1.00 (06-Oct-96)

Name:     ArtWorks Polygon module
Purpose:  Handling regular polygon and star objects in ArtWorks
Author:   Martin Wrthner
Requires: RISC OS 3.1 or higher, ArtWorks 1.1 or higher
Status:   ShareWare (see below for registering details!!!)

Welcome to the first non-commercial ArtWorks plug-in module!

This module provides a tool which allows you to create regular n-sided
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. This tool was inspired
by CorelXARA's QuickShape tool.

This module is ShareWare. You may copy it freely and give it away to anyone
free of charge (see [6] below for a more detailed Copyright notice). However,
if you find it useful, you are strongly encouraged to register and support my
work with your registration fee of 10. See [6] below for details.

Quick feature list:
* creation of regular n-sided polygons and stars (n in [3..49])
* numeric and interactive editing facilities for polygons and stars: change
  radius, number of sides, angle etc. at any time, turn polygons into stars
  and vice versa
* full integration with existing ArtWorks features (fill types, transformation
  tools, Make shapes etc.), i.e. polygon objects behave exactly like other
  ArtWorks shapes (ellipses, rectangles, rounded rectangles)
* full support of ArtWorks undo system and EPS export and import


1) Installation

Copy the !Polygon application inside the !ArtWorks.Auto directory. (Shift
double-click on !ArtWorks to open it, then double-click on the 'Auto' folder.
Then drag the !Polygon application to the Filer window showing
<something>.!ArtWorks.Auto in its title bar). This will cause ArtWorks to
load the module automatically next time it is started.

If you are not using the 'Quick start' feature of ArtWorks, then this is it
already. Otherwise (this is recognized by the fact the ArtWorks only displays
one icon 'Quick start' when starting up) you have to go on:

If the 'Quick start' option is selected in the ArtWorks choices window you
have to perform the following steps in order for ArtWorks to recognize the
new module:

* Load ArtWorks
* Open the ArtWorks choices window (icon bar menu 'Choices...', then click on
  the ArtWorks icon in the ArtWorks global choices window)
* Deselect 'Quick start' and click on 'Save'
* Quit ArtWorks
* Reload ArtWorks - while loading ArtWorks shows every module it loads, this
  should now include the Polygon module. If ArtWorks displays an error message
  like "Due to lack of memory one or more modules could not be loaded ..."
  something has gone wrong and you should check whether you have correctly
  installed the module.
* Open the ArtWorks choices window again
* Select 'Quick start' and click on 'Save'

If you ever should want to deinstall the module, remove the !Polygon
directory from the !ArtWorks.Auto directory. Then, if you are using
the 'Quick start' option, you must repeat the same steps above.


2) 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.

2.1) Creating polygons and stars

While the Polygon tool is selected, the info bar displays the field 'Sides',
'CentreX', 'CentreY' and an option button 'Stellated'. 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
will be rendered as a filled shape.

2.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 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.

2.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.

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). However, if you drag the inner corners, only
the inner radius is changed and the outer radius stays the same.

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.

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.

2.4) 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. As the Polygon module is ShareWare, you
   can give it away freely (see [6] below for a more detailed Copyright
   notice).
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
   * copies of ArtWorks without the Polygon module will load the polygons
     as path objects

Note that programs which only display ArtWorks files usually cope with
polygon objects very well: Impression and Thumbnail happily display polygon
objects. The same should apply to Ovation Pro, Composition or any other
program which claims to read ArtWorks files. If you should experience any
problems, try converting the polygons to shapes before exporting.


3) Other features

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.

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. Therefore, exporting as ArtWorks EPS is a safe way if
you do not know whether the destination copy of ArtWorks has the Polygon
module installed.

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, so as soon as you change
its properties, it will revert to a 1:1 aspect.

 
4) Take part in creating new ArtWorks modules!

If you have some spare time and you are wondering what to do with it: What
about writing a new ArtWorks module? You will need the ArtWorks SDK first,
which costs about 40, but it is worth the money. Lots of documentation and
most of the source code for the standard ArtWorks modules.

If you have really good ideas about what useful things an ArtWorks module
could do, do not hesitate to contact me. I will try and collect everything
the current user base of ArtWorks really needs.


5) Contacting me:
-----------------
Martin Wuerthner
Jahnstrasse 18
71116 Gaertringen
Germany

Phone: +49-7034-928986
Fax:   +49-7034-928988

e-mail: wuerthne@trick.informatik.uni-stuttgart.de
        (might expire in summer 97)


6) Copyright:
-------------
This ArtWorks module including all related files is Copyright 1996
by Martin Wrthner and is ShareWare.

This means that you may copy it freely provided that
(a) all files of this application are distributed together without
    modification
(b) this application is not sold for profit without my explicit written
    permission - you also have to apply for permission to distribute this
    program on a CD if any charge is made for it or together with other
    commercial software for which a charge is made
I retain the copyright on all files.

If you find this module useful and you are a private user, you are strongly
encouraged to register by sending 10 (or your country's equivalent of this
sum) to me. Of course, if you think that this piece of software is worth more
than 10, you are welcome to send more.

As a registered user, you are allowed to use the software on one stand-alone
machine and you are entitled to receive free upgrades as they become
available by sending a self-addressed envelope containing a formatted disc to
me. Alternatively, upgrades may be requested by e-mail.

If you are a professional or educational user then you *must* register if you
use this module. It is illegal to use this software for commercial or
educational purposes unless you are registered. The registration fee for
professional or educational users is 25 (one stand-alone machine) or 50 for
a site licence (unlimited number of machines at one site, i.e. at a single
postal address).

You may send cheques (drawn from UK or German banks only), Eurocheques or bank
notes. For my mail address see [5].

Remember that the development of ArtWorks modules is quite time-consuming and
that it would never have been viable for a company to produce this piece of
software. Therefore, support the development of further ArtWorks modules by
registering.

CorelXARA is a Trademark of Corel Corporation and Xara Ltd.
