basis/colors/colors-docs.factor

   1 USING: accessors help.markup help.syntax strings ;
   2 IN: colors
   3
   4 HELP: color
   5 { $class-description "The class of colors. Implementations include " { $link rgba } ", " { $vocab-link "colors.gray" } " and " { $vocab-link "colors.hsv" } "." } ;
   6
   7 HELP: rgba
   8 { $class-description "The class of colors with red, green, blue and alpha channel components. The slots store color components, which are real numbers in the range 0 to 1, inclusive." } ;
   9
  10 HELP: >rgba
  11 { $values { "color" color } { "rgba" rgba } }
  12 { $contract "Converts a color to an RGBA color." } ;
  13
  14 HELP: named-color
  15 { $values { "name" string } { "color" color } }
  16 { $description "Outputs a named color from the color database." }
  17 { $notes "In most cases, " { $link POSTPONE: COLOR: } " should be used instead." }
  18 { $errors "Throws an error if the color is not listed in " { $snippet "rgb.txt" } ", " { $snippet "factor-colors.txt" } " or " { $snippet "solarized-colors.txt" } "." } ;
  19
  20 HELP: named-colors
  21 { $values { "keys" "a sequence of strings" } }
  22 { $description "Outputs a sequence of all colors in the " { $snippet "rgb.txt" } " database." } ;
  23
  24 HELP: parse-color
  25 { $values { "str" string } { "color" color } }
  26 { $description "Parses a string as a named value or as a hexadecimal value." }
  27 { $examples
  28     { $example
  29         "USING: colors prettyprint ;"
  30         "COLOR: sky-blue ."
  31         "COLOR: sky-blue"
  32     }
  33     { $example
  34         "USING: colors prettyprint ;"
  35         "COLOR: #336699 ."
  36         "COLOR: #336699"
  37     }
  38 } ;
  39
  40 HELP: COLOR:
  41 { $syntax "COLOR: string" }
  42 { $description "Parses as a " { $link color } " object using " { $link parse-color } "." }
  43 { $errors "Throws an error if the color is not able to be parsed." }
  44 { $examples
  45   { $code
  46     "USING: colors io.styles ;"
  47     "\"Hello!\" { { foreground COLOR: cyan } } format nl"
  48   }
  49 } ;
  50
  51 ARTICLE: "colors.protocol" "Color protocol"
  52 "Abstract superclass for colors:"
  53 { $subsections color }
  54 "All color objects are required to implement a method on the " { $link >rgba } " generic word."
  55 $nl
  56 "Optionally, they can provide methods on the accessors " { $link red>> } ", " { $link green>> } ", " { $link blue>> } " and " { $link alpha>> } ", either by defining slots with the appropriate names, or with methods which calculate the color component values. The accessors should return color components which are real numbers in the range between 0 and 1."
  57 $nl
  58 "Overriding the accessors is purely an optimization, since the default implementations call " { $link >rgba } " and then extract the appropriate component of the result." ;
  59
  60 ARTICLE: "colors.constants" "Standard color database"
  61 "The " { $vocab-link "colors" } " vocabulary bundles the X11 " { $snippet "rgb.txt" } " database and Factor's " { $snippet "factor-colors.txt" } " theme database to provide words for looking up color values by name."
  62 { $subsections
  63     named-color
  64     named-colors
  65     parse-color
  66     POSTPONE: COLOR:
  67 } ;
  68
  69 ARTICLE: "colors" "Colors"
  70 "The " { $vocab-link "colors" } " vocabulary defines a protocol for colors, with a concrete implementation for RGBA colors. This vocabulary is used by " { $vocab-link "io.styles" } ", " { $vocab-link "ui" } " and other vocabularies, but it is independent of them."
  71 $nl
  72 "RGBA colors with floating point components in the range " { $snippet "[0,1]" } ":"
  73 { $subsections
  74     rgba
  75     <rgba>
  76 }
  77 "Converting a color to RGBA:"
  78 { $subsections >rgba }
  79 "Extracting RGBA components of colors:"
  80 { $subsections >rgba-components }
  81 "Further topics:"
  82 { $subsections
  83     "colors.protocol"
  84     "colors.constants"
  85 }
  86 "Color implementations:"
  87 { $vocab-subsection "CIE 1931 XYZ colors" "colors.xyz" }
  88 { $vocab-subsection "CIE 1931 xyY colors" "colors.xyy" }
  89 { $vocab-subsection "CIE 1976 LAB colors" "colors.lab" }
  90 { $vocab-subsection "CIE 1976 LUV colors" "colors.luv" }
  91 { $vocab-subsection "CMYK colors" "colors.cmyk" }
  92 { $vocab-subsection "Grayscale colors" "colors.gray" }
  93 { $vocab-subsection "HSL colors" "colors.hsl" }
  94 { $vocab-subsection "HSV colors" "colors.hsv" }
  95 { $vocab-subsection "RYB colors" "colors.ryb" }
  96 { $vocab-subsection "YIQ colors" "colors.yiq" }
  97 { $vocab-subsection "YUV colors" "colors.yuv" } ;
  98
  99 ABOUT: "colors"