extra/ui/render/render-docs.factor

   1 USING: ui.gadgets ui.gestures help.markup help.syntax
   2 kernel classes strings opengl.gl ;
   3 IN: ui.render
   4
   5 HELP: gadget
   6 { $class-description "An object which displays itself on the screen and acts on user input gestures. Gadgets have the following slots:"
   7     { $list
   8         { { $link gadget-pref-dim } " - a cached value for " { $link pref-dim } "; do not read or write this slot directly." }
   9         { { $link gadget-parent } " - the gadget containing this one, or " { $link f } " if this gadget is not part of the visible gadget hierarchy." }
  10         { { $link gadget-children } " - a vector of child gadgets. Do not modify this vector directly, instead use " { $link add-gadget } ", " { $link add-gadgets } ", " { $link unparent } " or " { $link clear-gadget } "." }
  11         { { $link gadget-orientation } " - an orientation specifier. This slot is used by layout gadgets." }
  12         { { $link gadget-state } " - stores the layout state of the gadget. Do not read or write this slot directly, instead call " { $link relayout } " and " { $link relayout-1 } " if the gadget needs to be re-laid out." }
  13         { { $link gadget-visible? } " - a boolean indicating if the gadget should display and receive user input." }
  14         { { $link gadget-root? } " - if set to " { $link t } ", layout changes in this gadget will not propagate to the gadget's parent." }
  15         { { $link gadget-clipped? } " - a boolean indicating if clipping will be enabled when drawing this gadget's children." }
  16         { { $link gadget-grafted? } " - if set to " { $link t } ", the gadget is parented in a native window." }
  17         { { $link gadget-interior } " - an object whose class implements the " { $link draw-interior } " generic word." }
  18         { { $link gadget-boundary } " - an object whose class implements the " { $link draw-boundary } " generic word." }
  19     }
  20 "Gadgets delegate to " { $link rect } " instances holding their location and dimensions." }
  21 { $notes
  22 "Other classes may delegate to " { $link gadget } " in order to re-implement generic words such as " { $link draw-gadget* } " and " { $link user-input* } ", or to define gestures with " { $link set-gestures } "." }
  23 { $warning
  24 "When setting a tuple's delegate to be a gadget, " { $link set-gadget-delegate } " should be used instead of " { $link set-delegate } "." } ;
  25
  26 HELP: clip
  27 { $var-description "The current clipping rectangle." } ;
  28
  29 HELP: draw-gadget*
  30 { $values { "gadget" gadget } }
  31 { $contract "Draws the gadget by making OpenGL calls. The top-left corner of the gadget should be drawn at the location stored in the " { $link origin } " variable." }
  32 { $notes "This word should not be called directly. To force a gadget to redraw, call " { $link relayout-1 } "." } ;
  33
  34 HELP: draw-interior
  35 { $values { "interior" object } { "gadget" gadget } }
  36 { $contract "Draws the interior of a gadget by making OpenGL calls. The " { $link gadget-interior } " slot may be set to objects implementing this generic word." } ;
  37
  38 HELP: draw-boundary
  39 { $values { "boundary" object } { "gadget" gadget } }
  40 { $contract "Draws the boundary of a gadget by making OpenGL calls. The " { $link gadget-boundary } " slot may be set to objects implementing this generic word." } ;
  41
  42 HELP: solid
  43 { $class-description "A class implementing the " { $link draw-boundary } " and " { $link draw-interior } " generic words to draw a solid outline or a solid fill, respectively. The " { $link solid-color } " slot stores a color specifier." } ;
  44
  45 HELP: gradient
  46 { $class-description "A class implementing the " { $link draw-interior } " generic word to draw a smoothly shaded transition between colors. The " { $link gradient-colors } " slot stores a sequence of color specifiers and the gradient is drawn in the direction given by the " { $link gadget-orientation } " slot of the gadget." } ;
  47
  48 HELP: polygon
  49 { $class-description "A class implementing the " { $link draw-boundary } " and " { $link draw-interior } " generic words to draw a solid outline or a solid filled polygon, respectively. Instances of " { $link polygon } " have two slots:"
  50     { $list
  51         { { $link polygon-color } " - a color specifier" }
  52         { { $link polygon-points } " - a sequence of points" }
  53     }
  54 } ;
  55
  56 HELP: <polygon>
  57 { $values { "color" "a color specifier" } { "points" "a sequence of points" } }
  58 { $description "Creates a new instance of " { $link polygon } "." } ;
  59
  60 HELP: <polygon-gadget>
  61 { $values { "color" "a color specifier" } { "points" "a sequence of points" } { "gadget" "a new " { $link gadget } } }
  62 { $description "Creates a gadget which is drawn as a solid filled polygon. The gadget's size is the minimum bounding box containing all the points of the polygon." } ;
  63
  64 HELP: open-font
  65 { $values { "font" "a font specifier" } { "open-font" object } }
  66 { $description "Loads a font if it has not already been loaded, otherwise outputs the existing font." }
  67 { $errors "Throws an error if the font does not exist." } ;
  68
  69 HELP: string-width
  70 { $values { "open-font" "a value output by " { $link open-font } } { "string" string } { "w" "a positive integer" } }
  71 { $description "Outputs the width of a string." } ;
  72
  73 HELP: text-dim
  74 { $values { "open-font" "a value output by " { $link open-font } } { "text" "a string or an array of strings" } { "dim" "a pair of integers" } }
  75 { $description "Outputs the dimensions of a piece of text, which is either a single-line string or an array of lines." } ;
  76
  77 HELP: draw-string
  78 { $values { "font" "a font specifier" } { "string" string } { "loc" "a pair of integers" } }
  79 { $description "Draws a line of text." } ;
  80
  81 HELP: draw-text
  82 { $values { "font" "a font specifier" } { "text" "a string or an array of strings" } { "loc" "a pair of integers" } }
  83 { $description "Draws text. Text is either a single-line string or an array of lines." } ;
  84
  85 ARTICLE: "gadgets-polygons" "Polygon gadgets"
  86 "A polygon gadget renders a simple shaded polygon."
  87 { $subsection <polygon-gadget> }
  88 "Some pre-made polygons:"
  89 { $subsection arrow-up }
  90 { $subsection arrow-right }
  91 { $subsection arrow-down }
  92 { $subsection arrow-left }
  93 { $subsection close-box }
  94 "Polygon gadgets are rendered by the " { $link polygon } " pen protocol implementation." ;
  95
  96 ARTICLE: "ui-paint" "Customizing gadget appearance"
  97 "The UI carries out the following steps when drawing a gadget:"
  98 { $list
  99     { "The " { $link draw-interior } " generic word is called on the value of the " { $link gadget-interior } " slot." }
 100     { "The " { $link draw-gadget* } " generic word is called on the gadget." }
 101     { "The gadget's visible children are drawn, determined by calling " { $link visible-children } " on the gadget." }
 102     { "The " { $link draw-boundary } " generic word is called on the value of the " { $link gadget-boundary } " slot." }
 103 }
 104 "Now, each one of these steps will be covered in detail."
 105 { $subsection "ui-pen-protocol" }
 106 { $subsection "ui-paint-custom" } ;
 107
 108 ARTICLE: "ui-pen-protocol" "UI pen protocol"
 109 "The " { $link gadget-interior } " and " { $link gadget-boundary } " slots of a gadget facilitate easy factoring and sharing of drawing logic. Objects stored in these slots must implement the pen protocol:"
 110 { $subsection draw-interior }
 111 { $subsection draw-boundary }
 112 "The default value of these slots is the " { $link f } " singleton, which implements the above protocol by doing nothing."
 113 $nl
 114 "Some other pre-defined implementations:"
 115 { $subsection solid }
 116 { $subsection gradient }
 117 { $subsection polygon }
 118 "Custom implementations must follow the guidelines set forth in " { $link "ui-paint-custom" } "." ;
 119
 120 ARTICLE: "text-rendering" "Rendering text"
 121 "Unlike OpenGL, Factor's FreeType binding only includes the bare essentials, and there is rarely any need to directly call words in the " { $vocab-link "freetype" } " vocabulary directly. Instead, the UI provides high-level wrappers."
 122 $nl
 123 "Font objects are never constructed directly, and instead are obtained by calling a word:"
 124 { $subsection open-font }
 125 "Measuring text:"
 126 { $subsection text-dim }
 127 { $subsection text-height }
 128 { $subsection text-width }
 129 "Rendering text:"
 130 { $subsection draw-string }
 131 { $subsection draw-text } ;
 132
 133 ARTICLE: "ui-paint-custom" "Implementing custom drawing logic"
 134 "The UI uses OpenGL to render gadgets. Custom rendering logic can be plugged in with the " { $link "ui-pen-protocol" } ", or by implementing a generic word:"
 135 { $subsection draw-gadget* }
 136 "Custom drawing code has access to the full OpenGL API in the " { $vocab-link "opengl" } " vocabulary."
 137 $nl
 138 "The UI uses a co-ordinate system where the y axis is oriented down. The OpenGL " { $link GL_MODELVIEW } " matrix is not saved or restored when rendering a gadget. Instead, the origin of the gadget relative to the OpenGL context is stored in a variable:"
 139 { $subsection origin }
 140 "Custom drawing implementations can translate co-ordinates manually, or save and restore the " { $link GL_MODELVIEW } " matrix."
 141 $nl
 142 "OpenGL state must not be altered as a result of drawing a gadget, so any flags which were enabled should be disabled, and vice versa."
 143 $nl
 144 "Gadgets must not draw outside of their bounding box, however clipping is not enforced by default, for performance reasons. This can be changed by setting the " { $link gadget-clipped? } " slot to " { $link t } " in the gadget's constructor."
 145 $nl
 146 "Saving the " { $link GL_MODELVIEW } " matrix and enabling/disabling flags can be done in a clean way using the combinators documented in the following section."
 147 { $subsection "gl-utilities" }
 148 { $subsection "text-rendering" } ;
 149
 150 ABOUT: "ui-paint-custom"