Finishing documentation for core/ui/text/

TODO.txt

@@ -5,7 +5,6 @@
 - ui docs
 - test factor on linux/ppc
 - auto-generate error-index
-- C+up/down broken
 
 + 0.88:
 

core/ui/gadgets/scrolling.facts

@@ -30,12 +30,12 @@ HELP: relative-scroll-rect
 
 HELP: scroll>rect
 { $values { "rect" rect } { "gadget" gadget } }
-{ $description "Ensures that a rectangular region relative to the top-left corner of " { $snippet "gadget" } " becomes visible in a scroller containing " { $snippet "gadget" } ". If no parent of " { $snippet "scroller" } " is a gadget, does nothing." }
+{ $description "Ensures that a rectangular region relative to the top-left corner of " { $snippet "gadget" } " becomes visible in a " { $link scroller } " containing " { $snippet "gadget" } ". Does nothing if no parent of " { $snippet "gadget" } " is a " { $link scroller } "." }
 { $see-also scroll>bottom scroll>top } ;
 
 HELP: scroll>bottom
 { $values { "gadget" gadget } }
-{ $description "Ensures that any scroller containing " { $snippet "gadget" } " is scrolled all the way down. If no parent of " { $snippet "scroller" } " is a gadget, does nothing." }
+{ $description "Ensures that any " { $link scroller } " containing " { $snippet "gadget" } " is scrolled all the way down. Does nothing if no parent of " { $snippet "gadget" } " is a " { $link scroller } "." }
 { $see-also scroll>rect scroll>top } ;
 
 HELP: scroll>top

core/ui/load.factor

@@ -76,6 +76,8 @@ PROVIDE: core/ui
     "gadgets/viewports.facts"
     "text/document.facts"
     "text/editor.facts"
