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>3.6. Labels</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="concepts.html" title="Chapter 3. PHPlot Concepts" /><link rel="prev" href="conc-colors.html" title="3.5. Colors" /><link rel="next" href="conc-otherelements.html" title="3.7. Other Plot Elements" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">3.6. Labels</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="conc-colors.html">Prev</a> </td><th width="60%" align="center">Chapter 3. PHPlot Concepts</th><td width="20%" align="right"> <a accesskey="n" href="conc-otherelements.html">Next</a></td></tr></table><hr /></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="conc-labels"></a>3.6. Labels</h2></div></div></div><div class="abstract"><p class="title"><strong></strong></p><p>
3 
This section contains information about creating labels which identify data
4 
values on the plot.
5 
For a list of functions used to control labels,
6 
see <a class="xref" href="ref-labels.html" title="6.11. Labels">Section 6.11, &#8220;Labels&#8221;</a>.
7 
  </p></div><p>
8 
Several types of labels are available in PHPlot:
9 
  </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
10 
Tick labels identify the values at the tick positions.
11 
There are X tick labels and Y tick labels.
12 
      </p></li><li class="listitem"><p>
13 
Axis data labels display the label values from your data array.
14 
X axis data labels are available for vertical plots, and
15 
Y axis data labels are available for horizontal plots.
16 
      </p></li><li class="listitem"><p>
17 
Data value labels display the actual value of a data point.
18 
These are available only for some plot types.
19 
Y data value labels are available for vertical plots, and
20 
X data value labels are available for horizontal plots.
21 
      </p></li><li class="listitem"><p>
22 
Pie chart data labels identify the pie segments. By default, they show the
23 
percentage of each pie segment.
24 
      </p></li></ul></div><p>
25 
</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
26 
The term <span class="emphasis"><em>data label</em></span> is often used to refer to both axis
27 
data labels and data value labels. The same PHPlot functions are used
28 
to configure axis data labels and data value labels.
29 
  </p></div><p>
30 
 
31 
Here is a sample plot with the Y tick labels and X axis data labels called out.
32 
</p><div class="informalfigure"><div class="mediaobject"><img src="images/labels.png" alt="Tick labels and Data labels on a plot" /></div></div><p>
33 
</p><p>
34 
 
35 
Here is a sample plot with the pie chart labels called out.
36 
</p><div class="informalfigure"><div class="mediaobject"><img src="images/labels-pie.png" alt="Pie chart data labels" /></div></div><p>
37 
</p><p>
38 
 
39 
Here is a sample vertical bar plot with the Y tick labels,
40 
Y data value labels, and X axis data labels called out.
41 
</p><div class="informalfigure"><div class="mediaobject"><img src="images/labels-bar.png" alt="Tick labels, Data labels, and Data Value labels on a plot" /></div></div><p>
42 
</p><p>
43 
 
44 
Here is a sample horizontal bar plot with the Y (axis) data labels,
45 
X data value labels, and X tick labels called out.
46 
</p><div class="informalfigure"><div class="mediaobject"><img src="images/labels-horizbar.png" alt="Tick labels, Data labels, and Data Value labels on a plot" /></div></div><p>
47 
</p><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="conc-labels-tick"></a>3.6.1. Tick Labels</h3></div></div></div><p>
48 
Tick labels identify the X or Y values at tick positions (even if the tick
49 
marks themselves are not drawn).
50 
See <a class="xref" href="conc-otherelements.html#conc-ticks" title="3.7.4. Tick Marks">Section 3.7.4, &#8220;Tick Marks&#8221;</a> for information about the tick positions.
51 
</p><p>
52 
Note that even with data type 'data-data', where explicit independent
53 
variable values for the data are supplied, the tick positions and labels
54 
along that axis are still calculated automatically (unless modified by the
55 
available functions).
56 
For example, for vertical plots, your supplied X values in the
57 
data array are not used for the X tick labels.
58 
</p><p>
59 
You can enable, disable, or position the tick labels with
60 
<a class="xref" href="SetXTickLabelPos.html" title="SetXTickLabelPos"><span class="refentrytitle">SetXTickLabelPos</span></a> and <a class="xref" href="SetYTickLabelPos.html" title="SetYTickLabelPos"><span class="refentrytitle">SetYTickLabelPos</span></a>.
61 
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="conc-labels-data"></a>3.6.2. Axis Data Labels</h3></div></div></div><p>
62 
Axis data labels are available for the independent variable axis. This is X
63 
for vertical plots, and Y for horizontal plots.
64 
These data labels are supplied in your data array for each data point.
65 
For example, with data type text-data :
66 
</p><pre class="programlisting">$data = array( array('Peaches',100),
67 
               array('Apples', 140),
68 
               array('Pears', 90));
