7.18 text%

► |  | The Racket Graphical Interface Toolkit

1 | Windowing
2 | Widget Gallery
3 | Windowing Classes
4 | Windowing Functions
5 | Editors
6 | Snip and Style Classes
7 | Editor Classes
8 | Editor Functions
9 | WXME Decoding
10 | Preferences
11 | Dynamic Loading
12 | Startup Actions
13 | Init Libraries
14 | Platform Dependencies
| Index

▼ | 7 | Editor Classes

7.1 | editor<%>
7.2 | editor-admin%
7.3 | editor-canvas%
7.4 | editor-data%
7.5 | editor-data-class%
7.6 | editor-data-class-list<%>
7.7 | editor-snip-editor-admin<%>
7.8 | editor-snip%
7.9 | editor-stream-in%
7.10 | editor-stream-in-base%
7.11 | editor-stream-in-bytes-base%
7.12 | editor-stream-out%
7.13 | editor-stream-out-base%
7.14 | editor-stream-out-bytes-base%
7.15 | editor-wordbreak-map%
7.16 | keymap%
7.17 | pasteboard%
7.18 | text%

On this page:

new
after-change-style
after-delete
after-insert
after-merge-snips
after-set-position
after-set-size-constraint
after-split-snip
call-clickback
can-change-style?
can-delete?
can-insert?
can-set-size-constraint?
caret-hidden?
change-style
copy
copy-self-to
cut
delete
do-copy
do-paste
do-paste-x-selection
erase
extend-position
find-line
find-newline
find-next-non-string-snip
find-position
find-position-in-line
find-snip
find-string
find-string-embedded
find-string-all
find-string-embedded-all
find-wordbreak
flash-off
flash-on
get-anchor
get-autowrap-bitmap-width
get-between-threshold
get-character
get-end-position
get-extend-start-position
get-extend-end-position
get-file-format
get-line-spacing
get-overwrite-mode
get-padding
get-position
get-region-data
get-revision-number
get-snip-position
get-snip-position-and-location
get-start-position
get-styles-sticky
get-tabs
get-text
get-top-line-base
get-visible-line-range
get-visible-position-range
get-wordbreak-map
grapheme-position
hide-caret
insert
kill
last-line
last-paragraph
last-position
line-end-position
line-length
line-location
line-paragraph
line-start-position
move-position
on-change-style
on-default-char
on-default-event
on-delete
on-insert
on-new-string-snip
on-new-tab-snip
on-reflow
on-set-size-constraint
paragraph-end-line
paragraph-end-position
paragraph-start-line
paragraph-start-position
paste
paste-next
paste-x-selection
position-grapheme
position-line
position-location
position-locations
position-paragraph
read-from-file
remove-clickback
scroll-to-position
set-anchor
set-autowrap-bitmap
set-between-threshold
set-clickback
set-file-format
set-line-spacing
set-overwrite-mode
set-padding
set-paragraph-alignment
set-paragraph-margins
set-position
set-position-bias-scroll
set-region-data
set-styles-sticky
set-tabs
set-wordbreak-func
set-wordbreak-map
split-snip
write-to-file

