Home  /  Autodocs

palette.gadget

A colour selection gadget.

FUNCTIONS

PALETTE_GetClass

SUPERCLASS

gadgetclass

REQUIRES

bevel.image

DESCRIPTION

This gadget is equivalent to the GadTools PALETTE_KIND gadget, but implemented as a BOOPSI gadget class. It displays a palette of colours, allowing the user to select one.

Advantages that this class provides:

ATTRIBUTES

GA_Disabled (BOOL)
Set to TRUE to disable gadget, FALSE otherwise.

Defaults to FALSE.

Applicability is (OM_NEW, OM_SET, OM_GET)

PALETTE_Colour (UBYTE)
Initially selected color of the palette. This number is a pen number, and not the ordinal color number within the palette gadget itself. The exception is when PALETTE_ColourTable is used, in which case you will get an index into your table.

Defaults to 0.

Applicability is (OM_NEW, OM_SET, OM_GET)

PALETTE_ColourOffset (UBYTE)
First colour in screen palette to display.

Defaults to 0.

Applicability is (OM_NEW, OM_SET, OM_GET)

PALETTE_ColourTable (UWORD *)
Pointer to a table of pen numbers indicating which colors should be used and edited by the palette gadget. The array provided with this tag must remain valid for the life of the gadget or until a new table is provided.

This array must contain as many entries as there are colours displayed in the palette gadget PLUS the colour offset. The first PALETTE_ColourOffset entries in your table are skipped (ignored). Eg. If PALETTE_ColourOffset is 8, and PALETTE_NumColours is 4, you must provide an array of 12 UWORDs but only the last 4 will be used.

Note:
in earlier versions of this document, this attribute

has been incorrectly described as being of type UBYTE *; the correct type is (and has always been) UWORD *, as stated in the <gadgets/palette.h> header file.

Default is NULL, which causes a 1-to-1 mapping of pen numbers.

Applicability is (OM_NEW, OM_SET, OM_GET)

PALETTE_NumColours (UWORD)
Number of colors to display in the palette gadget. Currently this must be a power of 2.

Defaults to 2.

Applicability is (OM_NEW, OM_SET, OM_GET)

PALETTE_RenderHook (struct Hook *)
(V47) Custom rendering hook for palette boxes. This allows you to extend the palette gadget functionality by using it to show a "palette" of arbitrary items rather than just colours.

Your hook will be called with the following arguments:

hook
pointer to your own hook structure

object
currently NULL, reserved for future use

message
pointer to a PBoxDrawMsg structure

The rendering hook will have to fill the bounds provided in the PBoxDrawMsg structure if the received message is of type PB_DRAW (check the value of pbdm_MethodID to find out the message type) and return PBCB_OK. If the message type is not PB_DRAW, or another known type, the hook should immediately return PBCB_UNKNOWN without performing any processing.

See <gadgets/palette.h> for more information on the palette rendering hook and the PBoxDrawMsg message structure.

Defaults to NULL, which means no custom rendering hook is used.

Applicability is (OM_NEW, OM_SET, OM_GET)

NOTES

The usability of a palette gadget decreases as the number of colours it is displaying increases. If there is a possibility that your palette gadget may be displaying a large number of colours (say, greater than 16), you should provide a means to simplify the colour selection. One possibility would be to divide your colour palette into banks, and have users switch banks via a chooser gadget for example. Another possibility would be to attach a scroller gadget to allow the user to scroll through the available colours, displaying just a subset of them on screen at a time. You may also want to sort your colours in some logical manner and use PALETTE_ColourTable.