Intersect 1.06 (22-Apr-03)

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

Welcome to the Intersect module. Make sure that you read section [5]
below which tells you of its copyright status.

This module allows you to intersect shapes (or objects which can be
turned into shapes).

If you are upgrading from a previous version, read section [2].

1) The Intersect module
-----------------------
1.1) How it works

In contrast to the Polygon and Translate modules this module does not
provide its own tool in the tool box because this is not necessary. Instead,
it adds two menu entries to the Lines/Shapes submenu of the main ArtWorks
menu. These are called "Intersect all" and "Intersect with top".
The menu entries appear next to the entries "Join shapes" and "Break
shapes" which perform related functions so this way of presenting the
features of this module should be rather intuitive.

So how do you use it? Simply try it yourself by creating two overlapping
shapes (e.g. a rectangle and an ellipse), selecting them and choosing
"Intersect all". The result is the intersection of both. Note that
this actually alters the lines physically (unlike the "Join shapes" item),
so there is no way to restore the original shapes apart from using Undo.
Needless to say that this module fully supports the ArtWorks Undo system.

The second entry, "Intersect with top", can be used to intersect a whole
selection of items with the top shape. The difference is that with
"Intersect all" you get the area which is covered by all selected shapes
(or all shapes obtained by turning the selection into shapes). Therefore,
"Intersect all" is not very useful if you want to intersect a collection of
shapes (e.g. a text object consisting of several characters) with a common
clipping path. Generally, if you apply "Intersect all" to a selection
containing any two objects which do not overlap, then the whole result is
empty because their intersection is empty.

So most of the time you will probably use the "Intersect with top" entry.
This causes all but the topmost object of the selection to be intersected
with the top shape. For this to work the top object must be a single shape
or convertible to a single shape (e.g. an ellipse or a rectangle or any
single or joined path object).

So to colour the top half of a line of text in one colour and the bottom
half in a different colour, clone the line of text and create a rectangle
covering the top half of the text line. Select the cloned text and the
rectangle and select "Intersect with top". This should leave you with a
shape covering the top half of the text line which can be filled with any
colour.

Note that although you can only use a single path as the clipping path, you
can join several paths to use them as the clipping path. This is one of the
instances when it is actually useful that you can join non-overlapping shapes
which normally does not make sense as it acts like grouping them.

There are keyboard shortcuts for both operations provided by Intersect:
* Ctrl-W for "Intersect all"
* Ctrl-Shift-W for "Intersect with top"

1.2) Known bugs and Limitations

There are limitations on the sizes of objects you can use for clipping. It
does not matter how many selected objects there are but each single one
should not be too large (in terms of the number of control points). If a
shape is too complex you will receive the error "Clipping failed: Path too
complex". This is a limitation of the GDraw module used by Intersect (GDraw
was written by CC and comes with ArtWorks).

A common problem is that the objects which are to be clipped are joined.
As joined objects are regarded as a single path object, clipping such an
object is much more complex than clipping its components one by one. So if
clipping fails and the object which was to be clipped was a joined object,
try "Break shapes", then retry the intersection, then join the results.
Note that here I am referring to the objects which are *under* the top object
when doing an 'Intersect with top' operation.

1.3) Credits

Before you start praising my knowledge of maths: It was not me who wrote
the low-level path clipping routines, they were already there in the GDraw
module. Nevertheless it was a lot of work to get the whole module to work.

But the "real" work was done by the people at CC who wrote GDraw.

2) Changes
----------

Note that when upgrading, you must repeat all the steps detailed in section
[1] if you are using the QuickStart option of ArtWorks.

Most recent changes first:

Changes for version 1.06 (22-Apr-03):
* 32-bit compatible release for ArtWorks 2

Changes for version 1.05b (27-07-00):
-------------------------------------
* documentation update

Changes for version 1.05:
-------------------------
* Fixed some of the clipping problems with GDraw: Intersect 1.05 copes
  with larger clipping tasks than 1.04, so you should see the error
  "Clipping failed: paths too complex" less often. There are still some
  hard constraints that cannot be removed but Intersect 1.05 manages to
  convince GDraw to work in quite a few cases in which 1.04 would have
  given up.

Changes for version 1.04:
-------------------------
* Undo with "Intersect with top" now correctly restores the top object even
  if it was not a path object (e.g. if it was an ellipse); Intersect 1.03
  did not undo the conversion of the top object into a path
* Undo of "Intersect with top" sometimes caused subsequent drag operations
  to show additional outlines of unselected objects leaving a mess on the
  screen. This is fixed.
* Some major bugs removed: Input paths can now be of arbitrary size (did lead
  to crashes with version 1.03 if bigger than 16k).
* When hitting GDraw limitations, Intersect reports "Clipping failed: paths
  too complex" immediately rather than claiming memory until all memory is
  exhausted and reporting "Clipping has failed due to lack of memory" after
  a long time of showing the hourglass. (GDraw is a module that comes with
  ArtWorks and was written by CC)


New features in version 1.03:
-----------------------------
There are keyboard shortcuts for both operations provided by Intersect:
* Ctrl-W for "Intersect all"
* Ctrl-Shift-W for "Intersect with top"

Some major internal bug fixes:
* Previous versions of Intersect often generated paths that were displayed
  correctly but could not be edited because the Path editing tool of ArtWorks
  behaved in a strange way (when dragging one anchor point, two of them would
  move). This happened e.g. when clipping rectangles.
* When joined paths were intersected only the first subpath would have its
  filled bit set, so when breaking the shapes, only one would be filled.
Both these problems should be fixed now.

The module now contains German messages

New features in version 1.02:
-----------------------------
In order to prevent possible incompatibilities with the Precision Tool
(available from CC) which uses some codes allocated to me, I have modified
Intersect to use new codes.

3) Installation

Copy the !Intersect application inside the !ArtWorks.Auto directory.
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
* Open the ArtWorks choices window
* Select 'Quick start' and click on 'Save'

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


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

Phone: +49-(0)631-3608205
Fax:   +49-(0)7034-928915   (slow response!)

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

5) Copyright:
-------------
The Intersect ArtWorks module including all related files is Copyright 1996-98,
by Martin Wrthner.

It may not be copied or transmitted by any means without the prior consent
of the copyright holder. This software is *not* ShareWare/FreeWare/PD.

In order to use this module, you need a licence from the copyright holder.
This licence can be obtained by registering the Polygon module with the
copyright holder. The licence type of the Polygon registration (private user/
commerical or educational user/site licence) applies to the Intersect module
as well. If you do not have either a registration for the Polygon module or
a special personal licence for using the Intersect module, you must delete
this software, the Intersect module and its related files, now.