+    "text/elements.facts"
+    "text/interactor.facts"
 } }
 { +tests+ {
     "test/editor.factor"

core/ui/text/document.facts

@@ -77,7 +77,7 @@ HELP: doc-end
 
 HELP: doc-string
 { $values { "document" document } { "string" "a new " { $link string } } }
-{ $description "Outputs the contents of the document as a string." } ;
+{ $description "Outputs the contents of the document as a string. Lines are separated by " { $snippet "\\n" } "." } ;
 
 HELP: set-doc-lines
 { $values { "array" "an array of strings" } { "document" document } }

core/ui/text/editor.factor

@@ -46,9 +46,9 @@ M: editor model-changed
     over editor-mark [ over validate-loc ] (change-model)
     drop relayout ;
 
-: editor-caret* editor-caret model-value ;
+: editor-caret* ( editor -- loc ) editor-caret model-value ;
 
-: editor-mark* editor-mark model-value ;
+: editor-mark* ( editor -- loc ) editor-mark model-value ;
 
 : change-caret ( editor quot -- )
     over >r >r dup editor-caret* swap control-model r> call r>
@@ -68,8 +68,7 @@ M: editor model-changed
 : line-height ( editor -- n )
     editor-font* font-height ;
 
-: run-char-widths ( str editor -- wlist )
-    #! List of x co-ordinates of each character.
+: run-char-widths ( string editor -- widths )
     editor-font* swap >array [ char-width ] map-with
     dup 0 [ + ] accumulate nip swap 2 v/n v+ ;
 
@@ -217,10 +216,10 @@ M: editor gadget-selection
 M: editor user-input*
     [ selection-start/end ] keep control-model set-doc-range t ;
 
-: editor-string ( editor -- str )
+: editor-string ( editor -- string )
     control-model doc-string ;
 
-: set-editor-string ( str editor -- )
+: set-editor-string ( string editor -- )
     control-model set-doc-string ;
 
 ! Editors support the stream output protocol

core/ui/text/editor.facts

@@ -1,8 +1,8 @@
 IN: gadgets-text
-USING: help gadgets ;
+USING: help gadgets gadgets-scrolling models strings ;
 
 HELP: editor
-{ $class-description "Instances of this class are multi-line text editors which edit an underlying " { $link document } " model."
+{ $class-description "An editor is a " { $link control } " for editing a multi-line passage of text stored in a " { $link document } " model. Editors are crated by calling " { $link <editor> } "."
 $terpri
 "The " { $link interactor } " gadget is built off the " { $link editor } " gadget and is used by the " { $link "ui-listener" } "." }
 { $heading "General commands" }
@@ -10,4 +10,82 @@ $terpri
 { $heading "Caret motion commands" }
 { $commands editor "caret" }
 { $heading "Selection commands" }
-{ $commands editor "selection" } ;
+{ $commands editor "selection" }
+{ $heading "Slots" }
+"Editors have the following slots:"
+{ $list
+    { { $link editor-font } " - a font specifier." }
+    { { $link editor-color } " - text color specifier." }
+    { { $link editor-caret-color } " - caret color specifier." }
+    { { $link editor-selection-color } " - selection background color specifier." }
+    { { $link editor-caret } " - a model storing a line/column pair." }
+    { { $link editor-mark } " - a model storing a line/column pair. If there is no selection, the mark is equal to the caret, otherwise the mark is located at the opposite end of the selection from the caret." }
+    { { $link editor-focused? } " - a boolean." }
+} ;
+
+HELP: loc-monitor
+{ $class-description "Instances of this class are used internally by " { $link editor } " controls to redraw the editor when the caret or mark is moved by calling " { $link set-model } " on " { $link editor-caret } " or " { $link editor-mark } "." } ;
+
+HELP: <editor>
+{ $values { "editor" "a new " { $link editor } } }
+{ $description "Creates a new " { $link editor } " with an empty document." } ;
+
+HELP: editor-caret ( editor -- model )
+{ $values { "editor" editor } { "model" model } }
+{ $values "Outputs a " { $link model } " holding the current caret location." }
+{ $see-also editor-caret editor-mark editor-mark* } ;
+
+HELP: editor-caret*
+{ $values { "editor" editor } { "loc" "a pair of integers" } }
+{ $values "Outputs the current caret location as a line/column number pair." }
+{ $see-also editor-caret editor-mark editor-mark* } ;
+
+HELP: editor-mark ( editor -- model )
+{ $values { "editor" editor } { "model" model } }
+{ $values "Outputs a " { $link model } " holding the current mark location." }
+{ $see-also editor-mark editor-mark editor-mark* } ;
+
+HELP: editor-mark*
+{ $values { "editor" editor } { "loc" "a pair of integers" } }
+{ $values "Outputs the current mark location as a line/column number pair." }
+{ $see-also editor-mark editor-mark editor-mark* } ;
+
+HELP: change-caret
+{ $values { "editor" editor } { "quot" "a quotation with stack effect " { $snippet "( loc -- newloc )" } } }
+{ $description "Applies a quotation to the current caret location and moves the caret to the location output by the quotation." }
+{ $see-also mark>caret change-caret&mark } ;
+
+HELP: mark>caret
+{ $values { "editor" editor } }
+{ $description "Moves the mark to the caret location, effectively deselecting any selected text." }
+{ $see-also editor-caret editor-mark change-caret change-caret&mark } ;
+
+HELP: change-caret&mark
+{ $values { "editor" editor } { "quot" "a quotation with stack effect " { $snippet "( loc -- newloc )" } } }
+{ $description "Applies a quotation to the current caret location and moves the caret and the mark to the location output by the quotation." }
+{ $see-also mark>caret change-caret } ;
+
+HELP: run-char-widths
+{ $values { "string" string } { "editor" editor } { "widths" "a sequence of integers" } }
+{ $description "Outputs a sequence of x co-ordinates of the midpoint of each character in the string." }
+{ $notes "This word is used to convert x offsets to document locations, for example when the user moves the caret by clicking the mouse." } ;
+
+HELP: point>loc
+{ $values { "point" "a pair of integers" } { "editor" editor } { "loc" "a pair of integers" } }
+{ $description "Converts a point to a line/column number pair." } ;
+
+HELP: scroll>caret
+{ $values { "editor" editor } }
+{ $description "Ensures that the caret becomes visible in a " { $link scroller } " containing the editor. Does nothing if no parent of " { $snippet "gadget" } " is a " { $link scroller } "." } ;
+
+HELP: remove-editor-selection
+{ $values { "editor" editor } }
+{ $description "Removes currently selected text from the editor's " { $link document } "." } ;
+
+HELP: editor-string
+{ $values { "editor" editor } { "string" string } }
+{ $description "Outputs the contents of the editor's " { $link document } " as a string. Lines are separated by " { $snippet "\\n" } "." } ;
+
+HELP: set-editor-string
+{ $values { "array" "an array of strings" } { "editor" editor } }
+{ $description "Sets the contents of the editor's " { $link document } " to a string,  which may use either " { $snippet "\\n" } ", " { $snippet "\\r\\n" } " or " { $snippet "\\r" } " line separators." } ;

core/ui/text/elements.factor

@@ -1,8 +1,8 @@
 IN: gadgets-text
 USING: arrays kernel math sequences strings models ;
 
-GENERIC: prev-elt ( loc document elt -- loc )
-GENERIC: next-elt ( loc document elt -- loc )
+GENERIC: prev-elt ( loc document elt -- newloc )
+GENERIC: next-elt ( loc document elt -- newloc )
 
 TUPLE: char-elt ;
 

core/ui/text/elements.facts

@@ -0,0 +1,34 @@
+IN: gadgets-text
+USING: help ;
+
+HELP: prev-elt
+{ $values { "loc" "a pair of integers" } { "document" document } { "elt" "an element" } { "newloc" "a pair of integers" } }
+{ $contract "Outputs the location of the first occurrence of the element prior to " { $snippet "loc" } "." }
+{ $see-also next-elt } ;
+
+HELP: next-elt
+{ $values { "loc" "a pair of integers" } { "document" document } { "elt" "an element" } { "newloc" "a pair of integers" } }
+{ $contract "Outputs the location of the first occurrence of the element following " { $snippet "loc" } "." }
+{ $see-also prev-elt } ;
+
+HELP: char-elt
+{ $class-description "An element representing a single character." } ;
+
+HELP: one-word-elt
+{ $class-description "An element representing a single word. The " { $link prev-elt } " and " { $link next-elt } " words return the location of the beginning and the end of the word at the current location." }
+{ $see-also word-elt } ;
+
+HELP: word-elt
+{ $class-description "An element representing a single word. The " { $link prev-elt } " and " { $link next-elt } " words return the location of the previous and next word from the current location." }
+{ $see-also one-word-elt } ;
+
+HELP: one-line-elt
+{ $class-description "An element representing a single line. The " { $link prev-elt } " and " { $link next-elt } " words return the location of the beginning and the end of the line at the current location." }
+{ $see-also line-elt } ;
+
+HELP: line-elt
+{ $class-description "An element representing a single line. The " { $link prev-elt } " and " { $link next-elt } " words return the location of the previous and next line from the current location." }
+{ $see-also one-line-elt } ;
+
+HELP: doc-elt
+{ $class-description "An element representing the entire document. The " { $link prev-elt } " word outputs the start of the document and the " { $link next-elt } " word outputs the end of the document." } ;

core/ui/text/interactor.facts

@@ -0,0 +1,9 @@
+IN: gadgets-text
+USING: gadgets listener io help ;
+
+HELP: interactor
+{ $class-description "An interactor is an " { $link editor } " intended to be used as the input component of a " { $link "ui-listener" } "."
+$terpri
+"Interactors are created by calling " { $link <interactor> } "."
+$terpri
+"Interactors implement the " { $link stream-readln } ", " { $link stream-read } " and " { $link parse-interactive } " generic words." } ;

core/ui/tools/load.factor

@@ -15,4 +15,5 @@ PROVIDE: core/ui/tools
 } }
 { +tests+ {
     "test/listener.factor"
+    "test/workspace.factor"
 } } ;

core/ui/tools/test/workspace.factor

@@ -0,0 +1,13 @@
+IN: temporary
+USING: gadgets-workspace namespaces sequences
+gadgets-scrolling test gadgets ;
+
+! Since this is a rarely used feature, it makes sense to unit
+! test it to ensure it still works
+[ ] [ <workspace> "w" set ] unit-test
+[ ] [ "w" get tool-scroll-up ] unit-test
+[ ] [ "w" get tool-scroll-down ] unit-test
+[ t ] [
+    "w" get workspace-book gadget-children
+    [ tool-scroller ] map [ ] subset [ scroller? ] all?
+] unit-test