Inherited methods:
from editor<%>
add-canvas
add-undo
adjust-cursor
after-edit-sequence
after-load-file
after-save-file
after-scroll-to
auto-wrap
begin-edit-sequence
begin-write-header-footer-to-file
blink-caret
can-do-edit-operation?
can-load-file?
can-save-file?
clear
clear-undos
copy-self
dc-location-to-editor-location
default-style-name
do-edit-operation
editor-location-to-dc-location
enable-sha1
end-edit-sequence
end-write-header-footer-to-file
find-first-snip
find-scroll-line
get-active-canvas
get-admin
get-canvas
get-canvases
get-dc
get-descent
get-extent
get-file
get-file-creator-and-type
get-file-sha1
get-filename
get-flattened-text
get-focus-snip
get-inactive-caret-threshold
get-keymap
get-load-overwrites-styles
get-max-height
get-max-undo-history
get-max-view-size
get-max-width
get-min-height
get-min-width
get-paste-text-only
get-snip-data
get-snip-location
get-space
get-style-list
get-view-size
global-to-local
in-edit-sequence?
insert-box
insert-file
insert-image
insert-port
invalidate-bitmap-cache
is-locked?
is-modified?
is-printing?
is-sha1-enabled?
load-file
local-to-global
locations-computed?
lock
locked-for-flow?
locked-for-read?
locked-for-write?
needs-update
num-scroll-lines
on-change
on-char
on-display-size
on-display-size-when-ready
on-edit-sequence
on-event
on-focus
on-load-file
on-local-char
on-local-event
on-new-box
on-new-image-snip
on-paint
on-save-file
on-scroll-to
on-snip-modified
own-caret
print
print-to-dc
put-file
read-footer-from-file
read-header-from-file
redo
refresh
refresh-delayed?
release-snip
remove-canvas
resized
save-file
save-port
scroll-editor-to
scroll-line-location
scroll-to
select-all
set-active-canvas
set-admin
set-caret-owner
set-cursor
set-file-creator-and-type
set-filename
set-inactive-caret-threshold
set-keymap
set-load-overwrites-styles
set-max-height
set-max-undo-history
set-max-width
set-min-height
set-min-width
set-modified
set-paste-text-only
set-snip-data
set-style-list
set-undo-preserves-all-history
size-cache-invalid
style-has-changed
undo
undo-preserves-all-history?
update-sha1?
use-file-text-mode
write-footers-to-file
write-headers-to-file

top contents ← prev up next →

class text% : class?
superclass: object%
extends: | editor<%>

A text% object is a standard text editor. A text editor is displayed on the screen through an editor-canvas% object or some other display.

> > 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

The line-spacing argument sets the additional amount of space (in DC units) inserted between each line in the editor when the editor is displayed. This spacing is included in the reported height of each line.

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?

Refine this method with augment.
Specification: Called after the style is changed for a given range (and after the display is refreshed; use on-change-style and begin-edit-sequence to avoid extra refreshes when after-change-style modifies the editor).

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?

Refine this method with augment.
Specification: Called after a given range is deleted from the editor (and after the display is refreshed; use on-delete and begin-edit-sequence to avoid extra refreshes when after-delete modifies the editor).

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?

Refine this method with augment.
Specification: Called after items are inserted into the editor (and after the display is refreshed; use on-insert and begin-edit-sequence to avoid extra refreshes when after-insert modifies the editor).

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?

Refine this method with augment.
Specification: Called after adjacent snips in the editor are combined into one.

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?

Refine this method with augment.
Specification: Called after the start and end position have been moved (but not when the position is moved due to inserts or deletes).

See also on-edit-sequence.

Default implementation: Does nothing.

> method (send a-text after-set-size-constraint) → void?

Refine this method with augment.
Specification: Called after the editor’s maximum or minimum height or width is changed (and after the display is refreshed; use on-set-size-constraint and begin-edit-sequence to avoid extra refreshes when after-set-size-constraint modifies the editor).

