|
www.riscos.com Technical Support: |
The new hardware supported by 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.
Unless stated otherwise, all the facilities described in this chapter are available from RISC OS 3.5 onwards.
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. It is defined on Colour descriptors.
The colour picker works as follows:
From the client's point of view, a typical colour selection looks like this:
The full range of SWIs that clients may use are as follows:
The messages that the client may receive are:
This message is not issued by RISC OS 3.5.
When the client calls ColourPicker_OpenDialogue to create and open the colour picker dialogue, it can choose between different types of dialogue:
Because the closing of menu and submenu dialogues is handled by the Wimp rather than the colour picker, they are classed as transient dialogues.
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 | red value (0 - &FF) |
| 2 | green value (0 - &FF) |
| 3 | blue value (0 - &FF) |
| 4 | a word giving the size of the optional extension to the block, in bytes |
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.
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.
The extra data is:
| Offset | Data |
|---|---|
| 0 | Red value |
| 4 | Green value |
| 8 | Blue value |
All values should be in the range &00000000 - &00010000.
The extra data is:
| Offset | Data |
|---|---|
| 0 | Cyan value |
| 4 | Magenta value |
| 8 | Yellow value |
| 2 | Key (black) value |
All values should be in the range &00000000 - &00010000.
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 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 a request for help by a User_Message event (of type Message_HelpRequest) that has the colour picker's window handle, it should not supply help, since the colour picker will already have done so.
This service call is for internal use only; you must not use it in your code.
This call is for internal use only; you must not use it in your own code.
This call is for internal use only; you must not use it in your own code.
R0 = flags:
normal dialogue, menu dialogue toolbox dialogue submenu dialogue
R0 = dialogue handle
R1 = window handle
Interrupt status is undefined
Fast interrupts are enabled
Processor is in SVC mode
SWI is not re-entrant
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 (see Dialogue types), 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
| |
| 5 | 1 dialogue does not pass on unhandled key presses to the Wimp (RISC OS 3.6 onwards)
| |
| 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 (see Colour descriptors) | |
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.
If bit 4 is set, it is up to the calling application - rather than the dialogue - to pass on unhandled key presses to the Wimp. This bit is ignored under RISC OS 3.5.
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.
R0 = flags: all bits reserved (must be set to 0)
R1 = dialogue handle
R0, R1 preserved
Interrupt status is undefined
Fast interrupts are enabled
Processor is in SVC mode
SWI is not re-entrant
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.
None
Updates some or all of the contents of a colour picker dialogue
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 (RISC OS 3.6 onwards) |
| 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 |
| 9 | whether the dialogue passes on unhandled key presses to the Wimp (RISC OS 3.6 onwards) all other bits reserved (must be set to 0) |
R0 - R2 preserved
Interrupt status is undefined
Fast interrupts are enabled
Processor is in SVC mode
SWI is not re-entrant
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 (see 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.
Reads the current state of a colour picker dialogue without changing it
R0 = flags: all bits reserved (must be set to 0)
R1 = dialogue handle
R2 = pointer to a buffer to hold a colour picker block (see The colour picker block), or 0 to read required size
R0 preserved
R1 = window handle
R2 = required size of buffer (if 0 on entry); else preserved
Interrupt status is undefined
Fast interrupts are enabled
Processor is in SVC mode
SWI is not re-entrant
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.
None
None
This call is reserved for future expansion; you must not use it in your own code.
Makes the colour picker respond to a Message_HelpRequest with its own help text
R0 = flags: all bits reserved (must be zero)
R1 = pointer to Message_HelpRequest message block, as returned from Wimp_Poll
R0, R1 preserved
Interrupt status is undefined
Fast interrupts are enabled
Processor is in SVC mode
Not defined
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 (see ColourPicker_OpenDialogue). The client would then selectively respond to help requests itself, or use this call to make the colour picker respond instead.
None
This call is for internal use only; you must not use it in your own code.
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 and Messages.
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 (see Colour descriptors) |
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.
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 (see Colour descriptors) |
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.
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 ColourPicker will instead automatically close the dialogue itself.
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.
This message is issued to the client whenever the user clicks Adjust on the Cancel button of the dialogue. The format of the message block is:
| R1 + 20 | dialogue handle |
The client should respond by calling ColourPicker_UpdateDialogue, to reset the dialogue so that it displays the colour currently in effect. This is the last colour selected by clicking Adjust on the dialogue's OK icon, or failing that, the colour the dialogue showed when first opened.
This message is not issued under RISC OS 3.5.
*ModelList
None
*ModelList lists all the loaded colour models.
*ModelList 0: RGB The "physicist's model:" the quantity of each primary colour (red, green, blue). 1: CMYK The "printer's model:" the quantity of each secondary colour (cyan, magenta, yellow), alongwith the key (black). 2: HSV The "artist's model:" hue (or "tint"), saturation (or "shade") and value (or "tone").
None