GolfmlClass: what changed

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

Old	New		Line
1	1		# tgolfmlclass
2	2
3	3		------------------------------------------------------------------------
4	4
5	5		- A Lazarus/Free Pascal class to accept data via properties and write a well-formed golfml XML golf information exchange file.
6	6		- It will also read a well-formed golfml XML golf information exchange file and present the data via properties.
7	7		- You can have as many Courses and Tee positions as you like (they are stored in internal dynamic arrays) , but only one Golf Club. Holes can be 1 up to 18.
8	8		- ugolfmlclass.pas is available for download [from here](http://code.google.com/p/golfml/source/browse/#svn%2Fgolfml%2Fcoursewriter%2Fsource%2F2.x)
9	9		- An example application Golfml Coursewriter is available [from here](http://code.google.com/p/golfml/wiki/CourseWriter)
10	10		- To learn more about golfml visit <http://code.google.com/p/golfml/>
11	11
12	12		------------------------------------------------------------------------
13	13
14	14		## Declaration
15	15
16	16		`Uses: ugolfmlclass`\
17	17		`Var: GolfmlClass:TGolfMLClass;`
18	18
19	19		------------------------------------------------------------------------
20	20
21	21		## Methods
22	22
23	23		- function InitOK: boolean
24	24
25	25		` * Returns TRUE = Success, FALSE = Fatal Error`
26	26
27	27		- Procedure Reset (use before re-assigning a new club and courses)
28	28
29	29		Both methods initialise all variables in the class and prepare it for use. The Function InitOK only returns TRUE if all is well.
30	30
31	31		FORM CREATE EVENT EXAMPLE:
32	32
33	33		`GolfmlClass:=TGolfMLClass.Create; `\
34	34		`If NOT GolfmlClass.InitOK then Halt;`
35	35
36	36		- function MakeGolfmlFile:Boolean;
37	37
38	38		` * Returns TRUE=Success. Overwrites any file with the same name (set in CourseXMLPath property)`
39	39
40	40		- function GetCourseInfoFromFile:boolean
41	41
42	42		` * Returns TRUE=Success`
43	43
44	44		Reading
45	45
46	46		- GolfmlClass.GetCourseInfoFromFile is called before any properties are read and after CourseXMLPath has been set.
47	47
48	48		Writing
49	49
50	50		- GolfmlClass.!MakeGolfmlFile should only be called after all the data has been set using the properties (see below)
51	51
52	52		------------------------------------------------------------------------
53	53
54	54		## Properties Read/Write
55	55
56	56		`// Club-wide Properties`\
57	57		`property ClubAmeneties[iIndex:Integer]: string // 0..`\
58	58		`property ClubComments[iIndex:Integer]: string // 0..`\
59	59		`// Both are dynamic properties that grow as assigned. They should be assigned in order for reliable results.`\
60	60		`// The type and description are separated by a comma`\
61	61		`// GolfmlClass.ClubAmeneties[0]:='amenity type,amenity description';`\
62	62		`// GolfmlClass.ClubAmeneties[1]:='amenity type,amenity description';`\
63		-	\
64		-	\
	63	+
65	64		`property CourseXMLPath: string // Note: THIS NOT CHECKED FOR VALIDITY by tgolfmlclass.`\
66	65		`property ClubName: string`\
67	66		`property ClubCountry: string`\
68	67		`property ClubCountryCode: string`\
69	68		`property ClubMunicipality: string`\
70	69		`property ClubRegion: string`\
71	70		`property ClubStreet: string`\
72	71		`property ClubPostCode: string`\
73	72		`property ClubWebsite: string`\
74	73		`property ClubPhone: string`\
75		-	\
76		-	\
	74	+
77	75		`// Course-wide Properties`\
78	76		`// Change courses by changing the CourseIndex property (0-based)`\
79	77		`property CourseIndex:Cardinal //(zero-based)`\
80	78		`Property CourseName:String`\
81	79		`Property CoursePar:Cardinal // Total Par value of the course`\
82	80		`Property CourseNumberOfHoles:Cardinal //(1-based, usually 9 or 18)`\
83		-	\
84		-	\
	81	+
85	82		`// Tee Position-wide Properties`\
86	83		`// Change Tee sets by changing the TeeColourIndex property (0-based)`\
87	84		`// Normally, TeeColourIndex is normally from Gold (0) to Red (5)`\
88	85		`// but it can be any scheme you like as long as the TeeColour and`\
89	86		`// TeeGender agree.`\
90	87		`Property TeeColourIndex:Cardinal //(zero-based)`\
91	88		`property TeeTitle: string // Can be anything: 'Competition', 'Regular', 'Ladies'`\
92	89		`property TeeColour: string // i.e. 'gold', 'black', 'white', 'yellow', 'blue', 'red'`\
93	90		`property TeeGender: string // 'gentlemen' or 'ladies'`\
94	91		`Property CourseRating:Single`\
95	92		`Property SlopeRating:Cardinal`\
96		-	\
97		-	\
98		-	\
	93	+
99	94		`// Hole Properties`\
100	95		`// Change Hole by changing the HoleIndex property (0-17)`\
101	96		`property HoleIndex:Cardinal //(zero-based)`\
102	97		`Property Par:Cardinal`\
103	98		`Property StrokeIndex:Cardinal`\
104	99		`Property Metric:Boolean // Affects Distance conversion. Metric=TRUE means distances in meters`\
105	100		`Property TeeDistanceMetres:Cardinal`\
106	101		`Property TeeDistanceYards:Cardinal`\
107	102		`// Note Tee Distances are automatically converted yards->meters and meters->yards.`\
108	103		`// Only specify yards OR meters when setting Tee Distances`\
109		-	\
	104	+
110	105		`// Stylesheet writing properties`\
111	106		`Property IncludeScoreCardStylesheetReference:Boolean`\
112	107		`Property IncludePlayerScoreCardStylesheetReference:Boolean`\
113	108		`Property ScoreCardPlayerName:String`\
114	109		`Property ScoreCardPlayerGender:String`\
115	110		`Property ScoreCardPlayerDateOfBirth:String`\
116	111		`Property ScoreCardPlayerHandicap:Single`\
117		-	\
	112	+
118	113		`=== Properties Read Only ===`\
119		-	\
	114	+
120	115		`Property Version:String readonly;`\
121	116		`Property InTeeDistance:Cardinal; // Calculated value for each course.Metric determines metres or yards`\
122	117		`Property OutTeeDistance:Cardinal // Calculated value for each course. Metric determines metres or yards`\
123	118		`Property TotalTeeDistance:Cardinal // Calculated value for each course. Metric determines metres or yards`\
124	119		`Property CourseTotalPar:Cardinal // Calculated value for each course.`\
125	120		`Property BogeyRating:Single // Calculated value for each tee position.`\
126	121		`property MaxCourseIndex:Cardinal // Highest value for CourseIndex`\
127	122		`Property MaxTeeColourIndex:Cardinal`\
128	123		`Property ClubMaxAmenitiesIndex:Cardinal`\
129	124		`Property ClubMaxCommentsIndex:Cardinal`
130	125
131	126		- MaxIndex-type properties help when setting up a loop to read the indexed property values e.g.
132	127
133	128		`With GolfmlClass do`\
134	129		` Begin`\
135	130		` For iCount:=0 to MaxCourseIndex do`\
136	131		` begin`\
137	132		` CourseIndex:=iCount; // Set the course number`\
138	133		` MyStringList.Add(CourseName); // Read data for this course`\
139	134		` end;`\
140	135		` End;`
141	136
142	137		------------------------------------------------------------------------
143	138
144	139		SIMPLE WRITING EXAMPLE: To set the Par of Hole 3 to the value 5 on the first course at Tee-position 1:
145	140
146	141		`GolfmlClass.CourseIndex:=0;`\
147	142		`GolfmlClass.TeeIndex:=0;`\
148	143		`GolfmlClass.HoleIndex:=2;`\
149	144		`GolfmlClass.Par:=5;`
150	145
151	146		------------------------------------------------------------------------
152	147
153	148		SIMPLE READING EXAMPLE: To get the Par of Hole 3 on the first course at Tee-position 1:
154	149
155	150		`GolfmlClass.CourseIndex:=0;`\
156	151		`GolfmlClass.TeeIndex:=0;`\
157	152		`GolfmlClass.HoleIndex:=2;`\
158	153		`cParVariable:=GolfmlClass.Par;`
159	154
160	155		------------------------------------------------------------------------
161	156
162	157		#### How to populate the data before calling MakeGolfmlFile
163	158
164	159		Normally you would set up 3 nested loops, and assign values to properties within the loops according to their scope.
165	160
166	161		MULTIPLE WRITING EXAMPLE:
167	162
168	163		`GolfmlClass.Reset;`\
169	164		`...Set Club-wide properties...`\
170	165		`For CourseLoop:=0 to ... DO`\
171	166		` GolfmlClass.CourseIndex:=CourseLoop; // Write data to this course`\
172	167		` ...assign Course-wide properties...`\
173	168		` For TeeLoop:=0 to .. DO`\
174	169		` GolfmlClass.TeeColourIndex:=TeeLoop; // Write data to this Tee Position in this course`\
175	170		` ...assign Tee Position-wide properties...`\
176	171		` For HoleLoop:=0 to 17 (or 9) DO`\
177	172		` GolfmlClass.HoleIndex:=HoleLoop; // Write data to this hole in this Tee Position in this course`\
178	173		` ...assign Hole properties....`\
179	174		` end; // next hole`\
180	175		` end; // next tee position`\
181	176		`end; // next course`\
182	177		`GolfmlClass.CourseXMLPath:='C:\courses\mycourse.xml';`\
183	178		`GolfmlClass.MakeGolfmlFile;`
184	179
185	180		------------------------------------------------------------------------
186	181
187	182		#### How to retrieve the data after calling GetCourseInfoFromFile
188	183
189	184		MULTIPLE READING EXAMPLE
190	185
191	186		`GolfmlClass.Reset;`\
192	187		`GolfmlClass.CourseXMLPath:='C:\courses\mycourse.xml';`\
193	188		`GolfmlClass.GetCourseInfoFromFile;`\
194		-	\
	189	+
195	190		`//Retrieve the Club properties first.`\
196	191		`sName:=GolfmlClass.Clubname;`\
197	192		`...etc`\
198	193		`//Now get all the Club Amenities via a loop.`
199	194
200	195		Remember the amenity type and description are separated by a comma
201	196
202	197		Here's a function to separate them
203	198
204	199		`procedure SplitAmenety(var fAmenityType,fAmenetyValue:String;Const aString:String);`\
205	200		`// Changes fAmenityType, fAmenetyValue`\
206	201		`// Uses C_AMENETYDELIMITERCHAR`\
207	202		`Var`\
208	203		` i:Integer;`\
209	204		`begin`\
210	205		` if Length(aString)=0 then exit;`\
211	206		` i:=Pos(C_AMENETYDELIMITERCHAR,aString);`\
212	207		` If i > 1 then`\
213	208		` Begin`\
214	209		` fAmenityType:=LeftStr(aString,i-1);`\
215	210		` fAmenetyValue:=RightStr(aString,Length(aString)-i);`\
216	211		` end;`\
217	212		`end;`\
218		-	\
	213	+
219	214		`Var sAmenityType, sAmenityValue:String;`\
220	215		`For iLoop:=0 to GolfmlClass.ClubMaxAmenitiesIndex do`\
221	216		` begin`\
222	217		` // Initialise strings to pass by value to procedure`\
223	218		` sAmenityType:='';`\
224	219		` sAmenityValue:=''; `
225	220
226	221		`SplitAmenety(sAmenityType,sAmenityValue,GolfmlClass.ClubAmeneties[iLoop]);`\
227	222		` MyAmenityTypeList.Add(sAmenityType);`\
228	223		` MyAmenityValueList.Add(sAmenityValue);`\
229	224		` End;`
230	225
231	226		... fetch the ClubComments in the same way...
232	227
233	228		`For iLoop:=0 to GolfmlClass.ClubMaxCommentsIndex do`\
234	229		` begin `\
235	230		` MyStringList.Add(GolfmlClass.ClubComments[iLoop]);`\
236	231		` End;`
237	232
238	233		Retrieve the data for each hole in each tee set in each course via a loop
239	234
240	235		`For CourseLoop:=0 to GolfmlClass.MaxCourseIndex DO`\
241	236		` GolfmlClass.CourseIndex:=CourseLoop; // Read data from this course`\
242	237		` ...get Course-wide properties...`\
243	238		` .. get Hole pars and strokeindexes (via a holeindex loop)`\
244	239		` For TeeLoop:=0 to GolfmlClass.MaxTeeColourIndex DO`\
245	240		` GolfmlClass.TeeColourIndex:=TeeLoop; // Read data from this Tee Position in this course`\
246	241		` ...get Tee Position-wide properties for this course`\
247	242		` .... get Course and Slope ratings. Get the Tee colours, titles and genders...`\
248	243		` For HoleLoop:=GolfmlClass.CourseNumberOfHoles DO`\
249	244		` GolfmlClass.HoleIndex:=HoleLoop; // Read data from this hole in this Tee Position in this course`\
250	245		` GolfmlClass.Metric:=TRUE; //=FALSE would retrieve yards`\
251	246		` ...Get Hole distances in metres`\
252	247		` end; // next hole`\
253	248		` end; // next tee position`\
254	249		`end; // next course`
255	250
256	251		## Summary
257	252
258	253		Each property has a scope within a Club, Course, Tee-position or Hole.
259	254
260	255		..for instance:
261	256
262	257		- Distances are for a course, tee-position and hole
263	258		- StrokeIndexes are for a course and hole only.
264	259		- CourseRating is for a course and tee-position only
265	260
266	261		GolfmlClass tries to make this as simple as possible for reading and writing by having 3 "master" index properties for Course, TeePosition and Hole. (There is only ever one Club) In this way, you always know the scope of the property that you are trying to read or write.
267	262
268	263		---
269	264		From the Free Pascal wiki, page "GolfmlClass", as it stood on 2014-05-27 after a change by BigChimp, 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).
270	265		Category: Components
271	266		Category: XML

Back to history