doc/handbook/ui/tools.facts

   1 USING: gadgets gadgets-listener gadgets-browser gadgets-help
   2 gadgets-presentations gadgets-walker gadgets-dataflow
   3 gadgets-workspace help gadgets-panes gadgets-text listener
   4 definitions prettyprint io parser ;
   5
   6 ARTICLE: "ui-presentations" "Presentations in the UI"
   7 "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."
   8 $terpri
   9 "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)."
  10 $terpri
  11 "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" } "."
  12 $terpri
  13 "Clicking and holding the right mouse button on a presentation displays a popup menu listing available operations."
  14 $terpri
  15 "Presentation gadgets can be constructed directly using the " { $link <object-presentation> } " word, and they can also be written to " { $link pane } " gadgets using the " { $link write-object } " word." ;
  16
  17 ARTICLE: "ui-listener" "UI listener"
  18 "The graphical listener is based around the terminal listener (" { $link "listener" } ") and adds the following features:"
  19 { $list
  20     "Input history"
  21     "Completion"
  22     { "Clickable presentations (see " { $link "ui-presentations" } ")" }
  23 }
  24 "The below completion commands display a gadget at the bottom of the listener, known as the mini-buffer. Typing more text narrows down the list of available items. The " { $snippet "UP" } " and " { $snippet "DOWN" } " arrow keys shift the selection between listed items, and the " { $snippet "RETURN" } " key invokes a default operation for the selected item."
  25 { $commands listener-gadget }
  26 "The below word commands operate on the token at the caret position in the input area. The quotation commands operate on the entire contents of the input area."
  27 { $commands interactor }
  28 "Listeners are instances of " { $link listener-gadget } ". The listener consists of an output area (instance of " { $link pane } "), an input area (instance of " { $link interactor } "), and a stack display kept up to date using a " { $link listener-hook } "." ;
  29
  30 ARTICLE: "ui-browser" "UI definition browser"
  31 { $commands browser }
  32 "Definition browsers are instances of " { $link browser } "." ;
  33
  34 ARTICLE: "ui-help" "UI documentation browser"
  35 "The documentation browser is used to display Factor documentation, which is rooted at the " { $link "handbook" } " page."
  36 { $commands help-gadget }
  37 "Documentation browsers are instances of " { $link help-gadget } "." ;
  38
  39 ARTICLE: "ui-walker" "UI walker"
  40 "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" } "."
  41 $terpri
  42 "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."
  43 { $commands walker-gadget }
  44 "Walkers are instances of " { $link walker-gadget } "." ;
  45
  46 ARTICLE: "ui-dataflow" "UI dataflow tool"
  47 "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."
  48 $terpri
  49 "Only quotations and words for which a stack effect can be inferred can be viewed. See " { $link "inference" } "."
  50 $terpri
  51 "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."
  52 { $commands dataflow-gadget }
  53 "Dataflow viewers are instances of " { $link dataflow-gadget } "." ;
  54
  55 ARTICLE: "ui-cocoa" "Functionality specific to Mac OS X"
  56 "On Mac OS X, the Factor UI offers additional features which integrate with this operating system."
  57 $terpri
  58 "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."
  59 $terpri
  60 "Dropping a source file onto the Factor icon in the dock runs the source file in the listener."
  61 $terpri
  62 "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."
  63
  64 ;
  65
  66 ARTICLE: "ui-tools" "UI development tools"
  67 "The Factor development environment can seem rather different from what you are used to, however it is very simple and powerful."
  68 $terpri
  69 "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 } "."
  70 $terpri
  71 "The following is an example of a typical session with the UI which should give you a taste of its power:"
  72 { $list
  73     { "You decide to refactor some code, and move a few words from a source file you have already loaded, into a new source file." }
  74     { "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." }
  75     { "You refactor your words, move them to a new source file, and load the new file using " { $link run-file } "." }
  76     { "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." }
  77     { "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." }
  78     { "After fixing the problem in the source editor, you right click on the word in the stepper and invoke " { $strong "Reload" } "." }
  79 }
  80 "All development tools are integrated into a single-window " { $emphasis "workspace" } ". Multiple workspaces can be open at once, and keyboard commands are provided for switching between tools."
  81 { $commands workspace }
  82 "Workspaces are instances of " { $link workspace-window } "."
  83 { $subsection "ui-presentations" }
  84 { $subsection "ui-listener" }
  85 { $subsection "ui-browser" }
  86 { $subsection "ui-help" }
  87 { $subsection "ui-walker" }
  88 { $subsection "ui-dataflow" }
  89 { $subsection "ui-cocoa" } ;