146 lines
5.0 KiB
Racket
146 lines
5.0 KiB
Racket
#lang scribble/manual
|
|
|
|
@(require (for-label racket/base
|
|
racket/class
|
|
"../main.rkt"))
|
|
|
|
@title{rackedit}
|
|
@author[@author+email["Hans Dijkema" "hans@dijkewijk.nl"]]
|
|
|
|
@defmodule[rackedit]
|
|
|
|
@tt{rackedit} provides a small editor window based on Racket's GUI framework.
|
|
It is intended for situations where a program, DrRacket interaction, or command
|
|
line session needs to open a file in a simple Racket editor without starting a
|
|
separate full editor application.
|
|
|
|
@section{Opening an editor}
|
|
|
|
@defproc[(rkdt [filename path-string?]
|
|
[#:wait? wait? boolean? #f]
|
|
[#:width width exact-positive-integer? 900]
|
|
[#:height height exact-positive-integer? 650]
|
|
[#:x x exact-integer? 100]
|
|
[#:y y exact-integer? 100]
|
|
[#:frame-cb frame-cb procedure?
|
|
(λ (call-time frame) #t)])
|
|
void?]{
|
|
|
|
@bold{Purpose.} Opens an editor window for @racket[filename].
|
|
|
|
@bold{Preconditions.} @racket[filename] identifies the file to open.
|
|
@racket[frame-cb] must accept two arguments: a lifecycle symbol and the editor
|
|
frame. The geometry arguments specify valid dimensions and screen coordinates.
|
|
|
|
@bold{Postconditions.} An editor frame has been created and shown. When
|
|
@racket[wait?] is @racket[#f], @racket[rkdt] returns after the frame has been
|
|
shown and the @racket['after-show] callback has run. When @racket[wait?] is
|
|
@racket[#t], @racket[rkdt] waits until the frame is closed.
|
|
|
|
@bold{Result.} The procedure returns @racket[(void)]. The editor frame itself is
|
|
made available to @racket[frame-cb] during its lifecycle callbacks.
|
|
|
|
@bold{Internal workings.} Each open editor receives an internal number. That
|
|
number is appended to the window title and is used to distinguish stored window
|
|
geometry. Numbers belonging to closed editors are reused. On close, the current
|
|
position and size are stored for that internal number and the current screen
|
|
configuration.
|
|
|
|
The @racket[#:width], @racket[#:height], @racket[#:x], and @racket[#:y]
|
|
arguments specify the initial geometry when no stored geometry is available.
|
|
Stored geometry is associated with the screen configuration derived from the
|
|
number and dimensions of the displays visible to Racket. Changing the monitor
|
|
configuration therefore selects a different set of stored geometry values.
|
|
|
|
The standard File menu does not contain the @onscreen{Exit} or
|
|
@onscreen{Quit} command. Closing an editor window closes only that window.
|
|
}
|
|
|
|
@section{Frame callback lifecycle}
|
|
|
|
The procedure supplied with @racket[#:frame-cb] is called as
|
|
@racket[(frame-cb call-time frame)]. Its return value is ignored. The
|
|
@racket[call-time] argument has the following meanings.
|
|
|
|
@itemlist[
|
|
@item{@racket['before-show] is called after the frame has been fully created,
|
|
positioned, resized, numbered, and supplied with the callback, but before
|
|
@racket[show] is called. This is the preferred point for changes that
|
|
should already be visible when the window first appears, such as changing
|
|
the title.}
|
|
@item{@racket['after-show] is called immediately after @racket[show] has been
|
|
called. It can be used for actions that require a shown frame.}
|
|
@item{@racket['wait-for-close] is called only when @racket[#:wait? #t] is in
|
|
effect, immediately before @racket[rkdt] starts waiting for the frame to
|
|
close.}
|
|
@item{@racket['on-close] is called while the frame's close event is being
|
|
handled. At that point its geometry has been stored, its internal number
|
|
has been released for reuse, and the close semaphore has been posted.}
|
|
]
|
|
|
|
Thus, without waiting, the normal lifecycle is
|
|
@racket['before-show], @racket['after-show], and eventually
|
|
@racket['on-close]. With @racket[#:wait? #t], @racket['wait-for-close] occurs
|
|
between @racket['after-show] and @racket['on-close].
|
|
|
|
@section{Examples}
|
|
|
|
The simplest use opens a file and returns immediately:
|
|
|
|
@racketblock[
|
|
(require rackedit)
|
|
|
|
(rkdt "notes.rkt")
|
|
]
|
|
|
|
Use @racket[#:wait? #t] when execution should continue only after the editor is
|
|
closed:
|
|
|
|
@racketblock[
|
|
(rkdt "notes.rkt" #:wait? #t)
|
|
]
|
|
|
|
A frame callback can customize the editor before it becomes visible:
|
|
|
|
@racketblock[
|
|
(require racket/class
|
|
rackedit)
|
|
|
|
(rkdt "notes.rkt"
|
|
#:frame-cb
|
|
(λ (call-time frame)
|
|
(when (eq? call-time 'before-show)
|
|
(send frame
|
|
set-label
|
|
(string-append (send frame get-label)
|
|
" - Rash")))))
|
|
]
|
|
|
|
The same callback can react to multiple lifecycle moments:
|
|
|
|
@racketblock[
|
|
(rkdt "notes.rkt"
|
|
#:wait? #t
|
|
#:frame-cb
|
|
(λ (call-time frame)
|
|
(case call-time
|
|
[(before-show)
|
|
(displayln "Editor will be shown")]
|
|
[(after-show)
|
|
(displayln "Editor is shown")]
|
|
[(wait-for-close)
|
|
(displayln "Waiting for the editor to close")]
|
|
[(on-close)
|
|
(displayln "Editor is closing")])))
|
|
]
|
|
|
|
The initial window geometry can be supplied explicitly:
|
|
|
|
@racketblock[
|
|
(rkdt "notes.rkt"
|
|
#:width 1200
|
|
#:height 800
|
|
#:x 50
|
|
#:y 50)
|
|
]
|