SetPlotAreaPixels

SetPlotAreaPixels — Set the limits for the plot area in device coordinates

Synopsis

$plot->SetPlotAreaPixels([$x1], [$y1], [$x2], [$y2])
    

Description

SetPlotAreaPixels sets the area to be used for the plot within the image, in device coordinates. (Device coordinates are GD coordinates, with the origin at the top left of the image, X values increase to the right, Y values increase down, and the units in pixels.) The plot area is equal to the image area minus the margins. By default, the margins (and therefore the plot area) are automatically calculated based on the space needed for titles, labels, etc. Use SetPlotAreaPixels to override these automatic calculations and control the plot area. The four coordinate values are specified independently. SetPlotAreaPixels and SetMarginsPixels perform the same function with different semantics.

Parameters

$x1, $y1

Device coordinates of the top left corner of the area to use for the plot. Each value is optional, and if omitted or NULL the automatically calculated value is used.

$x2, $y2

Device coordinates of the bottom right corner of the area to use for the plot. Each value is optional, and if omitted or NULL the automatically calculated value is used.

Notes

The plot area is equal to the image area minus the margins. By default, the margins (and therefore the plot area) are automatically calculated based on the space needed (for the axis labels, tick labels, and tick marks). Use SetPlotAreaPixels to override these automatic calculations and control the plot area.

SetPlotAreaPixels and SetMarginsPixels perform the same function with different semantics. It makes no sense to use both - only the last one called will have an effect.

One possible use for SetPlotAreaPixels is to place multiple plots on an image. See Example 5.18, “Two Plots on One Image” for an example of multiple plots. SetPlotAreaPixels is used there to limit the plot area to only use part of the image for each plot.

Trailing defaulted arguments can be omitted, but non-trailing defaulted arguments must be specified as NULL. For example, to fix the bottom right corner of the plot area at (600, 400) and let PHPlot calculate the upper left corner use:

$plot->SetPlotAreaPixels(NULL, NULL, 600, 400);
      

You do not have to specify both X and Y. The following example sets the right edge of the plot area at X=600 and lets the other 3 edges be automatically calculated:

$plot->SetPlotAreaPixels(NULL, NULL, 600);
      

History

Through PHPlot-5.0.6, SetPlotAreaPixels required all 4 arguments be specified and not be NULL. Starting with PHPlot-5.0.7, each X and Y parameter can either be specified or automatically calculated.

SetPlotAreaPixels and SetPlotAreaWorld can be called in either order. Through PHPlot-5.0.4 this was because SetPlotAreaPixels would reset the scale factors if SetPlotAreaWorld was already called. Starting with PHPlot-5.0.5, both functions just store the information, and no calculations take place until DrawGraph is used.