Subversion Repositories cheapmusic

Rev

Details | Last modification | View Log | RSS feed

Rev Author Line No. Line
98 - 1
<?xml version="1.0" encoding="ISO-8859-1" standalone="no"?>
2
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1" /><title>4.4. Callbacks</title><link rel="stylesheet" type="text/css" href="phplotdoc.css" /><meta name="generator" content="DocBook XSL Stylesheets V1.78.1" /><link rel="home" href="index.html" title="PHPlot Reference Manual" /><link rel="up" href="advanced.html" title="Chapter 4. PHPlot Advanced Topics" /><link rel="prev" href="adv-truecolor.html" title="4.3. Truecolor Images" /><link rel="next" href="adv-datacolor-callback.html" title="4.5. Custom Data Color Selection" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">4.4. Callbacks</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="adv-truecolor.html">Prev</a> </td><th width="60%" align="center">Chapter 4. PHPlot Advanced Topics</th><td width="20%" align="right"> <a accesskey="n" href="adv-datacolor-callback.html">Next</a></td></tr></table><hr /></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="callbacks"></a>4.4. Callbacks</h2></div></div></div><div class="abstract"><p class="title"><strong></strong></p><p>
3
This section documents the callback feature in PHPlot.
4
  </p></div><p>
5
Callbacks allow a programmer using PHPlot to insert their own functions
6
into the graph drawing process. Callbacks are currently also used for
7
development and testing of PHPlot.
8
</p><div class="warning" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Warning</h3><p>
9
All PHPlot class variables, and all methods/functions which are not
10
documented in the "Reference" section of the PHPlot Reference Manual, are
11
considered to be for internal use and are subject to be changed or removed
12
at any time.
13
If you call internal functions, or access internal class variables,
14
you greatly increase the risk of breaking your application with
15
future PHPlot releases.
16
  </p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="callbacks-api"></a>4.4.1. Callbacks Application Interface</h3></div></div></div><p>
17
Refer to these entries in the Function Reference:
18
  </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
19
<a class="xref" href="SetCallback.html" title="SetCallback"><span class="refentrytitle">SetCallback</span></a> - Register a callback function
20
      </p></li><li class="listitem"><p>
21
<a class="xref" href="GetCallback.html" title="GetCallback"><span class="refentrytitle">GetCallback</span></a> - Return a currently registered callback function
22
      </p></li><li class="listitem"><p>
23
<a class="xref" href="RemoveCallback.html" title="RemoveCallback"><span class="refentrytitle">RemoveCallback</span></a> - Unregister a callback function
24
      </p></li></ul></div><p>
25
</p><p>
26
Either a function name or an object and method can be registered as
27
a callback with <a class="xref" href="SetCallback.html" title="SetCallback"><span class="refentrytitle">SetCallback</span></a>.
28
For more information about using callbacks with objects and methods,
29
see the PHP manual under
30
<a class="ulink" href="http://www.php.net/manual/en/language.pseudo-types.php#language.types.callback" target="_top">Types, Pseudo Types, Callback</a>
31
and the documentation for the PHP
32
<a class="ulink" href="http://www.php.net/manual/en/function.call-user-func.php " target="_top">call_user_func</a>
33
function.
34
Also refer to <a class="xref" href="callbacks.html#callbacks-objects" title="4.4.4. Object Methods as Callbacks">Section 4.4.4, &#8220;Object Methods as Callbacks&#8221;</a> later in this manual.
35
Whether calling a function or an object method as a callback,
36
the same calling sequence is used.
37
</p><p>
38
  </p><pre class="programlisting">function_name($img, $passthrough_arg, [other_args...])
39
</pre><p>
40
</p><p>
41
  </p><div class="variablelist"><dl class="variablelist"><dt><span class="term">$img</span></dt><dd><p>
42
The GD image resource for the plot image.
43
        </p></dd><dt><span class="term">$passthrough_arg</span></dt><dd><p>
44
The third argument supplied to SetCallback ($arg) when the callback is
45
established. This allows the programmer to pass information to the callback
46
without using global variables. This can be any PHP type including array.
47
To pass a reference, you should put it into an array and pass the array.
48
        </p></dd><dt><span class="term">other_args...</span></dt><dd><p>
