Service calls
======= =====

Service_ColourPickerLoaded (service call &93)
-------------------------- -------- ---- ----

   Request colour model modules to register themselves

  ENTRY
      R1 = 0x93 (reason code)
      R2 -> code to be called to register a colour model
      R3 = workspace pointer for ColourPicker

   The ColourPicker uses a system similar to ResourceFS and the Territory
Manager to allow dynamic loading of colour models. When it starts up, it
passes round Service_ColourPickerLoaded. Since it is not yet on the module
chain, it is not yet implementing any SWI's: therefore, it passes round an
address which a module must call in order to register itself as a colour
model module. The entry conditions for this are similiar to those for SWI
ColourPicker_RegisterModel:

      R0 = model no
      R1 -> model data block:
         +0    flags:
                  all words reserved (must be 0)
         +4    pointer to a brief name for this colour model (e g, 'RGB')
         +8    pointer to a longer description, for use in help text
                  (e g, 'Defines the quantity of each primary colour (red,
                  green, blue) present.')
         +12   x0,
         +16   y0,
         +20   x1,
         +24   y1 of the work area extent required by this  model's colour
                    chooser
         +28   pointers to code for the following model-specific functions:
               +0    ColourPicker_EntryDialogueStarting
               +4    ColourPicker_EntryDialogueFinishing
               +8    ColourPicker_EntryRedrawArea
               +12   ColourPicker_EntryReadValues
               +16   ColourPicker_EntrySetValues
               +20   ColourPicker_EntryProcessEvent
      R2 -> model workspace
      R3 -> workspace pointer for ColourPicker (from the service call)

   Colour models currently defined are

      0     ColourPicker_ModelRGB
      1     ColourPicker_ModelCMYK
      2     ColourPicker_ModelHSV

It is possible to adsd more colour models by using this intrface: the numbers
must be allocated centrally by Acorn.

SWI's
=====

ColourPicker_RegisterModel (SWI &46140)
-------------------------- ---- -------

   ENTRY
      R0 = model no
      R1 -> model data, as defined above
      R2 -> model workspace

   This SWI must be called by a colour model module in its initialisation
code. In conjunction with the service call Service_ColourPickerLoaded, this
ensures that the Colour Picker always knows about all the colour models, no
matter which order they started up in.

ColourPicker_DeregisterModel (SWI &46141)
---------------------------- ---- -------

   ENTRY
      R0 = model no

   This SWI must be called by a colour model module in its termination code.
It informs the Colour Picker that the colour model is no longer available.

ColourPicker_OpenDialogue (SWI &46142)
------------------------- ---- -------

   ENTRY
      R0 = flags:
         bit 0: dialogue box is to transient
         All other reserved (must be 0)
      R1 -> block:

         +0    flags:
                  bit 0: dialogue box is to offer a 'None' button
                  bit 1: dialogue box is to have the 'None' button selected
                  bits 2, 3: dialogue box "button type," defining when 
                     Message_ColourPickerColourChanged is issued for it:

                     0: Never issued.
                     1: On any change, except during drags. Drags
                                give message at drag end.
                     2: On any change, including during drags.

         +4    pointer to the title to be used, or 0 for a default title
         +8    x0,
         +12   y0,
         +16   x1,
         +20   y1 of the bounding box of the visible area of the dialogue
                  box - only (x0, y1) are honoured: (x1, y0) should be set
                  to large +ve and -ve values, respectively
         +24   xscroll,
         +28   yscroll of the dialogue box. Only used if the visible area
                  provided in +8, ..., +20 is too small (which should never
                  be the case!), in which case the dialogue box gets scroll
                  bars automatically
         +32   a colour block, defined as follows
               +0    0
               +1    blue value (0, ..., &FF)
               +2    green value
               +3    red value
               +4    size of the remainder of this block (which is optional)
               +8    colour model number (as in the service call)
               +12   other model-dependent data

   EXIT
      R0 = handle for this dialogue box

   This SWI is used by an application that wants to display a Colour Picker
dialogue box to the user, for interactive choosing of a colour. The handle
is used as an argument to the other ColourPicker SWI's, and also in messages
that the ColourPicker module sends to the application to provide feedback on
the user's selection of a colour. The colour descriptor specifies the initial
settings placed into it. The dialogue will always have an OK and Cancel
button. If the allow transparent bit is set then a 'None' button will appear
between the colour patch and the Cancel button. It will selected if the
transparent bit is set.

ColourPicker_CloseDialogue (SWI &46143)
-------------------------- ---- -------

   ENTRY
      R0 = flags:
         all bits reserved (must be 0)
      R1 = dialogue box handle

   Called by the application to close the dialogue. This may also be done by
the WIMP, if the dialogue is a transient one. It is normally called in
response to Message_ColourPickerCloseDialogueRequest.

