Normally, this method is called only by set-editor in editor-canvas%.

The system automatically installs undo records to undo built-in editor operations, such as inserts, deletes, and font changes. Install an undoer only when it is necessary to maintain state or handle operations that are not built-in. For example, in a program where the user can assign labels to snips in a pasteboard, the program should install an undoer to revert a label change. Thus, when a user changes a snip’s label and then selects Undo (from a standard menu bar), the snip’s label will revert as expected. In contrast, there is no need to install an undoer when the user moves a snip by dragging it, because the system installs an appropriate undoer automatically.

After an undoer returns, the undoer is popped off the editor’s undo (or redo) stack; if the return value is true, then the next undoer is also executed as part of the same undo (or redo) step. The undoer should return true if the action being undone was originally performed as part of a begin-edit-sequence and end-edit-sequence sequence. The return value should also be true if the undone action was implicitly part of a sequence. To extend the previous example, if a label change is paired with a move to realign the snip, then the label-change undoer should be added to the editor after the call to move, and it should return #t when it is called. As a result, the move will be undone immediately after the label change is undone. (If the opposite order is needed, use begin-edit-sequence and end-edit-sequence to create an explicit sequence.)

The system adds undoers to an editor (in response to other method calls) without calling this method.

See also set-cursor.

Default implementation: If an overriding cursor has been installed with set-cursor, then the installed cursor is returned.

Otherwise, if the event is a dragging event, a snip in the editor has the focus, and the snip’s adjust-cursor method returns a cursor, that cursor is returned.

Otherwise, if the cursor is over a snip and the snip’s adjust-cursor method returns a cursor, that cursor is returned.

Otherwise, if a cursor has been installed with set-cursor, then the installed cursor is returned.

Otherwise, if the cursor is over a clickback region in an editor, an arrow cursor is returned.

Finally, if none of the above cases apply, a default cursor is returned. For a text editor, the default cursor is an I-beam. For a pasteboard editor, the default cursor is an arrow.

See also on-edit-sequence.

Default implementation: Does nothing.

The argument to the method originally specified whether the save was successful, but failures now trigger exceptions such that the method is not even called. Consequently, the argument is always #t.

See also can-load-file? and on-load-file.

Default implementation: Does nothing.

The argument to the method originally specified whether the save was successful, but failures now trigger exceptions such that the method is not even called. Consequently, the argument is always #t.

See also can-save-file? and on-save-file.

Default implementation: Does nothing.

When the wrapping mode is changed, the on-display-size method is called immediately to update the editor’s maximum width.

Auto-wrapping is initially disabled.

When an editor contains other editors, using begin-edit-sequence and end-edit-sequence on the main editor brackets some changes to the sub-editors as well, but it is not as effective when a sub-editor changes as calling begin-edit-sequence and end-edit-sequence for the sub-editor.

See also refresh-delayed? and in-edit-sequence?, and see Editors and Threads for information about edit sequences and refresh requests.

If the undoable? flag is #f, then the changes made in the sequence cannot be reversed through the undo method. This flag is only effective for the outermost begin-edit-sequence when nested sequences are used. Note that, for a text% object, the character-inserting version of insert interferes with sequence-based undo groupings.

If the interrupt-streak? flag is #f and the sequence is outermost, then special actions before and after the sequence count as consecutive actions. For example, kills just before and after the sequence are appended in the copy buffer.

Default implementation: Starts a sequence.

The name string must be a unique name that can be used by a header reader to recognize the data. This method will store a value in buffer that should be passed on to end-write-header-footer-to-file.

Default implementation: Propagates the request to any snip with the editor-local focus.

Default implementation: Allows the operation depending on the selection, whether the editor is locked, etc.

The filename argument is the name the file will be loaded from. See load-file for information about format.

Note that the filename argument cannot be a string; it must be a path value.

Default implementation: Returns #t.

The filename argument is the name the file will be saved to. See load-file for information about format.

Note that the filename argument cannot be a string; it must be a path value.

Default implementation: Returns #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.

The style within 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-change-style in text% to monitor style changes.

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 in text% or on-delete in pasteboard% to monitor content deletions changes.

The system may execute a copy (in response to other method calls) without calling this method. To extend or re-implement copying, override the do-copy in text% or do-copy in pasteboard% method of an editor.

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.