49
Zero or more additional arguments supplied by PHPlot to callbacks of this
50
type. Refer to <a class="xref" href="callbacks.html#callbacks-names" title="4.4.3. Available Callbacks">Section 4.4.3, &#8220;Available Callbacks&#8221;</a> to see what callback
51
reasons supply extra arguments.
52
        </p></dd></dl></div><p>
53
</p><p>
54
For example, given this callback setup:
55
  </p><pre class="programlisting">$plot-&gt;SetCallback('draw_graph', 'my_drawing_callback', $myvar);
56
</pre><p>
57
Then PHPlot will call:
58
  </p><pre class="programlisting">my_drawing_callback($img, $myvar_value, $plot_area);
59
</pre><p>
60
Where $myvar_value is the value of $myvar at the time SetCallback was called.
61
(The plot_area parameter is only supplied for the draw_graph callback in
62
PHPlot-5.1.0 and later.)
63
</p><p>
64
Some callbacks are expected to return a value. This is documented in
65
<a class="xref" href="callbacks.html#callbacks-names" title="4.4.3. Available Callbacks">Section 4.4.3, &#8220;Available Callbacks&#8221;</a>. In all other cases, the return value
66
from a callback function is ignored.
67
(Callbacks which return a value were implemented in PHPlot-5.1.3.)
68
</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
69
Instead of using the name of a function in <code class="function">SetCallback</code>,
70
you can use a PHP anonymous function.
71
See the example in <a class="xref" href="adv-datacolor-callback.html#adv-datacolor-callback-custom" title="4.5.2. Custom Data Color Selection">Section 4.5.2, &#8220;Custom Data Color Selection&#8221;</a>.
72
  </p></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="callbacks-access"></a>4.4.2. Callback Function Access</h3></div></div></div><p>
73
By default, the callback function has access only to the GD image resource
74
as the $img argument, the pass-through argument provided when the callback
75
function was registered, and additional arguments (if any) provided by
76
PHPlot for the callback. It does not have access to the PHPlot
77
class object instance, nor any of its contents.
78
</p><p>
79
If you need access to the internals of the PHPlot class instance from your
80
callback, you have three options.
81
  </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>
82
You can declare your PHPlot class instance variable as
83
<span class="emphasis"><em>global</em></span>.
84
      </p></li><li class="listitem"><p>
85
You can pass the instance variable as the $arg when registering the
86
callback. With PHP5 and above, this will pass a reference to the object,
87
which allows reading and changing variables.
88
      </p></li><li class="listitem"><p>
89
You can use a class method which extends PHPlot.
90
This is described in <a class="xref" href="callbacks.html#callbacks-objects" title="4.4.4. Object Methods as Callbacks">Section 4.4.4, &#8220;Object Methods as Callbacks&#8221;</a>.
91
      </p></li></ol></div><p>
92
</p><p>
93
As stated in the warning at the top of this section, any access to the class
94
internals is risky and subject to break with any new update to PHPlot.
95
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="callbacks-names"></a>4.4.3. Available Callbacks</h3></div></div></div><p>
96
This section defines the currently available callback names. A callback
97
name is also called a <span class="emphasis"><em>reason</em></span>.
98
  </p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
99
At most one callback can be active for any given callback name, for each
100
PHPlot object. Setting a second callback on the same name will result in
101
the new callback replacing the old one.
102
    </p></div><p>
103
</p><p>
104
Most of the callbacks currently available are drawing callbacks, activated
105
during the graph drawing process started by <a class="xref" href="DrawGraph.html" title="DrawGraph"><span class="refentrytitle">DrawGraph</span></a>.
106
By convention, a drawing callback occurs right after the event which it names.
107
For example, the <span class="command"><strong>draw_titles</strong></span> callback will be called after
108
drawing the plot titles.
109
</p><p>
110
Debug callbacks are for use when developing and debugging PHPlot itself.
111
Needless to say, their use for other purposes is discouraged.
112
</p><p>
113
The following table lists the available callback reasons.
114
</p><p>
115
  </p><div class="informaltable"><a id="callback-reasons"></a><table summary="PHPlot available callback reasons" border="1"><colgroup><col class="c1" /><col class="c2" /><col class="c3" /><col class="c4" /></colgroup><thead><tr><th>Callback Name:</th><th>Calling Point:</th><th>Extra Parameters:</th><th>Notes:</th></tr></thead><tbody><tr><td>data_color</td><td>Every time a color is needed for a data element.</td><td>$row, $col, $extra</td><td>The callback is expected to return an integer color index
