Peg Solitaire tutorial

This is an old revision of Peg Solitaire tutorial, edited by Eny at . The current revision is 74923.

/* It's all about events */

Template:Newpage

This tutorial is the second Lazarus tutorial that aims at introducing the basics of Lazarus application development. It's best to start this tutorial after having finished the first one (Howdy_World_(Hello_World_on_steroids)). This tutorial exlpains a bit about how to work with graphics and how to make a program modular. The final product of this tutorial is a basic but working version of the Peg Solitaire game (http://en.wikipedia.org/wiki/Peg_solitaire). If all goes well in the end it will look something like this:

Start the project

As mentioned in the previous tutorial it's best to start with a clean, separate directory for each project. A quick recap:

And extra for this project:

First steps

It's always a good idea to seperate gui related code from data structure definitions. So the first step will be the creation of a separate unit for our Solitaire data structures.

The basic elements of a Peg Solitaire board are the marbles, the board structure and the empy places. We'll simulate this by a simple matrix that has cells of a certain type (empty, occupied and not accessible). And we'll encapsulate all this in a class that handles all the data manipulation.

<Delphi>const

 C_MAX = 7;  // Max board size: 7x7

type

 TCellNums = 1..C_MAX;
 TCellType = (ctNoAccess, ctEmpty, ctPeg);
 TPegCells = array[TCellNums, TCellNums] of TCellType;
 TPegSolitaire = class
 private
   Size: TCellNums;
   PegCells: TPegCells;
 public
   constructor Create(const pSize: TCellNums);
 end;</Delphi>

It's fair to assume that other code that is going to use this class needs access to the cells contents (i.e. PegCells). The way to handle this is either by defining a set of functions to access the cells or define a so called array property. Let's go for the latter approach and add the following line to the public section of the TPegSolitaire class: <Delphi>property Cell[const pRow, pCol: TCellNums]: TCellType;</Delphi>

<Delphi>result := PegCells[pRow,pCol]</Delphi>

<Delphi>PegCells[pRow,pCol] := pValue</Delphi>

<Delphi>var iRow,iCol: integer; begin

 // Store the size of the board locally
 Size := pSize;
 // Initialize all cells to 'not accessible'
 for iRow := 1 to C_MAX do
   for iCol := 1 to C_MAX do
     Cell[iRow,iCol] := ctNoAccess;</Delphi>

Now that the basic data structure is in place, let's have a look at the graphics we are going to need. There are many ways to display a solitaire board. We are going to use a paintbox. That will give us full control over the graphic features that Lazarus gives us out of the box.

Our main form is going to use the data structure we defined in the PegDatastructure file.

<Delphi>uses

 PegDatastructures,
 Classes, SysUtils, FileUtil, Forms, Controls, Graphics, Dialogs;</Delphi>

Next step is to draw the cells matrix on this paintbox by splitting it in rows and columns that will contain each cell of the board. To make it scaleable we'll calculate the width and height independantly. We'll need a couple of variables to hold the results. First the width and height of the cells, so all cells (7) fit exactly on the form. We'll develop the painting code interactively and we are going to use the button that was dropped on the form for that.

<Delphi>var

 CellWidth : integer;
 CellHeight: integer;</Delphi>

We'll need some extra variables to hold intermediate results:

<Delphi> iRow, iCol : TCellNums;

 CellArea: TRect</Delphi>

CellArea is used to limit the rectangular area on screen where a cell will be drawn.

To process all rows and cols two straightforward for loops will do.

<Delphi> // Calculate the width/height of each cell to accomodate for all cells in the paintbox

 CellWidth := pbPeg.Width div 7;
 CellHeight := pbPeg.Height div 7;
 // Draw boxes for all cells
 for iRow := 1 to 7 do
   for iCol := 1 to 7 do
   begin
     // Calculate the position of the cell in the paintbox
     CellArea.Top    := (iRow-1) * CellHeight;
     CellArea.Left   := (iCol-1) * CellWidth;
     CellArea.Right  := CellArea.Left + CellWidth;
     CellArea.Bottom := CellArea.Top  + CellHeight;
     // And now draw the cell
     pbPeg.Canvas.Rectangle(CellArea);
   end;</Delphi>

