Working on documentation

basis/colors/colors-docs.factor

@@ -2,7 +2,7 @@ IN: colors
 USING: accessors help.markup help.syntax ;
 
 HELP: color
-{ $class-description "The class of colors. Implementations include " { $link rgba } ", " { $link "colors.gray" } " and " { $vocab-link "colors.hsv" } "." } ;
+{ $class-description "The class of colors. Implementations include " { $link rgba } ", " { $vocab-link "colors.gray" } " and " { $vocab-link "colors.hsv" } "." } ;
 
 HELP: rgba
 { $class-description "The class of colors with red, green, blue and alpha channel components. The slots store color components, which are real numbers in the range 0 to 1, inclusive." } ;
@@ -32,7 +32,7 @@ $nl
 { $subsection >rgba-components }
 "Further topics:"
 { $subsection "colors.protocol" }
-{ $subsection "colors.gray" }
+{ $vocab-subsection "Grayscale colors" "colors.gray" }
 { $vocab-subsection "HSV colors" "colors.hsv" } ;
 
 ABOUT: "colors"

basis/colors/constants/constants.factor

@@ -23,6 +23,8 @@ MEMO: rgb.txt ( -- assoc )
 
 PRIVATE>
 
+: named-colors ( -- keys ) rgb.txt keys ;
+
 ERROR: no-such-color name ;
 
 : named-color ( name -- rgb )

basis/documents/documents-docs.factor

@@ -92,7 +92,7 @@ HELP: clear-doc
 { $side-effects "document" } ;
 
 ARTICLE: "documents" "Documents"
-"The " { $vocab-link "documents" } " vocabulary implements " { $emphasis "documents" } ", which are models storing a passage of text as a sequence of lines. Operations are defined for operating on subranges of the text, and " { $link "gadgets-editors" } " can display these models."
+"The " { $vocab-link "documents" } " vocabulary implements " { $emphasis "documents" } ", which are models storing a passage of text as a sequence of lines. Operations are defined for operating on subranges of the text, and " { $link "ui.gadgets.editors" } " can display these models."
 { $subsection document }
 { $subsection <document> }
 "Getting and setting the contents of the entire document:"
@@ -109,7 +109,7 @@ ARTICLE: "documents" "Documents"
 { $subsection each-line }
 { $subsection "document-locs" }
 { $subsection "documents.elements" }
-{ $see-also "gadgets-editors" } ;
+{ $see-also "ui.gadgets.editors" } ;
 
 ARTICLE: "document-locs" "Document locations"
 "Locations in the document are represented as a line/column number pair, with both indices being zero-based. There are some words for manipulating locations:"

basis/help/handbook/handbook.factor

@@ -288,6 +288,7 @@ $nl
 { $subsection "first-program" }
 { $subsection "handbook-language-reference" }
 { $subsection "handbook-environment-reference" }
+{ $subsection "ui" }
 { $subsection "handbook-library-reference" }
 "The below indices only include articles from loaded vocabularies. To explore more vocabularies, see " { $link "vocab-index" } "."
 { $subsection "article-index" }

basis/help/tutorial/tutorial.factor

@@ -40,11 +40,11 @@ $nl
 $nl
 "When you do this, you will get an error about the " { $link dup } " word not being found. This is because this word is part of the " { $vocab-link "kernel" } " vocabulary, but this vocabulary is not part of the source file's " { $link "vocabulary-search" } ". You must explicitly list dependencies in source files. This allows Factor to automatically load required vocabularies and makes larger programs easier to maintain."
 $nl
-"To add the word to the search path, first convince yourself that this word is in the " { $vocab-link "kernel" } " vocabulary. Enter " { $snippet "dup" } " in the listener's input area, and press " { $operation com-follow } ". This will open the documentation browser tool, viewing the help for the " { $link dup } " word. One of the subheadings in the help article will mention the word's vocabulary."
+"To add the word to the search path, first convince yourself that this word is in the " { $vocab-link "kernel" } " vocabulary. Enter " { $snippet "dup" } " in the listener's input area, and press " { $operation com-browse } ". This will open the documentation browser tool, viewing the help for the " { $link dup } " word. One of the subheadings in the help article will mention the word's vocabulary."
 $nl
 "So now, add the following at the start of the source file:"
 { $code "USING: kernel ;" }
