eXept Software AG Logo

Smalltalk/X Webserver

Documentation of class 'Color':

Home

Documentation
www.exept.de
Everywhere
for:
[back]

Class: Color


Inheritance:

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

Package:
stx:libview
Category:
Graphics-Support
Version:
rev: 1.277 date: 2018/02/04 23:40:05
user: cg
file: Color.st directory: libview
module: stx stc-classLibrary: libview
Author:
Claus Gittinger

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.

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 systems supports true colors.
It is arguably, if that stuff should remain here, or if we should simply give up support
for old VGA-like displays 
(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 devices depth. The plain colors needed by the ditherForm are found in its
colormap (as usual for bitmaps).

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).


Related information:

    DeviceWorkstation
    GraphicsContext
    DeviceDrawable
    Form
    Image
    Colormap
    Font
    Cursor

Class protocol:

Compatibility-Squeak
o  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

o  fromRgbTriplet: aTriple

o  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.

o  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

o  paleBlue

o  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.
usage example(s):
     self pixelScreenForDepth: depth

o  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)

o  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

o  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

o  showColors: colorList
Display the given collection of colors across the top of the Display.

o  wheel: thisMany
Return a collection of thisMany colors evenly spaced around the color wheel.
usage example(s):
Color showColors: (Color wheel: 12)

o  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
o  colorAllocationFailSignal
return the signal raised when a color allocation failed.

o  colorErrorSignal
return the parent signal of all color error signals.

o  invalidColorNameSignal
return the signal raised when an invalid color name is encountered

accessing
o  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) **

o  allocatedColorsOnDevice: aDevice
return a collection of colors which have already been allocated
on aDevice.
usage example(s):
     Color allocatedColorsOnDevice:Display

color space conversions
o  withHLSFromRed: r green: g blue: b do: aBlock
compute hls form rgb, evaluate aBlock with h,l and s as arguments.
r,g,b in 0..100
h in 0..360; l in 0..100; s in 0..100

o  withHLSFromScaledRed: r scaledGreen: g scaledBlue: b do: aBlock
compute hls form rgb, evaluate aBlock with h,l and s as arguments

o  withRGBFromHue: h light: l saturation: s do: aBlock
compute rgb form hls, evaluate aBlock with r,g and b as arguments
r,g,b in 0..100
h in 0..360; l in 0..100; s in 0..100

constant colors
o  black
return the black color
usage example(s):
     Color black inspect

o  blue
return the blue color
usage example(s):
     Color blue inspect

o  brown
Color brown

o  cyan
return the cyan color - ST-80 compatibility
usage example(s):
     Color cyan inspect

o  cyan: cyan
return a cyan color;
the argument cyan is interpreted as percent (0..100)

o  darkGray
return the dark grey color (English version ;-)
usage example(s):
     Color darkGray inspect

o  darkGrey
return the darkGrey color (US version ;-)
usage example(s):
     Color darkGrey inspect

o  gray
return a medium grey color (US version ;-)
usage example(s):
     Color gray inspect

o  gray: gray
return a gray color (US version).
The argument, gray is interpreted as percent (0..100).
usage example(s):
     Color gray:25

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

o  green
return green
usage example(s):
     Color green inspect

o  greenCaringForColorBlindness
return the color to use for a darkened green (showing text in that color),
possibly using anther color if the settings specifies color blindness
usage example(s):
     self greenCaringForColorBlindness

o  grey
return the grey color (English version ;-)
usage example(s):
     Color grey inspect

o  grey: grey
return a grey color (English version).
The argument, grey is interpreted as percent (0..100).
usage example(s):
     Color grey:25
     Color grey:12.5

o  greyByte: greyByte
return a grey color (English version).
The argument, grey is interpreted as byte-value (0..255).
usage example(s):
     Color greyByte:127

o  lightBlue
return a light blue color
usage example(s):
     Color lightBlue inspect

o  lightBrown
Color lightBrown

o  lightGray
return the lightGrey color (US version ;-)
usage example(s):
     Color lightGray inspect

o  lightGreen
return a light green color
usage example(s):
     Color lightGreen inspect

o  lightGrey
return the lightGrey color (English version ;-)
usage example(s):
     Color lightGrey inspect

o  lightRed
return a light red color
usage example(s):
     Color lightRed inspect

o  lightYellow

o  magenta
return the magenta color - ST-80 compatibility
usage example(s):
     Color magenta inspect

o  magenta: magenta
return a magenta color;
the argument magenta is interpreted as percent (0..100)

o  mediumGray
return medium-grey color (US version ;-)
usage example(s):
     Color mediumGray inspect

o  mediumGrey
return medium-grey color (English version ;-)
usage example(s):
     Color mediumGrey inspect

o  orange
return the orange color - ST-80 compatibility
usage example(s):
     Color orange inspect

o  orange: orange
return a orange color;
the argument orange is interpreted as percent (0..100)

o  pink
return the pink color - ST-80 compatibility

o  red
return the red color
usage example(s):
     Color red inspect