69 
</pre><p>
70 
The three points have data labels 'Peaches', 'Apples', and 'Pears'.
71 
For vertical plots, these data labels will be drawn at the bottom of the plot
72 
(by default) below the corresponding X values.
73 
For horizontal plots, these data labels will be drawn to the left of the plot
74 
(by default), to the left of the corresponding Y values.
75 
You can disable or reposition the data labels with
76 
<a class="xref" href="SetXDataLabelPos.html" title="SetXDataLabelPos"><span class="refentrytitle">SetXDataLabelPos</span></a> and
77 
<a class="xref" href="SetYDataLabelPos.html" title="SetYDataLabelPos"><span class="refentrytitle">SetYDataLabelPos</span></a>.
78 
</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
79 
The axis data labels are not necessarily drawn along axis lines. They are
80 
usually drawn along the bottom (for X) or left side (for Y) of the plot.
81 
Although these are also the usual positions for the X axis and Y axis, the
82 
actual axis lines may be drawn elsewhere.
83 
See <a class="xref" href="SetXAxisPosition.html" title="SetXAxisPosition"><span class="refentrytitle">SetXAxisPosition</span></a> or <a class="xref" href="SetYAxisPosition.html" title="SetYAxisPosition"><span class="refentrytitle">SetYAxisPosition</span></a>
84 
for more information on axis positions.
85 
  </p></div><p>