116
             into the data colors array. This is for custom color selection.
117
             For more information, see
118
             <a class="xref" href="adv-datacolor-callback.html" title="4.5. Custom Data Color Selection">Section 4.5, &#8220;Custom Data Color Selection&#8221;</a>.</td></tr><tr><td>data_points</td><td>Every time a data point is plotted, for supported plot types.</td><td>$shape, $row, $col, ...</td><td>This callback is primarily used to create image maps.
119
             For more information, see <a class="xref" href="adv-imgmap.html" title="4.10. Image Maps for Plot Data">Section 4.10, &#8220;Image Maps for Plot Data&#8221;</a>.
120
             This was added in PHPlot-5.7.0.
121
          </td></tr><tr><td>draw_setup</td><td>After all setup, before drawing anything.</td><td>(None)</td><td>Anything drawn here will be covered by the background.</td></tr><tr><td>draw_image_background</td><td>After drawing the image backgrounds and border.</td><td>(None)</td><td> </td></tr><tr><td>draw_plotarea_background</td><td>After drawing the plot area background.</td><td>plot_area</td><td>plot_area parameter was added in PHPlot-5.1.0</td></tr><tr><td>draw_titles</td><td>After drawing the plot title, X and Y titles.</td><td>(None)</td><td>Called even if no titles were set.</td></tr><tr><td>draw_axes</td><td>After drawing the X and Y axis and grid lines.</td><td>(None)</td><td>Not called for pie charts.</td></tr><tr><td>draw_graph</td><td>After drawing the body of the graph.</td><td>plot_area</td><td>plot_area parameter was added in PHPlot-5.1.0</td></tr><tr><td>draw_border</td><td>After drawing the plot area border.</td><td>(None)</td><td>Not called for pie charts before PHPlot-5.6.0</td></tr><tr><td>draw_legend</td><td>After drawing the legend, if legend is enabled.</td><td>(None)</td><td>Not called if no legend was set.</td></tr><tr><td>draw_all</td><td>After all drawing is complete.</td><td>plot_area</td><td>Added in PHPlot-5.1.0</td></tr><tr><td>debug_textbox</td><td>Just before drawing any text.</td><td>$px, $py, $bbox_width, $bbox_height</td><td>Provides access to the orthogonal bounding box position
122
              and size for the text string.</td></tr><tr><td>debug_scale</td><td>Called at end of many scale calculation functions.</td><td>Function name, then an array of variable name =&gt; value</td><td>For displaying intermediate values in margin and scale
123
              calculations.</td></tr></tbody></table></div><p>
124
</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Notes:</h3><p>
125
Several of the drawing callbacks include <em class="parameter"><code>plot_area</code></em>
126
as an extra parameter. This is an array of 4 values that define the plot area
127
within the image, in GD pixel coordinates, as left_x, top_y, right_x, and
128
bottom_y. For more information, see <a class="xref" href="dev-layout.html" title="Chapter 7. PHPlot Plot Layout">Chapter 7, <em>PHPlot Plot Layout</em></a>.
129
  </p><p>
130
See <a class="xref" href="callbacks.html#callbacks-drawing" title="4.4.5. Using Callbacks to Annotate Plots">Section 4.4.5, &#8220;Using Callbacks to Annotate Plots&#8221;</a>
131
for information on using the drawing callbacks to annotate your plot.
132
  </p></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="callbacks-objects"></a>4.4.4. Object Methods as Callbacks</h3></div></div></div><p>
133
The callback function argument to <a class="xref" href="SetCallback.html" title="SetCallback"><span class="refentrytitle">SetCallback</span></a>
134
can be an array of two elements: a class variable and a method.
135
This can be used with any class, but here we are interested in using an
136
extension of the PHPlot class.
137
Consider the following setup:
138
</p><p>
139
  </p><pre class="programlisting">class my_PHPlot extends PHPlot
