ui.*: a little more ui docs

basis/ui/gadgets/gadgets-docs.factor

@@ -1,8 +1,11 @@
-USING: help.markup help.syntax opengl kernel strings
-classes.tuple classes quotations models math.rectangles
-ui.gadgets.private accessors ;
+USING: accessors concurrency.flags help.markup help.syntax kernel
+math.rectangles models strings ui.gadgets.private ;
 IN: ui.gadgets
 
+HELP: control-value
+{ $values { "control" gadget } { "value" object } }
+{ $description "Outputs the value of the control's model." } ;
+
 HELP: gadget-child
 { $values { "gadget" gadget } { "child" gadget } }
 { $description "Outputs the first child of the gadget. Typically this word is used with gadgets which are known to have an only child." } ;
@@ -173,14 +176,14 @@ HELP: focusable-child
 
 { control-value set-control-value } related-words
 
-HELP: control-value
-{ $values { "control" gadget } { "value" object } }
-{ $description "Outputs the value of the control's model." } ;
-
 HELP: set-control-value
 { $values { "value" object } { "control" gadget } }
 { $description "Sets the value of the control's model." } ;
 
+HELP: ui-notify-flag
+{ $var-description "A " { $link flag } " raised to notify the UI thread that there is work to do." }
+{ $see-also notify-ui-thread } ;
+
 ARTICLE: "ui-control-impl" "Implementing controls"
 "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."
 $nl

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

@@ -1,4 +1,4 @@
-USING: ui.gadgets help.markup help.syntax ui.gadgets.packs ;
+USING: help.markup help.syntax ui.gadgets ui.gadgets.packs ;
 IN: ui.gadgets.incremental
 
 HELP: incremental
@@ -8,6 +8,8 @@ $nl
 $nl
 "Children are managed with the " { $link add-incremental } " and " { $link clear-incremental } " words."
 $nl
+"An example of an incremental is the " { $slot "output" } " of a 'pane' gadget."
+$nl
 "Not every " { $link pack } " can use incremental layout, since incremental layout does not support non-default values for the " { $slot "align" } ", " { $slot "fill" } ", and " { $slot "gap" } " slots." } ;
 
 HELP: <incremental>

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

@@ -1,5 +1,5 @@
-USING: ui.gadgets models help.markup help.syntax io kernel
-quotations ;
+USING: help.markup help.syntax io kernel models quotations ui.gadgets
+ui.gadgets.panes.private ;
 IN: ui.gadgets.panes
 
 HELP: pane
@@ -16,6 +16,11 @@ HELP: write-gadget
 
 { write-gadget print-gadget gadget. } related-words
 
+HELP: pane-nl
+{ $values { "pane" pane } }
+{ $description "Outputs a virtual newline character to the pane stream." }
+{ $see-also nl } ;
+
 HELP: print-gadget
 { $values { "gadget" gadget } { "stream" "an output stream" } }
 { $description "Writes a gadget to the stream, followed by a newline." }

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

@@ -10,13 +10,21 @@ ARTICLE: "ui-track-layout" "Track layouts"
 "Adding children:"
 { $subsections track-add } ;
 
-HELP: track
-{ $class-description "A track is like a " { $link pack } " except each child is resized to a fixed multiple of the track's dimension in the direction of " { $snippet "orientation" } ". Tracks are created by calling " { $link <track> } "." } ;
-
 HELP: <track>
 { $values { "orientation" "an orientation specifier" } { "track" "a new " { $link track } } }
 { $description "Creates a new track which lays out children along the given orientation, either " { $link horizontal } " or " { $link vertical } "." } ;
 
+HELP: new-track
+{ $values
+  { "orientation" "an orientation specifier" }
+  { "class" "a gadget class" }
+  { "track" gadget }
+}
+{ $description "Creates a new container gadget of the specified class and sets its children lay out to either " { $link horizontal } " or " { $link vertical } "." } ;
+
+HELP: track
+{ $class-description "A track is like a " { $link pack } " except each child is resized to a fixed multiple of the track's dimension in the direction of " { $snippet "orientation" } ". Tracks are created by calling " { $link <track> } "." } ;
+
 HELP: track-add
 { $values { "track" track } { "gadget" gadget } { "constraint" "a number between 0 and 1, or " { $link f } } }
 { $description "Adds a new child to a track. If the constraint is " { $link f } ", the child always occupies its preferred size. Otherwise, the constrant is a fraction of the total size which is allocated for the child." } ;

