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>10.2. Member Variable Notes</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="dev-vars.html" title="Chapter 10. PHPlot Class Member Variables" /><link rel="prev" href="dev-vars.html" title="Chapter 10. PHPlot Class Member Variables" /><link rel="next" href="dev-const.html" title="10.3. PHPlot Class Constants" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">10.2. Member Variable Notes</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="dev-vars.html">Prev</a> </td><th width="60%" align="center">Chapter 10. PHPlot Class Member Variables</th><td width="20%" align="right"> <a accesskey="n" href="dev-const.html">Next</a></td></tr></table><hr /></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="dev-var-notes"></a>10.2. Member Variable Notes</h2></div></div></div><div class="abstract"><p class="title"><strong></strong></p><p>
3
This section contains details on some of the PHPlot class member variables
4
listed in the previous section.
5
Remember that all PHPlot class member variables are meant for internal use only.
6
  </p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="var-datatypes"></a>10.2.1. datatypes[]</h3></div></div></div><p>
7
The <code class="varname">datatypes[]</code> array contains information about the
8
available data types. See <a class="xref" href="conc-datatypes.html" title="3.3. PHPlot Data Types">Section 3.3, &#8220;PHPlot Data Types&#8221;</a> for more
9
information about data types.
10
It is used by <a class="xref" href="SetDataType.html" title="SetDataType"><span class="refentrytitle">SetDataType</span></a> to validated the supplied data
11
type, and by <a class="xref" href="dev-internal.html#DecodeDataType">DecodeDataType</a> to set the flags that
12
describe the datatype.
13
</p><p>
14
The goal is to keep the names and details about the data types in this
15
array only, and minimize other uses of the actual data type names. However,
16
each plot type drawing function (for example <a class="xref" href="dev-internal.html#DrawLines">DrawLines</a>)
17
also 'knows' about the data types it supports, and specifies the data type
18
names when calling <a class="xref" href="dev-internal.html#CheckDataType">CheckDataType</a>.
19
</p><p>
20
This array was added in PHPlot-6.1.0.
21
It is a protected static member variable in the PHPlot class, so it must be
22
accessed as <code class="varname">self::$datatypes</code> from inside the class (or a
23
derived class), and not through an instance of the class.
24
Is not accessible from outside the class or derived classes.
25
</p><p>
26
The array keys are the data types (for example: 'text-data').
27
The values are arrays which contain information about the data type.
28
The second-level array keys correspond to the 'datatype' flag variables,
29
without the 'datatype_' prefix. A key will be present, with the value
30
<code class="literal">TRUE</code>, if the flag should be set for that data type.
31
The key will be absent if the flag should not be set.
32
For example: for data type <code class="literal">text-data</code>, the array contains
33
one value: <code class="literal">'implied' =&gt; TRUE</code>. This means that for
34
data type text-data, the <code class="literal">datatype_implied</code> flag should be
35
TRUE (indicating that this data type has implied independent variable
36
values), and all other flags should be FALSE. In addition to
37
<code class="literal">implied</code>, the other possible keys are
38
<code class="literal">pie_single</code>, <code class="literal">error_bars</code>,
39
<code class="literal">swapped_xy</code>, and <code class="literal">yz</code>.
40
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="var-fonts"></a>10.2.2. fonts[]</h3></div></div></div><p>
41
 
42
The <code class="varname">fonts[]</code> array contains information about the fonts to
43
use for text on the plot. The array keys are the element names (such as
44
<code class="literal">title</code> or <code class="literal">legend</code>) as used in
45
<a class="xref" href="SetFont.html" title="SetFont"><span class="refentrytitle">SetFont</span></a>, <a class="xref" href="SetFontGD.html" title="SetFontGD"><span class="refentrytitle">SetFontGD</span></a>, or
46
<a class="xref" href="SetFontTTF.html" title="SetFontTTF"><span class="refentrytitle">SetFontTTF</span></a>. The array values are arrays which contain
47
information about the font to use for that element. The keys and values of
48
the second-level arrays are:
49
 