(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?

Refine this method with augment.
Specification: Called after a snip in the editor is split into two, either through a call to split-snip or during some other action, such as inserting.

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?

Simulates a user click that invokes a clickback, if the given range of positions is within a clickback’s region. See also Clickbacks.

> method (send a-text can-change-style? start len) → boolean?
> start : exact-nonnegative-integer?
> len : exact-nonnegative-integer?

Refine this method with augment.
Specification: Called before the style is changed in a given range of the editor. If the return value is #f, then the style change will be aborted.

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?

Refine this method with augment.
Specification: Called before a range is deleted from the editor. If the return value is #f, then the delete will be aborted.

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?

Refine this method with augment.
Specification: Called before items are inserted into the editor. If the return value is #f, then the insert will be aborted.

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?

Refine this method with augment.
Specification: Called before the editor’s maximum or minimum height or width is changed. If the return value is #f, then the change will be aborted.

(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?

Returns #t if the caret is hidden for this editor or #f otherwise.

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

Changes the style for a region in the editor by applying a style delta or installing a specific style. If start is 'start and end is 'end, then the currently selected items are changed. Otherwise, if end is 'end, then the style is changed from start until the end of the selection. If counts-as-mod? is #f, then set-modified is not called after applying the style change.

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 (send a-text copy [extend? time start end]) → void?
> extend? : any/c = #f
> time : exact-integer? = 0
> start : (or/c exact-nonnegative-integer? 'start) = 'start
> end : (or/c exact-nonnegative-integer? 'end) = 'end

Extends copy in editor<%>.
Copies specified range of text into the clipboard. If extend? is not #f, the old clipboard contents are appended. If start is 'start or end is 'end, then the current selection start/end is used.

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%))

Overrides copy-self-to in editor<%>.
In addition to the default copy-self-to in editor<%> work, this editor’s file format, wordbreak function, wordbreak map, click-between-threshold, caret visibility state, overwrite mode state, and autowrap bitmap are installed into dest.

> method (send a-text cut [extend? time start end]) → void?
> extend? : any/c = #f
> time : exact-integer? = 0
> start : (or/c exact-nonnegative-integer? 'start) = 'start
> end : (or/c exact-nonnegative-integer? 'end) = 'end

Overrides cut in editor<%>.
Copies and then deletes the specified range. If extend? is not #f, the old clipboard contents are appended. If start is 'start or end is 'end, then the current selection start/end is used.

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 delete start [end scroll-ok?]) → void?
> 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?

Deletes the specified range or the currently selected text (when no range is provided) in the editor. If start is 'start, then the starting selection position is used; if end is 'back, then only the grapheme preceding start is deleted. If scroll-ok? is not #f and start is the same as the current caret position, then the editor’s display may be scrolled to show the new selection position.

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.

Changed in version 1.67 of package gui-lib: Changed 'back to delete a grapheme instead of a character.

> method (send a-text do-copy start end time extend?) → void?
> start : exact-nonnegative-integer?
> end : exact-nonnegative-integer?
> time : exact-integer?
> extend? : any/c

Specification: Called to copy a region of the editor into the clipboard. This method is provided so that it can be overridden by subclasses. Do not call this method directly; instead, call copy.

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 (send a-text do-paste start time) → void?
> start : exact-nonnegative-integer?
> time : exact-integer?

Specification: Called to paste the current contents of the clipboard into the editor. This method is provided so that it can be overridden by subclasses. Do not call this method directly; instead, call paste.

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?

Specification: Called to paste the current contents of the X11 selection on Unix (or the clipboard on Windows or Mac OS) into the editor. This method is provided so that it can be overridden by subclasses. Do not call this method directly; instead, call paste-x-selection.

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 erase) → void?

Erases the contents of the editor.

See also delete.

> method (send a-text extend-position pos) → void?
> pos : exact-nonnegative-integer?

Updates the selection (see set-position) based on the result of get-extend-end-position, get-extend-start-position, and pos.

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

Given a location in the editor, returns the line at the location. Lines are numbered starting with 0.

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

Like find-string, but specifically finds a paragraph break (possibly more efficiently than searching text).

> 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)

Given a snip, returns the next snip in the editor (after the given one) that is not an instance of string-snip%. If #f is given as the snip, the result is the first non-string snip in the editor (if any). If no non-string snip is found after the given snip, the result is #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

Given a location in the editor, returns the position at the location.

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 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 strictly to the left of the item’s left edge, the value is -100.0; if the point is at or to the right of the item’s right edge, the value is 100.0; otherwise, the value is zero or negative if the point is closest to the left, positive if the point is closest to the right edge of the item, and the magnitude of the value is the distance from the point to the edge of the item.

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

Given a location within a line of the editor, returns the position at the location. Lines are numbered starting with 0.

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 (send a-text find-snip pos direction [s-pos])
> → (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

Returns the snip at a given position, or #f if an appropriate snip cannot be found.

If the position pos is between two snips, direction specifies which snip to return; direction can be any of the following:

- '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 : non-empty-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

Finds an exact-match string in the editor and returns its position. If the string is not found, #f is returned.

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 : non-empty-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

Like find-string, but also searches in embedded editors, returning a series of cons pairs whose car positions are the editors on the path to the editor where the search string occurred and whose final cdr position is the search result position.

> > method
> > (send a-text find-string-all |  | str |
> > | [ | direction |
> > |  | start |
> > |  | end |
> > |  | get-start? |
> > |  | case-sensitive]) |
> → (listof exact-nonnegative-integer?)
> str : non-empty-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

Finds all occurrences of a string using find-string. If no occurrences are found, the empty list is returned. The arguments are the same as for find-string.

> > 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 : non-empty-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

Like find-string-embedded, but also searches in embedded editors, returning search results a list of the editors that contain the matches.

> > 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)

Finds wordbreaks in the editor using the current wordbreak procedure. See also set-wordbreak-func.

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-off) → void?

