|
www.riscos.com Technical Support: |
The colour selection window can be described as follows:
A Colour Dialogue object has the following attributes which are specified in its object template and can be manipulated at run-time by the client application:
| Attributes | Description | |
|---|---|---|
| flags | Bit | Meaning |
| 0 | when set, this bit indicates that a ColourDbox_AboutTobeShown event should be raised when SWI Toolbox_ShowObject is called for this object. | |
| 1 | when set, this bit indicates that a ColourDbox_DialogueCompleted event should be raised when the Colour Dialogue object has been removed from the screen. | |
| 2 | when set, include a None button in the dialogue box | |
| 3 | when set, select the None button when the dialogue box is created | |
| title | this gives an alternative string to use instead of the string 'Colour Choice' in the title bar of the dialogue box (0 means use default) | |
| max title length | this gives the maximum length in bytes of title text which will be used for this object | |
| colour | an RGB value for the initial colour value | |
Note that it is possible to set and read whether a Colour Dialogue has a None entry at run-time using the following methods:
ColourDbox_SetNoneAvailable
ColourDbox_GetNoneAvailable
A Colour Dialogue object is created using SWI Toolbox_CreateObject.
When this object is created it has no attached objects (see Attached objects).
A Colour Dialogue object is deleted using SWI Toolbox_DeleteObject.
The setting of the non-recursive delete bit does not have a meaning for Colour Dialogue objects.
When a Colour Dialogue object is displayed on the screen using SWI Toolbox_ShowObject it has the following behaviour:
| Show type | Position | |
|---|---|---|
| 0 (default) | the underlying window is shown at the last place shown on the screen, or the coordinates given in its template, if it has not already been shown | |
| 2 (topleft) | R3 + 0 | visible area minimum x coordinate |
| R3 + 4 | visible area minimum y coordinate | |
For most applications it will not be necessary to make these calls explicitly, but instead to mark the templates with their auto-create bit set, so that a Colour Dialogue object is created on start-up.
When the client calls Toolbox_ShowObject, a ColourDbox_AboutToBeShown Toolbox event is raised (if the appropriate flags bit is set), allowing the client to take any last minute action. Typically, a client will indicate which of the colours should be shown as the currently selected one, when it receives this event.
It is possible for the colour which is currently selected in the dialogue box to be set by the client application. This is independent of the colour model being used, since the colour is specified as an RGB colour value. The client passes a 'colour block' to the Colour Dialogue module which has a one-word RGB value as its first word; the remainder of the block is intended to support any future colour models other than RGB, CMYK and HSV. It has a size field followed by colour-model-specific data. For clients not requiring this extensibility, the size field should be set to 0. The method for setting the colour thus used in a Colour Dialogue is ColourDbox_SetColour.
The current colour (and colour model data) can be read using the ColourDbox_GetColour method (described on ColourDbox_GetColour 3).
The colour model used in a Colour Dialogue is normally chosen by the user by clicking on the appropriate radio button. The client can however set this at run-time using the ColourDbox_SetColourModel method, passing a colour number (RGB=0, CMYK=1, HSV=2). If any other colour model is required, then further colour-model-specific data must also be passed to this method (none are currently supported).
The current colour model used can be read using the ColourDbox_GetColourModel method.
When the user has found the correct colour he wants, he will click the OK button in the Colour Dialogue box. The Colour Dialogue module delivers a ColourDbox_ColourSelected Toolbox event to the client at this point giving the RGB value of the colour chosen.
When the Colour Dialogue module has hidden its dialogue box at the end of a dialogue, it delivers a ColourDbox_DialogueCompleted Toolbox event to the client, with an indication of whether a colour selection occurred during the dialogue.
The following methods are all invoked by calling SWI Toolbox_MiscOp with:
| R0 | holding a flags word |
| R1 | being a Colour Dialogue id |
| R2 | being the method code which distinguishes this method |
| R3-R9 | potentially holding method-specific data |
| R0 | = | flags |
| R1 | = | Colour Dbox object id |
| R2 | = | 0 |
| R0 | = | Wimp window handle of underlying window |
This method returns the Wimp window handle of the window used by the underlying Colour Picker module to implement the Colour dialogue. The value returned is only valid when the Colour dialogue box is showing.
extern _kernel_oserror *colourdbox_get_wimp_handle ( unsigned int flags,
ObjectId colourdbox,
int *wimp_handle
);
| R0 | = | flags |
| R1 | = | Colour Dbox object id |
| R2 | = | 1 |
| R0 | = | ColourPicker dialogue handle of underlying dialogue box |
This method returns the handle of the dialogue box used by the underlying Colour Picker module to reference the Colour dialogue. The value returned is only valid when the Colour dialogue box is showing.
extern _kernel_oserror *colourdbox_get_dialogue_handle ( unsigned int flags,
ObjectId colourdbox,
int *dialogue_handle
);
| R0 | = | flags bit 0 set  select the None option
|
| R1 | = | Colour Dbox object id |
| R2 | = | 2 |
| R3 | = | pointer to colour block |
| R1-R9 preserved |
This method sets the colour currently displayed in the Colour Dialogue (adjusting the colour slice shown, the sliders, and the writable fields appropriately).
The colour block is 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 may be 0) |
| + 8 | colour model number |
| + 12... | other model-dependent data |
Currently there are no extra colour models supported, so the size field at byte offset 4 should be set to 0.
If bit 0 of the flags word is set (select the None option) then R3 may be 0.
extern _kernel_oserror *colourdbox_set_colour ( unsigned int flags,
ObjectId colourdbox,
int *colour_block
);
| R0 | = | flags |
| R1 | = | Colour Dbox object id |
| R2 | = | 3 |
| R3 | = | pointer to buffer for colour block |
| R4 | = | size of buffer |
| if bit 0 of R0 is set None is selected
| ||
| R4 | = | size of buffer required (if R3 was 0) (currently fixed because no extra colour models are supported) else buffer pointed at by R3 contains colour information R4 holds number of bytes written to buffer. |
This method returns the colour currently displayed in the Colour Dialogue.
The colour block is 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 may be 0) |
| + 8 | colour model number |
| + 12... | other model-dependent data |
extern _kernel_oserror *colourdbox_get_colour ( unsigned int flags,
ObjectId colourdbox,
int *buffer,
int buff_size,
int *nbytes
);
| R0 | = | flags |
| R1 | = | Colour Dbox object id |
| R2 | = | 4 |
| R3 | = | pointer to colour model block |
| R1-R9 preserved |
This method sets the colour model currently used in the Colour Dialogue. The colour which is being displayed will now be shown using the new colour model, and the layout of the dialogue box will change accordingly.
The colour model block is defined as follows:
| + 0 | size of the remainder of this block (currently only 4) |
| + 4 | colour model number |
| + 8... | other model-dependent data |
The current valid colour model numbers are:
| 0 | RGB |
| 1 | CMYK |
| 2 | HSV |
Currently there are no extra colour models supported, so the size field at byte offset 0 should be set to 4 (i.e. just a colour model number).
extern _kernel_oserror *colourdbox_set_colour_model ( unsigned int flags,
ObjectId colourdbox,
int *colour_model_block
);
| R0 | = | flags |
| R1 | = | Colour Dbox object id |
| R2 | = | 5 |
| R3 | = | ointer to buffer for colour block |
| R4 | = | size of buffer |
| R4 | = | size of buffer required (if R3 was 0) (currently fixed because no extra colour models are supported) else buffer pointed at by R3 contains colour information R4 holds number of bytes written to buffer |
This method returns the number of the colour model currently used in the Colour Dialogue.
The colour model block is defined as follows:
| + 0 | size of the remainder of this block |
| + 4 | colour model number (currently: 0 = RGB, 1 = CMYK and 2 = HSV) |
| + 8... | other model-dependent data |
extern _kernel_oserror *colourdbox_get_colour_model ( unsigned int flags,
ObjectId colourdbox,
int *buffer,
int buff_size,
int *nbytes
);
| R0 | = | flags |
| R1 | = | Colour Dbox object id |
| R2 | = | 6 |
| R3 | = | non-zero means None is available |
| R1-R9 preserved |
This method sets whether a None option appears in the Colour Dialogue.
extern _kernel_oserror *colourdbox_set_none_available ( unsigned int flags,
ObjectId colourdbox,
int none
);
| R0 | = | flags |
| R1 | = | Colour Dbox object id |
| R2 | = | 7 |
| if bit 0 of R0 is set, then None is available |
This method returns whether the None option appears in a Colour Dialogue.
extern _kernel_oserror *colourdbox_get_none_available ( unsigned int flags,
ObjectId colourdbox,
int *out_flags
);
There are a number of Toolbox events which are generated by the Colour Dialogue module:
| + 8 | 0x829C0 |
| + 12 | flags (as passed in to Toolbox_ShowObject) |
| + 16 | value which will be passed in R2 to ToolBox_ShowObject |
| + 20... | block which will be passed in R3 to ToolBox_ShowObject for the underlying dialogue box. |
This Toolbox event is raised when SWI Toolbox_ShowObject has been called for a Colour Dialogue object. It gives the application the opportunity to set fields in the dialogue box before it actually appears on the screen.
typedef struct
{
ToolboxEventHeader hdr;
int show_type;
union
{
TopLeft pos;
WindowShowObjectBlock full;
} info;
} ColourDboxAboutToBeShownEvent;
| + 8 | 0x829C1 |
| + 12 | flags bit 0 set means that a colour selection was done during this dialogue |
This Toolbox event is raised after the Colour Dialogue object has been hidden, either by a Cancel click, or after an OK click, or by the user pressing Escape. It allows the client to tidy up its own state associated with this dialogue.
typedef struct
{
ToolboxEventHeader hdr;
} ColourDboxDialogueCompletedEvent;
| + 8 | 0x829C2 |
| + 12 | flags bit 0 set means None was chosen |
| + 16 | colour block chosen |
This Toolbox event is raised when the user clicks OK in the dialogue box. The colour block has the same format shown in the ColourDbox_SetColour method.
Note that event if the None button is set, a colour value is still returned, reflecting the current state of the dialogue box.
typedef struct
{
ToolboxEventHeader hdr;
unsigned int colour_block[(212/4)];
} ColourDboxColourSelectedEvent;
The layout of a Colour Dialogue template is shown below. Fields which have types MsgReference and StringReference are those which will require relocation when they are loaded from a resource file. If the template is being constructed in memory, then these fields should be real pointers (i.e. they do not require relocation).
For more details on relocation, see Resource File Formats.
| Field | Size in bytes | Type |
|---|---|---|
| flags | 4 | word |
| title | 4 | MsgReference |
| max_title | 4 | word |
| colour | 4 | word |