-"Next, find out what vocabulary " { $link reverse } " lives in; type the word name " { $snippet "reverse" } " in the listener's input area, and press " { $operation com-follow } "."
+"Next, find out what vocabulary " { $link reverse } " lives in; type the word name " { $snippet "reverse" } " in the listener's input area, and press " { $operation com-browse } "."
 $nl
 "It lives in the " { $vocab-link "sequences" } " vocabulary, so we add that to the search path:"
 { $code "USING: kernel sequences ;" }

basis/math/complex/complex-docs.factor

@@ -26,21 +26,6 @@ HELP: complex
 
 ABOUT: "complex-numbers"
 
-HELP: 2>rect
-{ $values { "x" "a complex number" } { "y" "a complex number" } { "xr" "real part of " { $snippet "x" } } { "xi" "imaginary part of " { $snippet "x" } } { "yr" "real part of " { $snippet "y" } } { "yi" "imaginary part of " { $snippet "y" } } }
-{ $description "Extracts real and imaginary components of two numbers at once." } ;
-
-HELP: complex/
-{ $values { "x" "a complex number" } { "y" "a complex number" } { "r" "a real number" } { "i" "a real number" } { "m" "a real number" } }
-{ $description
-    "Complex division kernel. If we use the notation from " { $link 2>rect } ", this word computes:"
-    { $code
-        "r = xr*yr+xi*yi"
-        "i = xi*yr-xr*yi"
-        "m = yr*yr+yi*yi"
-    }
-} ;
-
 HELP: <complex> ( x y -- z )
 { $values { "x" "a real number" } { "y" "a real number" } { "z" "a complex number" } }
 { $description "Low-level complex number constructor. User code should call " { $link rect> } " instead." } ;

basis/opengl/textures/textures-docs.factor

@@ -1,5 +1,5 @@
 IN: opengl.textures
-USING: help.markup help.syntax opengl.gl math alien ;
+USING: help.markup help.syntax opengl.gl opengl.textures.private math alien images ;
 
 HELP: gen-texture
 { $values { "id" integer } }
@@ -10,6 +10,6 @@ HELP: delete-texture
 { $description "Wrapper for " { $link glDeleteTextures } " to handle the common case of deleting a single texture ID." } ;
 
 HELP: make-texture
-{ $values { "dim" "a pair of integers" } { "pixmap" c-ptr } { "format" "an OpenGL texture format, for example " { $link GL_UNSIGNED_BYTE } } { "type" "an OpenGL texture type, for example " { $link GL_RGBA } } { "id" "an OpenGL texture ID" } }
+{ $values { "image" image } { "id" "an OpenGL texture ID" } }
 { $description "Creates a new OpenGL texture from a pixmap image whose dimensions are equal to " { $snippet "dim" } "." } ;
   

basis/ui/backend/backend.factor

@@ -30,3 +30,5 @@ HOOK: offscreen-pixels ui-backend ( world -- alien w h )
 : with-gl-context ( handle quot -- )
     swap [ select-gl-context call ] keep
     glFlush flush-gl-context gl-error ; inline
+
+HOOK: (with-ui) ui-backend ( quot -- )

basis/ui/backend/cocoa/cocoa.factor

@@ -3,7 +3,7 @@
 USING: accessors math arrays assocs cocoa cocoa.application
 command-line kernel memory namespaces cocoa.messages
 cocoa.runtime cocoa.subclassing cocoa.pasteboard cocoa.types
-cocoa.windows cocoa.classes cocoa.nibs sequences ui
+cocoa.windows cocoa.classes cocoa.nibs sequences ui ui.private
 ui.backend ui.clipboards ui.gadgets ui.gadgets.worlds
 ui.backend.cocoa.views core-foundation core-foundation.run-loop
 core-graphics.types threads math.rectangles fry libc

basis/ui/backend/cocoa/views/views.factor

@@ -1,10 +1,10 @@
 ! Copyright (C) 2006, 2008 Slava Pestov
 ! See http://factorcode.org/license.txt for BSD license.
