basis/ui/text/text-docs.factor

   1 IN: ui.text
   2 USING: help.markup help.syntax kernel ui.text.private strings math fonts images ;
   3
   4 HELP: string-width
   5 { $values { "font" font } { "string" string } { "w" "a positive integer" } }
   6 { $contract "Outputs the width of a string." }
   7 { $notes "This is a low-level word; use " { $link text-width } " instead." } ;
   8
   9 HELP: text-width
  10 { $values { "font" font } { "text" "a string or sequence of strings" } { "w" "a positive integer" } }
  11 { $description "Outputs the width of a piece of text." } ;
  12
  13 HELP: string-height
  14 { $values { "font" font } { "string" string } { "h" "a positive integer" } }
  15 { $contract "Outputs the height of a string." }
  16 { $notes "This is a low-level word; use " { $link text-height } " instead." } ;
  17
  18 HELP: text-height
  19 { $values { "font" font } { "text" "a string or sequence of strings" } { "h" "a positive integer" } }
  20 { $description "Outputs the height of a piece of text." } ;
  21
  22 HELP: string-dim
  23 { $values { "font" font } { "string" string } { "dim" "a pair of integers" } }
  24 { $contract "Outputs the dimensions of a string." }
  25 { $notes "This is a low-level word; use " { $link text-dim } " instead." } ;
  26
  27 HELP: text-dim
  28 { $values { "font" font } { "text" "a string or sequence of strings" } { "dim" "a pair of integers" } }
  29 { $description "Outputs the dimensions of a piece of text, which is either a single-line string or an array of lines." } ;
  30
  31 HELP: draw-string
  32 { $values { "font" font } { "string" string } }
  33 { $contract "Draws a line of text." } ;
  34
  35 HELP: draw-text
  36 { $values { "font" font } { "text" "a string or an array of strings" } }
  37 { $description "Draws a piece of text." } ;
  38
  39 HELP: x>offset
  40 { $values { "x" real } { "font" font } { "string" string } { "n" integer } }
  41 { $contract "Outputs the string index closest to the given x co-ordinate." } ;
  42
  43 HELP: offset>x
  44 { $values { "n" integer } { "font" font } { "string" string } { "x" real } }
  45 { $contract "Outputs the x co-ordinate of the character at the given index." } ;
  46
  47 HELP: line-metrics
  48 { $values { "font" font } { "string" string } { "metrics" line-metrics } }
  49 { $contract "Outputs a " { $link metrics } " object with text measurements." } ;
  50
  51 HELP: string>image
  52 { $values { "font" font } { "string" string } { "image" image } { "loc" "a pair of real numbers" } }
  53 { $description "Renders a line of text into an image." } ;
  54
  55 ARTICLE: "text-rendering" "Rendering text"
  56 "The " { $vocab-link "ui.text" } " vocabulary provides a cross-platform interface to the operating system's native font rendering engine. Currently, it uses Core Text on Mac OS X, Uniscribe on Windows and Pango on X11."
  57 { $subsections "fonts" }
  58 "Measuring text:"
  59 { $subsections
  60     text-dim
  61     text-width
  62     text-height
  63     line-metrics
  64 }
  65 "Converting screen locations to string offsets, and vice versa:"
  66 { $subsections
  67     x>offset
  68     offset>x
  69 }
  70 "Rendering text:"
  71 { $subsections draw-text string>image }
  72 "Low-level text protocol for UI backends:"
  73 { $subsections
  74     string-width
  75     string-height
  76     string-dim
  77     draw-string
  78 } ;
  79
  80 ABOUT: "text-rendering"