86 
You will generally not want both tick labels and axis data labels on,
87 
because they will overlap and be unreadable. If you are not using data
88 
labels, you should either make them all empty strings in your data array,
89 
or else use <a class="xref" href="SetXDataLabelPos.html" title="SetXDataLabelPos"><span class="refentrytitle">SetXDataLabelPos</span></a>('none') (for vertical plots)
90 
or <a class="xref" href="SetYDataLabelPos.html" title="SetYDataLabelPos"><span class="refentrytitle">SetYDataLabelPos</span></a>('none') (for horizontal plots)
91 
to turn them off.
92 
You can also call <a class="xref" href="SetXTickLabelPos.html" title="SetXTickLabelPos"><span class="refentrytitle">SetXTickLabelPos</span></a> (for vertical plots)
93 
or <a class="xref" href="SetYTickLabelPos.html" title="SetYTickLabelPos"><span class="refentrytitle">SetYTickLabelPos</span></a> (for horizontal plots)
94 
to explicitly position the tick labels.
95 
PHPlot will then disable the data labels.
96 
</p><p>
97 
If you don't tell PHPlot what to do with data and tick labels,
98 
the behavior depends on the PHPlot version.
99 
PHPlot 5.1.0 and later will examine your data array to see if there are any
100 
non-empty data labels, and if so it will draw only data labels, and omit
101 
tick labels.
102 
If all of the labels in your data array are empty, tick labels will be drawn.
103 
(PHPlot through 5.0.7 will draw both tick and data labels in these cases.)
104 
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="conc-labels-datavalue"></a>3.6.3. Data Value Labels</h3></div></div></div><p>
105 
Data value labels are available only for some plot types.
106 
These are displayed inside the plot, and show the value at
107 
each data point, bar, or bar segment.
108 
</p><p>
109 
For vertical bar charts, Y data value labels indicate the Y value for each
110 
bar, and are drawn above the bar for positive values, or below the bar for
111 
negative values.
112 
For vertical stackedbar charts, Y data value labels indicate the total Y
113 
value for each stack, and optionally indicate the value of each segment.
114 
Use <a class="xref" href="SetYDataLabelPos.html" title="SetYDataLabelPos"><span class="refentrytitle">SetYDataLabelPos</span></a> to enable Y data value labels.
115 
</p><p>
116 
For horizontal bar charts, X data value labels indicate the X value for each
117 
bar, and are drawn to the left or right of the end of the bar.
118 
For horizontal stackedbar charts, X data value labels indicate the total X
119 
value for each stack, and optionally indicate the value of each segment.
120 
Use <a class="xref" href="SetXDataLabelPos.html" title="SetXDataLabelPos"><span class="refentrytitle">SetXDataLabelPos</span></a> to enable X data value labels.
121 
</p><p>
122 
Y data value labels are also available for vertical plots of types
123 
lines, linepoints, points, and squared (starting in PHPlot-5.3.0).
124 
X data value labels are available for horizontal plots of types
125 
lines, linepoints, and points (starting in PHPlot-6.0.0).
126 
The data value labels indicate the value of each point and are displayed
127 
(by default) above each point.
128 
Use <a class="xref" href="SetYDataLabelPos.html" title="SetYDataLabelPos"><span class="refentrytitle">SetYDataLabelPos</span></a> to enable Y data value labels for
129 
these vertical plots, and <a class="xref" href="SetXDataLabelPos.html" title="SetXDataLabelPos"><span class="refentrytitle">SetXDataLabelPos</span></a> to enable X
130 
data value labels for these horizontal plots.
131 
PHPlot does not attempt to prevent interference between the labels and
132 
other plot elements.
133 
To change the position of the labels, see <a class="xref" href="adv-tuning.html#adv-tuning-labels" title="4.7.7. Tuning Labels">Section 4.7.7, &#8220;Tuning Labels&#8221;</a>.
134 
</p><p>
135 
Data value labels are not available with other plot types.
136 
</p><p>
137 
  </p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
138 
The same function is used to position X axis data labels and X data value
139 
labels, and the same function is used to position Y axis data labels and Y data
140 
value labels. There is no ambiguity, because one type of label is available
141 
for each axis for vertical plots, and the other type for horizontal plots.
142 
    </p></div><p>
