basis/ui/freetype/freetype-docs.factor

   1 USING: help.syntax help.markup strings kernel alien opengl
   2 quotations ui.render io.styles freetype ;
   3 IN: ui.freetype
   4
   5 HELP: freetype
   6 { $values { "alien" alien } }
   7 { $description "Outputs a native handle used by the FreeType library, initializing FreeType first if necessary." } ;
   8
   9 HELP: open-fonts
  10 { $var-description "Global variable. Hashtable mapping font descriptors to " { $link font } " instances." } ;
  11
  12 { font open-fonts open-font char-width string-width text-dim draw-string draw-text } related-words
  13
  14 HELP: init-freetype
  15 { $description "Initializes the FreeType library." }
  16 { $notes "Do not call this word if you are using the UI." } ;
  17
  18 HELP: font
  19
  20 { $class-description
  21
  22 "A font which has been loaded by FreeType. Font instances have the following slots:"
  23
  24 {
  25   $list
  26   {
  27     { $snippet "ascent"  } ", "
  28     { $snippet "descent" } ", "
  29     { $snippet "height"  } " - metrics."
  30   }
  31
  32   {
  33     { $snippet "handle" }
  34     " - alien pointer to an "
  35     { $snippet "FT_Face" } "."
  36   }
  37
  38   {
  39     { $snippet "widths" }
  40     " - sequence of character widths. Use "
  41     { $snippet "width" }
  42     " and "
  43     { $snippet "width" }
  44     " to compute string widths instead of reading this sequence directly."
  45   }
  46 }
  47
  48 } ;
  49
  50 HELP: close-freetype
  51 { $description "Closes the FreeType library." }
  52 { $notes "Do not call this word if you are using the UI." } ;
  53
  54 HELP: open-face
  55 { $values { "font" string } { "style" "one of " { $link plain } ", " { $link bold } ", " { $link italic } " or " { $link bold-italic } } { "face" "alien pointer to an " { $snippet "FT_Face" } } }
  56 { $description "Loads a TrueType font with the requested logical font name and style." }
  57 { $notes "This is a low-level word. Call " { $link open-font } " instead." } ;
  58
  59 HELP: render-glyph
  60 { $values  { "font" font } { "char" "a non-negative integer" } { "bitmap" alien } }
  61 { $description "Renders a character and outputs a pointer to the bitmap." } ;
  62
  63 HELP: <char-sprite>
  64 { $values { "open-font" font } { "char" "a non-negative integer" } { "sprite" sprite } }
  65 { $description "Renders a character to an OpenGL texture and records a display list which draws a quad with this texture. This word allocates native resources which must be freed by " { $link free-sprites } "." } ;
  66
  67 HELP: (draw-string)
  68 { $values { "open-font" font } { "sprites" "a vector of " { $link sprite } " instances" } { "string" string } { "loc" "a pair of integers" } }
  69 { $description "Draws a line of text." }
  70 { $notes "This is a low-level word, UI code should use " { $link draw-string } " or " { $link draw-text } " instead." }
  71 { $side-effects "sprites" } ;
  72
  73 HELP: run-char-widths
  74 { $values { "open-font" font } { "string" string } { "widths" "a sequence of integers" } }
  75 { $description "Outputs a sequence of x co-ordinates of the midpoint of each character in the string." }
  76 { $notes "This word is used to convert x offsets to document locations, for example when the user moves the caret by clicking the mouse." } ;