<-- Back to AG_Intro.3

SYNOPSIS

#include <agar/core.h>
#include <agar/gui.h>

DESCRIPTION

The AG_HSVPal widget is a HSV (Hue, Saturation, Value) color editor which allows the user to edit a color's hue, saturation, value and alpha components. The widget can bind directly to different color representations:

Individual Hue / Saturation / Value / Alpha floats.
Individual R/G/B/A component integers or floats.
An AG_Color(3) structure.
A pixel element in packed-pixel format (e.g., an Uint32 and a corresponding AG_PixelFormat(3)).

INHERITANCE HIERARCHY

AG_Object(3)-> AG_Widget(3)-> AG_HSVPal.

INITIALIZATION

AG_HSVPal * AG_HSVPalNew (AG_Widget *parent, Uint flags)

The AG_HSVPalNew() function allocates, initializes, and attaches a new AG_HSVPal widget. Acceptable flags include:

AG_HSVPAL_NOALPHA	(Read-only) Transparency control is disabled. Set (or cleared) when `pixel-format` is bound to a pixel format with (or without) alpha.
AG_HSVPAL_FORCE_NOALPHA	Disable the transparency control.
AG_HSVPAL_NOPREVIEW	Disable the color preview band.
AG_HSVPAL_HFILL	Expand horizontally in parent (equivalent to invoking AG_ExpandHoriz(3)).
AG_HSVPAL_VFILL	Expand vertically in parent (equivalent to invoking AG_ExpandVert(3)).
AG_HSVPAL_EXPAND	Shorthand for AG_HSVPAL_HFILL\|AG_HSVPAL_VFILL.

UPDATING VALUES

void AG_HSVPalUpdateHue (AG_HSVPal *pal, int x, int y)

void AG_HSVPalUpdateSV (AG_HSVPal *pal, int x, int y)

AG_HSVPalUpdateHue() sets the hue to that closest to cursor coordinates x, y and triggers a refresh. AG_HSVPalUpdateSV() sets the saturation and value to that at cursor coordinates x, y and triggers a refresh.

BINDINGS

The AG_HSVPal widget provides the following bindings:

`float *hue`	Color hue (0..1).
`float *saturation`	Color saturation (0..1).
`float *value`	Color brightness (0..1).
`float *alpha`	Alpha component value (0..1).
`AG_PixelFormat **pixel-format`	Pointer to the AG_PixelFormat(3) to use for generating the `pixel` value. The AG_HSVPAL_NOALPHA flag will be set automatically depending on the presence of an alpha component in the newly bound format (use AG_HSVPAL_FORCE_NOALPHA to disable this test).
`Uint32 *pixel`	Resulting pixel value. The pixel's components are extracted immediately when this binding is made (using the current `pixel-format`) so make sure to always bind `pixel-format` prior to `pixel`.
`void *RGBv`	A three-element array containing the RGB components. Acceptable binding types include FLOAT and DOUBLE, INT and UINT8. For floating point types, the values are scaled to 0.0-1.0. For integral types, the values are scaled to 0-255.
`void *RGBAv`	Same as above, except that the array has 4 elements where the last element is the alpha component.

EVENTS

The AG_HSVPal widget generates the following events:

h-changed (void)	The hue has changed.
sv-changed (void)	The saturation or the value has changed.

TROUBLETONS

The conversion between integer RGB and HSV triplets is not reversible without loss of precision. In cases where it is desirable to maintain the same hue throughout changes in saturation, the color should be stored in HSV format.

HISTORY

The AG_HSVPal widget first appeared in Agar 1.0.