The colour picker
=================


Introduction and Overview
-------------------------

RISC OS 3.5 supports a much greater pixel depth than previous versions, and
can display up to 16 million colours. The colour picker module is a utility
that allows users to pick a colour from this immense choice. This utility
should be used by all applications that need to choose colours.

This chapter describes how a client application and the colour picker module 
interact.


Terminology used
----------------

The colour picker module provides a colour picker dialogue for applications
to use;  different types of dialogue are available. The dialogue is not a
Wimp task. The  colour picker makes use of the Wimp filter mechanism to
receive events for its  dialogues.

A colour picker client is an application which use the colour picker. All
clients must  be Wimp tasks.

A colour descriptor is a structure giving the full details of a colour.


Technical details
-----------------

How the colour picker works

The colour picker works as follows:

o       The client application communicates with the colour picker by calling
        SWIs. 

o       Whenever a client opens a new colour picker dialogue, the colour
        picker module installs a Wimp pre-filter and post-filter box around
        that client application.

o       The colour picker module then maintains the colour dialogue by
        intercepting  Wimp events directed to it, and passing the user's
        colour choices to the client  using Wimp messages.

o       Once the dialogue is opened, it is identified in all SWIs and
        messages by a  handle. This avoids confusion if multiple clients are
        using the colour picker at  once.


Typical usage
------------

From the client's point of view, a typical colour selection looks like this:

        Client receives colour selection request by user
        Client prepares structure describing dialogue
        Client issues the SWI ColourPicker_OpenDialogue
        User makes colour selection
        Client receives the message Message_ColourPickerColourChoice
        Client applies colour information


SWIs and messages used
----------------------


SWIs
----

The full range of SWIs that clients may use are as follows:

o       ColourPicker_OpenDialogue -     Creates and opens a colour picker 
                                        dialogue for a client.

o       ColourPicker_CloseDialogue -    Closes a colour picker dialogue 
                                        which is in progress.

o       ColourPicker_UpdateDialogue -   Updates some or all of the 
                                        contents of a colour picker dialogue.

o       ColourPicker_ReadDialogue -     Reads the current state of a colour 
                                        picker dialogue without changing it.

o       ColourPicker_HelpReply -        Makes the colour picker respond to a 
                                        Message_HelpRequest with its own help text.


Messages
--------

The messages that the client may receive are:

o       Message_ColourPickerColourChoice -      issued whenever the user 
                                                makes a definite choice of colour.

o       Message_ColourPickerColourChanged  -    optionally issued when the colour 
                                                displayed in the dialogue changes.

o       Message_ColourPickerCloseDialogueRequest - optionally issued when the user 
                                                   dismisses the dialogue.

o       Message_ColourPickerOpenParentRequest - issued when the user opens a toolbox 
                                                dialogue's parent by clicking Adjust or 
                                                Shift-Adjust on its Close icon. 


Dialogue types
--------------

When the client calls ColourPicker_OpenDialogue to create and open  the
colour picker dialogue, it can choose between different types of dialogue:

o       A normal dialogue has OK and Cancel buttons, and issues
        Message_ColourPickerColourChoice when OK is used

o       A toolbox dialogue has no OK and Cancel buttons, but has Back and
        Close icons  on its window. It never issues
        Message_ColourPickerColourChoice; the client  can call
        ColourPicker_ReadDialogue to read the colour when it needs to, or
        monitor the colour continuously by making the dialogue issue
        Message_ColourPickerColourChanged.

o       A menu dialogue is like a normal dialogue, but is opened using 
        Wimp_CreateMenu; it is therefore automatically closed by the Wimp
        when the  user clicks elsewhere.

o       A submenu dialogue is like a menu dialogue, except that it is
        attached to an open  menu tree, and hence created using
        Wimp_CreateSubMenu.


Transient dialogues
-------------------

Because the closing of menu and submenu dialogues is handled by the Wimp 
rather than the colour picker, they are classed as transient dialogues.


Colour descriptors
------------------

