frame callback perfectioned

2026-08-20 19:13:12 +02:00
parent 4e96ae7df8
commit 86ebac5578
13 changed files with 2950 additions and 15 deletions
@@ -0,0 +1,102 @@
+#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? (λ (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.
+
+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.
+
+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.
+}
+
+@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 frame:
+
+@racketblock[
+(require racket/class
+         rackedit)
+
+(rkdt "notes.rkt"
+      #:frame-cb
+      (λ (frame)
+        (send frame set-label "Notes")))
+]
+
+The initial window geometry can be supplied explicitly:
+
+@racketblock[
+(rkdt "notes.rkt"
+      #:width 1200
+      #:height 800
+      #: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.