Chapter 9. PHPlot Class Internal Functions

This chapter documents PHPlot internal functions. These functions are intended to be used only by PHPlot itself.

Note

Starting with PHPlot-5.1.0, most of the internal functions are declared as protected, which limits their visibility to other member functions and inherited or parent classes. Some internal functions are still public, usually because they are needed for testing PHPlot. However, all functions documented in this chapter should be treated as private, for use only by PHPlot. If you feel you have a need to use one of these functions from outside PHPlot (or an inherited class), please report this via the available PHPlot support mechanisms.

array_merge_php4($array1,$array2)

This non-member function was removed at PHPlot-5.0.4.

array_pad_array(&$arr, $size, $arr2=NULL)

This non-member function was removed at PHPlot-5.0.4 and replaced with the class member function pad_array.

CalcAxisPositions()

Calculates the X and Y axis positions in world coordinates. These can be supplied by the user, in which case they are only changed if they are outside the data range. If axis positions are not supplied by the user, CalcAxisPositions applies defaults as described in SetXAxisPosition and SetYAxisPosition. Called by DrawGraph. Note: This code was moved out of CalcTranslation at PHPlot-5.0.5.

CalcBarWidths($stacked, $verticals)

Calculates values for bars and stackedbars plot types. It calculates the width of the bars and the margins around and between them. An argument was added in PHPlot-5.1.2 to support horizontal plots. Arguments were changed in PHPlot-5.3.0 to explicitly select stacked or grouped bars, and vertical or horizontal plots. This is called by the bar chart drawing functions DrawBars, DrawStackedBars, DrawHorizBars, and DrawHorizStackedBars. (Through PHPlot-5.1.2 this was called by DrawGraph before a bars or stackedbars plot.)

CalcGridSettings()

This function was removed at PHPlot-6.0.0. It applied the defaults to the X and Y grid flags. PHPlot now uses GetGridSetting instead.

CalcMargins($maximize)

Calculates the size of the four margins around the plot area: x_left_margin, x_right_margin, y_top_margin, and y_bot_margin. It does this by trying to determine how much space is needed for titles, labels, and tick marks. Starting with PHPlot-5.0.5, this is only called by DrawGraph, and it also calculates position offsets for titles and labels. It is called even in case of a user-supplied plot area (SetPlotAreaPixels or SetMarginsPixels was used). If the $maximize argument is true, then the plot area does not leave room for X or Y axis, labels, or titles; this is used for pie charts.

Through PHPlot-5.0.6, all 4 margins are either user-defined or all 4 are automatically calculated. Starting with PHPlot-5.0.7, the 4 margins can be independently set or defaulted to automatic. CalcMargins calculates values for all 4 margins, but only saves those that have not been set using either SetMarginsPixels or SetPlotAreaPixels. Note that other than the overall plot title, elements are drawn relative to the plot area, which is calculated based on the actual margins. If the top margin is increased, for example, the plot title stays at the top of the image, but top tick marks and labels move down against the graph.

CalcMaxDataLabelSize($which = 'x')

Calculates the size of the biggest X or Y data label. For 'x' it returns the height along the Y axis of the tallest data label. For 'y' it returns the width along the sides of the widest data label. This is used to allocate space for margins. This was added to PHPlot-5.0.5. The argument supporting Y label width was added in PHPlot-5.1.2. Called by CalcMargins.

CalcMaxTickLabelSize($which)

Calculates the size of the biggest tick label. The $which argument is 'x' or 'y' to indicate which labels to work with. For 'x', it returns the height along the Y axis; for 'y' it returns the width along the X axis. This is used to allocate space for margins. This was added to PHPlot-5.0.5. Calls CalcTicks to determine the tick value parameters. Called by CalcMargins.

CalcPlotAreaPixels()

Calculates the pixel coordinates of the plot area. This was added to PHPlot-5.0.5 by moving the parts of the calculations out of SetPlotAreaPixels and SetMarginsPixels. Those two functions now simply record their arguments, and make no attempt to calculate any parameters. Called by DrawGraph, after CalcMargins is used to calculate margins.

CalcPlotAreaWorld()

Calculates the world coordinate limits of the plot area. This was added to PHPlot-5.0.5 by moving the calculations out of SetPlotAreaWorld. Starting with PHPlot-6.0.0, it just calls CalcPlotRange twice, once for X and once for Y. Called by DrawGraph, after FindDataLimits is used to examine the data array values.

CalcPlotRange($which)

Calculates the plot range and tick increment. $which is 'x' or 'y', to calculate values for the X or Y axis. Specified values (e.g. with SetPlotAreaWorld or SetXTickIncrement) are used if set. Otherwise, values are calculated heuristically. Returns an array of 3 calculated values: tick_increment, plot_min, and plot_max. This was added in PHPlot-6.0.0. Calls CalcStep if necessary to calculate the tick increment. (If either the tick increment or number of ticks has been set, then CalcPlotRange uses those instead of calling CalcStep). Called by CalcPlotAreaWorld, once for X and once for Y.

CalcRangeInit(&$plot_limit, $implied, $data_limit)

Calculates the initial values for the plot range ends. $plot_limit is one end (min or max) of a plot range. It is passed as a reference because it might be unset. Unset, NULL, or an empty string means this end of the range has not been set and needs to be calculated. $implied is true when the data type does not specify the value (for example, the X value in text-data data type). $data_limit is the actual data limit (min or max) at this end of the range; given no other information this is the initial guess for the plot range limit. Returns an array of 2 elements: the initial value for the plot range limit, and a flag indicating if additional adjustment of that value is to be done.

This was added in PHPlot-6.0.0. Called by CalcPlotRange 4 times, once for each end of the X and Y ranges.

CalcStep($which, $range)

Calculates an appropriate tick increment. $which is 'x' or 'y', and selects configuration variables for that axis. $range is the plot area range (max - min). Returns the calculated tick increment.

This function is not called if the user has set a tick increment (SetXTickIncrement, SetYTickIncrement) or the number of tick marks (SetNumXTicks, SetNumYTicks). This function calls either CalcStep125, CalcStepBinary, or CalcStepDatetime to calculate an appropriate value, depending on the tick increment mode. This was added in PHPlot-6.0.0. Called by CalcPlotRange.

CalcStep125($range, $min_ticks)

Calculates an appropriate tick increment in 'decimal' mode. This is the default mode. $range is the plot area range (max - min). $min_ticks is the minimum number of tick intervals to produce. Returns the calculated tick increment. The algorithm produces the largest tick increment that is a power of 10 times 1, 2, or 5, and divides the plot area range $range into no fewer than $min_ticks intervals. This was added in PHPlot-6.0.0. Called by CalcStep.

CalcStepBinary($range, $min_ticks)

Calculates an appropriate tick increment in 'binary' (power of 2) mode. $range is the plot area range (max - min). $min_ticks is the minimum number of tick intervals to produce. Returns the calculated tick increment. The algorithm produces the largest tick increment that is a power of 2 and divides the plot area range $range into no fewer than $min_ticks intervals. This was added in PHPlot-6.0.0. Called by CalcStep.

CalcStepDatetime($range, $min_ticks)