-USING: accessors alien alien.c-types arrays assocs cocoa kernel
-math cocoa.messages cocoa.subclassing cocoa.classes cocoa.views
-cocoa.application cocoa.pasteboard cocoa.types cocoa.windows
-sequences ui ui.gadgets ui.gadgets.private ui.gadgets.worlds ui.gestures
-core-foundation.strings core-graphics core-graphics.types
+USING: accessors alien alien.c-types arrays assocs cocoa kernel math
+cocoa.messages cocoa.subclassing cocoa.classes cocoa.views
+cocoa.application cocoa.pasteboard cocoa.types cocoa.windows sequences
+ui ui.private ui.gadgets ui.gadgets.private ui.gadgets.worlds
+ui.gestures core-foundation.strings core-graphics core-graphics.types
 threads combinators math.rectangles ;
 IN: ui.backend.cocoa.views
 

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

@@ -92,8 +92,8 @@ ARTICLE: "gadgets-editors-commands" "Editor gadget commands"
 { $command-map editor "selection" }
 { $command-map multiline-editor "multiline" } ;
 
-ARTICLE: "gadgets-editors" "Editor gadgets"
-"The " { $vocab-link "ui.gadgets.editors" } " vocabulary implements editor gadgets. An editor edits a passage of text."
+ARTICLE: "ui.gadgets.editors" "Editor gadgets"
+"The " { $vocab-link "ui.gadgets.editors" } " vocabulary implements editor gadgets. An editor edits a passage of text. Editors display a " { $link document } ". Editors are built from and inherit all features of " { $link "ui.gadgets.line-support" } "."
 { $subsection "gadgets-editors-commands" }
 "Editors:"
 { $subsection editor }
@@ -108,4 +108,4 @@ ARTICLE: "gadgets-editors" "Editor gadgets"
 "Editors edit " { $emphasis "documents" } ":"
 { $subsection "documents" } ;
 
-ABOUT: "gadgets-editors"
+ABOUT: "ui.gadgets.editors"

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

@@ -1,5 +1,5 @@
 USING: help.syntax help.markup ui.gadgets kernel arrays
-quotations classes.tuple ui.gadgets.grids parser ;
+quotations classes.tuple ui.gadgets.grids parser math ;
 IN: ui.gadgets.frames
 
 ARTICLE: "ui-frame-layout" "Frame layouts"
@@ -18,8 +18,8 @@ $nl
 "Frames are constructed by calling " { $link <frame> } " and since they inherit from " { $link grid } ", children can be managed with " { $link grid-add } " and " { $link grid-remove } "." } ;
 
 HELP: <frame>
-{ $values { "frame" frame } }
-{ $description "Creates a new " { $link frame } " for laying out gadgets in a 3x3 grid." } ;
+{ $values { "cols" integer } { "rows" integer } { "frame" frame } }
+{ $description "Creates a new " { $link frame } " for laying out gadgets in a grid." } ;
 
 { grid frame } related-words
 

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

@@ -9,7 +9,7 @@ HELP: <labeled-gadget>
 { $values { "gadget" gadget } { "title" string } { "newgadget" "a new " { $link <labeled-gadget> } } }
 { $description "Creates a new " { $link labeled-gadget } " display " { $snippet "gadget" } " with " { $snippet "title" } " on top." } ;
 
-ARTICLE: "ui.gadgets.labeled" "Labelled gadgets"
+ARTICLE: "ui.gadgets.labeled" "Labeled gadgets"
 "The " { $vocab-link "ui.gadgets.labeled" } " vocabulary implements labeled borders around child gadgets."
 { $subsection labeled-gadget }
 { $subsection <labeled-gadget> } ;

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

@@ -1,13 +1,67 @@
-USING: help.markup help.syntax ui.commands ;
+USING: help.markup help.syntax ui.commands kernel ;
 IN: ui.gadgets.tables
 