50
</p><div class="informaltable"><table summary="fonts[] array elements" border="1"><colgroup><col class="c1" /><col class="c2" /><col class="c3" /></colgroup><thead><tr><th>Key</th><th>Value for TTF</th><th>Value for GD Font</th></tr></thead><tbody><tr><td>ttf</td><td>True for a TrueType font</td><td>False for a GD font</td></tr><tr><td>font</td><td>Pathname of the font file</td><td>Font number: 1 through 5</td></tr><tr><td>size</td><td>Font point size</td><td>Not used</td></tr><tr><td>height</td><td>Height in pixels of an upper-case "E" in the font</td><td>Font height in pixels</td></tr><tr><td>width</td><td>Width in pixels of an upper-case "E" in the font</td><td>Font width in pixels</td></tr><tr><td>spacing</td><td>Font's built-in inter-line spacing</td><td>Not used</td></tr><tr><td>line_spacing</td><td>User-requested inter-line spacing factor.</td><td>Same as for TTF</td></tr></tbody></table></div><p>
51
</p><p>
52
For TrueType fonts, the height and width can vary by character. The fonts
53
array stores a height and width value for the font, but these are only used
54
for sizing non-text plot elements (such as the legend color boxes). When
55
PHPlot needs to know the drawn size of a string that will use TTF, it calculates
56
the exact size of that specific string when drawn with the designated font.
57
</p><p>
58
GD fonts have fixed character width and height, so the values stored in
59
the fonts array can be used to calculate text string sizes.
60
</p><p>
61
The <code class="literal">spacing</code> key stores the TrueType font's built-in
62
inter-line spacing. Although TrueType fonts have this information
63
internally, PHP cannot access it, so PHPlot calculates it by taking the
64
height of the string "E\nE" and subtracting twice the height of the letter E.
65
</p><p>
66
The <code class="literal">line_spacing</code> key stores the user-specified line spacing
67
adjustment for a text element, if any, from <a class="xref" href="SetFont.html" title="SetFont"><span class="refentrytitle">SetFont</span></a> or
68
one of the two related functions. It will be NULL if the spacing was
69
not set for this element, meaning use the default line spacing.
70
See <a class="xref" href="SetLineSpacing.html" title="SetLineSpacing"><span class="refentrytitle">SetLineSpacing</span></a> for more information on how this is used.
71
</p><p>
72
Here is an example of part of a fonts array, for the title element:
73
</p><pre class="programlisting">$plot-&gt;fonts['title'] = array(
74
    'ttf' =&gt; FALSE,          // This element uses a GD font
75
    'font' =&gt; 2,             // Use GD font 2
76
    'height' =&gt; 13,          // Provided by GD
77
    'width' =&gt; 6,            // Provided by GD
78
    'line_spacing' =&gt; NULL,  // Use default line spacing
79
)
80
</pre><p>
81
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="var-label-format"></a>10.2.3. label_format[]</h3></div></div></div><p>
82
The <code class="varname">label_format[]</code> array contains information about how
83
text labels should be formatted. This array has 5 entries, with keys 'x',
84
'y', 'xd', 'yd', and 'p'. The 'x' and 'y' entries are for tick labels, and the
85
'xd' and 'yd' entries are for data labels. (Note that PHPlot defaults data
86
label formatting to match tick label formatting, but this is handled in
87
<a class="xref" href="dev-internal.html#FormatLabel">FormatLabel</a>.)
88
The 'p' entry is for pie chart labels, and will only exist for pie charts.
89
(The 'p' entry was added in PHPlot-5.6.0.)
90
</p><p>
91
 
92
The value of each entry in <code class="varname">label_format</code> is an array
93
containing formatting information. The arrays are empty by default, meaning
94
there is no special formatting. If formatting has been enabled, for example
95
with <a class="xref" href="SetXLabelType.html" title="SetXLabelType"><span class="refentrytitle">SetXLabelType</span></a>, the arrays can contain the following
96
keys and values:
97
 
98
</p><div class="informaltable"><table summary="label_format[] array elements" border="1"><colgroup><col class="c1" /><col class="c2" /><col class="c3" /></colgroup><thead><tr><th>Key</th><th>Used with type</th><th>Value</th></tr></thead><tbody><tr><td>type</td><td> </td><td>Formatting type: data, time, printf, or custom.</td></tr><tr><td>precision</td><td>data</td><td>The number of decimal positions to produce.</td></tr><tr><td>prefix</td><td>data</td><td>A prefix string to append to the label (for example, a currency
99
            sign).</td></tr><tr><td>suffix</td><td>data</td><td>A suffix string to append to the label (for example, a currency
100
           sign or percent sign).