Colours are passed to and from the colour picker as a colour descriptor,
which is a  structure of two or more words.

The colour is always held in a word as a 24 bit RGB value; the simplest form
of a  colour descriptor has no extra information. However, the descriptor may
also hold  data giving a colour model, the colour value as represented in
that model, and  optional extra data. Clients may store the entire colour
descriptor, and make full  use of the information it stores.

A colour descriptor has this structure

Offset  Data

0       0
1       blue value  (0-&FF)
2       green value (0-&FF)
3       red value   (0-&FF)
4       size of optional extension to the block

The optional extension consists of:

Offset  Data

8       colour model number: 0=RGB, 1=CMYK, 2=HSV
12      colour model dependent data (see below)

An application may treat the colour descriptor as a self contained block to
be  stored away, and retrieved for use later with the colour picker.


Colour model dependent data
---------------------------

All colour model dependent data uses fixed point 32 bit numbers, with 16 bits 
below the point, and 16 bits above the point. Offsets given below are
relative to the  start of the colour model dependent data.

RGB (model number 0)

The extra data is:

Offset  Data

0       Red value
4       Green value
8       Blue value

All values should be in the range &00000000 - &00010000.

CMYK (model number 1)

The extra data is:

Offset  Data

0       Cyan value
4       Magenta value
8       Yellow value
12      Key (black) value

All values should be in the range &00000000 - &00010000.

HSV (model number 2)

The extra data is:

Offset  Data

0       Hue angle
4       Saturation percentage
8       Value percentage

The Hue should be in the range &00000000 - &0167FFFF. The Saturation and
Value  should be in the range &00000000 - &00010000.


Wimp events and the client
--------------------------

Wimp events directed to the colour picker are also sent to the client. They
can be  distinguished by the window handle in the event block.