143 
</p><p>
144 
<a class="xref" href="ex-bars4.html#example-bars4" title="Example 5.19. Bar Chart with Data Value Labels">Example 5.19, &#8220;Bar Chart with Data Value Labels&#8221;</a> shows a vertical bar chart
145 
with Y data value labels.
146 
<a class="xref" href="ex-stackedbars3.html#example-stackedbars3" title="Example 5.20. Stacked Bars with Y Data Value Labels">Example 5.20, &#8220;Stacked Bars with Y Data Value Labels&#8221;</a> shows a vertical stacked bar chart
147 
with Y data value labels.
148 
<a class="xref" href="ex-linepoints2.html#example-linepoints2" title="Example 5.33. Linepoints Plot with Data Value Labels">Example 5.33, &#8220;Linepoints Plot with Data Value Labels&#8221;</a> shows a linepoints plot
149 
with Y data value labels.
150 
</p><p>
151 
<a class="xref" href="ex-horizbar.html#example-horizbar" title="Example 5.27. Horizontal Bar Chart">Example 5.27, &#8220;Horizontal Bar Chart&#8221;</a> shows a horizontal bar chart
152 
with X data value labels.
153 
<a class="xref" href="ex-horizstackedbar.html#example-horizstackedbar" title="Example 5.28. Horizontal Stacked Bar Chart">Example 5.28, &#8220;Horizontal Stacked Bar Chart&#8221;</a> shows a horizontal stacked bar chart
154 
with X data value labels.
155 
<a class="xref" href="ex-horizlinepts.html#example-horizlinepts" title="Example 5.48. Horizontal Linepoints Plot with Data Value Labels and Lines">Example 5.48, &#8220;Horizontal Linepoints Plot with Data Value Labels and Lines&#8221;</a> shows a horizontal linepoints plot
156 
with X data value labels.
157 
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="conc-labels-pie"></a>3.6.4. Pie Chart Labels</h3></div></div></div><p>
158 
Pie chart labels identify segments on a pie chart. By default, these
159 
show the percentage of each segment, relative to the whole pie. Starting
160 
with PHPlot-5.6.0, pie chart labels can display other information, and can
161 
be flexibly formatted.
162 
</p><p>
163 
Use <a class="xref" href="SetPieLabelType.html" title="SetPieLabelType"><span class="refentrytitle">SetPieLabelType</span></a> to select the source for pie labels
164 
as well as how to format them.
165 
<a class="xref" href="ex-pielabeltype.html#example-pielabeltype" title="Example 5.41. Pie Chart Label Types">Example 5.41, &#8220;Pie Chart Label Types&#8221;</a> shows a pie chart with different
166 
labeling options.
167 
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="conc-labels-format"></a>3.6.5. Formatting Labels</h3></div></div></div><p>
168 
Tick labels, data labels, and pie chart labels are subject to format controls.
169 
There are several choices in formatting.  By default, the label value itself
170 
is simply displayed.
171 
Use <a class="xref" href="SetXLabelType.html" title="SetXLabelType"><span class="refentrytitle">SetXLabelType</span></a> and <a class="xref" href="SetYLabelType.html" title="SetYLabelType"><span class="refentrytitle">SetYLabelType</span></a> to
172 
select one of the other format types for tick labels.
173 
Use <a class="xref" href="SetXDataLabelType.html" title="SetXDataLabelType"><span class="refentrytitle">SetXDataLabelType</span></a> and
174 
<a class="xref" href="SetYDataLabelType.html" title="SetYDataLabelType"><span class="refentrytitle">SetYDataLabelType</span></a> to select one of the other format
175 
types for data labels (both axis data labels and data value labels).
176 
(Note that SetXLabelType also sets the default format for X data labels,
177 
for use if SetXDataLabelType is not called.
178 
Also SetYLabelType sets the default for Y data labels, for use if
179 
SetYDataLabelType is not called.)
180 
Use <a class="xref" href="SetPieLabelType.html" title="SetPieLabelType"><span class="refentrytitle">SetPieLabelType</span></a> to select a format type for pie chart
181 
labels.
182 
</p><p>
183 
The following sections contain details of the available formatting types.
184 
More examples can be found in the reference page for
185 
<a class="xref" href="SetXLabelType.html" title="SetXLabelType"><span class="refentrytitle">SetXLabelType</span></a>.
186 
</p><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a id="conc-labels-format-data"></a>3.6.5.1. Formatting Labels: 'data' type</h4></div></div></div><p>
187 
Label format type 'data' expects the tick label, data label, or pie label
188 
values to be numbers, and formats the values as floating point numbers with
189 
a separator between every group of thousands and a fixed number of decimal
190 
places.  You can set the number of digits of precision, with the default
191 
being 1 digit. You can also set a prefix and/or suffix string (such as a
192 
currency symbol or percent sign).
193 
PHPlot will try to set the thousands grouping separator and
194 
decimal separator according to your locale, but this can be overridden if
195 
necessary.
196 
</p><p>
197 
For example:
198 
  </p><pre class="programlisting">$plot-&gt;SetYLabelType('data', 2, '$');