+ARTICLE: "ui.gadgets.tables.renderers" "Table row renderer protocol"
+"Table gadgets use a row renderer to display rows and do a few other things."
+$nl
+"Renderers are usually instances of singleton classes, since they don't need any state of their own. Renderers are required to implement a single generic word:"
+{ $subsection row-columns }
+"Renderers can also implement the following optional generic words for additional row information:"
+{ $subsection row-value }
+{ $subsection row-color }
+"The following optional generic words allow the renderer to provide some information about the display of all rows:"
+{ $subsection prototype-row }
+{ $subsection column-alignment }
+{ $subsection filled-column }
+{ $subsection column-titles } ;
+
+ARTICLE: "ui.gadgets.tables.selection" "Table row selection"
+"At any given time, a single row in the table may be selected."
+$nl
+"A few slots in the table gadget concern row selection:"
+{ $table
+  { { $slot "selected-value" } { " - if set to a model, the currently selected row's value, as determined by a " { $link row-value } " call to the renderer, is stored in this model. See " { $link "models" } "." } }
+  { { $slot "selected-index" } " - the index of the currently selected row." }
+  { { $slot "selection-required?" } { " - if set to a true value, the table ensures that some row is always selected, if the model is non-empty. If set to " { $link f } ", a state where nothing is selected is permitted to occur. The default is " { $link f } "." } }
+}
+"Some words for row selection:"
+{ $subsection selected-row }
+{ $subsection (selected-row) } ;
+
+ARTICLE: "ui.gadgets.tables.actions" "Table row actions"
+"When the user double-clicks on a row, or presses " { $command table "row" row-action } " while a row is selected, optional action and hook quotations are invoked. The action receives the row value and the hook receives the table gadget itself. These quotations are stored in the " { $slot "action" } " and " { $snippet "hook" } " slots of a table, respectively."
+$nl
+"If the " { $slot "single-click?" } " slot is set to a true value, then single-clicking on a row will invoke the row action. The default value is " { $link f } "."
+$nl
+"The row action can also be invoked programmatically:"
+{ $subsection row-action } ;
+
+ARTICLE: "ui.gadgets.tables.config" "Table gadget configuration"
+"Various slots in the table gadget can be set to change the appearance and behavior of the table gadget."
+{ $table
+  { { $slot "gap" } }
+  { { $slot "focus-border-color" } }
+  { { $slot "mouse-color" } }
+  { { $slot "column-line-color" } }
+  { { $slot "takes-focus?" } }
+} ;
+
+ARTICLE: "ui.gadgets.tables.example" "Table gadget example"
+"The " { $vocab-link "color-table" } " vocabulary implements a simple application which demonstrates table gadgets. It lists all the colors in the " { $snippet "rgb.txt" } " database shipped with " { $vocab-link "colors.constants" } " in a table. Rows are highlighted with their actual color, and columns show the red, green, and blue components. Column titles are supplied." ;
+
 ARTICLE: "ui.gadgets.tables" "Table gadgets"
 "The " { $vocab-link "ui.gadgets.tables" } " vocabulary implements table gadgets. Table gadgets display a grid of values, with each row's columns generated by a renderer object."
+$nl
+"Tables display a model as a series of rows. The model must be a sequence, and a " { $emphasis "renderer" } " creates a sequence of columns for each row. Tables are built from and inherit all features of " { $link "ui.gadgets.line-support" } "."
 { $command-map table "row" }
 "The class of tables:"
 { $subsection table }
 { $subsection table? }
 "Creating new tables:"
-{ $subsection <table> } ;
+{ $subsection <table> }
+{ $subsection "ui.gadgets.tables.renderers" }
+{ $subsection "ui.gadgets.tables.selection" }
+{ $subsection "ui.gadgets.tables.actions" }
+{ $subsection "ui.gadgets.tables.example" } ;
 
 ABOUT: "ui.gadgets.tables"

basis/ui/gadgets/tables/tables.factor

@@ -38,7 +38,7 @@ single-click?
 column-widths total-width
 focus-border-color
 { mouse-color initial: COLOR: black }
-{ column-line-color initial: T{ rgba f 0 0 0 0 } }
+column-line-color
 selection-required?
 selected-index selected-value
 mouse-index
@@ -51,7 +51,8 @@ focused? ;
         swap >>model
         f <model> >>selected-value
         sans-serif-font >>font
-        focus-border-color >>focus-border-color ;
+        focus-border-color >>focus-border-color
+        transparent >>column-line-color ;
 
 <PRIVATE
 

