SetLegendPosition
Prev | PHPlot Function Reference | Next

## SetLegendPosition

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.

Prev | Up | Next
SetLegendPixels | Home | SetLegendReverse