199 
</pre><p>
200 
This might format the value 1234.567 as "$1,234.57" (depending on locale).
201 
</p></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a id="conc-labels-format-time"></a>3.6.5.2. Formatting Labels: 'time' type</h4></div></div></div><p>
202 
Label format type 'time' expects the tick or data label values to be a PHP time
203 
value (number of seconds since a fixed base data, the Unix Epoch).
204 
PHPlot will format the labels according to the format string you provide.
205 
Refer to the PHP documentation for <code class="function">strftime()</code> for
206 
details on the format string.
207 
</p><p>
208 
For example:
209 
  </p><pre class="programlisting">$plot-&gt;SetXLabelType('time', $format);
210 
</pre><p>
211 
If a label value is the numeric equivalent of "31 December 2004 at 1:23:45 pm"
212 
(which is 1104517425 on some platforms), the following table shows some
213 
examples of the result with different values of $format:
214 
</p><div class="informaltable"><table summary="Date/time format examples" border="1"><colgroup><col class="c1" /><col class="c2" /></colgroup><thead><tr><th>$format:</th><th>Result:</th></tr></thead><tbody><tr><td>%Y-%m-%d</td><td>2004-12-31</td></tr><tr><td>%b %Y</td><td>Dec 2004</td></tr><tr><td>%b %d, %Y</td><td>Dec 31, 2004</td></tr><tr><td>%d %b</td><td>31 Dec</td></tr><tr><td>%H:%M:%S</td><td>13:23:45</td></tr></tbody></table></div><p>
215 
(This formatting type is generally not applicable to pie chart labels.)
216 
</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
217 
If you select 'time' formatting, but don't set a time format string,
218 
PHPlot-5.0rc3 and higher will format the values as hours, minutes, and
219 
seconds as shown in the last row of the table above.
220 
(The default format was undefined before version 5.0rc3.)
221 
  </p><p>
222 
Also note that there are limits to the range of this type of formatting
223 
that can make it unusable for historical data. On some platforms, dates
224 
before 1970-01-01 can not be formatted.
225 
  </p><p>
226 
Starting with PHPlot-5.0.4, empty string values for data labels are
227 
ignored for 'time' and 'data' formatting. Earlier versions would format
228 
the labels as 0 (for 'data') or cause an error (for 'time').
229 
  </p></div><p>
230 
While date/time formatting can be useful, for X values it may be
231 
easier to just format the label values in your PHP code and put the result
232 
into the label positions in the data array. If you need date/time formatting for
233 
Y values (and it is hard to imagine where that would be useful), you have
234 
no option but to use the 'time' format labels for tick values.
235 
</p></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a id="conc-labels-format-printf"></a>3.6.5.3. Formatting Labels: 'printf' type</h4></div></div></div><p>
236 
Label format type 'printf' expects one, two, or three additional
237 
arguments specifying <code class="function">printf</code> format strings,
238 
and formats the label value according to the format string(s).
239 
If a single format string is given, it is used for the label values.
240 
The format string must contain exactly one conversion specification
241 
(%-code) which consumes a single argument.
242 
For example:
243 
  </p><pre class="programlisting">$plot-&gt;SetYLabelType('printf', '%8.2e parsecs');
244 
</pre><p>
245 
This might produce a label like " 1.23e+8 parsecs".
246 
</p><p>
247 
If two format strings are provided, the first is used to format the value
248 
of the label if it is greater than or equal to zero. The second format
249 
string is used to format the absolute value of the label if the label value
250 
is less than zero.
251 
</p><p>
252 
If three format strings are provided, the first is used to format the value
253 
of the label if it is greater than zero. The second format string is used to
254 
format the absolute value of the label if the label value is less than zero.
255 
The third is used to format the value of the label if it is zero. In some
256 
applications, it may be appropriate to use an empty string as the third
257 
format string, which will suppress the display of labels with a value of zero.
258 
</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
259 
Support for using two or three 'printf' format strings was added
260 
in PHPlot-6.2.0.
261 
When using 2 or 3 'printf' format strings, the labels being formatted must
262 
be numeric values.
263 
  </p></div></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a id="conc-labels-format-custom"></a>3.6.5.4. Formatting Labels: 'custom' type</h4></div></div></div><p>
