basis/ui/render/render-docs.factor

   1 USING: help.markup help.syntax kernel math.rectangles models
   2 opengl.gl ui.gadgets ui.gadgets.worlds ui.gestures ui.pens ;
   3 IN: ui.render
   4
   5 HELP: clip
   6 { $var-description "The current clipping rectangle." } ;
   7
   8 HELP: draw-gadget*
   9 { $values { "gadget" gadget } }
  10 { $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." }
  11 { $notes "This word should not be called directly. To force a gadget to redraw, call " { $link relayout-1 } "." } ;
  12
  13 HELP: gadget
  14 { $class-description "An object which displays itself on the screen and acts on user input gestures. Gadgets have the following slots:"
  15     { $slots
  16         { "pref-dim" { "a cached value for " { $link pref-dim } "; do not read or write this slot directly." } }
  17         { "parent" { "the gadget containing this one, or " { $link f } " if this gadget is not part of the visible gadget hierarchy." } }
  18         { "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 } "." } }
  19         { "graft-state" { "a pair of " { $link boolean } " values that represent the current graft state of the gadget and what its next state will become." } }
  20         { "orientation" "an orientation specifier. This slot is used by layout gadgets." }
  21         { "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." } }
  22         { "visible?" "a boolean indicating if the gadget should display and receive user input." }
  23         { "root?" { "if set to " { $link t } ", layout changes in this gadget will not propagate to the gadget's parent." } }
  24         { "clipped?" "a boolean indicating if clipping will be enabled when drawing this gadget's children." }
  25         { "interior" { "an implementation of the " { $link "ui-pen-protocol" } } }
  26         { "boundary" { "an implementation of the " { $link "ui-pen-protocol" } } }
  27         {  "model" { "a " { $link model } " or " { $link f } "; see " { $link "ui-control-impl" } } }
  28     }
  29 "Gadgets subclass the " { $link rect } " class, and thus all instances have " { $slot "loc" } " and " { $slot "dim" } " instances holding their location and dimensions." }
  30 { $notes
  31 "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 } "." } ;
  32
  33 HELP: gl-draw-init
  34 { $values { "world" world } }
  35 { $description "Does some OpenGL setup that is required each time the world is to be redrawn." } ;
  36
  37 ARTICLE: "ui-paint" "Customizing gadget appearance"
  38 "The UI carries out the following steps when drawing a gadget:"
  39 { $list
  40     { "The " { $link draw-interior } " generic word is called on the value of the " { $slot "interior" } " slot." }
  41     { "The " { $link draw-gadget* } " generic word is called on the gadget." }
  42     { "The gadget's visible children are drawn, determined by calling " { $link visible-children } " on the gadget." }
  43     { "The " { $link draw-boundary } " generic word is called on the value of the " { $slot "boundary" } " slot." }
  44 }
  45 "Now, each one of these steps will be covered in detail."
  46 { $subsections
  47     "ui-pen-protocol"
  48     "ui-paint-custom"
  49 } ;
  50
  51 ARTICLE: "ui-paint-coord" "The UI co-ordinate system"
  52 "The UI uses a co-ordinate system where the y axis is oriented down. The OpenGL " { $link GL_MODELVIEW } " matrix is saved or restored when rendering a gadget, and the origin is translated to the gadget's origin within the window. The current origin is stored in a variable:"
  53 { $subsections origin }
  54 "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." ;
  55
  56 ABOUT: "ui-paint"