basis/ui/gadgets/editors/editors-docs.factor

   1 USING: documents help.markup help.syntax ui.gadgets
   2 ui.gadgets.scrollers models strings ui.commands ;
   3 IN: ui.gadgets.editors
   4
   5 HELP: editor
   6 { $class-description "An editor is a control for editing a multi-line passage of text stored in a " { $link document } " model. Editors are crated by calling " { $link <editor> } "."
   7 $nl
   8 "Editors have the following slots:"
   9 { $list
  10     { { $snippet "font" } " - a font specifier." }
  11     { { $snippet "color" } " - text color specifier." }
  12     { { $snippet "caret-color" } " - caret color specifier." }
  13     { { $snippet "selection-color" } " - selection background color specifier." }
  14     { { $snippet "caret" } " - a model storing a line/column pair." }
  15     { { $snippet "mark" } " - a model storing a line/column pair. If there is no selection, the mark is equal to the caret, otherwise the mark is located at the opposite end of the selection from the caret." }
  16     { { $snippet "focused?" } " - a boolean." }
  17 } } ;
  18
  19 HELP: <editor>
  20 { $values { "editor" "a new " { $link editor } } }
  21 { $description "Creates a new " { $link editor } " with an empty document." } ;
  22
  23 ! 'editor-caret' is now an old accessor, but it's documented as a word here. Maybe move this description somewhere else.
  24
  25 ! HELP: editor-caret ( editor -- caret )
  26 ! { $values { "editor" editor } { "caret" model } }
  27 ! { $description "Outputs a " { $link model } " holding the current caret location." } ;
  28
  29 { editor-caret* editor-mark* } related-words
  30
  31 HELP: editor-caret*
  32 { $values { "editor" editor } { "loc" "a pair of integers" } }
  33 { $description "Outputs the current caret location as a line/column number pair." } ;
  34
  35 ! HELP: editor-mark ( editor -- mark )
  36 ! { $values { "editor" editor } { "mark" model } }
  37 ! { $description "Outputs a " { $link model } " holding the current mark location." } ;
  38
  39 HELP: editor-mark*
  40 { $values { "editor" editor } { "loc" "a pair of integers" } }
  41 { $description "Outputs the current mark location as a line/column number pair." } ;
  42
  43 HELP: change-caret
  44 { $values { "editor" editor } { "quot" "a quotation with stack effect " { $snippet "( loc -- newloc )" } } }
  45 { $description "Applies a quotation to the current caret location and moves the caret to the location output by the quotation." } ;
  46
  47 { change-caret change-caret&mark mark>caret } related-words
  48
  49 HELP: mark>caret
  50 { $values { "editor" editor } }
  51 { $description "Moves the mark to the caret location, effectively deselecting any selected text." } ;
  52
  53 HELP: change-caret&mark
  54 { $values { "editor" editor } { "quot" "a quotation with stack effect " { $snippet "( loc -- newloc )" } } }
  55 { $description "Applies a quotation to the current caret location and moves the caret and the mark to the location output by the quotation." } ;
  56
  57 HELP: point>loc
  58 { $values { "point" "a pair of integers" } { "editor" editor } { "loc" "a pair of integers" } }
  59 { $description "Converts a point to a line/column number pair." } ;
  60
  61 HELP: scroll>caret
  62 { $values { "editor" editor } }
  63 { $description "Ensures that the caret becomes visible in a " { $link scroller } " containing the editor. Does nothing if no parent of " { $snippet "gadget" } " is a " { $link scroller } "." } ;
  64
  65 HELP: remove-selection
  66 { $values { "editor" editor } }
  67 { $description "Removes currently selected text from the editor's " { $link document } "." } ;
  68
  69 HELP: editor-string
  70 { $values { "editor" editor } { "string" string } }
  71 { $description "Outputs the contents of the editor's " { $link document } " as a string. Lines are separated by " { $snippet "\\n" } "." } ;
  72
  73 HELP: set-editor-string
  74 { $values { "string" string } { "editor" editor } }
  75 { $description "Sets the contents of the editor's " { $link document } " to a string,  which may use either " { $snippet "\\n" } ", " { $snippet "\\r\\n" } " or " { $snippet "\\r" } " line separators." } ;
  76
  77 ARTICLE: "gadgets-editors-selection" "The caret and mark"
  78 "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."
  79 { $subsection editor-caret* }
  80 { $subsection editor-mark* }
  81 { $subsection change-caret }
  82 { $subsection change-caret&mark }
  83 { $subsection mark>caret }
  84 "Getting the selected text:"
  85 { $subsection gadget-selection? }
  86 { $subsection gadget-selection }
  87 "Removing selected text:"
  88 { $subsection remove-selection }
  89 "Scrolling to the caret location:"
  90 { $subsection scroll>caret }
  91 "Use " { $link user-input* } " to change selected text." ;
  92
  93 ARTICLE: "gadgets-editors" "Editor gadgets"
  94 "An editor edits a multi-line passage of text."
  95 { $command-map editor "general" }
  96 { $command-map editor "caret-motion" }
  97 { $command-map editor "selection" }
  98 { $heading "Editor words" }
  99 { $subsection editor }
 100 { $subsection <editor> }
 101 { $subsection editor-string }
 102 { $subsection set-editor-string }
 103 { $subsection "gadgets-editors-selection" }
 104 { $subsection "documents" }
 105 { $subsection "document-locs-elts" } ;
 106
 107 ABOUT: "gadgets-editors"