264 
A user-defined function can be provided to format labels. Specify
265 
formatting type 'custom', and provide the name of your function as
266 
a string. (This is actually a PHP <span class="emphasis"><em>callback</em></span> type
267 
argument, which can also be an array containing an object and a method
268 
name. See the PHP documentation on callbacks for more details.)
269 
You can provide an additional argument which will be passed
270 
to your function when formatting labels (a
271 
<span class="emphasis"><em>pass-through</em></span> argument).
272 
</p><p>
273 
In this example, the user-provided function is called
274 
<code class="function">my_formatter</code>, and you want an additional argument $data
275 
passed to the function.
276 
  </p><pre class="programlisting">$plot-&gt;SetYLabelType('custom', 'my_formatter', $data);
277 
</pre><p>
278 
</p><p>
279 
Your formatting function will accept 1 or 2 arguments (or more - see below).
280 
  </p><pre class="programlisting">function my_formatter($label, $arg)
281 
{
282 
    ...
283 
    return $some_result;
284 
}
285 
</pre><p>
286 
The function will be called with $label set to the value of the label to be
287 
formatted, and is expected to return the formatted label text. $arg is a
288 
pass-through argument that has whatever value you used with
289 
<code class="function">SetXLabelType</code> (etc.). In the above example, this is
290 
$data. You need to declare this second argument in your function only if
291 
you are using a pass-through argument.
292 
</p><p>
293 
You can also use PHP anonymous functions for custom label formatting.
294 
This avoids having to define a function elsewhere in your code, and keeps
295 
the custom label formatting code near where it is being used.
296 
This is recommended only when the custom label formatting code is relatively
297 
short<a href="#ftn.idp1374419092" class="footnote" id="idp1374419092"><sup class="footnote">[3]</sup></a>.
298 
Anonymous functions can also take advantage of the PHP <code class="literal">use</code>
299 
clause to inherit variables from the parent scope.
300 
</p><p>
301 
Here is an example of a custom label formatting function that uses an
302 
anonymous function to offset the Y axis label by an amount in a local
303 
variable.
304 
  </p><pre class="programlisting">$offset = 10; // A local variable
305 
...
306 
$plot-&gt;SetYLabelType('custom', function ($y) use ($offset) {
307 
     return ($y - $offset); } );
308 
</pre><p>
309 
</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
310 
PHPlot may call your label formatting function multiple times for the same
311 
label, and your function must return the same value each time.
312 
Also, do not rely on the labels being formatted in any particular order.
313 
  </p><p>
314 
A custom label formatting function will not be called at all if the
315 
label value is an empty string (<code class="literal">''</code>).
316 
This generally only applies to axis data labels (the label strings in
317 
your data array), since others are numbers.
318 
This means you cannot use custom label formatting to replace an empty
319 
string with something else. The custom label formatting function
320 
will be called if the label string is anything other than an empty
321 
string, such as a string with single space.
322 
  </p></div><p>