Each snip in an-editor is copied and inserted into dest. In addition, an-editor’s filename, maximum undo history setting, keymap, interactive caret threshold, and overwrite-styles-on-load settings are installed into dest. Finally, an-editor’s style list is copied and the copy is installed as the style list for dest.

The system may execute a cut (in response to other method calls) without calling this method. To extend or re-implement the copying portion of the cut, override the do-copy in text% or do-copy in pasteboard% method of an editor. To monitor deletions in an editor, override on-delete in text% or on-delete in pasteboard%.

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.

The result is only valid when the editor is displayed (see Editor Structure and Terminology).

See also editor-location-to-dc-location.

• 'undo — undoes the last operation

• 'redo — undoes the last undo

• 'clear — deletes the current selection

• 'cut — cuts

• 'copy — copies

• 'paste — pastes

• 'kill — cuts to the end of the current line, or cuts a newline if there is only whitespace between the selection and end of line

• 'select-all — selects everything in the editor

• 'insert-text-box — inserts a text editor as an item in this editor; see also on-new-box .

• 'insert-pasteboard-box — inserts a pasteboard editor as an item in this editor; see also on-new-box .

• 'insert-image — gets a filename from the user and inserts the image as an item in this editor; see also on-new-image-snip .

If recursive? is not #f, then the command is passed on to any active snips of this editor (i.e., snips which own the caret).

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.

The result is only valid when the editor is displayed (see Editor Structure and Terminology).

See also dc-location-to-editor-location.

See File Format and write-headers-to-file for more information.

The first snip in a text editor is the one at position 0. The first snip in a pasteboard is the frontmost snip. (See Editor Structure and Terminology for information about snip order in pasteboards.)

For text% objects: Calling this method may force the recalculation of location information, even if the editor currently has delayed refreshing (see refresh-delayed?). The result is only valid when the editor is displayed (see Editor Structure and Terminology).

The result is only valid when the editor is displayed (see Editor Structure and Terminology). 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?).

The result is only valid when the editor is displayed (see Editor Structure and Terminology). 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?).

Note that the directory argument cannot be a string; it must be a path value or #f.

Default implementation: Calls the global get-file procedure.

If the editor is displayed in a single canvas, then the canvas’s top-level frame is used as the parent for the file dialog. Otherwise, the file dialog will have no parent.

The temp box is filled with #t if the filename is temporary or #f otherwise.

The returned snip might be an editor-snip% object. In that case, the embedded editor might delegate the focus to one of its own snips. However, the get-focus-snip method returns only the editor-snip% object, because it is the focus-owning snip within the immediate editor.

See also set-caret-owner.

See also set-inactive-caret-threshold and Caret Ownership.

See also set-load-overwrites-styles.

The result is only valid when the editor is displayed (see Editor Structure and Terminology).

If the display is an editor canvas, see also reflow-container.

Default implementation: Returns #f.

The x box is filled with the x-coordinate of the snip’s location, unless x is #f. The y box is filled with the y-coordinate of the snip’s location, unless y is #f.

If bottom-right? is not #f, the values in the x and y boxes are for the snip’s bottom right corner instead of its top-left corner.

Obtaining the location if the bottom-right corner may trigger delayed size calculations (including snips other than the one whose location was requested).

The result is only valid when the editor is displayed (see Editor Structure and Terminology). As a special case, however, a pasteboard% object always reports valid answers when bottom-right? is #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?).

The result is only valid when the editor is displayed (see Editor Structure and Terminology). 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?).

The w box is filled with the visible area width, unless w is #f. The h box is filled with the visible area height, unless h is #f.

The result is only valid when the editor is displayed (see Editor Structure and Terminology).

If the display is an editor canvas, see also reflow-container.

The x box is filled with the translated x-coordinate of the value initially in x, unless x is #f. The y box is filled with the translated x-coordinate of the value initially in y, unless y is #f.

The result is only valid when the editor is displayed (see Editor Structure and Terminology).

See also local-to-global.

See also refresh-delayed?.

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-insert in text% or on-insert in pasteboard% to monitor content additions changes.

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-insert in text% or on-insert in pasteboard% to monitor content additions changes.