Turns off the hiliting and shows the normal selection range again; see flash-on. There is no effect if this method is called when flashing is already off.

> > 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

Temporarily hilites a region in the editor without changing the current selection.

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?

Returns #t if the selection is currently auto-extending. See also set-anchor.

> method (send a-text get-autowrap-bitmap-width)
> → (and/c real? (not/c negative?))

Returns the width of the bitmap last passed to set-autowrap-bitmap or zero? if no bitmap has been passed to set-autowrap-bitmap or if #f was most recently passed.

> method (send a-text get-between-threshold)
> → (and/c real? (not/c negative?))

Returns an amount used to determine the meaning of a user click. If the click falls within the threshold of a position between two items, then the click registers on the space between the items rather than on either item.

See also set-between-threshold.

> method (send a-text get-character start) → char?
> start : exact-nonnegative-integer?

Returns the character following the position start. The character corresponds to getting non-flattened text from the editor.

If start is greater than or equal to the last position, #\nul is returned.

> method (send a-text get-end-position) → exact-nonnegative-integer?

Returns the ending position of the current selection. See also get-position.

> method (send a-text get-extend-start-position)
> → exact-nonnegative-integer?

Returns the beginning of the “extend” region if the selection is currently being extended via, e.g., shift and a cursor movement key; otherwise returns the same value as get-start-position.

> method (send a-text get-extend-end-position)
> → exact-nonnegative-integer?

Returns the beginning of the “extend” region if the selection is currently being extended via, e.g., shift and a cursor movement key; otherwise returns the same value as get-end-position.

> method (send a-text get-file-format)
> → (or/c 'standard 'text 'text-force-cr)

Returns the format of the last file saved from or loaded into this editor. See also load-file.

> method (send a-text get-line-spacing)
> → (and/c real? (not/c negative?))

Returns the spacing inserted by the editor between each line. This spacing is included in the reported height of each line.

> method (send a-text get-overwrite-mode) → boolean?

Returns #t if the editor is in overwrite mode, #f otherwise. Overwrite mode only affects the way that on-default-char handles keyboard input for insertion characters. See also set-overwrite-mode.

> > 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?))

Returns the editor’s padding for its left, top, right, and bottom sides (in that order).

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

Returns the current selection range in positions. If nothing is selected, the start and end will be the same number and that number will be where the insertion point is.

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?

Gets extra data associated with a given region. See Editor Data for more information.

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-revision-number)
> → (and/c real? (not/c negative?))

Returns an inexact number that increments every time the editor is changed in one of the following ways: a snip is inserted (see after-insert), a snip is deleted (see after-delete), a snip is split (see after-split-snip), snips are merged (see after-merge-snips), or a snip changes its count (which is rare; see recounted).

