![[Contents]](../images/toc_d.gif)
![[Index]](../images/index_d.gif)
![[Help]](../images/help_d.gif)
![[Retrace]](../images/retrace_d.gif)
![[Browse <]](../images/prev.gif)
![[Browse >]](../images/next.gif)
NAME
colorwheel.gadget -- create standard HSB color wheel BOOPSI objects
(V39)
FUNCTION
The color wheel class provides the ability to create gadgets
enabling the user to control the hue and saturation components
of an HSB (Hue-Saturation-Brightness) color space. The companion
gradient slider class enables control of the brightness component of
the color space.
The color wheel can operate on screens of any depth, and adapts
its rendering to the number of colors available. The system's pen
sharing mechanism is used in order to maximize the number of colors
used by the wheel. A color wheel gadget is (normally) responsible
for choosing it's own color pens to draw in (using
graphics.library/ObtainBestPen()). However, the creator of the gadget
can "donate" some pens to the gadget, using the WHEEL_Donation
tag.
The reason that the color wheel picks its own colors is because
it has the ability to display several different layouts depending
on the number and variety of colors available. For example, when
opening on a screen of low depth or when opening on a screen where
all the pens have already been allocated exclusively, the gadget will
display a "monochrome" version of the color wheel, where instead of
colored segments, the letters "R" (for red), "G" (for green), "B"
(for blue), "Y" (for yellow), "C" (for cyan) and "M" (for magenta)
will be used as labels.
You can talk to the color wheel using HSB or RGB, even though the
color wheel only really deals with HSB in its user-interface. All
communications with applications are performed with full 32-bit
color component values.
TAGS
WHEEL_Hue (ULONG) -- Set and get the hue component of a color wheel.
This is effectively the angle around the wheel where the
desired color lies. If the wheel is currently displayed,
the position of the selection knob will be moved to reflect
the new hue.
A hue value of 0 is all red, and nothing but red. Increasing
the value moves the color towards all green at $55555555, full
blue at $AAAAAAAA, and back to red at $FFFFFFFF.
If you are setting or getting more than one color component at
a time, it is more efficient to use the WHEEL_HSB tag.
Default for this tag is 0. Applicability is (ISGNU).
(V39)
WHEEL_Saturation (ULONG) -- Set and get the saturation component of a
color wheel. This is effectively the distance from the center
of the wheel where the desired color lies. If the wheel is
currently displayed, the position of the selection knob will
be moved to reflect the new saturation.
A saturation value of 0 puts the knob at the center of the
wheel and always yields white. Increasing the value
progressively moves the knob farther away from the center.
until the value $FFFFFFFF is reached in which case the knob
is as far as it can go.
If you are setting or getting more than one color component at
a time, it is more efficient to use the WHEEL_HSB tag.
Default for this tag is $FFFFFFFF. Applicability is (ISGNU).
(V39)
WHEEL_Brightness (ULONG) -- Set and get the brightness component of a
color wheel. The color wheel does not itself have any means of
displaying or editing brightness, but it does maintain this
value internally. Used with WHEEL_GradientSlider, this tag lets
you control the value of a gradient slider object by passing
WHEEL_Brightness to a color wheel.
A brightness value of 0 means all black. Increasing the value
progressively brightens the current color, until the value
$FFFFFFFF is reached in which case the color is as bright as
it gets.
If you are setting or getting more than one color component at
a time, it is more efficient to use the WHEEL_HSB tag.
Default for this tag is $FFFFFFFF. Applicability is (ISGU).
(V39)
WHEEL_HSB (struct colorwheelhsb *) -- set and get the hue, saturation,
and brightness components of a color wheel. This is a buik
version of the separate WHEEL_Hue, WHEEL_Saturation, and
WHEEL_Brightness tags.
When setting this tag, initialize a colorwheelhsb structure,
and provide a pointer to it. When getting this tag, pass a
pointer to a colorwheelhsb structure, and the color wheel
object will fill it in with the current values.
Default for this tag is a hue of 0, a saturation of $FFFFFFFF,
and a brightness of $FFFFFFFF. Applicability is (ISGU).
(V39)
WHEEL_Red (ULONG) -- Set and get the red component of a color wheel.
If the wheel is currently displayed, the position of the
selection knob will be moved to reflect the new amount of red.
If you are setting or getting more than one color component at
a time, it is more efficient to use the WHEEL_RGB tag.
Default for this tag is $FFFFFFFF. Applicability is (ISGNU).
(V39)
WHEEL_Green (ULONG) -- Set and get the green component of a color
wheel. If the wheel is currently displayed, the position of
the selection knob will be moved to reflect the new amount of
green.
If you are setting or getting more than one color component at
a time, it is more efficient to use the WHEEL_RGB tag.
Default for this tag is 0. Applicability is (ISGNU).
(V39)
WHEEL_Blue (ULONG) -- Set and get the blue component of a color
wheel. If the wheel is currently displayed, the position of
the selection knob will be moved to reflect the new amount of
blue.
If you are setting or getting more than one color component at
a time, it is more efficient to use the WHEEL_RGB tag.
Default for this tag is 0. Applicability is (ISGNU).
(V39)
WHEEL_RGB (struct colorwheelrgb *) -- set and get the red, green,
and brightness components of a color wheel. This is a buik
version of the separate WHEEL_Red, WHEEL_Green, and
WHEEL_Blue tags.
When setting this tag, initialize a colorwheelrgb structure,
and provide a pointer to it. When getting this tag, pass a
pointer to a colorwheelrgb structure, and the color wheel
object will fill it in with the current values.
Default for this tag is a red of $FFFFFFFF, a green of 0, and
a blue of 0. Applicability is (ISGU).
(V39)
WHEEL_Screen (struct screen *) - indicate the screen the color
wheel is to open on. This is a required tag and must be
provided when the wheel is created via newobject().
Applicability is (I). (V39)
WHEEL_Abbrv (STRPTR) - When the color wheel is rendered on a display
which doesn't have enough colors to allow it to draw itself
in color, it automatically renders itself in monochrome
instead. In such a case, the various color segments are
identified by six letters G=Green, C=Cyan, B=Blue, M=Magenta,
R=Red, and Y=Yellow. You can provide a replacement set of six
letters. This is meant for localization of the wheel.
Default for this tag is "GCBMRY". Applicability is (I). (V39)
WHEEL_Donation (UWORD *) - Specifies an array of pens donated by
the application for use by the color wheel. The array can
contain any number of pens, and is terminated with a pen
value of ~0. The wheel will change the RGB values of these
pens to suit its needs, so be prepared for this. This means
the pens should likely be allocated using the PENF_EXCLUSIVE
option of the graphics.library/obtainpen() function.
Default for this tag is NULL. Applicability is (I). (V39)
WHEEL_BevelBox (BOOL) - Set to TRUE if you want a raised bevelled box
to be drawn around the wheel.
Default for this tag is FALSE. Applicability is (I). (V39)
WHEEL_MaxPens (ULONG) - Indicate the maximum number of shared color
pens the wheel should attempt to allocate. This tag is useful
if you wish to minimize the impact the wheel can have on your
screen's pens.
Default for this tag is 256. Applicability is (I). (V39)
WHEEL_GradientSlider (struct gadget *) - this tag lets you do simple
linking of a gradient slider object to a color wheel object.
You give this tag a pointer to a gradient slider object
obtained previously from newobject(). once this is done,
anytime the various tags that can affect the brightness
component of the current color is sent to the color wheel,
the color wheel automatically changes the value of the
attached gradient slider to match that new brightness value.
Reading the brightness value from the color wheel returns the
current value indicated by the gradient slider.
Using this tag effectively allows you to treat the color wheel
and gradient slider as a single gadget. Once things are set up,
all communications occur through the wheel object, and the
gradient slider can pretty much be ignored by the application.
Default for this tag is NULL. Applicability is (IS). (V39)
GA_ID (UWORD) - Specify the gadget ID of a color wheel object.
Applicability is (ISGNU). (V39)
WARNING
Once a color wheel has been created on a given screen, the wheel
object must be deleted using disposeobject() prior to closing the
screen. This is because the wheel object allocates pens on the
screen.
BUGS
Even though all communication with the color wheel is done using full
32-bit color components, color calculations are currently done using
16-bit math, which can cause certain rounding errors to appear.
Prior to V40, the WHEEL_Red, WHEEL_Green, and WHEEL_Blue tags
did not return the correct values when a gradient slider is linked
with the color wheel using the WHEEL_GradientSlider tag. The
workaround is to always use the WHEEL_RGB tag, and just extract the
values from there.