o  redCaringForColorBlindness
return the color to use for green,
possibly using anther color if the settings specifies color blindness

o  transparent
return the transparent-color
usage example(s):
     self transparent

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

o  veryDarkGrey
return a very dark-grey color (English version ;-)

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

o  veryLightGrey
return a very light-grey color (English version ;-)

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

o  white
return the white-color
usage example(s):
     Color white inspect

o  yellow
return the yellow color - ST-80 compatibility
usage example(s):
     Color yellow inspect

o  yellow: yellow
return a yellow color;
the argument yellow is interpreted as percent (0..100)

initialization
o  initialize
setup tracker of known colors and initialize classvars with
heavily used colors
usage example(s):
     Color initialize

o  initializeStandardColorNames
setup standard colors
usage example(s):
     Color initializeStandardColorNames

o  update: something with: aParameter from: changedObject
handle image restarts and flush any device resource handles

instance creation
o  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)

o  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)

o  blue: blue
return a color from blue value;
the argument green is interpreted as percent (0..100)
usage example(s):
     (Color blue:50) inspect

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

o  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.

o  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

o  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

o  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

o  dithered: 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)

o  fromUser
let user point on a screen pixel.
Return an instance for that pixels color
usage example(s):
     Color fromUser

o  fromUserWithFeedBack: feedbackBlockOrNil
let user point on a screen pixel.
Return an instance for that pixels color
usage example(s):
     Color fromUserWithFeedBack:nil

o  green: green
return a color from green value;
the argument green is interpreted as percent (0..100)
usage example(s):
     (Color green:50) inspect

o  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'

o  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'

o  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

o  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

o  name: colorName
Return a named color (either exact or dithered).
Report an error, if aString is not a valid color name.

We hereby only guarantee that the 8 basic colors are supported
on every device (X uses the Xcolor database, so it supports more
names - other devices use a builtIn name table containing only the
common names)
- use with special names (such as 'mediumGoldenRod' is not recommended).
Better use: #name:ifIllegal: and provide a fallBack.
usage example(s):
     Color name:'brown'
     Color name:'snow'
     Color name:'foo'

o  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]

o  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)

o  red: red
return a color from red value;
the argument r is interpreted as percent (0..100)
usage example(s):
     (Color red:50) inspect

o  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

o  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

o  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

o  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)

o  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)

o  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)

o  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

o  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

o  scaledGray: aGrayValue
return a gray color with a scaled gray value (0..MaxValue)

o  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)

o  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)

obsolete
o  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) **

o  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) **

o  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
o  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 :-)

o  existingColorRed: r green: g blue: b on: aDevice
return a device color on aDevice with rgb values
if there is one, nil otherwise.

o  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
o  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.

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

o  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].]

o  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

o  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.

o  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
o  constantNames
return names known as instance creation messages

o  scalingValue
ST-80 compatibility

special instance creation
o  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).

o  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)

o  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).

o  nearestColorScaledRed: r scaledGreen: g scaledBlue: 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.

o  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
o  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.

o  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)

o  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.

o  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

o  flushDeviceColors
unassign all colors from their device

o  flushDeviceColorsFor: aDevice

o  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

o  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

o  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

o  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

o  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

o  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

o  getColorsRed: nRed green: nGreen blue: nBlue on: aDevice
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 on:Display

o  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

o  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).

o  grayColorVector: nGray
Color getGrayColors:16 on:Display

o  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

o  vgaColors


Instance protocol:

Compatibility-ST80
o  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

o  asHiliteColor
same as lightened - for ST-80 compatibility

o  asShadowColor
same as darkened - for ST-80 compatibility

Compatibility-Squeak
o  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)

o  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.

o  colorForInsets
Squeak compatibility - dummy

o  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) muchDarker

o  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)
     (Color red) lighter
     (Color red) muchLighter
     (Color red) veryMuchLighter

o  muchDarker
Squeak compatibility:
return a new color, which is much darker than the receiver
usage example(s):
     (Color red) darker
     (Color red) muchDarker

o  muchLighter
Squeak compatibility:
return a new color, which is much lighter than the receiver
usage example(s):
     (Color red) lighter
     (Color red) mixed:0.833 with:Color white
     (Color red) muchLighter
     (Color red) veryMuchLighter

o  newTileMorphRepresentative
( an extension from the stx:libcompat package )
Squeak compatibility - dummy

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

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

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

o  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)

o  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

o  veryMuchLighter
Squeak compatibility:
return a new color, which is very much lighter than the receiver
usage example(s):
     (Color red) lighter
     (Color red) muchLighter
     (Color red) veryMuchLighter

o  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
o  alpha
return the alpha value (0..1),
where 0 is completely transparent and 1 is completely opaque

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

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

o  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

o  colorId
return the device-dependent color-id

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

o  device
return the device I am associated to

o  deviceBlue
return the actual value of the blue component in percent.

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

o  deviceRed
return the actual value of the red component in percent.
usage example(s):
     (Color yellow on:Display) deviceRedValue
     (Color yellow on:aPrinterPage) deviceRedValue

