Dulux-Oz's Pointer Toolkit For Dummies
Hi Guys,
Because I've been informed that some people are having trouble using the Pointer Toolkit I put together this post to try to make things clearer - Enjoy!
IMPORTNAT POINT No 1
Quote:
Pointers can be considered an "advanced" topic in FG Coding. You NEED to FULLY read and understand the Pointer Toolkit Documentation to be able to use the Toolkit consistently and successfully. Just about all of the issues people have had with getting the Toolkit to work have stemmed from the fact that they HAVEN'T FULLY read and/or understood the documentation (and/or they've been trying to use the Toolkit to do things it wasn't designed to do).
IMPORTNAT POINT No 2
Quote:
The Pointer Toolkit is NOT designed to be used "as is" - it's a Toolkit - you take the individual tool or tools from the kit and use them in your project.
IMPORTNAT POINT No 3
Quote:
The Pointer Toolkit includes some SAMPLE or EXAMPLE functions to show you how to achieve certain results. If the Sample functions are useful to use "as is", by all means use them - BUT they were designed as Examples, not as finalised code.
OK, now that we've understood these three very important points, lets get started.
FG has two types of Pointers: Standard Pointers and Custom Pointers.
The Standard Pointers are: Circle, Square, 90-Degree Cone and Arrow. Custom Pointers are Pointers we create.
We don't need to do anything to the FG Code to use the Standard Pointers, UNLESS we want to use one or more Custom Pointers in our Ruleset.
Any Ruleset can have a MAXIMUM of 5 Pointers. The 5 Pointers can be a mix of Standard and Custom Pointers.
Any Pointer is made up of Lines, Curves and Quarter-Ellipse Curves.
To draw a Line we use the fpLineCurve() function from the Toolkit and give it the Starting and Ending X- and Y-Coordinates, plus an Offset. I'll explain what the Offset does later. Most people will use an Offset of 0.
To draw a curve we can use either the fpAngleArcCurve() or the fpEndpointArcCurve() function and give them the Starting X- and Y-Coordinates of the Curve, the X- and Y-Coordinates of the Centrepoint of the Circle the Curve is a part of and either the Angle that the Curve needs to cover in Degrees (for the first function) or the Ending X- and Y-Coordinates of the Curve (for the second function). Both of these functions in turn call the fpArcCurve() function.
To draw a Quarter-Ellipse curve we can use the fpEllipseCurve() function and give it the X- and Y-Radius of the Quarter-Ellipse, plus an Offset. The "flatness" of the Quarter-Ellipse depends upon the ratio of the two Radii: if they are the same (ie 1:1) we end up with a Quarter-Circle.
So, if your Pointer has Lines you need to include the fpLineCurve(), if it has Quarter-Ellipses you need to include the fpEllipseCurve() function, and if it has Curves you need to include the fpArcCurve() function and either (or both) the fpAngleArcCurve() or the fpEndpointArcCurve() function, depending upon how you draw your curves (End-Point or Angle-of-Arc).
These four functions are called Curve Definition Functions.
OK, so How do we do this?
Well, Pointers are part of imagecontrols, so we need to modify the imagecontrol used to display maps, etc. In the CoreRPG this imagecontol is called "image" and is found starting at line 28 of the campaign/campaign_images.xml file. If we look at line 35 of this file we can see that the image imagecontrol calls a script file called image.lua in the campaign/scripts folder. So we know we need to modify these two files: we need to put the relevant functions from the Pointer Toolkit into the image.lua file and make some changes to the image imagecontrol in the campaign_images.xml file. Of course, this is just one way of accomplishing our goal - and we need to be aware that if we modify these two files the next time FG is updated the two files will be reverted back to they way they were before we changed them - some people solve this problem by putting their Custom Pointers in an Extension, but this can lead to conflicts with other Extensions that deal with the image imagecontrol.
To tell FG that we want to use Custom Pointers we need to put a <pointertypes> tag inside the image imagecontrol and a pointer tag for each Custom Pointer AND one for each Standard Pointer. The SAMPLE Code below shows a <pointertypes> tag with 5 pointer tags: one for each of the Standard Pointers and one for a Custom Pointer called "45Cone".
Code:
<imagecontrol>
<pointertypes>
<custom name="45Cone">
<icon>pointer_cone</icon>
<label>Draw a 45-Degree Cone</label>
</custom>
<arrow>
<icon>pointer</icon>
<label>Draw Arrow</label>
</arrow>
<square>
<icon>pointer_square</icon>
<label>Draw Square</label>
</square>
<circle>
<icon>pointer_circle</icon>
<label>Draw Circle</label>
</circle>
<cone>
<icon>pointer_cone</icon>
<label>Draw Cone</label>
</cone>
</pointertypes>
<!-- Other imagecontrol tags -->
</imagecontrol>
Once FG sees the <pointertypes> tag and the corresponding <custom> tag it automatically calls a function called onBuildCustomPointer() with takes the Starting and Ending X- and Y-Coordinates of the Pointer, plus a string representing the Custom Pointer name (eg "45Cone"). We don't have to worry about calling onBuildCustomPointer() with the correct values: FG takes care of this for us. We do have to tell onBuildCustomPointer() what to do, such as work out the length of the Pointer, etc, plus draw the Pointer. Obviously, onBuildCustomPointer() should go into the same file that we've placed the required Curve Definition Functions in (eg image.lua or our Extension).
The best way to draw a Pointer is have onBuildCustomPointer() call a Pointer-Drawing function, one for each Custom Pointer. These Pointer-Drawing functions also go into the file with the other functions (eg image.lua).
To draw a Pointer FG expects a table of Coordinates. The Curve Definition Functions return the correctly values in the correct format, so if our Pointer-Drawing function calls the correct Curve Definition Functions with the correct values, then we've drawn our Pointer.
The Pointer Toolkit includes 11 SAMPLE Pointer-Drawing functions and a SAMPLE onBuildCustomPointer() function to show you how to do this.
Pointers are drawn centred around the Start Point (for Circles, Squares, etc) or originating at the Start Point (for Cones and Arrows) and extending out to the End Point. Remember the Offset value used in some of the Curve Definition Functions? This causes the Line/Ellipse-Curve to "slide along" the line from the Start Point to the End Point. If you look closely at the Sample Pointer-Drawing functions you can see how this works.
So, to summarise: take the functions and Sample functions from the Toolkit and place them in a file. Link the file (if it isn't already) to the imagecontol. Tell FG to use the Custom Pointers via the <pointertypes> tag.
And have fun!
I hope this has made things clearer for everyone.
Any question, please ask.
Cheers
