SetLegendPosition

SetLegendPosition
Prev	PHPlot Function Reference	Next

SetLegendPosition — Position the legend

Synopsis

$plot->SetLegendPosition($x, $y, $relative_to, $x_base, $y_base,
       [$x_offset], [$y_offset])

Description

SetLegendPosition lets you position the legend on the image, using relative coordinates, world coordinates, or device (pixel) coordinates.

Parameters

$x, $y

Relative coordinates of a point on the legend box to use as a reference. The coordinates are relative to the size of the legend box, with the upper left corner as (0.0, 0.0) and the lower right corner as (1.0, 1.0).

$relative_to

A string indicating how the next two parameters ($x_base, $y_base) are interpreted. Accepted values are: image, plot, world, or title. See the description of the next parameters for details.

$x_base, $y_base

Reference point for positioning the legend. The interpretation depends on the previous parameter $relative_to as follows.

$relative_to	$x_base, $y_base
image	Relative coordinates of a point on the image. The point on the legend box indicated by ($x, $y) is placed at this point. These coordinates are relative to the size of the image, with (0.0, 0.0) being the upper left corner, and (1.0, 1.0) being the lower right corner.
plot	Relative coordinates of a point on the plot area. (The plot area is generally the area enclosed by the X and Y axis lines.) The point on the legend box indicated by ($x, $y) is placed at this point. These coordinates are relative to the size of the plot area, with (0.0, 0.0) being the upper left corner, and (1.0, 1.0) being the lower right corner.
title	Relative coordinates of a point in the main plot title. The point on the legend box indicated by ($x, $y) is placed at this point. These coordinates are relative to a bounding box which encloses the main plot title, with (0.0, 0.0) being the upper left corner of the title, and (1.0, 1.0) being the lower right corner.
world	World coordinates

$x_offset, $y_offset

Optional arguments specifying an additional offset for the legend, in device (pixel) coordinates. After the legend position has been calculated using the preceding arguments, this offset is added to the position. It can be used to move the legend a little bit away from the edge of the image or plot, for example. If not specified, no offset is applied.

Notes

For examples of using SetLegendPosition, see Section 5.36, “Example - Legend Positioning”.

By default, PHPlot will position the legend in the upper right corner of the plot area, with a small offset. This is equivalent to:

$plot->SetLegendPosition(1, 0, 'plot', 1, 0, -5, 5);

The default behavior can be restored by using NULL for the $x and $y arguments (or the $x_offset and $y_offset arguments) in SetLegendPosition. That is, using NULL for any of those arguments undoes any previous call to SetLegendPosition, SetLegendPixels, and SetLegendWorld.

See SetLegendPixels and SetLegendWorld for simpler forms of legend positioning.

SetLegendWorld($x, $y) is equivalent to SetLegendPosition(0, 0, 'world', $x, $y).

SetLegendPixels($x, $y) is equivalent to SetLegendPosition(0, 0, 'image', 0, 0, $x, $y).

The value of each of X and Y used in relative coordinates are usually in the range (0.0 <= x, y <= 1.0), but this is not required by PHPlot. For the legend box reference point ($x, $y) or when using 'title' or 'plot' mode ($base_x, $base_y), a value outside this range may be used to refer to a point outside the object. For example, using (-1, -1) for ($x, $y) indicates a point above and to the left of the upper left corner of the legend box at a distance equal to the width and height of the legend box. Relative coordinates outside this range for 'image' mode ($base_x, $base_y) will be outside the image and not visible.

Positioning relative to 'world' will not work with pie charts, because they have no valid world coordinates.

History

This function was added in PHPlot-5.4.0, and SetLegendPixels and SetLegendWorld were changed to be simple wrappers that call SetLegendPosition. No other legend positioning methods were available in earlier releases.