A colour object represents a 32-bit RGBA colour value (8
bits each for red, green, blue and alpha). Colours are typically
attached to
graphical objects:
?- send(new(P, picture), open), send(P, display, new(B, box(100, 100))), send(B, colour, red), send(B, fill, blue).
Like fonts and cursors, colour
objects are reusable — they can be attached to multiple graphicals.
xpce will not create the same colour twice; instead it returns the
existing colour object
from the
@colours table
(see colour<-lookup).
Application code normally just names a colour and lets the type-checker
convert.
xpce ships with the classic SVG/CSS named-colour set (red, blue,
dark_green, …) in the hash table @colour_names;
any name not in that table is looked up via the OS colour database.
Colours may also be specified in CSS hex notation (#RGB, #RGBA, #RRGGBB,
#RRGGBBAA) or constructed from RGB or HSV triples — see
colour->initialise.
@colour_names
also holds the system colours, whose names start with sys_,
such as sys_window_background. They reflect the colours of
the desktop, e.g., the light or dark
appearance and the accent colour, and are reloaded by display_manager ->system_colours_changed
if the desktop settings change. Colour
objects of these names change their value in place. The xpce user
interface and the development tools use theme colours, class
theme_colour, whose value follows the selected theme. See
the sections System colours and Themes of the XPCE User
Guide.
<-hilite.<-hilite
if the colour is dark, i.e., its
colour<-intensity
is below 128. Moving a dark colour most of the way to white makes it
unrecognisable, e.g., the preview of a menu
item on a dark background would be almost white.<-reduce.<-fade.
|int#RRGGBB / #RRGGBBAA)
or, for anonymous colours, the encoded integer value.named when the colour was constructed by name (so
resolution happens lazily through the colour database); rgb
when the caller supplied numeric components directly; theme
for a
theme_colour.<-red, colour<-green,
colour<-blue
and colour<-alpha
getters to extract components.
Named colours improve readability — @colour_names
maps well-known names (the SVG/CSS palette) to RGB triples. Names in the
form #RGB, #RGBA, #RRGGBB or #RRGGBBAA
are interpreted as CSS hex literals.
When name is @default,
the colour is built from the numeric components. The default model is rgb
and each component is an integer 0..255. The first component is
therefore named
red but actually carries the hue (0..360) when
model=hsv.
Examples:
new(C1, colour(red)) %% named new(C2, colour(@default, 255, 0, 0)) %% RGB triple new(C3, colour(@default, 180, 50, 50, 255, hsv)) %% HSV
See colour<-hue/colour<-saturation/colour<-value
for the HSV model.
colour(@default, ...) literals can yield distinct objects
with identical components.
<-kind
colour against the colour database on first access.
<-hue
selects the basic colour (think of it as a position on the rainbow);
<-saturation
is how intense the colour is — 0 is grey, 100 is fully saturated;
<-value
is brightness — 0 is black, 100 is white. HSV is more convenient than
RGB for shading and palette arithmetic. Colours may be created in this
space via
colour->initialise
with model=hsv. Reasoning in colour spaces is beyond the
scope of this manual.
(20*R + 32*G + 18*B) / 70
which closely matches ITU‑R BT.601 luma.
Useful for converting colour to a monochrome substitute.
|int -> int.0..1.0] ->
colour.0..1.0] ->
colour Return a lighter (colour<-hilite)
or darker (colour<-reduce)
variant. Used by class elevation to derive the lit and
shadow sides of a 3-D box. 0.0 returns the
colour unchanged; 1.0 returns white (colour<-hilite)
or black (colour<-reduce).
Defaults come from the hilite_factor / reduce_factor
class variables. A dark colour uses dark_hilite_factor
rather than hilite_factor.
The derived colour is associated with the original; asking for the same modification again returns the cached object, and destroying the original lets the derivative go.
.0..1.0] ->
colour Return a colour with the same RGB but alpha multiplied by
factor. 0.0 yields a fully
transparent variant; 1.0 leaves alpha
unchanged. The default factor comes from the
fade_factor class variable
(0.5).
Complements graphical->opacity: setting
the fill or pen to a faded colour lets a single graphical carry both an
alpha component and its shape/stroke identity, without a global
graphical opacity slot. Like colour<-hilite
and colour<-reduce,
the result is cached against the source colour via @colours.
.0..1.0] ->
colour Return the colour that is factor of the way from
this colour towards with. 0.0
returns this colour and 1.0 returns with.
The default factor is 0.5. Mixing a
background a little towards the text colour derives a colour that stands
out on light and dark backgrounds alike. Like colour<-hilite,
the result is associated with the source colour.
# and has 3, 4, 6 or 8 hex
digits after it, interpret it as a CSS hex literal:
#c0453f -> R=192, G=69, B=63, A=255
With three or four hex digits, each digit is doubled (#abc
≡ #aabbcc). With four or eight digits the trailing byte
is the alpha channel.
|int],
red=[0..360], green=[0..255], blue=[0..255], alpha=[0..255], model=[{rgb,hsv}] -> colour->initialise.
A lookup from RGB values never returns a theme colour, as its value
changes with the theme.<-kind
or theme, return its colour<-name.
Otherwise return #RRGGBB (or #RRGGBBAA when
alpha is not 255). The result is suitable as input to colour<-convert.
See also object<-storage_reference, object->save_in_file
and source_sink<-object.