146 lines
7.8 KiB
Racket
146 lines
7.8 KiB
Racket
#lang scribble/doc
|
|
@(require scribble/manual
|
|
(for-label framework/splash
|
|
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?
|
|
(is-a?/c bitmap%)
|
|
(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?]
|
|
[#:allow-funny? allow-funny? boolean? #f]
|
|
[#:frame-icon
|
|
frame-icon
|
|
(or/c #f
|
|
(is-a?/c bitmap%)
|
|
(cons/c (is-a?/c bitmap%)
|
|
(is-a?/c bitmap%)))
|
|
#f])
|
|
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 splash screen should
|
|
contain if there is no preference saved for the splash screen width.
|
|
The splash library uses @racket[get-preference] and @racket[put-preferences]
|
|
to store preferences, using
|
|
@racketblock[(string->symbol (format "plt:~a-splash-max-width" splash-title))]
|
|
as the key for the preference. Each time the app starts up, the maximum width
|
|
is reset based on the number of files that were loaded that time.
|
|
|
|
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 it is
|
|
a bitmap, then that bitmap is used directly. 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.
|
|
|
|
The @racket[allow-funny?] argument determines if a special gauge is used on Christmas day.
|
|
|
|
The @racket[frame-icon] is used just like the value of the parameter @racket[frame:current-icon] is used,
|
|
but for the splash screen.
|
|
}
|
|
|
|
@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 real?] [y real?])
|
|
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.
|
|
}
|