Smalltalk/X Webserver

Documentation of class 'Color':

Class: Color

Inheritance
Description
Class protocol
Instance protocol
Private classes

Inheritance:

   Object
   |
   +--Color
      |
      +--ColorValue
      |
      +--TranslucentColor

Package:: stx:libview

Category:: Graphics-Support

Version:: rev: 1.348 date: 2024/04/22 17:06:38; user: stefan; file: Color.st directory: libview; module: stx stc-classLibrary: libview

Description:

Color represents colors in a device independent manner.
The main info I keep in mySelf are the red, green and blue components,
scaled into 0 .. MaxValue (currently 16bit).

A device specific color can be acquired by sending a color the 'onDevice:aDevice' message,
which will return a color with the same r/g/b values as the receiver but with a specific
colorID for that device (which may or may not imply a colormap slot allocation on that device).
A device-specific color index (i.e. palette-ID) is then found in the newly allocated color's colorID slot.

Most of the device dependent coding was to support limited graphics devices (non truecolor, eg. palette)
in a transparent way. 
This was required at that time (late 80's, early 90's), but is now almost obsolete, 
as these days, virtually any graphic system supports true colors (8+8+8 bits).
It is arguably, if that stuff should remain here, or if we should simply give up support
for old VGA-like displays.

Note: 
    actually, there are still such limited displays around, 
    for example in the embedded area.
    So we will leave that support in for another few years ;-) ).

On such limited devices, colors can be pure or dithered, depending on the capabilities of the device.
For plain colors, the colorId-instvar is a handle (usually lookup-table entry) for that
device. For dithered colors, the colorId is nil and ditherForm specifies the form
used to dither that color. The ditherForm can be either a depth-1 bitmap or a pixmap
with the device's depth. 
The plain colors needed by the ditherForm are found in its colormap (as usual for bitmaps).

Problems with palette displays (eg. 8 bit palettes):

The default algorithm for color allocation is to ask the display for colors as
new colors are created. When running out of colors, dithered colors will be used,
using existing nearest colors and a dither pattern to approximate the color.
There could be situations, where no good colors are available for the dither, leading
to ugly looking dither colors.
This can be avoided by preallocating a set of colors over the complete range, which
makes certain that appropriate colors are later available for the dither process.
To do so, add a statement like: 'Color getColors5x5x5' to the startup.rc file.
(beside 5x5x5, there are various other size combinations available).
However, doing so may make things worse when displaying bitmap images, since this
preallocated table may steal colors from the image ...

[Instance variables:]

  red             <Integer>       the red component (0..MaxValue)
  green           <Integer>       the green component (0..MaxValue)
  blue            <Integer>       the blue component (0..MaxValue)

  device          <Device>        the device I am on, or nil
  colorId         <Object>        some device dependent identifier (or nil if dithered)
  ditherForm      <Form>          the Form to dither this color (if non-nil)
  writable        <Boolean>       true if this is for a writable color cell