A Canvas, as it's name suggests, is a control (a drawing surface) that helps us drawing things like lines, rectangles, circles etc. A paintbox control has an embedded canvas. Therefore the line pbPeg.Canvas.Rectangle(CellArea) will draw a rectangle on the paintbox, limited to the area defined in CellArea. And because the paintbox is placed on the form, we can see the result there.

This proves that our calculations were spot on and that we now have the means to draw whatever is necessary in the right spot. One thing needs to be done though before adding more drawing functionality. Drawing of the cells has no relation with the main form whatsoever (or any form for that matter). The only thing we need for drawing things is a Canvas and some measurements for the cells. So we are going to create a supporting class to clean up the main form.

<Delphi>type

 TPegSolPainter = class
 private
   PegSol      : TPegSolitaire;
   Canvas      : TCanvas;
 public
   constructor Create(pPegSol: TPegSolitaire; pCanvas: TCanvas);
 end;</Delphi>

Note that a TPegSolitaire variable is also added, because obviously we are going to use that class to retrieve a cells' state.

<Delphi>constructor TPegSolPainter.Create(pPegSol: TPegSolitaire; pCanvas: TCanvas); begin

 PegSol := pPegSol;
 Canvas := pCanvas;

end;</Delphi>

Trying to compile this code will failse because we haven't added the PegDatastrucures unit to the uses section. And because we use a TCanvas we'll have to add the Graphics unit as well.

<Delphi>uses

 PegDatastructures,
 Graphics,
 Classes, SysUtils; </Delphi>

The reason we built this class was to remove all drawing and painting code from the form. So we need to create a method that will do the drawing. Before adding that method there is something that needs to be addressed: to calculate the width of a cell, we divide the paintbox width by the number of cells. In theory we could use the property Canvas.Width for this. However that property does not always give us the right width at the right time. So to be able to draw cells, we must provide our draw method with the correct values for the width and height of the canvas.

Now we now this, we can add a paint method to our class.

<Delphi> TPegSolPainter = class

 private
   PegSol      : TPegSolitaire;
   Canvas      : TCanvas;
 public
   constructor Create(pPegSol: TPegSolitaire; pCanvas: TCanvas);
   procedure Repaint(const pCanvasWidth, pCanvasHeight: integer);
 end;

</Delphi>

<Delphi>procedure TPegSolPainter.Repaint(const pCanvasWidth, pCanvasHeight: integer); var

 CellWidth    : integer;
 CellHeight   : integer;
 iRow, iCol   : TCellNums;
 CellArea     : TRect;

begin

 // Calculate the width of each cell to accomodate for all cells
 CellWidth := pbPeg.Width div 7;
 CellHeight := pbPeg.Height div 7;
 // Draw boxes for all cells
 for iRow := 1 to 7 do
   for iCol := 1 to 7 do
   begin
     // Calculate the position of the cell in the paintbox
     CellArea.Top    := (iRow-1) * CellHeight;
     CellArea.Left   := (iCol-1) * CellWidth;
     CellArea.Right  := CellArea.Left + CellWidth;
     CellArea.Bottom := CellArea.Top  + CellHeight;
     // And now draw the cell
     pbPeg.Canvas.Rectangle(CellArea);
   end;

end;</Delphi>

Because we no longer need the paintbox pbPeg we must remove the references to it. Three changes are needed:

<Delphi> // Calculate the width of each cell to accomodate for all cells

 CellWidth := pCanvasWidth div 7;
 CellHeight := pCanvasHeight div 7;</Delphi>

<Delphi> // And now draw the cell

     Canvas.Rectangle(CellArea);</Delphi>

Now that we have a class that can do the fancy painting for us, it's time to make use of it. We are going to use this paint class together with the PegSolitare class to draw the cells.

