| 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, “Object Methods as Callbacks”</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, “Available Callbacks”</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->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, “Available Callbacks”</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, “Custom Data Color Selection”</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, “Object Methods as Callbacks”</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, “Custom Data Color Selection”</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, “Image Maps for Plot Data”</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 => 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, “Using Callbacks to Annotate Plots”</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->plot_area[0]}, {$this->plot_area[1]}) :");
|
|
|
150 |
fwrite(STDERR, " ({$this->plot_area[2]}, {$this->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->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->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, “Example - Annotating a Plot Using a Callback”</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, “Available Callbacks”</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, “Example - Annotating a Plot Using a Callback”</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->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, “Callbacks Application Interface”</a> for more on these options.
|
|
|
288 |
</p><pre class="programlisting">$plot->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->GetDeviceXY($best_index, $best_sales);
|
|
|
317 |
list($worst_x, $worst_y) = $plot->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->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>
|