#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.