From f780c7f5b4862127d84b37e999af22f9577d00b3 Mon Sep 17 00:00:00 2001 From: Hans Dijkema Date: Thu, 20 Aug 2026 22:31:25 +0200 Subject: [PATCH] Documentation added --- README.md | 14 ++++-- scrbl/rkdt.scrbl | 115 ++++++++++++++++++++++++++++++++--------------- 2 files changed, 89 insertions(+), 40 deletions(-) diff --git a/README.md b/README.md index 9384051..b5b82b9 100644 --- a/README.md +++ b/README.md @@ -10,7 +10,7 @@ The package exports one procedure: (rkdt "notes.rkt") ``` - + By default `rkdt` shows the editor and returns immediately. Use `#:wait? #t` when execution should continue only after the editor is closed: @@ -22,7 +22,12 @@ The initial window geometry can be specified with `#:width`, `#:height`, `#:x`, and `#:y`. Window positions and sizes are remembered per internal editor number and per screen configuration. -The frame can be customized with `#:frame-cb`. For example: +The frame can be observed or customized with `#:frame-cb`. The callback receives +an event symbol and the editor frame. It is called at the lifecycle points +`'before-show`, `'after-show`, `'wait-for-close`, and `'on-close`. +`'wait-for-close` is emitted only when `#:wait? #t` is used. + +For example, the window title can be changed before the frame becomes visible: ```racket (require racket/class @@ -30,8 +35,9 @@ The frame can be customized with `#:frame-cb`. For example: (rkdt "notes.rkt" #:frame-cb - (λ (frame) - (send frame set-label "Notes"))) + (λ (event frame) + (when (eq? event 'before-show) + (send frame set-label "Notes")))) ``` The standard File menu does not contain the Exit/Quit command, so closing one diff --git a/scrbl/rkdt.scrbl b/scrbl/rkdt.scrbl index ba11ed3..353ed89 100644 --- a/scrbl/rkdt.scrbl +++ b/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.