Calculates an appropriate tick increment in 'date' mode. This is for when the values along the axis represent date/time values. $range is the plot area range (max - min), in seconds. $min_ticks is the minimum number of tick intervals to produce. Returns the calculated tick increment. The function contains a list of acceptable intervals between 1 second and 1 week, and returns one of those if possible - the largest value that divides the plot area range $range into no fewer than $min_ticks intervals. If the range is too large (would produce too many ticks with an increment of 1 week), the function falls back to using CalcStep125 with units of 1 day. This was added in PHPlot-6.0.0. Called by CalcStep.

CalcTicks($which)

Gets the tick parameters. $which is 'x' or 'y'. Returns an array of 3 values: start, end, and interval. This was added to PHPlot-5.0.5, although still using the method of just dividing the interval by 10 if there is no user-supplied interval or tick count. Starting with PHPlot-5.4.0, it also accounts for a tick anchor value, by shifting the start value as needed. Starting in PHPlot-6.0.0, it no longer calculates the tick increment, but simply uses the values calculated by CalcPlotRange. Called by CalcMaxTickLabelSize, DrawYTicks, and DrawXTicks.

CalcTranslation()

Calculates the parameters for transforming world to pixel coordinates. This function calculates the scale (xscale, yscale) and origin (plot_origin_x, plot_origin_y) for X and Y translations, which are used by the xtr() and ytr() functions. Starting with PHPlot-5.0.5, this is only called by DrawGraph, as nothing else uses the parameters until the graph is ready to be drawn.

CheckDataArray()

Checks that there is a valid data array for the plot, and calculates values that depend on the data type. Called very early by DrawGraph. This was added in PHPlot-5.1.3, moving the checking out of DrawGraph and adding the data_columns calculation.

CheckDataType($valid_types)

Used to validate the data_type for a plot_type. This works like a specialized version of CheckOption. $valid_types contains the valid data type(s) for the current plot_type, separated by a comma and space if more than one is supported. If the current data_type is in the list, returns TRUE, else produces an error. This was added in PHPlot-5.1.2 to unify the way the plot drawing functions check the data type.

CheckDataValueLabels($label_control, &$dvl)

Checks to see if data value labels should be drawn, based on $label_control (which is either $this->y_data_label_pos for vertical plots, or $this->x_data_label_pos for horizontal plots). Returns FALSE if the labels are off, else returns TRUE and sets 4 variables in the $dvl array. This array is used by DrawDataValueLabel to position the label. The array contains these keys: x_offset, y_offset : device coordinate (pixel) offsets for the label; h_align, v_align : text alignment. Called by plot type drawing functions such as DrawDots which do data value labels, other than bars and stackedbars. This was added in PHPlot-5.3.0. Through PHPlot-5.7.0, four separate reference arguments were used for the return values, instead of an array.

CheckLabels()

Fixes up the data and tick label position and angle. This applies defaults to data label and tick label positions but avoids having them overlap unless the user deliberately positioned them that way. Also sets the default angle for X data labels. This is for compatibility with PHPlot-5.0.7 and earlier, when there was only one control for both types of labels. Called by DrawGraph before calculating margins with CalcMargins. This was added in PHPlot-5.1.0. Before PHPlot-6.0.0, it also applied tick label format settings as defaults for data label formatting. Starting with PHPlot-6.0.0, this is now handled in FormatLabel instead.

CheckLabelsAllEmpty()

Returns TRUE if all of the labels in the data array are empty strings. This is used by CheckLabels to determine whether tick or axis data labels should default on if both are left off. This was added in PHPlot-5.1.2.

CheckOption($which_opt, $which_acc, $which_func)

Checks the validity of an option passed to a PHPlot member function. $which_opt is the string to check, and $which_acc is a string of acceptable choices (with a comma and then a space between choices). If the string to check is not found in the string of acceptable choices, a fatal error will be reported using PrintError. The error message will include $which_func which should be the name of the calling function (using the PHP __FUNCTION__ magic constant). Note that this is used to catch programming errors, not run-time or user errors. If the string to check is acceptable, it is returned down-cased and trimmed of leading and trailing spaces. Note: At PHPlot-5.0.5, this function was changed to require exactly ', ' (comma space) between acceptable choices, and reject empty strings for $which_opt and disallow partial matches.

CheckOptionArray($opt, $acc, $func)

Checks the validity of an option argument passed to a PHPlot member function that can accept its argument as either a string or an array of strings. $opt is the string or array to check, and $acc is a string of acceptable choices (with a comma and then a space between choices). If the $opt argument is supplied as a string, it is first converted to an array with one element. Then the elements of the array are each checked for validity. If any element of the array of strings to check is not found in the string of acceptable choices, a fatal error will be reported using PrintError. The error message will include $func which should be the name of the calling function (using the PHP __FUNCTION__ magic constant). Note that this is used to catch programming errors, not run-time or user errors. If all of the array elements to check are acceptable, the array is returned with each element down-cased and trimmed of leading and trailing spaces. Note that an array is always returned, even if the opt argument is a string. This was added in PHPlot-5.1.2.

CheckPieLabels()

Sets up the default pie chart label type and format. The default is percentage labels formatted as 'data' (fixed-point). The default cannot be statically defined, for compatibility with previous releases which used the Y label precision (if set), else 1 digit if SetPrecisionY was never called. Called by DrawPieChart. This was added in PHPlot-5.6.0.

CheckPlotRange($which, &$plot_min, &$plot_max, $adjust_min, $adjust_max)

Ensures that the X or Y plot range is positive. This is necessary because the plot range and tick increment calculations, as well as the overall plotting functions, cannot handle zero or negative ranges. A bad range can happen as a result of 'flat' or missing data (all Y values the same, for example), or if SetPlotAreaWorld is used to set one end of the data range, and the actual data is on the wrong side of that limit. (SetPlotAreaWorld itself defends against setting both ends of a range such that min >= max). PHPlot will never adjust user-set plot limits, but it will adjust its own calculated limits to force a positive range (even if the resulting plot may not be useful).

$which is 'x' or 'y' (this is only used for error reporting). $plot_min and $plot_max are the range limits. These are passed by reference and may be adjusted by the function. $adjust_min and $adjust_max are flags indicating if the corresponding $plot_min and $plot_max values were user-specified (False) or calculated (True). A flag value of True means CheckPlotRange may adjust the corresponding plot range value to prevent a non-positive range. Called by CalcPlotRange. This was added in PHPlot-6.0.0.

CheckPointParams()

Adjusts the point_shapes and point_sizes arrays so they have the same size, and stores the size in a class variable. This handles processing deferred from SetPointShapes and SetPointSizes until graph drawing time. It it is called by DrawDots before using point shapes. This was added in PHPlot-5.1.0.

DecodeDataType()

Decodes the data type, and sets several member variables that other functions can use to understand how to process the data array. The variables it sets all have names starting with "datatype_" (refer to Chapter 10, PHPlot Class Member Variables). This is called by DrawGraph. It was added in PHPlot-5.1.2 (where it returned an array of 4 flags, and was called by several functions that needed to know the structure of the data array.) In PHPlot-5.1.3, it was changed to set member variables instead. It is now called just once, and the other functions reference the variables as needed. Starting with PHPlot-6.1.0, it uses the $datatypes array to set the flags based on the data type, so it no longer needs to 'know' the actual data type names.

DisableCaching()

