extra/ui/gadgets/controls/controls-docs.factor

   1 USING: ui.gadgets help.markup help.syntax models kernel classes
   2 tuples ;
   3 IN: ui.gadgets.controls
   4
   5 HELP: control
   6 { $class-description "A control is a " { $link gadget } " linked to a " { $link model } " stored in the " { $link control-model } " slot. Changes to the model are reflected in the appearance and behavior of the control, and the control may in turn change the value of the model in response to user input."
   7 $nl
   8 "Controls are created by calling " { $link <control> } " and " { $link construct-control } "."
   9 $nl
  10 "Objects may delegate to " { $link control } " instances, in which case the " { $link control-self } " slot must be set to the frontmost object in the delegation chain. This ensures that the correct object receives notification of model changes." } ;
  11
  12 HELP: <control>
  13 { $values { "model" model } { "gadget" gadget } { "quot" "a quotation with stack effect " { $snippet "( value control -- )" } } }
  14 { $description "Creates a new control linked to the given model. The gadget parameter becomes the control's delegate. The quotation is called when the model value changes," }
  15 { $examples
  16     "The following example creates a gadget whose fill color is determined by the value of a model:"
  17     { $code
  18         "USING: ui.gadgets ui.gadgets.panes models ;"
  19         ": set-fill-color >r <solid> r> set-gadget-interior ;"
  20         "{ 1.0 0.0 0.5 1.0 } <model>"
  21         "<gadget> [ set-fill-color ] <control>"
  22         "{ 100 100 } over set-rect-dim"
  23         "gadget."
  24     }
  25     "The " { $vocab-link "color-picker" } " module extends this example into an elaborate color choose."
  26 } ;
  27
  28 { <control> construct-control control-value set-control-value } related-words
  29
  30 HELP: control-value
  31 { $values { "control" control } { "value" object } }
  32 { $description "Outputs the value of the control's model." } ;
  33
  34 HELP: set-control-value
  35 { $values { "value" object } { "control" control } }
  36 { $description "Sets the value of the control's model." } ;
  37
  38 ARTICLE: "ui-control-impl" "Implementing controls"
  39 "A control is a gadget which is linked to an underlying " { $link model } "."
  40 { $subsection control }
  41 "There are two ways to implement a new control. First, an existing gadget can be wrapped in a control:"
  42 { $subsection <control> }
  43 "Second, a new tuple class can be defined, whose instances delegate to controls:"
  44 { $subsection construct-control }
  45 "Some utility words useful in control implementations:"
  46 { $subsection control-model }
  47 { $subsection control-value }
  48 { $subsection set-control-value }
  49 { $see-also "models" } ;
  50
  51 ABOUT: "ui-control-impl"