Documentation for the sb-world teachpack

The animation functions we'll use this semester are defined in the sb-world teachpack, which again doesn't come standard with DrScheme but can be installed using "Install .plt file..." and the URL http://home.adelphi.edu/sbloch/class/160/sb-world.plt. You should only have to do this once on your home computer, but this file may not be on the lab machines.

run-animation : number (width) number (height) world (initial) number (tick-length) handler ... -> true

This is the main function that runs an animation. You specify the width and height of the animation window, the initial "world" or "model", the number of seconds between clock ticks, and perhaps some handlers (see below). For example,
(run-animation 500 300 "blerg" 10 (on-tick do-this) (on-key do-that) (on-redraw do-the-other))
where do-this, do-that, and do-the-other are functions you've provided. Note that in this example the "world" is a string; it could equally well have been an image, a number, or something else, as long as your handlers all agree on what type it is.

If you provide more than one of a particular kind of handler, you'll get an error message. If you don't provide a tick handler, a key handler, or a mouse handler, the animation will ignore tick events, keyboard events, or mouse events respectively. If you don't provide a redraw handler, the animation will assume that the "world" is an image, and this image itself should be displayed every time the screen refreshes.

end-of-time : string or symbol -> world

A function you can call to end the animation. Normally, you'll call it in one of your handler functions in response to some event that you've decided should cause the animation to end, but you can also call it in the Interactions pane to stop a running animation.

nw:rectangle : number (width) number (height) mode color -> scene

A "scene" is a kind of image whose pinhole is at the top left so it's easier to place other images at specified coordinates on it. This function acts just like rectangle, but puts the pinhole at the top left corner. You're more likely to need...

empty-scene : number (width) number (height) -> scene

A solid white nw:rectangle. You'll probably use this in combination with...

place-image : image number (x) number (y) scene -> scene

This function places the specified image at the specified coordinates in the scene. It's almost the same as overlay/xy except that

1. it expects the background scene to be the last argument rather than the first, and the foreground to be the first argument rather than the last, and
2. if the resulting scene overlaps the edges of the original scene, this function trims it to be the same size as the original scene.

For example,
(place-image calendar 30 50 (empty-scene 200 150))
would place a calendar centered at position (30,50) within a blank rectangle 200 pixels wide by 150 pixels high.

on-tick : (world -> world) -> handler

Takes in a function (whose contract must be world -> world) and tells run-animation that it is to be called at every clock tick.

on-redraw : (world -> image) -> handler

Takes in a function (whose contract must be world -> image) and tells run-animation that it is to be called whenever the screen needs to be redrawn.

on-key : (world char-or-symbol -> world) -> handler

Takes in a function (whose contract must be world char-or-symbol -> world) and tells run-animation that it is to be called whenever a key is pressed or released on the keyboard.

When a key is typed, you'll get at least two key events: one with the key itself, and one with the symbol 'release when the key is released. (You may get more than two events, if the user holds down the key long enough for it to repeat.)

For regular keys (letters, numbers, punctuation marks) you'll get the obvious character, such as #\A, #\B, ... #\a... #\0, #\:, etc. Other than that, the most likely keys you'll be interested in are the arrow keys, which you'll get as one of the following symbols:
'left 'right 'up 'down 'home 'end 'next 'prior.
For function keys, you'll get one of the symbols 'f1 'f2 'f3 ...
For the numeric keypad, you'll get one of the symbols 'decimal 'add 'subtract 'multiply 'divide 'numpad0 'numpad1 ... 'numpad9

on-mouse : (world num num symbol -> world) -> handler

Takes in a function (whose contract must be world number number symbol -> world) and tells run-animation that it is to be called whenever anything interesting happens to the mouse. The two numbers are the x and y coordinates of the mouse respectively, and the symbol tells you what happened. The possible symbols are

'enter	the mouse has entered the animation window
'leave	the mouse has left the animation window
'button-down	the user has pressed (but not yet released) a mouse button
'button-up	the user has released a mouse button
'move	the mouse has moved, without a button pressed
'drag	the mouse has moved, with a button pressed
'wheel-up	the user has rolled the scroll wheel up
'wheel-down	the user has rolled the scroll wheel down

char->string : character -> string

Converts a character to a string of length one. Intended for use in key handlers.