git.sur5r.net Git - bacula/bacula/blob - gui/bacula-web/external_packages/phplot/doc/user_functions.html

   1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
   2 <HTML><HEAD>
   3 <TITLE>PHPlot User Functions</TITLE>
   4 </HEAD>
   5 <BODY>
   6
   7 <h2>PHPlot User Functions</h2>
   8
   9 <ul>
  10 <li><a href="#important">Important functions</a></li>
  11 <li><a href="#appearance">Appearance functions</a></li>
  12 <li><a href="#color">Color functions</a></li>
  13 <li><a href="#manipulation">Data manipulation functions</a></li>
  14 </ul>
  15
  16
  17 <hr>
  18
  19 <h3><a name="important">Important functions</a></h3>
  20
  21 <p><DT><B>SetDataType($which_dt)</B>
  22 <DD>User Function: PHPLOT can accept data in a number of different
  23 formats. One main difference between PHPLOT and PGPLOT
  24 is that the x-y or x-y-error data should be passed in
  25 with the data grouped together in an array.
  26 <p>
  27 Asside: Why the author chose this data format: In PGPLOT
  28 you would have the X-values in one array and the Y-values
  29 in a second. This would sometimes lead to really strange
  30 graphs if one array was accidentally one data element
  31 short. Plus most of the data the author was using came in
  32 from a database using a _get_row or _get_array (in php)
  33 and one can just pass it straight in to PHPLOT. <p>
  34
  35 Colors and border colors are set by <b>SetDataColors</b>. Why
  36 not have colors as part of the same array?  Because most
  37 data applications are used to putting out raw data and not
  38 raw data + color information. <p>
  39
  40 So in PHPLOT the datalabel,x-value,y-value and error are
  41 grouped together as a <b>value array</b>. Then the
  42 entire set of points to be plotted is passed in as a <b>data array</b>
  43 E.g. Data_array = array(value_array_1,value_array_2,....) <p>
  44 See below for examples of the various data types: <br>
  45
  46 <LI>text-data: Data is displayed at equal spacing along the x-axis. Data
  47 is passed in as a data array of value arrays. Each element of the data
  48 array is a position on the x-axis. The first element of the value array is
  49 the label for that x-axis position, every subsequent element of the value
  50 array is a y-value.
  51 Example data<br>
  52 <pre>
  53 $data = array(
  54         array("label 1",1.1,2,3,4),
  55         array("label 2",2,3,4,5),
  56         array("label 3",5,6,7,8),
  57         array("label 4",10,12,13,14)
  58 );
  59 </pre>
  60 Which will display data points at
  61 (1,1.1), (1,2), (1,3), (1,4), (2,2), (2,3)....<br>
  62 <IMG SRC="something.png">
  63 </LI>
  64 <LI>data-data:
  65         X-Y data is passed in like text-data except
  66 that the second element of the value array is the position along the
  67 x axis of the data point(s). One data element would be $data[] = (title,x,y1,y2,y3,y4,...)
  68 or
  69 <pre>
  70 $data = array(
  71         array("label 1",1.1,2,3,4),
  72         array("label 2",2,3,4,5),
  73         array("label 3",5,6,7,8),
  74         array("label 4",10,12,13,14)
  75 );
  76 </pre>
  77 Notice that this is the same as in the previous example except that
  78 the  x,y data points are at (1.1,2), (1.1,3), (1.1,4), (2,3)...
  79 </LI>
  80 <LI>data-data-error:
  81 Again X-Y data is passed in as an array with each value
  82 array being (data_label,x_position,y_position,error_plus,error_minus)
  83 </LI>
  84
  85 <p><DT><B>SetDataValues($which_dv)</B>
  86 <DD>User Function: Passes the raw data values into the class variable
  87 $this->data_values. This function <b>needs</b> to be called before any
  88 image can be drawn.
  89
  90 <p><DT><B>SetPlotType($which_pt)</B>
  91 <DD>User Function: Can be:  bars, lines, linepoints, area, points, and pie
  92
  93 <p><DT><B>SetErrorBarLineWidth($width)</B>
  94 <DD>Width of the Error Bars in Pixels. If not set then
  95 uses "line_width" to set the width of the error_bar lines.
  96
  97 <p><DT><B>SetFileFormat($which_file_format)</B>
  98 <DD>User Function: Set the format of the output graph. Supported formats
  99 are GIF, JPEG, and PNG.  You can only use those formats
 100 that are supported by your version of GD. For example,
 101 if you use GD-1.8.3 you can not use GIF images. If you
 102 use GD-1.2 you can not use PNG or JPEG images.
 103
 104 <p><DT><B>SetUseTTF($which_ttf)</B>
 105 <DD>User Function: Call this as SetUseTTF(1) when you have TTF compiled into PHP
 106 otherwise call this as SetUseTTF(0)
 107
 108
 109 <hr>
 110
 111 <h3><a name="appearance">Appearance functions</a></h3>
 112
 113
 114 <p><DT><B>SetErrorBarShape($which_ebs)</B>
 115 <DD>User Function: Can be "tee" or "line." If it is tee, then
 116 the half-width of the tee is set by <b>SetErrorBarSize</b>
 117
 118 <p><DT><B>SetErrorBarSize($which_ebs)</B>
 119 <DD>User Function: Size in pixels of the Tee shape of the error bar.
 120
 121 <p><DT><B>SetHorizTickIncrement($which_ti)</B>
 122 <DD>User Function: Set where to place the X-tick marks.
 123
 124 <p><DT><B>SetNumHorizTicks($which_nt)</B>
 125 <DD>User Function: Use this or SetHorizTickIncrements but not both.
 126
 127 <p><DT><B>SetNumVertTicks($which_nt)</B>
 128 <DD>User Function: Use this or SetVertTickIncrements but not both.
 129
 130 <p><DT><B>SetPlotAreaPixels($x1,$y1,$x2,$y2)</B>
 131 <DD>User Function: You can use this to set the actual size in
 132 pixels of the plot area on the image.
 133
 134 <p><DT><B>SetPointShape($which_pt)</B>
 135 <DD>User Function: Can be: rect,circle,diamond,triangle,dot,line,halfline
 136
 137 <p><DT><B>SetPointSize($which_ps)</B>
 138 <DD>User Function: Set the width of the displayed data point for
 139 plot_type's that have data points. E.g. dots, linepoints
 140 This is an integer. For diamonds, values that are even
 141 make the diamond look better.
 142
 143 <p><DT><B>SetPrecisionX($which_prec)</B>
 144 <DD>User Function: Set the precision of the data written to the X axis.
 145 $which_prec is an integer which represents the number of digits
 146 displayed to the right of the decimal. This uses the number_format
 147 command in PHP.
 148
 149 <p><DT><B>SetPrecisionY($which_prec)</B>
 150 <DD>User Function: Set the precision of the data written to the Y axis.
 151 $which_prec is an integer which represents the number of digits
 152 displayed to the right of the decimal. This uses the number_format
 153 command in PHP.
 154
 155 <p><DT><B>SetShading($which_s)</B>
 156 <DD>User Function: Set the length of the shadows for shading bar charts
 157 The color used is the LightGridColor See <b>SetLightGridColor</b>. <br>
 158
 159 <p><DT><B>SetTickLength($which_tl)</B>
 160 <DD>User Function: Set the length of the tick in pixels for the x axis and y axis.
 161 $which_color can be either a name like "black" or an rgb color array
 162 array(int,int,int). <br>
 163
 164
 165 <p><DT><B>SetTitle($title)</B>
 166 <DD>User Function: Set the title of the graph. Printed at the top
 167 middle of the graph.
 168
 169 <p><DT><B>SetHorizTickIncrement($which_ti)</B>
 170 <DD>User Function: Set the distance between tick marks on the X axis. $which_ti
 171 is in world coordinates.
 172
 173 <p><DT><B>SetVertTickIncrement($which_ti)</B>
 174 <DD>User Function: Set the distance between tick marks on the Y axis. $which_ti
 175 is in world coordinates.
 176
 177 <p><DT><b>SetXDatalabelMaxlength($which_xdlm)</b>
 178 <DD>User Function: Sets the maximum length of the datalabels on the x-axis.
 179 This adjusts the margins if the angle of the labels is not 0.
 180
 181 <p>
 182
 183 <p><DT><b>SetXGridLabelType($which_xtf)</b>
 184 <DD>User Function: Can be "time", "title", "none", "default" or "data". <br>
 185 time - label is set by the the php command strftime()<br>
 186 title - label is treated as text, the first element of the data array.<br>
 187 data - label is formateed using php command number_format<br>
 188 none - no labelss are printed.<br>
 189 default - prints as it is entered. <br>
 190 <p>
 191
 192
 193 <p><DT><b>SetXScaleType($which_xct)</b>
 194 <DD>Can be "log" or "linear".
 195
 196 <p><DT><b>SetXTimeFormat($which_xtf)</b>
 197 <DD>User Function: Used for x_grid_label_type="time".
 198 For the format see the php manual for strftime().  It assumes the x-data values are unix timestamps, and displays them according to the passed format string.
 199 <p>Example: If x values are seconds offset from the beginning of the day.  This coresponds to unix timestamps on January 1, 1970, so all I had to do was $graph->SetXGridLabelType("%H:%M") to display the time properly.
 200  <p>
 201 The php strtotime() function also comes in handy turning dates into timestamps, especially for parameters to SetPlotAreaWorld().
 202 <p>
 203 Example:<br>
 204 $graph->SetPlotAreaWorld(strtotime("October 1"), 0,strtotime("December 15"),10);<br>
 205 $graph->SetXGridLabelType("time") ;<br>
 206 $graph->SetXTimeFormat("%b %d") ;<br>
 207
 208 <p><DT><B>SetXLabel($xlbl)</B>
 209 <DD>User Function: Set the label for the X axis.
 210
 211 <p><DT><B>SetYLabel($ylbl)</B>
 212 <DD>User Function: Set the label for the Y axis.
 213
 214 <p><DT><b>SetYScaleType($which_xct)</b>
 215 <DD>Can be "log" or "linear".
 216
 217
 218 <hr>
 219
 220 <h3><a name="color">Color functions</a></h3>
 221
 222 <p><DT><B>SetBackgroundColor($which_color)</B>
 223 <DD>User Function: Set the color of the background of the entire image.
 224 $which_color can be either a name like "black" or an rgb color array
 225 array(int,int,int). <br> It defaults to array(222,222,222) if
 226 not defined.<br>
 227
 228 <p><DT><B>SetGridColor ($which_color)</B>
 229 <DD>User Function: Set the color of the grid. Defaults to "black"
 230 $which_color can be either a name like "black" or an rgb color array
 231 array(int,int,int). <br>
 232
 233 <p><DT><B>SetLegend($which_legend)</B>
 234 <DD>$which_legend is an array of text for display in a small box
 235 on the image. If you do not set the position with <b>SetLegendPixels()</b>
 236 then it puts it in the upper right hand side.
 237
 238 <p><DT><b>SetLegendPixels($which_x,$which_y,$which_type)</b>
 239 <DD>Pick the upper left corner of the legend box with
 240 $which_x and $which_y in pixels. $which_type is reserved
 241 for future use.
 242
 243 <p><DT><b>SetLegendWorld($which_x,$which_y,$which_type)</b>
 244 <DD>Untested and documentation not written. Have Fun!
 245
 246 <p><DT><B>SetLightGridColor ($which_color)</B>
 247 <DD>User Function: There are two grid colors, this sets the
 248 light grid color.
 249 $which_color can be either a name like "black" or an rgb color array
 250 array(int,int,int). <br> It defaults to array(222,222,222) if
 251 not defined.<br>
 252
 253 <p><DT><B>SetLineWidth($which_lt)</B>
 254 <DD>User Function: Set the width of lines in pixels for graphs that use
 255 lines (linepoints and lines). Affects the size of the
 256 error bar lines as well.
 257
 258 <p><DT><B>SetLineStyles($which_sls)</B>
 259 <DD>User Function: Set style of the line to be printed.
 260 This is an array. Currently only 'dashed' and 'solid' are
 261 supported.
 262
 263 <p><DT><B>SetPlotBgColor($which_color)</B>
 264 <DD>User Function: Set the Background color of the area on which
 265 the plot is defined. Called from <b>PlotAreaBackground</b><br>
 266 $which_color can be either a name like "black" or an rgb color array
 267 array(int,int,int). <br> It defaults to array(222,222,222) if
 268 not defined.
 269
 270 <p><DT><B>SetTextColor ($which_color)</B>
 271 <DD>User Function: Set the color of text written. It defaults to black if not called.
 272 You can call this function multiple times - each time it changes the
 273 color of text written.
 274 $which_color can be either a name like "black" or an rgb color array
 275 array(int,int,int). <br>
 276
 277 <p><DT><B>SetTickColor ($which_color)</B>
 278 <DD>User Function: Set the color of the ticks on the axes
 279 $which_color can be either a name like "black" or an rgb color array
 280 array(int,int,int). <br>
 281
 282 <p><DT><B>SetTitleColor($which_color)</B>
 283 <DD>User Function: Set the color of the title.
 284 $which_color can be either a name like "black" or an rgb color array
 285 array(int,int,int). <br>
 286
 287 <hr>
 288
 289 <h3><a name="manipulation">Data manipulation functions</a></h3>
 290
 291 <p>These functions only are availabe in the class PHPlot_data that extends PHPlot.
 292 Since all functions of that section do calculations on the data, it is neccessary
 293 that data is supplied to the class by the SetDataValues() function before calling
 294 any of the functions.</p>
 295
 296 <p><DT><B>DoScaleData($even, $show_in_legend)</B>
 297 <DD>User Function: Scales the data so that graphs with widely different amplitudes
 298 can be plotted into one image. If $show_in_legend is true, the amplification factor
 299 that is applied to each for the datasets is appended to the legend of the graph. If
 300 $even is true, the function multiplies only by 10^x,2*10^x or 5*10^x.<br>
 301
 302 <p><DT><B>DoMovingAverage($datarow, $interval, $show_in_legend)</B>
 303 <DD>User Function: Computes a moving average over an amount of $interval units
 304 on the data row that is indexed by $datarow. If $show_in_legend is true, a notice
 305 that a data row is averaged and the length of the interval are appended to the legend.
 306 <br>
 307
 308 <hr>
 309
 310 <h3>not implemented</h3>
 311
 312 <p><DT><B>SetCharacterHeight()</B>
 313 <DD>User Function: Not yet implemented
 314
 315 </body>
 316 </html>