rackedit/scrbl/rkdt.scrbl

#lang scribble/manual

@(require (for-label racket/base
                     racket/class
                     racket/contract
                     "../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 a simple Racket editor, optionally for a specific file, without
starting a separate full editor application.

@section{Opening an editor}

@defproc[(rkdt [filename (or/c path-string? #f) #f]
               [#: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. When @racket[filename] is a path or
string, that file is opened. When @racket[filename] is @racket[#f], which is the
default, an empty editor is opened.

@bold{Preconditions.} When supplied, @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.} A non-false @racket[filename] is converted to a
string before it is supplied to the Framework editor frame. A false filename is
passed through as @racket[#f], causing the frame to start without a file.

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 an empty editor and returns immediately:

@racketblock[
(require rackedit)

(rkdt)
]

Supply a filename to open a file:

@racketblock[
(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)
]