ARM Club 3/TheARMClub_PDCD3.iso/hensa/graphics/polygon_1/!Polygon/!Help

Text File | 1997-06-27 | 26KB | 562 lines

Polygon 1.20 (27-Jun-97)

Name:     ArtWorks Polygon module
Purpose:  Handling regular polygon and star objects in ArtWorks
Author:   Martin Würthner
Requires: RISC OS 3.1 or higher, ArtWorks 1.138 or higher
Status:   ShareWare (see [7] below for registering details)

0) Preface
----------

Depending on whether you are upgrading from an earlier version of the module
or whether you are a new user, you will be interested in different things.
Make sure that in any case you read section [7] which contains the details
for registering.

If you are upgrading from an earlier version of Polygon, read section [5.1]
for a list of new features and [5.2] to find out all changes.

Otherwise just go on reading:

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 [7] below for a more detailed Copyright notice). However,
if after a trial period of two weeks, you decide to keep it, you must register
by sending £10 to me.

** New ** When registering, you will also receive two additional ArtWorks
          modules, Intersect and PathUtils, which are reserved for registered
          users of Polygon exclusively.

Quick feature list of Polygon:
* 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, edit inner radius and angular offset of stars
* full integration with existing ArtWorks features (fill types, transformation
  tools, Make shapes, perspective, envelope 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

Do not miss my other ArtWorks modules:
  Translate (FreeWare)
  Intersect (available to registered users of Polygon only)
  PathUtils (available to registered users of Polygon only)
  ShowXY    (FreeWare)
  MadnessT  (FreeWare)
  Hatch     (commercial)

The latest addition to the range of ArtWorks modules is Hatch, a commercial
module providing 5 new fill styles: Hatch, Crosshatch, Chequered, Spots,
Squares. These are dynamic fills, so e.g. hatched text is still editable.
Hatch is available for £20+VAT from Computer Concepts. Registered users of
Polygon can buy Hatch from me directly at a reduced price.

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
it is 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 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.

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.

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

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 inner radius
only. In order to reset the star to its default non-twisted state, click on the
"Stellated" radio button twice or switch to extra mode and click on the "Reset"
button (see [2.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.

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

The info bar in extra mode shows the fields "Inner radius" and "Angular
offset" that behave very much like the other editable fields. 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.

2.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. As the Polygon module is ShareWare, you
   can give it away freely (see [7] below for a more detailed Copyright
   notice). You may either give away the complete Polygon distribution
   (so just keep a copy of the original archive for convenience) or the
   *complete* !Polygon directory including this !Help file.

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

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

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.


3) Other features
-----------------

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

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

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

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


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) History
----------

Note that when upgrading, you have to repeat the steps outlined in section 1
if you use the 'Quick start' option of ArtWorks.

5.1) New features

** New features of version 1.20 **

You can edit the inner radius and the angular offset of stars numerically.
Previous versions only allowed you to do this interactively. These new
features allow you more accurate control over stellated polygon objects.

Section 2.4 above tells you more about these features.

EPS import problems are fixed. See section 2.5.

** New features of version 1.17 **

Several bug fixes, read section 5.2 for details.

Due to some changes in the Undo system of Polygon, the undo buffers contained
in documents created with version 1.16 or earlier of Polygon do no longer work!
This refers only to undo entries belonging to polygon editing operations. Most
people do not use saved undo buffers so this should not be a serious problem.

** New features of version 1.15 **

The user interface has been cleaned up for better integration with the
rest of ArtWorks. Therefore, pressing any of the up/down arrows no longer
confirms the value entered in a writable field. Pressing Return enters the
values of all fields in the info bar. This is the way the other ArtWorks
tools behave.

Polygons with a radius of 0mm cannot be created any longer. These led to an
internal error when resizing.

** New features of version 1.12 **