<Delphi>procedure TfrmMain.Button1Click(Sender: TObject); var

 pegsol  : TPegSolitaire;  // The game data
 pegpaint: TPegSolPainter; // The paint class for the game

begin end;</Delphi>

To use the paint class is fairley straightforward: create a new instance and call the repaint method like so:

<Delphi> // Create a new game object

 pegsol := TPegSolitaire.Create(7);
 // Create a new painter object to paint this game
 pegpaint := TPegSolPainter.Create(pegsol, pbPeg.Canvas);
 // And paint the board
 pegpaint.Repaint(pbPeg.Width, pbPeg.Height);
 // Clean up
 pegpaint.Free;
 pegsol.Free</Delphi>

Run and test the program to see that it works exactly as before. The result will look something like this:

It's all about events

What have we accomplished so far? There is a datastructure that holds all the data for a Peg Solitaire game, there is a class that can paint on a Canvas and we have a fairly simple form with a test button. So what's next? Events!

As we have seen in the previous section, the cell matrix we painstakingly drew wasn't to last. This happens because the form doesn't know anything about our little game. As soon as the form thinks it's time to redraw itself, it does so and ignores our cell grid. What it dóes do is send a message to it's child controls that a refresh is necessary. This message is available to us in the form of an event: a Paint event.

This event is 'fired' everytime the paintbox needs to redraw it's surface. That is the place were we are going to do our drawing.

<Delphi>procedure TfrmMain.pbPegPaint(Sender: TObject); var

 pegsol  : TPegSolitaire;  // The game data
 pegpaint: TPegSolPainter; // The paint class for the game

begin

 // Create a new game object
 pegsol := TPegSolitaire.Create(7);
 // Create a new painter object to paint this game
 pegpaint := TPegSolPainter.Create(pegsol, pbPeg.Canvas);
 // And paint the board
 pegpaint.Repaint(pbPeg.Width, pbPeg.Height);
 // Clean up
 pegpaint.Free;
 pegsol.Free

end;</Delphi>

Now what is clear is that we create a game object in the OnPaint method, paint the empty cells and then destroy it. But we need to store the game object until a game has finished. The same goes for the paint object. So the OnPaint event is not the most logical place to create these objects. The form's class declaration is a better place to store them.

<Delphi> TfrmMain = class(TForm)

   pbPeg: TPaintBox;
   procedure pbPegPaint(Sender: TObject);
 private
   { private declarations }
   pegsol  : TPegSolitaire;  // The game data
   pegpaint: TPegSolPainter; // The paint class for the game
 public
   { public declarations }
 end; </Delphi>

These variables must be initialized as soon as the form opens (or anytime we want to start a new game). So let's create a procedure that does that for us and add it to the private section of the form.

<Delphi> private

   { private declarations }
   pegsol  : TPegSolitaire;  // The game data
   pegpaint: TPegSolPainter; // The paint class for the game
   procedure StartNewGame;</Delphi>

<Delphi>procedure TfrmMain.StartNewGame; begin

 // Clean up the previous game
 pegpaint.Free;
 pegsol.Free;
 // Start with a new game
 pegsol := TPegSolitaire.Create(7);
 pegpaint := TPegSolPainter.Create(pegsol, pbPeg.Canvas);

end;</Delphi>

Now that the initialization code is created, it must be executed. A logical time to do this is as soon as the form is created (i.e. the application is started). For this another event is available to us: the FormCreate event. We can create it in two ways: find the OnFormCreate event in the Object Inspector and click on the '...' button. But another way to generate it is double clicking the form itself.

<Delphi>procedure TfrmMain.FormCreate(Sender: TObject); begin

 StartNewGame

end;</Delphi>

Now that the game and paint objects are created at program start, they are no longer required in the OnPaint method.

<Delphi>procedure TfrmMain.pbPegPaint(Sender: TObject); begin

 // Paint the board
 pegpaint.Repaint(pbPeg.Width, pbPeg.Height);

end; </Delphi>

Intermezzo