101
           This replaces data_units_text (which still works too).</td></tr><tr><td>time_format</td><td>time</td><td>The date/time format string for the PHP strftime()
102
            function.</td></tr><tr><td>printf_format</td><td>printf</td><td>The format string(s) for the PHP printf() function.
103
           This can be a single string, or an array of one to three strings.
104
           </td></tr><tr><td>custom_callback</td><td>custom</td><td>The function (or array with object and method name) to call to
105
            format the label.</td></tr><tr><td>custom_arg</td><td>custom</td><td>An additional argument to pass to the custom_callback
106
            function.</td></tr></tbody></table></div><p>
107
</p><p>
108
Use of multiple strings for <code class="literal">printf_format</code> was added in
109
PHPlot-6.2.0.
110
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="var-legendpos"></a>10.2.4. legend_pos[]</h3></div></div></div><p>
111
The <code class="varname">legend_pos[]</code> array contains information about
112
positioning of the legend. This is set by <a class="xref" href="SetLegendPosition.html" title="SetLegendPosition"><span class="refentrytitle">SetLegendPosition</span></a>,
113
and by the functions which use it (<a class="xref" href="SetLegendPixels.html" title="SetLegendPixels"><span class="refentrytitle">SetLegendPixels</span></a> and
114
<a class="xref" href="SetLegendWorld.html" title="SetLegendWorld"><span class="refentrytitle">SetLegendWorld</span></a>).
115
This was added in PHPlot-5.4.0, replacing scalar variables legend_x_pos,
116
legend_y_pos, and legend_xy_world.
117
</p><p>
118
 
119
The array keys correspond to the arguments to
120
<a class="xref" href="SetLegendPosition.html" title="SetLegendPosition"><span class="refentrytitle">SetLegendPosition</span></a> and are shown in the following table.
121
</p><div class="informaltable"><table summary="legend_pos[] array elements" border="1"><colgroup><col class="c1" /><col class="c2" /></colgroup><thead><tr><th>Keys</th><th>Value</th></tr></thead><tbody><tr><td>x, y</td><td>Relative coordinates of a point on the legend box</td></tr><tr><td>mode</td><td>One of: image, plot, title, or world</td></tr><tr><td>x_base, y_base</td><td>Relative coordinates of a point on the image, plot, or
122
           title, or world coordinates</td></tr><tr><td>x_offset, y_offset</td><td>Pixel offset to be applied last</td></tr></tbody></table></div><p>
123
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="var-plots"></a>10.2.5. plots[]</h3></div></div></div><p>
124
The <code class="varname">plots[]</code> array contains information about known plot
125
types. It is used by <a class="xref" href="dev-internal.html#FindDataLimits">FindDataLimits</a>,
126
<a class="xref" href="DrawGraph.html" title="DrawGraph"><span class="refentrytitle">DrawGraph</span></a>, and other class functions to prepare for and
127
draw the main portion of the plot.
128
The goal is to contain the information about each available plot type
129
in a single place - this array. The actual names of the plot types (for
130
example 'bars' or 'linepoints') appear only in this array. To simplify
131
somewhat, adding a new plot type to PHPlot involves adding a new element to
132
the <code class="varname">plots[]</code> array, and adding a new function to PHPlot
133
which draws the 'insides' of the plot.
134
</p><p>
135
This array was added in PHPlot-5.3.0.
136
It is a protected static member variable in the PHPlot class, so it must be
137
accessed as <code class="varname">self::$plots</code> from inside the class (or a
138
derived class), and not through an instance of the class.
139
Is not accessible from outside the class or derived classes.
140
</p><p>
141
 
142
The array keys are the plot types (for example: 'bars', 'linepoints').
143
These must not include upper case letters.
144
The values are arrays which contain information about the plot type.
145
The keys and values of the second-level arrays are:
146
 
147
</p><div class="informaltable"><table summary="plots[] array elements" border="1"><colgroup><col class="c1" /><col class="c2" /></colgroup><thead><tr><th>Key</th><th>Value</th></tr></thead><tbody><tr><td>draw_method</td><td>
148
Name of the PHPlot class method (function) to call to draw the 'insides' of
149
the plot.  This is the only required entry.
150
        </td></tr><tr><td>draw_arg</td><td>