> method (send a-text get-snip-position snip)
> → (or/c exact-nonnegative-integer? #f)
> snip : (is-a?/c snip%)

Returns the starting position of a given snip or #f if the snip is not in this editor.

> > 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

This method is final, so it cannot be overridden.
Gets a snip’s position and top left location in editor coordinates. The return value is #t if the snip is found, #f otherwise.

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?

Returns the starting position of the current selection. See also get-position.

> method (send a-text get-styles-sticky) → boolean?

In the normal mode for a text editor, style settings are sticky. With sticky styles, when a string or character is inserted into an editor, it gets the style of the snip preceding the insertion point (or the snip that includes the insertion point if text is inserted into an exiting string snip). Alternatively, if change-style is called to set the style at the caret position (when it is not a range), then the style is remembered; if the editor is not changed before text is inserted at the caret, then the text gets the remembered style.

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

Returns the current tab-position array as a list.

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

Gets the text from start to end. If end is 'eof, then the contents are returned from start until the end of the editor.

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.

> method (send a-text get-top-line-base)
> → (and/c real? (not/c negative?))

Returns the distance from the top of the editor to the alignment baseline of the top line. This method is primarily used when an editor is an item within another editor. The reported baseline distance includes the editor’s top padding (see set-padding).

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

Returns the range of lines which are currently visible (or partially visible) to the user. Lines are numbered starting with 0.

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

Returns the range of positions that are currently visible (or partially visible) to the user.

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)

Returns the wordbreaking map that is used by the standard wordbreaking function. See set-wordbreak-map and editor-wordbreak-map% for more information.

> method (send a-text grapheme-position n) → exact-nonnegative-integer?
> n : exact-nonnegative-integer?

Returns the number of items in the editor that form the first n graphemes; or, equivalently, converts from an grapheme-based position to a item-based position.

Added in version 1.67 of package gui-lib.

> method (send a-text hide-caret hide?) → void?
> hide? : any/c

Determines whether the caret is shown when the editor has the keyboard focus.

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
> > (send a-text insert |  | str |  |  |  |
> > |  | start |  |  |  |
> > | [ | end |  |  |  |
> > |  | scroll-ok? |  |  |  |
> > |  | join-graphemes?]) |  | → |  | void?
> str : string?
> start : exact-nonnegative-integer?
> end : (or/c exact-nonnegative-integer? 'same) = 'same
> scroll-ok? : any/c = #t
> join-graphemes? : any/c = #f
> (send a-text insert |  | n |  |  |  |
> |  | str |  |  |  |
> |  | start |  |  |  |
> | [ | end |  |  |  |
> |  | scroll-ok? |  |  |  |
> |  | join-graphemes?]) |  | → |  | 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
> join-graphemes? : any/c = #f
> (send a-text insert str) → void?
> str : string?
> (send a-text insert n str [join-graphemes?]) → void?
> | n |  | : |  |
> (and/c exact-nonnegative-integer?
> (<=/c (string-length str)))
> str : string?
> join-graphemes? : any/c = #f
> (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

Overrides insert in editor<%>.
Inserts text or a snip into a-text at position start. If n is provided, the only the first n characters of str are inserted.

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.

If join-graphemes? is provided and not #f or if a character is provided to insert, then if characters before or after the inserted content would form a grapheme that spans the start or end of the inserted content, those characters are effectively added to the start and end of the inserted content, and the insertion range is adjusted to cover the absorbed characters. As a result, the grapheme-forming characters will be reliably placed in the same snip so that the grapheme renders properly. That adjustment may effectively change the style of the inserted content or of existing content that is involved with newly formed grapheme clusters

See also get-styles-sticky.

> method (send a-text kill [time]) → void?
> time : exact-integer? = 0
> (send a-text kill time start end) → void?
> time : exact-integer?
> start : exact-nonnegative-integer?
> end : exact-nonnegative-integer?

Overrides kill in editor<%>.
Cuts the text in the given region. If start and end are not supplied, then the selected region plus all whitespace to the end of line is cut; the newline is also cut if only whitespace exists between the selection and the end of line.

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?

Returns the number of the last line in the editor. Lines are numbered starting with 0, so this is one less than the number of lines in the editor.

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?

Returns the number of the last paragraph in the editor. Paragraphs are numbered starting with 0, so this is one less than the number of paragraphs in the editor.

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?

Returns the last selection position in the editor. This is also the number of items in the editor.

> > method
> > (send a-text line-end-position |  | line |
> > | [ | visible?]) |
> → exact-nonnegative-integer?
> line : exact-nonnegative-integer?
> visible? : any/c = #t

Returns the last position of a given line. Lines are numbered starting with 0.

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?

Returns the number of items in a given line. Lines are numbered starting with 0.

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

Given a line number, returns the location of the line. Lines are numbered starting with 0.

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?

Returns the paragraph number of the paragraph containing the line. Lines are numbered starting with 0. Paragraphs are numbered starting with 0.

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

Returns the first position of the given line. Lines are numbered starting with 0.

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?).

To calculate lines, if the following are true:

- 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

Moves the current selection.

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 grapheme 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.

Changed in version 1.67 of package gui-lib: Changed 'simple mode to move left or right by a grapheme instead of an item.

> method (send a-text on-change-style start len) → void?
> start : exact-nonnegative-integer?
> len : exact-nonnegative-integer?

Refine this method with augment.
Specification: Called before the style is changed in a given range of the editor, after can-change-style? is called to verify that the change is ok. The after-change-style method is guaranteed to be called after the change has completed.

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%)