Sends HTTP headers to the browser to disable client-side caching. This is called by PrintImage if SetBrowserCache was used to disable caching. It is also used by StartStream. This was added in PHPlot-5.8.0 by moving code out of PrintImage.

DoCallback($reason, ...)

Call a callback (hook) function. $reason is the name given to the callback, for example draw_titles (meaning: call after drawing titles). The reasons are array indexes in the $callbacks class variable. Following that are zero or more arguments to pass to the callback, after the image resource and passthrough arguments. DoCallback does nothing if there is no callback registered for the given reason, otherwise it calls the callback function. See Section 4.4, “Callbacks” for more information on callbacks.

Starting with PHPlot-5.1.3, DoCallback returns the value returned by the callback function, if any. If there is no callback defined for the given reason, NULL is returned. So it is possible to define a callback that returns a meaningful value (such as True/False), and still distinguish the case of where no callback has been set. However, it is often simpler to test first to see if a callback has been set, using GetCallback, before using DoCallback.

DrawArea($do_stacked = False)

Draws an area plot, or a stacked area plot (if the optional argument is True). Called by DrawGraph when the plot type is area or stackedarea. Stacked area plots were added in PHPlot-5.1.1; through PHPlot-5.1.0 this function did not have a parameter and was used only for area plots.

DrawBackground($overwrite = False)

Draws the image background, either an image file or solid fill or nothing. Called by DrawGraph and DrawMessage. The optional argument $overwrite (added in PHPlot-5.7.0 for DrawMessage) forces the background to be drawn, even if it was already drawn.

DrawBar($row, $column, $x1, $y1, $x2, $y2, $data_color, $shade_color, $border_color, $shade_top = TRUE, $shade_side = TRUE)

Draws a single bar (or bar segment), with either shading or border. The $row and $column indicate which data point is being plotted. Four corner coordinates and 3 color indexes are provided. The first color $data_color is the bar fill color, the second color $shade_color is the shading color, and the third color $border_color is used for bar borders. (These three come from GetBarColors.) The last two arguments are flags used to suppress the top or side shading for certain cases of stacked bar segments. Called by DrawBars and DrawHorizBars to draw each bar. Called by DrawStackedBars and DrawHorizStackedBars to draw each bar segment. This was added in PHPlot-5.2.0, moving common code from those 4 functions.

Starting with PHPlot-5.7.0, the arguments were changed as shown to accommodate a new callback which provides access to drawing coordinates. In previous releases, the usage was DrawBar($x1, $y1, $x2, $y2, $data_color, $alt_color, $shade_top = TRUE, $shade_side = TRUE).

In PHPlot-6.0.0, a single $alt_color argument was split into separate $shade_color and $border_color arguments. This corresponds to the change in GetBarColors, and allows for bar charts with independent control over shading and borders.

DrawBars()

Draws a bar chart plot. Called by DrawGraph when the plot type is bars. If the data type indicates a horizontal bar chart, calls DrawHorizBars instead.

DrawBoxes()

Draws a box plot. Called by DrawGraph when the plot type is boxes. This was added in PHPlot-6.1.0.

DrawBubbles()

Draws a bubbles plot. Called by DrawGraph when the plot type is bubbles. This was added in PHPlot-5.5.0.

DrawDataLabel($which_font, $which_angle, $x_world, $y_world, $which_color, $which_text, $which_halign = 'center', $which_valign = 'top', $x_adjustment=0, $y_adjustment=0)

This function was removed in PHPlot-5.1.3 and replaced by DrawDataValueLabel.

DrawDataValueLabel($x_or_y, $row, $column, $x_world, $y_world, $text, $dvl)

Draws a data value label (previously called "Y data label"). These are the above-bar or in-bar labels on bar and stackedbar charts, and the labels near data points available with some other plot types.

$x_or_y is 'x' or 'y' to select the font, angle, and formatting type. The $row and $column are passed to FormatLabel for possible use with a custom formatting function. The label is drawn at world coordinates ($x_world, $y_world) after device coordinate offset is applied (see below). $text is the label text, which gets formatted with FormatLabel before drawing.

The $dvl argument is an array with up to 6 variables containing positioning and related information. In $dvl, x_offset and y_offset are pixel offsets for the label; h_align and v_align specify the text alignment relative to the plotting point (see DrawText); min_width and max_width used to prevent labels from overlapping their allocated space. If either min_width or max_width is supplied in the $dvl array, the text is sized before drawing, and if it won't fit in the space the label is not drawn. This is used to suppress labels that are too wide to be drawn inside their bars, for example. The defaults for the X and Y offsets are 0, and the default alignment is (center, center). (The $dvl argument is required, but none of its elements is required.)

This function is called by all plot drawing functions which support data value labels, if those labels are enabled.

This function was added in PHPlot-5.1.3 and replaced DrawDataLabel. Through PHPlot-5.7.0, 6 separate arguments were used instead of the $dvl array, and the $row and $column arguments were not present.

DrawDot($row, $column, $x_world, $y_world, $color)

Draws a single marker point ('dot') at the given X and Y world coordinates, using the given color. The $row and $column indicate which data point is being plotted. The $column parameter also selects the marker shape and size, using the arrays set up with SetPointSizes() and SetPointShapes(). Called by DrawDots to plot point markers. Starting with PHPlot-5.4.0, DrawDot() simply converts the coordinates to device coordinates and then calls DrawShape. It has no knowledge of the available dot shapes.

Starting with PHPlot-5.7.0, the arguments were changed as shown to accommodate a new callback which provides access to drawing coordinates. In previous releases, the usage was DrawDot($x_world, $y_world, $record, $color). The old $record argument is equivalent to the new $column argument.

DrawDots($paired = False)

Draws a points plot, or the points for a linepoints plot, including error plots. Called by DrawGraph when the plot type is points, and by DrawLinePoints for the points portion of a linepoints plot. $paired is true for linepoints plots. When $paired is true, DrawDots() draws the points and error bars, and DrawLines draws the lines and data labels. (The $paired argument was added in PHPlot-5.1.3.) Starting with PHPlot-6.0.0, DrawDots() also handles error plots, and horizontal points and linepoints plots.

DrawDotsError($paired = False)

This function was removed in PHPlot-6.0.0 and merged into DrawDots.

DrawError($error_message, [$where_x], [$where_y])

Starting with PHPlot-5.0.5, this function is an alias for PrintError and is retained for compatibility. The $where_x and $where_arguments are now ignored. (Previously they positioned the error message on the image, but were never used.) Starting with PHPlot-5.7.0, this function is considered deprecated.

DrawHorizBars()

Draws a horizontal bars plot. Called by DrawBars when the data type indicates a horizontal plot. This was added in PHPlot-5.1.2 (but was called by DrawGraph). In PHPlot-5.1.3 it was changed to be called by DrawBars.

DrawHorizStackedBars()

Draws a horizontal stacked bars plot. Called by DrawStackedBars when the data type indicates a horizontal plot. This was added in PHPlot-5.1.3.

DrawImageBorder($overwrite = False)

Draws a border around the image, if enabled by SetImageBorderType. Called by DrawGraph and DrawMessage. The optional argument $overwrite (added in PHPlot-5.7.0 for DrawMessage) forces the border to be drawn, even if it was already drawn.

DrawLegend(x,y,type)

Draws the plot legend. This includes the box, text labels, and color boxes or shapes. Called by DrawGraph, but only if legend text has been set using SetLegend.