These events have already been fully processed by the colour picker. They are
sent  to the client merely as a `hook' for unusual circumstances where
special action is  required. This won't normally be necessary, and the client
should ignore these  events, just as it should any events it does not
understand. For example, if it is told  of an unknown key by a Key_Pressed
event that has the colour picker's window  handle, it must not call
Wimp_ProcessKey, since the colour picker will already have  done so.


Service Calls
-------------

Service_ColourPickerLoaded (Service Call &93)

This service call is for internal use only; you must not use it in your code.


SWI calls
---------

ColourPicker_RegisterModel (SWI &47700)
---------------------------------------

This call is for internal use only; you must not use it in your own code.


ColourPicker_DeregisterModel (SWI &47701)
-----------------------------------------

This call is for internal use only; you must not use it in your own code.


ColourPicker_OpenDialogue (SWI &47702)
--------------------------------------

Creates and opens a colour picker dialogue for a client

On entry

R0 = flags:
        bits 0, 1 = dialogue type:
                0 = normal dialogue, 1 = menu dialogue
                2 = toolbox dialogue, 3 = submenu dialogue
        all other bits reserved (must be set to 0)
R1 = pointer to a colour picker block (see below)

On exit

R0 = dialogue handle
R1 = window handle

Interrupts

Interrupt status is undefined
Fast interrupts are enabled

Processor Mode

Processor is in SVC mode

Re-entrancy

SWI is not re-entrant

Use

This call creates and opens a colour picker dialogue for a client, so that a
user can  choose a colour. The flags in R0 set the type of dialogue, and
hence whether or not the dialogue is transient.

The colour picker block specifies the initial settings for the dialogue. This
block is also  used by other colour picker SWIs. Its format is as follows:

Offset  Meaning

0       flags:
        Bit     Meaning
        0       1=>dialogue has a None button
        1       1=>dialogue has the None button selected
        2-3     dialogue button type, defining when
                Message_ColourPickerColourChanged is issued for it:
                0=>never issued; 1=>issued on any change, except during
                drags, which give a message at drag end; 2=>issued on any
                change, including during drags
        4       1=>dialogue ignores Message_HelpRequest messages
4       pointer to the title to be used, or 0 for a default title
8       x coordinate of top left of the visible area of the dialogue
12      reserved (must be &80000000)
16      reserved (must be &7FFFFFFF)
20      y coordinate of top left of the visible area of the dialogue
24      reserved (must be 0)
28      reserved (must be 0)
32      colour descriptor

Bits 0 and 1 of the flags control whether a None button appears between the colour 
patch and the Cancel button, and whether it is initially selected.

If the dialogue ignores Message_HelpRequest messages directed to  it, the
client may send the Wimp message Message_HelpReply to  respond with its own
text, or it may pass the message to the SWI  ColourPicker_HelpReply
to force the colour picker to reply with its  own text. The client can hence
replace the colour picker's help text for some or all  parts of the dialogue.

The returned dialogue handle is used as an argument to the other ColourPicker 
SWIs, and also in the Wimp messages that the ColourPicker module sends to the 
application to provide feedback on the user's selection of a colour.

Related SWIs

ColourPicker_CloseDialogue

Related vectors

None



ColourPicker_CloseDialogue (SWI &47703)
---------------------------------------

Closes a colour picker dialogue which is in progress

On entry

R0 = flags: all bits reserved (must be set to 0)
R1 = dialogue handle

On exit

R0, R1 preserved

Interrupts

Interrupt status is undefined
Fast interrupts are enabled

Processor Mode

Processor is in SVC mode

Re-entrancy

SWI is not re-entrant

Use

This call closes a colour picker dialogue which is in progress. This may either be 
done by the client, or by the Wimp if the dialogue was set to be transient
when  created (see Transient dialogues).

It is normally called in response to Message_ColourPickerCloseDialogueRequest.

Related SWIs

ColourPicker_OpenDialogue

Related vectors

None


ColourPicker_UpdateDialogue (SWI &47704)
----------------------------------------

Updates some or all of the contents of a colour picker dialogue

On entry

R0 = flags:
        Bit     Part of dialogue to update when set
        0       whether the dialogue has a None button
        1       whether the dialogue has the None button selected
        2       the button type of the dialogue
        3       the visible area of the dialogue
        4       reserved (must be clear)
        5       the window title
        6       colour setting, from the colour descriptor's initial RGB triplet only
        7       the colour model and setting, from the colour descriptor's model
                dependent data only (including optional data)
        8       whether the dialogue ignores Message_HelpRequest events
        all other bits reserved (must be set to 0)
R1 = dialogue handle
R2 = pointer to a colour picker block

On exit

R0 - R2 preserved

Interrupts

Interrupt status is undefined
Fast interrupts are enabled

Processor Mode

Processor is in SVC mode

Re-entrancy

SWI is not re-entrant

Use

This call updates some or all of the contents of the colour picker dialogue
whose  handle is given. Only the parts of the box indicated by the flags word
are updated.

The new values are taken from the passed colour picker block; all other parts
of the  block are ignored. The block need only be large enough to hold the
highest offset  field required.

The None button may be added or removed, and its setting adjusted. The title, 
setting and colour model may also be adjusted independently of each other.

If you are changing the visible area (ie bit 3 is set), you must fill in
offsets 8-20  inclusive of the colour picker block, including the reserved
words.  This is for future compatibility.

If bit 7 is set then bit 6 is ignored; the colour model is updated, and the
RGB triplet  is calculated from the data in the colour model block. If bit 6
is set and bit 7 is clear,  then the colour setting is updated from the
colour descriptor's initial RGB triplet  and the colour model left unchanged,
even if the current colour model isn't that in  the colour descriptor.

Related SWIs

ColourPicker_OpenDialogue

Related vectors

None


ColourPicker_ReadDialogue (SWI &47705)
--------------------------------------

Reads the current state of a colour picker dialogue without changing it

On entry

R0 = flags: all bits reserved (must be set to 0)
R1 = dialogue handle
R2 = pointer to a buffer to hold a colour picker block,
        or 0 to read required size

On exit

R0 preserved
R1 = required size of buffer (if 0 on entry); else preserved

Interrupts

Interrupt status is undefined
Fast interrupts are enabled

Processor Mode

Processor is in SVC mode

Re-entrancy

SWI is not re-entrant

Use

This call reads the current state of a colour picker dialogue without
changing it. The  state is returned as a colour picker block in the given
buffer, which is assumed to be  large enough to hold it. Because the size of
the block may change when the colour  model changes, you should always call
this SWI twice: once to read the required  size, then again to read the state
of the colour picker dialogue.

Related SWIs

None

Related vectors

None


ColourPicker_SetColour (SWI &47706)
-----------------------------------

This call is reserved for future expansion; you must not use it in your own code.


ColourPicker_HelpReply (SWI &47707)

Makes the colour picker respond to a Message_HelpRequest with its own help
text

On entry

R0 = flags: all bits reserved (must be zero)
R1 = pointer to Message_HelpRequest message block, as returned
        from Wimp_Poll

On exit

R0, R1 preserved

Interrupts

Interrupt status is undefined
Fast interrupts are enabled

Processor Mode

Processor is in SVC mode

Re-entrancy

Not defined

Use

This call makes the colour picker respond to a Message_HelpRequest with its
own  help text. It is typically used by a client that wishes to replace part
of the colour  picker's help system.

Such a client would, on creating and opening a colour picker dialogue, force it to 
ignore help requests. The client would then selectively respond to  help
requests itself, or use this call to make the colour picker respond instead.

Related SWIs

ColourPicker_OpenDialogue

Related vectors

None


ColourPicker_ModelSWI (SWI &47708)
----------------------------------

This call is for internal use only; you must not use it in your own code.



Messages
--------

Colour picker messages
----------------------

These Wimp messages are generated by the Colour Picker in response to Wimp 
events on the colour picker dialogue. For more details about Wimp messages, see 
Wimp_SendMessage on page 3-196, and Messages on page 3-230.


Message_ColourPickerColourChoice (&47700)
-----------------------------------------

This message is issued to the client whenever the user makes a definite choice of 
colour, by clicking Select or Adjust on the OK button of the dialogue. The
format of  the message block is:

R1+20           dialogue handle
R1+24           flags:
                        bit 0 set => None chosen
R1+28-          colour descriptor chosen

The colour descriptor gives the state of the dialogue so that a sensible
default may  be given next time the dialogue is used. When flags bit 0 is
set, signifying that  None was chosen, the colour descriptor will still be
present.

The message may or may not be followed by a 
Message_ColourPickerCloseDialogueRequest.


Message_ColourPickerColourChanged (&47701)
------------------------------------------

This optional message is issued to the client when the colour displayed in the 
dialogue changes.

The format of the message block is:

R1+20           dialogue handle
R1+24           flags:
                        bit 0 set => None chosen
                        bit 1 set => drag in progress
R1+28-          colour descriptor chosen

The client specifies when this message is to be sent (if at all) using button type flags, 
passed to ColourPicker_OpenDialogue as it creates and opens the 
dialogue.


Message_ColourPickerCloseDialogueRequest (&47702)
-------------------------------------------------

This message is issued to the client when the user dismisses the dialogue by 
clicking Select on the OK or Cancel icons or by using the Close icon of a toolbox 
dialogue. The client should respond by calling ColourPicker_CloseDialogue
with the given handle. The format of the message block is:

R1+20           dialogue handle

This message is not issued for transient dialogues (see Transient dialogues);
the Wimp will instead automatically close the dialogue itself.


Message_ColourPickerOpenParentRequest (&47703)
----------------------------------------------

This message is issued when the user opens a toolbox dialogue's parent by
clicking  Adjust or Shift-Adjust on its Close icon. If the colour picker has
a parent dialogue  box, the client should ensure that window is open and
brought to the front. The  format of the message block is:

R1+20           dialogue handle

In the former case (ie Adjust), the message will be followed by a 
Message_ColourPickerCloseDialogueRequest.




*Commands
---------

*ModelList
----------

Lists all the loaded colour models

Syntax

*ModelList

Parameters

None

Use

*ModelList lists all the loaded colour models.