[Class variables:]

  MaxValue        <Integer>       r/g/b components are scaled relative to this maximum

  Lobby           <Registry>      all colors in use - keeps track of already allocated
                                  colors for reuse and finalization.
                                  (don't use it: this will be moved to the device)

  Cells           <Registry>      keeps track of allocated writable color cells
                                  (don't use it: this will be moved to the device)

  FixColors       <Array>         preallocated colors for dithering on Display
  NumRedFix       <Integer>       number of distinct red values in FixColors
  NumGreenFix     <Integer>       number of distinct green values in FixColors
  NumBlueFix      <Integer>       number of distinct blue values in FixColors

  Black           <Color>         for fast return of black
  White           <Color>         for fast return of white
  Grey            <Color>         for fast return of grey
  LightGrey       <Color>         for fast return of lightGrey
  DarkGrey        <Color>         for fast return of darkGrey

  Pseudo0         <Color>         a color with 0 as handle (for forms and bitblit)
  Pseudo1         <Color>         a color with 1 as handle (for forms)
  PseudoAll       <Color>         a color with allPlanes as handle (for bitblit)

  Red             <Color>         red, needed for dithering
  Green           <Color>         green, for dithering
  Blue            <Color>         blue, for dithering

  DitherColors    <Collection>    some preallocated colors for dithering
                                  (kept, so they are available when needed)

  RetryAllocation <Boolean>       this flag controls how a request for a
                                  color should be handled which failed previously.
                                  I.e. a color is asked for, which was dithered
                                  the last time. Since it could happen, that in
                                  the meantime more colors became free, the request
                                  might succeed this time - however, your screen may
                                  look a bit funny, due to having both dithered and
                                  undithered versions around.
                                  The default is true, which means: do retry

compatibility issues:

    ST-80 seems to represent colors internally with scaled smallInteger
    components (this can be guessed from uses of
    scaledRed:scaledGreen:scaledBlue:). The main instance creation method is
    via 'ColorValue red:green:blue:', passing components in 0..1.
    In ST/X, rgb components are typically represented as percent.
    For more compatibility (when subclassing color), these internals may
    change in the near future. For migration, a compatibility subclass
    called ColorValue is provided.
    After the change, Color will be renamed to ColorValue and Color
    be made a subclass of ColorValue (offering the 0..100 interface for
    backward compatibility).

copyrightCOPYRIGHT (c) 1992 by Claus Gittinger
             All Rights Reserved

This software is furnished under a license and may be used
only in accordance with the terms of that license and with the
inclusion of the above copyright notice.   This software may not
be provided or otherwise made available to, or used by, any
other person.  No title to or ownership of the software is
hereby transferred.

Class protocol:

Compatibility-Squeak

colorPaletteForDepth: depth extent: chartExtent

Squeak mimicri:
Display a palette of colors sorted horizontally by hue and vertically by lightness. Useful for eyeballing the color gamut of the display, or for choosing a color interactively.

Usage example(s):

(Color colorPaletteForDepth: 16 extent: 190@60) display

fromRgbTriplet: aTriple

h: hue s: saturation v: brightness

Squeak mimicri:
Create a color with the given hue, saturation, and brightness.
Hue is given as the angle in degrees of the color on the color circle,
where red is zero degrees.
Saturation and brightness are numbers in [0.0..1.0],
where larger values are more saturated or brighter colors.
For example, (Color h: 0 s: 1 v: 1) is pure red.

indexedColors

Build an array of colors corresponding to the fixed colormap used
for display depths of 1, 2, 4, or 8 bits.

Usage example(s):

Color indexedColors

paleBlue

pixelScreenForDepth: depth

Return a 50% stipple containing alternating pixels of all-zeros
and all-ones to be used as a mask at the given depth.

** This is an obsolete interface - do not use it (it may vanish in future versions) **

r: redFraction g: greenFraction b: blueFraction

Squeak mimicri:
return a color from red, green and blue fractional values;
the arguments, r, g and b must be in (0..1)

r: r g: g b: b alpha: alphaValue

return a color from red, green and blue values;
the arguments, r, g, b and alpha must be in 0..1

Usage example(s):

     (Color r:1 g:0 b:0 alpha:0) inspect
     (Color r:0 g:1 b:0 alpha:0.5) inspect
     (Color r:0 g:0 b:1 alpha:1) inspect

r: r g: g b: b range: componentMax

return a color from red, green and blue values;
the arguments, r, g and b are interpreted as values (0..componentMax)

Usage example(s):

     (Color r:1023 g:0 b:0 range:1023) inspect
     (Color r:1023 g:1023 b:1023 range:1023) inspect
     (Color r:0 g:0 b:0 range:1023) inspect

showColors: colorList

Display the given collection of colors across the top of the Display.

wheel: thisMany

Return a collection of thisMany colors evenly spaced around the color wheel.

Usage example(s):

Color showColors: (Color wheel: 12)

wheel: thisMany saturation: s brightness: v

Return a collection of thisMany colors evenly spaced around the color wheel,
all of the given saturation and brightness.

Usage example(s):

Color showColors: (Color wheel: 12 saturation: 0.4 brightness: 1.0)

Usage example(s):

Color showColors: (Color wheel: 12 saturation: 0.8 brightness: 0.5)

Signal constants

colorAllocationFailSignal: return the signal raised when a color allocation failed.
colorErrorSignal: return the parent signal of all color error signals.
invalidColorNameSignal: return the signal raised when an invalid color name is encountered

accessing

allocatedColorsOn: aDevice

return a collection of colors which have already been allocated
on aDevice.

** This is an obsolete interface - do not use it (it may vanish in future versions) **

allocatedColorsOnDevice: aDevice

return a collection of colors which have already been allocated
on aDevice.

Usage example(s):

     Color allocatedColorsOnDevice:Display

color space conversions

withCMYKFromRed: rIn green: gIn blue: bIn do: aBlock

compute cmyk from hls, evaluate aBlock with c,m,y and k as arguments
and return the value from aBlock.
r,g,b in [0..100]; resulting cmyk in [0..1]
Notice, that this is different from cmy (see below)

Usage example(s):

     |clr|
     clr := Color red.
     Color withCMYKFromRed:(clr red) green:(clr green) blue:(clr blue) do:[:c :m :y :k |
        Transcript showCR:{ c . m . y . k }
     ]

Usage example(s):

     |clr|
     clr := Color grey.
     Color withCMYKFromRed:(clr red) green:(clr green) blue:(clr blue) do:[:c :m :y :k |
        Transcript showCR:{ c . m . y . k }
     ]

withHLSFromRed: r green: g blue: b do: aBlock

compute hls from rgb, evaluate aBlock with h,l and s as arguments.
and return the value from aBlock.
r,g,b in [0..100]
h in [0..360]; l in [0..100]; s in [0..100]

withHLSFromScaledRed: r scaledGreen: g scaledBlue: b do: aBlock

compute hls from rgb, evaluate aBlock with h,l and s as arguments;
Return the value from aBlock.

withHWBFromRed: r green: g blue: b do: aBlock

compute hwb from rgb, evaluate aBlock with h,w and b as arguments.
and return the value from aBlock.
r,g,b in [0..100];
h in [0..360]; w in [0..100]; b in [0..100]

Usage example(s):

    |clr|
    clr := Color white.
    Color withHWBFromRed:clr red green:clr green blue:clr blue do:[:h :w :b |
        Transcript showCR:{ h . w . b }
    ].

Usage example(s):

    |clr|
    clr := Color lime.
    Color withHWBFromRed:clr red green:clr green blue:clr blue do:[:h :w :b |
        Transcript showCR:{ h . w . b }
    ].

withRGBFromHue: h light: l saturation: s do: aBlock

compute rgb from hls, evaluate aBlock with r,g and b as arguments
and return the value from aBlock.
r,g,b in [0..100]
h in [0..360]; l in [0..100]; s in [0..100]

withRGBFromHue: hIn saturation: sIn value: vIn do: aBlock

compute rgb from hsv, evaluate aBlock with r,g and b as arguments
and return the value from aBlock.
r,g,b in [0..100]
h in [0..360]; v in [0..100]; s in [0..100]

withRGBFromRed: r yellow: y blue: b do: aBlock

compute RGB from RYB, evaluate aBlock with red,green and blue as arguments.
and return the value from aBlock.
r,g,b,y in [0..100]

Usage example(s):

     Color withRYBFromRed:100 green:0 blue:0 do:[:r :y :b | {r . y . b}] => #(100 0 0)
     Color withRYBFromRed:0 green:100 blue:0 do:[:r :y :b | {r . y . b}] => #(0 100 100)
     Color withRYBFromRed:100 green:100 blue:0 do:[:r :y :b | {r . y . b}] => #(0 100 0)

     Color withRGBFromRed:0 yellow:100 blue:0 do:[:r :g :b | {r . g . b}] => #(100 100 0)

withRYBFromRed: r green: g blue: b do: aBlock

compute RYB from rgb, evaluate aBlock with red,yellow and blue as arguments.
and return the value from aBlock.
r,g,b,y in [0..100]

Usage example(s):

     Color withRYBFromRed:100 green:0 blue:0 do:[:r :y :b | {r . y . b}] => #(100 0 0)
     Color withRYBFromRed:0 green:100 blue:0 do:[:r :y :b | {r . y . b}] => #(0 100 100)

constant colors

black

return the black color

Usage example(s):

     Color black inspect

blue

return the blue color

Usage example(s):

     Color blue inspect

brown

return the brown color.
See https://www.w3schools.com/colors/colors_names.asp

Usage example(s):

     Color brown
     Color name:'brown'

cyan

return the cyan color - ST-80 compatibility

Usage example(s):

     Color cyan inspect

cyan: cyan

return a cyanish color;
the argument cyan is interpreted as brightness in percent (0..100); 0 is black; 100 is cyan

Usage example(s):

     self cyan:100
     self cyan:50
     self cyan:0

darkGray

return the dark grey color (US version ;-)

Usage example(s):

     Color darkGray inspect

darkGreen

return a dark green color

Usage example(s):

     Color green
     Color darkGreen
     Color name:'darkGreen'

darkGrey

marked as obsolete by exept MBP at 20-09-2021

** This is an obsolete interface - do not use it (it may vanish in future versions) **

darkRed

return a dark green color

Usage example(s):

     Color darkRed

gray

return a medium grey color (US version ;-)

Usage example(s):

self grayPercent:50

Usage example(s):

     Color gray inspect

gray: grayPercent

return a gray color (US version).
The argument, gray is interpreted as percent (0..100).

Usage example(s):

     Color gray:25
     Color gray:50

grayByte: grayByte

return a grey color (US version).
The argument, grey is interpreted as byte-value (0..255).

Usage example(s):

     Color grayByte:127

grayPercent: gray

return a gray color (US version).
The argument, gray is interpreted as percent (0..100).

green

return green; notice: previously, this returned 00FF00, which is lime in w3c definition standard;
changed to return what others consider green.
See https://www.w3schools.com/colors/colors_names.asp

Usage example(s):

     Color green inspect
     Color lime inspect

greenCaringForColorBlindness

return the color to use for a darkened green (showing text in that color),
possibly using another color (ble) if the user's settings specifies color blindness

Usage example(s):

     self greenCaringForColorBlindness

grey

marked as obsolete by exept MBP at 20-09-2021

** This is an obsolete interface - do not use it (it may vanish in future versions) **

grey: greyPercent

marked as obsolete by exept MBP at 20-09-2021

** This is an obsolete interface - do not use it (it may vanish in future versions) **

greyByte: greyByte

marked as obsolete by exept MBP at 20-09-2021

** This is an obsolete interface - do not use it (it may vanish in future versions) **

lightBlue

return a light blue color

Usage example(s):

     Color lightBlue inspect

lightBrown

return the light brown color

Usage example(s):

     Color lightBrown
     Color name:'lightBrown'

lightGray

return the light grey color (US version ;-)

Usage example(s):

     Color lightGray inspect
     Color gray lightened inspect

lightGreen

return a light green color

Usage example(s):

     Color lightGreen inspect

lightGrey

marked as obsolete by exept MBP at 20-09-2021

** This is an obsolete interface - do not use it (it may vanish in future versions) **

lightRed

return a light red color

Usage example(s):

     Color lightRed inspect

lightYellow

return a light yellow color

lime

return the lime color (used to be called green previously).
See https://www.w3schools.com/colors/colors_names.asp

Usage example(s):

     Color green inspect
     Color lime inspect

magenta

return the magenta color - ST-80 compatibility

Usage example(s):

     Color magenta inspect

magenta: magenta

return a magentaish color;
the argument magenta is interpreted as brightness in percent (0..100); 0 is black; 100 is magenta

mediumGray

return medium-grey color (US version ;-)

Usage example(s):

     Color mediumGray inspect

mediumGrey

marked as obsolete by exept MBP at 20-09-2021

** This is an obsolete interface - do not use it (it may vanish in future versions) **

neonPink

return the neon pink color

orange

return the orange color - ST-80 compatibility

Usage example(s):

     Color orange inspect
     Color orange = (Color name:'orange')

orange: orange

return a orangeish color;
the argument orange is interpreted as brightness in percent (0..100); 0 is black; 100 is orange

Usage example(s):

     self orange:100
     self orange:50
     self orange:0

pink

return the pink color - ST-80 compatibility

Usage example(s):

     Color pink = (Color name:'pink')

red

return the red color

Usage example(s):

     Color red inspect

redCaringForColorBlindness

return the color to use for red,
possibly using another color if the user's settings specifies color blindness

salmon

return the salmon color

transparent

return the transparent-color

Usage example(s):

     self transparent

veryDarkGray

return a very dark-grey color (US version ;-)

veryDarkGreen

return a very dark green color

Usage example(s):

     Color veryDarkGreen

veryDarkGrey

marked as obsolete by exept MBP at 20-09-2021

** This is an obsolete interface - do not use it (it may vanish in future versions) **

veryLightGray

return a very light-grey color (US version ;-)

Usage example(s):

     Color veryLightGray inspect
     Color gray lightened lightened inspect

veryLightGrey

marked as obsolete by exept MBP at 20-09-2021

** This is an obsolete interface - do not use it (it may vanish in future versions) **

veryVeryLightGray

return a very very light-grey color (US version ;-)

white

return the white-color

Usage example(s):

     Color white inspect

yellow

return the yellow color - ST-80 compatibility

Usage example(s):

     Color yellow inspect

yellow: yellow

return a yellowish color;
the argument yellow is interpreted as brightness in percent (0..100); 0 is black; 100 is yellow

Usage example(s):

     self yellow:100
     self yellow:50
     self yellow:0

initialization

initialize

setup tracker of known colors and initialize classvars with
heavily used colors

Usage example(s):

self initializeStandardColorValues1.  "/ done when needed

Usage example(s):

self initializeStandardColorValues2.  "/ done when needed

Usage example(s):

     Color initialize

initializeStandardColorNames

marked as obsolete by exept MBP at 28-01-2022

** This is an obsolete interface - do not use it (it may vanish in future versions) **

initializeStandardColorValues

marked as obsolete by exept MBP at 28-01-2022

** This is an obsolete interface - do not use it (it may vanish in future versions) **

initializeStandardColorValues1

setup standard color names (X11-color names)

Usage example(s):

     self initializeW3CColorValues
     self initializeStandardColorValues1
     self initializeStandardColorValues2

initializeStandardColorValues2

setup less frequently used (but still somewhat standard) color names
(X11 and sgi color names)

Usage example(s):

     self initializeStandardColorValues2

initializeW3CColorValues

setup standard color names as defined in w3c

Usage example(s):

     self initializeW3CColorValues.
     self initializeStandardColorValues1
     self initializeStandardColorValues2

standardColorValues

marked as obsolete by exept MBP at 28-06-2022

** This is an obsolete interface - do not use it (it may vanish in future versions) **

standardColorValues1

return a dictionary mapping names to rgb values

Usage example(s):

     self standardColorValues1

standardColorValues2

return a dictionary mapping names to rgb values

Usage example(s):

     self standardColorValues2

update: something with: aParameter from: changedObject

handle image restarts and flush any device resource handles

instance creation

allColor

return a special color which, when used for bit-blitting will
behave like a all-1-color (i.e. have a device-pixel value of all-1s)

bgrValue: bgr

return a color from a 24bit BGR value (intentionally not RGB);
The value is composed of b<<16 + g<<8 + r.
(this byte-order is sometimes encountered with windows systems (progs)

blue: blue

return a color from blue value;
the argument green is interpreted as percent (0..100)

Usage example(s):

     (Color blue:50) inspect

brightness: brightness

create a gray color with given brightness (0..1).
ST-80 compatibility.

cmy: cmyVector

return a color from cyan, magenta, yellow values in a vector.
all values are given in percent (0..100).

Usage example(s):

     Color cmy:{ 100 . 0 . 0 }     - cyan
     Color cmy:{ 50 . 0 . 0  }     - cyan darkened
     Color cmy:(Color black cmyVector) 
     Color cmy:(Color orange darkened cmyVector)

cmyk: cmykVector

return a color from cyan, magenta, yellow and black values in a vector.
all values are given in percent (0..100).
The value returned here is questionable.
TODO: we loose information about one component here,
and should actually return an instance of CMYK color, which keeps this
information internally for later use (when saving).

Usage example(s):

     Color cmyk:{ 100 . 0 . 0 . 0 }     - cyan
     Color cmyk:{ 100 . 0 . 0 . 50 }    - cyan darkened
     Color cmyk:{ 0 . 0 . 0 . 100 }     - black
     Color cmyk:(Color black cmykVector) 
     Color cmyk:(Color white cmykVector) 
     Color cmyk:(Color orange darkened cmykVector)

colorId: id

return a color for a specific colorid without associating it to a
specific device. Use this only for bitmaps which want 0- or 1-color,
or for bitblits if you want to manipulate a specific colorplane.

cyan: c magenta: m yellow: y

return a color from cyan, magenta and yellow values.
all values are given in percent (0..100)

Usage example(s):

     Color cyan:100 magenta:0 yellow:0      - cyan
     Color cyan:100 magenta:100 yellow:0    - blue
     Color cyan:100 magenta:0 yellow:100    - green
     Color cyan:100 magenta:100 yellow:100  - black

cyan: c magenta: m yellow: y black: k

return a color from cyan, magenta, yellow and black values.
all values are given in percent (0..100).
The value returned here is questionable.
TODO: we loose information about one component here,
and should actually return an instance of CMYK color, which keeps this
information internally for later use (when saving).

Usage example(s):

     Color cyan:100 magenta:0 yellow:0 black:0      - cyan
     Color cyan:100 magenta:0 yellow:0 black:50     - cyan darkened
     Color cyan:100 magenta:50 yellow:50 black:0    - cyan darkened
     Color cyan:0 magenta:0 yellow:0 black:100      - black

dither: fraction between: color1 and: color2 on: aDevice

create a dithered Color which dithers between color1 and color2.
Fraction must be 0..1, color1 and color2 must be real (i.e. undithered)
colors.
Useful, if you explicitely want a dithered color
(for example, to not use up too many colors, or for special effects)

Usage example(s):

     (Color dither:0.25 between:Color red and:Color yellow on:Display) inspect
     (Color dither:0.5 between:Color red and:Color yellow on:Display) inspect
     (Color dither:0.75 between:Color red and:Color yellow on:Display) inspect

dithered: fraction between: color1 and: color2 on: aDevice

Usage example(s):

     |c|

     c := Color dithered:0.5 between:Color red and:Color yellow on:Display.
     c inspect.

Usage example(s):

     |v c|

     v := StandardSystemView new.
     v extent:100@100.
     v openAndWaitUntilVisible.

     c := Color dithered:0.5 between:Color red and:Color yellow on:Display.
     v paint:c.
     v fillRectangle:(10@10 corner:90@90).

fromColorDialog

open a color editor, ask for a color;
if cancelled, return nil. Otherwise return the chosen color.

Usage example(s):

     Color fromColorDialog

fromColorDialogWithInitialColor: aColorOrNil

open a color editor, ask for a color.
If the argument aColorOrNil is not nil, the editors shows that color
initially; otherwise black.
Returns nil if cancelled. Otherwise returns the chosen color.

Usage example(s):

     Color fromColorDialogWithInitialColor:(Color yellow)

fromUser

let user point on a screen pixel.
Return an instance for that pixel's color.
If user presses ESC, an abort signal is raised (and if that is ignored, nil is returned).

Usage example(s):

     Color fromUser

fromUserWithFeedBack: feedbackBlockOrNil

let user point on a screen pixel.
Return an instance for that pixels color

Usage example(s):

     Color fromUserWithFeedBack:nil

green: green

return a color from green value;
the argument green is interpreted as percent (0..100)

Usage example(s):

     (Color green:50) inspect

htmlName: colorName

see https://en.wikipedia.org/wiki/Web-safe#HTML_color_names
The web defines 16 standard color names, which are returned here.
Attention:
these are not the same colors as those built into X-servers;
eg. (Color name:'green') returns a bright green,
whereas (Color htmlName:'green') returns a dark green, and 'lime' would be the X-green.
Sigh

Usage example(s):

     Color htmlName:'lime'

     Color htmlName:'green'
     Color name:'green'

htmlName: colorName ifIllegal: errorBlock

see https://en.wikipedia.org/wiki/Web-safe#HTML_color_names
The web defines 16 standard color names, which are returned here.
If aString is not a valid color name,
return the result from evaluating errorBlock.
Attention:
these are not the same colors as those built into X-servers;
eg. (Color name:'green') returns a bright green,
whereas (Color htmlName:'green') returns a dark green, and 'lime' would be the X-green.
Sigh

Usage example(s):

     Color htmlName:'lime'

     Color htmlName:'green'
     Color name:'green'

hue: h brightness: b saturation: s

return a color from hue, light and saturation values.
Hue is in degrees (0..360);
brightness in (0..1)
and saturation in percent (0..100)

Usage example(s):

     Color hue:0 brightness:0.5 saturation:100   - red
     Color hue:0 brightness:0.2 saturation:100   - dark red
     Color hue:0 brightness:0.1 saturation:100   - very dark red
     Color hue:0 brightness:0.8 saturation:100   - light red
     Color hue:0 brightness:0.8 saturation:50    - light greyish red
     Color hue:0 brightness:0.8 saturation:25    - light very greyish red
     Color hue:0 brightness:1 saturation:100     - white

hue: h light: l saturation: s

return a color from hue, light and saturation values.
Hue is in degrees (0..360);
light and saturation are in percent (0..100)

Usage example(s):

     Color hue:0 light:50 saturation:100     - red
     Color hue:60 light:50 saturation:100    - yellow
     Color hue:120 light:50 saturation:100   - green
     Color hue:120 light:75 saturation:100   - bright green
     Color hue:120 light:25 saturation:100   - dark green
     Color hue:120 light:50 saturation:50    - greyish dark green
     Color hue:120 light:50 saturation:0     - b&w television dark green

hue: h saturation: s value: v

return a color from hue, saturation and value (HSV).
Hue is in degrees (0..360);
value and saturation are in percent (0..100)

Usage example(s):

     Color hue:0 saturation:100 value:100     - red
     Color hue:60 saturation:100 value:100    - yellow
     Color hue:120 saturation:100 value:100   - green
     Color hue:0 saturation:0 value:100       - red
     Color hue:120 saturation:100 value:50    - dark green

luma: y chromaBlue: cb chromaRed: cr

return a color from Y-Cb-Cr components.
See https://en.wikipedia.org/wiki/YCbCr
and ITU-R BT.601

Usage example(s):

     Color luma:0 chromaBlue:128 chromaRed:128 
     Color luma:1 chromaBlue:128 chromaRed:128 
     Color luma:0.5 chromaBlue:128 chromaRed:128

name: colorName

Return a named color (either exact or dithered).
Report an error, if aString is not a valid color name.
In previous versions, this used the X11 colornames;
changed to use w3c values
see https://www.w3schools.com/colors/colors_names.asp
Better use: #name:ifIllegal: and provide a fallBack.

Usage example(s):

     Color name:'red'   
     Color name:'brown'   
     Color name:'snow'    
     Color name:'gray'  
     Color name:'grey'   
     Color name:'sgi gray 16'  

     Color name:'lightBrown'
     Color name:'foo'

name: colorName ifIllegal: errorBlock

Return a named color (either exact or dithered).
If aString is not a valid color name,
return the result from evaluating errorBlock.

Usage example(s):

     Color name:'brown' ifIllegal:[Color black]  
     Color name:'red' ifIllegal:[Color black]
     Color name:'fuchsia' ifIllegal:[Color black]
     Color name:'foo' ifIllegal:[Color black]
     Color name:'foo' ifIllegal:[nil]

ncs: ncsName

see NCS colors in wikipedia.

Usage example(s):

     Color ncs:'0510-G50Y' 
     Color ncs:'0510-G20Y'

noColor

return a special color which, when used for bit-blitting will
behave like a 0-color (i.e. have a device-pixel value of all-0s)

random

return a random color

Usage example(s):

     self random inspect

red: red

return a color from red value;
the argument r is interpreted as percent (0..100)

Usage example(s):

     (Color red:50) inspect

red: r green: g blue: b

return a color from red, green and blue values;
the arguments, r, g and b are interpreted as percent (0..100)

Usage example(s):

     Color red:50 green:50 blue:50
     ColorValue red:0.5 green:0.5 blue:0.5
     TranslucentColor red:50 green:50 blue:50

red: redPercent yellow: yellowPercent blue: bluePercent

see wikipedia on the RYB model
RYB makes a nice color wheel...
https://en.wikipedia.org/wiki/Color_wheel#/media/File:RGV_color_wheel_1908.png

Usage example(s):

     self red:100 yellow:100 blue:0

redByte: r greenByte: g blueByte: b

return a color from red, green and blue values;
the arguments, r, g and b are interpreted as byte values (0..255)

Usage example(s):

     (Color redByte:255 greenByte:0 blueByte:0) inspect
     (Color redByte:255 greenByte:255 blueByte:255) inspect
     (Color redByte:0 greenByte:0 blueByte:0) inspect

redByte: r greenByte: g blueByte: b alphaByte: a

return a color from red, green, blue and alpha values;
the arguments, r, g, b and a are interpreted as byte values (0..255)

Usage example(s):

     (Color redByte:255 greenByte:0 blueByte:0 alphaByte:127) inspect

redFraction: r greenFraction: g blueFraction: b

return a color from red, green and blue values;
the arguments, r, g and b are interpreted as fraction (0..1)

redFraction: redFraction yellowFraction: yellowFraction blueFraction: blueFraction

args are in 0..1
see wikipedia on the RYB model
RYB makes a nice color wheel...
https://en.wikipedia.org/wiki/Color_wheel#/media/File:RGV_color_wheel_1908.png

Usage example(s):

     self redFraction:0 yellowFraction:0 blueFraction:0   => Color(sgigrey100)
     self redFraction:0 yellowFraction:1 blueFraction:0   => Color(Yellow)
     self red:100 yellow:100 blue:0                       => Color(#FF8000)

redPercent: r greenPercent: g bluePercent: b

return a color from red, green and blue values;
the arguments, r, g and b are interpreted as percent (0..100)

redPercent: r greenPercent: g bluePercent: b alphaPercent: a

return a color from red, green and blue values;
the arguments, r, g and b are interpreted as percent (0..100)

redShort: r greenShort: g blueShort: b

return a color from red, green and blue short values;
the arguments, r, g and b are interpreted as unsigned short values (0..16rFFFF)

Usage example(s):

     (Color redShort:16rFFFF greenShort:0 blueShort:0) inspect

rgb: rgbVector

return a color from red, green, blue values in a vector.
all values are given in percent (0..100).

Usage example(s):

     Color rgb:{ 100 . 0 . 0 }     - red
     Color rgb:{ 50 . 0 . 0  }     - red darkened
     Color rgb:{ 50 . 0 . 50  }    - violet slightly darkened
     Color rgb:(Color black rgbVector) 
     Color rgb:(Color orange darkened rgbVector)

rgbBytes: rgbBytesVector

return a color from red, green, blue values in a vector.
all values are given in bytes (0..255).

Usage example(s):

     Color rgbBytes:{ 255 . 0 . 0 }     - red
     Color rgbBytes:{ 127 . 0 . 0  }     - red darkened
     Color rgbBytes:{ 127 . 0 . 127  }    - violet slightly darkened
     Color rgbBytes:(Color black rgbBytes) 
     Color rgbBytes:(Color orange darkened rgbBytes)

rgbValue: rgb

return a color from a 24bit RGB value;
The value is composed of r<<16 + g<<8 + b,
i.e. rrggbb

Usage example(s):

     (Color rgbValue:16rFF0000) inspect
     (Color rgbValue:16r00FF00) inspect
     (Color rgbValue:16r0000FF) inspect
     (Color rgbValue:16rFF00FF) inspect
     (Color rgbValue:16rFFFFFF) inspect

scaledGray: aGrayValue

return a gray color with a scaled gray value (0..MaxValue)

scaledRed: r scaledGreen: g scaledBlue: b

return a color from red, green and blue values;
the arguments, r, g and b are interpreted as (0..MaxValue)

variableColorOn: aDevice

return a variable color (i.e. allocate a writable colorcell) on
aDevice. The returned color is not shared and its rgb components
are initially undefined. The components can be set to any value
using Color>>red:green:blue. Care should be taken, since this call
fails on static color or b&w displays (i.e. it depends on the device
being a pseudocolor device using colormaps).
Returns nil, if no more colorCells are available, or the display
uses a fix colormap (i.e. is a directColor or staticColor pr b&w device).
Because of this, you should not write your application to depend on
writable colors to be available (i.e. add fallBack code to redraw
things in another color)

Usage example(s):

     |l cell|

     l := Label new.
     l label:('hello' asText allBold).

     cell := Color variableColorOn:(Screen current).
     l foregroundColor:cell.
     [
	1 to:40 do:[:i|
	    i odd ifTrue:[
		cell red:100 green:0 blue:0
	    ] ifFalse:[
		cell red:0 green:0 blue:0
	    ].
	    Display flush.
	    (Delay forSeconds:0.4) wait
	].
	l destroy.
     ] fork.
     l open

obsolete

nameOrDither: colorName: return a named color - if the exact color is not available,
return a dithered color. Report an error, if the colorname is
illegal.

** This is an obsolete interface - do not use it (it may vanish in future versions) **
nameOrDither: colorName ifIllegal: errorBlock: return a named color - if the exact color is not available,
return a dithered color. If the colorname is illegal, return
the value of evaluating errorBlock.

** This is an obsolete interface - do not use it (it may vanish in future versions) **
nameOrNearest: colorName: return a named color - or its nearest match

** This is an obsolete interface - do not use it (it may vanish in future versions) **

private

colorNearRed: r green: g blue: b on: aDevice: return a device color on aDevice with rgb values
almost matching. If there is one, nil otherwise.
This is tried as a last chance before dithering.
The algorithm needs rework, the color components
should be weighted according some theory :-)
existingColorRed: r green: g blue: b on: aDevice: return a device color on aDevice with rgb values
if there is one, nil otherwise.
existingColorScaledRed: r scaledGreen: g scaledBlue: b on: aDevice: return a device color on aDevice with rgb values
if there is one, nil otherwise.

private-dithering

complexDitherRed: red green: green blue: blue on: aDevice into: aBlock

get a deep dither form for an rgb value.
Use all available colors for error dithering into a form.

ditherBits

return a dither pattern for x/64; x in 1..63

ditherGrayFor: fraction on: aDevice into: aBlock

get a dither form or colorId for a brightness value.
Fraction is 0..1.
Returns 2 values (either color or ditherForm) through aBlock.

Usage example(s):

     Color basicNew
	ditherGrayFor:0.5
	on:Display
	into:[:clr :form | clr notNil ifTrue:[clr inspect].
			   form notNil ifTrue:[(form magnifiedBy:16) inspect].]

Usage example(s):

     Color basicNew
	ditherGrayFor:0.25
	on:Display
	into:[:clr :form | clr notNil ifTrue:[clr inspect].
			   form notNil ifTrue:[(form magnifiedBy:16) inspect].]

ditherRed: rV green: gV blue: bV on: aDevice into: aBlock

get a dither form or colorId for an rgb value.
Returns 2 values (either color or ditherForm) through
aBlock.
This code is just a minimum of what is really needed,
and needs much more work. Currently only some special cases
are handled

fixDitherRed: redVal green: greenVal blue: blueVal on: aDevice into: aBlock

get a dither form for an rgb value.
Returns 2 values (either color or ditherForm) through aBlock.
This code uses the table of preallocated fix-colors to find
dither colors.

monoDitherFor: fraction between: color1 and: color2 on: aDevice into: aBlock

get a dither form or colorId for dithering between 2 colors.
Fraction is 0..1.
Returns 2 values (either color or ditherForm) through aBlock.

Usage example(s):

     Color basicNew
	monoDitherFor:(MaxValue // 2)
	between:Color black
	and:Color white
	on:Display
	into:[:clr :dither | clr inspect. dither inspect]

queries

constantNames

return names known as instance creation messages

getScaledRGBFromName: colorName into: aBlock

get scaled rgb components (0..16rFFFF) of the color named colorName,
and evaluate the 3-arg block, aBlock with them.
In addtion to names, this also supports the #RRGGBB notation (hex).
Returns the value from evaluating aBlock,
or nil for unknown color names or invalid hex numbers.

Usage example(s):

     self getScaledRGBFromName:'green' into:[:r :g :b |
        Transcript showCR: e'{r} / {g} / {b}'
     ]

     self getScaledRGBFromName:'lime' into:[:r :g :b |
        Transcript showCR: e'{r} / {g} / {b}'
     ]

     self getScaledRGBFromName:'#ff00ff' into:[:r :g :b |
        Transcript showCR: e'{r} / {g} / {b}'
     ]

     self getScaledRGBFromName:'veryVeryLightGray' into:[:r :g :b |
        Transcript showCR: e'{r} / {g} / {b}'
     ]

scalingValue

ST-80 compatibility

w3cColorValues

return name->value assocs of w3c colors

special instance creation

nearestColorRed: r green: g blue: b on: aDevice in: colors: return the nearest color on aDevice with RGB values
same or near r/g/b in a collection of colors.
If there is one, return it; nil otherwise.
Near is defined as having an error less than the argument
error (in percent). The error is computed by the color
vector distance (which may not be the best possible solution).
nearestColorScaledRed: r scaledGreen: g scaledBlue: b inCube: aColorCube numRed: nRed numGreen: nGreen numBlue: nBlue: return a color with rgb values same or near r/g/b in a given
collection, containing colors from a colorCube.
This is used with preallocated fixColors and is quite fast
(no need to search)
nearestColorScaledRed: r scaledGreen: g scaledBlue: b on: aDevice: return a device color on aDevice with RGB values
same or near r/g/b, if there is one, nil otherwise.
Near is defined as having an error less than the argument
error (in percent). The error is computed by the color
vector distance (which may not be the best possible solution).
nearestColorScaledRed: r scaledGreen: g scaledBlue: b on: aDevice in: colors: return the nearest color (optionally on aDevice) with RGB values
same or near r/g/b in a collection of colors.
If there is one, return it;
nil otherwise.
quickNearestColorScaledRed: r scaledGreen: g scaledBlue: b on: aDevice: return a device color on aDevice with rgb values
same or near r/g/b.
This looks for primary colors only and is thus faster
than the general nearestColor search (slightly uglier though).

utilities

RGBToYUV: rgbInteger

convert the 24bit integer in the format rrggbb (blue at least signif. bits)
to yuv in the format yyuuvv (v at least signif. bits).
Notice, that you won't get the original rgb value,
when converting rgb -> yuv -> rgb (due to rounding errors).
Uses the ITU-R factors (see https://en.wikipedia.org/wiki/YUV)

Usage example(s):

     (self RGBToYUV:0xFF0000) hexPrintString    '4C55FF'
     (self RGBToYUV:0x00FF00) hexPrintString    '952C16'
     (self RGBToYUV:0x0000FF) hexPrintString    '1DFF6C'

     (Color rgbValue:0xFF0000) grayByte hexPrintString 
     (Color rgbValue:0x00FF00) grayByte hexPrintString
     (Color rgbValue:0x0000FF) grayByte hexPrintString

YUVToRGB: yuvInteger

convert the 24bit integer in the format yyuuvv (v at least signif. bits)
to yuv in the format rrggbb (blue at least signif. bits).
Notice, that you won't get the original rgb value,
when converting rgb -> yuv -> rgb (due to rounding errors).
Uses the ITU-R factors (see https://en.wikipedia.org/wiki/YUV)

Usage example(s):

     (self RGBToYUV:0xFF0000) hexPrintString    '4C55FF'
     (self RGBToYUV:0x7F0000) hexPrintString    '256BBF'
     (self RGBToYUV:0x3F0000) hexPrintString    '12769F'
     (self YUVToRGB:0x4C55FF) hexPrintString  'FE0000'  
     (self YUVToRGB:0x256BBF) hexPrintString  '7D0000'  
     (self YUVToRGB:0x12769F) hexPrintString  '3D0000'  

     (self RGBToYUV:0x00FF00) hexPrintString    '952C16'
     (self YUVToRGB:0x952C16) hexPrintString  'FD00'  
     (self RGBToYUV:0x0000FF) hexPrintString    '1DFF6C'
     (self YUVToRGB:0x1DFF6C) hexPrintString  'FE'

allocateColorsIn: aColorVector on: aDevice

preallocates a nR x nG x nB colorMap for later use in dithering.
Doing so has the advantage that the system will never run out of colors,
however, colors may be either inexact or dithered.

best: numColors ditherColorsForImage: anImage

work in progress

Usage example(s):

     Color
        best:16 
        ditherColorsForImage:(Image fromFile:'../../goodies/bitmaps/pcxImages/lena_depth8_palette.pcx')

     Color
        best:16 
        ditherColorsForImage:(Image fromFile:'../../goodies/bitmaps/pcxImages/lena_depth24_rgb.pcx')

     Color
        best:16 
        ditherColorsForImage:((Image fromFile:'../../goodies/bitmaps/pcxImages/lena_depth8_palette.pcx') asGrayImageDepth:8)

browserColors

return the palette, known as 'the color cube', 'the Netscape palette',
or 'the Browser-Safe palette'.
This is familiar to all seasoned Web designers and graphics production specialists;
Use this map for low-color-res depth 8 (gif-) images, if old pseudo displays are to be
supported.

Usage example(s):

     |img|

     img := Image width:(8*6*6)+1 height:(8*6)+1 depth:8.
     img colorMap:(Color browserColors). 
     img pixelFunction:
         [:x :y |
            |r g b|
            
            (y \\ 8 == 0 ) ifTrue:[
                86
            ] ifFalse:[
                x \\ 8 == 0 ifTrue:[
                    86
                ] ifFalse:[
                    r := g := b := 0.
                    'y is green component'.
                    g := 5-(y // 8).
                    'x inside subsquare is blue component'.
                    b := (x \\ (8*6)) // 8.
                    'subsquare is red component'.
                    r := (x // (8*6)).
                    ((r*6)+g)*6+b
                ]
            ].    
         ].
     img inspect.

colorCubeWithRed: nRed green: nGreen blue: nBlue

given a number of red, green and blue shades,
return a color cube (map) containing those colors.
Eg, return a map containing any combination of the
nRed, nGreen and nBlue shades.
This is used for dithering of deep images onto limited-depth canvases
for example: with nRed,nGreen,nBlue == 2,3,2
you will get a cube of 2*3*2 = 12 colors, with two shades of red (0 and 255),
threed shades of green (0, 127 and 255) and two shades of blue (0 and 255).

Usage example(s):

     Color colorCubeWithRed:2 green:2 blue:2
     Color colorCubeWithRed:2 green:3 blue:2
     Color colorCubeWithRed:3 green:4 blue:3

flushDeviceColors

unassign all colors from their device

flushDeviceColorsFor: aDevice

getColors6x6x4

preallocates a 6x6x4 (144) colorMap and later uses those colors only
on a palette display (pseudoColor visual).

Doing so has the advantage that the system will never run out of colors,
however, colors may be either inexact or dithered.

Usage example(s):

     Color getColors6x6x4

getColors6x6x5

preallocates a 6x6x5 (180) colorMap and later uses those colors only
on a palette display (pseudoColor visual).

Doing so has the advantage that the system will never run out of colors,
however, colors may be either inexact or dithered.

Usage example(s):

     Color getColors6x6x5

getColors6x6x6

preallocates a 6x6x6 (196) colorMap and later uses those colors only
on a palette display (pseudoColor visual).

Doing so has the advantage that the system will never run out of colors,
however, colors may be either inexact or dithered.

Usage example(s):

     Color getColors6x6x6

getColors6x7x4

preallocates a 6x7x4 (168) colorMap and later uses those colors only
on a palette display (pseudoColor visual).

Doing so has the advantage that the system will never run out of colors,
however, colors may be either inexact or dithered.

Usage example(s):

     Color getColors6x7x4

getColors7x8x4

preallocates a 7x8x4 (224) colorMap and later uses those colors only
on a palette display (pseudoColor visual).

Doing so has the advantage that the system will never run out of colors,
however, colors may be either inexact or dithered.

Usage example(s):

     Color getColors7x8x4

getColorsRed: nRed green: nGreen blue: nBlue

preallocates a nR x nG x nB colorMap for later use in dithering
on a palette display (pseudoColor visual).

Doing so has the advantage that the system will never run out of colors,
however, colors may be either inexact or dithered.

Usage example(s):

     Color getColorsRed:2 green:2 blue:2

getColorsRed: nRed green: nGreen blue: nBlue on: aDevice

Usage example(s):

     Color getColorsRed:2 green:2 blue:2 on:Display

getGrayColors: nGray on: aDevice

preallocates nGray gray colors for later use in dithering
on a palette display (pseudoColor visual).

Doing so has the advantage that the system will never run out of colors,
however, colors may be either inexact or dithered.

Usage example(s):

     Color getGrayColors:16 on:Display

getPrimaryColorsOn: aDevice

preallocate the primary colors on a palette display (pseudoColor visual).

Doing so during early startup prevents us from running out
of (at least those required) colors later.
This guarantees, that at least some colors are available
for dithering (although, with only black, white, red, green and blue,
dithered images look very poor).

grayColorVector: nGray

Color getGrayColors:16 on:Display

standardDitherColorsForDepth8

return a set of colors useful for dithering (roughly 200 colors);
This includes a color cube and the main grayScale colors.

Usage example(s):

     self standardDitherColorsForDepth8

vgaColors

Instance protocol:

Compatibility-ST80

asDevicePaintOn: aDevice: ST-80 compatibility: an alias for on:.
create a new Color representing the same color as
myself on aDevice; if one already exists, return the one
asHiliteColor: same as lightened - for ST-80 compatibility
asShadowColor: same as darkened - for ST-80 compatibility

Compatibility-Squeak

alphaMixed: proportion with: aColor

Squeak compatibility:
Answer this color mixed with the given color. The proportion, a number
between 0.0 and 1.0, determines what what fraction of the receiver to
use in the mix.
For example, 1.0 yields the receiver, 0.0 yields aColor
and 0.9 would yield a color close to the receiver.
This method uses RGB interpolation;
HSV interpolation can lead to surprises.
Mixes the alphas (for transparency) also.

Usage example(s):

     (Color r:1 g:0 b:0 alpha:1) alphaMixed:0.5 with:(Color r:1 g:0 b:0 alpha:1)
     (Color r:1 g:0 b:0 alpha:0.5) alphaMixed:0.5 with:(Color r:0 g:1 b:0 alpha:0.5)

bitPatternForDepth: depth

Squeak compatibility:
Return a Bitmap, possibly containing a stipple pattern,
that best represents this color at the given depth.
BitBlt calls this method to convert colors into Bitmaps.
The resulting Bitmap may be multiple words to represent a stipple
pattern of several lines.

colorForInsets

Squeak compatibility - dummy

darker

Squeak compatibility;
return a new color, which is darker than the receiver.
Almost the same as darkened for Squeak compatibility.

Usage example(s):

     (Color red) darker
     (Color red) slightlyDarker
     (Color red) slightlyLighter
     (Color red) lighter
     (Color red) muchLighter
     (Color red) muchDarker

isColorObject

lighter

Squeak compatibility;
return a new color, which is slightly lighter than the receiver.
Almost the same as lightened for Squeak compatibility.

Usage example(s):

     (Color red) darker
     (Color red) slightlyDarker
     (Color red) slightlyLighter
     (Color red) lighter
     (Color red) muchLighter
     (Color red) muchDarker

muchDarker

Squeak compatibility:
return a new color, which is much darker than the receiver

Usage example(s):

     (Color red) darker
     (Color red) slightlyDarker
     (Color red) slightlyLighter
     (Color red) lighter
     (Color red) muchLighter
     (Color red) muchDarker

muchLighter

Squeak compatibility:
return a new color, which is much lighter than the receiver

Usage example(s):

     (Color red) darker
     (Color red) slightlyDarker
     (Color red) slightlyLighter
     (Color red) lighter
     (Color red) muchLighter
     (Color red) muchDarker

newTileMorphRepresentative
( an extension from the stx:libcompat package )

Squeak compatibility - dummy

privateBlue

Squeak compatibility:
return the blue components value mapped to 0..MaxValue

privateGreen

Squeak compatibility:
return the green components value mapped to 0..MaxValue

privateRed

Squeak compatibility:
return the red components value mapped to 0..MaxValue

scaledPixelValue32

Squeak compatibility:
return the argb byteValues packed into a 32bit integer;
The returned value is composed of a<<24 + r<<16 + g<<8 + b.
This is similar to rgbValue, but has an additional alpha byte value
in its high bits (which is 0 for fully transparent, 255 for fully opaque colors)

slightlyDarker

Squeak compatibility

Usage example(s):

     (Color red) darker
     (Color red) slightlyDarker
     (Color red) slightlyLighter
     (Color red) lighter
     (Color red) muchLighter
     (Color red) muchDarker

slightlyLighter

Squeak compatibility

Usage example(s):

     (Color red) darker
     (Color red) slightlyDarker
     (Color red) slightlyLighter
     (Color red) lighter
     (Color red) muchLighter
     (Color red) muchDarker

twiceDarker

Squeak compatibility:
return a new color, which is twice as dark as the receiver

Usage example(s):

     (Color red) 
     (Color red) darker
     (Color red) twiceDarker
     (Color red) muchDarker

veryMuchLighter

Squeak compatibility:
return a new color, which is very much lighter than the receiver

Usage example(s):

     (Color red) lighter
     (Color red) slightlyLighter
     (Color red) muchLighter
     (Color red) veryMuchLighter
     (Color red) slightlyDarker
     (Color red) darker
     (Color red) muchDarker

wheel: thisMany

Squeak compatibility:
An array of thisMany colors around the color wheel,
starting at self and ending all the way around the hue space just before self.
Array is of length thisMany.
Very useful for displaying color based on a variable in your program.

Usage example(s):

     Color red wheel:20
     Color red wheel:40

accessing

alpha

return the alpha value (0..1),
where 0 is completely transparent and 1 is completely opaque

alphaByte

return the alpha byte-value (0..255),
where 0 is completely transparent and 255 is completely opaque

blue

return the blue component in percent [0..100]

blueByte

return the blue components value mapped to 0..255

Usage example(s):

     Color red blueByte
     Color blue blueByte
     Color green blueByte
     Color black blueByte
     Color grey blueByte
     Color white blueByte

blueFraction

return the blue component in 0..1

cmyVector

return a vector containing cyan, magenta and yellow
in percent cmy color space.

Usage example(s):

     Color yellow cmyVector
     Color cmy:(Color green cmyVector)

cmykVector

return a vector containing cyan, magenta, yellow and black
in cmyk color space.

Usage example(s):

     Color yellow cmykVector
     Color green cmykVector

colorId

return the device-dependent color-id

cyan

return the cyan component in percent [0..100] in cmy color space

device

return the device I am associated to.
Please use graphicsDevice for ST80 compatibility.

** This is an obsolete interface - do not use it (it may vanish in future versions) **

deviceBlue

return the actual value of the blue component in percent.

deviceGreen

return the actual value of the green component in percent.
(usually 16bit in X; but could be different on other systems)

deviceRed

return the actual value of the red component in percent.

Usage example(s):

     (Color yellow on:Display) deviceRedValue
     (Color yellow on:aPrinterPage) deviceRedValue

ditherForm

return the form to dither the color

graphicsDevice

same as #device, for ST-80 compatibility naming.
Return the device I am associated with.

green

return the green component in percent [0..100]

greenByte

return the green components value mapped to 0..255

Usage example(s):

     Color red greenByte
     Color blue greenByte
     Color green greenByte
     Color black greenByte
     Color grey greenByte
     Color white greenByte

greenFraction

return the green component in 0..1

hue

return the hue (in hue/light/saturation model) in degrees [0..360].
The hue value is the position on the color wheel.
0 is red, 120 green, 240 blue

Usage example(s):

     Color red hue      => 0.0
     Color yellow hue   => 60.0
     Color green hue    => 120.0
     Color brown hue    => 0.0

light

return the light (in hue/light/saturation model) in percent [0..100].
This corresponds to the brightness of the color (if displayed on
a b&w television screen).
Old; please use #brightness (which is 0..1) for compatibility with other smalltalks

Usage example(s):

     Color yellow light
     Color yellow darkened light

magenta

return the magenta component in percent [0..100] in cmy color space

privateAlpha

return the internal alpha value (0..255),
where 0 is completely transparent and 255 is completely opaque

red

return the red component in percent [0..100]

red: r green: g blue: b

set r/g/b components in percent. This method will change the color lookup
table in pseudocolor devices.
This is only allowed for writable colors (i.e. those allocated with
Color>>variableColorOn: on pseudoColor displays).
Using this may make your code unportable, since it depends on a display
using palettes (i.e. it will not work on greyScale or b&w displays).

Usage example(s):

     |c|

     c := Color variableColorOn:Display.
     c inspect.
     (Delay forSeconds:5) wait.
     c red:100 green:0 blue:0.
     (Delay forSeconds:5) wait.
     c red:0 green:100 blue:0.
     (Delay forSeconds:5) wait.
     c red:0 green:0 blue:100.

redByte

return the red components value mapped to 0..255;
nil if it has no red component.

Usage example(s):

     Color red redByte
     Color blue redByte
     Color green redByte
     Color black redByte
     Color grey redByte
     Color white redByte

redFraction

return the red component in 0..1

rgbBytes

return the rgb byteValues as a 3-byte byteArray #[red green blue]

Usage example(s):

     Color red rgbBytes
     Color blue rgbBytes
     Color green rgbBytes
     Color black rgbBytes
     Color grey rgbBytes
     Color white rgbBytes

rgbValue

return the rgb byteValues packed into a single 24bit integer;
The returned value is composed of r<<16 + g<<8 + b.

Usage example(s):

     Color red rgbValue hexPrintString
     Color blue rgbValue hexPrintString
     Color green rgbValue hexPrintString
     Color black rgbValue hexPrintString
     Color grey rgbValue hexPrintString
     Color white rgbValue hexPrintString

rgbVector

return the rgb values (in percent) as a vector

Usage example(s):

     Color red rgbVector
     Color blue rgbVector
     Color green rgbVector
     Color black rgbVector
     Color grey rgbVector
     Color white rgbVector

saturation

return the saturation (in hue/light/saturation model) in percent [0..100].
This corresponds to the saturation setting of a color TV

Usage example(s):

     Color yellow saturation

scaledAlpha

ST-80 compatibility:
return the alpha components value mapped to 0..MaxValue

scaledBlue

ST-80 compatibility:
return the blue components value mapped to 0..MaxValue

Usage example(s):

     Color blue scaledBlue
     Color black scaledBlue
     Color grey scaledBlue

scaledGray

return the grey intensity scaled to 0..MaxValue

Usage example(s):

     Color blue scaledGray
     Color black scaledGray
     Color white scaledGray
     Color grey scaledGray

scaledGreen

ST-80 compatibility:
return the green components value mapped to 0..MaxValue

scaledRed

ST-80 compatibility:
return the red components value mapped to 0..MaxValue

Usage example(s):

     Color red scaledRed
     Color black scaledRed
     Color grey scaledRed

scaledRed: r scaledGreen: g scaledBlue: b

set r/g/b components in 0..MaxValue.
This method will change the color lookup table in pseudocolor devices.
This is only allowed for writable colors (i.e. those allocated with
Color>>variableColorOn: on pseudoColor displays).
Using this may make your code unportable, since it depends on a display
using palettes (i.e. it will not work on greyScale or b&w displays).

writable

return true, if this is a writable colorcell

yellow

return the yellow component in percent [0..100] in cmy color space

comparing

= aColor

two colors are considered equal, if the color components are;
independent of the device, the color is on

almostSameAs: aColor

return true, if aColor looks almost the same as the receiver
(i.e. the components differ by a small, invisible amount).
We assume, that the human eye can distinguish roughly 100 grey levels
(which is optimistic ;-);
therefore, allow a 1 percent difference in each component for the colors
to compare as looking the same.

Usage example(s):

      (Color red:10 green:10 blue:10) almostSameAs:(Color red:11 green:11 blue:11)

hash

return an integer useful as hash key for the receiver.
Redefined since = is redefined

converting

asByteArray

return the rgb byteValues as a 3-byte byteArray #[red green blue]

fromLiteralArrayEncoding: encoding

read my values from an encoding.
The encoding is supposed to be either of the form:
(#Color redPart greenPart bluePart)
or:
(#Color constantColorSymbol)
This is the reverse operation to #literalArrayEncoding.

Usage example(s):

      Color new fromLiteralArrayEncoding:#(Color 50 25 25)
      Color new fromLiteralArrayEncoding:#(Color 16rFF00FF)
      Color new fromLiteralArrayEncoding:#(Color blue)

literalArrayEncoding

encode myself as an array, from which a copy of the receiver
can be reconstructed with #decodeAsLiteralArray.
The encoding is:
(#Color redPart greenPart bluePart)

Usage example(s):

      Color new fromLiteralArrayEncoding:#(#Color 50 25 25)
      (Color red:25 green:30 blue:70) literalArrayEncoding

copying

skipInstvarIndexInDeepCopy: index: cg: this is a horrible interface (DANGER alert).
there ought to be some unitTest to verify that:
self assert:(self instVarIndexFor:'device') == 4
self assert:(self instVarIndexFor:'colorId') == 5
self assert:(self instVarIndexFor:'ditherForm') == 6
self assert:(self instVarIndexFor:'replacementColor') == 7
etc.

copying-private

postCopy: redefined to clear out any device handles in the copy

encoding & decoding

skippedInJSONEncoding
( an extension from the stx:goodies/communication package ): return the names of inst-slots which are to be skipped when generating a jsonEncoding;
(to skip the ones with default or irrelevant values.)

getting a device color

exactOn: aDevice: create a new Color representing the same color as
myself on aDevice; if one already exists, return the one.
Do not dither or otherwise approximate the color, but return
nil, if the exact color is not available.
Used to acquire primary colors for dithering, during startup.
exactOrNearestOn: aDevice: get a device color for the receiver, which is either exact
or the nearest, but never dithered.
This can be used for viewBackgrounds, where the exact greyLevel
does not matter, but a dithered color is not wanted.
nearestIn: aColorMap: return the nearest color in a colorMap
nearestOn: aDevice: create a new Color representing the same color as myself on aDevice;
if one already exists, return the one. If no exact match is found,
search for the nearest match
on: aDevice: create a new Color representing the same color as
myself on aDevice; if one already exists, return the one

** This is an obsolete interface - do not use it (it may vanish in future versions) **
onDevice: aDevice: create a new Color representing the same color as
myself on aDevice; if one already exists, return the one

inspecting

inspectorExtraAttributes
( an extension from the stx:libtool package ): extra (pseudo instvar) entries to be shown in an inspector.
inspectorExtraMenuOperations
( an extension from the stx:libtool package ): extra (pseudo instvar) entries to be shown in an inspector.
inspectorValueListIconFor: anInspector
( an extension from the stx:libtool package ): returns the icon to be shown alongside the value list of an inspector
inspectorValueStringInListFor: anInspector
( an extension from the stx:libtool package ): returns a string to be shown in the inspector's list

instance creation

alpha: alphaValue

return a (possibly) new color with the same color, but different alpha as the receiver.
The alpha argument's range is 0..1 (0=completely transparent; 1=completely opaque)

Usage example(s):

     (Color red alpha:0.5) alpha
     Color red alpha

blendWith: aColor

create a new color from equally mixing the receiver
and the argument, aColor.
Mixing is done by adding components
(which is different from mixing colors on paper .. which is subtractive).

Usage example(s):

     (Color red) blendWith:(Color yellow)
     (Color red) blendWith:(Color blue)
     (Color red) blendWith:(Color black)
     (Color red) blendWith:(Color white)

contrastingBlackOrWhite

answer either black or white, whichever gives a better contrast
for drawing text on a background with my color.
(i.e. if I am dark, return white; if I am bright, return black

Usage example(s):

     (Color blue) contrastingBlackOrWhite
     (Color red) contrastingBlackOrWhite
     (Color green) contrastingBlackOrWhite
     (Color yellow) contrastingBlackOrWhite

contrastingColorFor: aBackgroundColor

answer a slightly brightened or darkened variant of myself,
to ensure a good contrast when showing text on a background color.
i.e. when drawing read on grey, it might be better to darken or brighten
the red, if it's brightness is too near to the grey's brightness.
Use this for alert strings shown on a color background.

Usage example(s):

     (Color blue) contrastingColorFor:Color white.
     (Color blue) contrastingColorFor:Color blue.
     (Color blue) contrastingColorFor:View defaultBackgroundColor.
     (Color red) contrastingColorFor:Color grey
     (Color blue) contrastingColorFor:Color black

darkened

return a new color, which is slightly darker than the receiver

Usage example(s):

     (Color red) darkened
     (Color red) darkened darkened

lightened

return a new color, which is slightly lighter than the receiver

Usage example(s):

     (Color red) lightened
     (Color red) lightened lightened

mixed: amount with: aColor

create a new color from mixing amount of the receiver
with the argument, aColor.
Mixing is done by adding components (i.e. additive mixing)
(which is different from mixing colors on paper, which is subtractive).
With an amount of 1, this is the same as blendWith (i.e. 1:1 mixing of rcvr:arg).
With an amount of 0, this returns aColor (i.e. 0 parts of the receiver, 1 of the argument).

Usage example(s):

     (Color red) mixed:1 with:(Color yellow)    - 1 part red, 1 part yellow
     (Color red) mixed:0.9 with:(Color yellow)
     (Color red) mixed:0.8 with:(Color yellow)
     (Color red) mixed:0.5 with:(Color yellow)  - 1 part red, 2 parts yellow
     (Color red) mixed:0.25 with:(Color yellow) - 1 part red, 4 parts yellow  
     (Color red) mixed:0 with:(Color yellow)    - 0 parts red, 1 part yellow

     (Color red) mixed:1 with:(Color white)
     (Color red) mixed:0.8 with:(Color white)
     (Color red) mixed:0.8 with:(Color black)

     (Color green) mixed:0.5 with:(Color grey)
     (Color red) mixed:0.5 with:(Color grey)

mixedSubtractive: amount with: aColor

create a new color from mixing amount of the receiver
with the argument, aColor.
Mixing is done subtractive; i.e. like mixing paints on a piece of paper.
(which is different from additive mixing colors on paper.
Amount is 0.. and gives the amount of myself to be mixed in
(i.e. with amount=1, mixing is 1:1;
with amount=0, we get aColor;
with amount=2, we take 2 parts of the receiver and 1 part of aColor)
WARNING: this yields unsatisfying results
(mix blue and yellow (which are complementary) to get a grey...)

Usage example(s):

     (Color blue) mixedSubtractive:1 with:(Color yellow) 
     (Color blue) mixedSubtractive:2 with:(Color yellow) 
     (Color blue) mixedSubtractive:0.5 with:(Color yellow) 
     (Color cyan) mixedSubtractive:1 with:(Color yellow)    - 1 part cyan, 1 part yellow
     (Color cyan) mixedSubtractive:0 with:(Color yellow)    - all yellow
     (Color cyan) mixedSubtractive:2 with:(Color yellow)    - 2 parts cyan, 1 part yellow
     (((Color cyan) 
        mixedSubtractive:1 with:(Color yellow))
        mixedSubtractive:1 with:(Color magenta))

saturatedBy: aFraction

return a new color, which is more or less saturated than the receiver
by the argument factor;
Fraction values greater than 1 will increase the saturation,
values less than 1 will decrease it.
I.e. with 0.5 the result will be more greyish,
with 2 it will be more colorful

Usage example(s):

     (Color red blendWith:Color grey) saturation        50.0970844099255

     (Color red blendWith:Color grey) saturatedBy:1.1   Color(#C53939)
     (Color red blendWith:Color grey) saturatedBy:1.2   Color(#CC3333)
     (Color red blendWith:Color grey) saturatedBy:1.3   Color(#D22C2C)
     (Color red blendWith:Color grey) saturatedBy:1.4   Color(#D82626)
     (Color red blendWith:Color grey) saturatedBy:1.5   Color(#DF2020)

     (Color red blendWith:Color grey) saturatedBy:0.9   Color(#B94646)
     (Color red blendWith:Color grey) saturatedBy:0.8   Color(#B24C4C)
     (Color red blendWith:Color grey) saturatedBy:0.7   Color(#AC5353)
     (Color red blendWith:Color grey) saturatedBy:0.5   Color(#9F5F5F)
     (Color red blendWith:Color grey) saturatedBy:0     Color(gray50)

slightlyDarkened

return a new color, which is a bit darker than the receiver

Usage example(s):

     (Color lime) inspect
     (Color lime) darkened inspect
     (Color lime) slightlyDarkened inspect

slightlyLightened

return a new color, which is a bit lighter than the receiver

Usage example(s):

     (Color red) inspect
     (Color red) lightened inspect
     (Color red) slightlyLightened inspect

instance release

executor: redefined, since for finalization only device and colorIndex
are needed - thus a faster copy is possible here
releaseFromDevice: I am no longer available on the device

misc

magnifiedTo: extent: do nothing here, for compatibility with Image/Form

misc ui support

inspectorClass
( an extension from the stx:libtool package ): return the class of an appropriate inspector.
ST/X has a specialized ColorInspectorView for that

object persistency

elementDescriptorFor: aspect: support for persistency:
answer the elements to be made persistent with an ObjectCoder

printing & storing

displayOn: aStream

Color red printString
Color red displayString
Color red storeString

Color red lightened printString
Color red lightened displayString
Color red lightened storeString

hex

** This is an obsolete interface - do not use it (it may vanish in future versions) **

hexPrintOn: aStream

print a base16 representation on aStream as rrggbb

hexPrintString

return a hex-printString as rrggbb

Usage example(s):

     Color red hexPrintString   -> 'FF0000'
     Color green hexPrintString -> '008000' 
     Color blue hexPrintString
     Color yellow hexPrintString

htmlPrintString

return a hex-printString for html as #rrggbb

Usage example(s):

     Color red htmlPrintString
     Color green htmlPrintString
     Color blue htmlPrintString
     Color yellow htmlPrintString

printOn: aStream

append a string representing of the receiver
to the argument, aStream

standardColorNameOrNil

see if the receiver has a standard name;
return it if so. Otherwise return nil.
This is a slow linear O(n) algorithm;
needs a reverse map from color-tuple to name if heavily used
(for now, it is used to generate a storeString)

Usage example(s):

     Color red standardColorNameOrNil

storeOn: aStream

append a string representing an expression to reconstruct the receiver
to the argument, aStream

w3cColorNameOrNil

see if the receiver has a w3c name; return it if so.
Otherwise return nil.
This is a slow linear O(n) algorithm;
needs a reverse map from color-tuple to name if heavily used
(for now, it is used in the inspector only)

Usage example(s):

     Color red w3cColorNameOrNil             => 'Red'
     (Color grey:50) w3cColorNameOrNil       => nil

     (Color grey:50) standardColorNameOrNil  => 'grey50'

wellknownColorNameOrNil

see if the receiver has a wellknown name; return it if so.
Otherwise return nil.
Wellknown colors have a special instance creation message in the Color class.
This is used to generate a storeString for the most common colors
(primary and secondary colors i.e.. red, green, blue, magenta, etc.)

Usage example(s):

     Color lime wellknownColorNameOrNil          => #lime 
     Color red wellknownColorNameOrNil           
     Color lightGray wellknownColorNameOrNil     => #lightGray      
     Color red lightened wellknownColorNameOrNil => nil

private

restored

private: color has been restored (either from snapin or binary store);
flush device stuff or reallocate a cell.

Usage example(s):

a variable color has been restored

setColorId: anId

private: set the deviceId

setDevice: aDevice colorId: aNumber

private:set device and colorId

setDevice: aDevice colorId: aNumber writable: wBool

private:set device, colorId and writable flag

setDitherForm: aForm

private: set the ditherForm

setScaledRed: r scaledGreen: g scaledBlue: b

private: set the components

setScaledRed: r scaledGreen: g scaledBlue: b device: aDevice

private: set the components

queries

averageColor

return the average color - that's myself.
This method has been added for compatibility with the image protocol.

averageColorIn: aRectangle

return the average color - that's myself.
This method has been added for compatibility with the image protocol.

brightness

ST80 compatibility: return the grey intensity in [0..1]

Usage example(s):

     Color black brightness -> 0.0
     Color white brightness -> 1.0
     Color red brightness   -> 0.3
     Color green brightness -> 0.6
     Color blue brightness  -> 0.1

colorNameOrNilInDictionary: aDictionary

see if the receiver has a name in aDictionary; return it if so.
Otherwise return nil.
This is a slow linear O(n) algorithm;
needs a reverse map from color-tuple to name if heavily used
(for now, it is used to generate a storeString)

deltaFrom: aColor

return the distance of the receiver from some color specified
by r/g/b values.
A very questionable value;
basing the distance on rgb values is very bad
- better do a distance in a cie color cone

Usage example(s):

     Color red deltaFrom:(Color blue)
     Color red deltaFrom:(Color yellow)
     Color red deltaFrom:(Color red:50)

deltaFromRed: r green: g blue: b

return the distance of the receiver from some color specified
by r/g/b values

deltaFromScaledRed: r scaledGreen: g scaledBlue: b

return the distance of the receiver from some color specified
by r/g/b values

errorFrom: aColor

return some value which can be used to compare colors.
The following simply returns the vector distance of the r/g/b vectors.
This may not be a very good idea; probably, we should honor the
fact that the hue difference should have more weight than saturation and/or light

grayByte

return the grey intensity in [0..255]

Usage example(s):

     Color black grayByte -> 0.0
     Color white grayByte -> 1.0
     Color red grayByte   -> 0.3
     Color green grayByte -> 0.6
     Color blue grayByte  -> 0.1

grayIntensity

return the grey intensity in percent [0..100] (US version ;-)

Usage example(s):

     Color red brightness
     Color red grayIntensity

greyIntensity

marked as obsolete by exept MBP at 20-09-2021

** This is an obsolete interface - do not use it (it may vanish in future versions) **

isBlack

Am I the black color

Usage example(s):

     Color blue isBlack  => false
     Color black isBlack => true

isBlueGreen

Am I considered BlueGreen ?

Usage example(s):

     Color blue isBlueGreen
     (Color blue blendWith:Color green) isBlueGreen

isBright

Am I considered a Bright color ?

Usage example(s):

     Color blue isBright
     Color yellow isBright
     Color white isBright
     Color black isBright

isBrown

Am I considered Brown ?

Usage example(s):

     Color blue isBrown
     Color yellow isBrown
     Color yellow darkened darkened isBrown
     Color brown isBrown
     Color black isBrown

isDark

Am I considered a Dark color ?

Usage example(s):

     Color blue isDark
     Color yellow isDark
     Color yellow darkened darkened isDark
     Color brown isDark
     Color black isDark

isDithered

return true, if this is a dithered Color.
Only makes sense if the receiver is a device color.

isGray

same as isGrayColor - for ST80 compatibility.

Usage example(s):

     (Color grey:50) isGray
     (Color red) isGray

isGrayColor

return true, if this color is a gray one (US version ;-) -
i.e. red = green = blue

Usage example(s):

     (Color grey:50) isGrayColor
     (Color red) isGrayColor

isGrayish

Am I considered almost Gray ?

Usage example(s):

     Color blue isGrayish
     Color yellow isGrayish
     Color yellow darkened darkened isGrayish
     Color brown isGrayish
     Color black isGrayish
     Color white isGrayish
     Color grey isGrayish

isGreyColor

marked as obsolete by exept MBP at 20-09-2021

** This is an obsolete interface - do not use it (it may vanish in future versions) **

isOnDevice: aGraphicsDevice

return true if i am allocated on aGraphicsDevice

isOpaque

return true, if I represent an opaque color

isOrange

Am I considered Orange ?

Usage example(s):

     Color blue isOrange
     Color yellow isOrange
     Color yellow darkened isOrange
     (Color yellow blendWith:Color red) isOrange
     Color orange isOrange
     Color red isOrange
     Color white isOrange
     Color grey isOrange

isPseudoColor

for special uses only:
colors which ONLY hold alpha values or
colorIDs (for example, for bit-blt operaions)
are called 'pseudo colors'

isSaturated

Am I considered to be a Saturated color ?

isTranslucent

return true, if I represent a translucent color;
that is: not completely opaque

isTranslucentColor

return true, if I represent a translucent color, but not transparent

isTransparent

return true, if I represent a completely transparent color

testing

isColor: return true if the receiver is a Color.

Private classes:

    DeviceColorHandle

ST/X 7.7.0.0; WebServer 1.702 at 20f6060372b9.unknown:8081; Mon, 18 Nov 2024 04:18:54 GMT