DrawLinePoints()

Draws a linepoints plot, with or without error bars. Called by DrawGraph when the plot type is linepoints. It simply calls DrawLines and DrawDots, which handle both the plain and error bar cases. This was added in PHPlot-5.1.3 to provide a function specific to this plot type.

DrawLines($paired = False)

Draws a line plot, or the lines part of a linepoints plot, including error plots. Called by DrawGraph when the plot type is lines, and by DrawLinePoints for the lines portion of a linepoints plot. $paired is true for linepoints plots. When $paired is true, DrawLines() draws the lines and data labels, and DrawDots draw the points and error bars. (The $paired argument was added in PHPlot-5.1.3.) Starting with PHPlot-6.0.0, DrawLines() also handles error plots, and horizontal lines and linepoints plots.

DrawLinesError($paired = False)

This function was removed in PHPlot-6.0.0 and merged into DrawLines.

DrawOHLC($draw_candles, $always_fill = FALSE)

Draws one of the three types of OHLC (Open/High/Low/Close) plots. If $draw_candles is FALSE, draws a basic OHLC plot (plot type ohlc). If $draw_candles is TRUE and $always_fill is FALSE, draws a candlestick OHLC plot (plot type candlesticks). If $draw_candles is TRUE and $always_fill is TRUE, draws a filled candlestick OHLC plot (plot type candlesticks2). Called by DrawGraph when the plot type is one of those three types. This was added in PHPlot-5.3.0.

DrawPieChart()

Draws a pie chart plot. Called by DrawGraph with the plot type is pie.

DrawPieLabel($label_txt, $xc, $yc, $start_angle, $arc_angle, $r)

Draws a pie chart label. $label_txt is the already-formatted label text string. ($xc, $yc) is the center of the pie (not the text basepoint). $start_angle is the starting angle in degrees for the segment being labeled, which extends for $arc_angle degrees. $r is an array of static values (constant for each pie chart): ellipse parameters and a flag to indicate the text alignment should be reversed. Called by DrawPieChart. This was added in PHPlot-5.6.0.

DrawPlotAreaBackground()

Draws the plot area background, either an image file set with SetPlotAreaBgImage, or else a solid fill color selected by SetPlotBgColor if enabled with SetDrawPlotAreaBackground or else nothing. Called by DrawGraph.

DrawPlotBorder($draw_axes=TRUE)

Draws the border around the plot area. This draws zero to four lines around the plot area (depending on SetPlotBorderType). The $draw_axes argument (added in PHPlot-5.6.0) is true for all plot types except pie charts, and controls the default value if SetPlotBorderType() was not called. Called by DrawGraph.

DrawShape($x, $y, $record, $color, $allow_none = TRUE)

Draws a single marker point ('dot' or 'shape') at the given X and Y device (pixel) coordinates, using the given color. The $record parameter selects the marker shape and size using the arrays set up with SetPointSizes() and SetPointShapes(); they are not passed as arguments themselves. Called by DrawDot and DrawLegend. This is the function that knows which shapes are available and how to draw them. (SetPointShapes also has a list of valid shapes.) This was added at PHPlot-5.4.0 by moving the shape drawing code out of DrawDot(), leaving behind only the conversion from world to device coordinates. This was necessary because DrawLegend() needs to specify marker positions in pixel coordinates when using point shapes instead of color boxes.

If the optional $allow_none is FALSE, then the function will substitute another shape for the special 'none' shape (which suppresses a shape marker for a data set in a linepoints plot). This is used when drawing a legend, to ensure that there is a marker shape for each data set. This argument was added in PHPlot-6.0.0.

DrawSquared()

Draws a squared (stepped lines) plot. Called by DrawGraph when the plot type is squared.

DrawSquaredArea($do_stacked = False)

Draws a squared area plot, or a stacked squared area plot (if the optional argument is True). Called by DrawGraph when the plot type is squaredarea or stackedsquaredarea. This was added in PHPlot-6.2.0.

DrawStackedBars()

Draws a stacked bars chart plot. Called by DrawGraph when the plot type is stackedbars. If the data type indicates a horizontal plot, calls DrawHorizStackedBars instead.

DrawText($font, $angle, $xpos, $ypos, $color, $text, $halign = 'left', $valign = 'bottom')

Draws a string of text $text, at position ($xpos, $ypos). The font settings are specified by $font, which is one of the text element names used by SetFont such as 'title' or 'x_label'. An empty string or NULL can be used to get the 'generic' font. For backward compatibility, a font array (from the PHPlot object $fonts[] array) can be used too.

The text is drawn at angle $angle (built-in fonts can be used at 0 and 90 degrees only, TrueType at any angle). $color is a GD color index for the image. Text alignment relative to the (x,y) point is controlled with $halign (center, left, or right) and $valign (center, bottom, or top).

Multi-line text strings are supported. This function accounts for the limitations and differences in GD text drawing routines for built-in and TrueType fonts. Called by numerous functions which place text on the plot.

Starting with PHPlot-5.0.5, this function just calls ProcessText in text drawing mode. DrawText should be used by all internal PHPlot code that needs to draw text, and ProcessText should only be used by DrawText and SizeText.

Starting with PHPlot-5.1.0, $font can be NULL or an empty string to use the generic font. This was intended to allow callbacks to avoid having to reference the internal class array variable which stores font information.

Starting with PHPlot-6.0.0, the preferred form for $font is the name of a PHPlot text element, with use of the $fonts[] member variable deprecated. This further eases use of DrawText by callbacks, which can specify a font other than 'generic' without referencing internal class variables.

DrawThinBarLines()

Draws a thin bar lines plot. This is sometimes called an impulse plot. Called by DrawGraph when the plot type is thinbarline. This function draws both vertical and horizontal variants of this plot type.

DrawTitle()

Draws the main plot title as set with SetTitle. This is centered at the very top of the image. Called by DrawGraph.

DrawXAxis()

Draws the X (horizontal) axis, including the axis line, tick marks and labels, and also draws the vertical grid lines. All of these except the axis line are done in DrawXTicks. Called by DrawGraph.

DrawXDataLabel($xlab, $xpos, $row, $do_lines=FALSE)

Draws an axis data label for an X value. The labels are above or below the plot area or both, depending on the value set with SetXDataLabelPos. The $row value indicates the row index in the data array for this label; it is used to position the data label line, and for custom label formatting. If $do_lines is true, this calls DrawXDataLine to draw a line from the label to the point, if enabled and supported by the plot type.

This function is used by vertical plots. It is called by plot drawing routines for all plot types except pie: DrawArea, DrawBars, DrawDots, DrawThinBarLines, DrawLines, DrawSquared, and DrawStackedBars.

DrawXDataLine($xpos, $row)

Draws X data label lines, which are vertical lines from the bottom or top of the plot to the data points. This is enabled with SetDrawXDataLabelLines. The lines are drawn from the position (above, below, or both) of the X axis data labels, which are set with SetXDataLabelPos. Called by DrawXDataLabel.

DrawXErrorBars($x, $y $error_plus, $error_minus, $color)

Draws an error bar set for the point at world coordinates ($x, $y). $error_plus and $error_minus are the X error amounts (in world coordinates). Both are non-negative values. Called by DrawDots and DrawLines when the data type indicates a horizontal error plot. This was added in PHPlot-6.1.0 when horizontal error plots were implemented.