151
Optional argument array to pass to the draw_method function.
152
        </td></tr><tr><td>suppress_axes</td><td>
153
Optional flag indicating that the X axis and Y axis should not be drawn.
154
Default is FALSE.
155
        </td></tr><tr><td>abs_vals</td><td>
156
Optional flag indicating that the plot type uses the absolute values of data.
157
Default is FALSE.
158
        </td></tr><tr><td>sum_vals</td><td>
159
Optional flag indicating that the plot type sums up the values in each row.
160
Default is FALSE.
161
        </td></tr><tr><td>legend_alt_marker</td><td>
162
Optional alternate marker mode for legends: box, shape, or line.
163
        </td></tr><tr><td>adjust_type</td><td>
164
Optional control for adjusting the end of an automatically calculated plot
165
range (see notes below).
166
        </td></tr></tbody></table></div><p>
167
</p><p>
168
Only the <code class="literal">draw_method</code> entry is required.  The named method
169
is used to draw everything inside the plot area. (That is, everything except
170
the plot titles, axis lines, tick marks and tick labels, grid lines, and
171
legend.)
172
</p><p>
173
The <code class="literal">draw_arg</code> entry can be used to pass constant
174
arguments to the <code class="literal">draw_method</code> method.
175
If present, this must be an array, and each element of the array is passed to
176
the drawing method as a separate argument.  If this is not specified, the
177
drawing method is called with no arguments.  This is generally used to
178
overload drawing methods, so they handle multiple similar plot types.
179
</p><p>
180
The <code class="literal">suppress_axes</code> flag indicates that X and Y axis lines
181
should not be drawn (used with pie charts, for example).
182
If omitted, FALSE is used, meaning the axis lines are drawn.
183
(Before PHPlot-6.0.0 this was called <code class="literal">draw_axes</code>, with
184
default TRUE, and FALSE for pie charts.)
185
</p><p>
186
The two special data processing flags <code class="literal">abs_vals</code> and
187
<code class="literal">sum_vals</code> are used by <a class="xref" href="dev-internal.html#FindDataLimits">FindDataLimits</a>
188
to indicate how to compute the minimum and maximum data values.
189
Plot types that ignore sign and take absolute values of the data set
190
<code class="literal">abs_vals</code> to TRUE.
191
Plot types that sum up the data values in each row set
192
<code class="literal">sum_vals</code> to TRUE.
193
The default if omitted for both flags is FALSE, meaning the plot type
194
uses the values as specified in the data array.
195
 
196
If both <code class="literal">abs_vals</code> and <code class="literal">sum_vals</code> are TRUE,
197
this means the plot type sums up the absolute values from the data array.
198
(The stackedarea plot type does this.)
199
</p><p>
200
The optional <code class="literal">legend_alt_marker</code> entry indicates the
201
use of an alternate maker shape in legends.
202
Use <a class="xref" href="SetLegendUseShapes.html" title="SetLegendUseShapes"><span class="refentrytitle">SetLegendUseShapes</span></a> to select either the primary
203
mode or the alternate mode for legend shapes. The primary mode is a solid
204
filled color box. The alternate mode varies with the plot type, according
205
the the <code class="literal">legend_alt_marker</code> entry.
206
Use 'box' for rectangular color boxes. This is the default if the
207
<code class="literal">legend_alt_marker</code> key is omitted from the array.
208
Effectively, this means there is no alternate marker
209
mode for these plot types, because color boxes are the primary mode.
210
Use 'shape' for point shape markers, which applies to points plots and similar
211
types which use point shapes.
212
Use 'line' for short line segments, which applies to line plots and similar
213
types.
214
</p><p>
215
The optional <code class="literal">adjust_type</code> entry controls adjustments
216
made to the end of an automatically calculated plot range.
217
See <a class="xref" href="TuneXAutoRange.html" title="TuneXAutoRange"><span class="refentrytitle">TuneXAutoRange</span></a> and <a class="xref" href="TuneYAutoRange.html" title="TuneYAutoRange"><span class="refentrytitle">TuneYAutoRange</span></a>
218
for more information.
219
This is used to indicate when a plot type needs additional space, perhaps
220
for labels, between the data extrema and the edge of the plot area.
221
If omitted, the default value 0 is used.
222
A value of 0 means apply the adjustment for the dependent variable only.
223
A value of 1 means apply the adjustment for both X and Y, and a value of
224
2 means do not apply the adjustment to either X or Y.
225
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="var-rangectl"></a>10.2.6. rangectl[]</h3></div></div></div><p>
226
The <code class="varname">rangectl[]</code> array contains parameters which are used
227
to control the automatic calculation of the plot area range.
228
</p><p>
229
 
