X-Git-Url: https://gitweb.factorcode.org/gitweb.cgi?p=factor.git;a=blobdiff_plain;f=basis%2Fui%2Fgadgets%2Feditors%2Feditors-docs.factor;h=927e50682496b31a70f920b773531ea00a3f80af;hp=a17642ca45125928bf453211d9edf62eb7ce23a2;hb=ce7ac93667de16e9206a2140941b67a66886d117;hpb=8fd159dadd38d04bf3847fdc88b6633abedd0439 diff --git a/basis/ui/gadgets/editors/editors-docs.factor b/basis/ui/gadgets/editors/editors-docs.factor index a17642ca45..927e506824 100644 --- a/basis/ui/gadgets/editors/editors-docs.factor +++ b/basis/ui/gadgets/editors/editors-docs.factor @@ -1,21 +1,31 @@ -USING: documents help.markup help.syntax ui.gadgets -ui.gadgets.scrollers models strings ui.commands -ui.text colors fonts ; +USING: colors documents fonts help.markup help.syntax help.tips models +sequences strings ui.commands ui.gadgets ui.gadgets.line-support +ui.gadgets.scrollers ; IN: ui.gadgets.editors +HELP: +{ $values { "editor" multiline-editor } } +{ $description "Creates a new multi-line editor gadget." } ; + HELP: editor -{ $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 } "." +{ $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 } "." $nl "Editors have the following slots:" -{ $list - { { $snippet "font" } " - a " { $link font } "." } - { { $snippet "color" } " - a " { $link color } "." } - { { $snippet "caret-color" } " - a " { $link color } "." } - { { $snippet "selection-color" } " - a " { $link color } "." } - { { $snippet "caret" } " - a " { $link model } " storing a line/column pair." } - { { $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." } - { { $snippet "focused?" } " - a boolean." } -} } ; +{ $slots + { "caret" { "a " { $link model } " storing a line/column pair." } } + { "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." } } + { "focused?" { "a boolean." } } + { "preedit-start" { "a line/column pair or " { $link f } ". It represents the starting point of the string being edited by an input method." } } + { "preedit-end" { "a line/column pair or " { $link f } ". It represents the end point of the string being edited by an input method." } } + { "preedit-selected-start" { "a line/column pair or " { $link f } ". It represents the starting point of the string being selected by an input method." } } + { "preedit-selected-end" { "a line/column pair or " { $link f } ". It represents the end point of the string being selected by an input method." } } + { "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." } } + { "preedit-underlines" { "an array or " { $link f } ". It stores underline attributes for its preedit area." } } +} +$nl +" Slots that are prefixed with \"preedit-\" should not be modified directly. They are changed by the platform-dependent backend." +} +{ $see-also line-gadget } ; HELP: { $values { "editor" "a new " { $link editor } } } @@ -23,6 +33,29 @@ HELP: { editor-caret editor-mark } related-words +HELP: caret-is-shape +{ $description + "Shape is defined as line, box, or filled box" +} +$nl +{ $code +" IN: ui.gadgets.editors" +" 2 caret-is-shape set" +"" +} print-element +$nl +{ $table + { "Value" "Shape" } + { "f" "default (line)" } + { "0" "line" } + { "1" "box" } + { "2" "filled box" } +} print-element + +{ $references "Set desired shape in your .factor-rc file" + "rc-files" } + ; + HELP: editor-caret { $values { "editor" editor } { "loc" "a pair of integers" } } { $description "Outputs the current caret location as a line/column number pair." } ; @@ -32,7 +65,7 @@ HELP: editor-mark { $description "Outputs the current mark location as a line/column number pair." } ; HELP: change-caret -{ $values { "editor" editor } { "quot" { $quotation "( loc -- newloc )" } } } +{ $values { "editor" editor } { "quot" { $quotation ( loc document -- newloc ) } } } { $description "Applies a quotation to the current caret location and moves the caret to the location output by the quotation." } ; { change-caret change-caret&mark mark>caret } related-words @@ -42,7 +75,7 @@ HELP: mark>caret { $description "Moves the mark to the caret location, effectively deselecting any selected text." } ; HELP: change-caret&mark -{ $values { "editor" editor } { "quot" { $quotation "( loc -- newloc )" } } } +{ $values { "editor" editor } { "quot" { $quotation ( loc document -- newloc ) } } } { $description "Applies a quotation to the current caret location and moves the caret and the mark to the location output by the quotation." } ; HELP: point>loc @@ -57,55 +90,81 @@ HELP: remove-selection { $values { "editor" editor } } { $description "Removes currently selected text from the editor's " { $link document } "." } ; +HELP: +{ $values { "model" model } { "gadget" editor } } +{ $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." } ; + +HELP: +{ $values { "quot" { $quotation ( string -- ) } } { "gadget" editor } } +{ $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." } ; + + HELP: editor-string { $values { "editor" editor } { "string" string } } { $description "Outputs the contents of the editor's " { $link document } " as a string. Lines are separated by " { $snippet "\\n" } "." } ; + + HELP: set-editor-string { $values { "string" string } { "editor" editor } } -{ $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." } ; +{ $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." } ; ARTICLE: "gadgets-editors-selection" "The caret and mark" "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." -{ $subsection editor-caret } -{ $subsection editor-mark } -{ $subsection change-caret } -{ $subsection change-caret&mark } -{ $subsection mark>caret } +{ $subsections + editor-caret + editor-mark + change-caret + change-caret&mark + mark>caret +} "Getting the selected text:" -{ $subsection gadget-selection? } -{ $subsection gadget-selection } +{ $subsections + gadget-selection? + gadget-selection +} "Removing selected text:" -{ $subsection remove-selection } +{ $subsections remove-selection } "Scrolling to the caret location:" -{ $subsection scroll>caret } +{ $subsections scroll>caret } "Use " { $link user-input* } " to change selected text." ; ARTICLE: "gadgets-editors-contents" "Getting and setting editor contents" -{ $subsection editor-string } -{ $subsection set-editor-string } -{ $subsection clear-editor } ; +{ $subsections + editor-string + set-editor-string + clear-editor +} ; ARTICLE: "gadgets-editors-commands" "Editor gadget commands" { $command-map editor "editing" } { $command-map editor "caret-motion" } { $command-map editor "selection" } +{ $command-map editor "clipboard" } { $command-map multiline-editor "multiline" } ; -ARTICLE: "gadgets-editors" "Editor gadgets" -"The " { $vocab-link "ui.gadgets.editors" } " vocabulary implements editor gadgets. An editor edits a passage of text." -{ $subsection "gadgets-editors-commands" } +ARTICLE: "ui.gadgets.editors" "Editor gadgets" +"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" } "." +{ $subsections "gadgets-editors-commands" } "Editors:" -{ $subsection editor } -{ $subsection } -{ $subsection "gadgets-editors-contents" } -{ $subsection "gadgets-editors-selection" } +{ $subsections + editor + + "gadgets-editors-contents" + "gadgets-editors-selection" +} "Multiline editors:" -{ $subsection } +{ $subsections } "Fields:" -{ $subsection } -{ $subsection } +{ $subsections + + +} "Editors edit " { $emphasis "documents" } ":" -{ $subsection "documents" } ; +{ $subsections "documents" } ; + +TIP: "Editor gadgets support undo and redo; press " { $command editor "editing" com-undo } " and " { $command editor "editing" com-redo } "." ; + +TIP: "Learn the keyboard shortcuts used in " { $link "ui.gadgets.editors" } "." ; -ABOUT: "gadgets-editors" +ABOUT: "ui.gadgets.editors"