RISCOS.com

www.riscos.com Technical Support:
Toolbox

 


Colour Dialogue box class


A Colour Dialogue box object allows the user to specify a colour using a variety of colour models.

User interface

The colour selection window can be described as follows:

COLOURDBOX-2.PNG

  • At the top is a row of radio buttons - these select which colour model is being used.
  • In the middle is an area defined by the current colour model - details of this are described overleaf.
  • At the bottom of the window is the colour patch, an optional None button which controls transparency, and the window's action buttons.

Application Program Interface

Attributes

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

Manipulating a Colour Dialogue object
Creating and deleting a Colour Dialogue object

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.

Showing a Colour Dialogue object

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.

Before the dialogue box is shown

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.

Setting and reading the colour used in a Colour Dialogue box

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).

Setting and reading the colour model used in a Colour Dialogue

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.

Reacting to colour selections

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.

Completion of a Colour Dialogue

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.

Colour Dialogue methods

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
ColourDbox_GetWimpHandle 0
On entry
R0 = flags
R1 = Colour Dbox object id
R2 = 0
On exit
R0 = Wimp window handle of underlying window
Use

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.

C veneer

extern _kernel_oserror *colourdbox_get_wimp_handle ( unsigned int flags,
                                                     ObjectId colourdbox,
                                                     int *wimp_handle
                                                   );

ColourDbox_GetDialogueHandle 1
On entry
R0 = flags
R1 = Colour Dbox object id
R2 = 1
On exit
R0 = ColourPicker dialogue handle of underlying dialogue box
Usage

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.

C veneer

extern _kernel_oserror *colourdbox_get_dialogue_handle ( unsigned int flags,
                                                         ObjectId colourdbox,
                                                         int *dialogue_handle
                                                       );

ColourDbox_SetColour 2
On entry
R0 = flags
bit 0 set => select the None option
R1 = Colour Dbox object id
R2 = 2
R3 = pointer to colour block
On exit
R1-R9 preserved
Use

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.

C veneer

extern _kernel_oserror *colourdbox_set_colour ( unsigned int flags,
                                                ObjectId colourdbox,
                                                int *colour_block
                                              );

ColourDbox_GetColour 3
On entry
R0 = flags
R1 = Colour Dbox object id
R2 = 3
R3 = pointer to buffer for colour block
R4 = size of buffer
On exit
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.
Use

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
C veneer

extern _kernel_oserror *colourdbox_get_colour ( unsigned int flags,
                                                ObjectId colourdbox,
                                                int *buffer,
                                                int buff_size,
                                                int *nbytes
                                              );

ColourDbox_SetColourModel 4
On entry
R0 = flags
R1 = Colour Dbox object id
R2 = 4
R3 = pointer to colour model block
On exit
R1-R9 preserved
Use

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).

C veneer

extern _kernel_oserror *colourdbox_set_colour_model ( unsigned int flags,
                                                      ObjectId colourdbox,
                                                      int *colour_model_block
                                                    );

ColourDbox_GetColourModel 5
On entry
R0 = flags
R1 = Colour Dbox object id
R2 = 5
R3 = ointer to buffer for colour block
R4 = size of buffer
On exit
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
Use

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
C veneer

extern _kernel_oserror *colourdbox_get_colour_model ( unsigned int flags,
                                                      ObjectId colourdbox,
                                                      int *buffer,
                                                      int buff_size,
                                                      int *nbytes
                                                    );

ColourDbox_SetNoneAvailable 6
On entry
R0 = flags
R1 = Colour Dbox object id
R2 = 6
R3 = non-zero means None is available
On exit
R1-R9 preserved
Use

This method sets whether a None option appears in the Colour Dialogue.

C veneer

extern _kernel_oserror *colourdbox_set_none_available ( unsigned int flags,
                                                        ObjectId colourdbox,
                                                        int none
                                                      );

ColourDbox_GetNoneAvailable 7
On entry
R0 = flags
R1 = Colour Dbox object id
R2 = 7
On exit
if bit 0 of R0 is set, then None is available
Use

This method returns whether the None option appears in a Colour Dialogue.

C veneer

extern _kernel_oserror *colourdbox_get_none_available ( unsigned int flags,
                                                        ObjectId colourdbox,
                                                        int *out_flags
                                                      );

Colour Dialogue events

There are a number of Toolbox events which are generated by the Colour Dialogue module:

ColourDbox_AboutToBeShown (Event 0x829C0)
Block
+ 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.
Use

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.

C data type

typedef struct
{
  ToolboxEventHeader  hdr;
  int                 show_type;
  union
  {
    TopLeft               pos;
    WindowShowObjectBlock full;
  } info;
} ColourDboxAboutToBeShownEvent;

ColourDbox_DialogueCompleted (Event 0x829C1)
Block
+ 8 0x829C1
+ 12 flags
bit 0 set means that a colour selection was done during this dialogue
Use

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.

C data type

typedef struct
{
  ToolboxEventHeader hdr;
} ColourDboxDialogueCompletedEvent;

ColourDbox_ColourSelected (Event 0x829C2)
Block
+ 8 0x829C2
+ 12 flags bit 0 set means None was chosen
+ 16 colour block chosen
Use

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.

C data type

typedef struct
{
  ToolboxEventHeader hdr;
  unsigned int       colour_block[(212/4)];
} ColourDboxColourSelectedEvent;

Colour Dialogue templates

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

This edition Copyright © 3QD Developments Ltd 2015
Last Edit: Tue,03 Nov 2015