Overrides on-default-char in editor<%>.
Handles the following:

- 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 (in grapheme-joining mode; see insert).

Note that an editor’s editor-canvas% normally handles mouse wheel events (see also on-char ).

Changed in version 1.67 of package gui-lib: Changed character inserting to use grapheme-joining mode.

> method (send a-text on-default-event event) → void?
> event : (is-a?/c mouse-event%)

Overrides on-default-event in editor<%>.
Tracks clicks on a clickback (see set-clickback) of changes the selection. Note that on-event dispatches to a caret-owning snip and detects a click on an event-handling snip before calling to this method.

- 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 (send a-text on-delete start len) → void?
> start : exact-nonnegative-integer?
> len : exact-nonnegative-integer?

Refine this method with augment.
Specification: Called before a range is deleted from the editor, after can-delete? is called to verify that the deletion is ok. The after-delete method is guaranteed to be called after the delete has completed.

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 (send a-text on-insert start len) → void?
> start : exact-nonnegative-integer?
> len : exact-nonnegative-integer?

Refine this method with augment.
Specification: Called before items are inserted into the editor, after can-insert? is called to verify that the insertion is ok. The after-insert method is guaranteed to be called after the insert has completed.

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%)

Specification: Called by insert when a string or character is inserted into the editor, this method creates and returns a new instance of string-snip% to store inserted text. The returned string snip is empty (i.e., its count is zero).

Default implementation: Returns a string-snip% instance.

> method (send a-text on-new-tab-snip) → (is-a?/c tab-snip%)

Specification: Creates and returns a new instance of tab-snip% to store an inserted tab. The returned tab snip is empty (i.e., its count is zero).

Default implementation: Returns a tab-snip% instance.

> method (send a-text on-reflow) → void?

Refine this method with augment.
Specification: Called after locations have changed and are recomputed for the editor. Default implementation: Does nothing.

> method (send a-text on-set-size-constraint) → void?

Refine this method with augment.
Specification: Called before the editor’s maximum or minimum height or width is changed, after can-set-size-constraint? is called to verify that the change is ok. The after-set-size-constraint method is guaranteed to be called after the change has completed.

