TABLE OF CONTENTS

palette.gadget/--datasheet--
palette.gadget/PALETTE_GetClass
palette.gadget/--datasheet--                     palette.gadget/--datasheet--

     NAME
	palette.gadget -- A colour selection gadget.

     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.

    PALETTE STYLE
	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_ColorTable.

     METHODS
	OM_NEW -- Create the gadget calls OM_SET. Passed to superclass.

	OM_SET -- Set object attributes. Passed to superclass first.

	OM_GET -- Get object attributes. Passed to superclass first.

	OM_NOTIFY -- Notify connections of attribute changes.

	OM_DISPOSE -- Frees resources and calls superclass.

	OM_UPDATE -- Calls OM_SET.

	GM_DOMAIN -- Return the maximum, nominal and minimum size of
	             the gadget.

	GM_RENDER -- Renders the gadget imagery.

	GM_GOACTIVE -- Activate the gadget.

	GM_HANDLEINPUT -- Handles input events once active.

	GM_GOINACTIVE -- Deactivates the gadget. Passed to the superclass.

	GM_EXTENT -- Reports gadget rendering extent.

	GM_CLIPRECT -- Installs ClipRect for virtual group support.

	GM_KEYGOACTIVE -- Handle keyboard activation. (V53.2)

	GM_KEYGOINACTIVE -- Handle keyboard deactivation. (V53.2)

	All other methods are passed to the superclass.

     ATTRIBUTES
	GA_ID (uint16)
	    Unique ID number for the gadget.

	    Defaults to 0.

	    Applicability is (OM_NEW, OM_SET, OM_GET, OM_UPDATE, OM_NOTIFY)

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

	    Defaults to FALSE.

	    Applicability is (OM_NEW, OM_SET, OM_GET, OM_UPDATE)

	GA_HintInfo (CONST_STRPTR)
	    Specify the text to use as the hint info for this gadget.
	    You can change this attribute at any time, and it will over-
	    ride any text specified in the windows HintInfo array. See
	    window.class autodoc for more information.

	    Defaults to NULL.

	    Applicability is (OM_NEW, OM_SET).

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

	    Defaults to 0.

	    Applicability is (OM_NEW, OM_SET, OM_GET, OM_UPDATE, OM_NOTIFY)

	PALETTE_ColorOffset (uint16)
	    First colour to use in screen palette.

	    Defaults to 0.

	    Applicability is (OM_NEW, OM_SET, OM_GET, OM_UPDATE)

	PALETTE_ColorTable (uint16 *)
	    Pointer to a table of pen numbers indicating which colours
	    should be used and edited by the palette gadget. This array
	    must contain as many entries as there are colours displayed in
	    the palette gadget PLUS the colour offset.  The array provided
	    with this tag must remain valid for the life of the gadget or
	    until a new table is provided.

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

	    Applicability is (OM_NEW, OM_SET, OM_GET, OM_UPDATE)

	PALETTE_NumColors (uint16)
	    Number of colours 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, OM_UPDATE)

	PALETTE_RenderHook (struct Hook *)
	    A custom render hook for the palette color boxes.
	    Your hook function will be called as follows:

	      uint32 Render(struct Hook *hook, APTR obj,
	                    struct PBoxDrawMsg *msg);

	    The obj argument is unused and currently set to NULL.

	    The message structure is as follows:

	      struct PBoxDrawMsg
	      {
	        uint32           pbdm_MethodID;  // PB_DRAW
	        struct RastPort *pbdm_RastPort;  // Where to render
	        struct DrawInfo *pbdm_DrawInfo;  // Useful to have
	        struct Rectangle pbdm_Bounds;    // Rendering limits
	        uint32           pbdm_State;     // How to render
	        uint32           pbdm_Color;     // Color index in palette
	        struct Gadget   *pbdm_Gadget;    // palette.gadget
	      };

	    PBoxDrawMsg.pbdm_State will be PBR_NORMAL, PBR_SELECTED,
	    PBR_NORMALDISABLED or PBR_SELECTEDDISABLED.

	    The hook must return PBCB_OK if rendering was successful or
	    PBCB_UNKNOWN if it doesn't understand the pbdm_MethodID.
	    Always check the pbdm_MethodID to support future expansions.

	    Defaults to NULL (colour boxes rendered by the gadget).

	    Applicability is (OM_NEW, OM_SET, OM_GET, OM_UPDATE)

palette.gadget/PALETTE_GetClass               palette.gadget/PALETTE_GetClass

    NAME
	PALETTE_GetClass -- Gets pointer to the palette class.

    SYNOPSIS
	Class * class = PALETTE_GetClass();

    FUNCTION
	This function is deprecated as of V52.
	Use the "palette.gadget" public class ID instead.

    RESULT
	class - Pointer to the palette class.