Peg Solitaire tutorial: what changed

Revision 1 to 2. Removed lines have a minus sign; added lines have a plus sign.

Old	New		Line
1	1		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 ([1](http://en.wikipedia.org/wiki/Peg_solitaire)). If all goes well in the end it will look something like this:
2	2
3		-	~~<figure>~~
4		-	~~<img src="tutpeg_solitaire.png" title="tutpeg_solitaire.png" />~~
5		-	~~<figcaption>tutpeg_solitaire.png</figcaption>~~
6		-	~~</figure>~~
	3	+	![](/wiki-images/5/5f/Tutpeg_solitaire.png)
7	4
8	5		## Start the project
9	6
10	7		As mentioned in the previous tutorial it's best to start with a clean, separate directory for each project. A quick recap:
11	8
12	9		- Create a new directory for this game.
13	10		- Start a new Application (Project/New Project... and select Application).
14	11		- Save the project as PegSolitaire.
15	12		- Save the main [[TForm\|form]] as ufrmMain.
16	13		- In the object inspector change the form's name to frmMain.
17	14		- Change the caption to Lazarus Peg Solitaire.
18	15		- In the project options insert bin\ in front of the target filename (or bin/ for Linuxes).
19	16
20	17		And extra for this project:
21	18
22		-	~~- Open the project options dialog ( <span class="kbd">Shift</span>+<span class="kbd">Ctrl</span>+ <span class="kbd">F11</span>).~~
	19	+	- Open the project options dialog ( `Shift`+`Ctrl`+ `F11`).
23	20		- Select Compiler Options/Code Generation.
24	21		- Enable Range checking and Overflow error checking (see image belows).
25	22
26		-	~~<figure>~~
27		-	~~<img src="tutpeg_compiler_options.png" title="tutpeg_compiler_options.png" />~~
28		-	~~<figcaption>tutpeg_compiler_options.png</figcaption>~~
29		-	~~</figure>~~
	23	+	![](/wiki-images/1/10/Tutpeg_compiler_options.png)
30	24
31	25		## First steps
32	26
33	27		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\|unit]] for our Solitaire data structures.
34	28
35	29		- From the menu choose File/New Unit.
36	30		- Save the unit as PegDatastructures.pas (and press the lowercase button that pops up).
37	31
38	32		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\|class]] that handles all the data manipulation.
39	33
40	34		- Add the following code to the PegDatastructures unit (after the classes in the [[Uses\|uses]] section and before the [[Implementation\|implementation]] section):
41	35
42	36		``` pascal
43	37		const
44	38		C_MAX = 7; // Max board size: 7x7
45	39
46	40		type
47	41		TCellNums = 1..C_MAX;
48	42		TCellType = (ctNoAccess, ctEmpty, ctPeg);
49	43		TPegCells = array[TCellNums, TCellNums] of TCellType;
50	44
51	45		TPegSolitaire = class
52	46		private
53	47		Size: TCellNums;
54	48		PegCells: TPegCells;
55	49
56	50		public
57	51		constructor Create(const pSize: TCellNums);
58	52		end;
59	53		```
60	54
61	55		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 [[Function\|functions]] to access the cells or define a so called [[Array\|array]] property. Let's go for the latter approach and add the following line to the public section of the TPegSolitaire class:
62	56
63	57		``` pascal
64	58		property Cell[const pRow, pCol: TCellNums]: TCellType;
65	59		```
66	60
67	61		- Position the text cursor on the constructor line.
68		-	- Press <span class="kbd">Ctrl</span>+<span class="kbd">Shift</span>+<span class="kbd">C</span>: the IDE generates the constructor body (as we expected) but it also generates the empty bodies for the 2 [[Method\|methods]] that give us access to PegCells via the Cells property.
	62	+	- Press `Ctrl`+`Shift`+`C`: the IDE generates the constructor body (as we expected) but it also generates the empty bodies for the 2 [[Method\|methods]] that give us access to PegCells via the Cells property.
69	63		- GetCell retrieves data from the private [[Variable\|variable]] PegCells. Add the following code to the [[Function\|function]]:
70	64
71	65		``` pascal
72	66		result := PegCells[pRow,pCol]
73	67		```
74	68
75	69		- SetCell populates the PegCells array with data. Add the following code to the [[Procedure\|procedure]]:
76	70
77	71		``` pascal
78	72		PegCells[pRow,pCol] := pValue
79	73		```
80	74
81	75		- And now finalize the Create [[Constructor\|constructor]]. Add this code to it's body:
82	76
83	77		``` pascal
84	78		var iRow,iCol: integer;
85	79		begin
86	80		// Store the size of the board locally
87	81		Size := pSize;
88	82
89	83		// Initialize all cells to 'not accessible'
90	84		for iRow := 1 to C_MAX do
91	85		for iCol := 1 to C_MAX do
92	86		Cell[iRow,iCol] := ctNoAccess;
93	87		```
94	88
95	89		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.
96	90
97	91		Our main form is going to use the data structure we defined in the PegDatastructure file.
98	92
99	93		- Open the main form's sourcefile.
100	94		- Add PegDatastructures it to the uses list at the top of the file:
101	95
102	96		``` pascal
103	97		uses
104	98		PegDatastructures,
105	99		Classes, SysUtils, FileUtil, Forms, Controls, Graphics, Dialogs;
106	100		```
107	101
108		-	~~- Press <span class="kbd">F12</span> (this will give us the form editor).~~
	102	+	- Press `F12` (this will give us the form editor).
109	103		- From the [[Standard tab\|Standard]] palette choose a [[TButton]] and drop it on the form (in the upper left corner).
110	104		- Change the caption to Test paint.
111	105		- On the [[Additional tab]] select [[TPaintBox]] and drop it on the form.
112	106		- Change Align to alRight.
113	107		- Change BordSpacing.Around to 4.
114	108		- Change Anchors.akLeft to true.
115	109		- Change Name to pbPeg.
116	110		- Resize the form so it looks something like this:
117	111
118		-	~~<figure>~~
119		-	~~<img src="tutpeg_empty.png" title="tutpeg_empty.png" />~~
120		-	~~<figcaption>tutpeg_empty.png</figcaption>~~
121		-	~~</figure>~~
	112	+	![](/wiki-images/0/0d/Tutpeg_empty.png)
122	113
123	114		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.
124	115
125	116		- Double click the test paint button (this creates the event handler).
126	117		- Add 2 variables:
127	118
128	119		``` pascal
129	120		var
130	121		CellWidth : integer;
131	122		CellHeight: integer;
132	123		```
133	124
134	125		We'll need some extra variables to hold intermediate results:
135	126
136	127		- Add 3 local variables:
137	128
138	129		``` pascal
139	130		iRow, iCol: TCellNums;
140	131		CellArea : TRect;
141	132		```
142	133
143	134		CellArea is used to limit the rectangular area on screen where a cell will be drawn.
144	135
145	136		To process all rows and cols two straightforward [[For\|for loops]] will do.
146	137
147	138		- Add the following code to the event handler:
148	139
149	140		``` pascal
150	141		// Calculate the width/height of each cell to accomodate for all cells in the paintbox
151	142		CellWidth := pbPeg.Width div 7;
152	143		CellHeight := pbPeg.Height div 7;
153	144
154	145		// Draw boxes for all cells
155	146		for iRow := 1 to 7 do
156	147		for iCol := 1 to 7 do
157	148		begin
158	149		// Calculate the position of the cell in the paintbox
159	150		CellArea.Top := (iRow-1) * CellHeight;
160	151		CellArea.Left := (iCol-1) * CellWidth;
161	152		CellArea.Right := CellArea.Left + CellWidth;
162	153		CellArea.Bottom := CellArea.Top + CellHeight;
163	154		// And now draw the cell
164	155		pbPeg.Canvas.Rectangle(CellArea);
165	156		end;
166	157		```
167	158
168	159		A Canvas, as it's name suggests, is a control 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.
169	160
170		-	~~- Compile and run the program (press <span class="kbd">F9</span>).~~
	161	+	- Compile and run the program (press `F9`).
