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

   1 USING: help.markup help.syntax help.tips io kernel listener
   2 sequences system ui.commands ui.gadgets.editors ui.gadgets.panes
   3 ui.operations ui.tools.common ui.tools.listener.completion
   4 vocabs vocabs.refresh words ;
   5 IN: ui.tools.listener
   6
   7 HELP: <listener-gadget>
   8 { $values { "listener" listener-gadget } }
   9 { $description "Creates a new listener gadget." } ;
  10
  11 HELP: interactor
  12 { $class-description "An interactor is an " { $link editor } " intended to be used as the input component of a " { $link "ui-listener" } ". It has the following slots:"
  13 { $slots
  14   {
  15       "waiting"
  16       { "If waiting is " { $link t } ", the interactor is waiting for user input, and invoking " { $link evaluate-input } " resumes the thread." }
  17   }
  18 }
  19 "Interactors are created by calling " { $link <interactor> } "."
  20 $nl
  21 "Interactors implement the " { $link stream-readln } ", " { $link stream-read } " and " { $link stream-read-quot } " generic words." } ;
  22
  23 HELP: interactor-busy?
  24 { $values { "interactor" interactor } { "?" boolean } }
  25 { $description "We're busy if there's no thread to resume." } ;
  26
  27 HELP: interactor-read
  28 { $values { "interactor" interactor } { "lines" sequence } }
  29 { $description "Implements the " { $link stream-readln } " generic for the interactor." } ;
  30
  31 HELP: wait-for-listener
  32 { $values { "listener" listener-gadget } }
  33 { $description "Wait up to five seconds for the listener to start." } ;
  34
  35 ARTICLE: "ui-listener" "UI listener"
  36 "The graphical listener adds input history and word and vocabulary completion. A summary with any outstanding error conditions is displayed before every prompt (see " { $link "ui.tools.error-list" } " for details)."
  37 $nl
  38 "See " { $link "listener" } " for general information on the listener."
  39 { $command-map listener-gadget "toolbar" }
  40 { $command-map interactor "completion" }
  41 { $command-map interactor "interactor" }
  42 { $command-map listener-gadget "scrolling" }
  43 { $command-map listener-gadget "multi-touch" }
  44 { $heading "Word commands" }
  45 "These words operate on the word at the cursor."
  46 { $operations \ word }
  47 { $heading "Vocabulary commands" }
  48 "These words operate on the vocabulary at the cursor."
  49 { $operations T{ vocab-link f "kernel" } }
  50 { $command-map interactor "quotation" }
  51 { $heading "Editing commands" }
  52 "The text editing commands are standard; see " { $link "gadgets-editors-commands" } ", which include Readline style keybindings."
  53 $nl
  54 { $heading "Implementation" }
  55 "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" } "." ;
  56
  57 TIP: "You can read documentation by pressing " { $snippet "F1" } "." ;
  58
  59 TIP: "The listener tool remembers previous lines of input. Press " { $command interactor "completion" recall-previous } " and " { $command interactor "completion" recall-next } " to cycle through them." ;
  60
  61 TIP: "When you mouse over certain objects, a black border will appear. Left-clicking on such an object will perform the default operation. Right-clicking will show a menu with all operations." ;
  62
  63 TIP: "The status bar displays stack effects of recognized words as they are being typed in." ;
  64
  65 TIP: "Press " { $command interactor "completion" code-completion-popup } " to complete word, vocabulary and Unicode character names. The latter two features become available if the cursor is after a " { $link POSTPONE: USE: } ", " { $link POSTPONE: USING: } " or " { $link POSTPONE: CHAR: } "." ;
  66
  67 TIP: "If a word's vocabulary is loaded, but not in the search path, you can use restarts to add the vocabulary to the search path. Auto-use mode (" { $command listener-gadget "toolbar" com-auto-use } ") invokes restarts automatically if there is only one restart." ;
  68
  69 TIP: "Scroll the listener from the keyboard by pressing " { $command listener-gadget "scrolling" com-page-up } " and " { $command listener-gadget "scrolling" com-page-down } "." ;
  70
  71 TIP: "Press " { $command tool "common" refresh-all } " or run " { $link refresh-all } " to reload changed source files from disk." ;
  72
  73 TIP: "On Windows: use " { $snippet "C+Break" } " to interrupt tight loops in your code started in the listener, such as" { $code "[ t ] [ ] while" } "Caution: this may crash the Factor runtime if the code uses cooperative multitasking or asynchronous I/O." ;
  74
  75 ABOUT: "ui-listener"