ColourBar 1.11 (04-Apr-03)

Name:     ArtWorks ColourBar module
Purpose:  ArtWorks module providing a drag 'n drop colour bar
Author:   Martin Wrthner
Requires: RISC OS 3.1 or higher, ArtWorks 1.138 or higher, PathTool 0.07 or
          higher
Status:    2003 Martin Wrthner; all rights reserved; see [5] below
WWW:      http://www.mw-software.com/

Welcome to the ColourBar module! This module allows you to apply fill and line
colours simply by dragging colours from the Colour Bar to the objects you want
to apply them to.

For installation instructions, see [3] below.


1) The ColourBar module
-----------------------
The ColourBar module does not add a new tool to the Tool Box. In fact, it is
one of its strengths that it does not - you can use the Colour Bar at any time,
no matter which tool you have selected. When you load ArtWorks the first time
after installing ColourBar, you should see the Colour Bar window as soon as you
open an ArtWorks document and select it (i.e., as soon as it gets a cream title
bar to show that it is the currently selected document).

The Colour Bar shows all the colours that have been defined for the currently
selected document. In addition, there are two special icons at the left-hand
side: These are for the two special colours "None" and "Registration black".

The shape of each colour patch indicates the type of the colour: Process
colours are square, tints are square with the top-right corner cut off and spot
colours are circular.

1.1) Applying colours using the Colour Bar

There are two ways to use the Colour Bar to apply colours: You can either drag
a colour patch from the Colour Bar to an object in the document window or you
can select objects and click on a colour patch in the Colour Bar to apply this
colour to the selected objects.

In both cases, using the left mouse button (Select) changes the fill colour and
using the right mouse button (Adjust) changes the line colour of the object(s).
The effect is exactly the same as if you had applied the colour using the
standard fill tool.

It is possible to drag a colour while there is a selection without affecting
the selected objects even though this may seem impossible because you cannot
drag a colour without first clicking on it: However, ColourBar simply waits
until you release the mouse button or start a drag by moving the pointer away,
so you have the choice: Click normally on a colour patch to apply the colour to
the currently selected objects or start a colour drag by keeping the mouse
button depressed. You can move the pointer away immediately to start a drag
without having to wait for the dashed box to appear.

The "None" and "Registration black" icons work in the same way as the colour
patches - you can click on them or drag them to objects, either with Select or
Adjust, to set the fill or line colour of objects to "None" or "Registration
black".

In addition to dragging colours to objects in the current document window, you
can also drag colours from the Colour Bar to Info Bar colour fields, e.g. the
start and end colour fields of the graduated or radial fill tools, or the fill
and line colour fields of the flat fill tool.

In order for a colour drag to the info bar or a dialogue box to have an effect,
the target module needs to support colour drags. At the time of writing,
PathTool 0.08 or higher (as supplied with ColourBar) and the Filter module are
the only modules to support colour drags. Other modules, e.g. Hatch(Pro)
(colour fields in the Info Bar) and the sprite tool (colour fields in the
sprite Contone dialogue box) have not been updated yet to support colour drags.

1.2) Editing colours

You can open the colour editor for a colour by simply clicking Menu over its
colour patch in the Colour Bar. If you click Menu over the empty space to the
right of the last colour patch, then the "New colour" dialogue is opened.

If you create a new colour (either by using the "New colour" dialogue or by
importing an ArtWorks colour table), or if you delete a colour, the Colour
Bar is updated immediately.

1.3) Controlling the colour bar position

The Colour Bar can be switched on and off by opening the ArtWorks document menu
and choosing the menu entry "Utilities => Show colour bar". The entry below,
"Attach colour bar" controls whether the Colour Bar moves with the document
window. If this entry is ticked, then ArtWorks will always keep the relative
position of the Colour Bar the same. The entry has a sub-menu that allows you
to choose whether the reference point for this relative position is the bottom
or the top of the document window. You should use "To top of doc window" if you
want to keep the Colour Bar above the document window because this means that
it will not be moved when you move the bottom edge of the window only (i.e.,
when you resize the document window).

