                              Colourpicker Interface
                              ======================
Overview
--------
   Rabbit scripts may sometimes allow the user to configure aspects of its
appearance including colours. Rabbit provides an interface to the Risc OS colour
picker module for this purpose.


Technical Details
-----------------
   When a script requires the user to make a colour selection, e.g. following a
click on an icon, it calls the open_cpicker command. If and when the user makes
a colour selection it is reported to the script via the colour_selection entry
point.
   The script is not notified if the colour picker is closed without a selection
having been made. Also note Rabbit will only have one colour picker window open
at once. Should another script or Rabbit itself require a colour picker while
there is already one open, then it is reassigned.
   All colours are in the standard 32 bit notation used y ColourTrans, i.e.
&BBGGRR00


Commands
--------

int open_cpicker(int colour)

   * Parameters:

       colour     - The colour initially displayed by the colour picker.


   * Returns: A colour picker handle if sucessful, -1 if not.

  opens a standard Risc OS colour picker. If a colour is selected it is
reported to the colour_selection entry point.




void close_cpicker(int handle)

   * Parameters:

       handle     - The handle of the colour picker to be closed.

   closes a colour picker previously opened by open_cpicker(). It can safely be
used if the colour picker has been closed without the owner's knowledge as it
will not cause an error if passed an invalid handle.


Entry Points
------------

void colour_selection(int handle; int colour)

   * Parameters:

       handle     - The handle of the colour picker in which the selection was
                    made.
       colour     - The colour selected.

   is called following a selection of a colour in a colour picker window owned
by the script. This does not necessarily result in the colour picker being
closed, so its handle may remain active following a call to this entry point.
Should this not be what is desired, then it should call close_cpicker().
