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

   1 USING: colors documents fonts help.markup help.syntax help.tips models
   2 sequences strings ui.commands ui.gadgets ui.gadgets.line-support
   3 ui.gadgets.scrollers ;
   4 IN: ui.gadgets.editors
   5
   6 HELP: <multiline-editor>
   7 { $values { "editor" multiline-editor } }
   8 { $description "Creates a new multi-line editor gadget." } ;
   9
  10 HELP: editor
  11 { $class-description "An editor is a control for editing a multi-line passage of text stored in a " { $link document } " model. Editors are created by calling " { $link <editor> } "."
  12 $nl
  13 "Editors have the following slots:"
  14 { $slots
  15     { "caret" { "a " { $link model } " storing a line/column pair." } }
  16     { "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     { "focused?" { "a boolean." } }
  18     { "preedit-start" { "a line/column pair or " { $link f } ". It represents the starting point of the string being edited by an input method." } }
  19     { "preedit-end" { "a line/column pair or " { $link f } ". It represents the end point of the string being edited by an input method." } }
  20     { "preedit-selected-start" { "a line/column pair or " { $link f } ". It represents the starting point of the string being selected by an input method." } }
  21     { "preedit-selected-end" { "a line/column pair or " { $link f } ". It represents the end point of the string being selected by an input method." } }
  22     { "preedit-selection-mode?" { "a boolean. It means the mode of selecting convertion canditate word. The caret in an editor is not drawn if it is true." } }
  23     { "preedit-underlines" { "an array or " { $link f } ". It stores underline attributes for its preedit area." } }
  24 }
  25 $nl
  26 " Slots that are prefixed with \"preedit-\" should not be modified directly. They are changed by the platform-dependent backend."
  27 }
  28 { $see-also line-gadget } ;
  29
  30 HELP: <editor>
  31 { $values { "editor" "a new " { $link editor } } }
  32 { $description "Creates a new " { $link editor } " with an empty document." } ;
  33
  34 { editor-caret editor-mark } related-words
  35
  36 HELP: caret-is-shape
  37 { $description
  38   "Shape is defined as line, box, or filled box"
  39 }
  40 $nl
  41 { $code
  42 "  IN: ui.gadgets.editors"
  43 "  +box+ caret-shape set-global"
  44 ""
  45 } print-element
  46 $nl
  47 { $table
  48   { "Value" "Shape" }
  49   { "+line+" "line (default)" }
  50   { "+box+" "box" }
  51   { "+filled+" "filled box" }
  52 } print-element
  53
  54 { $references   "Set desired shape in your .factor-rc file"
  55  "rc-files" }
  56     ;
  57
  58 HELP: editor-caret
  59 { $values { "editor" editor } { "loc" "a pair of integers" } }
  60 { $description "Outputs the current caret location as a line/column number pair." } ;
  61
  62 HELP: editor-mark
  63 { $values { "editor" editor } { "loc" "a pair of integers" } }
  64 { $description "Outputs the current mark location as a line/column number pair." } ;
  65
  66 HELP: change-caret
  67 { $values { "editor" editor } { "quot" { $quotation ( loc document -- newloc ) } } }
  68 { $description "Applies a quotation to the current caret location and moves the caret to the location output by the quotation." } ;
  69
  70 { change-caret change-caret&mark mark>caret } related-words
  71
  72 HELP: mark>caret
  73 { $values { "editor" editor } }
  74 { $description "Moves the mark to the caret location, effectively deselecting any selected text." } ;
  75
  76 HELP: change-caret&mark
  77 { $values { "editor" editor } { "quot" { $quotation ( loc document -- newloc ) } } }
  78 { $description "Applies a quotation to the current caret location and moves the caret and the mark to the location output by the quotation." } ;
  79
  80 HELP: point>loc
  81 { $values { "point" "a pair of integers" } { "editor" editor } { "loc" "a pair of integers" } }
  82 { $description "Converts a point to a line/column number pair." } ;
  83
  84 HELP: scroll>caret
  85 { $values { "editor" editor } }
  86 { $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 } "." } ;
  87
  88 HELP: remove-selection
  89 { $values { "editor" editor } }
  90 { $description "Removes currently selected text from the editor's " { $link document } "." } ;
  91
  92 HELP: <model-field>
  93 { $values { "model" model } { "gadget" editor } }
  94 { $description "Creates an editor gadget which targets the specified model. The model must contain a string, or another item with a defined " { $link length } ", as this will be checked during layout." } ;
  95
  96 HELP: <action-field>
  97 { $values { "quot" { $quotation ( string -- ) } } { "gadget" editor } }
  98 { $description "Creates an editor gadget with a blank model. Whenever a value is entered into the editor and Return pressed, the value is pushed on the stack as a string and the specified quotation is called. Note that the quotation cannot update the value in the field." } ;
  99
 100
 101 HELP: editor-string
 102 { $values { "editor" editor } { "string" string } }
 103 { $description "Outputs the contents of the editor's " { $link document } " as a string. Lines are separated by " { $snippet "\\n" } "." } ;
 104
 105
 106
 107 HELP: set-editor-string
 108 { $values { "string" string } { "editor" editor } }
 109 { $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." } ;
 110
 111 ARTICLE: "gadgets-editors-selection" "The caret and mark"
 112 "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."
 113 { $subsections
 114     editor-caret
 115     editor-mark
 116     change-caret
 117     change-caret&mark
 118     mark>caret
 119 }
 120 "Getting the selected text:"
 121 { $subsections
 122     gadget-selection?
 123     gadget-selection
 124 }
 125 "Removing selected text:"
 126 { $subsections remove-selection }
 127 "Scrolling to the caret location:"
 128 { $subsections scroll>caret }
 129 "Use " { $link user-input* } " to change selected text." ;
 130
 131 ARTICLE: "gadgets-editors-contents" "Getting and setting editor contents"
 132 { $subsections
 133     editor-string
 134     set-editor-string
 135     clear-editor
 136 } ;
 137
 138 ARTICLE: "gadgets-editors-commands" "Editor gadget commands"
 139 { $command-map editor "editing" }
 140 { $command-map editor "caret-motion" }
 141 { $command-map editor "selection" }
 142 { $command-map editor "clipboard" }
 143 { $command-map multiline-editor "multiline" } ;
 144
 145 ARTICLE: "ui.gadgets.editors" "Editor gadgets"
 146 "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" } "."
 147 { $subsections "gadgets-editors-commands" }
 148 "Editors:"
 149 { $subsections
 150     editor
 151     <editor>
 152     "gadgets-editors-contents"
 153     "gadgets-editors-selection"
 154 }
 155 "Multiline editors:"
 156 { $subsections <multiline-editor> }
 157 "Fields:"
 158 { $subsections
 159     <model-field>
 160     <action-field>
 161 }
 162 "Editors edit " { $emphasis "documents" } ":"
 163 { $subsections "documents" } ;
 164
 165 TIP: "Editor gadgets support undo and redo; press " { $command editor "editing" com-undo } " and " { $command editor "editing" com-redo } "." ;
 166
 167 TIP: "Learn the keyboard shortcuts used in " { $link "ui.gadgets.editors" } "." ;
 168
 169 ABOUT: "ui.gadgets.editors"