NAME

AG_HSVPal —

agar HSV color wheel widget

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: Disable the alpha component editor. This flag is automatically set or cleared whenever pixel-format is bound to a pixel format with or without alpha channel.
AG_HSVPAL_FORCE_NOALPHA: Disable the alpha component editor, regardless of whether the pixel format includes alpha support.
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.

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.