DrawXTick($x, $x_pixels)

Draws a single X value tick mark and its label. These can appear on the bottom of the graph, top of the graph, along the X axis (even if it is in the middle somewhere), on both sides, or nowhere, as set with SetXTickPos and SetXTickLabelPos. $x is the X value of the tick, and $x_pixels is its device coordinate value. Called by DrawXTicks. This was added at PHPlot-5.0.5 by splitting the code out of DrawXTicks, for symmetry with DrawYTicks. Through PHPlot-5.7.0, $x was passed to this function already formatted with FormatLabel. Starting with PHPlot-5.8.0, the actual tick value is passed, so DrawXTick can decide whether or not to format it.

DrawXTicks()

Draws the vertical grid lines, the tick marks, and tick labels. Calls CalcTicks to calculate the tick parameters. Calls DrawXTick to draw each tick mark and its label. Called by DrawXAxis.

DrawXTitle()

Draws the X axis title. There can be zero, one, or two of them depending on the position parameter specified in SetXTitle. Calls DrawText to actually draw the title(s). Called by DrawGraph.

DrawYAxis()

Draws the Y (vertical) axis, including the axis line, tick marks and labels, and also draws the horizontal grid lines. All of these except the axis line are done in DrawYTicks. Called by DrawGraph.

DrawYDataLabel($ylab, $ypos, $row, $do_lines=FALSE)

Draws an axis data label for a Y value. The labels are along the Y axis or side of the plot, or both, depending on the value set with SetYDataLabelPos. The $row value indicates the row index in the data array for this label; it is used for custom label formatting. If $do_lines is true, this calls DrawYDataLine to draw a line from the label to the point, if enabled and supported by the plot type. This function is used by horizontal plots, and was added in PHPlot-5.1.2. Called by horizontal plot drawing functions such as DrawHorizBars. The $do_lines argument was added in PHPlot-6.0.0 when horizontal plots supporting data label lines were first available.

DrawYDataLine($ypos, $row)

Draws Y data label lines, which are horizontal lines from the left or right side of the plot to the data points. This is enabled with SetDrawYDataLabelLines, and is only valid with horizontal plots which support Y data label lines. The lines are drawn from the position (left, right, or both) of the Y axis data labels, which are set with SetYDataLabelPos. Called by DrawYDataLabel. This was added in PHPlot-6.0.0.

DrawYErrorBar($x_world, $y_world, $error_height, $color)

This function was removed in PHPlot-6.1.0 and replaced with DrawYErrorBars.

DrawYErrorBars($x, $y $error_plus, $error_minus, $color)

Draws an error bar set for the point at world coordinates ($x, $y). $error_plus and $error_minus are the Y error amounts (in world coordinates). Both are non-negative values. Called by DrawDots and DrawLines when the data type indicates a vertical error plot. This was added in PHPlot-6.1.0, replacing DrawYErrorBar (which drew only 1 of the error bars for a point).

DrawYTick($y, $y_pixels)

Draws a single Y value tick mark and its label. These can appear on the left of the graph, right of the graph, along the Y axis (even if it is in the middle somewhere), on both sides, or nowhere, as set with SetYTickPos and SetYTickLabelPos. $y is the Y value of the tick, and $y_pixels is its device coordinate value. Called by DrawYTicks. Through PHPlot-5.7.0, $y was passed to this function already formatted with FormatLabel. Starting with PHPlot-5.8.0, the actual tick value is passed, so DrawYTick can decide whether or not to format it.

DrawYTicks()

Draws the horizontal grid lines, the tick marks, and tick labels. Calls DrawYTick to draw each tick mark and its label. Called by DrawYAxis.

DrawYTitle()

Draws the Y axis title. There can be zero, one, or two of them depending on the position parameter specified in SetYTitle. Calls DrawText to actually draw the title(s). Called by DrawGraph.

FindDataLimits()

Finds the limits of the data. Using the data_type and the data array, it goes through the points and determines the minimum and maximum X and Y values. It stores the min and max Y values for each row (plot line) in the class arrays data_min and data_max. (Before PHPlot-5.0.4, these were stored back into the data array with special index values MINY (-1) and MAXY (-2).) It also stores the overall min and max X and Y values as min_x, max_x, min_y, and max_y. It also stores the length of the longest data label in max_t. Starting with PHPlot-5.0.5, this is only called once by DrawGraph. (In PHPlot-5.0.4 and earlier, this was called from various places, with a flag data_limits_done to indicate it was called.)

FormatLabel($which_pos, $which_lab, ...)

Formats a value for use as a tick, data, or pie chart label. This implements the format type selected with SetXLabelType, SetYLabelType, SetXDataLabelType, SetYDataLabelType, and SetPieLabelType. If no formatting is in effect for that label type ($which_pos), it returns the label string $which_lab as-is. Otherwise, it formats it as directed. This can be a floating point number (formatted with number_format), a date/time value, or it can be formatted with sprintf or a user-defined function (type 'custom'). Any additional arguments after the first 2 are passed through to a custom label formatting function. This is used to make the data row and column available to the user-defined function (if applicable for the label type).

Called by several functions that need to format label values. Separation of data and tick label formatting was available starting with PHPlot-5.1.0. Use with pie chart labels was added in PHPlot-5.6.0. Support for additional arguments for custom functions was added in PHPlot-5.8.0.

FormatPieLabel($index, $pie_label_source, $arc_angle, $slice_weight)

Formats a pie chart label. This first gets the initial value, based on the $source argument to SetPieLabelType, which is passed in as $pie_label_source. It may use $index, $arc_angle, or $slice_weight, or a combination of those. Then it formats that value using FormatLabel and returns the result. Called by DrawPieChart. This was added in PHPlot-5.6.0.

GetBarColors($row, $idx, &$vars, &$data_color, &$shade_color, &$border_color)

Gets the color indexes to be used for a bar plot. This is used by bar and stackedbar plot drawing functions, and accounts for a custom data color callback if defined. $row and $idx are the indexes for the current bar or bar segment. $vars is an array argument that maintains information across calls - the caller allocates an empty array, and this function updates it. The color index for bar filling is returned in $data_color. $shade_color is the color index to use for shading (if shading is on). $border_color is the color index to use for the bar border (if on). This was added in PHPlot-5.2.0, moving common code into a function. In PHPlot-6.0.0, a single $alt_color argument was split into separate $shade_color and $border_color arguments.

GetColorIndex(&$color, $default_color_index=0)

Allocate a GD color index for a color given as a 4 component array (R,G,B,A) $color. Returns a color index to be used in GD drawing functions. The color returned is the exact color requested if it already exists in the image, or if can be allocated. For palette images, if the color map is full, no new colors can be allocated, and this function will return an index to the closest existing color. For truecolor images, this function always returns an index for the exact requested color. If $color is empty or unset, returns $default_color_index instead, without allocating a new color. This was added in PHPlot-5.2.0, replacing the second half of SetIndexColor. The $default_color_index argument was added in PHPlot-5.7.0, and the $color argument was changed to a reference (so an unset variable can be passed without an error).

GetColorIndexArray($color_array, $max_colors)

