constructor
(new text% [ [line-spacing line-spacing] [tab-stops tab-stops] [auto-wrap auto-wrap]]) → (is-a?/c text%) line-spacing : (and/c real? (not/c negative?)) = 1.0 tab-stops : (listof real?) = null auto-wrap : any/c = #f
See set-tabs for information about tabstops.
If auto-wrap is true, then auto-wrapping is enabled via auto-wrap.
A new keymap% object is created for the new editor. See also get-keymap and set-keymap.
A new style-list% object is created for the new editor. See also get-style-list and set-style-list.
method
(send a-text after-change-style start len) → void?
start : exact-nonnegative-integer? len : exact-nonnegative-integer?
See also can-change-style? and on-edit-sequence.
No internals locks are set when this method is called.
Default implementation: Does nothing.
method
(send a-text after-delete start len) → void?
start : exact-nonnegative-integer? len : exact-nonnegative-integer?
The start argument specifies the starting position of the deleted range. The len argument specifies number of deleted items (so start+len is the ending position of the deleted range).
See also can-delete? and on-edit-sequence.
No internals locks are set when this method is called.
Default implementation: Does nothing.
method
(send a-text after-insert start len) → void?
start : exact-nonnegative-integer? len : exact-nonnegative-integer?
The start argument specifies the position of the insert. The len argument specifies the total length (in positions) of the inserted items.
See also can-insert? and on-edit-sequence.
No internals locks are set when this method is called.
Default implementation: Does nothing.
method
(send a-text after-merge-snips pos) → void?
pos : exact-nonnegative-integer?
The pos argument specifies the position within the editor where the snips were merged (i.e., one old snip was just before pos, one old was just after pos, and the new snip spans pos).
See also merge-with.
Default implementation: Does nothing.
method
(send a-text after-set-position) → void?
See also on-edit-sequence.
Default implementation: Does nothing.
method
(send a-text after-set-size-constraint) → void?
(This callback method is provided because setting an editor’s maximum width may cause lines to be re-flowed with soft newlines.)
See also can-set-size-constraint? and on-edit-sequence.
Default implementation: Does nothing.
method
(send a-text after-split-snip pos) → void?
pos : exact-nonnegative-integer?
The pos argument specifies the position within the editor where a snip was split.
Default implementation: Does nothing.
method
(send a-text call-clickback start end) → void?
start : exact-nonnegative-integer? end : exact-nonnegative-integer?
method
(send a-text can-change-style? start len) → boolean?
start : exact-nonnegative-integer? len : exact-nonnegative-integer?
The editor is internally locked for writing during a call to this method (see also Internal Editor Locks). Use after-change-style to modify the editor, if necessary.
See also on-change-style, after-change-style, and on-edit-sequence.
Default implementation: Returns #t.
method
(send a-text can-delete? start len) → boolean?
start : exact-nonnegative-integer? len : exact-nonnegative-integer?
The start argument specifies the starting position of the range to delete. The len argument specifies number of items to delete (so start+len is the ending position of the range to delete).
The editor is internally locked for writing during a call to this method (see also Internal Editor Locks). Use after-delete to modify the editor, if necessary.
See also on-delete, after-delete, and on-edit-sequence.
Default implementation: Returns #t.
method
(send a-text can-insert? start len) → boolean?
start : exact-nonnegative-integer? len : exact-nonnegative-integer?
The start argument specifies the position of the potential insert. The len argument specifies the total length (in positions) of the items to be inserted.
The editor is internally locked for writing during a call to this method (see also Internal Editor Locks). Use after-insert to modify the editor, if necessary.
See also on-insert, after-insert, and on-edit-sequence.
Default implementation: Returns #t.
method
(send a-text can-set-size-constraint?) → boolean?
(This callback method is provided because setting an editor’s maximum width may cause lines to be re-flowed with soft newlines.)
See also on-set-size-constraint, after-set-size-constraint, and on-edit-sequence.
Default implementation: Returns #t.
method
(send a-text caret-hidden?) → boolean?
See also hide-caret.
method
(send a-text change-style delta [ start end counts-as-mod?]) → void? delta : (or/c (is-a?/c style-delta%) #f) start : (or/c exact-nonnegative-integer? 'start) = 'start end : (or/c exact-nonnegative-integer? 'end) = 'end counts-as-mod? : any/c = #t
(send a-text change-style style [ start end counts-as-mod?]) → void? style : (or/c (is-a?/c style<%>) #f) start : (or/c exact-nonnegative-integer? 'start) = 'start end : (or/c exact-nonnegative-integer? 'end) = 'end counts-as-mod? : any/c = #t
To change a large collection of snips from one style to another style, consider providing a style<%> instance rather than a style-delta% instance. Otherwise, change-style must convert the style-delta% instance to the style<%> instance for every snip; this conversion consumes both time and (temporary) memory.
When style is provided: The editor’s style list must contain style, otherwise the style is not changed. See also convert in style-list%.
method
extend? : any/c = #f time : exact-integer? = 0 start : (or/c exact-nonnegative-integer? 'start) = 'start end : (or/c exact-nonnegative-integer? 'end) = 'end
See Cut and Paste Time Stamps for a discussion of the time argument. If time is outside the platform-specific range of times, an exn:fail:contract exception is raised.
method
(send a-text copy-self-to dest) → void?
dest : (or/c (is-a?/c text%) (is-a?/c pasteboard%))
method
extend? : any/c = #f time : exact-integer? = 0 start : (or/c exact-nonnegative-integer? 'start) = 'start end : (or/c exact-nonnegative-integer? 'end) = 'end
See Cut and Paste Time Stamps for a discussion of the time argument. If time is outside the platform-specific range of times, an exn:fail:contract exception is raised.
method
start : (or/c exact-nonnegative-integer? 'start) end : (or/c exact-nonnegative-integer? 'back) = 'back scroll-ok? : any/c = #t (send a-text delete) → void?
The content of an editor can be changed by the system in response to other method calls, and such changes do not go through this method; use on-delete to monitor content deletion changes.
method
start : exact-nonnegative-integer? end : exact-nonnegative-integer? time : exact-integer? extend? : any/c
See Cut and Paste Time Stamps for a discussion of the time argument. If time is outside the platform-specific range of times, an exn:fail:contract exception is raised.
Default implementation: Copy the data from start to end, extending the current clipboard contexts if extend? is not #f.
method
start : exact-nonnegative-integer? time : exact-integer?
See Cut and Paste Time Stamps for a discussion of the time argument. If time is outside the platform-specific range of times, an exn:fail:contract exception is raised.
Default implementation: Pastes into the position start.
method
(send a-text do-paste-x-selection start time) → void? start : exact-nonnegative-integer? time : exact-integer?
See Cut and Paste Time Stamps for a discussion of the time argument. If time is outside the platform-specific range of times, an exn:fail:contract exception is raised.
Default implementation: Pastes into the position start.
See also delete.
method
(send a-text extend-position pos) → void?
pos : exact-nonnegative-integer?
If pos is before the extend start and extend end positions, then the selection goes from pos to the extend end position. If it is after, then the selection goes from the extend start position to pos.
Use this method to implement shift-modified movement keys in order to properly extend the selection.
method
(send a-text find-line y [on-it?]) → exact-nonnegative-integer?
y : real? on-it? : (or/c (box/c any/c) #f) = #f
The on-it? box is filled with #t if the line actually touches this position, or #f otherwise, unless on-it? is #f. (A large enough y will always return the last line number, but will set on-it? to #f.)
The result is only valid when the editor is displayed (see Editor Structure and Terminology). Editors are displayed when get-admin returns an administrator (not #f). Calling this method may force the recalculation of location information, even if the editor currently has delayed refreshing (see refresh-delayed?).
method
(send a-text find-newline [ direction start end]) → (or/c exact-nonnegative-integer? #f) direction : (or/c 'forward 'backward) = 'forward start : (or/c exact-nonnegative-integer? 'start) = 'start end : (or/c exact-nonnegative-integer? 'eof) = 'eof
method
(send a-text find-next-non-string-snip after)
→ (or/c (is-a?/c snip%) #f) after : (or/c (is-a?/c snip%) #f)
method
(send a-text find-position x y [ at-eol? on-it? edge-close?]) → exact-nonnegative-integer? x : real? y : real? at-eol? : (or/c (box/c any/c) #f) = #f on-it? : (or/c (box/c any/c) #f) = #f edge-close? : (or/c (box/c real?) #f) = #f
See End of Line Ambiguity for a discussion of the at-eol? argument. The on-it? box is filled with #t if the line actually touches this position, or #f otherwise, unless on-it? is #f.
The edge-close? box is filled with it will be filled in with a value indicating how close the point is to the vertical edges of the item when the point falls on the item, unless edge-close? is #f. If the point is closest to the left edge of the item, the value will be negative; otherwise, the value will be positive. In either case, then absolute value of the returned result is the distance from the point to the edge of the item. The values 100 and -100 indicate infinity.
The result is only valid when the editor is displayed (see Editor Structure and Terminology). Editors are displayed when get-admin returns an administrator (not #f). Calling this method may force the recalculation of location information, even if the editor currently has delayed refreshing (see refresh-delayed?).
method
(send a-text find-position-in-line line x [ at-eol? on-it? edge-close?]) → exact-nonnegative-integer? line : exact-nonnegative-integer? x : real? at-eol? : (or/c (box/c any/c) #f) = #f on-it? : (or/c (box/c any/c) #f) = #f edge-close? : (or/c (box/c real?) #f) = #f
See End of Line Ambiguity for a discussion of the at-eol? argument. The on-it? box is filled with #t if the line actually touches this position, or #f otherwise, unless on-it? is #f.
See find-position for a discussion of edge-close?.
The result is only valid when the editor is displayed (see Editor Structure and Terminology). Editors are displayed when get-admin returns an administrator (not #f). Calling this method may force the recalculation of location information, even if the editor currently has delayed refreshing (see refresh-delayed?).
method
→ (or/c (is-a?/c snip%) #f) pos : exact-nonnegative-integer? direction : (or/c 'before-or-none 'before 'after 'after-or-none) s-pos : (or/c (box/c exact-nonnegative-integer?) #f) = #f
'before-or-none —
returns the snip before the position, or #f if pos is 0 'before —
returns the snip before the position, or the first snip if pos is 0 'after —
returns the snip after the position, or the last snip if pos is the last position 'after-or-none – returns the snip after the position, or #f if pos is the last position or larger
The s-pos box is filled with the position where the returned snip starts, unless s-pos is #f.
method
(send a-text find-string str [ direction start end get-start? case-sensitive?]) → (or/c exact-nonnegative-integer? #f) str : string? direction : (or/c 'forward 'backward) = 'forward start : (or/c exact-nonnegative-integer? 'start) = 'start end : (or/c exact-nonnegative-integer? 'eof) = 'eof get-start? : any/c = #t case-sensitive? : any/c = #t
The direction argument can be 'forward or 'backward, indicating a forward search or backward search respectively. In the case of a forward search, the return value is the starting position of the string; for a backward search, the ending position is returned. However, if get-start? is #f, then the other end of the string position will be returned.
The start and end arguments set the starting and ending positions of a forward search (use start > end for a backward search). If start is 'start, then the search starts at the start of the selection. If end is 'eof, then the search continues to the end (for a forward search) or start (for a backward search) of the editor.
If case-sensitive? is #f, then an uppercase and lowercase of each alphabetic character are treated as equivalent.
method
(send a-text find-string-embedded str [ direction start end get-start? case-sensitive?])
→
(or/c exact-nonnegative-integer? #f (cons/c (is-a?/c editor<%>) (flat-rec-contract nested-editor-search-result (or/c (cons/c (is-a?/c editor<%>) nested-editor-search-result) exact-nonnegative-integer?)))) str : string? direction : (or/c 'forward 'backward) = 'forward start : (or/c exact-nonnegative-integer? 'start) = 'start end : (or/c exact-nonnegative-integer? 'eof) = 'eof get-start? : any/c = #t case-sensitive? : any/c = #t
method
(send a-text find-string-all str [ direction start end get-start? case-sensitive]) → (listof exact-nonnegative-integer?) str : string? direction : (or/c 'forward 'backward) = 'forward start : (or/c exact-nonnegative-integer? 'start) = 'start end : (or/c exact-nonnegative-integer? 'eof) = 'eof get-start? : any/c = #t case-sensitive : any/c = #t
method
(send a-text find-string-embedded-all str [ direction start end get-start? case-sensitive])
→
(listof (or/c exact-nonnegative-integer? (cons/c (is-a?/c editor<%>) (flat-rec-contract nested-editor-search-result (or/c (cons/c (is-a?/c editor<%>) nested-editor-search-result) (listof exact-nonnegative-integer?)))))) str : string? direction : (or/c 'forward 'backward) = 'forward start : (or/c exact-nonnegative-integer? 'start) = 'start end : (or/c exact-nonnegative-integer? 'eof) = 'eof get-start? : any/c = #t case-sensitive : any/c = #t
method
(send a-text find-wordbreak start end reason) → void? start : (or/c (box/c exact-nonnegative-integer?) #f) end : (or/c (box/c exact-nonnegative-integer?) #f) reason : (or/c 'caret 'line 'selection 'user1 'user2)
The contents of the start argument specifies an position to start searching backwards to the next word start; its will be filled with the starting position of the word that is found. If start is #f, no backward search is performed.
The contents of the end argument specifies an position to start searching forwards to the next word end; its will be filled with the ending position of the word that is found. If end is #f, no forward search is performed.
The reason argument specifies more information about what the wordbreak is used for. For example, the wordbreaks used to move the caret may be different from the wordbreaks used to break lines. The possible values of reason are:
'caret —
find a wordbreak suitable for moving the caret 'line —
find a wordbreak suitable for breaking lines 'selection —
find a wordbreak suitable for selecting the closest word 'user1 —
for other (not built-in) uses 'user2 —
for other (not built-in) uses
The actual handling of reason is controlled by the current wordbreak procedure; see set-wordbreak-funcfor details. The default handler and default wordbreak map treats alphanumeric characters the same for 'caret, 'line, and 'selection. Non-alphanumeric, non-space, non-hyphen characters do not break lines, but do break caret and selection words. For example a comma should not be counted as part of the preceding word for moving the caret past the word or double-clicking the word, but the comma should stay on the same line as the word (and thus counts in the same “line word”).
method
(send a-text flash-on start end [ at-eol? scroll? timeout]) → void? start : exact-nonnegative-integer? end : exact-nonnegative-integer? at-eol? : any/c = #f scroll? : any/c = #t timeout : exact-nonnegative-integer? = 500
See End of Line Ambiguity for a discussion of the at-eol? argument. If scroll? is not #f, the editor’s display will be scrolled if necessary to show the hilited region. If timeout is greater than 0, then the hiliting will be automatically turned off after the given number of milliseconds.
See also flash-off.
method
(send a-text get-anchor) → boolean?
See also set-between-threshold.
method
(send a-text get-character start) → char?
start : exact-nonnegative-integer?
If start is greater than or equal to the last position, #\nul is returned.
method
(send a-text get-end-position) → exact-nonnegative-integer?
method
(send a-text get-extend-start-position)
→ exact-nonnegative-integer?
method
(send a-text get-extend-end-position)
→ exact-nonnegative-integer?
method
(send a-text get-file-format)
→ (or/c 'standard 'text 'text-force-cr)
method
(send a-text get-overwrite-mode) → boolean?
method
(send a-text get-padding) →
(and/c real? (not/c negative?)) (and/c real? (not/c negative?)) (and/c real? (not/c negative?)) (and/c real? (not/c negative?))
See also set-padding.
method
(send a-text get-position start [end]) → void?
start : (or/c (box/c exact-nonnegative-integer?) #f) end : (or/c (box/c exact-nonnegative-integer?) #f) = #f
See also get-start-position and get-end-position.
The start box is filled with the starting position of the selection, unless start is #f. The end box is filled with the ending position of the selection, unless end is #f.
method
(send a-text get-region-data start end)
→ (or/c (is-a?/c editor-data%) #f) start : exact-nonnegative-integer? end : exact-nonnegative-integer?
This method is not called when the whole editor is saved to a file. In such cases, the information can be stored in the header or footer; see Global Data: Headers and Footers.
This method is meant to be overridden; the default set-region-data method does not store information to be retrieved by this method.
method
(send a-text get-snip-position snip)
→ (or/c exact-nonnegative-integer? #f) snip : (is-a?/c snip%)
method
(send a-text get-snip-position-and-location snip pos [ x y]) → boolean? snip : (is-a?/c snip%) pos : (or/c (box/c exact-nonnegative-integer?) #f) x : (or/c (box/c real?) #f) = #f y : (or/c (box/c real?) #f) = #f
The pos box is filled with starting position of snip, unless pos is #f. The x box is filled with left location of snip in editor coordinates, unless x is #f. The y box is filled with top location of snip in editor coordinates, unless y is #f.
When location information is requested: The result is only valid when the editor is displayed (see Editor Structure and Terminology). Editors are displayed when get-admin returns an administrator (not #f). Calling this method may force the recalculation of location information, even if the editor currently has delayed refreshing (see refresh-delayed?).
method
(send a-text get-start-position) → exact-nonnegative-integer?
method
(send a-text get-styles-sticky) → boolean?
With non-sticky styles, text inserted into an editor always gets the style in the editor’s style list named by default-style-name.
See also set-styles-sticky.
method
(send a-text get-tabs [ length tab-width in-units]) → (listof real?) length : (or/c (box/c exact-nonnegative-integer?) #f) = #f tab-width : (or/c (box/c real?) #f) = #f in-units : (or/c (box/c any/c) #f) = #f
The length box is filled with the length of the tab array (and therefore the returned list), unless length is #f. The tab-width box is filled with the width used for tabs past the end of the tab array, unless tab-width is #f. The in-units box is filled with #t if the tabs are specified in canvas units or #f if they are specified in space-widths, unless in-units is #f.
See also set-tabs.
method
(send a-text get-text [ start end flattened? force-cr?]) → string? start : exact-nonnegative-integer? = 0 end : (or/c exact-nonnegative-integer? 'eof) = 'eof flattened? : any/c = #f force-cr? : any/c = #f
If flattened? is not #f, then flattened text is returned. See Flattened Text for a discussion of flattened vs. non-flattened text.
If force-cr? is not #f and flattened? is not #f, then automatic newlines (from word-wrapping) are written into the return string as real newlines.
The result is only valid when the editor is displayed (see Editor Structure and Terminology). Editors are displayed when get-admin returns an administrator (not #f). For text% objects, calling this method may force the recalculation of location information if a maximum width is set for the editor, even if the editor currently has delayed refreshing (see refresh-delayed?).
method
(send a-text get-visible-line-range start end [ all?]) → void? start : (or/c (box/c exact-nonnegative-integer?) #f) end : (or/c (box/c exact-nonnegative-integer?) #f) all? : any/c = #t
The start box is filled with first line visible to the user, unless start is #f. The end box is filled with last line visible to the user, unless end is #f.
If the editor is displayed by multiple canvases and all? is #t, then the computed range includes all visible lines in all displays. Otherwise, the range includes only the visible lines in the current display.
The result is only valid when the editor is displayed (see Editor Structure and Terminology). Editors are displayed when get-admin returns an administrator (not #f). Calling this method may force the recalculation of location information, even if the editor currently has delayed refreshing (see refresh-delayed?).
method
(send a-text get-visible-position-range start end [ all?]) → void? start : (or/c (box/c exact-nonnegative-integer?) #f) end : (or/c (box/c exact-nonnegative-integer?) #f) all? : any/c = #t
The start box is filled with first position visible to the user, unless start is #f. The end box is filled with last position visible to the user, unless end is #f.
If the editor is displayed by multiple canvases and all? is #t, then the computed range includes all visible positions in all displays. Otherwise, the range includes only the visible positions in the current display.
The result is only valid when the editor is displayed (see Editor Structure and Terminology). Editors are displayed when get-admin returns an administrator (not #f). Calling this method may force the recalculation of location information, even if the editor currently has delayed refreshing (see refresh-delayed?).
method
(send a-text get-wordbreak-map)
→ (or/c (is-a?/c editor-wordbreak-map%) #f)
method
(send a-text hide-caret hide?) → void?
hide? : any/c
If hide? is not #f, then the caret or selection hiliting will not be drawn for the editor. The editor can still own the keyboard focus, but no caret will be drawn to indicate the focus.
See also caret-hidden? and lock.
method
str : string? start : exact-nonnegative-integer? end : (or/c exact-nonnegative-integer? 'same) = 'same scroll-ok? : any/c = #t
(send a-text insert n str start [ end scroll-ok?]) → void?
n :
(and/c exact-nonnegative-integer? (<=/c (string-length str))) str : string? start : exact-nonnegative-integer? end : (or/c exact-nonnegative-integer? 'same) = 'same scroll-ok? : any/c = #t (send a-text insert str) → void? str : string? (send a-text insert n str) → void?
n :
(and/c exact-nonnegative-integer? (<=/c (string-length str))) str : string?
(send a-text insert snip start [ end scroll-ok?]) → void? snip : (is-a?/c snip%) start : exact-nonnegative-integer? end : (or/c exact-nonnegative-integer? 'same) = 'same scroll-ok? : any/c = #t (send a-text insert snip) → void? snip : (is-a?/c snip%) (send a-text insert char) → void? char : char? (send a-text insert char start [end]) → void? char : char? start : exact-nonnegative-integer? end : (or/c exact-nonnegative-integer? 'same) = 'same
When a snip is provided: The snip cannot be inserted into multiple editors or multiple times within a single editor. As the snip is inserted, its current style is converted to one in the editor’s style list; see also convert.
When a char is provided: Multiple calls to the character-inserting method are grouped together for undo purposes, since this case of the method is typically used for handling user keystrokes. However, this undo-grouping feature interferes with the undo grouping performed by begin-edit-sequence and end-edit-sequence, so the string-inserting method should be used instead during undoable edit sequences.
When start is not provided, the current selection start is used. If the current selection covers a range of items, then char replaces the selected text. The selection’s start and end positions are moved to the end of the inserted character.
For a case where end is not provided and has no default, the current selection end is used. Otherwise, if end is not 'same, then the inserted value replaces the region from start to end, and the selection is left at the end of the inserted text. Otherwise, if the insertion position is before or equal to the selection’s start/end position, then the selection’s start/end position is incremented by the length of str.
If scroll-ok? is not #f and start is the same as the current selection’s start position, then the editor’s display is scrolled to show the new selection position.
See also get-styles-sticky.
method
time : exact-integer? = 0 (send a-text kill time start end) → void? time : exact-integer? start : exact-nonnegative-integer? end : exact-nonnegative-integer?
See Cut and Paste Time Stamps for a discussion of the time argument. If time is outside the platform-specific range of times, an exn:fail:contract exception is raised.
method
(send a-text last-line) → exact-nonnegative-integer?
See also paragraph-start-position, which operates on paragraphs (determined by explicit newline characters) instead of lines (determined by both explicit newline characters and automatic line-wrapping).
Calling this method may force the recalculation of location information if a maximum width is set for the editor, even if the editor currently has delayed refreshing (see refresh-delayed?). If the editor is not displayed and the editor has a maximum width, line breaks are calculated as for line-start-position (which handles specially the case of no display when the editor has a maximum width).
method
(send a-text last-paragraph) → exact-nonnegative-integer?
Calling this method may force the recalculation of location information if a maximum width is set for the editor, even if the editor currently has delayed refreshing (see refresh-delayed?).
method
(send a-text last-position) → exact-nonnegative-integer?
method
(send a-text line-end-position line [ visible?]) → exact-nonnegative-integer? line : exact-nonnegative-integer? visible? : any/c = #t
If there are fewer than line-1 lines, the end of the last line is returned. If line is less than 0, then the end of the first line is returned.
If the line ends with invisible items (such as a newline) and visible? is not #f, the first position before the invisible items is returned.
See also paragraph-start-position, which operates on paragraphs (determined by explicit newline characters) instead of lines (determined by both explicit newline characters and automatic line-wrapping).
Calling this method may force the recalculation of location information if a maximum width is set for the editor, even if the editor currently has delayed refreshing (see refresh-delayed?). If the editor is not displayed and the editor has a maximum width, line breaks are calculated as for line-start-position (which handles specially the case of no display when the editor has a maximum width).
method
(send a-text line-length i) → exact-nonnegative-integer?
i : exact-nonnegative-integer?
Calling this method may force the recalculation of location information if a maximum width is set for the editor, even if the editor currently has delayed refreshing (see refresh-delayed?). If the editor is not displayed and the editor has a maximum width, line breaks are calculated as for line-start-position (which handles specially the case of no display when the editor has a maximum width).
method
(send a-text line-location line [top?]) → real?
line : exact-nonnegative-integer? top? : any/c = #t
If top? is not #f, the location for the top of the line is returned; otherwise, the location for the bottom of the line is returned.
See also paragraph-start-position, which operates on paragraphs (determined by explicit newline characters) instead of lines (determined by both explicit newline characters and automatic line-wrapping).
The result is only valid when the editor is displayed (see Editor Structure and Terminology). Editors are displayed when get-admin returns an administrator (not #f). Calling this method may force the recalculation of location information, even if the editor currently has delayed refreshing (see refresh-delayed?).
method
(send a-text line-paragraph start) → exact-nonnegative-integer?
start : exact-nonnegative-integer?
Calling this method may force the recalculation of location information if a maximum width is set for the editor, even if the editor currently has delayed refreshing (see refresh-delayed?). If the editor is not displayed and the editor has a maximum width, line breaks are calculated as for line-start-position (which handles specially the case of no display when the editor has a maximum width).
method
(send a-text line-start-position line [ visible?]) → exact-nonnegative-integer? line : exact-nonnegative-integer? visible? : any/c = #t
If there are fewer than line-1 lines, the start of the last line is returned. If line is less than 0, then the start of the first line is returned.
If the line starts with invisible items and visible? is not #f, the first position past the invisible items is returned.
See also paragraph-start-position, which operates on paragraphs (determined by explicit newline characters) instead of lines (determined by both explicit newline characters and automatic line-wrapping).
Calling this method may force the recalculation of location information if a maximum width is set for the editor, even if the editor currently has delayed refreshing (see refresh-delayed?).
the editor is not displayed (see Editor Structure and Terminology),
a maximum width is set for the editor, and
the editor has never been viewed
then this method ignores the editor’s maximum width and any automatic line breaks it might imply. If the first two of the above conditions are true and the editor was formerly displayed, this method uses the line breaks from the most recent display of the editor. (Insertions or deletions since the display shift line breaks within the editor in the same way as items.)
method
(send a-text move-position code [ extend? kind]) → void? code : (or/c 'home 'end 'right 'left 'up 'down) extend? : any/c = #f kind : (or/c 'simple 'word 'page 'line) = 'simple
The possible values for code are:
'home —
go to start of file 'end —
go to end of file 'right —
move right 'left —
move left 'up —
move up 'down —
move down
If extend? is not #f, the selection range is extended instead of moved. If anchoring is on (see get-anchor and set-anchor), then extend? is effectively forced to #t. See also get-extend-start-position and get-extend-end-position.
The possible values for kind are:
'simple —
move one item or line 'word —
works with 'right or 'left 'page —
works with 'up or 'down 'line —
works with 'right or 'left; moves to the start or end of the line
See also set-position.
method
(send a-text on-change-style start len) → void?
start : exact-nonnegative-integer? len : exact-nonnegative-integer?
The editor is internally locked for writing during a call to this method (see also Internal Editor Locks). Use after-change-style to modify the editor, if necessary.
See also on-edit-sequence.
Default implementation: Does nothing.
method
(send a-text on-default-char event) → void?
event : (is-a?/c key-event%)
Delete and Backspace —
calls delete. The arrow keys, Page Up, Page Down, Home, and End (including shifted versions) —
moves the selection position with move-position. Any other character in the range (integer->char 32) to (integer->char 255) —
inserts the character into the editor.
Note that an editor’s editor-canvas% normally handles mouse wheel events (see also on-char ).
method
(send a-text on-default-event event) → void?
event : (is-a?/c mouse-event%)
Clicking on a clickback region starts clickback tracking. See set-clickback for more information. Moving over a clickback changes the shape of the mouse cursor.
Clicking anywhere else moves the caret to the closest position between items. Shift-clicking extends the current selection.
Dragging extends the selection, scrolling if possible when the selection is dragged outside the editor’s visible region.
method
start : exact-nonnegative-integer? len : exact-nonnegative-integer?
The start argument specifies the starting position of the range to delete. The len argument specifies number of items to delete (so start+len is the ending position of the range to delete).
The editor is internally locked for writing during a call to this method (see also Internal Editor Locks). Use after-delete to modify the editor, if necessary.
See also on-edit-sequence.
Default implementation: Does nothing.
method
start : exact-nonnegative-integer? len : exact-nonnegative-integer?
The start argument specifies the position of the insert. The len argument specifies the total length (in positions) of the items to be inserted.
The editor is internally locked for writing during a call to this method (see also Internal Editor Locks). Use after-insert to modify the editor, if necessary.
See also on-edit-sequence.
Default implementation: Does nothing.
method
(send a-text on-new-string-snip) → (is-a?/c string-snip%)
Default implementation: Returns a string-snip% instance.
method
(send a-text on-new-tab-snip) → (is-a?/c tab-snip%)
Default implementation: Returns a tab-snip% instance.
method
(send a-text on-set-size-constraint) → void?
(This callback method is provided because setting an editor’s maximum width may cause lines to be re-flowed with soft newlines.)
See also on-edit-sequence.
Default implementation: Does nothing.
method
(send a-text paragraph-end-line paragraph)
→ exact-nonnegative-integer? paragraph : exact-nonnegative-integer?
Calling this method may force the recalculation of location information if a maximum width is set for the editor, even if the editor currently has delayed refreshing (see refresh-delayed?). If the editor is not displayed and the editor has a maximum width, line breaks are calculated as for line-start-position (which handles specially the case of no display when the editor has a maximum width).
method
(send a-text paragraph-end-position paragraph [ visible?]) → exact-nonnegative-integer? paragraph : exact-nonnegative-integer? visible? : any/c = #t
If there are fewer than paragraph-1 paragraphs, the end of the last paragraph is returned. If paragraph is less than 0, then the end of the first paragraph is returned.
If the paragraph ends with invisible items (such as a newline) and visible? is not #f, the first position before the invisible items is returned.
method
(send a-text paragraph-start-line paragraph)
→ exact-nonnegative-integer? paragraph : exact-nonnegative-integer?
Calling this method may force the recalculation of location information if a maximum width is set for the editor, even if the editor currently has delayed refreshing (see refresh-delayed?). If the editor is not displayed and the editor has a maximum width, line breaks are calculated as for line-start-position (which handles specially the case of no display when the editor has a maximum width).
method
(send a-text paragraph-start-position paragraph [ visible?]) → exact-nonnegative-integer? paragraph : exact-nonnegative-integer? visible? : any/c = #t
If there are fewer than paragraph-1 paragraphs, the start of the last paragraph is returned.
If the paragraph starts with invisible items and visible? is not #f, the first position past the invisible items is returned.
method
time : exact-integer? = 0 start : (or/c exact-nonnegative-integer? 'start 'end) = 'start end : (or/c exact-nonnegative-integer? 'same) = 'same
See Cut and Paste Time Stamps for a discussion of the time argument. If time is outside the platform-specific range of times, an exn:fail:contract exception is raised.
method
(send a-text paste-next) → void?
It is a copy “ring” because the ring pointer wraps back to the most recent copied data after the oldest remembered data is pasted. Any cut, copy, or (regular) paste operation resets the copy ring pointer back to the beginning.
If the previous operation on the editor was not a paste, calling paste-next has no effect.
method
(send a-text paste-x-selection [ time start end]) → void? time : exact-integer? = 0 start : (or/c exact-nonnegative-integer? 'start 'end) = 'start end : (or/c exact-nonnegative-integer? 'same) = 'same
See Cut and Paste Time Stamps for a discussion of the time argument. If time is outside the platform-specific range of times, an exn:fail:contract exception is raised.
method
(send a-text position-line start [at-eol?])
→ exact-nonnegative-integer? start : exact-nonnegative-integer? at-eol? : any/c = #f
See also paragraph-start-position, which operates on paragraphs (determined by explicit newline characters) instead of lines (determined by both explicit newline characters and automatic line-wrapping).
See End of Line Ambiguity for a discussion of at-eol?.
Calling this method may force the recalculation of location information if a maximum width is set for the editor, even if the editor currently has delayed refreshing (see refresh-delayed?). If the editor is not displayed and the editor has a maximum width, line breaks are calculated as for line-start-position (which handles specially the case of no display when the editor has a maximum width).
method
(send a-text position-location start [ x y top? at-eol? whole-line?]) → void? start : exact-nonnegative-integer? x : (or/c (box/c real?) #f) = #f y : (or/c (box/c real?) #f) = #f top? : any/c = #t at-eol? : any/c = #f whole-line? : any/c = #f
The x box is filled with the x-location of the position start in editor coordinates, unless x is #f. The y box is filled with the y-location (top or bottom; see below) of the position start in editor coordinates, unless y is #f.
See End of Line Ambiguity for a discussion of at-eol?.
If top? is not #f, the top coordinate of the location is returned, otherwise the bottom coordinate of the location is returned.
The top y location may be different for different positions within a line when different-sized graphic objects are used. If whole-line? is not #f, the minimum top location or maximum bottom location for the whole line is returned in y.
The result is only valid when the editor is displayed (see Editor Structure and Terminology). Editors are displayed when get-admin returns an administrator (not #f). Calling this method may force the recalculation of location information, even if the editor currently has delayed refreshing (see refresh-delayed?).
method
(send a-text position-locations start [ top-x top-y bottom-x bottom-y at-eol? whole-line?]) → void? start : exact-nonnegative-integer? top-x : (or/c (box/c real?) #f) = #f top-y : (or/c (box/c real?) #f) = #f bottom-x : (or/c (box/c real?) #f) = #f bottom-y : (or/c (box/c real?) #f) = #f at-eol? : any/c = #f whole-line? : any/c = #f
The result is only valid when the editor is displayed (see Editor Structure and Terminology). Editors are displayed when get-admin returns an administrator (not #f). Calling this method may force the recalculation of location information, even if the editor currently has delayed refreshing (see refresh-delayed?).
method
(send a-text position-paragraph start [ at-eol?]) → exact-nonnegative-integer? start : exact-nonnegative-integer? at-eol? : any/c = #f
Returns the paragraph number of the paragraph containing a given position.
method
(send a-text read-from-file stream start [ overwrite-styles?]) → boolean? stream : (is-a?/c editor-stream-in%) start : (or/c exact-nonnegative-integer? 'start) overwrite-styles? : any/c = #f
(send a-text read-from-file stream [ overwrite-styles?]) → boolean? stream : (is-a?/c editor-stream-in%) overwrite-styles? : any/c = #f
method
(send a-text remove-clickback start end) → void?
start : exact-nonnegative-integer? end : exact-nonnegative-integer?
method
(send a-text scroll-to-position start [ at-eol? end bias]) → boolean? start : exact-nonnegative-integer? at-eol? : any/c = #f end : (or/c exact-nonnegative-integer? 'same) = 'same bias : (or/c 'start 'end 'none) = 'none
If end is 'same or equal to start, then position start is made visible. See End of Line Ambiguity for a discussion of at-eol?.
If end is not 'same and not the same as start, then the range start to end is made visible and at-eol? is ignored.
When the specified range cannot fit in the visible area, bias indicates which end of the range to display. When bias is 'start, then the start of the range is displayed. When bias is 'end, then the end of the range is displayed. Otherwise, bias must be 'none.
If the editor is scrolled, then the editor is redrawn and the return value is #t; otherwise, the return value is #f. If refreshing is delayed (see refresh-delayed?), then the scroll request is saved until the delay has ended. The scroll is performed (immediately or later) by calling scroll-editor-to.
Scrolling is disallowed when the editor is internally locked for reflowing (see also Internal Editor Locks).
The system may scroll the editor without calling this method. For example, a canvas displaying an editor might scroll the editor to handle a scrollbar event.
method
(send a-text set-anchor on?) → void?
on? : any/c
If on? is not #f, then the selection will be automatically extended when cursor keys are used (or, more generally, when move-position is used to move the selection or the keep-anchor? argument to set-position is a true value), otherwise anchoring is turned off. Anchoring is automatically turned off if the user does anything besides cursor movements.
method
(send a-text set-autowrap-bitmap bitmap)
→ (or/c (is-a?/c bitmap%) #f) bitmap : (or/c (is-a?/c bitmap%) #f)
If bitmap is #f, no autowrap indicator is drawn (this is the default). The previously used bitmap (possibly #f) is returned.
Setting the bitmap is disallowed when the editor is internally locked for reflowing (see also Internal Editor Locks).
method
(send a-text set-between-threshold threshold) → void?
threshold : (and/c real? (not/c negative?))
See also get-between-threshold.
method
(send a-text set-clickback start end f [ hilite-delta call-on-down?]) → void? start : exact-nonnegative-integer? end : exact-nonnegative-integer?
f :
(-> (is-a?/c text%) exact-nonnegative-integer? exact-nonnegative-integer? any) hilite-delta : (or/c (is-a?/c style-delta%) #f) = #f call-on-down? : any/c = #f
The callback procedure f is called when the user selects the clickback. The arguments to f are this editor and the starting and ending range of the clickback.
The hilite-delta style delta is applied to the clickback text when the user has clicked and is still holding the mouse over the clickback. If hilite-delta is #f, then the clickback region’s style is not changed when it is being selected.
If call-on-down? is not #f, the clickback is called immediately when the user clicks the mouse button down, instead of after a mouse-up event. The hilite-delta argument is not used in this case.
See also Clickbacks.
method
(send a-text set-file-format format) → void?
format : (or/c 'standard 'text 'text-force-cr)
The legal formats are:
'standard —
a standard editor file 'text —
a text file 'text-force-cr —
a text file; when writing, change automatic newlines (from word-wrapping) into real newlines
The file format of an editor can be changed by the system in response to file loading and saving method calls, and such changes do not go through this method; use on-load-file and on-save-file to monitor such file format changes.
method
(send a-text set-overwrite-mode on?) → void?
on? : any/c
method
(send a-text set-padding left top right bottom) → void? left : (and/c real? (not/c negative?)) top : (and/c real? (not/c negative?)) right : (and/c real? (not/c negative?)) bottom : (and/c real? (not/c negative?))
Unlike any margin that may be applied by the editor’s display, padding is counted in location information that is reported by methods such as position-location. For example, with a left padding of 17.0 and a top padding of 9.0, the location of position 0 will be (17.0, 9.0) rather than (0, 0). Padding also contributes to the editor’s size as reported by get-extent.
method
(send a-text set-paragraph-alignment paragraph alignment) → void? paragraph : exact-nonnegative-integer? alignment : (or/c 'left 'center 'right)
This method is experimental. It works reliably only when the paragraph is not merged or split. Merging or splitting a paragraph with alignment settings causes the settings to be transferred unpredictably (although other paragraphs in the editor can be safely split or merged). If the last paragraph in an editor is empty, settings assigned to it are ignored.
method
(send a-text set-paragraph-margins paragraph first-left left right) → void? paragraph : exact-nonnegative-integer? first-left : (and/c real? (not/c negative?)) left : (and/c real? (not/c negative?)) right : (and/c real? (not/c negative?))
The first line of the paragraph is indented by first-left points within the editor. If the paragraph is line-wrapped (when the editor has a maximum width), subsequent lines are indented by left points. If the editor has a maximum width, the paragraph’s maximum width for line-wrapping is right points smaller than the editor’s maximum width.
This method is experimental. See set-paragraph-alignment for more information.
method
(send a-text set-position start [ end at-eol? scroll? seltype]) → void? start : exact-nonnegative-integer? end : (or/c exact-nonnegative-integer? 'same) = 'same at-eol? : any/c = #f scroll? : any/c = #t seltype : (or/c 'default 'x 'local) = 'default
If end is 'same or less than or equal to start, the current start and end positions are both set to start. Otherwise the given range is selected.
See End of Line Ambiguity for a discussion of at-eol?. If scroll? is not #f, then the display is scrolled to show the selection if necessary.
'default —
if this window has the keyboard focus and given selection is non-empty, make it the current X selection 'x —
if the given selection is non-empty, make it the current X selection 'local —
do not change the current X selection
Setting the position is disallowed when the editor is internally locked for reflowing (see also Internal Editor Locks).
The system may change the selection in an editor without calling this method (or any visible method).
See also editor-set-x-selection-mode.
method
(send a-text set-position-bias-scroll bias start [ end ateol? scroll? seltype]) → void? bias : (or/c 'start-only 'start 'none 'end 'end-only) start : exact-nonnegative-integer? end : (or/c exact-nonnegative-integer? 'same) = 'same ateol? : any/c = #f scroll? : any/c = #t seltype : (or/c 'default 'x 'local) = 'default
'start-only —
only insure that the starting position is visible 'start —
if the range doesn’t fit in the visible area, show the starting position 'none —
no special scrolling instructions 'end —
if the range doesn’t fit in the visible area, show the ending position 'end-only —
only insure that the ending position is visible
See also scroll-to-position.
method
(send a-text set-region-data start end data) → void?
start : exact-nonnegative-integer? end : exact-nonnegative-integer? data : (is-a?/c editor-data%)
This method is meant to be overridden in combination with get-region-data .
Default implementation: Does nothing.
method
(send a-text set-styles-sticky sticky?) → void?
sticky? : any/c
method
(send a-text set-tabs tabs [ tab-width in-units?]) → void? tabs : (listof real?) tab-width : real? = 20 in-units? : any/c = #t
The tabs list determines the tabbing array. The tabbing array specifies the x-locations where each tab occurs. Tabs beyond the last specified tab are separated by a fixed amount tab-width. If in-units? is not #f, then tabs are specified in canvas units; otherwise, they are specified as a number of spaces. (If tabs are specified in spaces, then the graphic tab positions will change with the font used for the tab.)
Setting tabs is disallowed when the editor is internally locked for reflowing (see also Internal Editor Locks).
method
(send a-text set-wordbreak-func f) → void?
f :
((is-a?/c text%) (or/c (box/c exact-nonnegative-integer?) #f) (or/c (box/c exact-nonnegative-integer?) #f) symbol? . -> . any)
The standard wordbreaking function uses the editor’s editor-wordbreak-map% object to determine which characters break a word. See also editor-wordbreak-map% and set-wordbreak-map.
Since the wordbreak function will be called when line breaks are being determined (in an editor that has a maximum width), there is a constrained set of text% methods that the wordbreak function is allowed to invoke. It cannot invoke a member function that uses information about locations or lines (which are identified in this manual with “The result is only valid when the editor is displayed (see Editor Structure and Terminology). Editors are displayed when get-admin returns an administrator (not #f).”), but it can still invoke member functions that work with snips and items.
method
(send a-text set-wordbreak-map map) → void?
map : (or/c (is-a?/c editor-wordbreak-map%) #f)
If map is #f, then the standard map (the-editor-wordbreak-map) is used.
method
(send a-text split-snip pos) → void?
pos : exact-nonnegative-integer?
Splitting a snip is disallowed when the editor is internally locked for reflowing (see also Internal Editor Locks).
method
(send a-text write-to-file stream [start end]) → boolean?
stream : (is-a?/c editor-stream-out%) start : exact-nonnegative-integer? = 0 end : (or/c exact-nonnegative-integer? 'eof) = 'eof