Open the project spirals/ping_pong_01. The goal of this spiral is to display a small, black circle and a small, white rectangle with a black border; in other words, to learn how to draw. Take a look at the HTML file—all drawing is done within the <canvas> tag:

<canvas id="canvas" width="300" height="300">
  Canvas is not supported in your browser.
</canvas>

Adjusting the width and height values to the app's needs, you can also include text that which will be displayed in older browsers that do not support canvas (it is widely supported, but only in Internet Explorer from 9.0 onwards). Now we look at the code of ping_pong.dart in the following spiral:

library ping_pong;               (1)

import 'dart:html';
import 'dart:math';

part 'board.dart';               (2)

void main() {
  //get a reference to the canvas
  CanvasElement canvas = querySelector('#canvas');           (3)	
  Board board = new Board(canvas);         (4)
  board.circle(75, 75, 10);           (5)
  board.rectangle(95, 95, 20, 20);         (6)
}

Following good practice, we make our app a library in line (1). The file containing the library declaration contains the starting point main(); all other code resides in other parts (see line (2)). In line (3), we make a reference to <canvas> using an object of the type CanvasElement (in dart:html). Then, we have to make a context object (which can be either 2d or webgl (3d)) to draw on:

CanvasRenderingContext2D context = canvas.getContext('2d'),

In this app, we will draw on a Board object made in line (4); this object has the methods circle and rectangle that contain the details for drawing these shapes and they are called in lines (5) and (6). Line (4) passes the canvas object to the Board constructor (line (7)) in the part file board.dart, where the context object is created:

part of ping_pong;
class Board {
  CanvasRenderingContext2D context;
  Board(CanvasElement canvas) {          (7)
    context = canvas.getContext('2d'),
  }
  //draw a circle
  void circle(x, y, r) {
    context.beginPath();            (8)
    context.arc(x, y, r, 0, PI*2, true);      (9)
    context.closePath();            (10)
    context.fill();            (11)
  }
  //draw a rectangle
  void rectangle(x, y, w, h) {
    context.beginPath();
    context.rect(x,y,w,h);          (12)
    context.closePath();
    context.stroke();            (13)
  }
}

When drawing an arbitrary shape, we draw, in fact, a path. This usually involves a number of steps enclosed within a call to beginPath() (line (8)) and a call to closePath() (line (10)); this also closes the shape; when drawing basic shapes, such as lines, rectangles, and circles, as in this example, they can be left out. A black line or an open figure is drawn using context.stroke(), such as in line (13); for a filled-in shape, you need to use context.fill(), such as in line (13). When we run this script, it shows:

The screen of Ping Pong spiral 1

To further explore how lines and arcs are drawn, we create an additional web app canvas_1:

import 'dart:html';
import 'dart:math';
CanvasRenderingContext2D context;
var width, height;
void main() {
  //get a reference to the canvas
  CanvasElement canvas = querySelector('#canvas'),
  width = canvas.width;              (1)
  height = canvas.height;
  context = canvas.getContext('2d'),
  lines();
  arcs();
}
//drawing lines
void lines() {
  context.moveTo(100, 150);
  context.lineTo(450, 50);
  context.lineWidth = 2;
  context.lineCap = 'round'; // other values: 'square' or 'butt'
  context.stroke();
}
//drawing arcs
void arcs() {
  var x = width / 2;            (2)
  var y = height / 2;
  var radius = 75;
  var startAngle = 1.1 * PI;
  var endAngle = 1.9 * PI;
  var antiClockWise = false;
  context.arc(x, y, radius, startAngle, endAngle, antiClockWise);
  context.lineWidth = 8;
  context.stroke();
}

We obtain the width and height parameters of the canvas object (line (1)) in order to draw proportionally to the space that we have, for example, in choosing the center of a circle (for our arc), such as in line (2).