230
The array contains 2 arrays, indexed as <code class="literal">'x'</code> and
231
<code class="literal">'y'</code> for X and Y axis parameters respectively.
232
The keys and values of the second-level arrays are:
233
</p><div class="informaltable"><table summary="rangectl[] array elements" border="1"><colgroup><col class="c1" /><col class="c2" /><col class="c3" /></colgroup><thead><tr><th>Key</th><th>Default</th><th>Description</th></tr></thead><tbody><tr><td>zero_magnet</td><td>0.857142 (Note this is 6/7)</td><td>Strength of the <span class="emphasis"><em>zero magnet</em></span></td></tr><tr><td>adjust_mode</td><td>T</td><td>End adjustment mode: R, T, or I</td></tr><tr><td>adjust_amount</td><td>(Dynamic; see <a class="xref" href="dev-internal.html#GetRangeEndAdjust">GetRangeEndAdjust</a>)</td><td>Amount of end adjustment, as a fraction of the plot range</td></tr></tbody></table></div><p>
234
</p><p>
235
Values in this array are set with
236
<a class="xref" href="TuneXAutoRange.html" title="TuneXAutoRange"><span class="refentrytitle">TuneXAutoRange</span></a> and <a class="xref" href="TuneYAutoRange.html" title="TuneYAutoRange"><span class="refentrytitle">TuneYAutoRange</span></a>.
237
For more information see <a class="xref" href="adv-autorange.html#adv-autorange-params" title="4.6.4. Automatic Range Parameters">Section 4.6.4, &#8220;Automatic Range Parameters&#8221;</a>.
238
The values are used by <a class="xref" href="dev-internal.html#CalcPlotRange">CalcPlotRange</a>.
239
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="var-tickctl"></a>10.2.7. tickctl[]</h3></div></div></div><p>
240
The <code class="varname">tickctl[]</code> array contains parameters which are used
241
to control the automatic calculation of tick intervals.
242
</p><p>
243
 
244
The array contains 2 arrays, indexed as <code class="literal">'x'</code> and
245
<code class="literal">'y'</code> for X and Y axis parameters respectively.
246
The keys and values of the second-level arrays are:
247
</p><div class="informaltable"><table summary="tickctl[] array elements" border="1"><colgroup><col class="c1" /><col class="c2" /><col class="c3" /></colgroup><thead><tr><th>Key</th><th>Default</th><th>Description</th></tr></thead><tbody><tr><td>min_ticks</td><td>8</td><td>Minimum number of tick intervals</td></tr><tr><td>tick_mode</td><td>NULL (calculated)</td><td>Tick increment calculation mode: 'decimal', 'binary', or 'date'</td></tr><tr><td>tick_inc_integer</td><td>FALSE</td><td>If TRUE, force the tick increment to be a whole number</td></tr></tbody></table></div><p>
248
</p><p>
249
Values in this array are set with
250
<a class="xref" href="TuneXAutoTicks.html" title="TuneXAutoTicks"><span class="refentrytitle">TuneXAutoTicks</span></a> and <a class="xref" href="TuneYAutoTicks.html" title="TuneYAutoTicks"><span class="refentrytitle">TuneYAutoTicks</span></a>.
251
For more information see <a class="xref" href="adv-autorange.html#adv-autorange-tick-params" title="4.6.8. Automatic Tick Increment Parameters">Section 4.6.8, &#8220;Automatic Tick Increment Parameters&#8221;</a>.
252
The values are used by <a class="xref" href="dev-internal.html#CalcStep">CalcStep</a>.
253
</p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="dev-vars.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="dev-vars.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="dev-const.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 10. PHPlot Class Member Variables </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> 10.3. PHPlot Class Constants</td></tr></table></div></body></html>