Filter 1.07 (07-May-03)

Name:     ArtWorks Filter module
Purpose:  ArtWorks module for selection filtering
Author:   Martin Wrthner
Requires: RISC OS 3.5 or higher, ArtWorks 2
Status:    Martin Wrthner 2001; see [4] below
WWW:      http://www.mw-software.com/

Welcome to the Filter module. This module allows you to filter the current
selection depending on filter conditions, e.g. object type, fill style, line
colour, font size etc.

This allows you e.g. to change all red objects to blue by selecting all objects
first, filtering the selection so that only red objects remain and then
applying a blue fill colour to them. Note that Filter only handles the
selection of the relevant objects, it does not handle things like replacing
attributes. To do so, you can use standard ArtWorks features. Using these is
usually easy once the current selection consists of exactly the objects you
need. E.g. in order to replace one line width by another, simply use Filter to
select the objects with the line width that is to be replaced and then apply
the required new line width to the filtered selection.

The Filter module is very powerful but not entirely easy to understand. So,
please make sure you read all of the manual below.


1) The Filter module
--------------------
In contrast to many other ArtWorks modules this module does not provide its own
tool in the tool box because this is not necessary. Instead, it adds a menu
entry to the 'Objects' submenu of the main ArtWorks menu. This entry is called
'Filter'.

Filter allows you to filter the current selection using a range of filter
conditions, such as object type or certain attributes that apply to the object.
It looks at each selected object in turn and deselects it if it does not meet
the filter condition. If you want to select all objects in the document that
satisfy the filter condition, use ^A (or 'Select All' from the 'Objects' menu)
before using Filter.

Note that Filter works on top-level objects only (as these are the only ones
that can be selected in ArtWorks). So, each Group, Blend, Perspective,
Envelope and Replicate is treated as one object irrespective of its contents.
If you want to select only some of the objects that are inside a group, you
have to ungroup them first.

There is a keyboard shortcut for Filter which is ^A (Shift-Ctrl-A). The reason
for having this is that most of the time you will use ^A immediately before
using Filter, so pressing ^A afterwards is rather straightforward.

The Filter dialogue box
-----------------------
Choosing 'Filter' from the 'Objects' submenu or pressing ^A opens the Filter
dialogue box. If nothing happens, then most probably this is because you have
not selected any objects. Select the objects you are interested in or press
^A to select all objects.

The Filter dialogue box may look a bit complicated at first glance, but it is
straightfordward to use and you will not need to use its advanced features
(like specifying the start and/or end colours of graduated or radial fills)
most of the time.

After specifying all the options you want (these are explained below), click on
the 'Filter' icon to filter the current selection. This means that every
selected object is checked in turn and deselected if it does not pass the
filter condition. Note that the Filter module never *selects* any objects, it
only operates on the current selection and deselects objects that do not pass
the filter condition. This may seem more complicated than necessary but gives
you more flexibility as it allows you to apply a filter to part of a document
only (e.g. you could drag a box to select the top half of the document only and
then apply a filter to this selection).

'Deselect' performs the opposite of 'Filter', i.e. it deselects all objects that
match the filter specification. In other words, it leaves those objects selected
that would be deselected by 'Filter' and vice versa.

If you want the Filter dialogue box to remain on screen after applying the
filter, use Adjust rather than Select to click on 'Filter or 'Deselect'.

'Reset' allows you to reset the dialogue box to its initial state.

1.1 ) The top-level options
---------------------------
The box contains quite a number of option icons. The most important are the
six top-level options:
  * 'Object type'
  * 'Fill style'
  * 'Line colour'
  * 'Line Width'
  * 'Font name'
  * 'Font size'

Each of these controls a group of other icons. If the top-level option icon is
off, then the group is shaded. This means that the relevant condition is not
checked ("don't care").

So, if you leave e.g. 'Object type' off, then the types of objects do not
matter. If you switch 'Object type' on, then only the objects specified in the
'Object type' group are allowed to pass the filter.