323 
Custom label formatting is extremely flexible. You can convert values into
324 
another format (for example, degrees, minutes, seconds), or look up values
325 
in an external array (see <a class="xref" href="ex-bubbles1.html" title="5.40. Example - Bubbles Plot">Section 5.40, &#8220;Example - Bubbles Plot&#8221;</a>), for example.
326 
However, using this method, you can only selectively format or display labels
327 
based on their value. For even more control, use the additional arguments
328 
provided to the formatting function which are described in the next section.
329 
</p></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a id="conc-labels-format-custom2"></a>3.6.5.5. Formatting Labels: Extended 'custom' type</h4></div></div></div><p>
330 
When you use 'custom' formatting type, PHPlot actually provides 0, 1, or 2
331 
additional arguments to your callback. These identify the row, or row and
332 
column, of the data point being labeled. You can use these extra arguments
333 
in your callback for selective formatting or filtering based on the
334 
position of the point being plotted in your data array.
335 
</p><p>
336 
PHPlot provides the following additional arguments to a custom label
337 
formatting callback (after the label value and pass-through arguments):
338 
</p><div class="informaltable"><table summary="Custom formatting callback arguments" border="1"><colgroup><col class="c1" /><col class="c2" /></colgroup><thead><tr><th>Label:</th><th>Arguments Provided:</th></tr></thead><tbody><tr><td>Tick Labels</td><td>(None)</td></tr><tr><td>Axis Data Labels</td><td>$row</td></tr><tr><td>Data Value Labels (other than stackedbars total labels)</td><td>$row, $column</td></tr><tr><td>stackedbars data value labels for bar totals</td><td>$row</td></tr></tbody></table></div><p>
339 
</p><p>
340 
You need not declare these arguments unless you are using them, but if you
341 
do declare them, it is safer to make them optional with default NULL.
342 
(If you are only using the custom callback function for one specific type of
343 
label, you can omit the defaults.)
344 
For example:
345 
  </p><pre class="programlisting">function my_formatter($label, $arg, $row=NULL, $column=NULL)
346 
{
347 
    ...
348 
    return $some_result;
349 
}
350 
</pre><p>
351 
</p><p>
352 
The <span class="emphasis"><em>row</em></span> argument value is an index starting with zero
353 
that numbers the rows in your data array. This corresponds to the ordinal
354 
position of the independent variable (X for vertical plots, Y for
355 
horizontal plots). This is also the outer index of your data array.
356 
</p><p>
357 
The <span class="emphasis"><em>column</em></span> argument value is an index starting with zero
358 
that numbers the data sets in each row. This corresponds to the ordinal
359 
position of the dependent variable (Y for vertical plots, X for
360 
horizontal plots). Note that this is not simply the inner index of your
361 
data array, because the data array rows also have labels, and (depending on
362 
the data type) may contain other values.
363 
For example, given the data type <code class="literal">data-data</code> and this data
364 
array:
365 
  </p><pre class="programlisting">$data = array(
366 
    array('Jan', 1,  10, 11, 12),
367 
    array('Feb', 2,  20, 21, 22),
368 
    array('Mar', 3,  30, 31, 32),
369 
);
370 
</pre><p>
371 
When formatting a data value label for X=2, Y=22 (the 3rd data set in
372 
the row labeled 'Feb'), PHPlot will call a custom label formatting function
373 
like this:
374 
  </p><pre class="programlisting">my_formatter(22, $passthrough, 1, 2);
375 
</pre><p>
376 
That is, row=1 and column=2.
377 
</p><p>
378 
As described in <a class="xref" href="conc-labels.html#conc-labels-format-custom" title="3.6.5.4. Formatting Labels: 'custom' type">Section 3.6.5.4, &#8220;Formatting Labels: 'custom' type&#8221;</a>, your callback
379 
function returns the value of the formatted label. You can return an empty
380 
string to display no label. This can be used to display data value labels
381 
for only one data set, for example - just return an empty string if $column
382 
is not equal to the index of the data set you want to label.
383 
</p><p>
384 
See <a class="xref" href="ex-dlexformat.html" title="5.43. Example - Custom Data Value Label Formatting">Section 5.43, &#8220;Example - Custom Data Value Label Formatting&#8221;</a> for an example.
385 
</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
386 
These additional row and column arguments are only available
387 
starting with PHPlot-5.8.0.
388 
  </p></div></div></div><div class="footnotes"><br /><hr style="width:100; text-align:left;margin-left: 0" /><div id="ftn.idp1374419092" class="footnote"><p><a href="#idp1374419092" class="para"><sup class="para">[3] </sup></a>You can't do unit testing on an anonymous
389 
function.</p></div></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="conc-colors.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="concepts.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="conc-otherelements.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">3.5. Colors </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> 3.7. Other Plot Elements</td></tr></table></div></body></html>