basis/ui/render/render-docs.factor

   1 USING: ui.gadgets ui.gestures help.markup help.syntax
   2 kernel classes strings opengl opengl.gl models
   3 math.geometry.rect math colors ;
   4 IN: ui.render
   5
   6 HELP: gadget
   7 { $class-description "An object which displays itself on the screen and acts on user input gestures. Gadgets have the following slots:"
   8     { $list
   9         { { $snippet "pref-dim" } " - a cached value for " { $link pref-dim } "; do not read or write this slot directly." }
  10         { { $snippet "parent" } " - the gadget containing this one, or " { $link f } " if this gadget is not part of the visible gadget hierarchy." }
  11         { { $snippet "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 } "." }
  12         { { $snippet "orientation" } " - an orientation specifier. This slot is used by layout gadgets." }
  13         { { $snippet "layout-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." }
  14         { { $snippet "visible?" } " - a boolean indicating if the gadget should display and receive user input." }
  15         { { $snippet "root?" } " - if set to " { $link t } ", layout changes in this gadget will not propagate to the gadget's parent." }
  16         { { $snippet "clipped?" } " - a boolean indicating if clipping will be enabled when drawing this gadget's children." }
  17         { { $snippet "interior" } " - an object whose class implements the " { $link draw-interior } " generic word." }
  18         { { $snippet "boundary" } " - an object whose class implements the " { $link draw-boundary } " generic word." }
  19         { { $snippet "model" } " - a " { $link model } " or " { $link f } "; see " { $link "ui-control-impl" } }
  20     }
  21 "Gadgets subclass the " { $link rect } " class, and thus all instances have " { $snippet "loc" } " and " { $snippet "dim" } " instances holding their location and dimensions." }
  22 { $notes
  23 "Other classes may inherit from " { $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 } "." } ;
  24
  25 HELP: clip
  26 { $var-description "The current clipping rectangle." } ;
  27
  28 HELP: draw-gadget*
  29 { $values { "gadget" gadget } }
  30 { $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." }
  31 { $notes "This word should not be called directly. To force a gadget to redraw, call " { $link relayout-1 } "." } ;
  32
  33 HELP: draw-interior
  34 { $values { "interior" object } { "gadget" gadget } }
  35 { $contract "Draws the interior of a gadget by making OpenGL calls. The " { $snippet "interior" } " slot may be set to objects implementing this generic word." } ;
  36
  37 HELP: draw-boundary
  38 { $values { "boundary" object } { "gadget" gadget } }
  39 { $contract "Draws the boundary of a gadget by making OpenGL calls. The " { $snippet "boundary" } " slot may be set to objects implementing this generic word." } ;
  40
  41 HELP: solid
  42 { $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 " { $snippet "color" } " slot stores an instance of " { $link color } "." }
  43 { $notes "See " { $link "colors" } "." } ;
  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 " { $snippet "colors" } " slot stores a sequence of " { $link color } " instances, and the gradient is drawn in the direction given by the " { $snippet "orientation" } " slot of the gadget." }
  47 { $notes "See " { $link "colors" } "." } ;
  48
  49 HELP: polygon
  50 { $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:"
  51     { $list
  52         { { $snippet "color" } " - a " { $link color } }
  53         { { $snippet "points" } " - a sequence of points" }
  54     }
  55 } ;
  56
  57 HELP: <polygon>
  58 { $values { "color" color } { "points" "a sequence of points" } { "polygon" polygon } }
  59 { $description "Creates a new instance of " { $link polygon } "." } ;
  60
  61 HELP: <polygon-gadget>
  62 { $values { "color" color } { "points" "a sequence of points" } { "gadget" "a new " { $link gadget } } }
  63 { $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." } ;
  64
  65 ARTICLE: "gadgets-polygons" "Polygon gadgets"
  66 "A polygon gadget renders a simple shaded polygon."
  67 { $subsection <polygon-gadget> }
  68 "Some pre-made polygons:"
  69 { $subsection arrow-up }
  70 { $subsection arrow-right }
  71 { $subsection arrow-down }
  72 { $subsection arrow-left }
  73 { $subsection close-box }
  74 "Polygon gadgets are rendered by the " { $link polygon } " pen protocol implementation." ;
  75
  76 ARTICLE: "ui-paint" "Customizing gadget appearance"
  77 "The UI carries out the following steps when drawing a gadget:"
  78 { $list
  79     { "The " { $link draw-interior } " generic word is called on the value of the " { $snippet "interior" } " slot." }
  80     { "The " { $link draw-gadget* } " generic word is called on the gadget." }
  81     { "The gadget's visible children are drawn, determined by calling " { $link visible-children } " on the gadget." }
  82     { "The " { $link draw-boundary } " generic word is called on the value of the " { $snippet "boundary" } " slot." }
  83 }
  84 "Now, each one of these steps will be covered in detail."
  85 { $subsection "ui-pen-protocol" }
  86 { $subsection "ui-paint-custom" } ;
  87
  88 ARTICLE: "ui-pen-protocol" "UI pen protocol"
  89 "The " { $snippet "interior" } " and " { $snippet "boundary" } " slots of a gadget facilitate easy factoring and sharing of drawing logic. Objects stored in these slots must implement the pen protocol:"
  90 { $subsection draw-interior }
  91 { $subsection draw-boundary }
  92 "The default value of these slots is the " { $link f } " singleton, which implements the above protocol by doing nothing."
  93 $nl
  94 "Some other pre-defined implementations:"
  95 { $subsection solid }
  96 { $subsection gradient }
  97 { $subsection polygon }
  98 "Custom implementations must follow the guidelines set forth in " { $link "ui-paint-custom" } "." ;
  99
 100 ARTICLE: "ui-paint-coord" "The UI co-ordinate system"
 101 "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:"
 102 { $subsection origin }
 103 "Custom drawing implementations can translate co-ordinates manually, or save and restore the " { $link GL_MODELVIEW } " matrix using a word such as " { $link with-translation } "."
 104 $nl
 105 "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 " { $slot "clipped?" } " slot to " { $link t } " in the gadget's constructor." ;
 106
 107 ABOUT: "ui-paint"