suzanne.soy/racket
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

some progress made documenting the framework

Browse Source 
svn: r9443
This commit is contained in:
Robby Findler 2008-04-23 23:24:17 +00:00
parent dad2ce6c03
commit 5d6724c75b
30 changed files with 5000 additions and 9 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

18
collects/framework/framework-docs.ss
View File

@ -43,14 +43,22 @@
(define-syntax (export/docs stx)
(syntax-case stx ()
[(_ (id ctc argspec docs ...) ...)
#'(begin (fw-doc-form id ctc argspec docs ...) ...)]))
[(_ tag docs ...)
(let ([reg (regexp (format "^~a:" (syntax->datum #'tag)))])
(with-syntax ([((id ctc argspec docs ...) ...)
(filter (λ (x)
(syntax-case x ()
[(id ctc argspec docs ...)
(regexp-match reg (format "~a" (syntax->datum #'id)))]))
(syntax->list #'(docs ...)))])
#'(begin (fw-doc-form id ctc argspec docs ...) ...)))]))
(define-syntax (conv/export/docs stx)
(define-struct faux-stx (obj vec) #:prefab)
(syntax-case stx ()
[(id arg)
[(id tag arg)
#`(export/docs
tag
#,@(let loop ([f-stx (syntax->datum #'arg)])
(cond
[(faux-stx? f-stx)
@ -61,4 +69,6 @@
[else f-stx])))]))
(define-syntax (def-fw-procs stx)
#'(framework-exports/srcloc-preserved conv/export/docs))
(syntax-case stx ()
[(_ tag)
#'(framework-exports/srcloc-preserved conv/export/docs tag)]))

4
collects/framework/private/framework-exports.ss
View File

@ -1362,7 +1362,7 @@
[else stx]))])
#`(define-syntax (framework-exports/srcloc-preserved stx)
(syntax-case stx ()
[(_ id)
#'(id #,marshalled)]))))])))
[(_ id tag)
#'(id tag #,marshalled)]))))])))
(framework-exports make-framework-exports/srcloc-preserved)

8
collects/scribblings/framework/framework-application.scrbl Normal file
View File

@ -0,0 +1,8 @@
#lang scribble/doc
@(require scribble/manual)
@(require (for-label framework/framework))
@(require (for-label scheme/gui))
@title{Application}
@(require framework/framework-docs)
@(def-fw-procs application)

18
collects/scribblings/framework/framework-autosave.scrbl Normal file
View File

@ -0,0 +1,18 @@
#lang scribble/doc
@(require scribble/manual)
@(require (for-label framework/framework))
@(require (for-label scheme/gui))
@title{Autosave}
@definterface[autosave:autosavable<%> ()]{
Classes that implement this interface can be autosaved.
@defmethod*[(((do-autosave) void))]{
This method is called when the object is registered to be
autosaved (see
@scheme[autosave:register]).
}
}
@(require framework/framework-docs)
@(def-fw-procs autosave)

102
collects/scribblings/framework/framework-canvas.scrbl Normal file
View File

@ -0,0 +1,102 @@
#lang scribble/doc
@(require scribble/manual)
@(require (for-label framework/framework))
@(require (for-label scheme/gui))
@title{Canvas}
@definterface[canvas:basic<%> (editor-canvas%)]{
}
@defmixin[canvas:basic-mixin (editor-canvas%) (canvas:basic<%>)]{
}
@definterface[canvas:color<%> (canvas:basic<%>)]{
\index{background color}
Mixins that implement this interface initialize the
background color of the canvas to the value of the
\index{'framework:basic-canvas-background}
\scheme|'framework:basic-canvas-background| preference.
Adds a callback so that when that preference is modified,
the background color changes.
}
@defmixin[canvas:color-mixin (canvas:basic<%>) (canvas:color<%>)]{
}
@definterface[canvas:delegate<%> (canvas:basic<%>)]{
This class is part of the delegate window implementation.
}
@defmixin[canvas:delegate-mixin (canvas:basic<%>) (canvas:delegate<%>)]{
Provides an implementation of
@scheme[canvas:delegate<%>].
@defmethod*[#:mode override (((on-superwindow-show (shown? boolean)) void))]{
Notifies the delegate window when the original window is
visible. When invisible, the blue highlighting is erased.
}
}
@definterface[canvas:info<%> (canvas:basic<%>)]{
}
@defmixin[canvas:info-mixin (canvas:basic<%>) (canvas:info<%>)]{
@defmethod*[#:mode override (((on-focus) void))]{
sets the canvas that the frame displays info about.
}
@defmethod*[#:mode override (((set-editor) void))]{
Calls
@method[frame:info<%> update-info]
to update the frame's info panel.
}
}
@definterface[canvas:wide-snip<%> (canvas:basic<%>)]{
Any
@scheme[canvas%]
that matches this interface will automatically
resize selected snips when it's size changes. Use
@method[canvas:wide-snip<%> add-tall-snip]
and
@method[canvas:wide-snip<%> add-wide-snip]
to specify which snips should be resized.
@defmethod*[(((recalc-snips) void))]{
Recalculates the sizes of the wide snips.
}
@defmethod*[(((add-wide-snip (snip (instance snip%))) void))]{
Snips passed to this method will be resized when the canvas's size
changes. Their width will be set so they take up all of the space
from their lefts to the right edge of the canvas.
}
@defmethod*[(((add-tall-snip (snip (instance snip%))) void))]{
Snips passed to this method will be resized when the canvas's size
changes. Their height will be set so they take up all of the space
from their tops to the bottom of the canvas.
}
}
@defmixin[canvas:wide-snip-mixin (canvas:basic<%>) (canvas:wide-snip<%>)]{
This canvas maintains a list of wide and tall snips and adjusts their
heights and widths when the canvas's size changes.
The result of this mixin uses the same initialization arguments as the
mixin's argument.
@defmethod*[#:mode override (((on-size (width (integer-in 0 10000)) (height (integer-in 0 10000))) void))]{
Adjusts the sizes of the marked snips.
See
@method[canvas:wide-snip<%> add-wide-snip]
and
@method[canvas:wide-snip<%> add-tall-snip].
}
}
@defclass[canvas:basic% (canvas:basic-mixin editor-canvas%) ()]{}
@defclass[canvas:color% (canvas:color-mixin canvas:basic%) ()]{}
@defclass[canvas:info% (canvas:info-mixin canvas:basic%) ()]{}
@defclass[canvas:delegate% (canvas:delegate-mixin canvas:basic%) ()]{}
@defclass[canvas:wide-snip% (canvas:wide-snip-mixin canvas:basic%) ()]{}
@(require framework/framework-docs)
@(def-fw-procs canvas)

8
collects/scribblings/framework/framework-color-model.scrbl Normal file
View File

@ -0,0 +1,8 @@
#lang scribble/doc
@(require scribble/manual)
@(require (for-label framework/framework))
@(require (for-label scheme/gui))
@title{Color Model}
@(require framework/framework-docs)
@(def-fw-procs color-model)

8
collects/scribblings/framework/framework-color-prefs.scrbl Normal file
View File

@ -0,0 +1,8 @@
#lang scribble/doc
@(require scribble/manual)
@(require (for-label framework/framework))
@(require (for-label scheme/gui))
@title{Color Prefs}
@(require framework/framework-docs)
@(def-fw-procs color-prefs)

237
collects/scribblings/framework/framework-color.scrbl Normal file
View File

@ -0,0 +1,237 @@
#lang scribble/doc
@(require scribble/manual)
@(require (for-label framework/framework))
@(require (for-label scheme/gui))
@title{Color}
@definterface[color:text<%> (text:basic<%>)]{
This interface describes how coloring is stopped and started for text
that knows how to color itself. It also describes how to query the
lexical and s-expression structure of the text.
@defmethod*[(((start-colorer (token-sym-style (-> symbol? string?)) (get-token (-> input-port? (values any? symbol? (union false? symbol?) natural-number? natural-number?))) (pairs (listof (list/p symbol? symbol?)))) void))]{
Starts tokenizing the buffer for coloring and parenthesis matching.
token-sym-style will be passed the first return symbol from get-token
and should return the style-name that the token should be colored.
get-token takes an input port and returns the next token as 5 values:
\begin{enumerate}
\item
An unused value. This value is intended to represent the textual
component of the token and may be used as such in the future.
\item
A symbol describing the type of the token. This symbol is transformed
into a style-name via the token-sym->style argument. The symbols
'white-space and 'comment have special meaning and should always be
returned for white space and comment tokens respectively. The symbol
'no-color can be used to indicate that although the token is not white
space, it should not be colored. The symbol 'eof must be used to
indicate when all the tokens have been consumed.
\item
A symbol indicating how the token should be treated by the paren
matcher or \#f. This symbol should be in the pairs argument.
\item
The starting position of the token.
\item
The ending position of the token.
\end{enumerate}
get-token will usually be implemented with a lexer using the (lib
"lex.ss" "parser-tools") library.\\
get-token must obey the following invariants:
\begin{itemize}
\item
Every position in the buffer must be accounted for in exactly one
token.
\item
The token returned by get-token must rely only on the contents of the
input port argument. This means that the tokenization of some part of
the input cannot depend on earlier parts of the input.
\item
No edit to the buffer can change the tokenization of the buffer prior
to the token immediately preceding the edit. In the following
example this invariant does not hold. If the buffer contains:\\
" 1 2 3\\
and the tokenizer treats the unmatched " as its own token (a string
error token), and separately tokenizes the 1 2 and 3, an edit to make
the buffer look like:\\
" 1 2 3"\\
would result in a single string token modifying previous tokens. To
handle these situations, get-token must treat the first line as a
single token.
\end{itemize}
pairs is a list of different kinds of matching parens. The second
value returned by get-token is compared to this list to see how the
paren matcher should treat the token. An example: Suppose pairs is
\scheme+'((|(| |)|) (|[| |]|) (begin end))+. This means that there
are three kinds of parens. Any token which has 'begin as its second
return value will act as an open for matching tokens with 'end.
Similarly any token with \scheme+'|]|+ will act as a closing match for
tokens with \scheme+'|[|+. When trying to correct a mismatched
closing parenthesis, each closing symbol in pairs will be converted to
a string and tried as a closing parenthesis.
}
@defmethod*[(((stop-colorer (clear-colors boolean |#t|)) void))]{
Stops coloring and paren matching the buffer.
If clear-colors is true all the text in the buffer will have it's
style set to Standard.
}
@defmethod*[(((force-stop-colorer (stop? boolean)) void))]{
Causes the entire tokenizing/coloring system to become inactive.
Intended for debugging purposes only.
stop? determines whether the system is being forced to stop or allowed
to wake back up.
}
@defmethod*[(((is-stopped?) boolean))]{
Indicates if the colorer for this editor has been stopped, or not.
}
@defmethod*[(((is-frozen?) boolean))]{
Indicates if this editor's colorer is frozen. See also
@method[color:text<%> freeze-colorer]
and
@method[color:text<%> thaw-colorer].
}
@defmethod*[(((freeze-colorer) void))]{
Keep the text tokenized and paren matched, but stop altering the colors.
freeze-colorer will not return until the coloring/tokenization of the
entire text is brought up-to-date. It must not be called on a locked
text.
}
@defmethod*[(((thaw-colorer (recolor boolean |#t|) (retokenize boolean |#f|)) void))]{
Start coloring a frozen buffer again.
If recolor? is \scheme|#t|, the text is re-colored. If it is
\scheme|#f| the text is not recolored. When recolor? is \scheme|#t|,
retokenize? controls how the text is recolored. \scheme|#f| causes
the text to be entirely re-colored before thaw-colorer returns using
the existing tokenization. \scheme|#t| causes the entire text to be
retokenized and recolored from scratch. This will happen in the
background after the call to thaw-colorer returns.
}
@defmethod*[(((reset-region (start natural-number?) (end (union (quote end) natural-number?))) void))]{
Set the region of the text that is tokenized.
}
@defmethod*[(((reset-regions (regions (listof (list number (union (quote end) number))))) void))]{
Sets the currently active regions to be \var{regions}.
}
@defmethod*[(((get-regions) (listof (list number (union (quote end) number)))))]{
This returns the list of regions that are currently being colored in the editor.
}
@defmethod*[(((skip-whitespace (position natural-number?) (direction (symbols (quote forward) (quote backward))) (comments? boolean)) natural-number?))]{
Returns the next non-whitespace character.
Starts from position and skips whitespace in the direction indicated
by direction. If comments? is true, comments are skipped as well as
whitespace. skip-whitespace determines whitespaces and comments by
comparing the token type to 'white-space and 'comment.
Must only be called while the tokenizer is started.
}
@defmethod*[(((backward-match (position natural-number?) (cutoff natural-number?)) (union natural-number? false?)))]{
Skip all consecutive whitespaces and comments (using skip-whitespace)
immediately preceding the position. If the token at this position is
a close, return the position of the matching open, or \scheme|#f| if
there is none. If the token was an open, return \scheme|#f|. For any
other token, return the start of that token.
Must only be called while the tokenizer is started.
}
@defmethod*[(((backward-containing-sexp) void) ((backward-containing-sexp (position natural-number?) (cutoff natural-number?)) (union natural-number? false?)))]{
Return the starting position of the interior of the (non-atomic)
s-expression containing position, or \scheme|#f| is there is none.
Must only be called while the tokenizer is started.
}
@defmethod*[(((forward-match (position natural-number?) (cutoff natural-number?)) (union natural-number? false?)))]{
Skip all consecutive whitespaces and comments (using skip-whitespace)
immediately following position. If the token at this position is an
open, return the position of the matching close, or \scheme|#f| if
there is none. For any other token, return the end of that token.
Must only be called while the tokenizer is started.
}
@defmethod*[(((insert-close-paren (position natural-number?) (char char?) (flash? boolean) (fixup? boolean)) void))]{
Position is the place to put the parenthesis and char is the
parenthesis to be added. If fixup? is true, the right kind of closing
parenthesis will be chosen from the pairs list kept last passed to
start-colorer, otherwise char will be inserted, even if it is not the
right kind. If flash? is true the matching open parenthesis will be
flashed.
}
@defmethod*[(((classify-position (position natural-number?)) symbol?))]{
Return a symbol for the lexer-determined token type for the token that
contains the item after \scheme|position|.
Must only be called while the tokenizer is started.
}
}
@defmixin[color:text-mixin (text:basic<%>) (color:text<%>)]{
Adds the functionality needed for on-the-fly coloring and parenthesis
matching based on incremental tokenization of the text.
@defmethod*[#:mode override (((lock) void))]{
}
@defmethod*[#:mode override (((on-focus) void))]{
}
@defmethod*[#:mode augment (((after-edit-sequence) void))]{
}
@defmethod*[#:mode augment (((after-set-position) void))]{
}
@defmethod*[#:mode augment (((after-change-style) void))]{
}
@defmethod*[#:mode augment (((on-set-size-constraint) void))]{
}
@defmethod*[#:mode augment (((after-insert) void))]{
}
@defmethod*[#:mode augment (((after-delete) void))]{
}
}
@defclass[color:text% (color:text-mixin text:keymap%) ()]{}
@definterface[color:text-mode<%> ()]{
}
@defmixin[color:text-mode-mixin (mode:surrogate-text<%>) (color:text-mode<%>)]{
This mixin adds coloring functionality to the mode.
@defconstructor[((get-token lexer default-lexer) (token-sym->style (token $rightarrow$ string) |scheme(λ (x) "Standard"))|) (matches (listof (list/c symbol? symbol?)) null))]{
The arguments are passed to
@method[color:text<%> start-colorer].
}
@defmethod*[#:mode override (((on-disable-surrogate) void))]{
}
@defmethod*[#:mode override (((on-enable-surrogate) void))]{
}
}
@defclass[color:text-mode% (color:text-mode-mixin mode:surrogate-text%) ()]{}
@(require framework/framework-docs)
@(def-fw-procs color)

48
collects/scribblings/framework/framework-comment-box.scrbl Normal file
View File

@ -0,0 +1,48 @@
#lang scribble/doc
@(require scribble/manual)
@(require (for-label framework/framework))
@(require (for-label scheme/gui))
@title{Comment Box}
@defclass[comment-box:snip% decorated-editor-snip% (readable-snip<%>)]{
This snip implements the comment boxes that you see in
DrScheme.
@defmethod*[#:mode override (((make-editor) (is-a?/c text%)))]{
Makes an instance of
\begin{schemedisplay}
(scheme:text-mixin text:keymap%)
\end{schemedisplay}
}
@defmethod*[#:mode override (((make-snip) (is-a?/c comment-snip%)))]{
Returns an instance of the
@scheme[comment-snip%]
class.
}
@defmethod*[#:mode override (((get-corner-bitmap) (is-a?/c bitmap%)))]{
Returns the semicolon bitmap from the file
\begin{schemedisplay}
(build-path (collection-path "icons") "semicolon.gif")
\end{schemedisplay}
}
@defmethod*[#:mode override (((get-position) (symbols (quote left-top) (quote top-right))))]{
Returns \scheme|'left-top|
}
@defmethod*[#:mode override (((get-text) string))]{
Returns the same string as the super method, but with
newlines replaced by newline-semicolon-space.
}
@defmethod*[#:mode override (((get-menu) (is-a?/c popup-menu%)))]{
Returns a menu with a single item to change the box into
semicolon comments.
}
}
@(require framework/framework-docs)
@(def-fw-procs comment-box)

432
collects/scribblings/framework/framework-editor.scrbl Normal file
View File

@ -0,0 +1,432 @@
#lang scribble/doc
@(require scribble/manual)
@(require (for-label framework/framework))
@(require (for-label scheme/gui))
@title{Editor}
@definterface[editor:basic<%> (editor<%>)]{
Classes matching this interface support the basic
@scheme[editor<%>]
functionality required by the framework.
@defmethod*[(((has-focus?) boolean))]{
This function returns \rawscm{\#t} when the editor has the keyboard
focus. It is implemented using:
@method[editor<%> on-focus]
}
@defmethod*[(((local-edit-sequence?) boolean))]{
Indicates if this editor is in an edit sequence. Enclosing buffer's
edit-sequence status is not considered by this method.
See
@method[editor<%> begin-edit-sequence]
and
@method[editor<%> end-edit-sequence]
for more info about edit sequences.
}
@defmethod*[(((run-after-edit-sequence (thunk (-> void)) (tag (union symbol? |#f|) |#f|)) void))]{
This method is used to install callbacks that will be run after any
edit-sequence completes.
The procedure \var{thunk} will be called immediately if the edit is
not in an edit-sequence. If the edit is in an edit-sequence, it will
be called when the edit-sequence completes.
If \var{tag} is a symbol, the \var{thunk} is keyed on that symbol, and
only one thunk per symbol will be called after the
edit-sequence. Specifically, the last call to
@method[editor:basic<%> run-after-edit-sequence]'s argument will be called.
}
@defmethod*[(((get-top-level-window) (union |#f| (is-a?/c top-level-window<%>))))]{
Returns the
@scheme[top-level-window<%>]
currently associated with this buffer.
This does not work for embedded editors.
}
@defmethod*[(((save-file-out-of-date?) boolean))]{
Returns \rawscm{\#t} if the file on disk has been modified, by some other program.
}
@defmethod*[(((save-file/gui-error (filename (union path |#f|) |#f|) (format (union (quote guess) (quote standard) (quote text) (quote text-force-cr) same copy) (quote same)) (show-errors? boolean |#t|)) boolean))]{
This method is an alternative to
@method[editor<%> save-file]. Rather than showing errors via the original stdout, it
opens a dialog with an error message showing the error.
The result indicates if an error happened (the error has
already been shown to the user). It returns \rawscm{\#t} if
no error occurred and \rawscm{\#f} if an error occurred.
}
@defmethod*[(((load-file/gui-error (filename (union string |#f|) |#f|) (format (union (quote guess) (quote standard) (quote text) (quote text-force-cr) (quote same) (quote copy)) (quote guess)) (show-errors? boolean |#t|)) boolean))]{
This method is an alternative to
@method[editor<%> load-file]. Rather than showing errors via the original stdout, it
opens a dialog with an error message showing the error.
The result indicates if an error happened (the error has
already been shown to the user). It returns \rawscm{\#t} if
no error occurred and \rawscm{\#f} if an error occurred.
}
@defmethod*[(((on-close) void))]{
This method is called when an editor is closed. See also
@method[editor:basic<%> can-close?]
and
@method[editor:basic<%> close].
Does nothing.
}
@defmethod*[(((can-close?) boolean))]{
This method is called to query the editor if is okay to
close the editor. Although there is no visible effect
associated with closing an editor, there may be some cleanup
actions that need to be run when the user is finished with
the editor (asking if it should be saved, for example).
See also
@method[editor:basic<%> on-close]and
@method[editor:basic<%> close].
Returns \scheme|#t|.
}
@defmethod*[(((close) boolean))]{
This method is merely
\begin{schemedisplay}
(if (can-close?)
(begin (on-close) #t)
#f)
\end{schemedisplay}
It is intended as a shorthand, helper method for closing
an editor. See also
@method[editor:basic<%> can-close?]
and
@method[editor:basic<%> on-close].
}
@defmethod*[(((get-filename/untitled-name) string))]{
Returns the printed version of the filename for this
editor. If the editor doesn't yet have a filename, it
returns a symbolic name (something like "Untitled").
}
}
@defmixin[editor:basic-mixin (editor<%>) (editor:basic<%>)]{
This provides the basic editor services required by the rest of the
framework.
The result of this mixin uses the same initialization arguments as the
mixin's argument.
Each instance of a class created with this mixin contains a private
\iscmclass{keymap} that is chained to the global keymap via:
\rawscm{(send \var{keymap} chain-to-keymap (keymap:get-global) \#f)}.
This installs the global keymap \iscmprocedure{keymap:get-global} to
handle keyboard and mouse mappings not handled by \var{keymap}. The
global keymap is created when the framework is invoked.
@defmethod*[#:mode augment (((can-save-file? (filename string) (format symbol?)) boolean))]{
Checks to see if the file on the disk has been modified out
side of this editor, using
@method[editor:basic<%> save-file-out-of-date?].
If it has, this method prompts the user to be sure they want to save.
}
@defmethod*[#:mode augment (((after-save-file (success? boolean)) void))]{
If the current filename is not a temporary filename, this method calls
@scheme[handler:add-to-recent]with the current filename.
to add the new filename to the list of recently opened files.
Additionally, updates a private instance variable with the
modification time of the file, for using in implementing
@method[editor:basic<%> save-file-out-of-date?].
}
@defmethod*[#:mode augment (((after-load-file (success? boolean)) void))]{
Updates a private instance variable with the modification
time of the file, for using in implementing
@method[editor:basic<%> save-file-out-of-date?]
}
@defmethod*[#:mode override (((on-focus (on? boolean)) void))]{
Manages the state to implement
@method[editor:basic<%> has-focus?]
}
@defmethod*[#:mode augment (((on-edit-sequence) boolean))]{
Always returns \rawscm{\#t}. Updates a flag for
@method[editor:basic<%> local-edit-sequence?]
}
@defmethod*[#:mode augment (((after-edit-sequence) void))]{
Helps to implement
@method[editor:basic<%> run-after-edit-sequence].
}
@defmethod*[#:mode override (((on-new-box (type (union (quote pasteboard) (quote text)))) (instance editor-snip%)))]{
Creates instances of
@scheme[pasteboard:basic%]
or
@scheme[text:basic%]
instead of the built in
@scheme[pasteboard%]
and
@scheme[text%]
classes.
}
@defmethod*[#:mode override (((get-file (directory (or/c path-string? false/c))) string))]{
Uses
@scheme[finder:get-file]
to find a filename. Also, sets the parameter
@scheme[finder:dialog-parent-parameter]
to the result of
@method[editor:basic<%> get-top-level-window].
}
@defmethod*[#:mode override (((put-file (directory (or/c path? false/c)) (default-name (or/c path? false/c))) string))]{
Uses
@scheme[finder:put-file]
to find a filename. Also, sets the parameter
@scheme[finder:dialog-parent-parameter]
to the result of
@method[editor:basic<%> get-top-level-window].
}
}
@definterface[editor:standard-style-list<%> (editor<%>)]{
This interface is implemented by the results of
@scheme[editor:standard-style-list-mixin].
}
@defmixin[editor:standard-style-list-mixin (editor<%>) (editor:standard-style-list<%>)]{
The mixin adds code to the initialization
of the class that sets the editor's style
list (via
@method[editor<%> set-style-list])
to the result of
@scheme[editor:get-standard-style-list].
In addition, it calls
@method[editor<%> set-load-overwrites-styles]
with \scheme|#f|.
This ensures that saved files with different
settings for the style list do not clobber
the shared style list.
}
@definterface[editor:keymap<%> (editor:basic<%>)]{
Classes matching this interface add support for mixing in multiple
keymaps. They provides an extensible interface to chained keymaps,
through the
@method[editor:keymap<%> get-keymaps]
method.
This editor is initialized by calling
@scheme[add-editor-keymap-functions],
@scheme[add-text-keymap-functions], and
@scheme[add-pasteboard-keymap-functions].
@defmethod*[(((get-keymaps) (list-of (instance keymap%))))]{
The keymaps returned from this method are chained to this
\iscmintf{editor}'s keymap.
The result of this method should not change -- that is, it
should return the same list of keymaps each time it is
called.
Defaultly returns \rawscm{(list
@scheme[keymap:get-global])}
}
}
@defmixin[editor:keymap-mixin (editor:basic<%>) (editor:keymap<%>)]{
This provides a mixin that implements the
@scheme[editor:keymap<%>]
interface.
}
@definterface[editor:autowrap<%> (editor:basic<%>)]{
Classes implementing this interface keep the
@method[editor<%> auto-wrap]
state set based on the
\rawscm{'framework:auto-set-wrap?} preference
(see
\hyperref{the preferences section}{section~}{ for more info about preferences}{fw:preferences}).
They install a preferences callback with
@scheme[preferences:add-callback]
that sets the state when the preference changes and
initialize the value of
@method[editor<%> auto-wrap]
to the current value of \rawscm{'framework:auto-set-wrap?}
via
@scheme[preferences:get].
}
@defmixin[editor:autowrap-mixin (editor:basic<%>) (editor:autowrap<%>)]{
See
@scheme[editor:autowrap<%>]
}
@definterface[editor:file<%> (editor:keymap<%>)]{
Objects supporting this interface are expected to support files.
@defmethod*[(((get-can-close-parent) (union false (is-a/c? frame%) (is-a/c? dialog%))))]{
The result of this method is used as the parent for the
dialog that asks about closing.
Defaultly returns \scheme|#f|.
}
@defmethod*[(((update-frame-filename) void))]{
Attempts to find a frame that displays this editor. If it
does, it updates the frame's title based on a new filename
in the editor.
}
@defmethod*[(((allow-close-with-no-filename?) boolean))]{
This method indicates if closing the file when it hasn't
been saved is a reason to alert the user. See also
@method[editor:file-mixin can-close?].
Defaultly returns \scheme|#f|.
}
}
@defmixin[editor:file-mixin (editor:keymap<%>) (editor:file<%>)]{
This editor locks itself when the file that is opened is read-only in
the filesystem.
The class that this mixin produces uses the same initialization
arguments as it's input.
@defmethod*[#:mode override (((set-filename (name string) (temp? boolean |#f|)) void))]{
Updates the filename on each frame displaying this editor, for each
frame that matches
@scheme[frame:editor<%>].
}
@defmethod*[#:mode augment (((can-close?) boolean))]{
If the
@method[editor:file<%> allow-close-with-no-filename?]
method returns \scheme|#f|, this method checks to see if the file
has been saved at all yet. If not, it asks the user
about saving (and saves if they ask).
If the
@method[editor:file<%> allow-close-with-no-filename?]
method returns \scheme|#t|, this method does as before,
except only asks if the editor's
@method[editor<%> get-filename]method returns a path.
Also calls inner.
}
@defmethod*[#:mode override (((get-keymaps) (list-of (instance keymap%))))]{
This returns a list containing the super-class's keymaps, plus the
result of
@scheme[keymap:get-file]
}
}
@definterface[editor:backup-autosave<%> (editor:basic<%>)]{
Classes matching this interface support backup files and autosaving.
@defmethod*[(((backup?) boolean))]{
Indicates weather this
@scheme[editor<%>]
should be backed up.
Returns the value of the
@scheme[preferences:get]
applied to
\rawscm{'framework:backup-files?}.
\index{'framework:backup-files?}
}
@defmethod*[(((autosave?) boolean))]{
Indicates weather this
@scheme[editor<%>]
should be autosaved.
Returns \rawscm{\#t}.
}
@defmethod*[(((do-autosave) (union |#f| string)))]{
This method is called to perform the autosaving.
See also
@scheme[autosave:register]
When the file has been modified since it was last saved and autosaving
it turned on (via the
@method[editor:backup-autosave<%> autosave?]
method) an autosave file is created for this
@scheme[editor<%>].
Returns the filename where the autosave took place, or
\rawscm{\#f} if none did.
}
@defmethod*[(((remove-autosave) void))]{
This method removes the autosave file associated with this
@scheme[editor<%>].
}
}
@defmixin[editor:backup-autosave-mixin (editor:basic<%>) (editor:backup-autosave<%> autosave:autosavable<%>)]{
This mixin adds backup and autosave functionality to an editor.
During initialization, this object is registered
with
@scheme[autosave:register].
The result of this mixin uses the same initialization arguments as the
mixin's argument.
@defmethod*[#:mode augment (((on-save-file (filename path?) (format (one-of/c (quote guess) (quote standard) (quote text) (quote text-force-cr) (quote same) (quote copy)))) bool))]{
If a backup file has not been created this session for this file,
deletes any existing backup file and copies the old save file into the
backup file. For the backup file's name, see
@scheme[path-utils:generate-backup-name]
}
@defmethod*[#:mode augment (((on-close) void))]{
Deletes the autosave file and turns off autosaving.
}
@defmethod*[#:mode augment (((on-change) void))]{
Sets a flag indicating that this \iscmintf{editor} needs to be autosaved.
}
@defmethod*[#:mode override (((set-modified (modified? any/c)) void))]{
If the file is no longer modified, this method deletes the autosave
file. If it is, it updates a flag to indicate that the autosave file
is out of date.
}
}
@definterface[editor:info<%> (editor:basic<%>)]{
An
@scheme[editor<%>]
matching this interface provides information about its lock state to its
@scheme[top-level-window<%>].
}
@defmixin[editor:info-mixin (editor:basic<%>) (editor:info<%>)]{
This editor tells the frame when it is locked and unlocked.
See also
@scheme[frame:text-info<%>].
@defmethod*[#:mode override (((lock (lock? boolean)) void))]{
Uses
@method[editor:basic<%> run-after-edit-sequence]
to call
@method[frame:info<%> lock-status-changed].
}
}
@(require framework/framework-docs)
@(def-fw-procs editor)

8
collects/scribblings/framework/framework-exit.scrbl Normal file
View File

@ -0,0 +1,8 @@
#lang scribble/doc
@(require scribble/manual)
@(require (for-label framework/framework))
@(require (for-label scheme/gui))
@title{Exit}
@(require framework/framework-docs)
@(def-fw-procs exit)

8
collects/scribblings/framework/framework-finder.scrbl Normal file
View File

@ -0,0 +1,8 @@
#lang scribble/doc
@(require scribble/manual)
@(require (for-label framework/framework))
@(require (for-label scheme/gui))
@title{Finder}
@(require framework/framework-docs)
@(def-fw-procs finder)

2384
collects/scribblings/framework/framework-frame.scrbl Normal file
View File

File diff suppressed because it is too large Load Diff

124
collects/scribblings/framework/framework-group.scrbl Normal file
View File

@ -0,0 +1,124 @@
#lang scribble/doc
@(require scribble/manual)
@(require (for-label framework/framework))
@(require (for-label scheme/gui))
@title{Group}
@defclass[group:% object% ()]{
This class manages a group of frames matching the
@scheme[frame:basic<%>]
interface. There is one instance created by
the framework, returned by the function
@scheme[group:get-the-frame-group]
and every frame that was constructed with
@scheme[frame:basic-mixin]
adds itself to the result of
@scheme[group:get-the-frame-group].
@defmethod*[(((set-open-here-frame (frame (is-a?/c frame:editor%))) void))]{
Sets the frame to load new files into.
See also
@scheme[frame:open-here<%>].
}
@defmethod*[(((get-open-here-frame) (union |#f| (is-a?/c frame:editor<%>))))]{
Returns the currently saved frame
to load new files into.
}
@defmethod*[(((get-mdi-parent) (union |#f| (instance frame%))))]{
The result of this method must be used as the parent frame for each
frame in the group.
}
@defmethod*[(((get-frames) (list-of (instance frame:basic<%>))))]{
Returns the frames in the group.
}
@defmethod*[(((frame-label-changed (frame (is-a?/c frame:basic<%>))) void))]{
This method is called by frames constructed with
@scheme[frame:basic-mixin]
when their titles change.
Updates the windows menu of each frame in the group.
}
@defmethod*[(((frame-shown/hidden) void))]{
This method is called by instances of
@scheme[frame:basic%]
to notify the frame group that
a frame's visibility is changed.
Updates the Windows menus of all of the frames in the frame group.
}
@defmethod*[(((for-each-frame (f ((instance frame:basic<%>) -> void))) void))]{
This method applies a function to each frame in the group. It also
remembers the function and applies it to any new frames that are added
to the group when they are added.
See also
@method[group:% get-frames].
Applies \var{f} to each frame in the group
}
@defmethod*[(((get-active-frame) (is-a?/c frame:basic<%>)))]{
Returns the frame with the keyboard focus or the first frame in the
group.
}
@defmethod*[(((set-active-frame (frame (is-a?/c frame:basic<%>))) void))]{
Sets the active frame in the group.
This method is called by
@method[frame:register-group-mixin on-focus].
}
@defmethod*[(((insert-frame (frame (is-a?/c frame:basic<%>))) void))]{
Inserts a frame into the group.
}
@defmethod*[(((remove-frame (frame (is-a?/c frame:basic<%>))) void))]{
Removes a frame from the group.
}
@defmethod*[(((clear) boolean))]{
This removes all of the frames in the group. It does not close the frames. See also
@method[group:% on-close-all]and
@method[group:% can-close-all?].
}
@defmethod*[(((on-close-all) void))]{
Call this method to close all of the frames in the group.
The function
@method[group:% can-close-all?]
must have been called just before this function and it must have returned
\rawscm{\#t}.
Calls the
@method[top-level-window<%> on-close]
method and the
@method[top-level-window<%> show]
method (with \rawscm{\#f} as argument)
on each frame in the group.
}
@defmethod*[(((can-close-all?) void))]{
Call this method to make sure that closing all of the frames in the frame groups is
permitted by the user. The function
@method[group:% on-close-all]
is expected to be called just after this method is called.
Calls the
@method[top-level-window<%> can-close?]
method of each frame in the group.
}
@defmethod*[(((locate-file) (union |#f| (is-a?/c frame:basic<%>))))]{
Returns the frame that is editing or viewing a particular file.
}
}
@(require framework/framework-docs)
@(def-fw-procs group)

8
collects/scribblings/framework/framework-handler.scrbl Normal file
View File

@ -0,0 +1,8 @@
#lang scribble/doc
@(require scribble/manual)
@(require (for-label framework/framework))
@(require (for-label scheme/gui))
@title{Handler}
@(require framework/framework-docs)
@(def-fw-procs handler)

8
collects/scribblings/framework/framework-icon.scrbl Normal file
View File

@ -0,0 +1,8 @@
#lang scribble/doc
@(require scribble/manual)
@(require (for-label framework/framework))
@(require (for-label scheme/gui))
@title{Icon}
@(require framework/framework-docs)
@(def-fw-procs icon)

45
collects/scribblings/framework/framework-keymap.scrbl Normal file
View File

@ -0,0 +1,45 @@
#lang scribble/doc
@(require scribble/manual)
@(require (for-label framework/framework))
@(require (for-label scheme/gui))
@title{Keymap}
@definterface[keymap:aug-keymap<%> (keymap%)]{
This keymap overrides some of the built in \iscmclass{keymap} methods
to be able to extract the keybindings from the keymap.
@defmethod*[(((get-chained-keymaps) (listof (instance keymap%))))]{
Returns the list of keymaps that are chained to this one.
}
@defmethod*[(((get-map-function-table) hash-table))]{
Returns a hash-table that maps symbols naming key sequences to the
names of the keymap functions the are bound to.
}
@defmethod*[(((get-map-function-table/ht (ht hash-table)) hash-table))]{
This is a helper function for
@method[keymap:aug-keymap<%> get-map-function-table]
that returns the same result, except it accepts a hash-table that
it inserts the bindings into. It does not replace any bindings already in
\var{ht}.
}
}
@defmixin[keymap:aug-keymap-mixin (keymap%) (keymap:aug-keymap<%>)]{
@defmethod*[#:mode override (((chain-to-keymap (next (instance keymap%)) (prefix? boolean)) void))]{
Keeps a list of the keymaps chained to this one.
}
@defmethod*[#:mode override (((remove-chained-keymap (keymap (is-a?/c keymap))) void))]{
Keeps the list of the keymaps chained to this one up to date.
}
@defmethod*[#:mode override (((map-function (key-name string) (function-name string)) void))]{
Keeps a separate record of the key names and functions that they are
bound to in this keymap.
}
}
@defclass[keymap:aug-keymap% (keymap:aug-keymap-mixin keymap%) ()]{}
@(require framework/framework-docs)
@(def-fw-procs keymap)

8
collects/scribblings/framework/framework-main.scrbl Normal file
View File

@ -0,0 +1,8 @@
#lang scribble/doc
@(require scribble/manual)
@(require (for-label framework/framework))
@(require (for-label scheme/gui))
@title{Main}
@(require framework/framework-docs)
@(def-fw-procs main)

48
collects/scribblings/framework/framework-menu.scrbl Normal file
View File

@ -0,0 +1,48 @@
#lang scribble/doc
@(require scribble/manual)
@(require (for-label framework/framework))
@(require (for-label scheme/gui))
@title{Menu}
@definterface[menu:can-restore<%> (selectable-menu-item<%>)]{
Classes created with this mixin remember their keybindings so the
keybindings can be removed and then restored.
@defmethod*[(((restore-keybinding) void))]{
Sets the keyboard shortcut to the setting it had when the class was
created.
}
}
@defmixin[menu:can-restore-mixin (selectable-menu-item<%>) (menu:can-restore<%>)]{
}
@definterface[menu:can-restore-underscore<%> (labelled-menu-item<%>)]{
These menus can save and restore the underscores (indicated
via the \& characters in the original labels) in their
labels.
If the preference \scm{'framework:menu-bindings}
is \scm{\#f}, calls
@method[menu:can-restore-underscore<%> erase-underscores]
during initialization.
@defmethod*[(((erase-underscores) void))]{
Erases the underscores in the label of this menu, but
remembers them so they can be restores with
@method[menu:can-restore-underscore<%> restore-underscores].
}
@defmethod*[(((restore-underscores) void))]{
Restores underscores in the menu's label to their original
state.
}
}
@defmixin[menu:can-restore-underscore-mixin (labelled-menu-item<%>) (menu:can-restore-underscore<%>)]{
}
@defclass[menu:can-restore-menu-item% (menu:can-restore-mixin menu-item%) ()]{}
@defclass[menu:can-restore-checkable-menu-item% (menu:can-restore-mixin checkable-menu-item%) ()]{}
@defclass[menu:can-restore-underscore-menu% (menu:can-restore-underscore-mixin menu%) ()]{}
@(require framework/framework-docs)
@(def-fw-procs menu)

8
collects/scribblings/framework/framework-mode.scrbl Normal file
View File

@ -0,0 +1,8 @@
#lang scribble/doc
@(require scribble/manual)
@(require (for-label framework/framework))
@(require (for-label scheme/gui))
@title{Mode}
@(require framework/framework-docs)
@(def-fw-procs mode)

15
collects/scribblings/framework/framework-number-snip.scrbl Normal file
View File

@ -0,0 +1,15 @@
#lang scribble/doc
@(require scribble/manual)
@(require (for-label framework/framework))
@(require (for-label scheme/gui))
@title{Number Snip}
@defclass[number-snip:snip-class% snip-class% ()]{
@defmethod*[#:mode override (((read (f stream-in)) snip))]{
Constructs a number snip from its input.
}
}
@(require framework/framework-docs)
@(def-fw-procs number-snip)

171
collects/scribblings/framework/framework-panel.scrbl Normal file
View File

@ -0,0 +1,171 @@
#lang scribble/doc
@(require scribble/manual)
@(require (for-label framework/framework))
@(require (for-label scheme/gui))
@title{Panel}
@definterface[panel:single<%> (area-container<%>)]{
See
@scheme[panel:single-mixin%].
@defmethod*[(((active-child (child (is-a?/c area<%>))) void) ((active-child) (is-a?/c area<%>)))]{
Sets the active child to be \var{child}
Returns the current active child.
}
}
@defmixin[panel:single-mixin (area-container<%>) (panel:single<%>)]{
This mixin adds single panel functionality to an implementation of the
\iscmintf{area-container} interface.
Single panels place all of the children in the center of the panel,
and allow make one child to be visible at a time. The
@method[panel:single<%> active-child]
method controls which panel is currently active.
The
@method[window<%> show]
method is used to hide and show the children of a single panel.
@defmethod*[#:mode override (((after-new-child (child subarea<%>)) void))]{
Hides this child by calling \scmline{(send child show \#f)}, unless
this is the first child in which case it does nothing.
}
@defmethod*[#:mode override (((container-size) (values exact-integer exact-integer)))]{
Returns the maximum width of all the children and the maximum height
of all of the children.
}
@defmethod*[#:mode override (((place-children) (listof (list exact-integer exact-integer exact-integer exact-integer))))]{
Returns the positions for single panels and panes.
}
}
@definterface[panel:single-window<%> (panel:single<%> window<%>)]{
}
@defmixin[panel:single-window-mixin (panel:single<%> window<%>) (panel:single-window<%>)]{
@defmethod*[#:mode override (((container-size (info (list-of (list exact-integer exact-integer boolean boolean)))) (values exact-integer exact-integer)))]{
Factors the border width into the size calculation.
}
}
@defclass[panel:single% (panel:single-window-mixin (panel:single-mixin panel%)) ()]{}
@defclass[panel:single-pane% (panel:single-mixin pane%) ()]{}
@definterface[panel:dragable<%> (window<%> area-container<%>)]{
Classes matching this interface implement a panel where the
user can adjust the percentage of the space that each takes
up. The user adjusts the size by clicking and dragging the
empty space between the children.
@defmethod*[(((after-percentage-change) void))]{
This method is called when the user changes the percentage
by dragging the bar between the children, or when a new
child is added to the frame, but not when
@method[panel:dragable<%> set-percentages]
is called.
Use
@method[panel:dragable<%> get-percentages]
to find the current percentages.
}
@defmethod*[(((set-percentages (new-percentages (listof number))) void))]{
Call this method to set the percentages that each window
takes up of the panel.
The argument, \var{new-percentages} must be a list of
numbers that sums to 1. It's length must be equal to the
number of children of the panel (see
@method[area-container<%> get-children]) and each percentage must correspond to a number of pixels
that is equal to or larger than the
minimum with of the child, as reported by
@method[area<%> min-width].
}
@defmethod*[(((get-percentages) (listof numbers)))]{
Return the current percentages of the children.
}
@defmethod*[(((get-vertical?) boolean))]{
This method controls the behavior of the other overridden
methods in mixins that implement this interface.
If it returns \scheme|#t|, the panel will be vertically
aligned and if it returns \scheme|#f|, they will be
horizontally aligned.
}
}
@definterface[panel:vertical-dragable<%> (panel:dragable<%>)]{
A panel that implements
@scheme[panel:vertical-dragable<%>]. It aligns its children vertically.
}
@definterface[panel:horizontal-dragable<%> (panel:dragable<%>)]{
A panel that implements
@scheme[panel:horizontal-dragable<%>]. It aligns its children horizontally.
}
@defmixin[panel:dragable-mixin (window<%> area-container<%>) (panel:dragable<%>)]{
This mixin adds the
@scheme[panel:dragable<%>]
functionality to a
@scheme[panel%].
It is not useful unless the
@method[panel:dragable<%> get-vertical?]
method is overridden.
@defmethod*[#:mode override (((after-new-child (child (instance-of (is-a?/c area<%>)))) void))]{
Updates the number of percentages to make sure that it
matches the number of children and calls
@method[panel:dragable<%> after-percentage-change].
}
@defmethod*[#:mode override (((on-subwindow-event (receiver (instanceof window<%>)) (event (instanceof mouse-event%))) boolean))]{
When the cursor is dragging the middle bar around, this
method handles the resizing of the two panes.
}
@defmethod*[#:mode override (((place-children (info (list-of (list exact-int exact-int))) (w exact-int) (h exact-int)) (list-of (list exact-int exact-int exact-int exact-int))))]{
Places the children vertically in the panel, based on the percentages
returned from
@method[panel:dragable<%> get-percentages]. Also leaves a little gap between each pair of children.
}
@defmethod*[#:mode override (((container-size (info list)) two))]{
Computes the minimum size the panel would have to be in
order to have the current percentages (see
@method[panel:dragable<%> get-percentages]).
}
}
@defmixin[panel:vertical-dragable-mixin (panel:dragable<%>) (panel:vertical-dragable<%>)]{
This mixin merely overrides the
@method[panel:dragable<%> get-vertical?]
method of the
@scheme[panel:dragable-mixin]
to return \scheme|#t|.
@defmethod*[#:mode override (((get-vertical?) boolean))]{
Returns \scheme|#t|.
}
}
@defmixin[panel:horizontal-dragable-mixin (panel:dragable<%>) (panel:vertical-dragable<%>)]{
This mixin merely overrides the
@method[panel:dragable<%> get-vertical?]
method of the
@scheme[panel:dragable-mixin]
to return \scheme|#f|.
@defmethod*[#:mode override (((get-vertical?) boolean))]{
Returns \scheme|#f|.
}
}
@defclass[panel:vertical-dragable% (panel:vertical-dragable-mixin (panel:dragable-mixin vertical-panel%)) ()]{}
@defclass[panel:horizontal-dragable% (panel:horizontal-dragable-mixin (panel:dragable-mixin horizontal-panel%)) ()]{}
@(require framework/framework-docs)
@(def-fw-procs panel)

14
collects/scribblings/framework/framework-pasteboard.scrbl Normal file
View File

@ -0,0 +1,14 @@
#lang scribble/doc
@(require scribble/manual)
@(require (for-label framework/framework))
@(require (for-label scheme/gui))
@title{Pasteboard}
@defclass[pasteboard:basic% (editor:basic-mixin pasteboard%) ()]{}
@defclass[pasteboard:standard-style-list% (editor:standard-style-list-mixin pasteboard:basic%) ()]{}
@defclass[pasteboard:keymap% (editor:keymap-mixin pasteboard:standard-style-list%) ()]{}
@defclass[pasteboard:file% (editor:file-mixin pasteboard:keymap%) ()]{}
@defclass[pasteboard:backup-autosave% (editor:backup-autosave-mixin pasteboard:file%) ()]{}
@defclass[pasteboard:info% (editor:info-mixin pasteboard:backup-autosave%) ()]{}
@(require framework/framework-docs)
@(def-fw-procs pasteboard)

8
collects/scribblings/framework/framework-path-utils.scrbl Normal file
View File

@ -0,0 +1,8 @@
#lang scribble/doc
@(require scribble/manual)
@(require (for-label framework/framework))
@(require (for-label scheme/gui))
@title{Path Utils}
@(require framework/framework-docs)
@(def-fw-procs path-utils)

8
collects/scribblings/framework/framework-preferences.scrbl Normal file
View File

@ -0,0 +1,8 @@
#lang scribble/doc
@(require scribble/manual)
@(require (for-label framework/framework))
@(require (for-label scheme/gui))
@title{Preferences}
@(require framework/framework-docs)
@(def-fw-procs preferences)

273
collects/scribblings/framework/framework-scheme.scrbl Normal file
View File

@ -0,0 +1,273 @@
#lang scribble/doc
@(require scribble/manual)
@(require (for-label framework/framework))
@(require (for-label scheme/gui))
@title{Scheme}
@definterface[scheme:sexp-snip<%> ()]{
@defmethod*[(((get-saved-snips) (listof snip%)))]{
This returns the list of snips hidden by the sexp snip.
}
}
@defclass[scheme:sexp-snip% snip% (scheme:sexp-snip<%> readable-snip<%>)]{
@defmethod*[#:mode override (((get-text (offset number) (num number) (flattened? boolean |#f|)) string))]{
Returns the concatenation of the text for all of the hidden
snips.
}
@defmethod*[#:mode override (((copy) (is-a?/c scheme:sexp-snip%)))]{
Returns a copy of this snip that includes the hidden snips.
}
@defmethod*[#:mode override (((write (stream-out editor-stream-out%)) void))]{
Saves the embedded snips
}
@defmethod*[#:mode override (((draw (dc dc<%>) (x real) (y real) (left real) (top real) (right real) (bottom real) (dx real) (dy real) (draw-caret symbol?)) void))]{
Draws brackets with a centered ellipses between them.
}
@defmethod*[#:mode override (((get-extent (dc (is-a?/c dc<%>)) (x real) (y real) (w boxed |#f|) (h boxed |#f|) (descent boxed |#f|) (space boxed |#f|) (lspace boxed |#f|) (rspace boxed |#f|)) void))]{
Returns a size corresponding to what this snip draws.
}
}
@definterface[scheme:text<%> (text:basic<%> mode:host-text<%> color:text<%>)]{
Texts matching this interface support Scheme mode operations.
@defmethod*[(((get-limit (start exact-integer)) int))]{
Returns a limit for backward-matching parenthesis starting at position
\var{start}.
}
@defmethod*[(((balance-parens (key-event (instance key-event%))) void))]{
This function is called when the user types a close parenthesis in the
@scheme[text%]. If the close parenthesis that the user inserted does not match the
corresponding open parenthesis and the \rawscm{'framework:fixup-parens} preference is
\rawscm{\#t} (see
@scheme[preferences:get]) the correct closing parenthesis is inserted.
If the \rawscm{'framework:paren-match} preference is
\rawscm{\#t} (see
@scheme[preferences:get]) the matching open parenthesis is flashed.
}
@defmethod*[(((tabify-on-return?) boolean))]{
The result of this method is used to determine if the return key
automatically tabs over to the correct position.
Override it to change it's behavior.
}
@defmethod*[(((tabify (start-pos exact-integer (send this iscmclassmethod (text) (get-start-position)))) void))]{
Tabs the line containing by \var{start-pos}
}
@defmethod*[(((tabify-selection (start exact-integer) (end exact-integer)) void))]{
Sets the tabbing for the lines containing positions \var{start}
through \var{end}.
}
@defmethod*[(((tabify-all) void))]{
Tabs all lines.
}
@defmethod*[(((insert-return) void))]{
Inserts a newline into the buffer. If
@method[scheme:text<%> tabify-on-return?]
returns \rawscm{\#t}, this will tabify the new line.
}
@defmethod*[(((box-comment-out-selection (start-pos (union (quote start) exact-integer) rawscm) (end-pos (union (quote end) exact-integer) rawscm)) void))]{
This method comments out a selection in the text by putting it into a comment box.
Removes the region from \var{start-pos} to \var{end-pos}
from the editor and inserts a comment box with that region
of text inserted into the box.
If \var{start-pos} is \rawscm{'start}, the starting point of
the selection is used. If \var{end-pos} is \rawscm{'end},
the ending point of the selection is used.
}
@defmethod*[(((comment-out-selection (start exact-integer) (end exact-integer)) void))]{
Comments the lines containing positions \var{start} through \var{end}
by inserting a semi-colon at the front of each line.
}
@defmethod*[(((uncomment-selection (start int) (end int)) void))]{
Uncomments the lines containing positions \var{start} through \var{end}.
}
@defmethod*[(((get-forward-sexp (start exact-integer)) (union |#f| exact-integer)))]{
Returns the position of the end of next S-expression after position
\var{start}, or \rawscm{\#f} if there is no appropriate answer.
}
@defmethod*[(((remove-sexp (start exact-integer)) void))]{
Forward-deletes the S-expression starting after the position \var{start}.
}
@defmethod*[(((forward-sexp (start |#t|)) exact-integer))]{
Moves forward over the S-expression starting at position \var{start}.
}
@defmethod*[(((flash-forward-sexp (start-pos exact-integer)) void))]{
Flashes the parenthesis that closes the sexpression at
\var{start-pos}.
}
@defmethod*[(((get-backward-sexp (start exact-integer)) (union exact-integer |#f|)))]{
Returns the position of the start of the S-expression before or
containing \var{start}, or \rawscm{\#f} if there is no appropriate
answer.
}
@defmethod*[(((flash-backward-sexp (start-pos exact-integer)) void))]{
Flashes the parenthesis that opens the sexpression at
\var{start-pos}.
}
@defmethod*[(((backward-sexp (start-pos exact-integer)) void))]{
Move the caret backwards one sexpression
Moves the caret to the beginning of the sexpression that ends at
\var{start-pos}.
}
@defmethod*[(((find-up-sexp (start-pos exact-integer)) (union |#f| exact-integer)))]{
Returns the position of the beginning of the next sexpression outside
the sexpression that contains \var{start-pos}. If there is no such
sexpression, it returns \rawscm{\#f}.
}
@defmethod*[(((up-sexp (start exact-integer)) void))]{
Moves backward out of the S-expression containing the position \var{start}.
}
@defmethod*[(((find-down-sexp (start-pos exact-integer)) (union |#f| exact-integer)))]{
Returns the position of the beginning of the next sexpression inside
the sexpression that contains \var{start-pos}. If there is no such
sexpression, it returns \rawscm{\#f}.
}
@defmethod*[(((down-sexp (start exact-integer)) void))]{
Moves forward into the next S-expression after the position \var{start}.
}
@defmethod*[(((remove-parens-forward (start exact-integer)) void))]{
Removes the parentheses from the S-expression starting after the
position \var{start}.
}
@defmethod*[(((select-forward-sexp (start exact-integer)) |#t|))]{
Selects the next S-expression, starting at position \var{start}.
}
@defmethod*[(((select-backward-sexp (start exact-integer)) |#t|))]{
Selects the previous S-expression, starting at position \var{start}.
}
@defmethod*[(((select-up-sexp (start exact-integer)) |#t|))]{
Selects the region to the enclosing S-expression, starting at position \var{start}.
}
@defmethod*[(((select-down-sexp (start exact-integer)) |#t|))]{
Selects the region to the next contained S-expression, starting at position \var{start}.
}
@defmethod*[(((transpose-sexp (start exact-integer)) void))]{
Swaps the S-expression beginning before the position \var{start} with
the next S-expression following \var{start}.
}
@defmethod*[(((mark-matching-parenthesis (pos exact-positive-integer)) void))]{
If the paren after \var{pos} is matched, this method
highlights it and it's matching counterpart in dark green.
}
@defmethod*[(((get-tab-size) exact-integer))]{
This method returns the current size of the tabs for scheme mode.
See also
@method[scheme:text<%> set-tab-size].
}
@defmethod*[(((set-tab-size (new-size exact-integer)) void))]{
This method sets the tab size for this
text.
}
@defmethod*[(((introduce-let-ans) void))]{
Adds a let around the current s-expression and a printf into the body
of the let.
}
@defmethod*[(((move-sexp-out) void))]{
Replaces the sexpression surrounding the insertion point with the
sexpression following the insertion point.
}
}
@defmixin[scheme:text-mixin (text:basic<%> mode:host-text<%> color:text<%> text:autocomplete<%>) (scheme:text<%>)]{
This mixin adds functionality for editing Scheme files.
The result of this mixin uses the same initialization arguments as the
mixin's argument.
@defmethod*[#:mode override (((get-word-at (pos positive-exact-integer)) string))]{
Returns the word just before \var{pos}, which is then used
as the prefix for auto-completion.
}
}
@definterface[scheme:text-mode<%> ()]{
The result of
@scheme[scheme:text-mode-mixin]
implements this interface.
}
@defmixin[scheme:text-mode-mixin (color:text-mode<%> mode:surrogate-text<%>) (scheme:text-mode<%>)]{
This mixin adds Scheme mode functionality
to the mode that it is mixed into. The resulting
mode assumes that it is only set to an editor
that is the result of
@scheme[scheme:text-mixin].
@defmethod*[#:mode override (((on-disable-surrogate) void))]{
Removes the scheme keymap (see also
@scheme[scheme:get-keymap]) and disables any parenthesis
highlighting in the host editor.
}
@defmethod*[#:mode override (((on-enable-surrogate) void))]{
Adds the scheme keymap (see also
@scheme[scheme:get-keymap]) and enables a parenthesis
highlighting in the host editor.
}
}
@defmixin[scheme:set-mode-mixin (scheme:text<%> mode:host-text<%>) ()]{
This mixin creates a new instance of
@scheme[scheme:text-mode%]
and installs it, by calling its own
@method[mode:host-text<%> set-surrogate]
method with the object.
}
@defclass[scheme:text% (scheme:set-mode-mixin (scheme:text-mixin (text:autocomplete-mixin (mode:host-text-mixin color:text%)))) ()]{}
@defclass[scheme:text-mode% (scheme:text-mode-mixin color:text-mode%) ()]{}
@(require framework/framework-docs)
@(def-fw-procs scheme)

950
collects/scribblings/framework/framework-text.scrbl Normal file
View File

@ -0,0 +1,950 @@
#lang scribble/doc
@(require scribble/manual)
@(require (for-label framework/framework))
@(require (for-label scheme/gui))
@title{Text}
@definterface[text:basic<%> (editor:basic<%> text%)]{
Classes matching this interface are expected to implement the basic
functionality needed by the framework.
@defmethod*[(((highlight-range (start exact-integer) (end exact-integer) (color (instance color%)) (bitmap (union |#f| (instance bitmap%)) |#f|) (caret-space boolean |#f|) (priority (union (quote high) (quote low)) (quote low))) (-> void)))]{
This function highlights a region of text in the buffer.
The range between \var{start} and \var{end} will be highlighted with the
color in color, and \var{bitmap} will be painted over the range of text in
black and white. If \var{bitmap} is \rawscm{\#f}, the range will be inverted,
using the platform specific xor. This method is not recommended, because the
selection is also displayed using xor.
If \var{caret-space?} is not \rawscm{\#f}, the left edge of the range
will be one pixel short, to leave space for the caret. The caret does
not interfere with the right hand side of the range. Note that under X
windows the caret is drawn with XOR, which means almost anything can
happen. So if the caret is in the middle of the range it may be hard
to see, or if it is on the left of the range and \var{caret-space?} is
\rawscm{\#f} it may also be hard to see.
The \var{priority} argument indicates the relative priority for
drawing overlapping regions. If two regions overlap and have different
priorities, the region with \rawscm{'high} priority will be drawn second
and only it will be visible in the overlapping region.
This method returns a thunk, which, when invoked, will turn off
the highlighting from this range.
See also
@method[text:basic<%> unhighlight-range].
}
@defmethod*[(((unhighlight-range (start exact-integer) (end exact-integer) (color (instance color%)) (bitmap (union |#f| (instance bitmap%)) |#f|) (caret-space boolean |#f|)) void))]{
This method removes the highlight from a region of text in
the buffer.
The region must match up to a region specified
from an earlier call to
@method[text:basic<%> highlight-range].
}
@defmethod*[(((get-highlighted-ranges) (listof range)))]{
Returns a list of (opaque) values representing the active
ranges in the editor.
}
@defmethod*[(((get-styles-fixed) boolean))]{
If the result of this function is \rawscm{\#t}, the styles in this
@scheme[text:basic<%>]
will be fixed. This means
that any text inserted to this editor
has its style set to this editor's
@scheme[style-list%]'s \rawscm{"Standard"} style.
See also
@method[text:basic<%> set-styles-fixed].
}
@defmethod*[(((get-fixed-style) (is-a?/c style<%>)))]{
Returns the style used by
@method[text:basic<%> set-styles-fixed]when setting the styles.
}
@defmethod*[(((set-styles-fixed (fixed? boolean)) void))]{
Sets the styles fixed parameter of this
@scheme[text%]. See also
@method[text:basic<%> get-styles-fixed]
and
@method[text:basic<%> get-fixed-style].
}
@defmethod*[(((move/copy-to-edit (dest-text (instance text%)) (start exact-integer) (end exact-integer) (dest-pos exact-integer)) void))]{
This moves or copies text and snips to another edit.
Moves or copies from the edit starting at \var{start} and ending at
\var{end}. It puts the copied text and snips in \var{dest-text}
starting at location \var{dest-pos}.
If a snip refused to be moved, it will be copied, otherwise it will be
moved. A snip may refuse to be moved by returning \rawscm{\#f} from
@method[snip% release-from-owner].
}
@defmethod*[(((initial-autowrap-bitmap) (union |#f| (instance bitmap%))))]{
The result of this method is used as the initial autowrap
bitmap. Override this method to change the initial
@scheme[bitmap%]. See also
@method[text% set-autowrap-bitmap]
Defaultly returns the result of
@scheme[icon:get-autowrap-bitmap]
}
@defmethod*[(((get-port-name) symbol?))]{
The result of this method is a symbol that identifies this
editor and that is used as the port-name of a port that is
read from this editor if this editor is used in DrScheme.
See also
@method[text:basic<%> port-name-matches?].
}
@defmethod*[(((port-name-matches? (id (or/c path? symbol?))) boolean))]{
Indicates if \var{id} matches the port name of this file. If
the file is saved, the port name matches when the save file
is the path as \var{id}. If the file has not been saved, the
port name matches if the symbol is the same as the result of
@method[text:basic<%> port-name-matches].
}
}
@defmixin[text:basic-mixin (editor:basic<%> text%) (text:basic<%>)]{
This mixin implements the basic functionality needed for
@scheme[text%]
objects in the framework.
The class that this mixin produces uses the same initialization
arguments as it's input.
@defmethod*[#:mode override (((on-paint (before? any/c) (dc (is-a?/c dc<%>)) (left real?) (top real?) (right real?) (bottom real?) (dx real?) (dy real?) (draw-caret (one-of/c (quote no-caret) (quote show-inactive-caret) (quote show-caret)))) void))]{
Draws the rectangles installed by
@method[text:basic<%> highlight-range].
}
@defmethod*[#:mode augment (((on-insert (start exact-int) (end exact-int)) void))]{
See
@method[text:basic<%> set-styles-fixed].
}
@defmethod*[#:mode augment (((after-insert (start nonnegative-exact-integer?) (len nonnegative-exact-integer?)) void))]{
See
@method[text:basic<%> set-styles-fixed].
}
@defmethod*[#:mode override (((put-file (directory path) (default-name path)) void))]{
Like
@method[editor<%> put-file]
but uses
@scheme[finder:put-file]
instead of \scheme|put-file|.
}
}
@definterface[text:foreground-color<%> (text:basic<%> editor:standard-style-list<%>)]{
}
@defmixin[text:foreground-color-mixin (text:basic<%> editor:standard-style-list<%>) (text:foreground-color<%>)]{
This mixin changes the default text style to have
the foreground color controlled by
@scheme[editor:set-default-font-color].
@defmethod*[#:mode override (((default-style-name) string))]{
Returns the result of
@scheme[editor:get-default-color-style-name].
}
@defmethod*[#:mode override (((get-fixed-style) (is-a?/c style<%>)))]{
Returns the style named by
@scheme[editor:get-default-color-style-name].
}
}
@definterface[text:hide-caret/selection<%> (text:basic<%>)]{
This class hides the caret, except when the selection is active.
Instances of this class are useful for editors that used for
displaying purposes, but still allow users to copy their text.
}
@defmixin[text:hide-caret/selection-mixin (text:basic<%>) (text:hide-caret/selection<%>)]{
@defmethod*[#:mode augment (((after-set-position) void))]{
Calls
@method[text% hide-caret]
to hide the caret when there is only a caret and no selection.
}
}
@definterface[text:nbsp->space<%> (text%)]{
Classes that implement this interface silently change
non-breaking spaces, ie the character \scheme|(integer->char
160)|, to regular spaces when inserted into the editor.
}
@defmixin[text:nbsp->space-mixin (text%) (text:nbsp->space<%>)]{
@defmethod*[#:mode augment (((on-insert (start exact-int) (end exact-int)) void))]{
Starts an edit-sequence by calling
@method[editor<%> begin-edit-sequence].
}
@defmethod*[#:mode augment (((after-insert (start nonnegative-exact-integer?) (len nonnegative-exact-integer?)) void))]{
Replaces all non-breaking space characters
\begin{schemedisplay}
(integer->char 160)
\end{schemedisplay}
by \scheme|#\space| characters.
Ends the edit sequence (by calling
@method[editor<%> end-edit-sequence]) started in
@method[text:nbsp->space-mixin on-insert].
}
}
@definterface[text:searching<%> (editor:keymap<%> text:basic<%>)]{
Any object matching this interface can be searched.
}
@defmixin[text:searching-mixin (editor:keymap<%> text:basic<%>) (text:searching<%>)]{
This
@scheme[text%]
can be searched.
The result of this mixin uses the same initialization arguments as the
mixin's argument.
@defmethod*[#:mode override (((get-keymaps) (list-of (instance keymap%))))]{
This returns a list containing the super-class's keymaps, plus the
result of
@scheme[keymap:get-search]
}
}
@definterface[text:return<%> (text%)]{
Objects supporting this interface were created by
@scheme[text:return-mixin].
}
@defmixin[text:return-mixin (text%) (text:return<%>)]{
Use this buffer to perform some special action when return is typed.
@defconstructor[((return (-> boolean)))]{
}
@defmethod*[#:mode override (((on-local-char (event (is-a?/c key-event%))) void))]{
If \var{key} is either return or newline, only invoke the \var{return}
thunk (initialization argument) and do nothing else.
}
}
@definterface[text:wide-snip<%> (text:basic<%>)]{
@defmethod*[(((add-wide-snip (snip (instance snip%))) void))]{
Registers a snip in this editor to be resized when its viewing area
changes. Ensures the snip is as wide as the viewing area.
This method should only be called by
@method[canvas:wide-snip<%> add-tall-snip].
}
@defmethod*[(((add-tall-snip (snip (is-a?/c snip%))) void))]{
Registers a snip in this editor. It is resized when the
viewing area of the editor changes.
This method should only be called by
@method[canvas:wide-snip<%> add-tall-snip].
}
}
@defmixin[text:wide-snip-mixin (text:basic<%>) (text:wide-snip<%>)]{
}
@definterface[text:delegate<%> (text:basic<%>)]{
Implementations of this interface copy all of the
changes to this editor to the result of
@method[text:delegate<%> get-delegate]
except instead of regular string and tab snips,
instead instances of
@scheme[text:1-pixel-string-snip%]
and
@scheme[text:1-pixel-tab-snip%]
are created.
The contents of the two
editor are kept in sync, as modifications
to this object happen.
@defmethod*[(((get-delegate) (union |#f| (instanceof text%))))]{
The result of this method is the \iscmclass{text} object
that the contents of this editor are being delegated to, or
\rawscm{\#f}, if there is none.
}
@defmethod*[(((set-delegate (delegate (union |#f| (instanceof text%)))) void))]{
This method sets the current delegate.
When it is set, all of the snips are copied from this object
to \var{delegate}. Additionally, if this object implements
@scheme[scheme:text<%>]
the tab settings of \var{delegate} are updated to match this
objects.
}
}
@defclass[text:1-pixel-string-snip% string-snip% ()]{
This class re-uses the implementation of
@scheme[string-snip%]
to implement a string snip that just draws
a single pixel for each character in the string.
See also
@scheme[text:1-pixel-tab-snip%]
for a similar extension to the
@scheme[tab-snip%]class.
This snip is used in conjunction with the
@scheme[frame:delegate<%>]
and
@scheme[text:delegate<%>]
interfaces.
@defmethod*[#:mode override (((split (position exact) (first (box (instanceof snip%))) (second (box (instanceof snip%)))) void))]{
Fills the boxes with instance of
@scheme[text:1-pixel-string-snip%]s.
}
@defmethod*[#:mode override (((copy) (instanceof snip%)))]{
Creates and returns an instance of
@scheme[text:1-pixel-string-snip%].
}
@defmethod*[#:mode override (((get-extent (dc (instanceof dc<%>)) (x real) (y real) (w (box (union non-negative-real-number |#f|)) |#f|) (h (box (union non-negative-real-number |#f|)) |#f|) (descent (box (union non-negative-real-number |#f|)) |#f|) (space (box (union non-negative-real-number |#f|)) |#f|) (lspace (box (union non-negative-real-number |#f|)) |#f|) (rspace (box (union non-negative-real-number |#f|)) |#f|)) void))]{
Sets the descent, space, lspace, and rspace to zero. Sets
the height to 1. Sets the width to the number of characters
in the string.
}
@defmethod*[#:mode override (((insert (s string) (len exact) (pos exact 0)) void))]{
}
@defmethod*[#:mode override (((draw (dc (instanceof dc<%>)) (x real) (y real) (left real) (top real) (right real) (bottom real) (dx real) (dy real) (draw-caret (union (quote no-caret) (quote show-inactive-caret) (quote show-caret)))) void))]{
Draws black pixels for non-whitespace characters and draws
nothing for whitespace characters.
}
}
@defclass[text:1-pixel-tab-snip% tab-snip% ()]{
This class re-uses the implementation of
@scheme[tab-snip%]
to implement a string snip that is always one pixel
high.
See also
@scheme[text:1-pixel-string-snip%]
for a similar extension to the
@scheme[string-snip%]class.
This snip is used in conjunction with the
@scheme[frame:delegate<%>]
and
@scheme[text:delegate<%>]
interfaces.
@defmethod*[#:mode override (((split (position exact) (first (box (instanceof snip%))) (second (box (instanceof snip%)))) void))]{
Fills the boxes with instance of
@scheme[text:1-pixel-tab-snip%]s.
}
@defmethod*[#:mode override (((copy) (instanceof snip%)))]{
Creates and returns an instance of
@scheme[text:1-pixel-tab-snip%].
}
@defmethod*[#:mode override (((get-extent (dc (instanceof dc<%>)) (x real) (y real) (w (box (union non-negative-real-number |#f|)) |#f|) (h (box (union non-negative-real-number |#f|)) |#f|) (descent (box (union non-negative-real-number |#f|)) |#f|) (space (box (union non-negative-real-number |#f|)) |#f|) (lspace (box (union non-negative-real-number |#f|)) |#f|) (rspace (box (union non-negative-real-number |#f|)) |#f|)) void))]{
Sets the descent, space, lspace, and rspace to zero. Sets
the height to 1. Sets the width to the width of tabs as
returned in the \scm{tab-width} parameter of the
@method[text% get-tabs]
method.
}
@defmethod*[#:mode override (((draw (dc (instanceof dc<%>)) (x real) (y real) (left real) (top real) (right real) (bottom real) (dx real) (dy real) (draw-caret (union (quote no-caret) (quote show-inactive-caret) (quote show-caret)))) void))]{
Draws nothing.
}
}
@defmixin[text:delegate-mixin (text:basic<%>) (text:delegate<%>)]{
This mixin provides an implementation of the
@scheme[text:delegate<%>]
interface.
@defmethod*[#:mode override (((highlight-range (start exact-integer) (end exact-integer) (color (instance color%)) (bitmap (union |#f| (instance bitmap%))) (caret-space boolean |#f|) (priority (union (quote high) (quote low)) (quote low))) (-> void)))]{
In addition to calling the super method,
@method[text:basic<%> highlight-range], this method forwards the highlighting to
the delegatee.
}
@defmethod*[#:mode override (((unhighlight-range (start exact-integer) (end exact-integer) (color (instance color%)) (bitmap (union |#f| (instance bitmap%)) |#f|) (caret-space boolean |#f|)) void))]{
This method propagates the call to the delegate.
}
@defmethod*[#:mode override (((on-paint (before? any/c) (dc (is-a?/c dc<%>)) (left real?) (top real?) (right real?) (bottom real?) (dx real?) (dy real?) (draw-caret (one-of/c (quote no-caret) (quote show-inactive-caret) (quote show-caret)))) void))]{
Draws a blue region in the delegatee editor that shows where
the visible region of the delegate editor is.
}
@defmethod*[#:mode augment (((on-edit-sequence) void))]{
starts an edit sequence in the delegate.
}
@defmethod*[#:mode augment (((after-edit-sequence) void))]{
ends an edit sequence in the delegate.
}
@defmethod*[#:mode override (((resized (snip (is-a?/c snip%)) (redraw-now? boolean)) void))]{
Sends a message to the delegate to update the size of the
copied snip, if there is one.
}
@defmethod*[#:mode augment (((after-insert (start number) (len number)) void))]{
forwards the change to the delegate
}
@defmethod*[#:mode augment (((after-delete (start number) (len number)) void))]{
forwards the change to the delegate.
}
@defmethod*[#:mode augment (((after-change-style (start number) (len number)) void))]{
forwards the changed style to the delegate.
}
@defmethod*[#:mode augment (((on-load-file (filename string) (format symbol?)) void))]{
remembers the filename, for use in
@method[text:delegate-mixin after-load-file].
}
@defmethod*[#:mode augment (((after-load-file (success? boolean)) void))]{
updates the delegate with the new contents of the text.
}
}
@definterface[text:info<%> (text:basic<%>)]{
Objects supporting this interface are expected to send information
about themselves to the frame that is displaying them.
}
@defmixin[text:info-mixin (editor:keymap<%> text:basic<%>) (text:info<%>)]{
This mixin adds support for supplying information to objects created with
@scheme[frame:info-mixin]. When this
@scheme[editor:basic<%>]
is displayed in a frame, that frame must have been created with
@scheme[frame:info-mixin].
@defmethod*[#:mode override (((set-anchor (on? any/c)) void))]{
Calls the
@method[frame:text-info<%> anchor-status-changed]
method of the frame that is viewing this object. It uses
@method[editor<%> get-canvas]
to get the canvas for this frame, and uses that canvas's
@scheme[top-level-window<%>]
as the frame.
}
@defmethod*[#:mode override (((set-overwrite-mode (on? any/c)) void))]{
Calls the
@method[frame:text-info<%> overwrite-status-changed]method of the frame that is viewing this object. It uses
@method[editor<%> get-canvas]
to get the canvas for this frame, and uses that canvas's
@scheme[top-level-window<%>]
as the frame.
}
@defmethod*[#:mode augment (((after-set-position) void))]{
Calls the
@method[frame:text-info<%> editor-position-changed]
method of the frame that is viewing this object. It uses
@method[editor<%> get-canvas]
to get the canvas for this frame, and uses that canvas's
@scheme[top-level-window<%>]
as the frame.
}
@defmethod*[#:mode augment (((after-insert (start nonnegative-exact-integer?) (len nonnegative-exact-integer?)) void))]{
Calls the
@method[frame:text-info<%> editor-position-changed]
method of the frame that is viewing this object. It uses
@method[editor<%> get-canvas]
to get the canvas for this frame, and uses that canvas's
@scheme[top-level-window<%>]
as the frame.
}
@defmethod*[#:mode augment (((after-delete (start nonnegative-exact-integer?) (len nonnegative-exact-integer?)) void))]{
Calls the
@method[frame:text-info<%> editor-position-changed]
method of the frame that is viewing this object. It uses
@method[editor<%> get-canvas]
to get the canvas for this frame, and uses that canvas's
@scheme[top-level-window<%>]
as the frame.
}
}
@definterface[text:clever-file-format<%> (text%)]{
Objects supporting this interface are expected to support a clever
file format when saving.
}
@defmixin[text:clever-file-format-mixin (text%) (text:clever-file-format<%>)]{
The result of this mixin uses the same initialization arguments as the
mixin's argument.
When files are saved from this
@scheme[text%], a check is made to see if there are any non-@scheme[string-snip%]
objects in the
@scheme[text%]. If so, it is saved using the file format \rawscm{'std}. (see
@method[text% set-file-format]
for more information. If not, the file format passed to
@method[editor<%> save-file]
is used.
@defmethod*[#:mode augment (((on-save-file (filename path?) (format (one-of/c (quote guess) (quote standard) (quote text) (quote text-force-cr) (quote same) (quote copy)))) void))]{
If the method
@method[text% get-file-format]
returns \rawscm{'standard} and the text has only
@scheme[string-snip%]s, the file format is set to \rawscm{'text}.
If the method
@method[text% get-file-format]
returns \rawscm{'text} and the text has some non
@scheme[string-snip%]s, the file format is set to \rawscm{'standard}.
Depending on the user's preferences, the user may also be queried.
Also, the changes to the file format only happen if the argument
\var{file-format} is \rawscm{'copy} or \rawscm{'same}.
}
}
@definterface[text:file<%> (editor:file<%> text:basic<%>)]{
Mixins that implement this interface lock themselves when
the file they are editing is read only.
@defmethod*[(((get-read-write?) boolean))]{
Indicates whether or not this editor is in read-write mode.
}
@defmethod*[(((while-unlocked (thunk (-> any/c))) any/c))]{
Unlocks the editor, calls the thunk, and then relocks the
editor, all using a \scheme{dynamic-wind}.
}
}
@defmixin[text:file-mixin (editor:file<%> text:basic<%>) (text:file<%>)]{
@defmethod*[#:mode augment (((can-insert? (start number) (len number)) boolean))]{
Returns false if the result of
@method[text:file<%> get-read-write?]
is true, otherwise returns the
result of calling \scheme|inner|.
}
@defmethod*[#:mode augment (((can-delete? (start number) (len number)) boolean))]{
Returns false if the result of
@method[text:file<%> get-read-write?]
is true, otherwise returns the
result of calling \scheme|inner|.
}
@defmethod*[#:mode augment (((after-save-file) void))]{
Checks if the newly saved file is write-only in the filesystem. If
so, locks the editor with the
@method[editor<%> lock]
method. Otherwise unlocks the buffer
For each canvas returned from
@method[editor<%> get-canvases]
it checks to see if the
@scheme[canvas%]'s
@method[area<%> get-top-level-window]
matches the
@scheme[frame:editor<%>]
interface. If so, it calls
@method[frame:editor-mixin set-label]
with the last part of the filename (ie, the name of the file, not the
directory the file is in).
}
@defmethod*[#:mode augment (((after-load-file) void))]{
Checks if the newly loaded file is write-only in the filesystem. If
so, locks the editor with the
@method[editor<%> lock]
method. Otherwise unlocks the buffer
For each canvas returned from
@method[editor<%> get-canvases]
it checks to see if the
@scheme[canvas%]'s
@method[area<%> get-top-level-window]
matches the
@scheme[frame:editor<%>]
interface. If so, it calls
@method[frame:editor-mixin set-label]
with the last part of the filename (ie, the name of the file, not the
directory the file is in).
}
}
@definterface[text:ports<%> ()]{
Classes implementing this interface (via the associated
mixin) support input and output ports that read from the
editor.
There are two input ports: the normal input port just reads
from the editor's contents directly and the box input port
inserts an editor snip into this text and uses input typed
into the box as input into the port.
They create three threads to mediate access to the input and
output ports (one for each input port and one for all of the
output ports).
@defmethod*[(((delete/io (start exact-integer) (end exact-integer)) void))]{
Deletes the text between \var{start} and \var{end} without
changing the behavior of the ports (otherwise, deleting the
text would break internal invariants of the port).
Both \var{start} and \var{end} must be less than
@method[text:ports<%> get-insertion-point]
(or else it is safe to delete them so you don't need this
method).
}
@defmethod*[(((get-insertion-point) exact-integer))]{
Returns the position where characters put into the output
port will appear.
}
@defmethod*[(((set-insertion-point (ip exact-integer)) void))]{
Sets the position where the output port will insert characters.
See also
@method[text:ports<%> get-insertion-point].
}
@defmethod*[(((get-unread-start-point) exact-integer))]{
Returns the position where input will be taken into the
input port (after the next time return is typed).
}
@defmethod*[(((set-unread-start-point (usp exact-integer)) void))]{
Sets the position where input will be taken into the
input port (after the next time return is typed).
See also
@method[text:ports<%> get-unread-start-point].
}
@defmethod*[(((set-allow-edits (allow-edits? boolean)) void))]{
Enables or disables editing in the buffer. Be sure to update
the unread start point (via
@method[text:ports<%> set-unread-start-point]) and the insertion point (via
@method[text:ports<%> set-insertion-point]) after making changes to the buffer.
}
@defmethod*[(((get-allow-edits) boolean))]{
Indicates if editing is allowed in the buffer at this point.
}
@defmethod*[(((insert-between (str (union snip% string))) void))]{
Inserts some text between the unread start point and the
insertion point (and updates them properly). To insert
before the two points, see
@method[text:ports<%> insert-before].
See also
@method[text:ports<%> set-unread-start-point]
and
@method[text:ports<%> set-insertion-point].
}
@defmethod*[(((insert-before (str (union snip% string))) void))]{
Inserts some text before the unread start point and updates
it and the insertion point properly. To insert between
the two points, see
@method[text:ports<%> insert-between].
See also
@method[text:ports<%> set-unread-start-point]
and
@method[text:ports<%> set-insertion-point].
}
@defmethod*[(((submit-to-port? (key char)) boolean))]{
Augment this method to help control when characters should
be submitted to the input port.
Return \scheme|#t| or the result of calling \scheme|inner|.
}
@defmethod*[(((on-submit) void))]{
This method is called when text is sent into the input port.
Does nothing.
}
@defmethod*[(((send-eof-to-in-port) void))]{
This method puts an eof into the input port.
}
@defmethod*[(((send-eof-to-box-in-port) void))]{
This method puts an eof into the box input port.
}
@defmethod*[(((reset-input-box) void))]{
This method removes the current input box from the editor
(and all input in it is lost).
}
@defmethod*[(((clear-output-ports) void))]{
Flushes all of the data in all of the output ports that
hasn't appeared in the editor yet.
}
@defmethod*[(((clear-input-port) void))]{
Flushes all of the data in the input port that hasn't yet
been read. Reading will now block.
}
@defmethod*[(((clear-box-input-port) void))]{
Flushes all of the data in the box input port that hasn't
yet been read. Reading will now block.
}
@defmethod*[(((get-out-style-delta) (or/c (is-a?/c style-delta%) string?)))]{
The result of this method is the style that is used to color
text submitted to the result of
@method[text:ports<%> get-out-port].
If the result is a string that is not mapped in the editor's
style list, the style named \scheme|"Standard"| is used and
if that isn't mapped, the style named \scheme|"Basic"| is used.
This method is called during the initialization of the class.
Defaultly returns \scheme|"text:ports out"| which is mapped
to a blue style in the style list returned by
@scheme[editor:get-standard-style-list].
}
@defmethod*[(((get-err-style-delta) (or/c (is-a?/c style-delta%) string?)))]{
The result of this method is the style that is used to color
text submitted to the result of
@method[text:ports<%> get-err-port].
If the result is a string that is not mapped in the editor's
style list, the style named \scheme|"Standard"| is used and
if that isn't mapped, the style named \scheme|"Basic"| is used.
This method is called during the initialization of the class.
Defaultly returns \scheme|"text:ports err"| which is mapped
to a red italic style in the style list returned by
@scheme[editor:get-standard-style-list].
}
@defmethod*[(((get-value-style-delta) (or/c (is-a?/c style-delta%) string?)))]{
The result of this method is the style (or the name of the
style) that is used to color text submitted to the result of
@method[text:ports<%> get-value-port].
If the result is a string that is not mapped in the editor's
style list, the style named \scheme|"Standard"| is used and
if that isn't mapped, the style named \scheme|"Basic"| is used.
This method is called during the initialization of the class.
Defaultly returns \scheme|"text:ports value"| which is mapped
to a blue style in the style list returned by
@scheme[editor:get-standard-style-list].
}
@defmethod*[(((get-in-port) input-port))]{
Returns the input port that data in this editor is sent to.
}
@defmethod*[(((get-in-box-port) input-port))]{
Returns the box input port that data in this editor is sent to.
}
@defmethod*[(((get-out-port) output-port))]{
Returns an output port that writes into this editor. The
only difference between this port and the ports returned by
@method[text:ports<%> get-err-port]
and
@method[text:ports<%> get-value-port]
is the font style and color.
}
@defmethod*[(((get-err-port) output-port))]{
Returns an output port that writes into this editor. The
only difference between this port and the ports returned by
@method[text:ports<%> get-err-port]
and
@method[text:ports<%> get-out-port]
is the font style and color.
}
@defmethod*[(((get-value-port) output-port))]{
Returns an output port that writes into this editor. The
only difference between this port and the ports returned by
@method[text:ports<%> get-err-port]
and
@method[text:ports<%> get-out-port]
is the font style and color.
}
@defmethod*[(((after-io-insertion) void))]{
This method is called after an insertion due to IO occurs.
}
@defmethod*[(((get-box-input-editor-snip%) (subclass editor-snip%)))]{
The result of this method is used as the class of editor
snips that is inserted by the box port in this editor.
}
@defmethod*[(((get-box-input-text%) (implements iscmmixin (text:input-box))))]{
The result of this method is instantiated and placed inside the result of
@method[text:ports<%> get-box-input-editor-snip\%].
}
}
@defmixin[text:ports-mixin (text:wide-snip<%>) (text:ports<%>)]{
@defmethod*[#:mode augment (((can-insert? (start exact-integer) (len exact-integer)) boolean))]{
Returns the results of the \scheme|inner| call, unless
@method[text:ports<%> get-allow-edits]
returns \scheme|#f|.
}
@defmethod*[#:mode augment (((can-delete? (start exact-integer) (len exact-integer)) boolean))]{
Returns the results of the \scheme|inner| call, unless
@method[text:ports<%> get-allow-edits]
returns \scheme|#f|.
}
@defmethod*[#:mode override (((on-local-char (event (is-a?/c key-event%))) void))]{
Sends the data between the last position and the result of
@method[text:ports<%> get-unread-start-point]
to the input port, unless
@method[text:ports<%> submit-to-port?]
returns \scheme|#f|.
Also calls
@method[text:ports<%> on-submit].
}
@defmethod*[#:mode augment (((on-display-size) void))]{
Adjusts the embedded editor-snip (used for reading input to the
@method[text:ports<%> get-in-box-ports]) to match the width of the editor.
}
}
@definterface[text:input-box<%> (text%)]{
Classes that implement this interface are used as the
editors for the box input port in
@scheme[text:ports%].
}
@defmixin[text:input-box-mixin (text%) (text:input-box<%>)]{
This mixin provides an implementation of
@scheme[text:input-box<%>]
for use with
@scheme[text:ports<%>].
@defmethod*[#:mode override (((on-default-char (event key-event%)) void))]{
Notifies the
@scheme[text:ports<%>]
enclosing this editor that a new line of input has been provided.
}
}
@definterface[text:autocomplete<%> (text%)]{
The mixin implementing this interface provides an
unintrusive autocompletion menu when a particular
(configurable) keystroke is pressed.
@defmethod*[(((auto-complete) void))]{
Starts a completion.
}
@defmethod*[(((get-autocomplete-border-color) (or/c string? (is-a?/c color%))))]{
The border color for the autocomplete menu. Defaults to
\scheme|"black"|.
}
@defmethod*[(((get-autocomplete-background-color) (or/c string? (is-a?/c color%))))]{
The background color for the non-selected menu
items. Defaults to \scheme|"lavender"|.
}
@defmethod*[(((get-autocomplete-selected-color) (or/c string? (is-a?/c color%))))]{
The background color for the selected menu item. Defaults to
\scheme|(make-object color% 204 153 255)|.
}
@defmethod*[(((completion-mode-key-event? (key-event key-event%)) boolean))]{
Returns true when the key event passed to it should initiate
the completions menu.
}
@defmethod*[(((get-all-words) (listof string)))]{
Returns the list of the words that autocompletion should
choose from.
}
@defmethod*[(((get-word-at (pos positive-exact-integer)) string))]{
Given an editor location, returns the prefix ending at that location
that autocompletion should try to complete.
}
}
@defmixin[text:autocomplete-mixin (text%) (text:autocomplete<%>)]{
@defmethod*[#:mode override (((on-paint) void))]{
Draws the completion menu (when it is popped up).
}
@defmethod*[#:mode override (((on-char) void))]{
Takes over the handling of key events when the completions
menu is visible. Also, when the completions menu is not
visible, it calls the
@method[text:completion<%> completion-mode-key-event?]
method to see if it should start completing.
}
@defmethod*[#:mode override (((on-event) void))]{
This method is overridden to allow mouse access of the
completions menu. It only handles events when there is a
menu open and the mouse is in the menu, in which case it
makes the menu trace the mouse.
The only time it does not call the super method is when
the mouse is button is pushed.
}
}
@defclass[text:basic% (text:basic-mixin (editor:basic-mixin text%)) ()]{}
@defclass[text:hide-caret/selection% (text:hide-caret/selection-mixin text:basic%) ()]{}
@defclass[text:nbsp->space% (text:nbsp->space-mixin text:basic%) ()]{}
@defclass[text:delegate% (text:delegate-mixin text:basic%) ()]{}
@defclass[text:wide-snip% (text:wide-snip-mixin text:basic%) ()]{}
@defclass[text:standard-style-list% (editor:standard-style-list-mixin text:wide-snip%) ()]{}
@defclass[text:input-box% (text:input-box-mixin text:standard-style-list%) ()]{}
@defclass[text:keymap% (editor:keymap-mixin text:standard-style-list%) ()]{}
@defclass[text:return% (text:return-mixin text:keymap%) ()]{}
@defclass[text:autowrap% (editor:autowrap-mixin text:keymap%) ()]{}
@defclass[text:file% (text:file-mixin (editor:file-mixin text:autowrap%)) ()]{}
@defclass[text:clever-file-format% (text:clever-file-format-mixin text:file%) ()]{}
@defclass[text:backup-autosave% (editor:backup-autosave-mixin text:clever-file-format%) ()]{}
@defclass[text:searching% (text:searching-mixin text:backup-autosave%) ()]{}
@defclass[text:info% (text:info-mixin (editor:info-mixin text:searching%)) ()]{}
@(require framework/framework-docs)
@(def-fw-procs text)

8
collects/scribblings/framework/framework-version.scrbl Normal file
View File

@ -0,0 +1,8 @@
#lang scribble/doc
@(require scribble/manual)
@(require (for-label framework/framework))
@(require (for-label scheme/gui))
@title{Version}
@(require framework/framework-docs)
@(def-fw-procs version)

28
collects/scribblings/framework/framework.scrbl
View File

@ -8,5 +8,29 @@
@(defmodule framework/framework)
@(require framework/framework-docs)
@(def-fw-procs)
@include-section["framework-application.scrbl"]
@include-section["framework-autosave.scrbl"]
@include-section["framework-canvas.scrbl"]
@include-section["framework-color-model.scrbl"]
@include-section["framework-color-prefs.scrbl"]
@include-section["framework-color.scrbl"]
@include-section["framework-comment-box.scrbl"]
@include-section["framework-editor.scrbl"]
@include-section["framework-exit.scrbl"]
@include-section["framework-finder.scrbl"]
@include-section["framework-frame.scrbl"]
@include-section["framework-group.scrbl"]
@include-section["framework-handler.scrbl"]
@include-section["framework-icon.scrbl"]
@include-section["framework-keymap.scrbl"]
@;include-section["framework-main.scrbl"]
@include-section["framework-menu.scrbl"]
@;include-section["framework-mode.scrbl"]
@include-section["framework-number-snip.scrbl"]
@include-section["framework-panel.scrbl"]
@include-section["framework-pasteboard.scrbl"]
@include-section["framework-path-utils.scrbl"]
@include-section["framework-preferences.scrbl"]
@include-section["framework-scheme.scrbl"]
@include-section["framework-text.scrbl"]
@include-section["framework-version.scrbl"]

2
collects/scribblings/framework/info.ss
View File

@ -1,4 +1,4 @@
#lang setup/infotab
(define scribblings '(("framework.scrbl" (#;multi-page) (gui-library 100))))
(define scribblings '(("framework.scrbl" (multi-page))))