basis/ui/pens/pens-docs.factor

@@ -16,9 +16,9 @@ ARTICLE: "ui-pen-protocol" "UI pen protocol"
 "The default value of these slots is the " { $link f } " singleton, which implements the above protocol by doing nothing."
 $nl
 "Some other pre-defined implementations:"
-{ $vocab-subsection "ui.pens.gradient" }
-{ $vocab-subsection "ui.pens.image" }
-{ $vocab-subsection "ui.pens.polygon" }
-{ $vocab-subsection "ui.pens.solid" }
-{ $vocab-subsection "ui.pens.tile" }
+{ $vocab-subsection "Gradient pens" "ui.pens.gradient" }
+{ $vocab-subsection "Image pens" "ui.pens.image" }
+{ $vocab-subsection "Polygon pens" "ui.pens.polygon" }
+{ $vocab-subsection "Solid pens" "ui.pens.solid" }
+{ $vocab-subsection "Tile pens" "ui.pens.tile" }
 "Custom implementations must follow the guidelines set forth in " { $link "ui-paint-custom" } "." ;

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

@@ -3,7 +3,7 @@ IN: ui.tools.browser
 
 ARTICLE: "ui-browser" "UI browser"
 "The browser is used to display Factor code, documentation, and vocabularies. The browser is opened when a word or articlelink presentation is clicked. It can also be opened using words:"
-{ $subsection com-follow }
+{ $subsection com-browse }
 { $subsection browser-window }
 { $command-map browser-gadget "toolbar" }
 { $command-map browser-gadget "scrolling" }

basis/ui/tools/debugger/debugger.factor

@@ -42,7 +42,7 @@ M: restart-renderer row-columns
 
 PRIVATE>
 
-: <debugger> ( error continuation restarts restart-hook -- gadget )
+: <debugger> ( error continuation restarts restart-hook -- debugger )
     vertical debugger new-track
         { 3 3 } >>gap
         swap >>restart-hook

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

@@ -5,7 +5,7 @@ IN: ui.tools.inspector
 ARTICLE: "ui-inspector-edit" "Editing slot values in the inspector"
 "Slot values can be edited in the inspector. Clicking the ellipsis to the left of the slot's textual representation displays a slot editor gadget. A text representation of the object can be edited in the slot editor. The parser is used to turn the text representation back into an object. Keep in mind that some structure is lost in the conversion; see " { $link "prettyprint-limitations" } "."
 $nl
-"The slot editor's text editing commands are standard; see " { $link "gadgets-editors" } "."
+"The slot editor's text editing commands are standard; see " { $link "ui.gadgets.editors" } "."
 $nl
 "The slot editor has a toolbar containing various commands."
 { $command-map slot-editor "toolbar" } ;

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

@@ -24,7 +24,7 @@ ARTICLE: "ui-listener" "UI listener"
 { $operations \ word }
 { $command-map interactor "quotation" }
 { $heading "Editing commands" }
-"The text editing commands are standard; see " { $link "gadgets-editors" } "."
+"The text editing commands are standard; see " { $link "ui.gadgets.editors" } "."
 { $heading "Implementation" }
 "Listeners are instances of " { $link listener-gadget } ". The listener consists of an output area (instance of " { $link pane } ") and an input area (instance of " { $link interactor } "). Clickable presentations can also be printed to the listener; see " { $link "ui-presentations" } "." ;
 

basis/ui/tools/tools.factor

@@ -2,7 +2,7 @@
 ! See http://factorcode.org/license.txt for BSD license.
 USING: memory system kernel tools.vocabs ui.tools.operations
 ui.tools.listener ui.tools.browser ui.tools.common
-ui.tools.walker ui.commands ui.gestures ui ;
+ui.tools.walker ui.commands ui.gestures ui ui.private ;
 IN: ui.tools
 
 : main ( -- )

basis/ui/ui-docs.factor

@@ -2,7 +2,7 @@ USING: help.markup help.syntax strings quotations debugger
 namespaces ui.backend ui.gadgets ui.gadgets.worlds
 ui.gadgets.tracks ui.gadgets.packs ui.gadgets.grids
 ui.gadgets.private math.rectangles colors ui.text fonts
