Chapter 9. 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($verticals = TRUE)

Calculates values for bars and stackedbars plot types. It calculates the width of the bars and the margins around and between them. The argument was added in PHPlot-5.1.2 to support 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()

Applies defaults to the X and Y grid settings if not user specified. This was added in PHPlot-5.1.2 when the previous, static defaults (X grid off, Y grid on) needed to be dependent on the plot type. Called by DrawGraph.

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. Called by DrawGraph, after FindDataLimits is used to examine the data array values.

CalcTicks($which)

Calculates 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 it still uses the same method of just dividing the interval by 10 if there is no user-supplied interval or tick count. 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.

CheckLabels()

Fixes up the data and tick label position, angle, and format settings. 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, and the default formatting for X and Y data labels, to match the corresponding settings for tick labels if they were not already set. 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.

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 each choice). If the string to check is not found in the string of acceptable choices, a fatal error will be reported using DrawError. 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 each choice). 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 DrawError. 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.

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 must be called from internal functions that produce plots that use point shapes: currently DrawDots and DrawDotsError. This was added in PHPlot-5.1.0.

DecodeDataType()

Analyzes 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, 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.

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 Chapter 6, Callbacks for more information on callbacks. Starting with PHPlot-5.1.3, DoCallback returns the value returned by the callback function, if any.

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()

Draws the image background, either an image file or solid fill or nothing. Called by DrawGraph.

DrawBar($x1, $y1, $x2, $y2, $data_color, $alt_color, $shade_top = TRUE, $shade_side = TRUE)

Draws a single bar (or bar segment), with either shading or border. Four corner coordinates and 2 color indexes are provided. The first color $data_color is the bar fill color. The second color $alt_color is either the shading color or the border color, depending on whether shading is on or not (see 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.

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.

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, $x_world, $y_world, $text, $halign, $valign, $x_adjustment=0, $y_adjustment=0, $min_width=NULL, min_height=NULL)

Draws a data value label (previously called "Y data label"). These are the above-bar or in-bar labels on bar and stackedbar charts.

x_or_y is 'x' or 'y' to select the font, angle, and formatting type. The label is drawn at world coordinates (x_world, y_world) after device coordinate offset (x_adjustment, y_adjustment) is applied. Two arguments halign and valign specify the text alignment relative to the plotting point (see DrawText). The text argument is formatted with FormatLabel before drawing. The final arguments min_width and min_height are used to prevent labels from overlapping their allocated space. If either of these is supplied, the text is sized before drawing, and if it won't fit in the space the text is not drawn. This is used to suppress labels that are too wide to be drawn inside their bars, for example.

This function was added in PHPlot-5.1.3 and replaced DrawDataLabel. It is called by the bar chart drawing functions including DrawBars and DrawStackedBars if these labels are enabled.

DrawDot($x_world, $y_world, $record, $color)

Draws a single marker point ('dot') at the given X and Y world 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 those plotting routines that include dots: DrawDotsError and DrawDots.

DrawDots($paired = False)

Draws a dot plot. Called by DrawGraph when the plot type is points, and by DrawLinePoints for the points portion of a linepoints plot. If the data type indicates an error bar plot, it calls DrawDotsError instead. (Through PHPlot-5.1.2, this was called directly from DrawGraph for both lines and linepoints plots, but not for error bar plots.) $paired is true for linepoints plots, to suppress drawing elements that would be duplicated by the 'lines' part of the plot. (This argument was added in PHPlot-5.1.3.)

DrawDotsError($paired = False)

Draws a dot plot with error bars. Called by DrawDots (and indirectly from DrawLinePoints) when the data type indicates an error bar plot. (Through PHPlot-5.1.2 this was called directly by DrawGraph.) $paired is true for linepoints error plots, and defaults to false for points error plots. If true, it suppress drawing elements that would be duplicated by DrawLinesError. (This argument was added in PHPlot-5.1.3.)

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.)

(Through PHPlot-5.0.4, DrawError wrote the error message to an image, wrote the image, and exited.)

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()

Draws a border around the image, if enabled by SetImageBorderType. Called by DrawGraph.

DrawLegend(x,y,type)

Draws the plot legend. This includes the box, text labels, and color boxes. 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. Called by DrawGraph when the plot type is lines, and by DrawLinePoints for the lines portion of a linepoints plot. If the data type indicates an error bar plot, it calls DrawLinesError instead. (Through PHPlot-5.1.2, this was called directly from DrawGraph for both lines and linepoints plots, but not for error bar plots.) $paired is true for linepoints plots, to suppress drawing elements that would be duplicated by the points part of the plot. (This argument was added in PHPlot-5.1.3.)

DrawLinesError($paired = False)

Draws a lines plot with error bars. Called by DrawLines (and indirectly from DrawLinePoints) when the data type indicates an error bar plot. (Through PHPlot-5.1.2 this was called directly by DrawGraph.) $paired is true for linepoints error plots, to suppress drawing elements that would be duplicated by DrawDotsError. (This argument was added in PHPlot-5.1.3.)

