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

   1 USING: ui.gadgets models help.markup help.syntax io kernel
   2 quotations ;
   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 } " targetting the pane. Panes are created by calling " { $link <pane> } ", " { $link <scrolling-pane> } " or " { $link <pane-control> } "." } ;
   7
   8 HELP: <pane>
   9 { $values { "pane" "a new " { $link pane } } }
  10 { $description "Creates a new " { $link pane } " gadget." } ;
  11
  12 HELP: write-gadget
  13 { $values { "gadget" gadget } { "stream" "an output stream" } }
  14 { $contract "Writes a gadget to the stream." }
  15 { $notes "Not all streams support this operation." } ;
  16
  17 { write-gadget print-gadget gadget. } related-words
  18
  19 HELP: print-gadget
  20 { $values { "gadget" gadget } { "stream" "an output stream" } }
  21 { $description "Writes a gadget to the stream, followed by a newline." }
  22 { $notes "Not all streams support this operation." } ;
  23
  24 HELP: gadget.
  25 { $values { "gadget" gadget } }
  26 { $description "Writes a gadget followed by a newline to " { $link output-stream } "." }
  27 { $notes "Not all streams support this operation." } ;
  28
  29 HELP: ?nl
  30 { $values { "stream" pane-stream } }
  31 { $description "Inserts a line break in the pane unless the current line is empty." } ;
  32
  33 HELP: with-pane
  34 { $values { "pane" pane } { "quot" quotation } }
  35 { $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." } ;
  36
  37 HELP: make-pane
  38 { $values { "quot" quotation } { "gadget" "a new " { $link gadget } } }
  39 { $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." } ;
  40
  41 HELP: <scrolling-pane>
  42 { $values { "pane" "a new " { $link pane } } }
  43 { $description "Creates a new " { $link pane } " gadget which scrolls any scroll pane containing it to the bottom on output. behaving much like a terminal or logger." } ;
  44
  45 HELP: <pane-control>
  46 { $values { "model" model } { "quot" "a quotation with stack effect " { $snippet "( value -- )" } } { "pane" "a new " { $link pane } } }
  47 { $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 } "." } ;
  48
  49 HELP: pane-stream
  50 { $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> } "." } ;
  51
  52 HELP: <pane-stream> ( pane -- stream )
  53 { $values { "pane" pane } { "stream" "a new " { $link pane-stream } } }
  54 { $description "Creates a new " { $link pane-stream } " for writing to " { $snippet "pane" } "." } ;
  55
  56 { with-pane make-pane } related-words
  57
  58 ARTICLE: "ui.gadgets.panes" "Pane gadgets"
  59 "A pane displays formatted text."
  60 { $subsection pane }
  61 { $subsection <pane> }
  62 { $subsection <scrolling-pane> }
  63 { $subsection <pane-control> }
  64 "Panes are written to by creating a special output stream:"
  65 { $subsection pane-stream }
  66 { $subsection <pane-stream> }
  67 "In addition to the stream output words (" { $link "stream-protocol" } ", pane streams can have gadgets written to them:"
  68 { $subsection write-gadget }
  69 { $subsection print-gadget }
  70 { $subsection gadget. }
  71 "The " { $link gadget. } " word is useful for interactive debugging of gadgets in the listener."
  72 $nl
  73 "There are a few combinators for working with panes:"
  74 { $subsection with-pane }
  75 { $subsection make-pane } ;
  76
  77 ABOUT: "ui.gadgets.panes"