(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?

Returns the ending line of a given paragraph. Paragraphs are numbered starting with 0. Lines are numbered starting with 0.

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

Returns the ending position of a given paragraph. Paragraphs are numbered starting with 0.

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?

Returns the starting line of a given paragraph. If paragraph is greater than the highest-numbered paragraph, then the editor’s end position is returned. Paragraphs are numbered starting with 0. Lines are numbered starting with 0.

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

Returns the starting position of a given paragraph. Paragraphs are numbered starting with 0.

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 (send a-text paste [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

Overrides paste in editor<%>.
Pastes into the specified range. If start is 'start, then the current selection start position is used. If start is 'end, then the current selection end position is used. If end is 'same, then start is used for end, unless start is 'start, in which case the current selection end position is used.

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?

Editors collectively maintain a copy ring that holds up to 30 previous copies (and cuts) among the editors. When it is called as the next method on an editor after a paste, the paste-next method replaces the text from a previous paste with the next data in the copy ring, incrementing the ring pointer so that the next paste-next pastes in even older data.

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

Overrides paste-x-selection in editor<%>.
Pastes into the specified range. If start is 'start, then the current selection start position is used. If start is 'end, then the current selection end position is used. If end is 'same, then start is used for end, unless start is 'start, in which case the current selection end position is used.

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-grapheme n) → exact-nonnegative-integer?
> n : exact-nonnegative-integer?

Returns the number of graphemes within the editor formed by the first n items; or, equivalently, converts from an item-based position to a grapheme-based position.

Added in version 1.67 of package gui-lib.

> method (send a-text position-line start [at-eol?])
> → exact-nonnegative-integer?
> start : exact-nonnegative-integer?
> at-eol? : any/c = #f

Returns the line number of the line containing a given position. Lines are numbered starting with 0.

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

Returns the location of a given position. See also position-locations.

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

Like position-location, but returns both the “top” and “bottom” results at once.

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

See End of Line Ambiguity for a discussion of at-eol?.

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

Extends read-from-file in editor<%>.
New data is inserted at the position indicated by start, or at the current position if start is 'start.

> method (send a-text remove-clickback start end) → void?
> start : exact-nonnegative-integer?
> end : exact-nonnegative-integer?

Removes all clickbacks installed for exactly the range start to end. See also Clickbacks.

> > 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

Scrolls the editor so that a given position is visible.

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

Turns anchoring on or off. This method can be overridden to affect or detect changes in the anchor state. See also get-anchor.

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)

Sets the bitmap that is drawn at the end of a line when it is automatically line-wrapped.

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?))

Sets the graphical distance used to determine the meaning of a user click. If a click falls within threshold of a position between two items, then the click registers on the space between the items rather than on either item.

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

Installs a clickback for a given region. If a clickback is already installed for an overlapping region, this clickback takes precedence.

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)

Set the format of the file saved from this editor.

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-line-spacing space) → void?
> space : (and/c real? (not/c negative?))

Sets the spacing inserted by the editor between each line. This spacing is included in the reported height of each line.

> method (send a-text set-overwrite-mode on?) → void?
> on? : any/c

Enables or disables overwrite mode. See get-overwrite-mode. This method can be overridden to affect or detect changes in the overwrite mode.

> > 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?))

Sets padding that insets the editor’s content when drawn within its display.

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)

Sets a paragraph-specific horizontal alignment. The alignment is only used when the editor has a maximum width, as set with set-max-width. Paragraphs are numbered starting with 0.

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?))

Sets a paragraph-specific margin. Paragraphs are numbered starting with 0.

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

Sets the current selection in the editor.

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.

The seltype argument is only used when the X Window System selection mechanism is enabled. The possible values are:

- '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

Like set-position, but a scrolling bias can be specified.

The possible values for bias are:

- '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%)

Specification: Sets extra data associated with a given region. See Editor Data and get-region-data for more information.

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

See get-styles-sticky for information about sticky styles.

> > method
> > (send a-text set-tabs |  | tabs |  |  |  |
> > | [ | tab-width |  |  |  |
> > |  | in-units?]) |  | → |  | void?
> tabs : (listof real?)
> tab-width : real? = 20
> in-units? : any/c = #t

Sets the tabbing array for the editor.

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)

Sets the word-breaking function for the editor. For information about the arguments to the word-breaking function, see find-wordbreak.

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)

Sets the wordbreaking map that is used by the standard wordbreaking function. See editor-wordbreak-map% for more information.

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?

Given a position, splits the snip that includes the position (if any) so that the position is between two snips. The snip may refuse to split, although none of the built-in snip classes will ever refuse.

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

Extends write-to-file in editor<%>.
If start is 0 and end is 'eof negative, then the entire contents are written to the stream. If end is 'eof, then the contents are written from start until the end of the editor. Otherwise, the contents of the given range are written.
top contents ← prev up next →