diff --git a/collects/framework/splash.rkt b/collects/framework/splash.rkt index 0357046f..153d868b 100644 --- a/collects/framework/splash.rkt +++ b/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) '())))) diff --git a/collects/scribblings/framework/framework.scrbl b/collects/scribblings/framework/framework.scrbl index 01d2b005..912ebadb 100644 --- a/collects/scribblings/framework/framework.scrbl +++ b/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"] diff --git a/collects/scribblings/framework/splash.scrbl b/collects/scribblings/framework/splash.scrbl new file mode 100644 index 00000000..d9b58b77 --- /dev/null +++ b/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. +}