8 Editor Functions

• "copy-clipboard"

• "copy-append-clipboard"

• "cut-clipboard"

• "cut-append-clipboard"

• "paste-clipboard"

• "paste-x-selection"

• "delete-selection"

• "clear-selection"

• "undo"

• "redo"

• "select-all"

See also add-editor-keymap-functions.

See also add-editor-keymap-functions.

If text-only? is #f, then menu items that insert non-text snips (such as Insert Image...) are appended to the menu.

If popup-position is not #f, then append-editor-operation-menu-items is expected to have been called to build a popup menu and the two elements of the list should be the text% object where the mouse was clicked for the popup menu and the position where the click happened. In that case, the Copy and Cut menus are enabled when the click lands on a snip that is not a string-snip%, and the corresponding callbacks will copy and cut that one snip.

The initializer takes a keymap object and returns nothing. The default initializer chains the given keymap to an internal keymap that implements standard text editor keyboard and mouse bindings for cut, copy, paste, undo, and select-all. The right mouse button is mapped to popup an edit menu when the button is released. On Unix, start-of-line (Ctl-A) and end-of-line (Ctl-E) are also mapped.

First case:

If on? is #t, m: corresponds to the Command key. If on? is #f, then m: corresponds to no key on Mac OS X.

Second case:

Returns #t if m: corresponds to Command, #f otherwise.

An instance of string-snip% in text-editor generates a character sequence in the resulting port. All other kinds of snips are passed to snip-filter to obtain a “special” value for the port. If a snip is returned as the first result from snip-filter, and if the snip is an instance of readable-snip<%>, the snip generates a special value for the port through the read-special method. If snip-filter returns any other kind of snip, it is copied for the special result. Finally, a non-snip first result from snip-filter is used directly as the special result.

The port-name argument is used for the input port’s name. The expect-to-read-all? argument is a performance hint; use #t if the entire port’s stream will be read.

The result port must not be used if text-editor changes in any 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). The get-revision-number method can be used to detect any of these changes.

To help guard against such uses, if lock-while-reading? argument is a true value, then open-input-text-editor will lock the text-editor and call begin-edit-sequence before it returns and unlock it and call end-edit-sequence after it is safe to use the above methods. (In some cases, it will not lock the editor or put it in an edit sequence at all, if using those methods are always safe.)

If special-filter is provided, it is applied to any value written to the port with write-special, and the result is inserted in its place. If a special value is a snip% object, it is inserted into the editor. Otherwise, the special value is displayed into the editor.

If line counting is enabled for the resulting output port, then the port will report the line, offset from the line’s start, and position within the editor at which the port writes data.

If eventspace is not #f, then when the output port is used in a thread other than eventspace’s handler thread, content is delivered to text-editor through a low-priority callback in eventspace. Thus, if eventspace corresponds to the eventspace for the editor’s displays, writing to the output port is safe from any thread.

If eventspace is #f, beware that the port is only weakly thread-safe. Content is delivered to text-editor in an edit sequence, but an edit sequence is not enough synchronization if, for example, the editor is displayed in an enabled editor-canvas%. See Editors and Threads for more information.

One or more editors can be read from the stream by calling the editor’s read-from-file method. (The number of editors to be read must be known by the application beforehand.) When all editors are read, call read-editor-global-footer. Calls to read-editor-global-header and read-editor-global-footer must bracket any call to read-from-file, and only one stream at a time can be read using these methods or written using write-editor-global-header and write-editor-global-footer.

When reading from streams that span Racket versions, use read-editor-version before this procedure.

If parse-format? is true, then in-base is checked for an initial "WXME" format indicator. Use #f when "WXME" has been consumed already by format-dispatching code.

If raise-errors? is true, then an error in reading triggers an exception, instead of a #f result.

The handler recognizes Racket editor-format files (see File Format) and decodes them for loading. It is normally installed as GRacket starts (see Running Racket or GRacket).

The handler recognizes editor files by the first twelve characters of the file: WXME01‹digit›‹digit› ## . Such a file is opened for loading by creating a text% object, loading the file into the object with insert-file, and then converting the editor content into a port with open-input-text-editor. After obtaining a port in this way, the content is read in essentially the same way as by the default Racket load handler. The difference is that the editor may contain instances of readable-snip<%>, which are “read” though the snips’ read-special method; see open-input-text-editor for details.

One or more editors can be written to the stream by calling the editor’s write-to-file method. When all editors are written, call write-editor-global-footer. Calls to write-editor-global-header and write-editor-global-footer must bracket any call to write-to-file, and only one stream at a time can be written using these methods or read using read-editor-global-header and read-editor-global-footer.

To support streams that span Racket versions, use write-editor-version before this procedure.

See also File Format.

The out argument is currently not used, but out-base should be the base for out. In the future, out may record information about the version for later version-sensitive output.

The result is #t if the write succeeded, #f otherwise.