Canvas uses an (x, y) coordinate system, measured in pixels to locate points: the origin (0,0) is the upper-left corner of the drawing area, the x axis goes from left to right, and the y axis from top to bottom. moveTo(x, y) positions the drawing cursor at the point (x, y) method and the lineTo(x', y') method draws a straight line from (x, y) to (x', y') when the stroke or fill methods are called; lineWidth is an obvious property. To draw a circular arc, you use the method with the same name arc; this method takes no less than six parameters: context.arc(x, y, radius, startAngle, endAngle, antiClockWise); x and y are the coordinates of the circle's center; the third parameter is the circle's radius; parameters startAngle and endAngle are the start and end angles (in radians); the parameter antiClockWise is true or false (the default value is anticlockwise, that is from end to start) and defines the direction of the arc between its two end points: see the next figure for clarification and the example in the arcs() method (comment out the call to lines()). Now we see how a circle can be drawn by going from a 0 PI angle to a 2 PI angle, such as in the board.dart line (9), which is called using line (5).

Drawing an arc

Using the lineTo method, it takes three calls to draw a triangle and four for a rectangle. The latter case was considered common enough to provide a rect(x,y,w,h) method (line (12) in board.dart), where x and y are the coordinates of the upper-left corner, w is the width, and h is the height of the rectangle; this is applied in the rectangle() method called on board (line (6)).To erase all drawing in a rectangular area, use the context.clearRect(x,y,w,h) method (first used in Spiral 3 – moving a ball).

In the project spirals/ping_pong_02, the goal is to display two circles and two rectangles in different colors; that is: how can we get some color in our drawing? For that, we need two new properties: context: strokeStyle sets the drawing color for the border and fillStyle sets the fill color; if you do not use these, black is the default color. The color itself is given as a string, containing:

For example, a rectangle method can be given a border color and an inside color by calling:

  board.rectangle(15, 150, 120, 120,
        
"rgba(55, 55, 0, .75)", "rgba(155, 155, 0, .5)");
while the rectangle method is now changed to:
void rectangle(x, y, w, h, strokeStyle, fillStyle) {
    context.beginPath();
context.strokeStyle = strokeStyle;
context.fillStyle = fillStyle;
    context.rect(x,y,w,h);
    context.stroke();
    context.fill();
    context.closePath();
  }

Do experiment with the possibilities.

We now know everything we need to draw our Ping Pong game; we'll start doing this and developing the game logic in the next spiral. But, often, you need other techniques in drawing applications: you'll find more of them in canvas_2.dart To see clearly what each code section does, comment all code and uncomment only the section you want to run. In this code file, you can find the methods for drawing quadratic curves and Bezier curves, combining them in paths, custom shapes, linear and radial gradients, and drawing images and text. For more details on the different parameters, refer to http://www.html5canvastutorials.com/tutorials. You can find a lot more code examples in the GitHub repository git at http://github.com/dzenanr/ondart_examples especially the folders ondart_dom, ondart_html5, and ondart_canvas; these accompany the course presentations found at http://ondart.me/web_programming.md.

In the project spirals/ping_pong_03, the goal is to change the position of a small, black circle (a ball) in a straight line using subsequent calls of the move method.

Run the app: we see a ball moving down diagonally from the upper-left corner to the right and then disappearing out of sight. In the main file ping_pong.dart, nothing much has changed; a new part file ball.dart has appeared (line (1)). To describe the ball and its behavior in the Ball class; and; in line (2), the ball object is created, giving it a reference to the board object.

library ping_pong;
import 'dart:html';
import 'dart:async';
import 'dart:math';
part 'board.dart';
part 'ball.dart';            (1)
void main() {
  CanvasElement canvas = querySelector('#canvas'),
  Board board = new Board(canvas);
  Ball ball = new Ball(board, 0, 0, 10);        (2)
  new Timer.periodic(const Duration(milliseconds: 10), (t) => ball.move());              (3)
}

In ball.dart, we see that in the constructor (line (4)), our ball is drawn by calling context.arc on the board object.

part of ping_pong;
class Ball {
  Board board;
  int x, y, r;
  int dx = 2;
  int dy = 4;
  Ball(this.board, this.x, this.y, this.r) {        (4)
    draw();
  }
  void draw() {
    board.context.beginPath();
    board.context.arc(x, y, r, 0, PI*2, true);
    board.context.closePath();
    board.context.fill();
  }
  void move() {
    board.clear();            (5)
    board.context.beginPath();
    board.context.arc(x, y, r, 0, PI*2, true);
    board.context.closePath();
    board.context.fill();
    x += dx;            (6)
    y += dy;            (7)
  }
}

In (line (3)) in the main() method in the preceding code, a Timer invokes periodically the move() method on the ball. In the move() method, the board is first cleared (line (5)). Within the clear() method, this is done through a new clearRect() method on the context object:

void clear() {
    context.clearRect(0, 0, width, height);
}

In lines (6) and (7), the values of the x and y coordinates of the center of the ball are increased using dx and dy respectively. As these remain the same, the ball runs from left to right and top to bottom; it disappears when it leaves the canvas area determined by the width and height parameters. We will improve on this in Spiral 5 – a bouncing ball; for now, let's give the board object the same dimensions as the canvas element:

Board(CanvasElement canvas) {
    context = canvas.getContext("2d");
    width = canvas.width;
    height = canvas.height;
}

In this spiral, we pause and reorganise (refactor) our code a bit (we wrote duplicate code in draw() and move()—horror!). In our main() method, we now only create the board object, and call a new method init() on it:

void main() {
  CanvasElement canvas = querySelector('#canvas'),
  Board board = new Board(canvas);
  board.init();
}

This method in board.dart creates the ball object, passing it as a reference to the board object using the this parameter:

  void init() {
    Ball ball = new Ball(this, 0, 0, 10);
    new Timer.periodic(const Duration(milliseconds: 10), (t) =>   
  }

The common code in draw() and move() from the Spiral 3 – moving a ball section is eliminated by letting move() call draw() from ball.dart:

  void draw() {
    board.context.beginPath();
    board.context.arc(x, y, r, 0, PI*2, true);
    board.context.closePath();
    board.context.fill();
  }
  void move() {
    board.clear();
    draw();
    x += dx;
    y += dy;
  }

We have applied a fundamental principle called DRY (Don't Repeat Yourself, at least not in code).

In most games, the ball has to stay on the board, so let's try to bounce the ball on the board's edges. The code that lets the ball move is the move() method, so that is the only code that has to expand. For both coordinates, we now have to check the boundary that the ball will cross on the board's edge lines:

Verify that this procedure works (although the movement is rather boring at this stage).

In this spiral, we add a racket that is displayed as a small, black rectangle. From the beginning of the code, we represent it through its own class in racket.dart. In it, we provide a constructor and the draw method that uses context.rect; the racket also has a reference to the board object.

part of ping_pong;
class Racket {
  Board board;
  num x, y, w, h;
  Racket(this.board, this.x, this.y, this.w, this.h) {
    draw();
  }
  void draw() {
    board.context.beginPath();
    board.context.rect(x, y, w, h);
    board.context.closePath();
    board.context.fill();
  }
}

To enhance the adaptability of the game, we start by defining a number of constant values upfront in the Board class:

 const num START_X = 0;
 const num START_Y = 0;
 const num BALL_R = 10;
 const num RACKET_W = 75;
 const num RACKET_H = 10;

These are used in the init() method to construct the ball and racket objects:

void init() {
    ball = new Ball(this, START_X, START_Y, BALL_R);
    racket = new Racket(this, width/2, height-RACKET_H, RACKET_W,RACKET_H);
       timer = new Timer.periodic(const Duration(milliseconds: 10),
             (t) => redraw());
   }

Since we now have to draw two objects, we rename the periodic function to redraw() and give the responsibility to the board object, which calls the draw methods on the ball and racket objects (lines (1) and (2)).

void redraw() {
    clear();
    ball.draw();              (1)
    racket.draw();            (2)
    if (ball.x + dx > width || ball.x + dx < 0) {
      dx = -dx;
    }
    if (ball.y + dy > height || ball.y + dy < 0) {
      dy = -dy;
    } else if (ball.y + dy > height) {        (3)
      if (ball.x > racket.x && ball.x < racket.x + racket.w) {
        dy = -dy;
      } else {
        timer.cancel();
      }
    }
    ball.x += dx;
    ball.y += dy;
  }

It also does all the checks for the boundary conditions and we add in line (3) that the ball is bounced (dy = -dy) only when it touches the racket (ball.x > racket.x && ball.x < racket.x + racket.w); if it falls outside the racket, the game is over and we cancel the timer, stopping the animation (line (4)). Due to the start location of the ball, the game-over condition does not occur in this spiral.

Here, the goal is to move the racket using the left and right keys of the keyboard. To this end, the racket will have to listen to key events; the following is the code of racket.dart:

part of ping_pong;
class Racket {
  Board board;
  num x, y, w, h;
  bool rightDown = false;            (1)
  bool leftDown = false;
  Racket(this.board, this.x, this.y, this.w, this.h) {
    draw();
    document.onKeyDown.listen(_onKeyDown);        (2)
    document.onKeyUp.listen(_onKeyUp);  
  }
  void draw() { ... } // see Spiral 6
  _onKeyDown(event) {            (3)
    if (event.keyCode == 39) rightDown = true;
    else if (event.keyCode == 37) leftDown = true;  
  }
  _onKeyUp(event) {              (4)
    if (event.keyCode == 39) rightDown = false;
    else if (event.keyCode == 37) leftDown = false;  
  }
}

In line (2), we register for the KeyDown event and attach the handler _onKeyDown, which is also done in the following line for the KeyUp event. _onKeyDown and _onKeyUp are private methods that could have been used anonymously in the event definition. In these handlers, we test for the keyCode of the pressed key: the left arrow has keyCode 37 and the right arrow 39. We catch their state in two Boolean variables leftDown and rightDown: if the left arrow is pressed, we set leftDown to true and, when the right arrow is pressed, we set rightDown to true (line (3)). In the KeyUp event handler in line (4) that fires when the key is released, the boolean is reset to false. As long as the arrow key is pressed, its corresponding boolean is true. This is tested in the redraw() method of the Board class, where the following lines are added before racket.draw():

    if (racket.rightDown)     racket.x += 5;
    else if (racket.leftDown) racket.x -= 5;

When the right arrow is pressed, the racket moves to the right and vice versa.

This is the first playable version of our game; but, we see that our racket can disappear and, perhaps, we want to be able to move the racket using the mouse as well.

To accomplish moving the racket using the mouse, we listen for a MouseMove event and attach the event handler to the racket constructor: document.onMouseMove.listen(_onMouseMove).

We also define two variables that define the canvas width:

      canvasMinX = 0;
      canvasMaxX = canvasMinX + board.width;

We use the preceding code statements to perform a test in the mouse event handler: if the x coordinate of the mouse pointer (given by event.pageX) is situated in our canvas, set the x coordinate of our racket object to the same value:

  _onMouseMove(event) {
     if (event.pageX > canvasMinX && event.pageX < canvasMaxX)  x = event.pageX;
   }

The goals for this spiral are as follows:

The border is easy; call the border() method from init() to draw a rectangle around the canvas:

   void border() {
        context.beginPath();
        context.rect(X, Y, width, height);
        context.closePath();
        context.stroke();
      }

We add a second racket to the top of the screen, which moves synchronously with the bottom racket. Our board object will now contain two racket objects racketNorth and racketSouth, both of which are created in the init() method:

racketNorth = new Racket(this, width/2, 0, RACKET_W, RACKET_H);
racketSouth = new Racket(this, width/2, height-RACKET_H, RACKET_W, RACKET_H);

The code from Spiral 7 – moving the racket using keys is applied to both the objects.

The third goal is accomplished by adding a test to the MouseMove event handler:

  _onMouseMove(event) {
        if (event.pageX > board.X && event.pageX < board.width) {
          x = event.pageX - board.X - w/2;
          if (x < board.X) x = board.X;
          if (x > board.width - w) x = board.width - w;
        }
  }

By introducing an X constant for board, we have simplified the condition we saw in Spiral 8 – moving the racket using the mouse. The racket movements are now more synchronous with the mouse movement, and the last two if tests make it impossible for the rackets to go outside the borders of the board. Now we have a minimally decent game.

In this spiral, we add a title and a button to restart the game; both are done in HTML. The button is placed in a <div> tag outside the canvas:

<button type="button" id="play">Play</button>

We now change the constructor of board to only start init() when the button with the ID play is clicked: query Selector('#play').onClick.listen( (e) => init() );

That's it!

No new Dart code is added here, but we improve the display using CSS. Additionally, some relevant web links are added along with a section for each new spiral to indicate what is new. Take a look at ping_pong.html (in both the source and the browser) to learn how to use the document features of HTML5:

The preceding points are shown in the following screenshot:

Ping Pong, the master version

As an exercise, you could decouple the rackets so that we have two independent players and then keep score of the game (see the DOM version of the game for inspiration). Also, place the timer interval in a variable if you want to change the game's difficulty level.