SB-world Teachpack

SB-world Teachpack

To install...
(require (planet "install.ss" ("sbloch" "sb-world.plt" 1 0)))
You should need to do this only once, and it'll install an "sb-world.ss" teachpack into the "Add Teachpack" dialogue.

The sb-world teachpack provides a variety of functions for animations.  It's similar to the "world" teachpack shipped with DrScheme, but it has a slightly different (more functional, less imperative) interface.

> (run-animation width height init-model tick-interval handler ...) -> true
This is the most important function in the teachpack.  You give it the width and height of the window (numbers of pixels), the initial model, the number of seconds between clock ticks, and perhaps some "handlers" (see below), and it runs the animation.

> (run-saveable-animation width height init-model tick-interval handler ...) -> true
Just like run-animation, except that it records the sequence of events and allows you to save it as an animated GIF picture.

> (place-image foreground x y background) -> image
Takes in two images (foreground and background), and two numbers (x and y), and positions the foreground image at the specified location on the background image.

> (empty-scene width height) -> image
An easy way to produce a white box, outlined in black, of the specified dimensions.


_Handlers_
When you run an animation, you can provide handler functions to tell the animation how to do various things: how to redraw the screen from the model, how to change the model at every clock tick, how to change the model when the user uses the mouse or keyboard, etc. Once you've written a function to be used as a handler, you specify what kind of handler it is by calling on-redraw, on-tick, on-mouse, on-key, or stop-when, and passing the result to run-animation.

_Redraw handlers_
    You need to write a function with the contract
    model -> image
    and install it with on-redraw. This function will be called every time the model changes. 

_Tick handlers_
    You need to write a function with the contract
    model -> model
    and install it with on-tick. This function will be called every time the clock ticks (at the interval you specified in the fourth argument to run-animation). 

_Mouse handlers_
    You need to write a function with the contract
    model number(x) number(y) symbol(event) -> model
    and install it with on-mouse. This function will be called every time the user clicks, releases, or moves the mouse. 

_Key handlers_

    You need to write a function with the contract
    model char-or-symbol -> model
    and install it with on-key. This function will be called every time the user presses or releases a key on the keyboard. 

_Quit testers_
    An animation can choose when to stop itself. In DrScheme versions 37x, this job is up to the tick, mouse, and key handlers: any one of these can (presumably inside a conditional) call the end-of-time function with a value (typically a string); the animation will end, and that value will be printed out.

> (end-of-time result) -> whatever the result was
Stops the animation from which it was called, and returns the specified value (usually a string, but could be an image, a number, etc.)
Note: This function should only be called from within a tick, mouse, or key handler.  If you call it from run-animation, you've basically stopped the animation before it can start.

    Example:

    (define (dot-at-y y)
        (place-image (circle 3 "solid" "red") 50 y (empty-scene 100 100)))
    (define (sub1-or-bust y)
        (cond [(> y 0) (sub1 y)]
              [else (end-of-time "That's all, folks!")]))
    (run-animation 100 100 100 .1
                   (on-redraw dot-at-y)
    	       (on-tick sub1-or-bust))

_The image teachpack_
Since anyone using this teachpack to do animations will almost certainly want basic image-manipulation as well, this teachpack includes the built-in "image.ss" teachpack; if you have "sb-world" loaded, you don't also need to load "image" (and you're better off not doing so).