ColourPicker_UpdateDialogue (SWI &46144)
--------------------------- ---- -------

   ENTRY
      R0 = flags:
         bit 0: whether the dialogue box offers a 'None' button
         bit 1: whether 'None' is currently selected
         bit 2: the button type of the dialogue box
         bit 3: the visible area of the dialogue box (only (x0, y1) are
            honoured)
         bit 4: the scroll offsets (not honoured)
         bit 5: the window title
         bit 6: the colour (r, g, b triplet only)
         bit 7: the colour model (including all the optional data that the
            colour model requires)
      R1 = dialogue box handle
      R2 -> block as in ColourPicker_OpenDialogue

   Changes some or all of the contents of the dialogue box whose handle is
given. Only the parts of the box indicated by the flags word are updated. If
bit 7 is set, bit 6 is ignored: the (r, g, b) triplet is calculated from the
data in the colour model block. The transparent button may be added or
removed and its setting adjusted. The title, colour model and setting may
also be adjusted independantly of each other. If the colour setting is
updated, but not the colour model and the current colour model isn't that in
the colour descriptor then the colour descriptor's RGB word will be used and
the colour model left alone.

ColourPicker_ReadDialogue (&46145)
------------------------- --------

   ENTRY
      R0 = dialogue box handle
      R1 -> buffer, or 0 to read size

   EXIT
      R1 = size required, or preserved if non-0

   Fills the given buffer with a block as in ColourPicker_OpenDialogue. The
block is assumed to be big enough: to find out what size is required, R1 = 0
should be specified. This means you must call the SWI twice in order to use
it safely. This size may change when the colour model changes, so care should
be taken to always ask for the block size before getting the colour.

WIMP Message Numbers
==== ======= =======

   The Colour Picker communicates with its application clients by sending
them messages. The task handle in the message block will always be that of
the task itself.

   Note that in addition to these messages, the application will "see" all
the events (open window requests, mouse clicks, drags etc) that are generated
on the Colour Picker window. It must ignore these.

Message_ColourPickerChoice (message &46141)
-------------------------- -------- -------

   Issued to the application when the user makes a definite choice of
colour, by clicking Select or Adjust on the OK button of the dialogue box.

      +20   handle of the dialogue box concerned
      +24   flags:
               bit 0: 'none' chosen
      +28   colour block chosen

This message is always sent if the relevant event happens (though if the
user closes the dialogue box by pressing Cancel, it will not be sent at
all). When flags bit 0 is set, signifying that 'transparent' was chosen, the
colour descriptor *will* be present. The colour descriptor gives the state of
the dialogue so that a sensible default may be given next time the dialogue
is used.

Message_ColourPickerColourChanged (message &46141)
--------------------------------- -------- -------

      +20   handle of the dialogue box concerned
      +24   flags:
               bit 0: 'none' chosen
               bit 1: drag in progreess
      +28   colour block chosen

   Issued to the application when the colour displayed in the dialogue box
changes, in accordance with the setting of the "button type" of the dialogue.

Message_ColourPickerCloseDialogueRequest (message &46142)
---------------------------------------- -------- -------

      +20   handle of the dialogue box concerned

   Issued to the application when the user dismisses the dialogue box, by
clicking Select on the OK or Cancel icons. The application should respond by
calling ColourPicker_CloseDialogue with the given handle.

   If the dialogue box was opened with the 'transient' flag of
ColourPicker_OpenDialogue set, then it will not see this event for that
box, as the WIMP will close the window automatically.

Error numbers
===== =======

ColourPicker_ErrorUninit (error &20D00)
------------------------ ------ -------

   One of the Colour Picker SWI's to handle a dialogue box has been called,
but the caller is not a WIMP task. The application must be modified to call
Wimp_Initialise before it calls one of these SWI's.

ColourPicker_ErrorBadModel (error &20D01)
-------------------------- ------ -------

   The colour model specified in a colour block was not found among those
registered.

   It cannot be guaranteed that any particular colour model is loaded. The
only safe course is to use a colour block with no model number on the first
entry into ColourPicker_OpenDialogue (by setting the size field to 0), and
then to use the model numbers that it gives back in the Message_
ColourPickerChoice. Since the application is calling Wimp_Poll, it is still
possible that a colour model module may be RMKilled, so we recommend that if
this error is returned, the operation is retried with the colour block size
set to 0.

ColourPicker_ErrorBadHandle (error &20D02)
--------------------------- ------ -------

   The handle given is either not one returned from ColourPicker_
OpenDialogue, or has been closed since then.

ColourPicker_ErrorBadFlags (error &20D03)
-------------------------- ------ -------

   Only the flags defined in the description of each SWI may be set. ASetting
others will result in this error.

ColourPicker_ErrorInUse (error &20D04)
----------------------- ------ -------

   The ColourPicker module cannot be killed while there are dialogues open.
Instead, this error is returned.

ColourPicker_ErrorModelInUse (error &20D05)
---------------------------- ------ -------

   A olour model module caanot be killed while it is in use in an open
dialogue. Instead, this error is returned.

*Commands
=========

ModelList
---------

   SYNTAX
      *ModelList

   Lists all the currently active colour model modules, together with a
brief description of their use.