Object type
===========
The 'Object type' group box contains option icons for all object types ArtWorks
provides (this includes new object types as supplied by the various add-on
modules). By switching an icon on, you allow objects of the corresponding type
to pass the filter. The buttons 'All' and 'None' switch all options on and off
respectively.

Instead of having one option icon 'Path object', Filter provides you with two
options: 'Open path (line)' and 'Closed path (shape)'. Selecting both covers
all path objects.

Fill style
==========
This is by far the most complicated condition group. This option is used best
in conjunction with the object types 'Closed path', 'Ellipse', 'Rectangle',
'Rounded rectangle', 'Polygon' and 'Text line'. The fill style attribute does
not make any sense with the other object types, so that the result of applying
a 'Fill style' filter on them is undefined.

As usual, if 'Fill style' is off, then the fill style of objects is not taken
into account at all.

If 'Fill style' is on, then the four options 'Flat fill', 'Graduated', 'Radial'
and 'Hatched' and optionally further restricutions determine which fill styles
pass the filter. E.g. if you select only 'Flat fill' and leave 'Graduated',
'Radial' and 'Hatched' off, then only objects with a flat fill pass the filter.

You are not limited to selecting only one fill style. You can e.g. select
'Graduated' and 'Radial' to deselect all objects that do not have a graduated
or a radial fill.

Flat fill
---------
You can restrict the filter further by switching the option icon next to 'Flat
fill' on. This unshades a colour field where you can select the very colour you
are interested in. You can select 'None' ('Transparent' in the German version)
as well.

Filter interacts with the ColourBar module: Wherever you can choose a colour
from the colour menu, you can alternatively drop a colour dragged from the
Colour Bar onto the colour field. Dragging a colour from the Colour Bar to the
flat fill colour field automatically switches the "Fill style" and "Flat fill"
options on.

Graduated and Radial fills
--------------------------
You can restrict 'Graduated' and 'Radial' further by specify the start or end
colours of the fills. Each of the two fill styles has two colour fields next to
it: the top field controls the start colour and the bottom field controls the
end colour. If you leave the option icons next to these colour fields off, then
no restriction is imposed on the corresponding colour.

E.g. if you are only interested in objects with a radial fill that ends in Red,
switch 'Radial' on and switch the option icon next to the bottom of the two
colour fields next to 'Radial' on. This unshades the colour field and allows
you to select the colour 'Red'.

If you drag a colour from the Colour Bar to one of the colour fields, then
apart from filling in the dragged colour into the colour field, this also
switches the corresponding option buttons on - i.e., if you drop a colour on
the radial colour "From" field, then the "Fill style", "Radial" and the radial
"From" options are switched on.

Hatched
-------
Applying a 'Hatched' filter only make sense if you have the Hatch or HatchPro
module installed. These modules provide dynamic pattern fills.

If 'Hatched' is switched on, you can select the exact fill styles you are
interested in by selecting the relevant option icons next to the hatch style
samples. These are, from left to right: Hatch, Crosshatch, Chequered, Spots,
Squares and Hexagonal spots. Note that if you forget to select any of these,
hatched objects will not pass the filter at all. So, if you switch 'Hatched'
on, you have to specify which types exactly you are interested in. If you are
interested in hatched objects generally, then select all 6 hatch types.

The two colour fields are for the foreground (top colour field) and background
(bottom colour field) colours of the hatch fill. The work in a similar way as
for graduated and radial fills above (and they also support drags from the
Colour Bar).

So, to leave only Spots and Squares filled objects with a foreground of Red
selected, switch 'Hatched' on, select the Spots and Squares option icon (the
4th and 5th from the left) and switch the option icon next to the top colour
field on. Then, choose 'Red' from the menu.

Line colour
===========
If 'Line colour' is set, then only objects that have the line colour specified
in the corresponding colour field pass the filter. In order to select objects
without a line colour choose 'None' ('Transparent' in the German version).

Line width
==========
If 'Line width' is set, then only objects that satisfy the specified condition
pass the filter. You can select the required operator ('<', '<=', '=', '>=' or
'>') from the Relation menu you obtain by clicking on the pop-up menu button
next to the field showing the currently selected operator.