For information on format, see load-file. The show-errors? argument is no longer used.

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-insert in text% or on-insert in pasteboard% to monitor content additions changes.

If filename is #f, then the user is queried for a filename. The kind must one of the symbols that can be passed to load-file.

After the filename has been determined, an image is created by calling on-new-image-snip. See also image-snip%.

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-insert in text% or on-insert in pasteboard% to monitor content additions changes.

The port must support position setting with file-position.

For information on format, see load-file.

if replace-styles? is true, then styles in the current style list are replaced by style specifications in port’s stream.

See also insert-file.

The x, y, width, and height arguments specify the area that needs repainting in editor coordinates. If width/height is 'end, then the total height/width of the editor (as reported by get-extent) is used. Note that the editor’s size can be smaller than the visible region of its display. If width/height is 'display-end, then the largest height/width of the editor’s views (as reported by get-max-view) is used. If width/height is not 'display-end, then the given width/height is constrained to the editor’s size.

The default implementation triggers a redraw of the editor, either immediately or at the end of the current edit sequence (if any) started by begin-edit-sequence.

See also size-cache-invalid.

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.

See also cut.

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 in text% or on-delete in pasteboard% to monitor content deletions changes.

(send an-editor load-file  [ filename             format             show-errors?])   →   boolean?

filename : (or/c path-string? #f) = #f

format   :   (or/c 'guess 'same 'copy 'standard       'text 'text-force-cr)   =   'guess

show-errors? : any/c = #t

Loads a file into the editor and returns #t. If an error occurs, an exception is raised.

If filename is #f, then the internally stored filename will be used; if filename is "" or if the internal name is unset or temporary, then the user will be prompted for a name.

The possible values for format are listed below. A single set of format values are used for loading and saving files:

• 'guess — guess the format based on extension and/or contents; when saving a file, this is the same as 'standard

• 'same — read in whatever format was last loaded or saved

• 'standard — read/write a standard file (binary format)

• 'copy — write using whatever format was last loaded or saved, but do not change the modification flag or remember filename (saving only)

• 'text — read/write a text file (text% only); file writing uses the platform’s text-mode conventions (e.g., newlines as return–linefeed combinations under Windows) when not specifically disabled via use-file-text-mode

• 'text-force-cr — read/write a text file (text% only); when writing, change automatic newlines (from word-wrapping) into real carriage returns

In a text% instance, the format returned from get-file-format is always one of 'standard, 'text, or 'text-force-cr.

The show-errors? argument is no longer used.

The filename used to load the file can be retrieved with get-filename. For a text% instance, the format can be retrieved with get-file-format. However, if an error occurs while loading the file, the filename is set to #f.

See also on-load-file, after-load-file, can-load-file?, and set-load-overwrites-styles.

The x box is filled with the translated x-coordinate of the value initially in x, unless x is #f. The y box is filled with the translated x-coordinate of the value initially in y, unless y is #f.

The result is only valid when the editor is displayed (see Editor Structure and Terminology).

See also global-to-local.

Location information is often computed on demand, and begin-edit-sequence tends to delay the computation.

When the editor is locked for reflowing, location information cannot be recomputed. See also Internal Editor Locks.

See also is-locked?.

This method does not affect internal locks, as discussed in Internal Editor Locks.

The localx, localy, width, and height arguments specify the area that needs repainting in the coordinate system of snip.

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

For text% objects: Calling this method may force the recalculation of location information, 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).

The editor is locked for writing and reflowing during the call to on-change.

Default implementation: Does nothing.

Consider overriding on-local-char or on-default-char instead of this method.

Default implementation: Either passes this event on to a caret-owning snip or calls on-local-char. In the latter case, text% first calls hide-cursor-until-moved.

Default implementation: Does nothing.

Default implementation: Does nothing. See also on-default-event in text% and on-default-event in pasteboard%.

Default implementation: If automatic wrapping is enabled (see auto-wrap ) then set-max-width is called with the maximum width of all of the editor’s canvases (according to the administrators; call-as-primary-owner in editor-canvas% is used with each canvas to set the administrator and get the view size). If the editor is displayed but not in a canvas, the unique width is obtained from the editor’s administrator (there is only one). If the editor is not displayed, the editor’s maximum width is not changed.

