Documentation added

scrbl/rkdt.scrbl

@@ -7,7 +7,6 @@
 @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.
@@ -23,38 +22,67 @@ separate full editor application.
                [#:height height exact-positive-integer? 650]
                [#:x x exact-integer? 100]
                [#:y y exact-integer? 100]
-               [#:frame-cb frame-cb procedure? (λ (frame) #t)])
+               [#:frame-cb frame-cb procedure?
+                            (λ (call-time frame) #t)])
          void?]{
 
-Opens an editor window for @racket[filename]. The file name is passed to the
-Racket editor frame and the editor is shown immediately.
+@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 for a window for which no stored geometry
-is available. When an editor window is closed, @tt{rackedit} stores its position
-and size. A later editor window with the same internal window number restores
-that geometry.
+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.
 
-Stored geometry is associated with the current screen configuration. The screen
-configuration is derived from the number and dimensions of the displays visible
-to Racket. Consequently, changing the monitor configuration causes the default
-geometry, or geometry previously stored for that configuration, to be used.
-
-If @racket[wait?] is @racket[#f], the procedure returns after the editor has
-been shown. If @racket[wait?] is @racket[#t], the current event handler waits
-until the editor window is closed before the procedure continues.
-
-The @racket[frame-cb] procedure receives the editor frame. With the default
-@racket[#:wait?] value it is called after the frame has been shown and can be
-used to customize the frame, for example to change its title. When
-@racket[wait?] is @racket[#t], the callback is called only after the window has
-been closed. Its return value is ignored.
-
-Each open editor has an internal number. That number is shown in the window
-title and is also used to distinguish stored window geometries. Numbers of
-closed editor windows are reused.
+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:
@@ -72,7 +100,7 @@ closed:
 (rkdt "notes.rkt" #:wait? #t)
 ]
 
-A frame callback can customize the editor frame:
+A frame callback can customize the editor before it becomes visible:
 
 @racketblock[
 (require racket/class
@@ -80,8 +108,30 @@ A frame callback can customize the editor frame:
 
 (rkdt "notes.rkt"
       #:frame-cb
-      (λ (frame)
-        (send frame set-label "Notes")))
+      (λ (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:
@@ -93,10 +143,3 @@ The initial window geometry can be supplied explicitly:
       #:x 50
       #:y 50)
 ]
-
-@section{Window behavior}
-
-The editor uses Racket's standard editor menus, except that the standard
-@onscreen{Exit} or @onscreen{Quit} command is not added to the File menu.
-Closing an editor window closes only that window and releases its internal
-window number for reuse by a later editor window.