suzanne.soy/gui
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

added docs for the splash screen library in the framework

Browse Source 
original commit: 12ab498977f9f481187643c47ed6710c8a572d5b
This commit is contained in:
Robby Findler 2010-09-01 12:52:43 -05:00
parent abc2561579
commit 1947ad1240
3 changed files with 137 additions and 2 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
collects/framework/splash.rkt
View File

@ -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) '()))))

9
collects/scribblings/framework/framework.scrbl
View File

@ -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"]

126
collects/scribblings/framework/splash.scrbl Normal file
View File

@ -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.
}