From 78c31ada9ed97c8693c65fad2d0b86305b06f060 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Bj=C3=B6rn=20Lindqvist?= <bjourne@gmail.com>
Date: Thu, 18 Jan 2018 03:43:32 +0100
Subject: [PATCH] ui.*: doc updates

---
 basis/ui/event-loop/event-loop-docs.factor |  2 +-
 basis/ui/gadgets/gadgets-docs.factor       | 16 ++++++++++------
 basis/ui/ui-docs.factor                    | 12 ++++++++----
 3 files changed, 19 insertions(+), 11 deletions(-)

diff --git a/basis/ui/event-loop/event-loop-docs.factor b/basis/ui/event-loop/event-loop-docs.factor
index a262911149..eb23d9f9b8 100644
--- a/basis/ui/event-loop/event-loop-docs.factor
+++ b/basis/ui/event-loop/event-loop-docs.factor
@@ -3,4 +3,4 @@ IN: ui.event-loop
 
 HELP: event-loop?
 { $values { "?" boolean } }
-{ $description { $link t } " if there is active windows." } ;
+{ $description { $link t } " if there are active windows." } ;
diff --git a/basis/ui/gadgets/gadgets-docs.factor b/basis/ui/gadgets/gadgets-docs.factor
index 9d9b830990..f5f6def67d 100644
--- a/basis/ui/gadgets/gadgets-docs.factor
+++ b/basis/ui/gadgets/gadgets-docs.factor
@@ -6,6 +6,11 @@ HELP: <gadget>
 { $values { "gadget" "a new " { $link gadget } } }
 { $description "Creates a new gadget." } ;
 
+HELP: children-on
+{ $values { "rect" rect } { "gadget" gadget } { "seq" "a sequence of gadgets" } }
+{ $contract "Outputs a sequence of gadgets which potentially intersect a rectangle in the co-ordinate system of the gadget." }
+{ $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." } ;
+
 HELP: control-value
 { $values { "control" gadget } { "value" object } }
 { $description "Outputs the value of the control's model." } ;
@@ -19,6 +24,10 @@ HELP: notify
 { $description "Notifies the gadget that it has a graft message to handle." }
 { $see-also graft* ungraft* } ;
 
+HELP: notify-ui-thread
+{ $description "Notifies the UI thread that there is work to do." }
+{ $see-also ui-notify-flag } ;
+
 HELP: nth-gadget
 { $values { "n" "a non-negative integer" } { "gadget" gadget } { "child" gadget } }
 { $description "Outputs the " { $snippet "n" } "th child of the gadget." }
@@ -37,11 +46,6 @@ HELP: user-input*
 { $values { "str" string } { "gadget" gadget } { "?" boolean } }
 { $contract "Handle free-form textual input while the gadget has keyboard focus." } ;
 
-HELP: children-on
-{ $values { "rect" rect } { "gadget" gadget } { "seq" "a sequence of gadgets" } }
-{ $contract "Outputs a sequence of gadgets which potentially intersect a rectangle in the co-ordinate system of the gadget." }
-{ $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." } ;
-
 HELP: pick-up
 { $values { "point" "a pair of integers" } { "gadget" gadget } { "child/f" { $maybe gadget } } }
 { $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." } ;
@@ -70,7 +74,7 @@ HELP: relayout
 
 HELP: relayout-1
 { $values { "gadget" gadget } }
-{ $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 only be used when the gadget's internal layout or appearance has changed, but the dimensions have not." } ;
+{ $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." } ;
 
 { relayout relayout-1 } related-words
 
diff --git a/basis/ui/ui-docs.factor b/basis/ui/ui-docs.factor
index 9560ddce03..c97354e18b 100644
--- a/basis/ui/ui-docs.factor
+++ b/basis/ui/ui-docs.factor
@@ -6,15 +6,19 @@ vocabs.loader ;
 
 IN: ui
 
+HELP: open-window
+{ $values { "gadget" gadget } { "title/attributes" { "a " { $link string } " or a " { $link world-attributes } " tuple" } } }
+{ $description "Opens a native window containing " { $snippet "gadget" } " with the specified attributes. If a string is provided, it is used as the window title; otherwise, the window attributes are specified in a " { $link world-attributes } " tuple." } ;
+
+HELP: ui-running?
+{ $values { "?" boolean } }
+{ $description "Whether the UI is running or not." } ;
+
 HELP: ui-windows
 { $var-description "Global variable holding an association list mapping native window handles to " { $link world } " instances." } ;
 
 { ui-windows open-window find-window world-attributes } related-words
 
-HELP: open-window
-{ $values { "gadget" gadget } { "title/attributes" { "a " { $link string } " or a " { $link world-attributes } " tuple" } } }
-{ $description "Opens a native window containing " { $snippet "gadget" } " with the specified attributes. If a string is provided, it is used as the window title; otherwise, the window attributes are specified in a " { $link world-attributes } " tuple." } ;
-
 HELP: close-window
 { $values { "gadget" gadget } }
 { $description "Close the native window containing " { $snippet "gadget" } "." } ;