PtColorSel

Superclass for color-selector widgets

Class hierarchy:

PtWidget → PtBasic → PtContainer → PtCompound → PtColorSel

Immediate subclasses:

• PtColorPanel
• PtColorPatch
• PtColorSelGroup
• PtColorWell

For more information, see the diagram of the widget hierarchy.

PhAB icon:

None — not normally instantiated.

Public header:

<photon/PtColorSel.h>

Description:

PtColorSel is a superclass for all color-selection widgets. It defines a common interface to widgets that let you select colors. To maintain consistency, any widget that implements color selection should be a descendant of PtColorSel.

New resources:

Pt_ARG_CS_COLOR

The currently selected color. See PgColor_t in the Photon Library Reference.

Pt_ARG_CS_COLOR_MODELS

A list of color models that this color selector supports. When you set a color using a color model that the selector doesn't support, the actual color can still be calculated; ensuring that the color model is supported can reduce roundoff errors if the color doesn't cleanly map between RGB and the color model in question.

In addition, this resource is useful for widgets that let you choose from the different color models that the widget supports.

The following color models are defined:

Pg_CM_RGB

Red-green-blue.

Pg_CM_HSB

Hue-saturation-brightness.

Pg_CM_HLS

Hue-lightness-saturation. A modified HSB model that's more intuitive for selecting colors in a GUI.

Pg_CM_CMYK

Cyan-magenta-yellow-black.

Here's an example of how to set this resource:

PgColorModel_t const *models[]={Pg_CM_RGB, Pg_CM_CMYK,
                                Pg_CM_HSB};

PtSetResource( my_widget, Pt_ARG_CS_COLOR_MODELS,
               models, 3 );

Pt_ARG_CS_CURRENT_MODEL

An index to the currently active model into the array of color models that this widget supports. Indexes start at 0.

Pt_ARG_CS_FLAGS

Flags that control the widget's behavior:

Pt_CS_FAST_UPDATE

If the selector is undergoing a high-bandwidth change, do any rendering (if applicable) in a “fast” manner. This is a meta-flag that doesn't actually affect the behavior of PtColorSel itself, but may be observed by subclasses (PtColorPatch uses it to render the two-dimensional patch).

Pt_CS_QUANTIZE_COLOR

Ensure Pt_ARG_CS_COLOR is always mapped (quantized) to the nearest match in the palette if a palette is set. The PtColorSel widget always does this matching, so subclasses don't need to implement it.

Pt_ARG_CS_PALETTE

The color palette supported by this PtColorSel. A palette serves these main purposes:

• It supplies the needed palette information for a palette-oriented color selector.
• It imposes a discrete set of colors within a continuous range that this selector must conform to.

Pt_CB_CS_COLOR_CHANGED

A list of PtCallback_t structures that define the callbacks that are invoked when the selected color changes.

Each callback is passed a PtCallbackInfo_t structure that contains at least the following members:

reason

Pt_CB_CS_COLOR_CHANGED

reason_subtype

A combination of the following:

• Pt_CS_COLOR_CHANGED — a low-bandwidth change (e.g. click, set). If this bit isn't set, assume that a high-bandwidth change is in progress, and there might be many subsequent callbacks in a very short time.
• Pt_CS_COLOR_CHANGE_COMPLETE — a widget-specific inference that the selection is “complete.” For example, this bit is useful if the color selector appears in a popup pane that you wish to dismiss automatically when the change is complete.

event

A pointer to a PhEvent_t structure that describes the event that caused the callback to be invoked.

cbdata

A pointer to a PtColorSelCallback_t structure that contains at least these members:

• PgColor_t rgb — the selected color, in RGB format. See PgColor_t in the Photon Library Reference.
• PgColorChannel_t const *channels — the constituent channel values for the selected color. You should interpret these values based on the color_model.
• PgColorModel_t const *color_model — the color model, which you should to interpret the values stored in the channels. If this is NULL, the channels should be disregarded.

These callbacks should return Pt_CONTINUE.

Inherited resources:

If the widget modifies an inherited resource, the “Default override” column indicates the new value. This modification affects any subclasses of the widget.