basis/ui/tools/tools-docs.factor

   1 USING: editors help.markup help.syntax summary inspector io
   2 io.styles listener parser prettyprint tools.profiler
   3 tools.walker ui.commands ui.gadgets.editors ui.gadgets.panes
   4 ui.gadgets.presentations ui.gadgets.slots ui.operations
   5 ui.tools.browser ui.tools.interactor ui.tools.inspector
   6 ui.tools.listener ui.tools.operations ui.tools.profiler
   7 ui.tools.walker ui.tools.workspace vocabs ;
   8 IN: ui.tools
   9
  10 ARTICLE: "ui-presentations" "Presentations in the UI"
  11 "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."
  12 $nl
  13 "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)."
  14 $nl
  15 "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" } "."
  16 $nl
  17 "Clicking and holding the right mouse button on a presentation displays a popup menu listing available operations."
  18 $nl
  19 "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." ;
  20
  21 ARTICLE: "ui-listener" "UI listener"
  22 "The graphical listener is based around the terminal listener (" { $link "listener" } ") and adds the following features:"
  23 { $list
  24     "Input history"
  25     { "Completion (see " { $link "ui-completion" } ")" }
  26     { "Clickable presentations (see " { $link "ui-presentations" } ")" }
  27 }
  28 { $command-map listener-gadget "toolbar" }
  29 { $command-map interactor "interactor" }
  30 { $command-map source-editor "word" }
  31 { $command-map interactor "quotation" }
  32 { $heading "Editing commands" }
  33 "The text editing commands are standard; see " { $link "gadgets-editors" } "."
  34 { $heading "Implementation" }
  35 "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 } "." ;
  36
  37 ARTICLE: "ui-inspector" "UI inspector"
  38 "The graphical inspector builds on the terminal inspector (see " { $link "inspector" } ") and provides in-place editing of slot values."
  39 $nl
  40 "To display an object in the UI inspector, use the " { $link inspect } " word from the UI listener, or right-click a presentation and choose " { $strong "Inspect" } " from the menu that appears."
  41 $nl
  42 "When the UI inspector is running, all of the terminal inspector words are available, such as " { $link &at } " and " { $link &put } ". Changing slot values using terminal inspector words automatically updates the UI inspector display."
  43 $nl
  44 "Slots can also be edited graphically. 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" } "."
  45 $nl
  46 "The slot editor's text editing commands are standard; see " { $link "gadgets-editors" } "."
  47 $nl
  48 "The slot editor has a toolbar containing various commands."
  49 { $command-map slot-editor "toolbar" }
  50 { $command-map inspector-gadget "multi-touch" }
  51 "The following commands are also available."
  52 { $command-map source-editor "word" } ;
  53
  54 ARTICLE: "ui-browser" "UI browser"
  55 "The browser is used to display Factor code, documentation, and vocabularies."
  56 { $command-map browser-gadget "toolbar" }
  57 { $command-map browser-gadget "multi-touch" }
  58 "Browsers are instances of " { $link browser-gadget } "." ;
  59
  60 ARTICLE: "ui-profiler" "UI profiler"
  61 "The graphical profiler is based on the terminal profiler (see " { $link "profiling" } ") and adds more convenient browsing of profiler results."
  62 $nl
  63 "To use the profiler, enter a piece of code in the listener input area and press " { $operation com-profile } "."
  64 $nl
  65 "Vocabulary and word presentations in the profiler pane can be clicked on to show profiler results pertaining to the object in question. Clicking a vocabulary in the profiler yields the same output as the " { $link vocab-profile. } " word, and clicking a word yields the same output as the " { $link usage-profile. } " word. Consult " { $link "profiling" } " for details."
  66 { $command-map profiler-gadget "toolbar" } ;
  67
  68 ARTICLE: "ui-cocoa" "Functionality specific to Mac OS X"
  69 "On Mac OS X, the Factor UI offers additional features which integrate with this operating system."
  70 $nl
  71 "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."
  72 $nl
  73 "Dropping a source file onto the Factor icon in the dock runs the source file in the listener."
  74 $nl
  75 "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."
  76
  77 ;
  78
  79 ARTICLE: "ui-tool-tutorial" "UI tool tutorial"
  80 "The following is an example of a typical session with the UI which should give you a taste of its power:"
  81 { $list
  82     { "You decide to refactor some code, and move a few words from a source file you have already loaded, into a new source file." }
  83     { "You press " { $operation edit } " in the listener, which displays a gadget where you can type part of a loaded file's name, and then press " { $snippet "RET" } " when the correct completion is highlighted. This opens the file in your editor." }
  84     { "You refactor your words, move them to a new source file, and load the new file using " { $link run-file } "." }
  85     { "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 " { $operation walk } " to invoke the single stepper." }
  86     { "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 menu." }
  87     { "After fixing the problem in the source editor, you right click on the word in the stepper and invoke " { $strong "Reload" } " from the menu." }
  88 } ;
  89
  90 ARTICLE: "ui-completion-words" "Word completion popup"
  91 "Clicking a word in the word completion popup displays the word definition in the " { $link "ui-browser" } ". Pressing " { $snippet "RET" } " with a word selected inserts the word name in the listener, along with a " { $link POSTPONE: USE: } " declaration (if necessary)."
  92 { $operations \ $operations } ;
  93
  94 ARTICLE: "ui-completion-vocabs" "Vocabulary completion popup"
  95 "Clicking a vocabulary in the vocabulary completion popup displays a list of words in the vocabulary in another " { $link "ui-completion-words" } ". Pressing " { $snippet "RET" } " adds the vocabulary to the current search path, just as if you invoked " { $link POSTPONE: USE: } "."
  96 { $operations "kernel" vocab } ;
  97
  98 ARTICLE: "ui-completion-sources" "Source file completion popup"
  99 "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 "RET" } " opens the source file in your editor with " { $link edit } "."
 100 { $operations P" " } ;
 101
 102 ARTICLE: "ui-completion" "UI completion popups"
 103 "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:"
 104 { $command-map workspace "toolbar" }
 105 "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 "RET" } "."
 106 $nl
 107 "The primary and secondary actions, along with additional keyboard shortcuts, are documented for some completion popups in the below sections."
 108 { $subsection "ui-completion-words" }
 109 { $subsection "ui-completion-vocabs" }
 110 { $subsection "ui-completion-sources" } ;
 111
 112 ARTICLE: "ui-workspace-keys" "UI keyboard shortcuts"
 113 { $command-map workspace "tool-switching" }
 114 { $command-map workspace "scrolling" }
 115 { $command-map workspace "workflow" }
 116 { $command-map workspace "multi-touch" }
 117 { $heading "Implementation" }
 118 "Workspaces are instances of " { $link workspace } "." ;
 119
 120 ARTICLE: "ui-tools" "UI development tools"
 121 "The Factor development environment can seem rather different from what you are used to, because it is very simple and powerful.."
 122 $nl
 123 "To take full advantage of the UI, you should be using a supported text editor. See " { $link "editor" } "."
 124 { $subsection "ui-tool-tutorial" }
 125 { $subsection "ui-workspace-keys" }
 126 { $subsection "ui-presentations" }
 127 { $subsection "ui-completion" }
 128 { $heading "Tools" }
 129 "A single-window " { $emphasis "workspace" } " contains the most frequently-used tools:"
 130 { $subsection "ui-listener" }
 131 { $subsection "ui-browser" }
 132 { $subsection "ui-inspector" }
 133 { $subsection "ui-profiler" }
 134 "Additional tools:"
 135 { $subsection "ui-walker" }
 136 { $subsection "ui.tools.deploy" }
 137 "Platform-specific features:"
 138 { $subsection "ui-cocoa" } ;
 139
 140 ABOUT: "ui-tools"