Sign in Join
Wiki copytemporary

GolfmlClass: what changed

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

Title: GolfmlClass

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

Back to history