171	162		- Press the Test paint button.
172	163		- Maximize the form (the cells disappear; don't worry we'll fix that).
173	164		- Press the Test paint button again.
174	165
175	166		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.
176	167
177	168		- Create a new unit (File/New Unit).
178	169		- Save it as PegSolPainter.pas (File/Save and then and choose Rename to lowercase).
179	170		- Add a new class to the new unit file that will do all of the drawing (after the uses section, before the implementation section).
180	171
181	172		``` pascal
182	173		type
183	174		TPegSolPainter = class
184	175		private
185	176		PegSol : TPegSolitaire;
186	177		Canvas : TCanvas;
187	178
188	179		public
189	180		constructor Create(pPegSol: TPegSolitaire; pCanvas: TCanvas);
190	181		end;
191	182		```
192	183
193	184		Note that a TPegSolitaire variable is also added, because obviously we are going to use that class to retrieve a cells' state.
194	185
195		-	~~- Position the text cursor in the constructor line and press <span class="kbd">Ctrl</span>+<span class="kbd">Shift</span>+<span class="kbd">C</span>.~~
	186	+	- Position the text cursor in the constructor line and press `Ctrl`+`Shift`+`C`.
196	187		- The constructor must store the 2 parms locally:
197	188
198	189		``` pascal
199	190		constructor TPegSolPainter.Create(pPegSol: TPegSolitaire; pCanvas: TCanvas);
200	191		begin
201	192		PegSol := pPegSol;
202	193		Canvas := pCanvas;
203	194		end;
204	195		```
205	196
206	197		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.
207	198
208	199		- Add PegDatastructures and Graphics to the uses list.
209	200
210	201		``` pascal
211	202		uses
212	203		PegDatastructures,
213	204		Graphics,
214	205		Classes, SysUtils;
215	206		```
216	207
217	208		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.
218	209
219	210		Now we know this, we can add a paint method to our class.
220	211
221	212		- Add procedure Repaint to the class.
222	213
223	214		``` pascal
224	215		TPegSolPainter = class
225	216		private
226	217		PegSol : TPegSolitaire;
227	218		Canvas : TCanvas;
228	219
229	220		public
230	221		constructor Create(pPegSol: TPegSolitaire; pCanvas: TCanvas);
231	222		procedure Repaint(const pCanvasWidth, pCanvasHeight: integer);
232	223		end;
233	224		```
234	225
235		-	~~- Generate the body of the procedure (<span class="kbd">Ctrl</span>+<span class="kbd">Shift</span>+<span class="kbd">C</span>).~~
	226	+	- Generate the body of the procedure (`Ctrl`+`Shift`+`C`).
236	227		- Copy the code from TfrmMain.Button1Click(Sender: TObject) to this newly created method:
237	228
238	229		``` pascal
239	230		procedure TPegSolPainter.Repaint(const pCanvasWidth, pCanvasHeight: integer);
240	231		var
241	232		CellWidth : integer;
242	233		CellHeight : integer;
243	234		iRow, iCol : TCellNums;
244	235		CellArea : TRect;
245	236		begin
246	237		// Calculate the width of each cell to accomodate for all cells
247	238		CellWidth := pbPeg.Width div 7;
248	239		CellHeight := pbPeg.Height div 7;
249	240
250	241		// Draw boxes for all cells
251	242		for iRow := 1 to 7 do
252	243		for iCol := 1 to 7 do
253	244		begin
254	245		// Calculate the position of the cell in the paintbox
255	246		CellArea.Top := (iRow-1) * CellHeight;
256	247		CellArea.Left := (iCol-1) * CellWidth;
257	248		CellArea.Right := CellArea.Left + CellWidth;
258	249		CellArea.Bottom := CellArea.Top + CellHeight;
259	250		// And now draw the cell
260	251		pbPeg.Canvas.Rectangle(CellArea);
261	252		end;
262	253		end;
263	254		```
264	255
265	256		Because we no longer need the paintbox pbPeg we must remove the references to it. Three changes are needed:
266	257
267	258		- Change the calculation of the CellWidth and CellHeight to:
268	259
269	260		``` pascal
270	261		// Calculate the width of each cell to accomodate for all cells
271	262		CellWidth := pCanvasWidth div 7;
272	263		CellHeight := pCanvasHeight div 7;
273	264		```
274	265
275	266		- Change the drawing of the rectangle to:
276	267
277	268		``` pascal
278	269		// And now draw the cell
279	270		Canvas.Rectangle(CellArea);
280	271		```
281	272
282	273		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.
283	274
284	275		- In the main form source, locate the Button1Click method.
285	276		- Remove all statements and variables.
286	277		- Add 2 new variables: one for the game class and one for the painter class:
287	278
288	279		``` pascal
289	280		procedure TfrmMain.Button1Click(Sender: TObject);
290	281		var
291	282		pegsol : TPegSolitaire; // The game data
292	283		pegpaint: TPegSolPainter; // The paint class for the game
293	284		begin
294	285		end;
295	286		```
296	287
297	288		- Add PegSolPainter to the uses list.
298	289
299	290		To use the paint class is fairley straightforward: create a new instance and call the repaint method like so:
300	291
301	292		- Add the following code to the Button1Click method:
302	293
303	294		``` pascal
304	295		// Create a new game object
305	296		pegsol := TPegSolitaire.Create(7);
306	297
307	298		// Create a new painter object to paint this game
308	299		pegpaint := TPegSolPainter.Create(pegsol, pbPeg.Canvas);
309	300
310	301		// And paint the board
311	302		pegpaint.Repaint(pbPeg.Width, pbPeg.Height);
312	303
313	304		// Clean up
314	305		pegpaint.Free;
315	306		pegsol.Free
316	307		```
317	308
318	309		Run and test the program to see that it works exactly as before. The result will look something like this: ![](/wiki-images/2/2b/Tutpeg_empty_cells.png)
319	310
320	311		## It's all about events
321	312
322	313		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!
323	314
324	315		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 as an event: a paint event.
325	316
326		-	~~- Open the form editor (select ufrmMain in the editor and press <span class="kbd">F12</span>).~~
	317	+	- Open the form editor (select ufrmMain in the editor and press `F12`).
327	318		- Select the paintbox pbPeg.
328	319		- Open the Events tab in the Object Inspector.
329	320		- One of the events in the list is OnPaint.
330	321
331		-	~~<figure>~~
332		-	~~<img src="tutpeg_onpaint.png" title="tutpeg_onpaint.png" />~~
333		-	~~<figcaption>tutpeg_onpaint.png</figcaption>~~
334		-	~~</figure>~~
	322	+	![](/wiki-images/3/3a/Tutpeg_onpaint.png)
335	323
336	324		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.
337	325
338	326		- Select the OnPaint event in the Object Inspector and click on the small button with three dots. This will generate the event handler body.
339	327		- Copy/Paste the exact code from the Button1Click event handler to this new method.
340	328
341	329		``` pascal
342	330		procedure TfrmMain.pbPegPaint(Sender: TObject);
343	331		var
344	332		pegsol : TPegSolitaire; // The game data
345	333		pegpaint: TPegSolPainter; // The paint class for the game
346	334		begin
347	335		// Create a new game object
348	336		pegsol := TPegSolitaire.Create(7);
349	337
350	338		// Create a new painter object to paint this game
351	339		pegpaint := TPegSolPainter.Create(pegsol, pbPeg.Canvas);
352	340
353	341		// And paint the board
354	342		pegpaint.Repaint(pbPeg.Width, pbPeg.Height);
355	343
356	344		// Clean up
357	345		pegpaint.Free;
358	346		pegsol.Free
359	347		end;
360	348		```
361	349
362	350		- Remove all code and variables from method Button1Click. Remember: the IDE will automatically remove this now empty method for us.
363	351		- Remove the Test paint button from the form.
364	352		- Run the program to see what happens (ignore the fact that the background color is now different).
365	353
366	354		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.
367	355
368	356		- Find the forms's declaration.
369	357		- Add the 2 variables we created in the OnPaint event:
370	358
371	359		``` pascal
372	360		TfrmMain = class(TForm)
373	361		pbPeg: TPaintBox;
374	362		procedure pbPegPaint(Sender: TObject);
375	363		private
376	364		{ private declarations }
377	365		pegsol : TPegSolitaire; // The game data
378	366		pegpaint: TPegSolPainter; // The paint class for the game
379	367		public
380	368		{ public declarations }
381	369		end;
382	370		```
383	371
384	372		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.
385	373
386	374		- Add procedure StartNewGame to the form.
387	375
388	376		``` pascal
389	377		private
390	378		{ private declarations }
391	379		pegsol : TPegSolitaire; // The game data
392	380		pegpaint: TPegSolPainter; // The paint class for the game
393	381
394	382		procedure StartNewGame;
395	383		```
396	384
397	385		- Generate the body.
398	386		- Add the initialzation code:
399	387
400	388		``` pascal
401	389		procedure TfrmMain.StartNewGame;
402	390		begin
403	391		// Clean up the previous game
404	392		pegpaint.Free;
405	393		pegsol.Free;
406	394
407	395		// Start with a new game
408	396		pegsol := TPegSolitaire.Create(7);
409	397		pegpaint := TPegSolPainter.Create(pegsol, pbPeg.Canvas);
410	398		end;
411	399		```
412	400
413	401		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.
414	402
415		-	~~- Open the form editor (press <span class="kbd">F12</span>).~~
	403	+	- Open the form editor (press `F12`).