During an edit sequence, all callbacks methods are invoked normally, but it may be appropriate for these callbacks to delay computation during an edit sequence. The callbacks must manage this delay manually. Thus, when overriding other callback methods, such as on-insert in text%, on-insert in pasteboard%, after-insert in text%, or after-insert in pasteboard%, consider overriding on-edit-sequence and after-edit-sequence as well.

“Top-level edit sequence” refers to an outermost pair of begin-edit-sequence and end-edit-sequence calls. The embedding of an editor within another editor does not affect the timing of calls to on-edit-sequence, even if the embedding editor is in an edit sequence.

Pairings of on-edit-sequence and after-edit-sequence can be nested if an after-edit-sequence starts a new edit sequence, since after-edit-sequence is called after an edit sequence ends. However, on-edit-sequence can never start a new top-level edit sequence (except through an unpaired end-edit-sequence), because it is called after a top-level edit sequence starts.

Default implementation: Does nothing.

Consider overriding on-local-event or on-default-event instead of this method.

Default implementation: Either passes this event on to a caret-owning snip, selects a new caret-owning snip (text% only) and passes the event on to the selected snip, or calls on-local-event. A new caret-owning snip is selected in a text% object when the click is on an event-handling snip, and not too close to the space between snips (see get-between-threshold ).

The filename argument is the name the file will be loaded from. See load-file for information about format.

Note that the filename argument cannot be a string; it must be a path value.

Default implementation: Does nothing.

Consider overriding on-default-char instead of this method.

Default implementation: Either lets the keymap handle the event or calls on-default-char.

Consider overriding on-default-event instead of this method.

Default implementation: Either lets the keymap handle the event or calls on-default-event.

Default implementation: Creates a editor-snip% with either a sub-editor from text% or sub-pasteboard from pasteboard%, depending on whether type is 'text or 'pasteboard. The keymap (see keymap%) and style list (see style-list%) for of the new sub-editor are set to the keymap and style list of this editor.

Note that the filename argument cannot be a string; it must be a path value.

Default implementation: Returns (make-object image-snip% filename kind relative-path? inline?).

The before? argument is #t when the method is called just before a painting the contents of the editor or #f when it is called after painting. The left, top, right, and bottom arguments specify which region of the editor is being repainted, in editor coordinates. To get the coordinates for dc, offset editor coordinates by adding (dx, dy). See Caret Ownership for information about draw-caret.

The on-paint method, together with the snips’ draw methods, must be able to draw the entire state of an editor. Never paint directly into an editor’s display canvas except from within on-paint or draw. Instead, put all extra drawing code within on-paint and call invalidate-bitmap-cache when part of the display needs to be repainted.

If an on-paint method uses cached location information, then the cached information should be recomputed in response to a call of invalidate-bitmap-cache.

The on-paint method must not make any assumptions about the state of the drawing context (e.g., the current pen), except that the clipping region is already set to something appropriate. Before on-paint returns, it must restore any drawing context settings that it changes.

The editor is internally locked for writing and reflowing during a call to this method (see also Internal Editor Locks).

See also invalidate-bitmap-cache.

Default implementation: Does nothing.

The filename argument is the name the file will be saved to. See load-file for information about format.

Note that the filename argument cannot be a string; it must be a path value.

Default implementation: Does nothing.

See also set-modified.

Default implementation: If modified? is true and the editor was not already modified (i.e., its is-modified? method reports #f), then the set-modified method is called with #t. If the editor was already modified, then the internal modify-counter is incremented.

If modified? is #f, and if the modify-counter is 1, then the set-modified method is called with #f (on the assumption that the modify-counter was set to 1 by an earlier call to this method for the same snip).

The focus state of an editor can be changed by by the system, and such changes do not go through this method; use on-focus to monitor focus changes.

Default implementation: Propagates the flag to any snip with the editor-local focus. If no sub-editors are active, the editor assumes the caret ownership.

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.

The system may execute a paste (in response to other method calls) without calling this method. To extend or re-implement copying, override the do-paste in text% or do-paste in pasteboard% method.

See also get-paste-text-only.

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.

To extend or re-implement copying, override the do-paste-x-selection in text% or do-paste-x-selection in pasteboard% method.