-kernel ;
+kernel ui.private ;
 IN: ui
 
 HELP: windows
@@ -88,13 +88,12 @@ ARTICLE: "building-ui" "Building user interfaces"
 
 ARTICLE: "gadgets" "Pre-made UI gadgets"
 { $subsection "ui.gadgets.labels" }
-{ $subsection "gadgets-polygons" }
 { $subsection "ui.gadgets.borders" }
 { $subsection "ui.gadgets.labeled" }
 { $subsection "ui.gadgets.buttons" }
 { $subsection "ui.gadgets.sliders" }
 { $subsection "ui.gadgets.scrollers" }
-{ $subsection "gadgets-editors" }
+{ $subsection "ui.gadgets.editors" }
 { $subsection "ui.gadgets.menus" }
 { $subsection "ui.gadgets.panes" }
 { $subsection "ui.gadgets.presentations" }

basis/ui/ui.factor

@@ -8,6 +8,8 @@ ui.gadgets.tracks ui.gestures ui.backend ui.render ui.text
 ui.text.private ;
 IN: ui
 
+<PRIVATE
+
 ! Assoc mapping aliens to gadgets
 SYMBOL: windows
 
@@ -72,10 +74,6 @@ M: world ungraft*
     [ handle>> (close-window) ]
     [ reset-world ] tri ;
 
-: find-window ( quot -- world )
-    windows get values
-    [ gadget-child swap call ] with find-last nip ; inline
-
 : init-ui ( -- )
     <dlist> \ graft-queue set-global
     <dlist> \ layout-queue set-global
@@ -134,9 +132,17 @@ SYMBOL: ui-thread
     t \ ui-running set-global
     [ f \ ui-running set-global ] [ ] cleanup ; inline
 
+PRIVATE>
+
+: find-window ( quot -- world )
+    windows get values
+    [ gadget-child swap call ] with find-last nip ; inline
+
 : ui-running? ( -- ? )
     \ ui-running get-global ;
 
+<PRIVATE
+
 : update-ui-loop ( -- )
     [ ui-running? ui-thread get-global self eq? and ]
     [ ui-notify-flag get lower-flag update-ui ]
@@ -146,6 +152,21 @@ SYMBOL: ui-thread
     [ self ui-thread set-global update-ui-loop ]
     "UI update" spawn drop ;
 
+: start-ui ( quot -- )
+    call notify-ui-thread start-ui-thread ;
+
+: restore-windows ( -- )
+    [
+        windows get [ values ] [ delete-all ] bi
+        [ restore-world ] each
+        forget-rollover
+    ] (with-ui) ;
+
+: restore-windows? ( -- ? )
+    windows get empty? not ;
+
+PRIVATE>
+
 : open-world-window ( world -- )
     dup pref-dim >>dim dup relayout graft ;
 
@@ -166,26 +187,11 @@ HOOK: close-window ui-backend ( gadget -- )
 M: object close-window
     find-world [ ungraft ] when* ;
 
-: start-ui ( quot -- )
-    call notify-ui-thread start-ui-thread ;
-
 [
     f \ ui-running set-global
     <flag> ui-notify-flag set-global
 ] "ui" add-init-hook
 
-HOOK: (with-ui) ui-backend ( quot -- )
-
-: restore-windows ( -- )
-    [
-        windows get [ values ] [ delete-all ] bi
-        [ restore-world ] each
-        forget-rollover
-    ] (with-ui) ;
-
-: restore-windows? ( -- ? )
-    windows get empty? not ;
-
 : with-ui ( quot -- )
     ui-running? [ call ] [ '[ init-ui @ ] (with-ui) ] if ;
 

core/make/make-docs.factor

@@ -49,8 +49,8 @@ $nl
 { $subsection building }
 { $example
   "USING: make math.parser io ;"
-  "[ \"Language #\" % CHAR: \s , 5 # ] \"\" make print"
-  "Language #5"
+  "[ \"Language #\" % CHAR: \\s , 5 # ] \"\" make print"
+  "Language # 5"
 }
 { $subsection "make-philosophy" } ;