140
{
141
  function __construct($width=600, $height=400, $outfile=NULL, $infile=NULL)
142
  {
143
    parent::__construct($width, $height, $outfile, $infile);
144
  }
145
 
146
  function callback($img, $arg)
147
  {
148
    fwrite(STDERR, "callback in object\n");
149
    fwrite(STDERR, "Plot area: ({$this-&gt;plot_area[0]}, {$this-&gt;plot_area[1]}) :");
150
    fwrite(STDERR, " ({$this-&gt;plot_area[2]}, {$this-&gt;plot_area[2]})\n");
151
  }
152
}
153
</pre><p>
154
</p><p>
155
We define a class which extends PHPlot, and a method 'callback' which
156
displays the plot area using the internal PHPlot class variable plot_area.
157
  </p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
158
PHPlot version 6.1.0 and earlier used the class name as the constructor
159
method name, as required in PHP4.  This was deprecated in PHP7.
160
Earlier versions of this reference manual used
161
<code class="literal">$this-&gt;PHPlot(...)</code> to call the parent constructor.
162
This will not work with PHPlot after version 6.1.0 when the constructor
163
name was changed for PHP7.
164
    </p><p>
165
Using <code class="literal">__construct()</code> in the extended class as shown
166
above - for both the extended class constructor and when calling the
167
base class constructor - will work in PHP5 and PHP7, and with PHPlot
168
versions before and after the constructor name change.
169
    </p></div><p>
170
</p><p>
171
We will then create an instance of the extended class, and set a callback.
172
  </p><pre class="programlisting">$plot = new my_PHPlot(400,300);
173
$plot-&gt;SetCallback('draw_titles', array($plot, 'callback'));
174
</pre><p>
175
</p><p>
176
When the draw_titles callback is triggered, it will call the 'callback'
177
method inside our extended class. Because this is an extension of the
178
PHPlot class, it has access to all the member variables via $this.
179
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="callbacks-drawing"></a>4.4.5. Using Callbacks to Annotate Plots</h3></div></div></div><p>
180
This section contains information about using PHPlot callbacks to annotate
181
a plot with text and graphics. This is an advanced topic, and requires some
182
knowledge of both PHPlot and the PHP GD extension.
183
</p><div class="warning" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Warning</h3><p>
184
The information in this section uses features which are recent additions
185
to PHPlot, and in some cases uses PHPlot internal variables and functions.
186
As a result, these methods are less likely to work with older releases, and
187
more at risk to change or break in future releases.
188
  </p></div><p>
189
This section will first provide general information and advice about
190
annotating plots using callbacks.
191
 
192
After, portions of the script from <a class="xref" href="ex-annotate.html" title="5.22. Example - Annotating a Plot Using a Callback">Section 5.22, &#8220;Example - Annotating a Plot Using a Callback&#8221;</a>
193
will be explained in more detail.
194
</p><p>
195
The emphasis here is on using callbacks, but annotation is also possible
196
without callbacks.
197
You can use <a class="xref" href="SetPrintImage.html" title="SetPrintImage"><span class="refentrytitle">SetPrintImage</span></a>(False) to disable automatic
198
output of your image. Then, when <a class="xref" href="DrawGraph.html" title="DrawGraph"><span class="refentrytitle">DrawGraph</span></a> returns, you
199
can annotate your plot using GD functions on the <code class="literal">img</code>
200
member variable of your PHPlot object. Use of callbacks is preferred,
201
however, because it makes your script somewhat less dependent on PHPlot
202
internals (such as the <code class="literal">img</code> variable).
203
</p><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a id="callbacks-drawing-set"></a>4.4.5.1. Setting the callback</h4></div></div></div><p>
204
Use <a class="xref" href="SetCallback.html" title="SetCallback"><span class="refentrytitle">SetCallback</span></a> to establish a drawing callback.
205
You can find a list of callbacks in <a class="xref" href="callbacks.html#callbacks-names" title="4.4.3. Available Callbacks">Section 4.4.3, &#8220;Available Callbacks&#8221;</a>.
206
The various callbacks with names starting 'draw_' are called at different
207
points in the drawing process. Drawn objects will cover items drawn at an
208
earlier stage. For example, if you draw a line from a 'draw_titles' callback
209
(which is called after the plot titles are drawn, but before the graph is
210
drawn), the line would be 'behind' and possibly covered by the plotted data.
211
</p><p>
212
Note that PHPlot does very little except save parameter values until you
213
call <a class="xref" href="DrawGraph.html" title="DrawGraph"><span class="refentrytitle">DrawGraph</span></a>. For that reason, you should use GD functions
214
for annotation only from a drawing callback (that is, a callback with a name
215
starting with 'draw_').
216
The drawing callbacks are called after PHPlot calculations and image resource
217
setup, at which point everything is ready for drawing.
218
In addition, you should not use PHPlot functions which control plot
219
appearance from your drawing callback. These would either have no affect,
220
because it is too late, or produce unexpected results.
221
</p></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a id="callbacks-drawing-coords"></a>4.4.5.2. Coordinates</h4></div></div></div><p>
222
When drawing with GD, you will use the <a class="link" href="concepts.html#def-devcoor">Device
223
Coordinate system</a>. The coordinates in this system are pixels, with
224
the origin in the upper left corner of your image. Y advances down and X
225
advances to the right.
226
</p><p>
227
If you want to make annotations relative to specific values in your plot data,
228
you need to translate those values from
229
<a class="link" href="concepts.html#def-worldcoor">World Coordinates</a> to device coordinates.
230
Use the PHPlot function <a class="xref" href="GetDeviceXY.html" title="GetDeviceXY"><span class="refentrytitle">GetDeviceXY</span></a>
231
to perform this translation.
232
You will need access to your PHPlot object from inside your callback function
233
in order to use this (or any other PHPlot method function). You can make it
234
global, or designate it as the passthrough argument to SetCallback.
235
  </p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
