"core/io/buffer" require
"core/ui" require
"core/ui/tools" require
+ "core/ui/handbook" require
"core/compiler/" architecture get append require
"core/handbook" require
USING: help io kernel math namespaces parser prettyprint
-sequences ;
+sequences modules tools ;
+
+ARTICLE: "cookbook" "Factor cookbook"
+{ $list
+ { "The basic unit of code, corresponding to a \"function\" in other languages, is called a " { $emphasis "word" } " in Factor." }
+ { "Word take inputs from the stack, and leave output values on the stack. This is documented in a " { $emphasis "stack effect declaration" } ", for example " { $snippet "( x y -- z )" } " denotes that a word takes two inputs, with " { $snippet "y" } " at the top of the stack, and returns one output. See " { $link "effect-declaration" } " for details." }
+ { "You can load source files with " { $link run-file } ":"
+ { $code "\"my-program.factor\" run-file" } }
+ { { "You can load modules from " { $snippet "apps/" } ", " { $snippet "libs/" } " or " { $snippet "demos/" } " with " { $link require } ":" }
+ { $code "\"libs/httpd\" require" } }
+ { { "Some modules have a defined main entry point, and can be run just like applications in an operating system:" }
+ { $code "\"apps/tetris\" run-module" }
+ }
+ { { $link .s } " prints the contents of the stack." }
+ { { $link . } " prints the object at the top of the stack." }
+ { "If you are reading this from the Factor UI, take a look at " { $link "ui-tools" } "." }
+}
+{ $subsection "cookbook-syntax" }
+{ $subsection "cookbook-colon-defs" }
+{ $subsection "cookbook-combinators" }
+{ $subsection "cookbook-variables" }
+{ $subsection "cookbook-vocabs" }
+{ $subsection "cookbook-sources" }
+{ $subsection "cookbook-io" }
+{ $subsection "cookbook-philosophy" } ;
ARTICLE: "cookbook-syntax" "Basic syntax cookbook"
"The following is a simple snippet of Factor code:"
ARTICLE: "handbook" "Factor documentation"
{ $subsection "changes" }
-{ $heading "Survival guide" }
-{ $list
- { "The basic unit of code, corresponding to a \"function\" in other languages, is called a " { $emphasis "word" } " in Factor." }
- { "Word take inputs from the stack, and leave output values on the stack. This is documented in a " { $emphasis "stack effect declaration" } ", for example " { $snippet "( x y -- z )" } " denotes that a word takes two inputs, with " { $snippet "y" } " at the top of the stack, and returns one output. See " { $link "effect-declaration" } " for details." }
- { "You can load source files with " { $link run-file } ":"
- { $code "\"my-program.factor\" run-file" } }
- { { "You can load modules from " { $snippet "apps/" } ", " { $snippet "libs/" } " or " { $snippet "demos/" } " with " { $link require } ":" }
- { $code "\"libs/httpd\" require" } }
- { { "Some modules have a defined main entry point, and can be run just like applications in an operating system:" }
- { $code "\"apps/tetris\" run-module" }
- }
- { { $link .s } " prints the contents of the stack." }
- { { $link . } " prints the object at the top of the stack." }
- { "If you are reading this from the Factor UI, take a look at " { $link "ui-tools" } "." }
-}
-{ $heading "Cookbook" }
-{ $subsection "cookbook-syntax" }
-{ $subsection "cookbook-colon-defs" }
-{ $subsection "cookbook-combinators" }
-{ $subsection "cookbook-variables" }
-{ $subsection "cookbook-vocabs" }
-{ $subsection "cookbook-sources" }
-{ $subsection "cookbook-io" }
-{ $subsection "cookbook-philosophy" }
+"If you are new to Factor, please read the cookbook first."
+{ $subsection "cookbook" }
{ $heading "Language reference" }
{ $subsection "conventions" }
{ $subsection "syntax" }
{ $subsection "compiler" }
{ $heading "Graphical user interface" }
{ $subsection "ui-tools" }
+{ $subsection "gadgets" }
{ $heading "Currently-loaded contributed modules" }
{ $outliner [ modules-help ] }
{ $heading "Index" }
{ $subsection "article-index" }
-{ $subsection "primitive-index" }
{ $subsection "error-index" }
{ $subsection "type-index" }
-{ $subsection "class-index" } ;
+{ $subsection "class-index" }
+{ $subsection "primitive-index" } ;
ARTICLE: "article-index" "Article index"
{ $outliner [ articles get hash-keys ] } ;
"help.facts"
"tools.facts"
"words.facts"
- "ui/tools.facts"
- "ui/ui.facts"
} } ;
+++ /dev/null
-USING: gadgets gadgets-listener gadgets-browser gadgets-help
-gadgets-presentations gadgets-walker gadgets-dataflow
-gadgets-workspace help gadgets-panes gadgets-text listener
-definitions prettyprint io parser modules compiler words
-styles ;
-
-ARTICLE: "ui-presentations" "Presentations in the UI"
-"A " { $emphasis "presentation" } " is a graphical view of an object which is directly linked to the object in some way. The help article links you see in the documentation browser are presentations; and if you " { $link see } " a word in the UI listener, all words in the definition will themselves be presentations."
-$terpri
-"When you move the mouse over a presentation, it is highlighted with a rectangular border and a short summary of the object being presented is shown in the status bar (the summary is produced using the " { $link summary } " word)."
-$terpri
-"Clicking a presentation with the left mouse button invokes a default operation, which usually views the object in some way. For example, clicking a presentation of a word jumps to the word definition in the " { $link "ui-browser" } "."
-$terpri
-"Clicking and holding the right mouse button on a presentation displays a popup menu listing available operations."
-$terpri
-"Presentation gadgets can be constructed directly using the " { $link <presentation> } " word, and they can also be written to " { $link pane } " gadgets using the " { $link write-object } " word." ;
-
-ARTICLE: "ui-listener" "UI listener"
-"The graphical listener is based around the terminal listener (" { $link "listener" } ") and adds the following features:"
-{ $list
- "Input history"
- { "Completion (see " { $link "ui-completion" } ")" }
- { "Clickable presentations (see " { $link "ui-presentations" } ")" }
-}
-{ $heading "Listener commands" }
-{ $commands listener-gadget "toolbar" }
-{ $heading "Interactor commands" }
-{ $commands interactor "interactor" }
-{ $heading "Word commands" }
-"These commands operate on the token at the caret position in the input area."
-{ $commands interactor "words" }
-{ $heading "Quotation commands" }
-"These commands operate on the entire contents of the input area."
-{ $commands interactor "quotations" }
-{ $heading "Editing commands" }
-"The text editing commands are standard and are documented in the " { $link editor } " class."
-{ $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 } "), and a stack display kept up to date using a " { $link listener-hook } "." ;
-
-ARTICLE: "ui-browser" "UI definition browser"
-"The graphical browser displays word definitions. To show a word definition, click a presentation of a word or use the word and vocabulary completion popups to browse the dictionary (see " { $link "ui-completion" } ")."
-{ $commands browser "toolbar" }
-"Definition browsers are instances of " { $link browser } "." ;
-
-ARTICLE: "ui-help" "UI documentation browser"
-"The documentation browser is used to display Factor documentation, which is rooted at the " { $link "handbook" } " page."
-{ $commands help-gadget "toolbar" }
-"Documentation browsers are instances of " { $link help-gadget } "." ;
-
-ARTICLE: "ui-walker" "UI walker"
-"The walker single-steps through quotations. To use the walker, enter a piece of code in the listener's input area and press " { $snippet "C+A+w" } "."
-$terpri
-"The walker can travel backwards through time, and restore stacks. This does not undo side effects and therefore can only be used reliably on referentially transparent code."
-{ $commands walker-gadget "toolbar" }
-"Walkers are instances of " { $link walker-gadget } "." ;
-
-ARTICLE: "ui-dataflow" "UI dataflow tool"
-"The dataflow viewer displays the stack effect of a quotation in a graphical way. To use it, enter a piece of code in the listener's input area and press " { $snippet "C+A+d" } ", or click the " { $strong "Dataflow" } " button in a definition tile shown by the UI browser."
-$terpri
-"Only quotations and words for which a stack effect can be inferred can be viewed. See " { $link "inference" } "."
-$terpri
-"The dataflow viewer displays the dataflow intermediate representation output by the compiler's optimizer. Therefore inlining and various other optimizations will have already been performed, and the visual representation may not resemble your original code in many ways. An upside of this arrangement is that the dataflow viewer can be used to predict how fast the code will run, because you will see which layers of generic dispatch have been optimized out at compile time."
-{ $commands dataflow-gadget "toolbar" }
-"Dataflow viewers are instances of " { $link dataflow-gadget } "." ;
-
-ARTICLE: "ui-cocoa" "Functionality specific to Mac OS X"
-"On Mac OS X, the Factor UI offers additional features which integrate with this operating system."
-$terpri
-"First, a standard Mac-style menu bar is provided, which offers the bare minimum of what you would expect from a Mac OS X application."
-$terpri
-"Dropping a source file onto the Factor icon in the dock runs the source file in the listener."
-$terpri
-"If you install " { $strong "Factor.app" } " in your " { $strong "Applications" } " folder, then other applications will be able to call Factor via the System Services feature. For example, you can select some text in " { $strong "TextEdit.app" } ", then invoke the " { $strong "TextEdit->Services->Factor->Evaluate Selection" } " menu item, which will replace the selected text with the result of evaluating it in Factor."
-
-;
-
-ARTICLE: "ui-tool-tutorial" "UI tool tutorial"
-"The following is an example of a typical session with the UI which should give you a taste of its power:"
-{ $list
- { "You decide to refactor some code, and move a few words from a source file you have already loaded, into a new source file." }
- { "You press " { $snippet "C+e" } " in the listener, which displays a gadget where you can type part of a loaded file's name, and then press " { $snippet "RETURN" } " when the correct completion is highlighted. This opens the file in your editor." }
- { "You refactor your words, move them to a new source file, and load the new file using " { $link run-file } "." }
- { "Interactively testing the new code reveals a problem with one particular code snippet, so you enter it in the listener's input area, and press " { $snippet "C+A+w" } " to invoke the single stepper." }
- { "Single stepping through the code makes the problem obvious, so you right-click on a presentation of the broken word in the stepper, and choose " { $strong "Edit" } " from the resulting popup menu." }
- { "After fixing the problem in the source editor, you right click on the word in the stepper and invoke " { $strong "Reload" } "." }
-} ;
-
-ARTICLE: "ui-completion-words" "Word completion popup"
-"Clicking a word in the word completion popup displays the word definition in the " { $link "ui-browser" } ". Pressing " { $snippet "RETURN" } " with a word selected inserts the word name in the listener, along with a " { $link POSTPONE: USE: } " declaration (if necessary)."
-{ $operations word compound } ;
-
-ARTICLE: "ui-completion-vocabs" "Vocabulary completion popup"
-"Clicking a vocabulary in the vocabulary completion popup displays a list of words in the vocabulary in another " { $link "ui-completion-words" } ". Pressing " { $snippet "RETURN" } " adds the vocabulary to the current search path, just as if you invoked " { $link POSTPONE: USE: } "."
-{ $operations vocab-link } ;
-
-ARTICLE: "ui-completion-modules" "Module completion popup"
-"The module completion popup lists loaded and unloaded modules, the list being obtained by calling the " { $link available-modules } " word. Clicking a module in the module completion popup loads the module first if necessary, and then displays a list of source files in a " { $link "ui-completion-sources" } ". Pressing " { $snippet "RETURN" } " loads the module first if necessary, and then runs the module's main entry point with " { $link run-module } "."
-{ $operations module } ;
-
-ARTICLE: "ui-completion-sources" "Source file completion popup"
-"The source file completion popup lists all source files which have been previously loaded by " { $link run-file } ". Clicking a source file or pressing " { $snippet "RETURN" } " opens the source file in your editor with " { $link edit-file } "."
-{ $operations pathname } ;
-
-ARTICLE: "ui-completion" "UI completion popups"
-"Completion popups allow fast access to aspects of the environment. Completion popups can be invoked by clicking the row of buttons along the bottom of the workspace, or via keyboard commands:"
-{ $commands workspace "toolbar" }
-"A completion popup instantly updates the list of completions as keys are typed. The list of completions can be navigated from the keyboard with the " { $snippet "UP" } " and " { $snippet "DOWN" } " arrow keys. Every completion has a " { $emphasis "primary action" } " and " { $emphasis "secondary action" } ". The primary action is invoked when clicking a completion, and the secondary action is invoked on the currently-selected completion when pressing " { $snippet "RETURN" } "."
-$terpri
-"The primary and secondary actions, along with additional keyboard shortcuts, are documented for some completion popups in the below sections."
-{ $subsection "ui-completion-words" }
-{ $subsection "ui-completion-vocabs" }
-{ $subsection "ui-completion-modules" }
-{ $subsection "ui-completion-sources" } ;
-
-ARTICLE: "ui-workspace-keys" "UI keyboard shortcuts"
-{ $heading "Switching tools" }
-{ $commands workspace "tool-switch" }
-{ $heading "Opening new windows" }
-"Multiple workspace windows can be open at once."
-{ $commands workspace "tool-window" }
-{ $heading "Scrolling" }
-"The current tool's scroll pane can be scrolled from the keyboard."
-{ $commands workspace "scrolling" }
-{ $heading "Workflow" }
-"A pair of commands for invoking " { $link reload-modules } " and " { $link recompile } "."
-{ $commands workspace "workflow" }
-{ $heading "Implementation" }
-"Workspaces are instances of " { $link workspace-window } "." ;
-
-ARTICLE: "ui-tools" "UI development tools"
-"The Factor development environment can seem rather different from what you are used to, because it is very simple and powerful.."
-$terpri
-"To take full advantage of the UI, you should be using a supported text editor, and load the correct editor integration module. See " { $link edit } "."
-{ $subsection "ui-tool-tutorial" }
-{ $subsection "ui-workspace-keys" }
-{ $subsection "ui-presentations" }
-{ $subsection "ui-completion" }
-{ $heading "Tools" }
-"All development tools are integrated into a single-window " { $emphasis "workspace" } "."
-{ $subsection "ui-listener" }
-{ $subsection "ui-browser" }
-{ $subsection "ui-help" }
-{ $subsection "ui-walker" }
-{ $subsection "ui-dataflow" }
-{ $subsection "ui-cocoa" } ;
+++ /dev/null
-ARTICLE: "models" "Models" ;
-
-ARTICLE: "clipboard-protocol" "Clipboard protocol" ;
-
-ARTICLE: "timers" "Timers" ;
-
-ARTICLE: "keyboard-gestures" "Keyboard gestures" ;
HELP: button
{ $class-description "A button is a " { $link gadget } " which responds to mouse clicks by invoking a quotation."
$terpri
-"The following words construct buttons:"
-{ $list
- { $link <button> }
- { $link <roll-button> }
- { $link <bevel-button> }
- { $link <command-button> }
- { $link <presentation> }
- { $link <repeat-button> }
-}
"A button's appearance can vary depending on the state of the mouse button if the " { $link gadget-interior } " or " { $link gadget-boundary } " slots are set to instances of " { $link button-paint } "."
$terpri
"A button can be selected, which is distinct from being pressed. This state is held in the " { $link button-selected? } " slot, and is used by the " { $link <radio-box> } " word to construct a row of buttons for choosing among several alternatives." } ;
{ $class-description "A class implementing the " { $link draw-interior } " generic word to draw a single vertical line." } ;
HELP: outliner
-{ $class-description "A gadget with an expander arrow which can be clicked to show and hide a child gadget generated by the quotation stored in the " { $link outliner-quot } " slot. Outliners are created by calling " { $link <outliner> } "." }
+{ $class-description "An outliner is a " { $link gadget } " with an expander arrow which can be clicked to show and hide a child gadget generated by the quotation stored in the " { $link outliner-quot } " slot. Outliners are created by calling " { $link <outliner> } "." }
{ $see-also <outliner> "presentations" } ;
HELP: <expand-button>
--- /dev/null
+USING: gadgets gadgets-labels gadgets-buttons gadgets-sliders
+gadgets-panes gadgets-lists gadgets-text gadgets-borders
+gadgets-presentations gadgets-scrolling gadgets-outliners help ;
+
+ARTICLE: "gadgets" "UI gadgets"
+{ $subsection "gadgets-labels" }
+{ $subsection "gadgets-polygons" }
+{ $subsection "gadgets-borders" }
+{ $subsection "gadgets-buttons" }
+{ $subsection "gadgets-sliders" }
+{ $subsection "gadgets-scrolling" }
+{ $subsection "gadgets-editors" }
+{ $subsection "gadgets-panes" }
+{ $subsection "gadgets-presentations" }
+{ $subsection "gadgets-lists" }
+{ $subsection "gadgets-outliners" } ;
+
+ARTICLE: "gadgets-labels" "Label gadgets"
+"A label displays a piece of text, either a single line string or an array of line strings."
+{ $subsection label }
+{ $subsection <label> }
+{ $subsection <label-control> }
+{ $subsection label-string }
+{ $subsection set-label-string } ;
+
+ARTICLE: "gadgets-polygons" "Polygon gadgets"
+"A polygon gadget renders a simple shaded polygon."
+{ $subsection polygon }
+{ $subsection <polygon> }
+{ $subsection <polygon-gadget> }
+"Some pre-made polygons:"
+{ $subsection arrow-up }
+{ $subsection arrow-right }
+{ $subsection arrow-down }
+{ $subsection arrow-left }
+{ $subsection close-box } ;
+
+ARTICLE: "gadgets-borders" "Border gadgets"
+"Border gadgets add empty space around a child gadget."
+{ $subsection border }
+{ $subsection <border> }
+{ $subsection <default-border> }
+"It is also possible to create a labelled border around a child gadget:"
+{ $subsection labelled-gadget }
+{ $subsection <labelled-gadget> }
+"Or a labelled border with a close box:"
+{ $subsection closable-gadget }
+{ $subsection <closable-gadget> } ;
+
+ARTICLE: "gadgets-buttons" "Button gadgets"
+"Buttons respond to mouse clicks by invoking a quotation."
+{ $subsection button }
+"There are many ways to create a new button:"
+{ $subsection <button> }
+{ $subsection <roll-button> }
+{ $subsection <bevel-button> }
+{ $subsection <command-button> }
+{ $subsection <repeat-button> }
+"A radio box is a row of buttons for choosing amongst several distinct possibilities:"
+{ $subsection <radio-box> }
+"Button appearance can be customized:"
+{ $subsection button-paint } ;
+
+ARTICLE: "gadgets-sliders" "Slider gadgets"
+"A slider allows the user to graphically manipulate a value by moving a thumb back and forth."
+{ $subsection slider }
+{ $subsection <x-slider> }
+{ $subsection <y-slider> }
+"Changing slider values:"
+{ $subsection set-slider }
+{ $subsection set-slider-value }
+{ $subsection slide-by }
+{ $subsection slide-by-line }
+{ $subsection slide-by-page } ;
+
+ARTICLE: "gadgets-scrolling" "Scroller gadgets"
+"A scroller displays a gadget which is larger than the visible area."
+{ $subsection scroller }
+{ $subsection <scroller> }
+"Getting and setting the scroll position:"
+{ $subsection scroller-value }
+{ $subsection scroll }
+"Writing scrolling-aware gadgets:"
+{ $subsection scroll>bottom }
+{ $subsection scroll>top }
+{ $subsection scroll>rect }
+{ $subsection find-scroller } ;
+
+ARTICLE: "gadgets-editors-selection" "The caret and mark"
+"If there is no selection, the caret and the mark are at the same location; otherwise the mark delimits the end-point of the selection opposite the caret."
+{ $subsection editor-caret }
+{ $subsection editor-caret* }
+{ $subsection editor-mark }
+{ $subsection editor-mark* }
+{ $subsection change-caret }
+{ $subsection change-caret&mark }
+{ $subsection mark>caret }
+"Getting and setting the selected text:"
+{ $subsection gadget-selection? }
+{ $subsection gadget-selection }
+{ $subsection user-input* }
+"Scrolling to the caret location:"
+{ $subsection scroll>caret } ;
+
+ARTICLE: "documents" "Documents"
+"The " { $link control-model } " of an " { $link editor } " is a " { $link document } "."
+{ $subsection document }
+{ $subsection <document> }
+"Getting and setting the contents of the entire document:"
+{ $subsection doc-string }
+{ $subsection set-doc-string }
+{ $subsection clear-doc }
+"Getting and setting subranges:"
+{ $subsection doc-line }
+{ $subsection doc-lines }
+{ $subsection doc-range }
+{ $subsection set-doc-range }
+{ $subsection remove-doc-range } ;
+
+ARTICLE: "document-locs-elts" "Locations and elements"
+"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:"
+{ $subsection +col }
+{ $subsection +line }
+{ $subsection =col }
+{ $subsection =line }
+"New locations can be created out of existing ones by finding the start or end of a document element nearest to a given location."
+{ $subsection prev-elt }
+{ $subsection next-elt }
+"The different types of document elements correspond to the standard editing taxonomy:"
+{ $subsection char-elt }
+{ $subsection one-word-elt }
+{ $subsection word-elt }
+{ $subsection one-line-elt }
+{ $subsection line-elt }
+{ $subsection doc-elt }
+"Miscellaneous words for working with locations:"
+{ $subsection lines-equal? }
+{ $subsection validate-loc } ;
+
+ARTICLE: "gadgets-editors" "Editor gadgets"
+"An editor edits a multi-line passage of text."
+{ $heading "General commands" }
+{ $commands editor "editing" }
+{ $heading "Caret motion commands" }
+{ $commands editor "caret" }
+{ $heading "Selection commands" }
+{ $commands editor "selection" }
+{ $heading "Editor words" }
+{ $subsection editor }
+{ $subsection <editor> }
+{ $subsection editor-string }
+{ $subsection set-editor-string }
+{ $subsection "gadgets-editors-selection" }
+{ $subsection "documents" }
+{ $subsection "document-locs-elts" } ;
+
+ARTICLE: "gadgets-panes" "Pane gadgets"
+"A pane displays formatted text."
+{ $subsection pane }
+{ $subsection <pane> }
+{ $subsection <scrolling-pane> }
+{ $subsection <pane-control> }
+{ $subsection <labelled-pane> }
+"Panes are written to by creating a special output stream:"
+{ $subsection pane-stream }
+{ $subsection <pane-stream> }
+"In addition to the stream output words (" { $link "stream-protocol" } ", pane streams can have gadgets written to them:"
+{ $subsection write-gadget }
+{ $subsection print-gadget }
+{ $subsection gadget. }
+"The " { $link gadget. } " word is useful for interactive debugging of gadgets in the listener."
+$terpri
+"There are a few combinators for working with panes:"
+{ $subsection with-pane }
+{ $subsection make-pane } ;
+
+ARTICLE: "gadgets-presentations" "Presentation gadgets"
+"Outliner gadgets are usually not constructed directly, and instead are written to " { $link "gadgets-panes" } " with formatted stream output words (" { $link "presentations" } ")."
+{ $subsection presentation }
+{ $subsection <presentation> }
+"If you want to display your own windows with mouse-over help for presentations, add this gadget to the window:"
+{ $subsection <presentation-help> } ;
+
+ARTICLE: "gadgets-lists" "List gadgets"
+"A list displays a list of presentations."
+{ $subsection list }
+{ $subsection <list> }
+{ $subsection list-value } ;
+
+ARTICLE: "gadgets-outliners" "Outliner gadgets"
+"Outliner gadgets are usually not constructed directly, and instead are written to " { $link "gadgets-panes" } " with formatted stream output words (" { $link "presentations" } ")."
+{ $subsection outliner }
+{ $subsection <outliner> }
+{ $subsection set-outliner-expanded? } ;
--- /dev/null
+PROVIDE: core/ui/handbook
+{ +files+ {
+ "tools.facts"
+ "gadgets.facts"
+ "ui.facts"
+} } ;
--- /dev/null
+USING: gadgets gadgets-listener gadgets-browser gadgets-help
+gadgets-presentations gadgets-walker gadgets-dataflow
+gadgets-workspace help gadgets-panes gadgets-text listener
+definitions prettyprint io parser modules compiler words
+styles ;
+
+ARTICLE: "ui-presentations" "Presentations in the UI"
+"A " { $emphasis "presentation" } " is a graphical view of an object which is directly linked to the object in some way. The help article links you see in the documentation browser are presentations; and if you " { $link see } " a word in the UI listener, all words in the definition will themselves be presentations."
+$terpri
+"When you move the mouse over a presentation, it is highlighted with a rectangular border and a short summary of the object being presented is shown in the status bar (the summary is produced using the " { $link summary } " word)."
+$terpri
+"Clicking a presentation with the left mouse button invokes a default operation, which usually views the object in some way. For example, clicking a presentation of a word jumps to the word definition in the " { $link "ui-browser" } "."
+$terpri
+"Clicking and holding the right mouse button on a presentation displays a popup menu listing available operations."
+$terpri
+"Presentation gadgets can be constructed directly using the " { $link <presentation> } " word, and they can also be written to " { $link pane } " gadgets using the " { $link write-object } " word." ;
+
+ARTICLE: "ui-listener" "UI listener"
+"The graphical listener is based around the terminal listener (" { $link "listener" } ") and adds the following features:"
+{ $list
+ "Input history"
+ { "Completion (see " { $link "ui-completion" } ")" }
+ { "Clickable presentations (see " { $link "ui-presentations" } ")" }
+}
+{ $heading "Listener commands" }
+{ $commands listener-gadget "toolbar" }
+{ $heading "Interactor commands" }
+{ $commands interactor "interactor" }
+{ $heading "Word commands" }
+"These commands operate on the token at the caret position in the input area."
+{ $commands interactor "words" }
+{ $heading "Quotation commands" }
+"These commands operate on the entire contents of the input area."
+{ $commands interactor "quotations" }
+{ $heading "Editing commands" }
+"The text editing commands are standard; see " { $link "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 } "), and a stack display kept up to date using a " { $link listener-hook } "." ;
+
+ARTICLE: "ui-browser" "UI definition browser"
+"The graphical browser displays word definitions. To show a word definition, click a presentation of a word or use the word and vocabulary completion popups to browse the dictionary (see " { $link "ui-completion" } ")."
+{ $commands browser "toolbar" }
+"Definition browsers are instances of " { $link browser } "." ;
+
+ARTICLE: "ui-help" "UI documentation browser"
+"The documentation browser is used to display Factor documentation, which is rooted at the " { $link "handbook" } " page."
+{ $commands help-gadget "toolbar" }
+"Documentation browsers are instances of " { $link help-gadget } "." ;
+
+ARTICLE: "ui-walker" "UI walker"
+"The walker single-steps through quotations. To use the walker, enter a piece of code in the listener's input area and press " { $snippet "C+A+w" } "."
+$terpri
+"The walker can travel backwards through time, and restore stacks. This does not undo side effects and therefore can only be used reliably on referentially transparent code."
+{ $commands walker-gadget "toolbar" }
+"Walkers are instances of " { $link walker-gadget } "." ;
+
+ARTICLE: "ui-dataflow" "UI dataflow tool"
+"The dataflow viewer displays the stack effect of a quotation in a graphical way. To use it, enter a piece of code in the listener's input area and press " { $snippet "C+A+d" } ", or click the " { $strong "Dataflow" } " button in a definition tile shown by the UI browser."
+$terpri
+"Only quotations and words for which a stack effect can be inferred can be viewed. See " { $link "inference" } "."
+$terpri
+"The dataflow viewer displays the dataflow intermediate representation output by the compiler's optimizer. Therefore inlining and various other optimizations will have already been performed, and the visual representation may not resemble your original code in many ways. An upside of this arrangement is that the dataflow viewer can be used to predict how fast the code will run, because you will see which layers of generic dispatch have been optimized out at compile time."
+{ $commands dataflow-gadget "toolbar" }
+"Dataflow viewers are instances of " { $link dataflow-gadget } "." ;
+
+ARTICLE: "ui-cocoa" "Functionality specific to Mac OS X"
+"On Mac OS X, the Factor UI offers additional features which integrate with this operating system."
+$terpri
+"First, a standard Mac-style menu bar is provided, which offers the bare minimum of what you would expect from a Mac OS X application."
+$terpri
+"Dropping a source file onto the Factor icon in the dock runs the source file in the listener."
+$terpri
+"If you install " { $strong "Factor.app" } " in your " { $strong "Applications" } " folder, then other applications will be able to call Factor via the System Services feature. For example, you can select some text in " { $strong "TextEdit.app" } ", then invoke the " { $strong "TextEdit->Services->Factor->Evaluate Selection" } " menu item, which will replace the selected text with the result of evaluating it in Factor."
+
+;
+
+ARTICLE: "ui-tool-tutorial" "UI tool tutorial"
+"The following is an example of a typical session with the UI which should give you a taste of its power:"
+{ $list
+ { "You decide to refactor some code, and move a few words from a source file you have already loaded, into a new source file." }
+ { "You press " { $snippet "C+e" } " in the listener, which displays a gadget where you can type part of a loaded file's name, and then press " { $snippet "RETURN" } " when the correct completion is highlighted. This opens the file in your editor." }
+ { "You refactor your words, move them to a new source file, and load the new file using " { $link run-file } "." }
+ { "Interactively testing the new code reveals a problem with one particular code snippet, so you enter it in the listener's input area, and press " { $snippet "C+A+w" } " to invoke the single stepper." }
+ { "Single stepping through the code makes the problem obvious, so you right-click on a presentation of the broken word in the stepper, and choose " { $strong "Edit" } " from the resulting popup menu." }
+ { "After fixing the problem in the source editor, you right click on the word in the stepper and invoke " { $strong "Reload" } "." }
+} ;
+
+ARTICLE: "ui-completion-words" "Word completion popup"
+"Clicking a word in the word completion popup displays the word definition in the " { $link "ui-browser" } ". Pressing " { $snippet "RETURN" } " with a word selected inserts the word name in the listener, along with a " { $link POSTPONE: USE: } " declaration (if necessary)."
+{ $operations word compound } ;
+
+ARTICLE: "ui-completion-vocabs" "Vocabulary completion popup"
+"Clicking a vocabulary in the vocabulary completion popup displays a list of words in the vocabulary in another " { $link "ui-completion-words" } ". Pressing " { $snippet "RETURN" } " adds the vocabulary to the current search path, just as if you invoked " { $link POSTPONE: USE: } "."
+{ $operations vocab-link } ;
+
+ARTICLE: "ui-completion-modules" "Module completion popup"
+"The module completion popup lists loaded and unloaded modules, the list being obtained by calling the " { $link available-modules } " word. Clicking a module in the module completion popup loads the module first if necessary, and then displays a list of source files in a " { $link "ui-completion-sources" } ". Pressing " { $snippet "RETURN" } " loads the module first if necessary, and then runs the module's main entry point with " { $link run-module } "."
+{ $operations module } ;
+
+ARTICLE: "ui-completion-sources" "Source file completion popup"
+"The source file completion popup lists all source files which have been previously loaded by " { $link run-file } ". Clicking a source file or pressing " { $snippet "RETURN" } " opens the source file in your editor with " { $link edit-file } "."
+{ $operations pathname } ;
+
+ARTICLE: "ui-completion" "UI completion popups"
+"Completion popups allow fast access to aspects of the environment. Completion popups can be invoked by clicking the row of buttons along the bottom of the workspace, or via keyboard commands:"
+{ $commands workspace "toolbar" }
+"A completion popup instantly updates the list of completions as keys are typed. The list of completions can be navigated from the keyboard with the " { $snippet "UP" } " and " { $snippet "DOWN" } " arrow keys. Every completion has a " { $emphasis "primary action" } " and " { $emphasis "secondary action" } ". The primary action is invoked when clicking a completion, and the secondary action is invoked on the currently-selected completion when pressing " { $snippet "RETURN" } "."
+$terpri
+"The primary and secondary actions, along with additional keyboard shortcuts, are documented for some completion popups in the below sections."
+{ $subsection "ui-completion-words" }
+{ $subsection "ui-completion-vocabs" }
+{ $subsection "ui-completion-modules" }
+{ $subsection "ui-completion-sources" } ;
+
+ARTICLE: "ui-workspace-keys" "UI keyboard shortcuts"
+{ $heading "Switching tools" }
+{ $commands workspace "tool-switch" }
+{ $heading "Opening new windows" }
+"Multiple workspace windows can be open at once."
+{ $commands workspace "tool-window" }
+{ $heading "Scrolling" }
+"The current tool's scroll pane can be scrolled from the keyboard."
+{ $commands workspace "scrolling" }
+{ $heading "Workflow" }
+"A pair of commands for invoking " { $link reload-modules } " and " { $link recompile } "."
+{ $commands workspace "workflow" }
+{ $heading "Implementation" }
+"Workspaces are instances of " { $link workspace-window } "." ;
+
+ARTICLE: "ui-tools" "UI development tools"
+"The Factor development environment can seem rather different from what you are used to, because it is very simple and powerful.."
+$terpri
+"To take full advantage of the UI, you should be using a supported text editor, and load the correct editor integration module. See " { $link edit } "."
+{ $subsection "ui-tool-tutorial" }
+{ $subsection "ui-workspace-keys" }
+{ $subsection "ui-presentations" }
+{ $subsection "ui-completion" }
+{ $heading "Tools" }
+"All development tools are integrated into a single-window " { $emphasis "workspace" } "."
+{ $subsection "ui-listener" }
+{ $subsection "ui-browser" }
+{ $subsection "ui-help" }
+{ $subsection "ui-walker" }
+{ $subsection "ui-dataflow" }
+{ $subsection "ui-cocoa" } ;
--- /dev/null
+ARTICLE: "models" "Models" ;
+
+ARTICLE: "clipboard-protocol" "Clipboard protocol" ;
+
+ARTICLE: "timers" "Timers" ;
+
+ARTICLE: "keyboard-gestures" "Keyboard gestures" ;
: doc-string ( document -- str )
model-value "\n" join ;
-: set-doc-lines ( seq document -- )
- [ set-model ] keep dup doc-end swap update-locs ;
-
: set-doc-string ( string document -- )
- >r string-lines r> set-doc-lines ;
+ >r string-lines r> [ set-model ] keep
+ dup doc-end swap update-locs ;
: clear-doc ( document -- )
"" swap set-doc-string ;
{ $values { "document" document } { "string" "a new " { $link 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 } }
-{ $description "Sets the contents of the document to an array of lines." }
-{ $side-effects "document" } ;
-
HELP: set-doc-string
{ $values { "array" "an array of strings" } { "document" document } }
{ $description "Sets the contents of the document to a string, which may use either " { $snippet "\\n" } ", " { $snippet "\\r\\n" } " or " { $snippet "\\r" } " line separators." }
{ $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" }
-{ $commands editor "editing" }
-{ $heading "Caret motion commands" }
-{ $commands editor "caret" }
-{ $heading "Selection commands" }
-{ $commands editor "selection" }
-{ $heading "Slots" }
"Editors have the following slots:"
{ $list
{ { $link editor-font } " - a font specifier." }
projects / factor.git / commitdiff