Polygon 1.12 fixes a minor omission of 1.11: While pressing Shift constrains
the radius when dragging an outer handle of a star, it does not do so for
drags of an inner handle. This has been added, so Ctrl and Shift constrain
the angle/radius for both inner and outer drag operations. Another minor
update (requested by S.W. Tengelsen) is that clicking Adjust on the up/down
arrow buttons now decreases/increases the number of sides instead of acting
like Select.
  Messages files for Dutch and German users have been added (the Dutch files
were supplied by Dick Tanis and used with his kind permission).

** New features of version 1.11 **

Polygon 1.10 and below were incompatible with the Precision Tool (available
from CC) as the latter is using some codes which are in fact allocated
to me. As it is improbable that there will be a fix for the Precision Tool
I have applied for some new codes and modified all my modules to use these.

There is an important addition in this file: If you intend to register by
sending a cheque please make sure you read the registering details below.
Search for "IMPORTANT".

** New features of version 1.10 **

Polygon 1.10 has one major new feature: When editing stars by dragging an
inner handle, you can not only change the inner radius of the star but you
can also twist it. Simply drag the inner handle to any position.

If you want to maintain the degree of twisting of a star while editing its
inner radius, hold down Ctrl while dragging. If you want to reset a star
to its default non-twisted state, click on the "Stellated" radio button
twice.

Note that polygons created by version 1.10 of the Polygon module cannot
be rendered correctly by old versions of the module (they appear twisted
even if they are not). Of course, Polygon 1.10 can handle polygon objects
created by older versions of the module.


5.2) History list

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 Krämer 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 public

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

Phone: [phone]
Fax:   [phone]   (new fax number!)

e-mail: [e-mail]
        (might expire in summer 97)


7) Copyright:
-------------
This ArtWorks module including all related files is Copyright 1997
by Martin Würthner and is ShareWare.

This means that you may copy it freely provided that
(a) all files of this ArtWorks module 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 it is sold for profit or to distribute it together
    with other commercial software
I retain the copyright on all files.

You may use this module free of charge for a trial period of up to two
weeks. If you then decide to go on using the module, you have to register.
Otherwise, you have to deinstall the module.

How do I register?
------------------
In order to register as a private user, send £10 (or your country's equivalent
of this sum) to me (for my address see [6]). You may send bank notes (in any
currency), cheques (drawn from UK or German banks only), Eurocheques (in
Pounds, if drawn from a UK bank, else in DM). International postal orders are
welcome.

IMPORTANT: All cheques should be made payable to Martin Wuerthner.

If you have an e-mail address, please specify it when registering. This will
enable me to send you updates and information about new modules.

If you are a professional or educational user then you must obtain a special
licence which is £25. Note that it is illegal to use this software for
commercial or educational purposes without this licence. The registration fee
of £25 allows you to use the software on one stand-alone machine.
A site-licence is £50 (unlimited number of machines at one site, i.e. at a
single postal address). Whatever licence type you go for, the same licence
applies to the Intersect and PathUtils modules as well.

What do I get?
--------------
As a registered user, you will receive a disc with the latest versions of
Polygon, Intersect, PathUtils and some FreeWare ArtWorks tools: ShowXY,
MadnessT and Translate. As a registered user, you are allowed to use the
software on one stand-alone machine and you are entitled to receive free
upgrades by sending a self-addressed envelope containing a formatted disc
and return postage to me (note that it is not necessary to send an envelope
or disc when registering).

The disc you receive as a registered user of Polygon will contain the new
Intersect and PathUtils modules. Intersect allows you to intersect shapes.
Using this module you can create many interesting effects, including hatching,
pattern filling and transparency effects. PathUtils allows you to control the
angle and length of lines easily. Intersect and PathUtils are *not* ShareWare,
so the only way to get them legally is to register for the Polygon module.

Remember that the development of ArtWorks modules is quite complex and
time-consuming. Therefore, support the development of further ArtWorks
modules by registering.

¹CorelXARA is a Trademark of Corel Corporation and Xara Ltd.