236
This does not apply to pie charts, which have do not use world coordinates.
237
    </p></div><p>
238
</p><p>
239
If your annotations will fall outside the plot area (for example, in an
240
area you reserved for annotation using <a class="xref" href="SetPlotAreaPixels.html" title="SetPlotAreaPixels"><span class="refentrytitle">SetPlotAreaPixels</span></a>
241
or <a class="xref" href="SetMarginsPixels.html" title="SetMarginsPixels"><span class="refentrytitle">SetMarginsPixels</span></a>, then you need not be concerned with
242
coordinate translation. Of course, you can also add annotations at fixed
243
pixel coordinates inside the plot area, however these may overlay (if done
244
from a draw_graph or later callback) or underlay (if done before the
245
draw_graph callback) the plotted data.
246
</p></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a id="callbacks-drawing-colors"></a>4.4.5.3. Colors</h4></div></div></div><p>
247
Every GD drawing function you use will require a color value argument.
248
You are recommended to allocate your own colors in your callback using the
249
GD function <code class="function">imagecolorresolve()</code>. This function
250
will always return a color index, by either re-using an existing color in
251
the image's color map, or by allocating a new color.
252
Using imagecolorresolve() rather than trying to access the PHPlot internal
253
variables for color indexes will protect your script from breaking if the
254
way PHPlot manages its internal colors ever changes.
255
</p></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a id="callbacks-drawing-text"></a>4.4.5.4. Text</h4></div></div></div><p>
256
Text can be added to your plot using GD functions which include
257
<code class="function">imagestring</code>, for build-in simple fonts, and
258
<code class="function">imagettftext</code> for TrueType font text. To use these
259
functions, you need device coordinates, as described above.
260
</p><p>
261
You can also add text to your plot using the PHPlot function
262
<a class="xref" href="dev-internal.html#DrawText">DrawText</a>. This is documented only for internal
263
use by PHPlot, so there is a risk of future incompatibility. But this
264
function provides support for controlling the text justification, and works
265
better with multi-line text.
266
</p></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a id="callbacks-drawing-example"></a>4.4.5.5. Example</h4></div></div></div><p>
267
This example creates a bar chart and adds annotation. The goal is to draw an
268
ellipse and add text to the highest and lowest bars in a bar chart.
269
 
270
Refer to <a class="xref" href="ex-annotate.html" title="5.22. Example - Annotating a Plot Using a Callback">Section 5.22, &#8220;Example - Annotating a Plot Using a Callback&#8221;</a> for the complete script and
271
output from this example.
272
</p><p>
273
The script starts with the usual PHPlot object creation and setup.
274
</p><pre class="programlisting">$plot = new PHPlot(800, 600);
275
$plot-&gt;SetTitle('Monthly Widget Sales');
276
...
277
</pre><p>
278
(For the complete script, see the example referenced above.)
279
</p><p>
280
Before calling DrawGraph, establish the drawing callback. This uses the
281
<code class="literal">draw_all</code> callback, which gets called when all drawing is
282
complete in DrawGraph. (Note: If using PHPlot-5.0.7 or earlier, use
283
'draw_graph' instead, as 'draw_all' was not yet available.)
284
The name of our callback function is <code class="literal">annotate_plot</code>,
285
and we are passing the PHPlot object ($plot) as a pass-through parameter.
286
You can use a global or class callback instead -
287
see <a class="xref" href="callbacks.html#callbacks-api" title="4.4.1. Callbacks Application Interface">Section 4.4.1, &#8220;Callbacks Application Interface&#8221;</a> for more on these options.
288
</p><pre class="programlisting">$plot-&gt;SetCallback('draw_all', 'annotate_plot', $plot);
289
</pre><p>
290
</p><p>
291
Here is the declaration of our callback function. The <code class="literal">$img</code>
292
parameter is provided by PHPlot itself, and is the GD resource for our image.
293
The <code class="literal">$plot</code> parameter is the pass-through argument we provided
294
above when establishing the callback.
295
Some callbacks make other parameters available. In fact, 'draw_all' provides
296
the plot area coordinates as an additional parameter, but we don't need that
297
here so we do not have to include that in the function declaration.
298
</p><pre class="programlisting">function annotate_plot($img, $plot)
299
{
300
</pre><p>
301
</p><p>
302
As stated above, you should allocate your own colors, rather than trying to
303
get into PHPlot's internals for color values. Here we allocate two colors
304
and assign the color indexes to local variables:
305
</p><pre class="programlisting">$red = imagecolorresolve($img, 255, 0, 0);
306
$green = imagecolorresolve($img, 0, 216, 0);
307
</pre><p>
308
</p><p>
309
Next, we want to draw graphics centered on two points in our data. The
310
points were calculated as best_index (X), best_sales (Y), worst_index (X),
311
and worst_sales (Y). In order to draw at these locations, we need to
312
translate the values from
313
<a class="link" href="concepts.html#def-worldcoor">World Coordinates</a> to
314
<a class="link" href="concepts.html#def-devcoor">Device Coordinates</a>.
315
This is done using the PHPlot function <a class="xref" href="GetDeviceXY.html" title="GetDeviceXY"><span class="refentrytitle">GetDeviceXY</span></a>.
316
</p><pre class="programlisting">list($best_x, $best_y) = $plot-&gt;GetDeviceXY($best_index, $best_sales);
317
list($worst_x, $worst_y) = $plot-&gt;GetDeviceXY($worst_index, $worst_sales);
318
</pre><p>
319
</p><p>
320
Now we are ready to draw some ellipses, centered on our two data points.
321
The values 50 and 20 are the width and height, in pixels.
322
</p><pre class="programlisting">imageellipse($img, $best_x, $best_y, 50, 20, $green);
323
imageellipse($img, $worst_x, $worst_y, 50, 20, $red);
324
</pre><p>
325
</p><p>
326
As stated above, we have two options for text, and the example uses each method.
327
We can draw text using the GD functions, but we have to do a little more
328
work to position the text. Here the text is approximately centered
329
horizontally and above the data point. (Note ImageString by default uses the
330
upper left corner of the text string for positioning.)
331
</p><pre class="programlisting">$font = '3';
332
$fh = imagefontheight($font);
333
$fw = imagefontwidth($font);
334
imagestring($img, $font, $best_x-$fw*4, $best_y-$fh-10, 'Good Job!', $green);
335
</pre><p>
336
</p><p>
337
Or, we can use the PHPlot internal function <a class="xref" href="dev-internal.html#DrawText">DrawText</a>.
338
With a PHPlot version 5.1.0 and later, we omit the font specification
339
and it will default to the generic font, which can be set with
340
<a class="xref" href="SetFont.html" title="SetFont"><span class="refentrytitle">SetFont</span></a>('generic', ...)
341
</p><pre class="programlisting">$plot-&gt;DrawText('', 0, $worst_x, $worst_y-10, $red, 'Bad News!', 'center', 'bottom');
342
</pre><p>
343
</p></div></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="adv-truecolor.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="advanced.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="adv-datacolor-callback.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">4.3. Truecolor Images </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> 4.5. Custom Data Color Selection</td></tr></table></div></body></html>