o  ditherForm
return the form to dither the color

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

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

o  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

o  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
     Color yellow hue

o  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

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

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

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

o  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&gt;&gt;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).

o  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

o  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

o  rgbValue
return the rgb byteValues packed into a 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

o  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

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

o  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

o  scaledGray
return the grey intensity scaled to 0..MaxValue
usage example(s):
     Color blue scaledGray
     Color black scaledGray
     Color white scaledGray
     Color grey scaledGray

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

o  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

o  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&gt;&gt;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).

o  writable
return true, if this is a writable colorcell

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

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

o  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)

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

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

o  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)

o  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
o  postCopy
redefined to clear out any device handles in the copy

o  skipInstvarIndexInDeepCopy: index
skip device

getting a device color
o  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.

o  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.

o  nearestIn: aColorMap
return the nearest color in a colorMap

o  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

o  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) **

o  onDevice: aDevice
create a new Color representing the same color as
myself on aDevice; if one already exists, return the one

inspecting
o  inspectorExtraAttributes
( an extension from the stx:libtool package )
extra (pseudo instvar) entries to be shown in an inspector.

o  inspectorValueStringInListFor: anInspector
( an extension from the stx:libtool package )
returns a string to be shown in the inspector's list

instance creation
o  alpha: alphaValue
return a new color with the same color, but different alpha as the receiver.
The alpha arguments range is 0..1 (0=completely transparent; 1=completely opaque)
usage example(s):
     (Color red alpha:0.5) alpha
     Color red alpha

o  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)

o  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

o  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 red) contrastingColorFor:Color grey
     (Color blue) contrastingColorFor:Color black

o  darkened
return a new color, which is slightly darker than the receiver
usage example(s):
     (Color red) darkened
     (Color red) darkened darkened

o  lightened
return a new color, which is slightly lighter than the receiver
usage example(s):
     (Color red) lightened
     (Color red) lightened lightened

o  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.
usage example(s):
     (Color red) mixed:1 with:(Color 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)
     (Color red) mixed:0.25 with:(Color yellow)
     (Color red) mixed:0 with:(Color yellow)

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

o  slightlyDarkened
return a new color, which is a bit darker than the receiver
usage example(s):
     (Color green) inspect
     (Color green) darkened inspect
     (Color green) slightlyDarkened inspect

o  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
o  executor
redefined, since for finalization only device and colorIndex
are needed - thus a faster copy is possible here

o  releaseFromDevice
I am no longer available on the device

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

misc ui support
o  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
o  elementDescriptorFor: aspect
support for persistency:
answer the elements to be made persistent with an ObjectCoder

printing & storing
o  hex

o  hexPrintOn: aStream
print a base16 representation on aStream as rrggbb

o  hexPrintString
return a hex-printString as rrggbb
usage example(s):
     Color red hexPrintString
     Color green hexPrintString
     Color blue hexPrintString
     Color yellow hexPrintString

o  htmlPrintString
return a hex-printString for html as #rrggbb;
usage example(s):
     Color red htmlPrintString
     Color green htmlPrintString
     Color blue htmlPrintString
     Color yellow htmlPrintString

o  printOn: aStream
append a string representing of the receiver
to the argument, aStream

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

private
o  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

o  setColorId: anId
private: set the deviceId

o  setDevice: aDevice colorId: aNumber
private:set device and colorId

o  setDevice: aDevice colorId: aNumber writable: wBool
private:set device, colorId and writable flag

o  setDitherForm: aForm
private: set the ditherForm

o  setScaledRed: r scaledGreen: g scaledBlue: b
private: set the components

o  setScaledRed: r scaledGreen: g scaledBlue: b device: aDevice
private: set the components

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

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

o  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

o  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)

o  deltaFromRed: r green: g blue: b
return the distance of the receiver from some color specified
by r/g/b values

o  deltaFromScaledRed: r scaledGreen: g scaledBlue: b
return the distance of the receiver from some color specified
by r/g/b values

o  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

o  grayIntensity
return the grey intensity in percent [0..100] (US version ;-)
usage example(s):
     Color red brightness
     Color red grayIntensity

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

o  isColor
return true if the receiver is a Color.

o  isColorObject

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

o  isGray
same as isGrayColor - for ST80 compatibility.
usage example(s):
     (Color grey:50) isGray
     (Color red) isGray

o  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

o  isGreyColor
return true, if this color is a grey one (English version ;-) -
i.e. red = green = blue
usage example(s):
(Color grey:50) isGreyColor
usage example(s):
(Color red) isGreyColor

o  isOnDevice: aGraphicsDevice
return true if i am allocated on aGraphicsDevice

o  isOpaque
return true, if I represent an opaque color

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

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

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

o  isTransparent
return true, if I represent a completely transparent color


Private classes:

    DeviceColorHandle


ST/X 7.1.0.0; WebServer 1.663 at exept.de:8081; Sat, 22 Sep 2018 07:04:31 GMT