Example: You want to leave only objects with a line width of exactly 0.5pt
selected. To do so, choose '=' from the Relation menu and enter 0.5pt in the
writable field, then click on 'Filter'.

Example: You want to leave only objects with a line width of 1pt or greater
selected: To do so, choose '>=' from the Relation menu and enter 1pt in
the writable field, then click on 'Filter'.

Font name
=========
The pop-up menu icon allows you to choose a font name from the font menu. Only
objects to which specified font name applies pass the filter. This option is
really only useful in conjunction with an 'Object type' filter for 'Text line'
objects only. Note that using only a 'Font name' filter without an 'Object
type' filter does not necessarily deselect objects to which the concept of a
font name does not apply. The result is merely undefined.

Font size
=========
The 'Font size' field works very much like the 'Line width' field, the only
difference being that the condition is checked with respect to the font size
that applies to the object. Like 'Font name', this option is really only useful
in conjunction with an 'Object type' filter for 'Text line' objects only.

1.2) Other points to note

Overprinting
------------
ArtWorks allows objects to overprint. When selecting a colour, you can choose
whether or not the colour should overprint (Overprinting is explained in the
Commercial Priting Guide). Note that a colour with overprint is considered
different from the same colour without overprint! So, if the filter specifies
'Line colour' Red, then objects with line colour Red with 'Overprint' switched
on will not pass the filter.

Attributes
----------
Not all attributes apply to all object types. E.g. the 'Font name' attribute
only applies to 'Text line' objects. If you apply a 'Font name' filter on any
other object type, then the result is undefined.

The object types 'Group', 'Perspective', 'Envelope' and 'Blend' do not have
any attributes at all. So, again, the result is undefined when applying any
attribute filters to them.

Colours
-------
In ArtWorks, colours live in documents only. Therefore, if you change the
edited document and open the Filter dialogue box again, the colours are all
reset to 'None' ('Transparent' in the German version). This happens even if
there exists a colour with the same name in the other document.

1.3) Typical problems

Q: I have pressed ^A but the Filter dialogue box does not appear
A: Probably there is no current selection. Press ^A first to select all
   objects.

Q: I have clicked on 'Filter' but this did not select the wanted objects
A: Filter never selects any objects, it only deselects those which are not
   appropriate.

Q: After clicking on 'Filter', no objects are selected at all.
A: a) You did not select any objects before clicking on 'Filter'.
      Press ^A and try again.
   b) Your filter was too restrictive:
      1) You may have switched 'Object type' on but none of the object
         type icons 'Open path', 'Closed path' etc ... 'Sprite'.
      2) you may have selected 'Fill style' but none of the fill style icons
         'Flat fill', 'Graduated', 'Radial', 'Hatched'.
      3) You might have used an incompatible object type/attribute combination,
         e.g. 'Ellipse' and 'Font name' or 'Sprite' and 'Line colour'.

Q: I wanted to select all hatched objects but all objects were deselected.
A: You might have switched 'Hatched' on but forgotten to select any of the
   hatch fill styles.


2) History
----------
Version 1.07 (07-May-03):
- 32-bit compatible version for ArtWorks 2

Version 1.06 (25-Sep-01):
- added Replicate, JPEGObject and TextArea objects
- added hexagonal spots hatch type
- made the main Filter dialogue box a scrollable pane window inside the
  actual dialogue box with the action buttons
- supports colour drag protocol, so colours can be dragged from the Colour Bar
  to all colour fields in the Filter dialogue box
- added German and (thanks to Dick Tanis) Dutch resources

Version 1.05c (25-Aug-00):
- updated documentation

Version 1.05b (11-Aug-97):
- moved font size relation menu icon to proper position

Version 1.05 (28-Jul-97):
- added 'Reset' and 'Deselect' buttons

Version 1.04 (28-Jul-97):
- fixed handling of relations (was wrong way round :-()
- fixed buffer problems with filter dialogue box (?)
- fixed interactions between line width/font size and rest

Version 1.03 (25-Jul-97):
- first beta release version


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 Filter 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 Filter
module and its related files, now.