Changing any of the attachment options does not move the colour bar in any way.
Simply move the Colour Bar to your favourite position by dragging its grey drag
handle at its left-hand side. If "Attach colour bar" is ticked, then the
relative positionof the Colour Bar will be maintained when you move the main
document window.

If you choose "Save choices" from the ArtWorks icon bar menu, then the
attachment options, the relative Colour Bar position and the colour bar width
are saved, so when you load ArtWorks the next time, the Colour Bar will be in
your favourite position.

The Colour Bar width stays the same when you change between documents, so even
if a document has very few colours, the Colour Bar does not shrink unless you
resize it manually. If you want to retain the current width for the future,
simply choose "Save choices" from the ArtWorks icon bar menu. If you want a
very wide Colour Bar, you may have to create a few colours first to allow you
to drag the Colour Bar to the desired width - once you have saved the width by
choosing "Save choices", it well be retained even if you later work with
documents containing fewer colours.

If the Colour Bar is not attached, then only its width but not its absolute
position is saved when you save choices.

1.4) Colour names

In contrast to the colour menu, the Colour Bar does not show any colour names.
However, ColourBar responds to the help protocol, so if the pointer is over a
colour patch and the interactive help application is loaded, then the name of
the colour is displayed in the help window.

You can use the rather archaic standard interactive help application !Help as
supplied with RISC OS or one of its more advanced replacements, e.g.,
BubbleHelp by Miles Sabin/David Pilling or the Freeware Float application by
Stephen Fryatt (http://www.stevefryatt.org.uk/software/). The latter two have
the big advantage that the help text pops up in a small window next to the
pointer only if the pointer has not been moved for a while. This resembles the
industry standard "tool tip" convention.

2) History
----------
Version 1.11 (04-Apr-03)
- 32-bit compatible, support for Method_ModuleInfo

Version 1.10 (11-Feb-02)
- clicking Menu to the right of the last colour patch works correctly now - in
  earlier versions not all positions to the right of the last patch were
  detected
- if a colour is added (either by creating a new colour or by importing a
  colour table) or deleted, the colour bar is updated immediately

Version 1.09 (02-Aug-01)
- ColourBar responds to help requests and sends the name of the colour the
  pointer is over to the Help application
- German and Dutch messages added (thanks to Dick Tanis for the translation)

Version 1.08 (11-Jun-01)
- colours can be dragged to colour fields of dialogue boxes and in the Info
  Bar, currently, only the PathTool flat, graduated and radial Info Bar fields
  are supported (requires PathTool 0.08)

Version 1.07 (28-May-01)
- bug fix: if the selected window was changed, applying colours by clicking did
  not work correctly (only in the last window opened)

Version 1.06 (17-May-01)
- spot colour redraw corrected

Version 1.05 (14-May-01)
- None and Registration black icon functionality corrected

Version 1.04 (13-May-01)
- rewrote button handling - it is now possible to drag a colour without
  performing a "click" operation first, i.e. without affecting the selected
  objects
- the target object of a colour drag is always selected, "Colour drag selects
  target object?" option removed - now that you can drag without affecting
  the selected objects, there is no reason why you would want to switch it off
- deselection icon removed - not needed any more

Version 1.03 (11-May-01)
- if the ColourBar is attached and the main window is put to the back or front,
  then the ColourBar is moved with it
- the width of the Colour Bar is stored when the choices are saved
- redraw of tints and spot colours fixed
- added "Colour drag selects target object?" configuration option - if this is
  set to "Yes" in !ArtWorks.!Choices, then ColourBar selects an object after a
  colour has been dragged to it

Version 1.02 (09-May-01)
- first release version


3) Installation
---------------
Copy the !ColourBar 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 !ColourBar
directory from the !ArtWorks.Auto directory. Then, if you are using the 'Quick
start' option, you must repeat the same steps above.


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