c0a8a01222
tree and verifying that there are no changes). (Also fixed a few bugs that were in the code) svn: r14427
433 lines
15 KiB
Racket
433 lines
15 KiB
Racket
#lang scribble/doc
|
|
@(require "common.ss"
|
|
scribble/bnf)
|
|
|
|
@title{Editor Functions}
|
|
|
|
|
|
@defproc[(add-editor-keymap-functions [keymap (is-a?/c keymap%)])
|
|
void?]{
|
|
|
|
Given a @scheme[keymap%] object, the keymap is loaded with mappable
|
|
functions that apply to all @scheme[editor<%>] objects:
|
|
|
|
@itemize[
|
|
@item{@scheme["copy-clipboard"]}
|
|
@item{@scheme["copy-append-clipboard"]}
|
|
@item{@scheme["cut-clipboard"]}
|
|
@item{@scheme["cut-append-clipboard"]}
|
|
@item{@scheme["paste-clipboard"]}
|
|
@item{@scheme["paste-x-selection"]}
|
|
@item{@scheme["delete-selection"]}
|
|
@item{@scheme["clear-selection"]}
|
|
@item{@scheme["undo"]}
|
|
@item{@scheme["redo"]}
|
|
@item{@scheme["select-all"]}
|
|
]
|
|
|
|
}
|
|
|
|
@defproc[(add-pasteboard-keymap-functions [keymap (is-a?/c keymap%)])
|
|
void?]{
|
|
|
|
Given a @scheme[keymap%] object, the table is loaded with mappable
|
|
functions that apply to @scheme[pasteboard%] objects. Currently,
|
|
there are no such functions.
|
|
|
|
See also
|
|
@scheme[add-editor-keymap-functions].
|
|
|
|
}
|
|
|
|
@defproc[(add-text-keymap-functions [keymap (is-a?/c keymap%)])
|
|
void?]{
|
|
|
|
Given a @scheme[keymap%] object, the table is loaded with functions
|
|
that apply to all @scheme[text%] objects:
|
|
@itemize[
|
|
@item{@scheme["forward-character"]}
|
|
@item{@scheme["backward-character"]}
|
|
@item{@scheme["previous-line"]}
|
|
@item{@scheme["next-line"]}
|
|
@item{@scheme["previous-page"]}
|
|
@item{@scheme["next-page"]}
|
|
@item{@scheme["forward-word"]}
|
|
@item{@scheme["backward-word"]}
|
|
@item{@scheme["forward-select"]}
|
|
@item{@scheme["backward-select"]}
|
|
@item{@scheme["select-down"]}
|
|
@item{@scheme["select-up"]}
|
|
@item{@scheme["select-page-up"]}
|
|
@item{@scheme["select-page-down"]}
|
|
@item{@scheme["forward-select-word"]}
|
|
@item{@scheme["backward-select-word"]}
|
|
@item{@scheme["beginning-of-file"]}
|
|
@item{@scheme["end-of-file"]}
|
|
@item{@scheme["beginning-of-line"]}
|
|
@item{@scheme["end-of-line"]}
|
|
@item{@scheme["select-to-beginning-of-file"]}
|
|
@item{@scheme["select-to-end-of-file"]}
|
|
@item{@scheme["select-to-beginning-of-line"]}
|
|
@item{@scheme["select-to-end-of-line"]}
|
|
@item{@scheme["copy-clipboard"]}
|
|
@item{@scheme["copy-append-clipboard"]}
|
|
@item{@scheme["cut-clipboard"]}
|
|
@item{@scheme["cut-append-clipboard"]}
|
|
@item{@scheme["paste-clipboard"]}
|
|
@item{@scheme["paste-x-selection"]}
|
|
@item{@scheme["delete-selection"]}
|
|
@item{@scheme["delete-previous-character"]}
|
|
@item{@scheme["delete-next-character"]}
|
|
@item{@scheme["clear-selection"]}
|
|
@item{@scheme["delete-to-end-of-line"]}
|
|
@item{@scheme["delete-next-word"]}
|
|
@item{@scheme["delete-previous-word"]}
|
|
@item{@scheme["delete-line"]}
|
|
@item{@scheme["undo"]}
|
|
@item{@scheme["redo"]}
|
|
]
|
|
|
|
See also
|
|
@scheme[add-editor-keymap-functions].
|
|
|
|
}
|
|
|
|
@defproc[(append-editor-font-menu-items [menu (or/c @scheme[menu%] (is-a?/c popup-menu%))])
|
|
void?]{
|
|
Appends menu items to a given menu (not a popup menu) to implement a
|
|
standard set of font-manipulation operations, such as changing the
|
|
font face or style. The callback for each menu item uses
|
|
@xmethod[top-level-window<%> get-edit-target-object] (finding the frame by following a chain of parents until a frame is
|
|
reached); if the result is an @scheme[editor<%>] object,
|
|
@xmethod[editor<%> change-style] is called on the editor.
|
|
|
|
}
|
|
|
|
@defproc[(append-editor-operation-menu-items [menu (or/c @scheme[menu%] (is-a?/c popup-menu%))]
|
|
[text-only? any/c #t])
|
|
void?]{
|
|
Appends menu items to a given menu (not a popup menu) to implement the
|
|
standard editor operations, such as cut and paste. The callback for
|
|
each menu item uses
|
|
@xmethod[top-level-window<%> get-edit-target-object] (finding the frame by following a chain of parents until a frame is
|
|
reached); if the result is an @scheme[editor<%>] object,
|
|
@xmethod[editor<%> do-edit-operation] is called on the editor.
|
|
|
|
|
|
|
|
If @scheme[text-only?] is @scheme[#f], then menu items that insert
|
|
non-text snips (such as @onscreen{Insert Image...}) are appended to
|
|
the menu.
|
|
|
|
|
|
|
|
}
|
|
|
|
@defparam[current-text-keymap-initializer proc ((is-a?/c keymap%) . -> . any/c)]{
|
|
|
|
Parameter that specifies a keymap-initialization procedure. This
|
|
procedure is called to initialize the keymap of a
|
|
@scheme[text-field%] object or a @scheme[text%] object created by
|
|
@scheme[graphical-read-eval-print-loop].
|
|
|
|
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. Under X,
|
|
start-of-line (Ctl-A) and end-of-line (Ctl-E) are also mapped.
|
|
|
|
}
|
|
|
|
@defproc[(editor-set-x-selection-mode [on any/c])
|
|
void?]{
|
|
|
|
Under X Windows, editor selections conform to the X Windows selection
|
|
conventions instead of a clipboard-based convention. If @scheme[on] is
|
|
@scheme[#f], the behavior is switched to the clipboard-based convention
|
|
(where copy must be explicitly requested before a paste).
|
|
|
|
|
|
|
|
}
|
|
|
|
@defproc[(get-the-editor-data-class-list)
|
|
(is-a?/c editor-data-class-list<%>)]{
|
|
|
|
Gets the editor data class list instance for the current eventspace.
|
|
|
|
|
|
|
|
}
|
|
|
|
@defproc[(get-the-snip-class-list)
|
|
(is-a?/c snip-class-list<%>)]{
|
|
|
|
Gets the snip class list instance for the current eventspace.
|
|
|
|
|
|
|
|
}
|
|
|
|
@defproc*[([(map-command-as-meta-key [on? any/c])
|
|
void?]
|
|
[(map-command-as-meta-key)
|
|
boolean?])]{
|
|
Determines the interpretation of @litchar{m:} for a @scheme[keymap%]
|
|
mapping under Mac OS X. See also
|
|
@xmethod[keymap% map-function].
|
|
|
|
|
|
First case:
|
|
|
|
|
|
If @scheme[on?] is @scheme[#t], @litchar{m:} corresponds to the Command key. If
|
|
@scheme[on?] is @scheme[#f], then @litchar{m:} corresponds to no key under Mac OS
|
|
X.
|
|
|
|
|
|
|
|
Second case:
|
|
|
|
|
|
Returns @scheme[#t] if @litchar{m:} corresponds to Command,
|
|
@scheme[#f] otherwise.
|
|
|
|
}
|
|
|
|
@defproc[(open-input-graphical-file [filename string?])
|
|
input-port]{
|
|
|
|
Opens @scheme[filename] (in @scheme['binary] mode) and checks whether it looks
|
|
like a ``graphical'' file in editor format. If the file does not
|
|
appear to be an editor file, the file port is returned with line
|
|
counting enabled. Otherwise, the file is loaded into an editor, and
|
|
the result port is created with
|
|
@scheme[open-input-text-editor].
|
|
|
|
|
|
}
|
|
|
|
@defproc[(open-input-text-editor [text-editor (is-a?/c text%)]
|
|
[start-position exact-nonnegative-integer? 0]
|
|
[end-position (or/c exact-nonnegative-integer? (one/of 'end)) 'end]
|
|
[snip-filter ((is-a?/c snip%) . -> . any/c) (lambda (s) s)]
|
|
[port-name any/c @scheme[text-editor]]
|
|
[expect-to-read-all? any/c #f])
|
|
input-port]{
|
|
|
|
Creates an input port that draws its content from @scheme[text-editor].
|
|
The editor content between positions @scheme[start-position] and
|
|
@scheme[end-position] is the content of the port. If @scheme[end-position]
|
|
is @scheme['end], the content runs until the end of the editor. If a
|
|
snip that is not a @scheme[string-snip%] object spans
|
|
@scheme[start-position] or @scheme[end-position], the entire snip
|
|
contributes to the port. If a @scheme[string-snip%] instance spans
|
|
@scheme[start-position], only the part of the snip after
|
|
@scheme[start-position] contributes, and if a @scheme[string-snip%]
|
|
object spans @scheme[end-position], only the part before
|
|
@scheme[end-position] contributes.
|
|
|
|
An instance of @scheme[string-snip%] in @scheme[text-editor] generates
|
|
a character sequence in the resulting port. All other kinds of snips
|
|
are passed to @scheme[snip-filter] to obtain a ``special'' value for
|
|
the port. If a snip is returned as the first result from
|
|
@scheme[snip-filter], and if the snip is an instance of
|
|
@scheme[readable-snip<%>], the snip generates a special value for the
|
|
port through the @method[readable-snip<%> read-special] method. If
|
|
@scheme[snip-filter] returns any other kind of snip, it is copied for
|
|
the special result. Finally, a non-snip first result from
|
|
@scheme[snip-filter] is used directly as the special result.
|
|
|
|
The @scheme[port-name] argument is used for the input port's name. The
|
|
@scheme[expect-to-read-all?] argument is a performance hint; use
|
|
@scheme[#t] if the entire port's stream will be read.
|
|
|
|
The result port must not be used if @scheme[text-editor] changes in any
|
|
of the following ways: a snip is inserted (see
|
|
@method[text% after-insert]), a snip is deleted (see
|
|
@method[text% after-delete]), a snip is split (see
|
|
@method[text% after-split-snip]), snips are merged (see
|
|
@method[text% after-merge-snips]), or a snip changes its count (which is rare; see
|
|
@method[snip-admin% recounted]). The
|
|
@method[text% get-revision-number] method can be used to detect any of these changes.
|
|
|
|
|
|
|
|
}
|
|
|
|
@defproc[(open-output-text-editor [text-editor (is-a?/c text%)]
|
|
[start-position (or/c exact-nonnegative-integer? (one/of 'end)) 'end]
|
|
[special-filter (any/c . -> . any/c) (lambda (x) x)]
|
|
[port-name any/c @scheme[text-editor]])
|
|
output-port]{
|
|
|
|
Creates an output port that delivers its content to @scheme[text-editor].
|
|
The content is written to @scheme[text-editor] starting at the position
|
|
@scheme[start-position], where @scheme['end] indicates that output should
|
|
start at the text editor's current end position.
|
|
|
|
If @scheme[special-filter] is provided, it is applied to any value
|
|
written to the port with @scheme[write-special], and the result is
|
|
inserted in its place. If a special value is a @scheme[snip%]
|
|
object, it is inserted into the editor. Otherwise, the special value
|
|
is @scheme[display]ed 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.
|
|
|
|
|
|
|
|
}
|
|
|
|
@defproc[(read-editor-global-footer [in (is-a?/c editor-stream-in%)])
|
|
boolean?]{
|
|
|
|
See
|
|
@scheme[read-editor-global-header]. Call
|
|
@scheme[read-editor-global-footer] even if
|
|
@scheme[read-editor-global-header] returns @scheme[#f].
|
|
|
|
|
|
|
|
}
|
|
|
|
@defproc[(read-editor-global-header [in (is-a?/c editor-stream-in%)])
|
|
boolean?]{
|
|
|
|
Reads data from @scheme[in] to initialize for reading editors from the
|
|
stream. The return value is @scheme[#t] if the read succeeds, or @scheme[#f]
|
|
otherwise.
|
|
|
|
One or more editors can be read from the stream by calling
|
|
the editor's
|
|
@method[editor<%> read-from-file] method. (The number of editors to be
|
|
read must be known by the application beforehand.) When all editors
|
|
are read, call
|
|
@scheme[read-editor-global-footer]. Calls to
|
|
@scheme[read-editor-global-header] and
|
|
@scheme[read-editor-global-footer] must bracket any call to
|
|
@method[editor<%> read-from-file], and only one stream at a time
|
|
can be read using these methods or written using
|
|
@scheme[write-editor-global-header] and
|
|
@scheme[write-editor-global-footer].
|
|
|
|
When reading from streams that span PLT Scheme versions, use
|
|
@scheme[read-editor-version] before this procedure.
|
|
|
|
|
|
|
|
}
|
|
|
|
@defproc[(read-editor-version [in (is-a?/c editor-stream-in%)]
|
|
[in-base (is-a?/c editor-stream-in-base%)]
|
|
[parse-format? any/c]
|
|
[raise-errors? any/c #t])
|
|
boolean?]{
|
|
|
|
Reads version information from @scheme[in-base], where @scheme[in-base] is
|
|
the base for @scheme[in]. The version information parsed from
|
|
@scheme[in-base] is recorded in @scheme[in] for later version-sensitive
|
|
parsing. The procedure result is true if the version information was
|
|
read successfully and if the version is supported.
|
|
|
|
If @scheme[parse-format?] is true, then @scheme[in-base] is checked for an
|
|
initial @scheme["WXME"] format indicator. Use @scheme[#f] when
|
|
@scheme["WXME"] has been consumed already by format-dispatching code.
|
|
|
|
If @scheme[raise-errors?] is true, then an error in reading triggers an
|
|
exception, instead of a @scheme[#f] result.
|
|
|
|
|
|
|
|
}
|
|
|
|
@defproc[(text-editor-load-handler [filename path string]
|
|
[expected-module-name (or/c symbol false/c)])
|
|
any/c]{
|
|
|
|
This procedure is a load handler for use with @scheme[current-load].
|
|
|
|
The handler recognizes PLT Scheme editor-format files (see
|
|
@secref["editorfileformat"]) and decodes them for loading. It is
|
|
normally installed as MrEd starts (see @secref[#:doc reference-doc
|
|
"running-sa"]).
|
|
|
|
The handler recognizes editor files by the first twelve characters of
|
|
the file: @litchar{WXME01}@nonterm{digit}@nonterm{digit}@litchar{ ## }.
|
|
Such a file is opened for loading by creating a @scheme[text%]
|
|
object, loading the file into the object with @method[editor<%>
|
|
insert-file], and then converting the editor content into a port with
|
|
@scheme[open-input-text-editor]. After obtaining a port in this way,
|
|
the content is read in essentially the same way as by the default
|
|
MzScheme load handler. The difference is that the editor may contain
|
|
instances of @scheme[readable-snip<%>], which are ``read'' though the
|
|
snips' @method[readable-snip<%> read-special] method; see
|
|
@scheme[open-input-text-editor] for details.
|
|
|
|
|
|
}
|
|
|
|
@defthing[the-editor-wordbreak-map (is-a?/c editor-wordbreak-map%)]{
|
|
|
|
See @scheme[editor-wordbreak-map%].
|
|
|
|
}
|
|
|
|
@defthing[the-style-list (is-a?/c style-list%)]{
|
|
|
|
See @scheme[style-list%].
|
|
|
|
}
|
|
|
|
@defproc[(write-editor-global-footer [out (is-a?/c editor-stream-out%)])
|
|
boolean?]{
|
|
|
|
See @scheme[write-editor-global-header]. Call
|
|
@scheme[write-editor-global-footer] even if
|
|
@scheme[write-editor-global-header] returns @scheme[#f].
|
|
|
|
|
|
|
|
}
|
|
|
|
@defproc[(write-editor-global-header [out (is-a?/c editor-stream-out%)])
|
|
boolean?]{
|
|
|
|
Writes data to @scheme[out], initializing it for writing editors to
|
|
the stream. The return value is @scheme[#t] if the write succeeds, or
|
|
@scheme[#f] otherwise.
|
|
|
|
One or more editors can be written to the stream by calling the
|
|
editor's @method[editor<%> write-to-file] method. When all editors
|
|
are written, call @scheme[write-editor-global-footer]. Calls to
|
|
@scheme[write-editor-global-header] and
|
|
@scheme[write-editor-global-footer] must bracket any call to
|
|
@method[editor<%> write-to-file], and only one stream at a time can
|
|
be written using these methods or read using
|
|
@scheme[read-editor-global-header] and
|
|
@scheme[read-editor-global-footer].
|
|
|
|
To support streams that span PLT Scheme versions, use
|
|
@scheme[write-editor-version] before this procedure.
|
|
|
|
See also @secref["editorfileformat"].
|
|
|
|
}
|
|
|
|
@defproc[(write-editor-version [out (is-a?/c editor-stream-out%)]
|
|
[out-base (is-a?/c editor-stream-out-base%)])
|
|
boolean?]{
|
|
|
|
Writes version information to @scheme[out-base] in preparation for
|
|
writing editor information to the stream @scheme[out].
|
|
|
|
The @scheme[out] argument is currently not used, but @scheme[out-base]
|
|
should be the base for @scheme[out]. In the future, @scheme[out] may record
|
|
information about the version for later version-sensitive output.
|
|
|
|
The result is @scheme[#t] if the write succeeded, @scheme[#f] otherwise.
|
|
|
|
}
|