core/ui/text.facts

   1 IN: gadgets
   2 USING: help freetype strings kernel styles alien opengl ;
   3
   4 HELP: freetype
   5 { $var-description "Global variable. Holds a native handle used by the FreeType library." }
   6 { $see-also with-freetype } ;
   7
   8 HELP: open-fonts
   9 { $var-description "Global variable. Hashtable mapping font descriptors to " { $link font } " instances." }
  10 { $see-also open-font } ;
  11
  12 HELP: init-freetype
  13 { $description "Initializes the FreeType library." }
  14 { $notes "Do not call this word if you are using the UI." } ;
  15
  16 HELP: font
  17 { $class-description "A font which has been loaded by FreeType. Font instances have the following slots:"
  18     { $list
  19         { { $link font-ascent } ", " { $link font-descent } ", " { $link font-height } " - metrics." }
  20         { { $link font-handle } " - alien pointer to an " { $snippet "FT_Face" } "." }
  21         { { $link font-widths } " - sequence of character widths. Use " { $link char-width } " and " { $link string-width } " to compute string widths instead of reading this sequence directly." }
  22     }
  23 }
  24 { $see-also open-font char-width string-width text-dim draw-string draw-text } ;
  25
  26 HELP: close-freetype
  27 { $description "Closes the FreeType library." }
  28 { $notes "Do not call this word if you are using the UI." } ;
  29
  30 HELP: with-freetype
  31 { $values { "quot" quotation } }
  32 { $description "Sets up and tears down FreeType before and after calling the quotation. This word is re-entrant, so the quotation itself can call " { $link with-freetype } "." }
  33 { $notes "Do not call this word if you are using the UI." } ;
  34
  35 HELP: open-face
  36 { $values { "font" string } { "style" "one of " { $link plain } ", " { $link bold } ", " { $link italic } " or " { $link bold-italic } } { "face" "alien pointer to an " { $snippet "FT_Face" } } }
  37 { $description "Loads a TrueType font with the requested logical font name and style." }
  38 { $notes "This is a low-level word. Call " { $link open-font } " instead." } ;
  39
  40 HELP: open-font
  41 { $values { "font" "a font specifier" } { "open-font" font } }
  42 { $description "Loads a TrueType font if it has not already been loaded, otherwise outputs the existing " { $link font } " instance." }
  43 { $errors "Throws an error if the font does not exist." } ;
  44
  45 HELP: render-glyph
  46 { $values  { "font" font } { "char" "a non-negative integer" } { "bitmap" alien } }
  47 { $description "Renders a character and outputs a pointer to the bitmap." } ;
  48
  49 HELP: <char-sprite>
  50 { $values { "font" font } { "char" "a non-negative integer" } { "sprite" sprite } }
  51 { $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 } "." } ;
  52
  53 HELP: (draw-string)
  54 { $values { "open-font" font } { "sprites" "a vector of " { $link sprite } " instances" } { "string" string } { "loc" "a pair of integers" } }
  55 { $description "Draws a line of text." }
  56 { $notes "This is a low-level word, UI code should use " { $link draw-string } " or " { $link draw-text } " instead." }
  57 { $side-effects "sprites" } ;
  58
  59 HELP: string-width
  60 { $values { "open-font" "an instance of " { $link font } } { "string" string } { "w" "a positive integer" } }
  61 { $description "Outputs the width of a string." }
  62 { $see-also open-font text-dim } ;
  63
  64 HELP: text-dim
  65 { $values { "open-font" "an instance of " { $link font } } { "text" "a string or an array of strings" } { "dim" "a pair of integers" } }
  66 { $description "Outputs the dimensions of a piece of text, which is either a single-line string or an array of lines." }
  67 { $see-also open-font string-width } ;
  68
  69 HELP: draw-string
  70 { $values { "font" "a font specifier" } { "string" string } { "loc" "a pair of integers" } }
  71 { $description "Draws a line of text." }
  72 { $see-also open-font draw-text } ;
  73
  74 HELP: draw-text
  75 { $values { "font" "a font specifier" } { "text" "a string or an array of strings" } { "loc" "a pair of integers" } }
  76 { $description "Draws text. Text is either a single-line string or an array of lines." }
  77 { $see-also open-font draw-text } ;