Allocates GD color indexes for each color in the array $color_array, which are given as 4 component arrays (R,G,B,A). Up to $max_colors colors will be allocated. (This is used to limit the number of allocated data colors to the number of data sets in the plot, for example.) GetColorIndex is used to allocate each color. Returns an array of GD color indexes to be used in GD drawing functions. This was added in PHPlot-5.3.1.

GetDarkColorIndex($color)

Allocate a GD color index for a darker shade of a color given as a 4 component array (R,G,B,A). Returns a color index to be used in GD drawing functions. The method used is to subtract 48 from each red, green, and blue component (without letting any go negative). The alpha component is not adjusted. The color returned is the exact color requested if it already exists in the image, or if can be allocated, else the closest color available. This is used for shadow colors (for example, in bar charts and pie charts). This was added in PHPlot-5.2.0, replacing the second half of SetIndexDarkColor.

GetDarkColorIndexArray($color_array, $max_colors)

Allocates GD color indexes for a darker shade of each color in the array $color_array, which are given as 4 component arrays (R,G,B,A). Up to $max_colors colors will be allocated. (This is used to limit the number of allocated dark-shade data colors to the number of data sets in the plot, for example.) GetDarkColorIndex is used to allocate each color. Returns an array of GD color indexes to be used in GD drawing functions. This was added in PHPlot-5.3.1.

GetDataColor($row, $idx, &$vars, &$data_color, $extra=0)

Gets the color index to be used for a data element (a point or line segment, for example). This is used by multiple plot drawing functions to get the data color, accounting for a custom data color callback if defined. $row and $idx are the indexes for the data point. $vars is an array argument that maintains information across calls - the caller allocates an empty array, and this function updates it. The color index to use is returned in $data_color. $extra contains extra information for a data color callback. This was added in PHPlot-5.2.0, moving common code into a function.

GetDataErrorColors($row, $idx, &$vars, &$data_color, &$error_color, $extra=0)

This is an extended version of GetDataColor which is used for error bar plots. It returns two color index values: $data_color for the data element, and $error_color for the error bar. This is used by error plot drawing functions, and accounts for a custom data color callback if defined. $row and $idx are the indexes for the data point. $vars is an array argument that maintains information across calls - the caller allocates an empty array, and this function updates it. $extra contains extra information for a data color callback. This was added in PHPlot-5.2.0, moving common code into a function.

GetDefaultTTFont()

Returns the default TrueType font name. If no default font has been set using SetDefaultTTFont, the first time this is called it will go through a list of likely sans-serif fonts, trying to find one that works. The first one that works, or the last one if none works, will be set as the default font. This was added in PHPlot-5.1.3, replacing the static initialization of default font.

GetGridSetting($xy)

Returns a flag indicating whether to draw the grid along the axis indicated by $xy ('x' or 'y'). This implements the grid default which differs for horizontal and vertical plots. This was added in PHPlot-6.0.0, replacing CalcGridSettings().

GetImage($image_filename, &$width, &$height)

Reads an image file from $image_filename, stores the width and height (in pixels) in the $width and $height reference arguments, and returns a PHP GD image resource of the image. This is used by SetInputFile and tile_img. Errors go to PrintError; there is no way for the script to recover. Possible errors include an image file type which is unsupported by PHP GD, or a corrupt image file. Note: This was added at PHPlot-5.0.4, by moving common code from the two calling functions.

GetImageBorderWidth()

This returns the image border width, as set with SetImageBorderWidth or as defaulted. It is used by CalcMargins to account for image border width, and by DrawImageBorder when drawing the image border. This was added in PHPlot-5.1.2.

GetImageType(&$mime_type, &$output_f)

Given the current file type (e.g. 'png'), this sets the MIME type for the image (e.g. 'image/png') and the name of the GD output function (e.g. 'imagepng') corresponding to that type. The results are stored in the arguments, and TRUE is returned unless an error occurs. It is used by PrintImage and EncodeImage. This was added in PHPlot-5.5.0, from code moved out of PrintImage.

GetLegendPosition($width, $height)

This calculates and returns the device coordinates (as a 2 element array X,Y) of the upper left corner of the legend box. $width and $height are the size of the legend box. It accounts for the positioning mode, reference point, base point, and pixel offset as set with SetLegendPosition. Called by DrawLegend. This was added in PHPlot-5.4.0.

GetLegendSizeParams()

This calculates a number of parameters that determine how to draw the legend, and returns an array containing those variables and their values. Called by GetLegendSize (which only uses the 'width' and 'height' elements), and by DrawLegend. This was added in PHPlot-5.4.0.

GetLineSpacing($font)

Given a font array variable, returns the proper spacing in pixels between lines of text using that font. This works for both GD and TrueType fonts. See also SetLineSpacing. Used by ProcessTextGD, ProcessTextTTF, and DrawLegend. Note: This was added at PHPlot-5.0.6, with support for mixing TTF and GD fonts.

GetRangeEndAdjust($which, &$adjust)

Applies a default to $adjust, the plot range end adjustment factor. $which is 'x' or 'y'. If $adjust is already set, the function does nothing. Otherwise, it uses the current plot type to apply a default setting to $adjust. See the notes on the adjust_type entry in Section 10.2.5, “plots[]” for more on the per-plot-type adjustment mode. This is used by CalcPlotRange. It was added at PHPlot-6.0.0.

GetTextAlignment($sin_t, $cos_t, &$h_align, &$v_align, $reverse = FALSE)

Selects the best alignment for text which is at a specific angle ($sin_t, $cos_t) from a point. The result is returned in $h_align and $v_align, suitable for use with DrawText. The alignment is chosen from 8 possible values (left/center, center/bottom, etc.) to keep the closest edge or corner of the text box at a fixed distance from the reference point (typically the center of a pie chart, or a plotted point), regardless of the text string size. For example, text at 0 degrees is left/center aligned, and text at 90 degrees is center/bottom aligned. If $reverse is true, the alignment is reversed; this is used for text inside an ellipse but close to the circumference. Used by CheckDataValueLabels and DrawPieLabel. Note: This was added at PHPlot-5.6.0 by moving code out of CheckDataValueLabels.

initialize($imagecreate_function, $width, $height, $output_file, $input_file)

Initialize a newly created object. This is called from the two class constructors, PHPlot and PHPlot_truecolor. $imagecreate_function is the name of the GD function used to create an image (imagecreate or imagecreatetruecolor). The other arguments are the same as in the class constructors, except the defaults are already applied. This was added in PHPlot-5.6.0 by moving duplicated code from the two constructors into a shared function.

NeedDataDarkColors()

Allocates darker data colors, which are used for shading. This is called by graph drawing functions such as DrawPieChart if they need to use these colors for shading. This was added in PHPlot-5.2.0.

NeedErrorBarColors()

Allocates colors used for error bars. This is called by any graph drawing functions that is going to draw error bars. This was added in PHPlot-5.2.0.

number_format($number, $decimals=0)

Formats a floating point number, like PHP's number_format(), inserting a decimal separator and thousands groups separators. Unlike the PHP function, this uses variables in the PHPlot class to select the separators. The separators can be set with SetNumberFormat, or by default PHPlot will attempt to get locale-specific values. For example, 1234+(56/100) will be returned as "1,234.56" if the locale is "en_US", and as "1.234,56" if the locale is "de_DE". As a fall-back, if locale information is not available, '.' is used for decimal point, and ',' for thousands separator. This fall-back is equivalent to the behavior in PHPlot 5.0rc3 and earlier. This is used by FormatLabel when the formatting type is data, and also for the pie chart labels in DrawPieChart.