basis/ui/text/text-docs.factor

@@ -1,6 +1,9 @@
 IN: ui.text
 USING: help.markup help.syntax kernel ui.text.private strings math fonts images ;
 
+HELP: flush-layout-cache
+{ $description "Flushes the cache of pre-rendered layouts." } ;
+
 HELP: string-width
 { $values { "font" font } { "string" string } { "w" "a positive integer" } }
 { $contract "Outputs the width of a string." }

basis/ui/tools/listener/listener-docs.factor

@@ -1,16 +1,33 @@
-USING: help.markup help.syntax ui.commands ui.operations
-ui.gadgets.editors ui.gadgets.panes listener io words
-ui.tools.listener.completion ui.tools.common help.tips
-vocabs vocabs.refresh ;
+USING: help.markup help.syntax help.tips io kernel listener
+ui.commands ui.gadgets ui.gadgets.editors ui.gadgets.panes
+ui.operations ui.tools.common ui.tools.listener.completion vocabs
+vocabs.refresh words ;
 IN: ui.tools.listener
 
+HELP: <listener-gadget>
+{ $values { "listener" listener-gadget } }
+{ $description "Creates a new listener gadget." } ;
+
 HELP: interactor
-{ $class-description "An interactor is an " { $link editor } " intended to be used as the input component of a " { $link "ui-listener" } "."
-$nl
+{ $class-description "An interactor is an " { $link editor } " intended to be used as the input component of a " { $link "ui-listener" } ". It has the following slots:"
+{ $table
+  {
+      { $slot "waiting" }
+      { "If waiting is " { $link t } ", the interactor is waiting for user input, and invoking " { $link evaluate-input } " resumes the thread." }
+  }
+}
 "Interactors are created by calling " { $link <interactor> } "."
 $nl
 "Interactors implement the " { $link stream-readln } ", " { $link stream-read } " and " { $link stream-read-quot } " generic words." } ;
 
+HELP: interactor-busy?
+{ $values { "interactor" interactor } { "?" boolean } }
+{ $description "We're busy if there's no thread to resume." } ;
+
+HELP: wait-for-listener
+{ $values { "listener" listener-gadget } }
+{ $description "Wait for the listener to start." } ;
+
 ARTICLE: "ui-listener" "UI listener"
 "The graphical listener adds input history and word and vocabulary completion. A summary with any outstanding error conditions is displayed before every prompt (see " { $link "ui.tools.error-list" } " for details)."
 $nl

basis/ui/tools/listener/listener.factor

@@ -30,7 +30,6 @@ INSTANCE: interactor input-stream
     thread>> thread-continuation ;
 
 : interactor-busy? ( interactor -- ? )
-    ! We're busy if there's no thread to resume.
     {
         [ waiting>> ]
         [ thread>> dup [ thread-registered? ] when ]
@@ -226,7 +225,6 @@ M: listener-gadget focusable-child*
     input>> dup popup>> or ;
 
 : wait-for-listener ( listener -- )
-    ! Wait for the listener to start.
     input>> flag>> wait-for-flag ;
 
 : listener-busy? ( listener -- ? )
@@ -372,7 +370,10 @@ M: interactor handle-gesture
     {
         { [ over key-gesture? not ] [ call-next-method ] }
         { [ dup popup>> ] [ { [ pass-to-popup ] [ call-next-method ] } 2&& ] }
-        { [ dup token-model>> value>> ] [ { [ interactor-operation ] [ call-next-method ] } 2&& ] }
+        {
+            [ dup token-model>> value>> ]
+            [ { [ interactor-operation ] [ call-next-method ] } 2&& ]
+        }
         [ call-next-method ]
     } cond ;