basis/ui/gadgets/panes/panes-docs.factor

   1 USING: help.markup help.syntax io kernel models quotations ui.gadgets
   2 ui.gadgets.panes.private ;
   3 IN: ui.gadgets.panes
   4
   5 HELP: pane
   6 { $class-description "A pane " { $link gadget } " displays formatted text which is written to a " { $link pane-stream } " targeting the pane. Panes are created by calling " { $link <pane> } " or " { $link <pane-control> } ". Panes have the following slots"
   7   { $table
   8     {
   9         { $slot "input" }
  10         { "A gadget that receives input events and writes to the pane's input stream." }
  11     }
  12   }
  13 } ;
  14
  15 HELP: <pane>
  16 { $values { "pane" "a new " { $link pane } } }
  17 { $description "Creates a new " { $link pane } " gadget." } ;
  18
  19 HELP: write-gadget
  20 { $values { "gadget" gadget } { "stream" "an output stream" } }
  21 { $contract "Writes a gadget to the stream." }
  22 { $notes "Not all streams support this operation." } ;
  23
  24 { write-gadget print-gadget gadget. } related-words
  25
  26 HELP: pane-nl
  27 { $values { "pane" pane } }
  28 { $description "Outputs a virtual newline character to the pane stream." }
  29 { $see-also nl } ;
  30
  31 HELP: print-gadget
  32 { $values { "gadget" gadget } { "stream" "an output stream" } }
  33 { $description "Writes a gadget to the stream, followed by a newline." }
  34 { $notes "Not all streams support this operation." } ;
  35
  36 HELP: gadget.
  37 { $values { "gadget" gadget } }
  38 { $description "Writes a gadget followed by a newline to " { $link output-stream } "." }
  39 { $notes "Not all streams support this operation." } ;
  40
  41 HELP: with-pane
  42 { $values { "pane" pane } { "quot" quotation } }
  43 { $description "Clears the pane and calls the quotation in a new scope where " { $link output-stream } " is rebound to a " { $link pane-stream } " writing to the pane." } ;
  44
  45 HELP: make-pane
  46 { $values { "quot" quotation } { "gadget" "a new " { $link gadget } } }
  47 { $description "Calls the quotation in a new scope where " { $link output-stream } " is rebound to a " { $link pane-stream } " writing to a new pane. The output area of the new pane is output on the stack after the quotation returns. The pane itself is not output." } ;
  48
  49 HELP: <pane-control>
  50 { $values { "model" model } { "quot" { $quotation ( value -- ) } } { "pane" "a new " { $link pane } } }
  51 { $description "Creates a new control delegating to a " { $link pane } ". When the value of the model changes, the value is pushed on the stack and the quotation is called using " { $link with-pane } "." } ;
  52
  53 HELP: pane-stream
  54 { $class-description "Pane streams implement the portion of the " { $link "stream-protocol" } " responsible for output of text, including full support for " { $link "styles" } ". Pane streams also support direct output of gadgets via " { $link write-gadget } " and " { $link print-gadget } ". Pane streams are created by calling " { $link <pane-stream> } "." } ;
  55
  56 HELP: <pane-stream>
  57 { $values { "pane" pane } { "pane-stream" "a new " { $link pane-stream } } }
  58 { $description "Creates a new " { $link pane-stream } " for writing to " { $snippet "pane" } "." } ;
  59
  60 { with-pane make-pane } related-words
  61
  62 HELP: content-gadget
  63 { $values { "object" object } { "gadget/f" { $maybe gadget } } }
  64 { $description "This generic function may be implemented for objects in order to display a rich representation of the object in the " { $link "ui-inspector" } ". If " { $snippet "content-gadget" } " returns a gadget for an inspected object, the returned gadget is displayed under the \"Content\" heading in the inspector window. If " { $snippet "content-gadget" } " returns " { $link POSTPONE: f } ", no content section is included in the given object's inspector." } ;
  65
  66 ARTICLE: "ui.gadgets.panes" "Pane gadgets"
  67 "The " { $vocab-link "ui.gadgets.panes" } " vocabulary implements panes, which display formatted text."
  68 { $subsections
  69     pane
  70     <pane>
  71     <pane-control>
  72 }
  73 "Panes are written to by creating a special output stream:"
  74 { $subsections
  75     pane-stream
  76     <pane-stream>
  77 }
  78 "In addition to the stream output words (" { $link "stream-protocol" } "), pane streams can have gadgets written to them:"
  79 { $subsections
  80     write-gadget
  81     print-gadget
  82     gadget.
  83 }
  84 "The " { $link gadget. } " word is useful for interactive debugging of gadgets in the listener."
  85 $nl
  86 "There are a few combinators for working with panes:"
  87 { $subsections
  88     with-pane
  89     make-pane
  90 } ;
  91
  92 ABOUT: "ui.gadgets.panes"