factor/core/ui/text.facts

IN: gadgets
USING: help freetype strings kernel styles alien opengl ;

HELP: freetype
{ $var-description "Global variable. Holds a native handle used by the FreeType library." }
{ $see-also with-freetype } ;

HELP: open-fonts
{ $var-description "Global variable. Hashtable mapping font descriptors to " { $link font } " instances." }
{ $see-also open-font } ;

HELP: init-freetype
{ $description "Initializes the FreeType library." }
{ $notes "Do not call this word if you are using the UI." } ;

HELP: font
{ $class-description "A font which has been loaded by FreeType. Font instances have the following slots:"
    { $list
        { { $link font-ascent } ", " { $link font-descent } ", " { $link font-height } " - metrics." }
        { { $link font-handle } " - alien pointer to an " { $snippet "FT_Face" } "." }
        { { $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." }
    }
}
{ $see-also open-font char-width string-width text-dim draw-string draw-text } ;

HELP: close-freetype
{ $description "Closes the FreeType library." }
{ $notes "Do not call this word if you are using the UI." } ;

HELP: with-freetype
{ $values { "quot" quotation } }
{ $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 } "." }
{ $notes "Do not call this word if you are using the UI." } ;

HELP: open-face
{ $values { "font" string } { "style" "one of " { $link plain } ", " { $link bold } ", " { $link italic } " or " { $link bold-italic } } { "face" "alien pointer to an " { $snippet "FT_Face" } } }
{ $description "Loads a TrueType font with the requested logical font name and style." }
{ $notes "This is a low-level word. Call " { $link open-font } " instead." } ;

HELP: open-font
{ $values { "font" "a font specifier" } { "open-font" font } }
{ $description "Loads a TrueType font if it has not already been loaded, otherwise outputs the existing " { $link font } " instance." }
{ $errors "Throws an error if the font does not exist." } ;

HELP: render-glyph
{ $values  { "font" font } { "char" "a non-negative integer" } { "bitmap" alien } }
{ $description "Renders a character and outputs a pointer to the bitmap." } ;

HELP: <char-sprite>
{ $values { "font" font } { "char" "a non-negative integer" } { "sprite" sprite } }
{ $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 } "." } ;

HELP: (draw-string)
{ $values { "open-font" font } { "sprites" "a vector of " { $link sprite } " instances" } { "string" string } { "loc" "a pair of integers" } }
{ $description "Draws a line of text." }
{ $notes "This is a low-level word, UI code should use " { $link draw-string } " or " { $link draw-text } " instead." }
{ $side-effects "sprites" } ;

HELP: string-width
{ $values { "open-font" "an instance of " { $link font } } { "string" string } { "w" "a positive integer" } }
{ $description "Outputs the width of a string." }
{ $see-also open-font text-dim } ;

HELP: text-dim
{ $values { "open-font" "an instance of " { $link font } } { "text" "a string or an array of strings" } { "dim" "a pair of integers" } }
{ $description "Outputs the dimensions of a piece of text, which is either a single-line string or an array of lines." }
{ $see-also open-font string-width } ;

HELP: draw-string
{ $values { "font" "a font specifier" } { "string" string } { "loc" "a pair of integers" } }
{ $description "Draws a line of text." }
{ $see-also open-font draw-text } ;

HELP: draw-text
{ $values { "font" "a font specifier" } { "text" "a string or an array of strings" } { "loc" "a pair of integers" } }
{ $description "Draws text. Text is either a single-line string or an array of lines." }
{ $see-also open-font draw-text } ;