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 ui.text colors fonts help.tips ;
   4 IN: ui.gadgets.editors
   5
   6 HELP: editor
   7 { $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> } "."
   8 $nl
   9 "Editors have the following slots:"
  10 { $list
  11     { { $snippet "font" } " - a " { $link font } "." }
  12     { { $snippet "color" } " - a " { $link color } "." }
  13     { { $snippet "caret-color" } " - a " { $link color } "." }
  14     { { $snippet "selection-color" } " - a " { $link color } "." }
  15     { { $snippet "caret" } " - a " { $link model } " storing a line/column pair." }
  16     { { $snippet "mark" } " - a " { $link 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." }
  17     { { $snippet "focused?" } " - a boolean." }
  18 } } ;
  19
  20 HELP: <editor>
  21 { $values { "editor" "a new " { $link editor } } }
  22 { $description "Creates a new " { $link editor } " with an empty document." } ;
  23
  24 { editor-caret editor-mark } related-words
  25
  26 HELP: editor-caret
  27 { $values { "editor" editor } { "loc" "a pair of integers" } }
  28 { $description "Outputs the current caret location as a line/column number pair." } ;
  29
  30 HELP: editor-mark
  31 { $values { "editor" editor } { "loc" "a pair of integers" } }
  32 { $description "Outputs the current mark location as a line/column number pair." } ;
  33
  34 HELP: change-caret
  35 { $values { "editor" editor } { "quot" { $quotation "( loc -- newloc )" } } }
  36 { $description "Applies a quotation to the current caret location and moves the caret to the location output by the quotation." } ;
  37
  38 { change-caret change-caret&mark mark>caret } related-words
  39
  40 HELP: mark>caret
  41 { $values { "editor" editor } }
  42 { $description "Moves the mark to the caret location, effectively deselecting any selected text." } ;
  43
  44 HELP: change-caret&mark
  45 { $values { "editor" editor } { "quot" { $quotation "( loc -- newloc )" } } }
  46 { $description "Applies a quotation to the current caret location and moves the caret and the mark to the location output by the quotation." } ;
  47
  48 HELP: point>loc
  49 { $values { "point" "a pair of integers" } { "editor" editor } { "loc" "a pair of integers" } }
  50 { $description "Converts a point to a line/column number pair." } ;
  51
  52 HELP: scroll>caret
  53 { $values { "editor" editor } }
  54 { $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 } "." } ;
  55
  56 HELP: remove-selection
  57 { $values { "editor" editor } }
  58 { $description "Removes currently selected text from the editor's " { $link document } "." } ;
  59
  60 HELP: editor-string
  61 { $values { "editor" editor } { "string" string } }
  62 { $description "Outputs the contents of the editor's " { $link document } " as a string. Lines are separated by " { $snippet "\\n" } "." } ;
  63
  64 HELP: set-editor-string
  65 { $values { "string" string } { "editor" editor } }
  66 { $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." } ;
  67
  68 ARTICLE: "gadgets-editors-selection" "The caret and mark"
  69 "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."
  70 { $subsections
  71     editor-caret
  72     editor-mark
  73     change-caret
  74     change-caret&mark
  75     mark>caret
  76 }
  77 "Getting the selected text:"
  78 { $subsections
  79     gadget-selection?
  80     gadget-selection
  81 }
  82 "Removing selected text:"
  83 { $subsections remove-selection }
  84 "Scrolling to the caret location:"
  85 { $subsections scroll>caret }
  86 "Use " { $link user-input* } " to change selected text." ;
  87
  88 ARTICLE: "gadgets-editors-contents" "Getting and setting editor contents"
  89 { $subsections
  90     editor-string
  91     set-editor-string
  92     clear-editor
  93 } ;
  94
  95 ARTICLE: "gadgets-editors-commands" "Editor gadget commands"
  96 { $command-map editor "editing" }
  97 { $command-map editor "caret-motion" }
  98 { $command-map editor "selection" }
  99 { $command-map editor "clipboard" }
 100 { $command-map multiline-editor "multiline" } ;
 101
 102 ARTICLE: "ui.gadgets.editors" "Editor gadgets"
 103 "The " { $vocab-link "ui.gadgets.editors" } " vocabulary implements editor gadgets. An editor edits a passage of text. Editors display a " { $link document } ". Editors are built from and inherit all features of " { $link "ui.gadgets.line-support" } "."
 104 { $subsections "gadgets-editors-commands" }
 105 "Editors:"
 106 { $subsections
 107     editor
 108     <editor>
 109     "gadgets-editors-contents"
 110     "gadgets-editors-selection"
 111 }
 112 "Multiline editors:"
 113 { $subsections <multiline-editor> }
 114 "Fields:"
 115 { $subsections
 116     <model-field>
 117     <action-field>
 118 }
 119 "Editors edit " { $emphasis "documents" } ":"
 120 { $subsections "documents" } ;
 121
 122 TIP: "Editor gadgets support undo and redo; press " { $command editor "editing" com-undo } " and " { $command editor "editing" com-redo } "." ;
 123
 124 TIP: "Learn the keyboard shortcuts used in " { $link "ui.gadgets.editors" } "." ;
 125
 126 ABOUT: "ui.gadgets.editors"