On this page:
big-bang
on-tick-event
key-event?
key=?
on-key-event
on-mouse-event
on-redraw
stop-when
Version: 4.1.2.4

3 Interactions

An animation starts from a given “world” and generates new ones in response to events on the computer. This teachpack keeps track of the “current world” and recognizes three kinds of events: clock ticks; keyboard presses and releases; and mouse movements, mouse clicks, etc.

Your program may deal with such events via the installation of handlers. The teachpack provides for the installation of three event handlers: on-tick-event, on-key-event, and on-mouse-event. In addition, it provides for the installation of a draw handler, which is called every time your program should visualize the current world.

The following picture provides an intuitive overview of the workings of "world".

The big-bang function installs World_0 as the initial world; the callbacks tock, react, and click transform one world into another one; done checks each time whether the world is final; and draw renders each world as a scene.

World any/c

For animated worlds and games, using the teachpack requires that you provide a data definition for World. In principle, there are no constraints on this data definition. You can even keep it implicit, even if this violates the Design Recipe.

(big-bang width height r world0)  true
  width : natural-number/c
  height : natural-number/c
  r : number?
  world0 : World
(big-bang width height r world0 animated-gif?)  true
  width : natural-number/c
  height : natural-number/c
  r : number?
  world0 : World
  animated-gif? : boolean?

Creates and displays a width x height canvas, starts the clock, makes it tick every r seconds, and makes world0 the current world. If it is called with five instead of four arguments and the last one (animated-gif?) is true, the teachpack allows the generation of images from the animation, including an animated GIF image.

(on-tick-event tock)  true
  tock : (-> World World)

Tell DrScheme to call tock on the current world every time the clock ticks. The result of the call becomes the current world.

KeyEvent (or/c char? symbol?)

A KeyEvent represents key board events, e.g., keys pressed or released, by the computer’s user. A char? KeyEvent is used to signal that the user has hit an alphanumeric key. Symbols such as 'left, 'right, 'up, 'down, 'release denote arrow keys or special events, such as releasing the key on the keypad.

(key-event? x)  boolean?
  x : any

is x a KeyEvent

(key=? x y)  boolean?
  x : key-event?
  y : key-event?

compares two KeyEvent for equality

(on-key-event change)  true
  change : (-> World key-event? World)

Tell DrScheme to call change on the current world and a KeyEvent for every keystroke the user of the computer makes. The result of the call becomes the current world.

Here is a typical key-event handler:

  (define (change w a-key-event)
    (cond
      [(key=? a-key-event 'left)  (world-go w -DELTA)]
      [(key=? a-key-event 'right) (world-go w +DELTA)]
      [(char? a-key-event) w] ; to demonstrate order-free checking
      [(key=? a-key-event 'up)    (world-go w -DELTA)]
      [(key=? a-key-event 'down)  (world-go w +DELTA)]
      [else w]))

MouseEvent (one-of/c 'button-down 'button-up 'drag 'move 'enter 'leave)

A MouseEvent represents mouse events, e.g., mouse movements or mouse clicks, by the computer’s user.

(on-mouse-event clack)  true
  clack : (-> World natural-number/c natural-number/c MouseEvent World)

Tell DrScheme to call clack on the current world, the current x and y coordinates of the mouse, and and a MouseEvent for every action of the mouse by the user of the computer. The result of the call becomes the current world.

(on-redraw to-scene)  true
  to-scene : (-> World Scene)

Tell DrScheme to call to-scene whenever the canvas must be redrawn. The canvas is usually re-drawn after a tick event, a keyboard event, or a mouse event has occurred. The generated scene is displayed in the world’s canvas.

(stop-when last-world?)  true
  last-world? : (-> World boolean?)

Tell DrScheme to call last-world? whenever the canvas is drawn. If this call produces true, the clock is stopped; no more tick events, KeyEvents, or MouseEvents are forwarded to the respective handlers. As a result, the canvas isn’t updated either.

Example: The following examples shows that (run-simulation 100 100 (/ 1 28) create-UFO-scene) is a short-hand for three lines of code:

  (define (create-UFO-scene height)
    (place-image UFO 50 height (empty-scene 100 100)))
  
  (define UFO
    (overlay (circle 10 'solid 'green)
             (rectangle 40 4 'solid 'green)))
  
  (big-bang 100 100 (/1 28) 0)
  (on-tick-event add1)
  (on-redraw create-UFO-scene)

Exercise: Add a condition for stopping the flight of the UFO when it reaches the bottom.