added docs for the splash screen library in the framework

collects/drracket/private/drracket-normal.rkt

@@ -100,7 +100,7 @@
    [(and valentines-day? high-color?)
     (collection-file-path "heart.png" "icons")]
    [(and (or prince-kuhio-day? kamehameha-day?) high-color?)
-    (set-splash-progress-bar? #f)
+    (set-splash-progress-bar?! #f)
     (let ([size ((dynamic-require 'drracket/private/palaka 'palaka-pattern-size) 4)])
       (vector (dynamic-require 'drracket/private/honu-logo 'draw-honu) 
               size 

collects/framework/splash.rkt

@@ -14,7 +14,7 @@
          shutdown-splash
          close-splash
          add-splash-icon
-         set-splash-progress-bar?
+         set-splash-progress-bar?!
          set-splash-char-observer
          set-splash-event-callback
          get-splash-event-callback
@@ -86,7 +86,7 @@
                     (send (icon-bm icon) get-loaded-mask)))
             icons))
 
-(define (set-splash-progress-bar? b?) 
+(define (set-splash-progress-bar?! b?) 
   (send gauge-panel change-children
         (λ (l) (if b? (list gauge) '()))))
 

collects/scribblings/framework/framework.scrbl

@@ -78,6 +78,14 @@ The precise set of exported names is:
 @racket[preferences:set-un/marshall], and
 @racket[preferences:restore-defaults].
 }
+
+@item{@bold{Splash Screen}
+       @racket[(require @#,racketmodname[framework/splash])]
+       
+       This library provides support for a splash screen. See
+       @racketmodname[framework/splash] for more.
+}
+
 @item{@bold{Decorated Editor Snip}
 @racket[(require framework/decorated-editor-snip)]
 
@@ -123,6 +131,7 @@ their feedback and help.
 @include-section["preferences-text.scrbl"]
 @include-section["scheme.scrbl"]
 @include-section["text.scrbl"]
+@include-section["splash.scrbl"]
 @include-section["test.scrbl"]
 @include-section["version.scrbl"]
 

collects/scribblings/framework/splash.scrbl

@@ -0,0 +1,126 @@
+#lang scribble/doc
+@(require scribble/manual
+          (for-label racket/gui
+                     racket/base))
+@title{Splash}
+@defmodule[framework/splash]
+
+This module helps support applications with splash screens like the one in DrRacket.
+
+When this module is invoked, it sets the @racket[current-load] parameter to a procedure
+that counts how many files are loaded (until @racket[shutdown-splash] is called) and uses
+that number to control the gauge along the bottom of the splash screen.
+
+@defproc[(start-splash [draw-spec (or/c path-string?
+                                        (vector/c (or/c (-> (is-a?/c dc<%>) void?)
+                                                        (-> (is-a?/c dc<%>) 
+                                                            exact-nonnegative-integer?
+                                                            exact-nonnegative-integer?
+                                                            exact-nonnegative-integer?
+                                                            exact-nonnegative-integer?
+                                                            void?))
+                                                  exact-nonnegative-integer?
+                                                  exact-nonnegative-integer?))]
+                       [splash-title string?]
+                       [width-default exact-nonnegative-integer?])
+         void?]{
+  Starts a new splash screen. The splash screen is created in its own, new 
+  @tech[#:doc '(lib "scribblings/gui/gui.scrbl") #:key "eventspace"]{eventspace}.
+  The progress gauge at the bottom of the window advances as files are loaded
+  (monitored via the @racket[current-load] parameter).
+  
+  The @racket[draw-spec] determines what the splash window contains. 
+  The @racket[splash-title] is used as the title of the window and the @racket[width-default] determines
+  how many progress steps the gauge in the the splash screen should
+  contain (if there is no preference saved for the splash screen width; see @racket[set-splash-width-preference-name]).
+  
+  If the @racket[draw-spec] is a @racket[path-string?], then the path is expected to be a file
+  that contains a bitmap that is drawn as the contents of the splash screen. If @racket[draw-spec]
+  is a vector, then the vector's first element is a procedure that is called to draw
+  the splash screen and the other two integers are the size of the splash screen, width followed by height.
+  If the procedure accepts only one argument, then it is called with a @racket[dc<%>] object where the
+  drawing should occur. If it accepts 5 arguments, it is called with the @racket[dc<%>], as well as
+  (in order) the current value of the gauge, the maximum value of the gauge, and the width and the height
+  of the area to draw.
+
+  
+  
+  }
+@defproc[(shutdown-splash) void?]{
+  Stops the splash window's gauge from advancing. Call this after all of the files have been loaded.
+}
+
+@defproc[(close-splash) void?]{
+  Closes the splash window. Call @racket[shutdown-splash] first. You can leave some time between these two
+  if there is more initialization work to be done where you do not want to count loaded files.
+}
+
+@defproc[(add-splash-icon [bmp (is-a?/c bitmap%)] [x exact-nonnegative-integer?] [y exact-nonnegative-integer?])
+         void?]{
+  Adds an icon to the splash screen. (DrRacket uses this function to show the tools as they are loaded.)                
+}
+
+@defproc[(get-splash-bitmap) (or/c #f (is-a?/c bitmap%))]{Returns the splash bitmap unless one has not been set.}
+@defproc[(set-splash-bitmap [bmp (is-a?/c bitmap%)]) void?]{
+  Sets the splash bitmap to @racket[bmp] and triggers a redrawing of the splash screen. Don't use this to set
+  the initial bitmap, use @racket[start-splash] instead.
+}
+@defproc[(get-splash-canvas) (is-a?/c canvas%)]{
+  Returns the canvas where the splash screen bitmap is drawn (if there is a bitmap; see @racket[start-splash] for how the splash is drawn.
+}
+@defproc[(get-splash-eventspace) eventspace?]{
+  Returns the splash screen's eventspace.
+}
+@defproc[(get-splash-paint-callback)
+         (-> (is-a?/c dc<%>) 
+             exact-nonnegative-integer?
+             exact-nonnegative-integer?
+             exact-nonnegative-integer?
+             exact-nonnegative-integer?
+             void?)]{
+  Returns the callback that is invoked when redrawing the splash screen.                    
+}
+@defproc[(set-splash-paint-callback
+          [cb
+           (-> (is-a?/c dc<%>) 
+               exact-nonnegative-integer?
+               exact-nonnegative-integer?
+               exact-nonnegative-integer?
+               exact-nonnegative-integer?
+               void?)])
+         void?]{
+  Sets the callback that is invoked when redrawing the splash screen. See @racket[start-splash] for
+  what the arguments are.
+}
+@defproc[(set-splash-progress-bar?! [b boolean?]) void?]{
+  Calling this procedure with @racket[#f] removes the progress bar from the splash screen.
+  Useful in conjunction with setting your own paint callback for the splash screen that measures
+  progress in its own way, during drawing. DrRacket uses this on King Kamehameha and Prince
+  Kuhio day.
+}
+@defproc[(set-splash-char-observer [obs (-> (is-a?/c key-event%) any)]) void?]{
+  Sets a procedure that is called whenever a user types a key with the splash screen as the focus.
+}
+@defproc[(set-splash-event-callback [obj (-> (is-?/c mouse-event%) any)]) void?]{
+  Sets a procedure that is called whenever a mouse event happens in the splash canvas.                                             }
+@defproc[(get-splash-event-callback) (-> (is-?/c mouse-event%) any)]{
+  Returns the last procedure passed to @racket[set-splash-event-callback] or @racket[void], if
+  @racket[set-splash-event-callback] has not been called.
+}
+@defproc[(set-refresh-splash-on-gauge-change?! [proc (-> exact-nonnegative-integer? 
+                                                         exact-nonnegative-integer? 
+                                                         any)]) 
+         void?]{
+  Sets a procedure that is called each time the splash gauge changes. If the procedure returns a true value (i.e., not @racket[#f]),
+  then the splash screen is redrawn. The procedure is called with the current value of the gauge and the maximum value.
+  
+  The default function is @racket[(lambda (curr tot) #f)].
+}
+@defproc[(get-splash-width) exact-nonnegative-integer?]{Returns the width of the splash drawing area / bitmap. See @racket[start-splash] for the details of the size and how things are drawn.}
+@defproc[(get-splash-height) exact-nonnegative-integer?]{Returns the width of the splash drawing area / bitmap. See @racket[start-splash] for the details of the size and how things are drawn.}
+@defproc[(refresh-splash) void?]{
+  Triggers a refresh of the splash, handling the details of double buffering
+  and doing the drawing on the splash's
+  @tech[#:doc '(lib "scribblings/gui/gui.scrbl") #:key "eventspace"]{eventspace's}
+  main thread.                                 
+}