core/ui/hierarchy.facts

   1 IN: gadgets
   2 USING: help gadgets-text gadgets-tracks ;
   3
   4 HELP: graft*
   5 { $values { "gadget" gadget } }
   6 { $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." }
   7 { $see-also ungraft* } ;
   8
   9 HELP: ungraft*
  10 { $values { "gadget" gadget } }
  11 { $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." }
  12 { $see-also graft* } ;
  13
  14 HELP: graft
  15 { $values { "gadget" gadget } }
  16 { $description "Calls " { $link graft* } " on the gadget and all children." }
  17 { $notes "This word should never be called directly." }
  18 { $see-also graft* ungraft } ;
  19
  20 HELP: ungraft
  21 { $values { "gadget" gadget } }
  22 { $description "If the gadget is grafted, calls " { $link ungraft* } " on the gadget and all children." }
  23 { $notes "This word should never be called directly." }
  24 { $see-also ungraft* graft } ;
  25
  26 HELP: unparent
  27 { $values { "gadget" gadget } }
  28 { $description "Removes the gadget from its parent. This will relayout the parent." }
  29 { $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." }
  30 { $warning "Some gadget classes have their own words for removing children, for example " { $link grid-remove } ". Read the documentation for the class of the gadget's parent before using this word." } ;
  31
  32 HELP: clear-gadget
  33 { $values { "gadget" gadget } }
  34 { $description "Removes all children from the gadget. This will relayout the gadget." }
  35 { $notes "This may result in " { $link ungraft* } " being called on the children, if the gadget is visible on the screen." }
  36 { $warning "Some gadget classes have their own words for adding children, for example " { $link grid-remove } ". Read the documentation for the gadget class before using this word." }
  37 { $side-effects "gadget" } ;
  38
  39 HELP: add-gadget
  40 { $values { "gadget" gadget } { "parent" gadget } }
  41 { $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." }
  42 { $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." }
  43 { $warning "Some gadget classes have their own words for adding children, for example " { $link grid-add } " and " { $link add-incremental } ". Read the documentation for the gadget class before using this word." }
  44 { $side-effects "parent" } ;
  45
  46 HELP: add-gadgets
  47 { $values { "seq" "a sequence of gadgets" } { "parent" gadget } }
  48 { $description "Adds a sequence of gadgets to a parent. The parent will be relayout." }
  49 { $notes "This may result in " { $link graft* } " being called on the children, if the parent is visible on the screen." }
  50 { $warning "Some gadget classes have their own words for adding children, for example " { $link grid-add } " and " { $link add-incremental } ". Read the documentation for the gadget class before using this word." }
  51 { $side-effects "parent" } ;
  52
  53 HELP: parents
  54 { $values { "gadget" gadget } }
  55 { $description "Outputs a sequence of all parents of the gadget, with the first element being the gadget itself." } ;
  56
  57 HELP: each-parent
  58 { $values { "gadget" gadget } { "quot" "a quotation with stack effect " { $snippet "( gadget -- )" } } }
  59 { $description "Applies the quotation to every parent of the gadget, starting from the gadget itself." } ;
  60
  61 HELP: find-parent
  62 { $values { "gadget" gadget } { "quot" "a quotation with stack effect " { $snippet "( gadget -- ? )" } } { "parent" gadget } }
  63 { $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." } ;
  64
  65 HELP: screen-loc
  66 { $values { "gadget" gadget } { "loc" "a pair of integers" } }
  67 { $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." } ;
  68
  69 HELP: child?
  70 { $values { "parent" gadget } { "child" gadget } { "?" "a boolean" } }
  71 { $description "Tests if " { $snippet "child" } " is contained inside " { $snippet "parent" } "." } ;
  72
  73 HELP: focusable-child*
  74 { $values { "gadget" gadget } { "child" gadget } }
  75 { $description "Outputs the child of the gadget which would prefer to receive keyboard focus, or " { $link t } " if the gadget itself should receive focus." }
  76 { $examples "For example, if your gadget consists of an " { $link 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." } ;
  77
  78 HELP: focusable-child
  79 { $values { "gadget" gadget } { "child" gadget } }
  80 { $description "Outputs the child of the gadget which would prefer to receive keyboard focus." } ;
  81
  82 HELP: make-pile
  83 { $values { "children" "a sequence of gadgets" } { "pack" "a new " { $link pack } } }
  84 { $description "Creates a new " { $link pack } " which lays out a sequence of gadgets vertically." } ;
  85
  86 HELP: make-filled-pile
  87 { $values { "children" "a sequence of gadgets" } { "pack" "a new " { $link pack } } }
  88 { $description "Creates a new " { $link pack } " which lays out a sequence of gadgets vertically, such that all gadgets have the same width." } ;
  89
  90 HELP: make-shelf
  91 { $values { "children" "a sequence of gadgets" } { "pack" "a new " { $link pack } } }
  92 { $description "Creates a new " { $link pack } " which lays out a sequence of gadgets horizontally." } ;