pad_array(&$arr, $size)

Pads an array $arr with copies of itself until it reaches the given size. If $arr is a scalar, it will first be converted to an array with one element. Then, if $arr has fewer than $size elements, elements of $arr starting from the first will be appended until it reaches $size elements. This only works on zero-based sequential integer indexed arrays. Called by PadArrays, SetPointShapes, and SetPointSizes. This replaced array_pad_array at PHPlot-5.0.4, however that had an unused 3rd argument, and worked on general indexed arrays.

PadArrays()

Pads the style arrays (line_widths, line_styles, data_colors, etc.) so they are all large enough to contain an entry for each data set or plot line. This uses pad_array. Called by DrawGraph before drawing anything.

PrintError($error_message)

Handles a fatal error within PHPlot. Starting with PHPlot-5.0.5 this and DrawError are identical. PrintError attempts to draw the error message $error_message into the image, and then output the image. This method is used because PHPlot is normally expected to output an image, and text output would not be displayed properly. (If no image resource was available, and the SetIsInline flag is not on, PHPlot will send a 500 Internal Server Error header.) PrintError uses DrawMessage to actually draw the message onto the image. After this, PrintError uses the PHP trigger_error() function to signal a user error. This is normally fatal to the script, unless caught. This will also result in the error message written to the error output stream, which typically ends up in a web server error log.

(Through PHPlot-5.0.4, PrintError wrote an error message to standard output and exited.)

ProcessText($draw_it, $font_id, $angle, $x, $y, $color, $text, $halign, $valign)

This function acts as a bridge, or switch, between the two functions SizeText and DrawText, which handle both GD and TTF text, and the functions which specifically handle GD text or TTF text. The arguments to this function are the same as DrawText except for an additional first argument $draw_it. If $draw_it is true, text is drawn. This is used by DrawText. If $draw_it is false, only the bounding box size of the text is calculated and returned. This is used by SizeText. In text sizing mode, the x, y, color, halign, and valign arguments are ignored, as they are not needed when calculating the text bounding box size. This function is only called by SizeText and DrawText, and calls either ProcessTextTTF or ProcessTextGD.

ProcessText examines the $font_id argument and handles the variations described under DrawText. If $font_id is an array, it is assumed to be an element of the member array $fonts[], and is passed as-is to the lower level functions. If it is a string that exists as an index to $fonts[], that font array is used. In all other cases, the generic font is used.

ProcessTextGD($draw_it, $font, $angle, $x, $y, $color, $text, $h_factor, $v_factor)

Draws GD fixed-font text, or calculates the size of GD fixed-font text. This is only called by ProcessText after it determines that GD text is in use. If $draw_it is true, text is drawn; if $draw_it is false, only the bounding box size of the text is calculated and returned as a two-element array ($width, $height). Here $width is measured along the X axis, and $height along Y, regardless of the text angle. These are the size of an orthogonal bounding box that contains the text block. The $font argument is a PHPlot font array, which must reference a GD font. The $angle is 0 or 90 degrees, as GD text only supports those values. $x, $y are the reference point of the text $text, which is drawn in color $color. The text string can contain multiple lines, with a newline character between lines. The $h_factor and $v_factor arguments are translated from the alignment arguments supplied to DrawText or SizeText: 0, 0.5, or 1.0 If $draw_it is false, for text sizing mode, the x, y, color, h_factor and v_factor arguments are ignored.

Note: This was added at PHPlot-5.0.5. It was changed at PHPlot-5.0.6 to take a single font array argument, rather than 3 separate arguments for font number, width, and height.

ProcessTextTTF($draw_it, $font, $angle, $x, $y, $color, $text, $h_factor, $v_factor)

Draws TTF text, or calculates the size of TTF text. This is only called by ProcessText after it determines that TTF text is in use. If $draw_it is true, text is drawn; if $draw_it is false, only the bounding box size of the text is calculated and returned as a two-element array ($width, $height). Here $width is measured along the X axis, and $height along Y, regardless of the text angle. These are the size of an orthogonal bounding box that contains the text block. The $font argument is a PHPlot font array, which must reference a TTF font. The text is drawn at $angle degrees; unlike GD text TTF text can be drawn at any angle. $x, $y are the reference point of the text $text, which is drawn in color $color. The text string can contain multiple lines, with a newline character between lines. The $h_factor and $v_factor arguments are translated from the alignment arguments supplied to DrawText or SizeText: 0, 0.5, or 1.0 If $draw_it is false, for text sizing mode, the x, y, color, h_factor and v_factor arguments are ignored.

Note that the interpretation of the alignment for text at arbitrary angles may not be what you expect. Rotation of text happens before alignment, and alignment and positioning use the orthogonal bounding box of the text.

Note: This was added at PHPlot-5.0.5. It was changed in PHPlot-5.0.6 to take a single font array argument, rather than 2 separate arguments for font filename and size.

SetBgColorIndexes()

Allocates the colors for the image background and image border. Called by SetColorIndexes before drawing anything, and by DrawMessage if needed. This was added in PHPlot-5.7.0 by moving code from SetColorIndexes, so that DrawMessage can set up only the color indexes it needs.

SetColorIndexes()

Allocates all the colors needed for a plot. Called by DrawGraph before drawing anything. Calls SetBgColorIndexes (starting at PHPlot-5.7.0) to set the background and border color indexes. This was added in PHPlot-5.2.0.

SetDashedStyle($which_ndxcol, $use_style = TRUE)

Sets the GD line style to select a dashed line, if line styles are enabled, in preparation for drawing a dashed line. $which_ndxcol is the color index to use for the line, and $use_style is a flag indicating if a styled line is to be drawn. Returns a GD color index to use for drawing. If $use_styles is false, indicating solid lines, the return value is $which_ndxcol. If $use_styles is true or omitted, the return value is a GD constant used to indicate drawing a styled line, and $which_ndxcol is used to set up the line style. The return value is then used by the caller as the color argument in drawing functions such as imageline.

To understand how this function works, see the documentation for the PHP GD function ImageSetStyle() and also refer to SetDefaultDashedStyle. GD expects a line style to be specified as an array of pixel values, which is awkward to deal with. PHPlot uses a shorthand notation with integer values indicating pairs of the number of color pixels ("on" pixels), then transparent pixels ("off" pixels). SetDefaultDashedStyle() creates a template string with a marker for each "on" pixel, and the special GD color code for transparent pixels for each "off" pixel. This template is saved in the class variable default_dashed_style. The actual color to use for the "on" pixels is filled in by SetDashedStyle() before the dashed style is used. The result is an array of pixel values for ImageSetStyle().

(In PHPlot-6.1.0 and earlier, SetDefaultDashedStyle() created a string of PHP code to generate an array of pixel values in the form used by the GD function ImageSetStyle(), and saved this as default_dashed_style. SetDashedStyle() then evaluated the PHP code, with the correct color filled in from $which_ndxcol.)

Called by all functions that need to draw lines that can have a line style applied, including DrawXTicks and DrawYTicks (for drawing the grid lines, not the ticks), and DrawLines for drawing line plots.

