| editor<%> : interface? |
The editor<%> interface is implemented by text% and pasteboard%.
| (send an-editor add-canvas canvas) → void? |
| canvas : (is-a?/c editor-canvas%) |
Adds a canvas to this editor’s list of displaying canvases. (See get-canvases.)
Normally, this method is called only by set-editor in editor-canvas%.
| (send an-editor add-undo undoer) → void? |
| undoer : (-> any) |
Adds an undoer procedure to the editor’s undo stack. If an undo is currently being performed, the undoer is added to the editor’s redo stack. The undoer is called by the system when it is undoing (or redoing) changes to an editor, and when this undoer is the first item on the undo (or redo) stack.
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.
| (send an-editor adjust-cursor event) |
| → (or/c (is-a?/c cursor%) false/c) |
| event : (is-a?/c mouse-event%) |
Specification: Gets a cursor to be used in the editor’s display. If the return value is #f, a default cursor is used.
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.
| (send an-editor after-edit-sequence) → void? |
Refine this method with augment.
Specification: Called after a top-level edit sequence completes (involving unnested begin-edit-sequence and end-edit-sequence).
See also on-edit-sequence.
Default implementation: Does nothing.
| (send an-editor after-load-file success?) → void? |
| success? : any/c |
Refine this method with augment.
Specification: Called just after the editor is loaded from a file.
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.
| (send an-editor after-save-file success?) → void? |
| success? : any/c |
Refine this method with augment.
Specification: Called just after the editor is saved to a file.
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.
| (send an-editor auto-wrap) → boolean? |
| (send an-editor auto-wrap auto-wrap?) → void? |
| auto-wrap? : any/c |
Enables or disables automatically calling set-max-width in response to on-display-size, or gets the state of auto-wrapping. For text editors, this has the effect of wrapping the editor’s contents to fit in a canvas displaying the editor (the widest one if multiple canvases display the editor). For pasteboard editors, “auto-wrapping” merely truncates the area of the pasteboard to match its canvas display.
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.
| ||||||||||||||
| undoable? : any/c = #t | ||||||||||||||
| interrupt-streak? : any/c = #t |
Specification: The begin-edit-sequence and end-edit-sequence methods are used to bracket a set of editor modifications so that the results are all displayed at once. The commands may be nested arbitrarily deep. Using these functions can greatly speed up displaying the changes.
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.
| ||||||||||||
| → void? | ||||||||||||
| f : (is-a?/c editor-stream-out%) | ||||||||||||
| name : string? | ||||||||||||
| buffer : (box/c (and/c exact? integer?)) |
This method must be called before writing any special header data to a stream. See File Format and write-headers-to-file for more information.
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.
| (send an-editor blink-caret) → void? |
Specification: Tells the editor to blink the selection caret. This method is called periodically when the editor’s display has the keyboard focus.
Default implementation: Propagates the request to any snip with the editor-local focus.
| ||||||||||||||
| ||||||||||||||
| recursive? : any/c = #t |
Specification: Checks whether a generic edit command would succeed for the editor. This check is especially useful for enabling and disabling menus on demand. See do-edit-operation for information about the op and recursive? arguments.
Default implementation: Allows the operation depending on the selection, whether the editor is locked, etc.
| ||||||||||||||
| filename : path? | ||||||||||||||
|
Refine this method with augment.
Specification: Called just before the editor is loaded from a file. If the return value is #f, the file is not loaded. See also on-load-file and after-load-file.
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.
| ||||||||||||||
| filename : path? | ||||||||||||||
|
Refine this method with augment.
Specification: Called just before the editor is saved to a file. If the return value is #f, the file is not saved. See also on-save-file and after-save-file.
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.
| (send an-editor change-style delta) → void? |
| delta : (or/c (is-a?/c style-delta%) false/c) |
| (send an-editor change-style style) → void? |
| style : (or/c (is-a?/c style<%>) false/c) |
Changes the style for items in the editor, either by applying a style delta or using a specific style.
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.
| (send an-editor clear) → void? |
Deletes the currently selected items.
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 clear-undos) → void? |
Destroys the undo history of the editor.
| (send an-editor copy [extend? time]) → void? |
| extend? : any/c = #f |
| time : (and/c exact? integer?) = 0 |
Copies items into the clipboard. If extend? is not #f, the old clipboard contents are appended.
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.
| (send an-editor copy-self) |
| → (or/c (is-a?/c text%) (is-a?/c pasteboard%)) |
Creates a new editor with the same properties as this one. After an editor is created (either a text% or pasteboard% instance, as appropriate), the new editor is passed to copy-self-to.
| (send an-editor copy-self-to dest) → void? |
| dest : (or/c (is-a?/c text%) (is-a?/c pasteboard%)) |
Copies the properties of an-editor to dest.
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.
| (send an-editor cut [extend? time]) → void? |
| extend? : any/c = #f |
| time : (and/c exact? integer?) = 0 |
Copies and then deletes the currently selected items. If extend? is not #f, the old clipboard contents are appended.
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.
| |||||||||||||||||
| x : real? | |||||||||||||||||
| y : real? |
Converts the given coordinates from top-level display coordinates (usually canvas coordinates) to editor location coordinates. The same calculation is performed by global-to-local.
The result is only valid when the editor is displayed (see Editor Structure and Terminology).
See also editor-location-to-dc-location.
| (send an-editor default-style-name) → string? |
Returns the name of a style to be used for newly inserted text, etc. The default is "Standard".
| |||||||||||||||||||||
| |||||||||||||||||||||
| recursive? : any/c = #t | |||||||||||||||||||||
| time : (and/c exact? integer?) = 0 |
Performs a generic edit command. The op argument must be a valid edit command, one of:
'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.
| |||||||||||||||||
| x : real? | |||||||||||||||||
| y : real? |
Converts the given coordinates from editor location coordinates to top-level display coordinates (usually canvas coordinates). The same calculation is performed by local-to-global.
The result is only valid when the editor is displayed (see Editor Structure and Terminology).
See also dc-location-to-editor-location.
| (send an-editor end-edit-sequence) → void? |
See begin-edit-sequence.
| ||||||||
| → void? | ||||||||
| f : (is-a?/c editor-stream-out%) | ||||||||
| buffer-value : (and/c exact? integer?) |
This method must be called after writing any special header data to a stream. The buffer-value argument must be the value put in the buffer argument box by begin-write-header-footer-to-file.
See File Format and write-headers-to-file for more information.
| (send an-editor find-first-snip) |
| → (or/c (is-a?/c snip%) false/c) |
Returns the first snip in the editor, or #f if the editor is empty. To get all of the snips in the editor, use the next in snip% on the resulting snip.
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.)
| (send an-editor find-scroll-line location) |
| → exact-nonnegative-integer? |
| location : real? |
Maps a vertical location within the editor to a vertical scroll position.
For text% objects: Calling this method may force the recalculation of location information, even if the editor currently has delayed refreshing (see