basis/ui/gadgets/gadgets-docs.factor

   1 USING: accessors concurrency.flags help.markup help.syntax kernel
   2 math.rectangles models strings ui.gadgets.private ;
   3 IN: ui.gadgets
   4
   5 HELP: <gadget>
   6 { $values { "gadget" "a new " { $link gadget } } }
   7 { $description "Creates a new gadget." } ;
   8
   9 HELP: children-on
  10 { $values { "rect" rect } { "gadget" gadget } { "seq" "a sequence of gadgets" } }
  11 { $contract "Outputs a sequence of gadgets which potentially intersect a rectangle in the co-ordinate system of the gadget." }
  12 { $notes "This does not have to be an accurate intersection test, and simply returning " { $link children>> } " is a valid implementation. However, an accurate intersection test reduces the amount of work done when drawing this gadget if it is partially clipped and not all children are visible." } ;
  13
  14 HELP: control-value
  15 { $values { "control" gadget } { "value" object } }
  16 { $description "Outputs the value of the control's model." } ;
  17
  18 HELP: gadget-child
  19 { $values { "gadget" gadget } { "child" gadget } }
  20 { $description "Outputs the first child of the gadget. Typically this word is used with gadgets which are known to have only one child." } ;
  21
  22 HELP: notify
  23 { $values { "gadget" gadget } }
  24 { $description "Notifies the gadget that it has a graft message to handle." }
  25 { $see-also graft* ungraft* } ;
  26
  27 HELP: notify-ui-thread
  28 { $description "Notifies the UI thread that there is work to do." }
  29 { $see-also ui-notify-flag } ;
  30
  31 HELP: nth-gadget
  32 { $values { "n" "a non-negative integer" } { "gadget" gadget } { "child" gadget } }
  33 { $description "Outputs the " { $snippet "n" } "th child of the gadget." }
  34 { $errors "Throws an error if " { $snippet "n" } " is negative or greater than or equal to the number of children." } ;
  35
  36 HELP: relative-loc
  37 { $values { "fromgadget" gadget } { "togadget" gadget } { "loc" "a pair of integers" } }
  38 { $description
  39     "Outputs the location of the top-left corner of " { $snippet "togadget" } " relative to the co-ordinate system of " { $snippet "fromgadget" } "."
  40 }
  41 { $errors
  42     "Throws an error if " { $snippet "togadget" } " is not contained in a child of " { $snippet "fromgadget" } "."
  43 } ;
  44
  45 HELP: user-input*
  46 { $values { "str" string } { "gadget" gadget } { "?" boolean } }
  47 { $contract "Handle free-form textual input while the gadget has keyboard focus." } ;
  48
  49 HELP: temp-im-input
  50 { $values { "str" string } { "gadget" gadget } { "?" boolean } }
  51 { $contract "Handle free-form textual input while the gadget has keyboard focus. This is used to display the string being preedited by an input method on the gadget. Input by this word is not include changes in the Undo and Redo actions." } ;
  52
  53 HELP: pick-up
  54 { $values { "point" "a pair of integers" } { "gadget" gadget } { "child/f" { $maybe gadget } } }
  55 { $description "Outputs the child at a point in the gadget's co-ordinate system. This word recursively descends the gadget hierarchy, and so outputs the deepest child." } ;
  56
  57 HELP: max-dims
  58 { $values { "seq" "a sequence of pairs of integers" } { "dim" "a pair of integers" } }
  59 { $description "Outputs the smallest dimensions of a rectangle which can fit all the dimensions in the sequence." } ;
  60
  61 { pref-dims max-dims sum-dims } related-words
  62
  63 HELP: each-child
  64 { $values { "gadget" gadget } { "quot" { $quotation ( child -- ) } } }
  65 { $description "Applies the quotation to each child of the gadget." } ;
  66
  67 HELP: gadget-selection?
  68 { $values { "gadget" gadget } { "?" boolean } }
  69 { $contract "Outputs if the gadget has an active text selection; if so, the selected text can be obtained with a call to " { $link gadget-selection } "." } ;
  70
  71 HELP: gadget-selection
  72 { $values { "gadget" gadget } { "string/f" { $maybe string } } }
  73 { $contract "Outputs the gadget's text selection, or " { $link f } " if nothing is selected." } ;
  74
  75 HELP: relayout
  76 { $values { "gadget" gadget } }
  77 { $description "Relayout and redraw a gadget before the next iteration of the event loop. Unlike " { $link relayout-1 } ", this relayouts all parents up to a gadget having " { $snippet "root?" } " set, so this word should be used when the gadget's dimensions have potentially changed." } ;
  78
  79 HELP: relayout-1
  80 { $values { "gadget" gadget } }
  81 { $description "Relayout and redraw a gadget before the next iteration of the event loop. Unlike " { $link relayout } ", this does not propagate requests up to the parent, and so this word should be used when the gadget's internal layout or appearance has changed, but the dimensions have not." } ;
  82
  83 { relayout relayout-1 } related-words
  84
  85 HELP: pref-dim*
  86 { $values { "gadget" gadget } { "dim" "a pair of integers" } }
  87 { $contract "Outputs the preferred dimensions of the gadget, possibly computing them from the preferred dimensions of the gadget's children." }
  88 { $notes "User code should not call this word directly, instead call " { $link pref-dim } "." } ;
  89
  90 HELP: pref-dim
  91 { $values { "gadget" gadget } { "dim" "a pair of integers" } }
  92 { $description "Outputs the preferred dimensions of the gadget. The value is cached between calls, and invalidated when the gadget needs to be relayout." } ;
  93
  94 HELP: pref-dims
  95 { $values { "gadgets" "a sequence of gadgets" } { "seq" "a sequence of pairs of integers" } }
  96 { $description "Collects the preferred dimensions of every gadget in the sequence into a new sequence." } ;
  97
  98 HELP: layout*
  99 { $values { "gadget" gadget } }
 100 { $contract "Lays out the children of the gadget according to the gadget's policy. The dimensions of the gadget are already set by the parent by the time this word is called." }
 101 { $notes "User code should not call this word directly, instead call " { $link relayout } " and " { $link relayout-1 } "." } ;
 102
 103 HELP: prefer
 104 { $values { "gadget" gadget } }
 105 { $contract "Resizes the gadget to assume its preferred dimensions." } ;
 106
 107 HELP: sum-dims
 108 { $values { "seq" "a sequence of pairs of integers" } { "dim" "a pair of integers" } }
 109 { $description "Sums a sequence of dimensions." } ;
 110
 111 HELP: layout
 112 { $values { "gadget" gadget } }
 113 { $description "Lays out the children of the gadget if the gadget needs to be relayout, and otherwise does nothing." }
 114 { $notes "User code should not call this word directly, instead call " { $link relayout } " and " { $link relayout-1 } "." } ;
 115
 116 { pref-dim pref-dim* layout layout* } related-words
 117
 118 HELP: graft*
 119 { $values { "gadget" gadget } }
 120 { $contract "Called to notify the gadget it has become visible on the screen. This should set up timers and threads, and acquire any resources used by the gadget." } ;
 121
 122 { graft graft* ungraft ungraft* } related-words
 123
 124 HELP: ungraft*
 125 { $values { "gadget" gadget } }
 126 { $contract "Called to notify the gadget it is no longer visible on the screen. This should stop timers and threads, and release any resources used by the gadget." } ;
 127
 128 HELP: graft
 129 { $values { "gadget" gadget } }
 130 { $description "Calls " { $link graft* } " on the gadget and all children." }
 131 { $notes "This word should never be called directly." } ;
 132
 133 HELP: ungraft
 134 { $values { "gadget" gadget } }
 135 { $description "If the gadget is grafted, calls " { $link ungraft* } " on the gadget and all children." }
 136 { $notes "This word should never be called directly." } ;
 137
 138 HELP: unparent
 139 { $values { "gadget" gadget } }
 140 { $description "Removes the gadget from its parent. This will relayout the parent." }
 141 { $notes "This may result in " { $link ungraft* } " being called on the gadget and its children, if the gadget's parent is visible on the screen." } ;
 142
 143 HELP: clear-gadget
 144 { $values { "gadget" gadget } }
 145 { $description "Removes all children from the gadget. This will relayout the gadget." }
 146 { $notes "This may result in " { $link ungraft* } " being called on the children, if the gadget is visible on the screen." }
 147 { $side-effects "gadget" } ;
 148
 149 HELP: add-gadget
 150 { $values { "parent" gadget } { "child" gadget } }
 151 { $description "Adds a child gadget to a parent. If the gadget is contained in another gadget, " { $link unparent } " is called on the gadget first. The parent will be relayout." }
 152 { $notes "Adding a gadget to a parent may result in " { $link graft* } " being called on the children, if the parent is visible on the screen." }
 153 { $side-effects "parent" } ;
 154
 155 HELP: add-gadgets
 156 { $values { "parent" gadget } { "children" "a sequence of gadgets" } }
 157 { $description "Adds a sequence of gadgets to a parent. The parent will be relayout." }
 158 { $notes "This may result in " { $link graft* } " being called on the children, if the parent is visible on the screen." }
 159 { $side-effects "parent" } ;
 160
 161 HELP: child?
 162 { $values { "parent" gadget } { "child" gadget } { "?" boolean } }
 163 { $description "Tests if " { $snippet "child" } " is contained inside " { $snippet "parent" } "." } ;
 164
 165 HELP: each-parent
 166 { $values { "gadget" gadget } { "quot" { $quotation ( gadget -- ? ) } } { "?" boolean } }
 167 { $description "Applies the quotation to every parent of the gadget, starting from the gadget itself, stopping if the quotation yields " { $link f } ". Outputs " { $link t } " if the iteration completed, and outputs " { $link f } " if it was stopped prematurely." } ;
 168
 169 HELP: find-parent
 170 { $values { "gadget" gadget } { "quot" { $quotation ( gadget -- ? ) } } { "parent" gadget } }
 171 { $description "Outputs the first parent of the gadget, starting from the gadget itself, for which the quotation outputs a true value, or " { $link f } " if the quotation outputs " { $link f } " for every parent." } ;
 172
 173 HELP: focusable-child*
 174 { $values { "gadget" gadget } { "child/t" "a " { $link gadget } " or " { $link t } } }
 175 { $description "Outputs the child of the gadget which would prefer to receive keyboard focus, or " { $link t } " if the gadget itself should receive focus." }
 176 { $examples "For example, if your gadget consists of an editor together with an output area whose contents react to changes in editor contents, then the " { $link focusable-child* } " method for your gadget class should return the editor, so that when the gadget is displayed in a window or passed to " { $link request-focus } ", the editor receives keyboard focus automatically." } ;
 177
 178 HELP: focusable-child
 179 { $values { "gadget" gadget } { "child" gadget } }
 180 { $description "Outputs the child of the gadget which would prefer to receive keyboard focus." } ;
 181
 182 { control-value set-control-value } related-words
 183
 184 HELP: layout-later
 185 { $values { "gadget" gadget } }
 186 { $description "Adds the gadget to the " { $link layout-queue } " and notifies the UI thread that there is a gadget to layout. If the length of the queue is larger than " { $link layout-queue-limit } ", then the current thread is yielded so that the UI thread has a chance to run." } ;
 187
 188 HELP: parents
 189 { $values { "gadget" gadget } { "seq" "a sequence of gadgets" } }
 190 { $description "Outputs a sequence of all parents of the gadget, with the first element being the gadget itself." } ;
 191
 192 HELP: screen-loc
 193 { $values { "gadget" gadget } { "loc" "a pair of integers" } }
 194 { $description "Outputs the location of the gadget relative to the top-left corner of the world containing the gadget. This word does not output a useful value if the gadget is not grafted." } ;
 195
 196 HELP: set-control-value
 197 { $values { "value" object } { "control" gadget } }
 198 { $description "Sets the value of the control's model." } ;
 199
 200 HELP: unqueue-graft
 201 { $values { "gadget" gadget } }
 202 { $description "Removes the gadget from the " { $link graft-queue } "." } ;
 203
 204 HELP: ui-notify-flag
 205 { $var-description "A " { $link flag } " raised to notify the UI thread that there is work to do." }
 206 { $see-also notify-ui-thread } ;
 207
 208 ARTICLE: "ui-control-impl" "Implementing controls"
 209 "A " { $emphasis "control" } " is a gadget which is linked to an underlying " { $link model } " by having its " { $snippet "model" } " slot set to a " { $link model } " instance."
 210 $nl
 211 "Some utility words useful in control implementations:"
 212 { $subsections
 213     control-value
 214     set-control-value
 215 }
 216 "Graft handling:"
 217 { $subsections
 218   graft
 219   notify
 220   ungraft
 221   unqueue-graft
 222 }
 223 { $see-also "models" } ;