DrawPieChart()

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

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()

Draws the border around the plot area. This draws zero to four lines around the plot area (depending on SetPlotBorderType). It only draws the outline; other functions draw the tick marks and labels for the X axis and Y axis. Called by DrawGraph.

DrawSquared()

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

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($which_font, $which_angle, $which_xpos, $which_ypos, $which_color, $which_text, $which_halign = 'left', $which_valign = 'bottom')

Draws a string of text $which_text, at position ($which_xpos, $which_ypos). The font is selected with $which_font, which is one of the font arrays in the object. The text is drawn at angle $which_angle (built-in fonts can be used at 0 and 90 degrees only, TrueType at any angle). $which_color is a GD color index for the image. Text alignment relative to the (x,y) point is controlled with $which_halign (center, left, or right) and $which_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.

There are 7 font array variables in the PHPlot object. Through PHPlot-5.0.5, these were separate variables: generic_font, title_font, legend_font, x_label_font, y_label_font, x_title_font, and y_title_font. Starting with PHPlot-5.0.6, these were combined into a single class array variable fonts, indexed by the element name, for example $fonts['generic'].

Starting with PHPlot-5.1.0, $which_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.

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=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. This also calls DrawXDataLine to draw a line from the label to the point, if enabled. This is used by vertical plots. Called by plot drawing routines for all plot types except pie: DrawArea, DrawBars, DrawDots, DrawDotsError, DrawThinBarLines, DrawLines, DrawLinesError, DrawSquared, and DrawStackedBars.

DrawXDataLine($xpos, $row)

Draws X data 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.

DrawXTick($which_xlab, $which_xpix)

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. Called by DrawXTicks. This was added at PHPlot-5.0.5 by splitting the code out of DrawXTicks, for symmetry with DrawYTicks.

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)

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. This is used by horizontal plots, and was added in PHPlot-5.1.2. Called by horizontal plot drawing functions such as DrawHorizBars.

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

Draws an error bar for the point at world coordinates ($x_world, $y_world). $error_height is the height (in world coordinates) of the error bar: positive for the upper range error, negative for the lower range error. The $error_bar_type is set to tee or line by SetErrorBarShape. Called by DrawDotsError and DrawLinesError, twice for each point on the plot (upper range error and lower range error).

DrawYTick($which_ylab, $which_ypix)

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. Called by DrawYTicks.

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 or data label. This implements the format type selected with SetXLabelType ,SetYLabelType, SetXDataLabelType ,and SetYDataLabelType. By default it returns the value as-is, or it can format it as a floating point number or date/time value. 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.

GetBarColors($row, $idx, &$vars, &$data_color, &$alt_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. $alt_color is the color index to use for shading (if shading is on), else the color index to use for the bar border (if shading is off). (This dual use argument corresponds to the usage of DrawBar.) This was added in PHPlot-5.2.0, moving common code into a function.

GetColorIndex($color)

Allocate a GD color index for a color given as a 4 component array (R,G,B,A). 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. This was added in PHPlot-5.2.0, replacing the second half of SetIndexColor.

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.

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.

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.

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.

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.) 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, $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.

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.

SetColorIndexes()

Allocates all the colors needed for a plot. Called by DrawGraph before drawing anything. This was added in PHPlot-5.2.0.

SetDashedStyle($which_ndxcol)

Sets the GD line style to select a dashed line, in preparation for drawing a dashed line. To understand how this works, it helps to look at 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, then transparent pixels. SetDefaultDashedStyle creates a string of PHP code to generate an array of pixel values the way GD wants them, but defers filling in the exact color to use. SetDashedStyle evaluates this string with $which_ndx_color set to the color to use for the current line. The result is an array of pixel values for GD's ImageSetStyle. Called by DrawXTicks and DrawYTicks if a dashed grid is selected, as well as other line drawing functions such as DrawLines if dashed lines are used.

SetDefaultFonts()

Selects all the default font values and sizes. See SetFont for details of the font element names and default values. Called by PHPlot, the class constructor, 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 PHPlot, the class constructor, to initialize the plot object.

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. This is used by the constructor, PHPlot. 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 when creating an instance of the object.

SetLabelType($mode, $args)

Sets the formatting used for tick and data labels. This implements SetXLabelType, SetYLabelType, SetXDataLabelType ,and SetYDataLabelType. $mode is either 'x', 'xd', 'y', or 'yd' and selects the axis to configure and type of label being drawn (x, y for tick labels; xd, yd for data 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.

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 3.6.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.

SizeText($which_font, $which_angle, $which_text)

Calculates the size of a block of text. It works on both GD (fixed-font) and TTF text. $which_font is a PHPlot font array, $which_angle is the text angle in degrees, and $which_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 file over another the current 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. cale 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)

Truncates a 0-based sequential integer indexed array so it has no more than $size elements. This is used to trim the data colors arrays. This was added in PHPlot-5.2.0.

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

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

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.