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" } "."
  53 $nl
  54 "If you want to add support for Emacs-style text entry, specifically the following:"
  55 $nl
  56 { $table
  57     { "Ctrl-k" "Delete to end of line" }
  58     { "Ctrl-a" "Move cursor to start of line" }
  59     { "Ctrl-e" "Move cursor to end of line" }
  60 }
  61 $nl
  62 "Then you can run the following code, or add it to your " { $link ".factor-rc" } "."
  63 $nl
  64 { $code
  65     "USING: accessors assocs kernel sequences sets ui.commands
  66 ui.gadgets.editors ui.gestures ui.tools.listener ;
  67
  68 \"multiline\" multiline-editor get-command-at [
  69     {
  70         { T{ key-down f { C+ } \"k\" } delete-to-end-of-line }
  71         { T{ key-down f { C+ } \"a\" } start-of-line }
  72         { T{ key-down f { C+ } \"e\" } end-of-line }
  73     } append members
  74 ] change-commands drop multiline-editor update-gestures
  75
  76 \"interactor\" interactor get-command-at [
  77     [ drop T{ key-down f { C+ } \"k\" } = ] assoc-reject
  78 ] change-commands drop interactor update-gestures"
  79 }
  80 $nl
  81 { $heading "Implementation" }
  82 "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" } "." ;
  83
  84 TIP: "You can read documentation by pressing " { $snippet "F1" } "." ;
  85
  86 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." ;
  87
  88 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." ;
  89
  90 TIP: "The status bar displays stack effects of recognized words as they are being typed in." ;
  91
  92 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: } "." ;
  93
  94 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." ;
  95
  96 TIP: "Scroll the listener from the keyboard by pressing " { $command listener-gadget "scrolling" com-page-up } " and " { $command listener-gadget "scrolling" com-page-down } "." ;
  97
  98 TIP: "Press " { $command tool "common" refresh-all } " or run " { $link refresh-all } " to reload changed source files from disk." ;
  99
 100 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." ;
 101
 102 ABOUT: "ui-listener"