The $use_style argument and return value were added in PHPlot-6.0.0. Before that, SetDashedStyle unconditionally set up the line style, and returned a boolean value.

SetDefaultFonts()

Selects all the default font values and sizes. See SetFont for details of the font element names and default values. Called by the class constructor initialization function initialize to initialize fonts in the plot object, and by SetUseTTF to restore the defaults when changing from or to TrueType font usage.

SetDefaultStyles()

Initializes default colors and styles for PHPlot objects. Mostly this calls the public member functions such as SetDataColors but without specifying an array of colors, which causes the member functions to select default values. Called by the class constructor initialization function initialize.

SetIndexColor($which_color, $alpha = 0)

This function was removed in PHPlot-5.2.0. It parsed a color specification, and allocated a GD color index. The first part is replaced by calling SetRGBColor directly, and the second part is implemented with GetColorIndex at graph drawing time.

SetIndexDarkColor($which_color, $alpha = 0)

This function was removed in PHPlot-5.2.0. It parsed a color specification, and allocated a GD color index for a slightly darker shade of the color. The first part is replaced by calling SetRGBColor directly, and the second part is implemented with GetDarkColorIndex at graph drawing time.

SetInputFile($which_input_file)

Sets an image file $which_input_file to be used as the background image for the graph. Also resets the graph size to the size of the image file. Called by the class constructor initialization function initialize. Note: In earlier releases, this was considered an externally available function. After a PHPlot object was created with the constructor, SetInputFile could be used to resize it and set the background image. Although this still works, it is deprecated. SetInputFile should be considered an internal-use-only function. Users should set the background image file using the 4th argument of PHPlot or PHPlot_truecolor when creating an instance of the object.

SetLabelType($mode, $args)

Sets the formatting used for tick, data, and pie chart labels. This implements SetXLabelType, SetYLabelType, SetXDataLabelType, SetYDataLabelType, and part of SetPieLabelType. $mode is either 'x', 'xd', 'y', 'yd', or 'p' to select the type of label (x, y for tick labels; xd, yd for data labels; p for pie chart labels). $args is an array of arguments, with $args[0] selecting the type of formatting (for example, data). Additional array elements depend on the formatting type. For more details, see the above-referenced functions. All arguments to those functions are combined into an array and passed to SetLabelType as $args. Separation of data and tick label formatting was available starting with PHPlot-5.1.0. Support for pie chart label formatting was added in PHPlot-5.6.0.

SetRGBColor($color_asked, $alpha = 0)

Converts a general color specification into a standard form as an array of 4 components: red, green, blue, and alpha, and returns the array. The 3 color components are integers in the range 0-255, and the alpha component is an integer in the range 0-127 (where 0 means opaque). The acceptable color specification forms are documented in Section 3.5.1, “Color Parameter Forms” and Section 4.3.4, “Color Parameter Form Extensions”, and include color names, component arrays, and strings of the form #RRGGBB and #RRGGBBAA. The alpha argument provides a default value if the color specification does not include alpha; the default 0 makes the color opaque. This is used directly by all functions that accept a color specification. Use of alpha in the color specification, the default alpha argument, and the 4th component in the returned array were added in PHPlot-5.1.1.

SetupAreaPlot($stacked, &$xd, &$yd)

Sets up for an area plot (plot types area, stackedarea, squaredarea, and stackedsquaredarea). $stacked indicates a stacked (cumulative) plot, so the Y values in the data array are to be accumulated for each X row.

This function calculates two arrays, $xd[] and $yd[], which are used for drawing area fills. On return, $xd[] contains the device coordinates for the X values from the data array (or implied, for text-data data type). $yd[] is returned as a 2-dimensional array of Y values in device coordinates. SetupAreaPlot adds an additional column of Y values representing the X axis, which is the base line for area fills. For stacked plots, this goes before the first real Y value in the array. For unstacked plots, it goes after the last real Y value in the array.

While traversing the data array, this function also draws axis data labels if they are enabled. (Doing it here avoids having the calling functions need to access the data array at all.)

This was added in PHPlot-6.2.0.

SizeText($font, $angle, $text)

Calculates the size of a block of text. It works on both GD (fixed-font) and TTF text. $font is a text element name, empty, or a PHPlot font array (use of an array is deprecated); see DrawText for details. $angle is the text angle in degrees. $text is the text string. The text string can contain multiple lines, with a newline character between lines. This function just calls ProcessText in text sizing mode to do the work. It returns a two-element array with the text width and height. These are the width and height of an orthogonal bounding box (box aligned with the X and Y axes) which contains the rotated text block. Called by functions which need to determine text size for laying out plot elements, such as CalcMargins. This function replaced TTFBBoxSize at PHPlot-5.0.5.

tile_img($file, $xorig, $yorig, $width, $height, $mode)

Tiles an image from a file onto the plot image. $file is the filename of the image to use as the tile. ($xorig, $yorig) are the origin point for the tiling, and ($width, $height) are the area to be tiled. These are used to tile just under the plot area versus the entire image. The $mode can be centeredtile, tile, or scale. Scale mode scales the source image to fit the target area. Tile and centeredtile modes repeat the source image as needed to fit into the target area; the difference is that centeredtile offsets the tile start position by half its size, which works better for some tiles. Called by DrawBackground and DrawPlotAreaBackground if an image file is selected for the plot area or overall background.

truncate_array(&$array, $size)

This was added in PHPlot-5.2.0 and removed in PHPlot-5.3.1, when data color processing was changed to not truncate the color arrays.

TTFBBoxSize($size, $angle, $font, $string)

This function was removed at PHPlot-5.0.5. It was replaced by SizeText.

TuneAutoRange($which, $zero_magnet, $adjust_mode, $adjust_amount)

This implements TuneXAutoRange and TuneYAutoRange to store tuning parameters used by the automatic range calculation. $which is 'x' or 'y', and the other arguments are as described under those two public functions. This was added in PHPlot-6.0.0

TuneAutoTicks($which, $min_ticks, $tick_mode, $tick_inc_integer)

This implements TuneXAutoTicks and TuneYAutoTicks to store tuning parameters used by the tick increment calculation. $which is 'x' or 'y', and the other arguments are as described under those two public functions. This was added in PHPlot-6.0.0

xtr($x_world)

Translates an X world coordinate value into a pixel coordinate value. This uses the scale and translation set up by CalcTranslation. See GetDeviceXY for a public interface.

ytr($y_world)

Translates a Y world coordinate value into a pixel coordinate value. This uses the scale and translation set up by CalcTranslation. See GetDeviceXY for a public interface.

__sleep()

This is a PHP "magic method" that prepares a PHPlot object for serialization. It stores the PHPlot version string (for checking at wakeup time), and a flag indicating if it used a truecolor image or not. See Section 4.2, “PHPlot Object Serialization”. This was added in PHPlot-5.8.0.

__wakeup()

This is a PHP "magic method" that re-creates a PHPlot object after unserialization. It checks the stored version string to make sure the object was serialized with the exact same PHPlot version, and then re-creates the image resource. See Section 4.2, “PHPlot Object Serialization”. This was added in PHPlot-5.8.0.

SourceForge.net Logo

This version of the manual was produced for the PHPlot Sourceforge project web service site, which requires the logo on each page.

To download a logo-free copy of the manual, see the PHPlot project downloads area.