416	404		- Double click somewhere in a free area on the form; do nót click on the paintbox.
417	405
418		-	~~<figure>~~
419		-	~~<img src="tutpeg_form_create.png" title="tutpeg_form_create.png" />~~
420		-	~~<figcaption>tutpeg_form_create.png</figcaption>~~
421		-	~~</figure>~~
	406	+	![](/wiki-images/4/4a/Tutpeg_form_create.png)
422	407
423	408		- Add the call to the StartNewGame procedure:
424	409
425	410		``` pascal
426	411		procedure TfrmMain.FormCreate(Sender: TObject);
427	412		begin
428	413		StartNewGame
429	414		end;
430	415		```
431	416
432	417		Now that the game and paint objects are created at program start, they are no longer required in the OnPaint method.
433	418
434	419		- Locate procedure procedure TfrmMain.pbPegPaint(Sender: TObject);
435	420		- Remove the local variables and all code except for the line that actualle does the painting.
436	421
437	422		``` pascal
438	423		procedure TfrmMain.pbPegPaint(Sender: TObject);
439	424		begin
440	425		// Paint the board
441	426		pegpaint.Repaint(pbPeg.Width, pbPeg.Height);
442	427		end;
443	428		```
444	429
445	430		- Run the program and see what happens.
446	431
447	432		## Intermezzo
448	433
449	434		So far we have focused on building a program to play the classic solitaire game in the 7x7 grid. Is it now possible to create smaller or bigger grids for other type games? Let's test this.
450	435
451	436		- In the main form locate the StartNewGame method.
452	437		- Change the line pegsol := TPegSolitaire.Create(7); to pegsol := TPegSolitaire.Create(5);. So a smaller board with 5x5 squares is created.
453	438		- Run the program and see what happens.
454	439
455	440		As we can see on screen we still see a 7x7 matrix! This is the result of using magic numbers, which we should have avoided (see <http://en.wikipedia.org/wiki/Magic_number_%28programming%29#Unnamed_numerical_constants>).
456	441
457	442		Using magic numbers equals disaster: it's a matter of when, not if a program will fail.
458	443
459	444		- Open PegSolPainter.
460	445		- Locate the procedure TPegSolPainter.Repaint(const pCanvasWidth, pCanvasHeight: integer);.
461	446
462	447		In there we see the number of 7 a couple of times. This the magic number that plays tricks on us. In the calculation of the cell width and height, we need the size of the board as stored in the pegsol game variable. And the same goes for the iRow and iCol loops. So let's fix this once and for all:
463	448
464	449		``` pascal
465	450		// Calculate the width of each cell to accomodate for all cells
466	451		CellWidth := pCanvasWidth div pegsol.Size;
467	452		CellHeight := pCanvasHeight div pegsol.Size;
468	453
469	454		// Draw boxes for all cells
470	455		for iRow := 1 to pegsol.Size do
471	456		for iCol := 1 to pegsol.Size do
472	457		begin
473	458		// Calculate the position of the cell in the paintbox
474	459		CellArea.Top := (iRow-1) * CellHeight;
475	460		CellArea.Left := (iCol-1) * CellWidth;
476	461		CellArea.Right := CellArea.Left + CellWidth;
477	462		CellArea.Bottom := CellArea.Top + CellHeight;
478	463		// And now draw the cell
479	464		Canvas.Rectangle(CellArea);
480	465		end;
481	466		```
482	467
483	468		There's a caveat here: pegsol doesn't have a publicly accessible Size variable. And this is how it should be: all variables in a class should be private. The way to access those private *values* is via functions or properties (the interface of the class). For this simple value we will use a property.
484	469
485	470		- Open PegDatastructures.
486	471		- Rename the private variable in TPegSolitaire to FSize.
487	472		- Add a public read only property to the class: property Size: TCellNums read FSize;
488	473
489	474		The class will now look like this:
490	475
491	476		``` pascal
492	477		TPegSolitaire = class
493	478		private
494	479		FSize: TCellNums;
495	480		PegCells: TPegCells;
496	481		function GetCell(const pRow, pCol: TCellNums): TCellType;
497	482		procedure SetCell(const pRow, pCol: TCellNums; const pValue: TCellType);
498	483
499	484		public
500	485		constructor Create(const pSize: TCellNums);
501	486		property Cell[const pRow, pCol: TCellNums]: TCellType read GetCell write SetCell;
502	487		property Size: TCellNums read FSize;
503	488		end;
504	489		```
505	490
506	491		It's common practice to prefix variables that are accessed via properties with a letter F. We've made the public access to the size property read-only, because it should never be changed, once the game is started. The only place where the private variable should get it's final value is in the Create constructor.
507	492
508	493		- Locate the constructor.
509	494		- Change Size := pSize; to FSize := pSize; (if you don't you'll get a compilation error).
510	495		- And while we're at it, the initialization needs a minor fix as well. There is no need to initialize cells we are not going to use. So the constructor should look like this (C_MAX is replaced with Size):
511	496
512	497		``` pascal
513	498		constructor TPegSolitaire.Create(const pSize: TCellNums);
514	499		var iRow,iCol: integer;
515	500		begin
516	501		FSize := pSize;
517	502		for iRow := 1 to Size do
518	503		for iCol := 1 to Size do
519	504		Cell[iRow,iCol] := ctNoAccess;
520	505		end;
521	506		```
522	507
523	508		We are now ready to test the program and see if it now draws a nice 5x5 matrix.
524	509
525	510		- Run the program and see what happens (a 5x5 matrix is drawn).
526	511
527	512		Now that the basics of the game are in place, it's time to flesh out the gui.
528	513
529	514		## Let's get artistic
530	515
531	516		So far so good. We now have a game class, a supporting paint class and an unimpressive checker board on our form (well, sort of). In our solitaire game a cell can have 3 states: not accessible, empty or occupied. For each cell type we want a different graphic representation. Let's get to it.
532	517
533	518		- In the editor open PegSolPainter (the unit with the paint class for our board).
534	519		- Locate the Repaint method.
535	520		- Locate the line where the cell is drawn: Canvas.Rectangle(CellArea);.
536	521
537	522		Obviously we need to make a change here. It depends on the cell state what needs to be drawn (not accessible cell, empty cell or peg cell). The case... operation comes to the rescue.
538	523
539	524		- Change the drawing of cells like so:
540	525
541	526		``` pascal
542	527		// Draw boxes for all cells
543	528		for iRow := 1 to pegsol.Size do
544	529		for iCol := 1 to pegsol.Size do
545	530		begin
546	531		// Calculate the position of the cell in the paintbox
547	532		CellArea.Top := (iRow-1) * CellHeight;
548	533		CellArea.Left := (iCol-1) * CellWidth;
549	534		CellArea.Right := CellArea.Left + CellWidth;
550	535		CellArea.Bottom := CellArea.Top + CellHeight;
551	536
552	537		// And now draw the cell based on the cell's contents
553	538		case pegsol.Cell[iRow,iCol] of
554	539
555	540		ctNoAccess: // Draw cells that are not accessible
556	541		begin
557	542		Canvas.Brush.Color := clGray;
558	543		Canvas.Rectangle(CellArea);
559	544		end;
560	545
561	546		ctEmpty: // Draw cells that are currently empty
562	547		begin
563	548		Canvas.Brush.Color := clBlue;
564	549		Canvas.Rectangle(CellArea);
565	550		end;
566	551
567	552		ctPeg: // Draw cells that are occupied
568	553		begin
569	554		Canvas.Brush.Color := clBlue;
570	555		Canvas.Rectangle(CellArea); // Erase the background first
571	556		Canvas.Brush.Color := clGreen;
572	557		Canvas.Ellipse(CellArea); // Draw the pegs as green circles
573	558		end;
574	559		end;
575	560		end;
576	561		```
577	562
578	563		We could run the program at this stage (just try it), but it will only display a boring 5x5 grayish grid. This is because we didn't define any game setup yet. Let's fix this first.
579	564
580	565		- Open the main form source.
581	566		- Locate the StartNewGame method.
582	567		- Create a 7x7 game instead of 5x5.
583	568		- Initialize a couple of cells. For example:
584	569
585	570		``` pascal
586	571		procedure TfrmMain.StartNewGame;
587	572		begin
588	573		// Clean up the previous game
589	574		pegpaint.Free;
590	575		pegsol.Free;
591	576
592	577		// Start with a new 7x7 game
593	578		pegsol := TPegSolitaire.Create(7);
594	579		pegpaint := TPegSolPainter.Create(pegsol, pbPeg.Canvas);
595	580
596	581		// Initialize some cells
597	582		pegsol.Cell[3,4] := ctEmpty;
598	583		pegsol.Cell[4,2] := ctPeg;
599	584		pegsol.Cell[4,3] := ctPeg;
600	585		pegsol.Cell[4,4] := ctEmpty;
601	586		pegsol.Cell[4,5] := ctPeg;
602	587		pegsol.Cell[4,6] := ctPeg;
603	588		pegsol.Cell[5,4] := ctEmpty;
604	589		end;
605	590		```
606	591
607	592		- Run the program (it'll look something like the image below).
608	593
609		-	~~<figure>~~
610		-	~~<img src="tutpeg_first_pegs.png" title="tutpeg_first_pegs.png" />~~
611		-	~~<figcaption>tutpeg_first_pegs.png</figcaption>~~
612		-	~~</figure>~~
	594	+	![](/wiki-images/0/0b/Tutpeg_first_pegs.png)
613	595
614	596		## Populate the board
615	597
616	598		As we know a classic solitaire board should look something like this:
617	599
618		-	~~<figure>~~
619		-	~~<img src="tutpeg_classic.png" title="tutpeg_classic.png" />~~
620		-	~~<figcaption>tutpeg_classic.png</figcaption>~~
621		-	~~</figure>~~
	600	+	![](/wiki-images/6/6c/Tutpeg_classic.png)
622	601
623	602		And if we were to populate all cells individually, that would result in a lot of code. What if we could intialize the game by just passing it some text that would symbolically describe the board? Something like this:
624	603
625	604		``` pascal
626	605		// Initialize the cells to the classic game
627	606		pegsol.InitializeBoard( ' ooo ' + LineEnding +
628	607		' ooo ' + LineEnding +
629	608		'ooooooo' + LineEnding +
630	609		'ooo.ooo' + LineEnding +
631	610		'ooooooo' + LineEnding +
632	611		' ooo ' + LineEnding +
633	612		' ooo ' );
634	613		```
635	614
636	615		1. o is an occupied cell.
637	616		2. . is an empty but playable cell.
638	617		3. The spaces indicate cells that are not accessible.
639	618
640	619		Let's assume this is going to work and create a method in the TPegSelitaire class that can handle this.
641	620
642	621		- Let's be optimistic (also called 'Top down design') and add the above code to TfrmMain.StartNewGame:
643	622
644	623		``` pascal
645	624		procedure TfrmMain.StartNewGame;
646	625		begin
647	626		// Clean up the previous game
648	627		pegpaint.Free;
649	628		pegsol.Free;
650	629
651	630		// Start with a new 7x7 game
652	631		pegsol := TPegSolitaire.Create(7);
653	632		pegpaint := TPegSolPainter.Create(pegsol, pbPeg.Canvas);
654	633
655	634		// Initialize the cells to the classic game
656	635		pegsol.InitializeBoard( ' ooo ' + LineEnding +
657	636		' ooo ' + LineEnding +
658	637		'ooooooo' + LineEnding +
659	638		'ooo.ooo' + LineEnding +
660	639		'ooooooo' + LineEnding +
661	640		' ooo ' + LineEnding +
662	641		' ooo ' );
663	642		end;
664	643		```
665	644
666	645		- Open the PegDatastructures sourcefile.
667	646		- Add this procedure to the public section of the class: InitializeBoard(const pBoard: ansistring);
668	647
669	648		``` pascal
670	649		public
671	650		constructor Create(const pSize: TCellNums);
672	651		procedure InitializeBoard(const pBoard: ansistring);
673	652
674	653		property Cell[const pRow, pCol: TCellNums]: TCellType read GetCell write SetCell;
675	654		property Size: TCellNums read FSize;
676	655		```
677	656
678		-	~~- Generate the body of InitializeBoard (<span class="kbd">Ctrl</span>+<span class="kbd">Shift</span>+<span class="kbd">C</span>...).~~
	657	+	- Generate the body of InitializeBoard (`Ctrl`+`Shift`+`C`...).
679	658
680	659		Now what does this procedure actually need to do? It must split the textstring into seperate lines and then process those lines, Because we used LineEnding tokens to separate the lines, we can use a TStringList class to split them.
681	660
682	661		- Code InitalizeBoard like so:
683	662
684	663		``` pascal
685	664		procedure TPegSolitaire.InitializeBoard(const pBoard: ansistring);
686	665		var lst : TStringList;
687	666		iRow,iCol: integer;
688	667		s : string;
689	668		begin
690	669		// Create a list with the board text in it. This will split all lines
691	670		// into individual lines, because of the LineEnding 'splitter'.
692	671		lst := TStringList.Create;
693	672		lst.Text := pBoard;
694	673
695	674		// Process all lines one at a time
696	675		for iRow := 0 to lst.Count-1 do
697	676		if iRow < Size then // Make sure there is no overflow in the rows
698	677		begin
699	678		// Process a single line of text
700	679		s := lst[iRow];
701	680		for iCol := 1 to length(s) do
702	681		if iCol <= Size then // Make sure there is no overflow in the columns
703	682		case s[iCol] of
704	683		' ': Cell[iRow+1,iCol] := ctNoAccess;
705	684		'.': Cell[iRow+1,iCol] := ctEmpty;
706	685		'o': Cell[iRow+1,iCol] := ctPeg;
707	686		end;
708	687		end;
709	688
710	689		// Clean up the list
711	690		lst.Free;
712	691		end;
713	692		```
714	693
715	694		1. a TStringList is used as a buffer. This works because we used LineEnding as a separator between all lines.
716	695		2. There are Count number of lines, but they are numbered 0..Count-1. Our cells are numbered starting with 1. That's why you see iRow+1 in the cell assignments.
717	696
718	697		The above procedure contains a lot of extra variables and shouldn't be that difficult to understand. It's possible to reduce the procedure to the bare minimum like so:
719	698
720	699		``` pascal
721	700		procedure TPegSolitaire.InitializeBoard(const pBoard: ansistring);
722	701		var iRow,iCol: integer;
723	702		begin
724	703		with TStringList.Create do
725	704		begin
726	705		Text := pBoard;
727	706		for iRow := 0 to Min(Count-1, Size-1) do
728	707		for iCol := 1 to Min(length(Strings[iRow]),Size) do
729	708		case Strings[iRow][iCol] of
730	709		' ': Cell[iRow+1,iCol] := ctNoAccess;
731	710		'.': Cell[iRow+1,iCol] := ctEmpty;
732	711		'o': Cell[iRow+1,iCol] := ctPeg;
733	712		end;
734	713		Free;
735	714		end;
736	715		end;
737	716		```
738	717
739	718		This procedure does exactly the same but it uses the handy feature that you can use the With statement together with dynamically created objects. For this procedure to work add the Math unit to the uses section.
740	719
741	720		- Run the program. All cells are now populated like in the classic Peg Solitaire game.
742	721
743	722		## Events revisited
744	723
745	724		It doesn't look too impressive yet, but we have done quite a lot. The main thing missing at the moment is being able to leap cells to remove them from the board. And for that we are going to use the mouse. But how? Let's investigate the possibilities.
746	725
747	726		- Drop a [[TMemo]] on the form, to the left of the paint box pbPeg (it's on the Standard tab of the component palette).
748	727		- In the Object Inspector change Align to alClient. It will occupy all remaining space that is left of the paintbox.
749	728		- Change BorderSpacing.Around to 4.
750	729		- Clear the Lines property (click on the 3-dotted button and erase the text). The result should look like this:
751	730
752		-	~~<figure>~~
753		-	~~<img src="tutpeg_with_memo.png" title="tutpeg_with_memo.png" />~~
754		-	~~<figcaption>tutpeg_with_memo.png</figcaption>~~
755		-	~~</figure>~~
	731	+	![](/wiki-images/1/11/Tutpeg_with_memo.png)
756	732
757	733		- Select the paintbox pbPeg.
758	734		- In the Object Inspector select the Events tab.
759	735
760	736		There are 2 events that are interesting to us: OnMouseDown and OnMouseUp. Let's see what happens whith the OnMouseDown event.
761	737
762	738		- In the Object Inspector select the OnMouseDown event.
763	739		- Click on the 3-dotted button (this generates the body of the event procedure).
764	740
765	741		The header of the generated procedure contains a number of variables. Two of them are X and Y. They contain the position on the paintbox where the mouse button was pressed. Let's make them visible by adding some information to the memo component we've placed on the form.
766	742
767	743		- Add the following statement to the procedure; it adds a formatted line to the memo displaying the position where the mouse button was pressed:
768	744
769	745		``` pascal
770	746		Memo1.Append( format('Mouse down @ %dx%d',[X,Y]) )
771	747		```
772	748
773		-	~~- Run the program (press <span class="kbd">F9</span>).~~
	749	+	- Run the program (press `F9`).
774	750		- Click on the game board at several different locations. The memo box will display where the mouse button was pressed.
775	751		- End the program.
776	752
777	753		Obviously we cannot use the 'raw' X and Y coordinates; they are too high for our 7x7 game board. They must be translated to the cell's row and column coordinates. For that we need a function that translates a X/Y coordinate to a cell coordinate. For that we need the width and height of the paintbox, the number of cells in the grid and the width/height of an individual cell. The one place where all this comes together is... the paint class. So that is the obvious place to do this calculation.
778	754
779	755		- Open the PegDatastructures file.
780	756		- Add the TCellPosition record type to store cell coordinates:
781	757
782	758		``` pascal
783	759		type
784	760		TCellNums = 1..C_MAX;
785	761		TCellType = (ctNoAccess, ctEmpty, ctPeg);
786	762		TPegCells = array[TCellNums, TCellNums] of TCellType;
787	763
788	764		TCellPosition = record
789	765		Row: TCellNums;
790	766		Col: TCellNums;
791	767		end;
792	768		```
793	769
794	770		- Open the PegSolPainter class file.
795	771		- Add the public function CanvasXYtoCell(...) to the class:
796	772
797	773		``` pascal
798	774		public
799	775		constructor Create(pPegSol: TPegSolitaire; pCanvas: TCanvas);
800	776
801	777		procedure Repaint(const pCanvasWidth, pCanvasHeight: integer);
802	778		function CanvasXYtoCell(const pX, pY: integer): TCellPosition;
803	779		```
804	780
805		-	~~- Generate the body (<span class="kbd">Ctrl</span>+<span class="kbd">Shift</span>+<span class="kbd">C</span>).~~
	781	+	- Generate the body (`Ctrl`+`Shift`+`C`).
806	782		- Add the following code:
807	783
808	784		``` pascal
809	785		function TPegSolPainter.CanvasXYtoCell(const pX, pY: integer): TCellPosition;
810	786		begin
811	787		result.Col := (pX div CellWidth) + 1;
812	788		result.Row := (pY div CellHeight) + 1;
813	789		end;
814	790		```
815	791
816	792		The above code maps the large X/Y coordinate on the actual cell's row/col numbers. There is one problem though: the CellWidth and CellHeight are not available. They are intermediate results in the Repaint procedure and not stored. Let's fix that as well.
817	793
818	794		- Add CellWidth and CellHeight as private variables to the TPegSolPainter class:
819	795
820	796		``` pascal
821	797		TPegSolPainter = class
822	798		private
823	799		PegSol : TPegSolitaire;
824	800		Canvas : TCanvas;
825	801		CellWidth : integer;
826	802		CellHeight : integer;
827	803		```
828	804
829	805		- Remove the variables CellWidth and CellHeight from the variable list in the Repaint procedure:
830	806
831	807		``` pascal
832	808		procedure TPegSolPainter.Repaint(const pCanvasWidth, pCanvasHeight: integer);
833	809		var
834	810		iRow, iCol : TCellNums;
835	811		CellArea : TRect;
836	812		begin
837	813		```
838	814
839	815		Now we can modify the procedure where the mouse down coordinate was processed. With the new function the X/Y position can now be translated to an actuel cell coordinate.
840	816
841	817		- Open the main form sourcefile.
842	818		- Locate the pbPegMouseDown procedure.
843	819		- Change the code to:
844	820
845	821		``` pascal
846	822		procedure TfrmMain.pbPegMouseDown(Sender: TObject; Button: TMouseButton; Shift: TShiftState; X, Y: Integer);
847	823		var CellRC: TCellPosition;
848	824		begin
849	825		CellRC := pegpaint.CanvasXYtoCell(X,Y);
850	826		Memo1.Append( format('Mouse down @ %dx%d',[CellRC.Row, CellRC.Col]) )
851	827		end;
852	828		```
853	829
854	830		Let's do the same for the OnMouseUp event:
855	831
856	832		- Generate the procedure body for the OnMouseUp event.
857	833		- Add this code:
858	834
859	835		``` pascal
860	836		procedure TfrmMain.pbPegMouseUp(Sender: TObject; Button: TMouseButton; Shift: TShiftState; X, Y: Integer);
861	837		begin
862	838		with pegpaint.CanvasXYtoCell(X,Y) do
863	839		Memo1.Append( format('Mouse up @ %dx%d',[Row, Col]) )
864	840		end;
865	841		```
866	842
867	843		Note that this method does exactly the same as the OnMouseDown, but using the with construct saves us the trouble of declaring a local variable (less is more...).
868	844
869	845		Let's test this:
870	846
871	847		- Run the program.
872	848		- Click on the upper left most cell and hold the mouse down.
873	849		- Move the mouse cursor to another cell.
874	850		- Release the mouse button.
875	851
876	852		Every time you press the mouse button and release it, the exact cell where the mouse button was pressed or released is displayed in the memo box.
877	853
878	854		## Gluing things together
879	855
880	856		This program works a bit like the calculator program:
881	857
882	858		1. The user selects a peg to move by pressing the mouse button.
883	859		2. The user moves the peg over another peg to an empty cell (leaps).
884	860		3. The user release the mouse button to execute the leap.
885	861
886	862		Here we do not remember a number but a cell (-position). So as soon as the user presses the mouse button on a cell, we must store that position somewhere.
887	863
888	864		- Open the main form's sourcefile.
889	865		- Add a variable FromCell the the form's private variables.
890	866
891	867		``` pascal
892	868		private
893	869		{ private declarations }
894	870		pegsol : TPegSolitaire; // The game data
895	871		pegpaint: TPegSolPainter; // The paint class for the game
896	872		FromCell: TCellPosition; // The peg that is going to leap
897	873		```
898	874
899	875		- Locate the OnMouseDown event handler.
900	876		- Add the following line to that procedure:
901	877
902	878		``` pascal
903	879		FromCell := pegpaint.CanvasXYtoCell(X,Y);
904	880		```
905	881
906	882		Now as soon as the user releases the mouse button, we must execute the leap (verify if it's ok and update the board). Let's be optimistic (remember the Top Down remark?) and assume there is a procedure that does that for us: Leap(\<FromCell\>, \<ToCell\>).
907	883
908	884		- Locate the OnMouseUp event handler and add the following line:
909	885
910	886		``` pascal
911	887		pegsol.Leap(FromCell, pegpaint.CanvasXYtoCell(X,Y));
912	888		```
913	889
914	890		FromCell we already populated when the mouse button was pressed. The target cell is simply calculated by calling pegpaint.CanvasXYToCell(...). We could introduce a local variable for that, but it's not really necessary.
915	891
916	892		- Add the following line to the procedure as well:
917	893
918	894		``` pascal
919	895		pbPeg.Repaint;
920	896		```
921	897
922	898		This will force the paintbox to repaint itself, so all updated cells show the correct contents.
923	899
924	900		The complete OnMouseUp method now looks like this:
925	901
926	902		``` pascal
927	903		procedure TfrmMain.pbPegMouseUp(Sender: TObject; Button: TMouseButton; Shift: TShiftState; X, Y: Integer);
928	904		begin
929	905		with pegpaint.CanvasXYtoCell(X,Y) do
930	906		Memo1.Append( format('Mouse up @ %dx%d',[Row, Col]) );
931	907		pegsol.Leap(FromCell, pegpaint.CanvasXYtoCell(X,Y));
932	908		pbPeg.Repaint;
933	909		end;
934	910		```
935	911
936	912		Before going into the Leap procedure, a bit of extra functionality is introduced. Remember that we can retrieve the state of a cell (empty, peg or no access) via the Cell property of TPegSolitaire? For example pegsol.Cell\[2,2\] would give us the state of the cell in row 2 and column 2. But in the mean time we have introduced a new datastructure: TCellPosition. So for example if we want to get the state of the FromCell we would need the following awkward statement:
937	913
938	914		``` pascal
939	915		state := pegsol.Cell[ FromCell.Row, FromCell.Col ]
940	916		```
941	917
942	918		It would be nice if we could write something like:
943	919
944	920		``` pascal
945	921		state := pegsol.GetCell(FromCell)
946	922		```
947	923
948	924		Let's add this to our game class.
949	925
950	926		- Open sourcefile PegDatastructures.
951	927		- Add the private function: GetCell(const pPosition: TCellPosition): TCellType;
952	928
953	929		``` pascal
954	930		TPegSolitaire = class
955	931		private
956	932		FSize: TCellNums;
957	933		PegCells: TPegCells;
958	934
959	935		function GetCell(const pRow, pCol: TCellNums): TCellType;
960	936		procedure SetCell(const pRow, pCol: TCellNums; const pValue: TCellType);
961	937		function GetCell(const pPosition: TCellPosition): TCellType;
962	938		```
963	939
964	940		There now are two functions with the name GetCell, but the parameter list is different. So Lazarus knows exactly when to call which function.
965	941
966		-	~~- Generate the body of the function (<span class="kbd">Ctrl</span>+<span class="kbd">Shift</span>+<span class="kbd">C</span>).~~
	942	+	- Generate the body of the function (`Ctrl`+`Shift`+`C`).
967	943		- Insert the following code:
968	944
969	945		``` pascal
970	946		result := Cell[pPosition.Row, pPosition.Col]
971	947		```
972	948
973	949		Back to the main storyline. We have introduced a procedure Leap(...), but it doesn't exist yet. It is a method that changes the game board, so the place to put it is the TPegSolitaire class.
974	950
975	951		- Open sourcefile PegDatastructures.
976	952		- Add procedure Leap to the public section of the TPegSolitaire class.
977	953
978	954		``` pascal
979	955		public
980	956		constructor Create(const pSize: TCellNums);
981	957		procedure InitializeBoard(const pBoard: ansistring);
982	958		procedure Leap(const pFromCell, pToCell: TCellPosition);
983	959		```
984	960
985		-	~~- Generate the procedure body (<span class="kbd">Ctrl</span>+<span class="kbd">Shift</span>+<span class="kbd">C</span>).~~
	961	+	- Generate the procedure body (`Ctrl`+`Shift`+`C`).
986	962
987	963		Now this procedure does all the hard work: check if the cells are valid and if the leap is at all possible. This is not difficult, but the number of checks is quite extensive for something that looks simple. The code is fairly self-explanatory and if not, hopefully the comments explain what is going on. Note that the procedure uses the GetCell(\<cellposition\>) function we created earlier.
988	964
989	965		``` pascal
990	966		procedure TPegSolitaire.Leap(const pFromCell, pToCell: TCellPosition);
991	967		var dx, dy: integer;
992	968		JumpedCell: TCellPosition;
993	969		begin
994	970		// Verify that the start cell is occupied and the target cell is empty
995	971		// If not, leave the procedure via the EXIT.
996	972		if (GetCell(pFromCell) <> ctPeg) or
997	973		(GetCell(pToCell) <> ctEmpty) then
998	974		EXIT;
999	975
1000	976		// Calculate the horizontal and vertical distance between the cells
1001	977		dx := abs(pFromCell.Col - pToCell.Col);
1002	978		dy := abs(pFromCell.Row - pToCell.Row);
1003	979
1004	980		// A valid move has one direction equal to zero and the other equal to 2
1005	981		if ((dx = 2) and (dy = 0))
1006	982		or ((dx = 0) and (dy = 2)) then
1007	983		begin
1008	984		// Determine the position of the jumped cell; it's in the middle
1009	985		JumpedCell.Col := (pFromCell.Col + pToCell.Col) div 2;
1010	986		JumpedCell.Row := (pFromCell.Row + pToCell.Row) div 2;
1011	987
1012	988		// Final check: is there a peg in the jumped cell?
1013	989		if GetCell(JumpedCell) = ctPeg then
1014	990		begin
1015	991		// Jump: clear the FromCell, empty the jumped cell and populate the ToCell
1016	992		Cell[pFromCell.Row, pFromCell.Col] := ctEmpty;
1017	993		Cell[JumpedCell.Row, JumpedCell.Col] := ctEmpty;
1018	994		Cell[pToCell.Row, pToCell.Col] := ctPeg;
1019	995		end;
1020	996		end;
1021	997		end;
1022	998		```
1023	999
1024	1000		Believe it or not but we now have a working Peg Solitaire game program!
1025	1001
1026	1002		- Run the program.
1027	1003		- Press the mouse button on one peg cell.
1028	1004		- Leap over another peg cell to an empty cell.
1029	1005		- Release the mouse button.
1030	1006		- Repeat...
1031	1007
1032	1008		## Cleaning up
1033	1009
1034	1010		On the form we still have the memo component that displays mouse clicks. We don't really need it anymore.
1035	1011
1036	1012		- Delete the memo from the main form.
1037	1013		- Delete the memo updates from the MouseDown and MouseUp events.
1038	1014
1039	1015		``` pascal
1040	1016		procedure TfrmMain.pbPegMouseDown(Sender: TObject; Button: TMouseButton; Shift: TShiftState; X, Y: Integer);
1041	1017		begin
1042	1018		FromCell := pegpaint.CanvasXYtoCell(X,Y);
1043	1019		end;
1044	1020
1045	1021		procedure TfrmMain.pbPegMouseUp(Sender: TObject; Button: TMouseButton; Shift: TShiftState; X, Y: Integer);
1046	1022		begin
1047	1023		pegsol.Leap(FromCell, pegpaint.CanvasXYtoCell(X,Y) );
1048	1024		pbPeg.Repaint;
1049	1025		end;
1050	1026		```
1051	1027
1052		-	~~- Open the form editor (<span class="kbd">F12</span>).~~
	1028	+	- Open the form editor (`F12`).
1053	1029		- Select the paintbox pbPeg
1054	1030		- In the Object Inspector change property Align to alClient (look on the Properties tab).
1055	1031		- Remove the unit stdctrls from the uses list. The compiler would othwerwise give a hint in the Messages window that it isn't used (it was automatically added when we dropped the memo component on the form).
1056	1032
1057	1033		### What's next?
1058	1034
1059	1035		To make it a fully functional game we need a way to change the board without recompiling the application. And the graphics could be improved as well. Let's address the first issue first.
1060	1036
1061	1037		## Creating more board layouts
1062	1038
1063	1039		It would be nice if we could add more boards to our game without recompiling the application. The obvious place would be to store the board layouts in external textfiles. The user can then start a new game by opening one of the textfiles. The fun thing is, it's easy to add because we've already done most of the hard work. First let's make two board layouts.
1064	1040
1065	1041		- From the menu choose File/New...; this opens a pop up dialog.
1066	1042		- Choose the option Module/Text and click OK.
1067	1043		- Type the following text (it should look familiar :-) ):
1068	1044
1069	1045		``` pascal
1070	1046		ooo
1071	1047		ooo
1072	1048		ooooooo
1073	1049		ooo.ooo
1074	1050		ooooooo
1075	1051		ooo
1076	1052		ooo
1077	1053		```
1078	1054
1079	1055		- From the menu choose File/Save.
1080	1056		- Save the file in the projects' bin folder as classic.txt.
1081	1057
1082	1058		Add another file:
1083	1059
1084	1060		- From the menu choose File/New....
1085	1061		- Choose the option Module/Text and click OK.
1086	1062		- Type the following text:
1087	1063
1088	1064		``` pascal
1089	1065		...
1090	1066		.o.
1091	1067		..ooo..
1092	1068		.ooooo.
1093	1069		ooooooo
1094	1070		...
1095	1071		...
1096	1072		```
1097	1073
1098	1074		- From the menu choose File/Save.
1099	1075		- Save the file in the bin folder as triangle.txt.
1100	1076
1101	1077		There are many ways to create and open new boards. In this tutorial we'll use the menu driven approach (a thorough description of the menu is something for another tutorial).
1102	1078
1103	1079		- Open the main form's editor.
1104	1080		- Select the [[TMainMenu]] control from the Standard components palette.
1105	1081		- Click on the form (it doesn't matter if you 'hit' the paintbox). An icon is displayed showing that the menu is now availabe.
1106	1082		- Double click on the icon with label MainMenu1. This opens the menu editor with one item aldready available, labeled New Item1.
1107	1083		- In the Object Inspector change Caption to &File (include the ampersand; it's used to draw the underscore symbol when you press Alt to access the main menu).
1108	1084		- Right click on the File item in the Menu Editor and select Create Submenu from the pop up window.
1109	1085		- Change the Caption to E&xit (this adds a familiar application exit button).
1110	1086		- Right click on the File item.
1111	1087		- Select Insert New Item (after) from the pop up menu.
1112	1088		- Change the caption of that new menu to &Game.
1113	1089		- Right click on the Game menu and select Create Submenu from the pop up..
1114	1090		- Change the caption to Load from file....
1115	1091
1116	1092		The menu will now look something like this:
1117	1093
1118		-	~~<figure>~~
1119		-	~~<img src="tutpeg_mainmenu.png" title="tutpeg_mainmenu.png" />~~
1120		-	~~<figcaption>tutpeg_mainmenu.png</figcaption>~~
1121		-	~~</figure>~~
	1094	+	![](/wiki-images/4/4e/Tutpeg_mainmenu.png)
1122	1095
1123	1096		The menu is also visible at the top of the main form.
1124	1097
1125	1098		- Click on the File menu item; this opens the submenu and Exit is visible.
1126	1099		- Double click on Exit. As you might have guessed this creates an event handler. In other words the procedure that gets executed as soon as the user clicks on this menu item.
1127	1100		- Add the following not too complex code to the generated procedure:
1128	1101
1129	1102		``` pascal
1130	1103		Close
1131	1104		```
1132	1105
1133	1106		This will close the main form. And because it is the only form of our application it will end the application.
1134	1107
1135	1108		Okay now it's time to look at how to open the board files. There are standard components and menu's available to do this, but let's do it the manual way.
1136	1109
1137	1110		- Open the main form's editor.
1138	1111		- In the component palette select the [[Dialogs tab]].
1139	1112		- Select the [[TOpenDialog]] component (click on it).
1140	1113		- Click on the main form (anywhere). A OpenDialog1 component is now visible. This component provides us with a kind of explorer pop up with which we can select files. The main form now looks like this:
1141	1114
1142		-	~~<figure>~~
1143		-	~~<img src="tutpeg_mainform.png" title="tutpeg_mainform.png" />~~
1144		-	~~<figcaption>tutpeg_mainform.png</figcaption>~~
1145		-	~~</figure>~~
	1115	+	![](/wiki-images/5/51/Tutpeg_mainform.png)
1146	1116
1147	1117		- In the Object Inspector click on the Filter property and then on the 3-dotted button. This pops up the filter dialog. This is the place where we tell the file dialog what files we allow the user to select.
1148	1118		- We only want to see text files so add this filter line: Peg Solitaire textfiles (.txt) \\| .txt (see image below).
1149	1119		- Press OK.
1150	1120
1151		-	~~<figure>~~
1152		-	~~<img src="tutpeg_filterdialog.png" title="tutpeg_filterdialog.png" />~~
1153		-	~~<figcaption>tutpeg_filterdialog.png</figcaption>~~
1154		-	~~</figure>~~
	1121	+	![](/wiki-images/1/13/Tutpeg_filterdialog.png)
1155	1122
1156	1123		- In the Object Inspector change Options.ofFileMustExist to true. This forces the dialog to only allow existing files to be selected.
1157	1124
1158	1125		So far so good. Now to actually open a file when the menu item is selected:
1159	1126
1160	1127		- On the main form click on the Game menu item. This opens the drop down menu.
1161	1128		- Click on Load from file.... As expected this generates an.... event handler.
1162	1129		- Add the following code to the Event handler:
1163	1130
1164	1131		``` pascal
1165	1132		if OpenDialog1.Execute then
1166	1133		ShowMessage(OpenDialog1.FileName);
1167	1134		```
1168	1135
1169	1136		Remember: small steps. We have now added a menu to the form to exit the application and to load a game board set up from disk. We haven't actually coded the loading part, but let's first try the code we have so far.
1170	1137
1171	1138		- Run the application.
1172	1139		- From the menu choose Game/Load from file....
1173	1140		- Select triangle.txt and press Open.
1174	1141		- A window pops up that shows us the selected filename.
1175	1142		- End the program.
1176	1143
1177	1144		Now let's finish the board loading code. The code is pretty self-explanatory and reuses some of the procedures we have created so far.
1178	1145
1179	1146		- Open the main form's editor.
1180	1147		- From the menu choose Game/Load from file.... This will open the event handler.
1181	1148		- Replace the code with this:
1182	1149
1183	1150		``` pascal
1184	1151		procedure TfrmMain.MenuItem4Click(Sender: TObject);
1185	1152		begin
1186	1153		// Open the pop up dialog
1187	1154		if OpenDialog1.Execute then
1188	1155		begin
1189	1156		// Start with a new empty board
1190	1157		StartNewGame;
1191	1158
1192	1159		// Dynamically create a stringlist to load the board layout
1193	1160		with TStringList.Create do
1194	1161		begin
1195	1162		// Load the board layout from the textfile
1196	1163		LoadFromFile(OpenDialog1.FileName);
1197	1164
1198	1165		// Initialize the board with the file's contents
1199	1166		pegsol.InitializeBoard(Text);
1200	1167
1201	1168		// Clean up the stringlist
1202	1169		Free
1203	1170		end;
1204	1171
1205	1172		// After loading the new board update the paintbox
1206	1173		pbPeg.Repaint;
1207	1174		end;
1208	1175		end;
1209	1176		```
1210	1177
1211	1178		And that's all there is to it!
1212	1179
1213	1180		Run the program, open a board set up file and play the game!
1214	1181
1215	1182		## Eye candy
1216	1183
1217	1184		We now have a working Peg Solitaire application. There's still plenty of room for improvent, but the game itself is working nicely. The last part of this tutorial is about improving the looks of the game. Sure the game works, but a bit more detail in the graphics would be nice. And that's pretty easy to add. All we need are three images for the cell types, update the painter class and in the main form, tell the painter to use the images. So let's add the three images to the painter class:
1218	1185
1219	1186		- Open the PegSolPainter sourcefile.
1220	1187		- Add the 3 images to the private variables section:
1221	1188
1222	1189		``` pascal
1223	1190		TPegSolPainter = class
1224	1191		private
1225	1192		PegSol : TPegSolitaire;
1226	1193		Canvas : TCanvas;
1227	1194		CellWidth : integer;
1228	1195		CellHeight : integer;
1229	1196
1230	1197		ImgNoAccess: TPicture;
1231	1198		ImgEmpty : TPicture;
1232	1199		ImgPeg : TPicture;
1233	1200		```
1234	1201
1235	1202		- Add a procedure to the public section for loading the images.
1236	1203
1237	1204		``` pascal
1238	1205		public
1239	1206		constructor Create(pPegSol: TPegSolitaire; pCanvas: TCanvas);
1240	1207		procedure Repaint(const pCanvasWidth, pCanvasHeight: integer);
1241	1208		function CanvasXYtoCell(const pX, pY: integer): TCellPosition;
1242	1209		procedure LoadImage(const pCellType: TCellType; const pFilename: string);
1243	1210		```
1244	1211
1245	1212		- Generate the body for the procedure.
1246	1213		- Add the code:
1247	1214
1248	1215		``` pascal
1249	1216		procedure TPegSolPainter.LoadImage(const pCellType: TCellType; const pFilename: string);
1250	1217
1251	1218		procedure UpdateImage(var pImg: TPicture; const pNewImage: TPicture);
1252	1219		begin
1253	1220		pImg.Free;
1254	1221		pImg := pNewImage
1255	1222		end;
1256	1223
1257	1224		var pic: TPicture;
1258	1225		begin
1259	1226		// Make sure the file exists
1260	1227		if FileExists(pFilename) then
1261	1228		begin
1262	1229		// First load the picture in a local variable
1263	1230		pic := TPicture.Create;
1264	1231		pic.LoadFromFile(pFilename);
1265	1232
1266	1233		// Now update the required image based on the pCelltype parm
1267	1234		case pCelltype of
1268	1235		ctNoAccess: UpdateImage(ImgNoAccess, pic);
1269	1236		ctEmpty : UpdateImage(ImgEmpty, pic);
1270	1237		ctPeg : UpdateImage(ImgPeg, pic);
1271	1238		end;
1272	1239		end;
1273	1240		end;
1274	1241		```
1275	1242
1276	1243		The code again is self-explanatory. Note that we use a short local procedure to update an image. If we wouldn't do that then the case statement (case pCellType of) would be more complex (i.e. contain more redundant code). Now each cell type only needs one line to update the right image.
1277	1244
1278	1245		We've added the pictures to the class. Now we must use them and that of course happens in the Repaint procedure. For each celltype we check whether an image is available. And if so, use that image instead of the plain drawing.
1279	1246
1280	1247		- Locate the Repaint method.
1281	1248		- In the case statement, change the ctNoAccess, ctEmpty and ctPeg sections to:
1282	1249
1283	1250		``` pascal
1284	1251		// And now draw the cell based on the cell's contents
1285	1252		case pegsol.Cell[iRow,iCol] of
1286	1253
1287	1254		ctNoAccess: // Draw cells that are not accessible
1288	1255		if not assigned(ImgNoAccess) then
1289	1256		begin
1290	1257		Canvas.Brush.Color := clGray;
1291	1258		Canvas.Rectangle(CellArea);
1292	1259		end
1293	1260		else with ImgNoAccess do
1294	1261		Canvas.CopyRect(CellArea, Bitmap.Canvas, Rect(0,0,Width,Height));
1295	1262
1296	1263		ctEmpty: // Draw cells that are currently empty
1297	1264		if not assigned(ImgEmpty) then
1298	1265		begin
1299	1266		Canvas.Brush.Color := clBlue;
1300	1267		Canvas.Rectangle(CellArea);
1301	1268		end
1302	1269		else with ImgEmpty do
1303	1270		Canvas.CopyRect(CellArea, Bitmap.Canvas, Rect(0,0,Width,Height));
1304	1271
1305	1272		ctPeg: // Draw cells that are occupied
1306	1273		if not assigned(ImgPeg) then
1307	1274		begin
1308	1275		Canvas.Brush.Color := clBlue;
1309	1276		Canvas.Rectangle(CellArea); // Erase the background first
1310	1277		Canvas.Brush.Color := clGreen;
1311	1278		Canvas.Ellipse(CellArea);
1312	1279		end
1313	1280		else with ImgPeg do
1314	1281		Canvas.CopyRect(CellArea, Bitmap.Canvas, Rect(0,0,Width,Height));
1315	1282
1316	1283		end;
1317	1284		```
1318	1285
1319	1286		In the main form locate the StartNewGame method and add the image loading code to the painter class.
1320	1287
1321	1288		- Open the main form editor.
1322	1289		- Locate method StartNewGame.
1323	1290		- Add LoadImage statements after the creation of the pegpaint object:
1324	1291
1325	1292		``` pascal
1326	1293		// Start with a new 7x7 game
1327	1294		pegsol := TPegSolitaire.Create(7);
1328	1295		pegpaint := TPegSolPainter.Create(pegsol, pbPeg.Canvas);
1329	1296
1330	1297		pegpaint.LoadImage(ctNoAccess, 'tutpeg_cellforbidden.jpg');
1331	1298		pegpaint.LoadImage(ctEmpty, 'tutpeg_cellempty.jpg');
1332	1299		pegpaint.LoadImage(ctPeg, 'tutpeg_celloccupied.jpg');
1333	1300		```
1334	1301
1335	1302		Make sure that the above images are downloaded from below and put in the program's bin folder, or better yet, create your own images. Note: to download these images, click on them first thén download them.
1336	1303
1337	1304		![](/wiki-images/1/1c/Tutpeg_cellforbidden.jpg) ![](/wiki-images/5/51/Tutpeg_cellempty.jpg) ![](/wiki-images/9/9c/Tutpeg_celloccupied.jpg)
1338	1305
1339	1306		- Now test the solitaire game and hopefully it looks something like the image at the beginning of this tutorial...
1340	1307
1341	1308		## Final tweaks
1342	1309
1343	1310		Most programs have their own icons that are displayed in menu's and in explorer windows. It's easy to add your own custom icon to an application.
1344	1311
1345	1312		- From the menu choose Project/Project Options....
1346	1313		- Click on Project Options in the pop up dialog (right at the top). This will display the window with the application icon.
1347	1314		- Click on Load Icon and load your icon of choice; or download the marble that comes with this tutorial:
1348	1315
1349		-	~~<figure>~~
1350		-	~~<img src="tutpeg_marble.png" title="tutpeg_marble.png" />~~
1351		-	~~<figcaption>tutpeg_marble.png</figcaption>~~
1352		-	~~</figure>~~
	1316	+	![](/wiki-images/e/eb/Tutpeg_marble.png)
1353	1317
1354	1318		- Press OK.
1355	1319
1356	1320		The application will now have a nice marble icon in the form's title bar and in explorer windows.
1357	1321
1358	1322		---
1359	1323		From the Free Pascal wiki, page "Peg Solitaire tutorial", as it stood on 2023-12-04 after a change by Amerou, out of the wiki's dump of 2024-05-26. Copyright stays with the author who wrote it, according to the old wiki's [[Licensing]] page. If you have concerns about this material, [message the admin](/wiki-contact).

Back to history