From a4726678ff9555f8128540cc48bf6262d13a7d3f Mon Sep 17 00:00:00 2001
From: Robby Findler <robby@racket-lang.org>
Date: Wed, 16 Jun 2010 11:50:03 -0500
Subject: [PATCH] added documentation for the extended gui-interaction & co.
 operators

---
 collects/scriblib/scribblings/gui-eval.scrbl | 67 +++++++++++++++++---
 1 file changed, 58 insertions(+), 9 deletions(-)

diff --git a/collects/scriblib/scribblings/gui-eval.scrbl b/collects/scriblib/scribblings/gui-eval.scrbl
index f6a86f800f..48682f11a2 100644
--- a/collects/scriblib/scribblings/gui-eval.scrbl
+++ b/collects/scriblib/scribblings/gui-eval.scrbl
@@ -16,16 +16,65 @@ images. Future runs (with the environment variable unset) use the
 generated image.
 
 @deftogether[(
-@defform[(gui-interaction datum ...)]
-@defform[(gui-interaction-eval datum ...)]
-@defform[(gui-interaction-eval-show datum ...)]
-@defform[(gui-schemeblock+eval datum ...)]
-@defform[(gui-schememod+eval datum ...)]
-@defform[(gui-def+int datum ...)]
-@defform[(gui-defs+int datum ...)]
+@defform*[((gui-interaction datum ...)
+               (gui-interaction 
+                #:eval+opts the-eval get-predicate? get-render 
+                            get-get-width get-get-height
+                datum ...))
+               ]
+@defform*[((gui-interaction-eval datum ...)
+           (gui-interaction-eval 
+            #:eval+opts the-eval get-predicate? get-render 
+                        get-get-width get-get-height
+            datum ... ))]
+@defform*[((gui-interaction-eval-show datum ...)
+           (gui-interaction-eval-show
+            #:eval+opts the-eval get-predicate? get-render 
+                        get-get-width get-get-height
+            datum ...))]
+@defform*[((gui-schemeblock+eval datum ...)
+           (gui-schemeblock+eval
+            #:eval+opts the-eval get-predicate? get-render 
+                        get-get-width get-get-height
+            datum ...))]
+@defform*[((gui-schememod+eval datum ...)
+           (gui-schememod+eval
+            #:eval+opts the-eval get-predicate? get-render 
+                        get-get-width get-get-height
+            datum ...))]
+@defform*[((gui-def+int datum ...)
+           (gui-def+int
+            #:eval+opts the-eval get-predicate? get-render 
+                        get-get-width get-get-height
+            datum ...))]
+@defform*[((gui-defs+int datum ...)
+           (gui-defs+int
+            #:eval+opts the-eval get-predicate? get-render 
+                        get-get-width get-get-height
+            datum ...))]
 )]{
 
-Like @scheme[interaction], etc., but actually evaluating the forms
+The first option of each of the above is
+like @scheme[interaction], etc., but actually evaluating the forms
 only when the @envvar{MREVAL} environment variable is set, and then in
 an evaluator that is initialized with @schememodname[racket/gui/base]
-and @schememodname[slideshow]. }
+and @schememodname[slideshow]. 
+
+The second option of each allows you to specify your own evaluator via
+the @scheme[the-eval] argument and then to specify four thunks that
+return functions for finding and rendering graphical objects:
+@itemize[
+         @item{@scheme[get-predicate? : (-> (-> any/c boolean?))]
+                Determines if a value is a graphical object (and thus handled by the other operations)}
+         @item{@scheme[get-render : (-> (-> any/c (is-a?/c dc<%>) number? number? void?))]
+                Draws a graphical object (only called if the predicate returned @scheme[#t]; the first
+                argument will be the value for which the predicate holds).}
+         @item{@scheme[get-get-width : (-> (-> any/c number?))]
+                Gets the width of a graphical object (only called if the predicate returned @scheme[#t]; the first
+                argument will be the value for which the predicate holds).}
+         @item{@scheme[get-get-height : (-> (-> any/c number?))]
+                Gets the height of a graphical object (only called if the predicate returned @scheme[#t]; the first
+                argument will be the value for which the predicate holds).}
+          ]
+
+}