Blame | Last modification | View Log | RSS feed
<?xml version="1.0" encoding="ISO-8859-1" standalone="no"?><!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1" /><title>SetLegendPosition</title><link rel="stylesheet" type="text/css" href="phplotdoc.css" /><meta name="generator" content="DocBook XSL Stylesheets V1.78.1" /><link rel="home" href="index.html" title="PHPlot Reference Manual" /><link rel="up" href="reference.html" title="PHPlot Function Reference" /><link rel="prev" href="SetLegendPixels.html" title="SetLegendPixels" /><link rel="next" href="SetLegendReverse.html" title="SetLegendReverse" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">SetLegendPosition</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="SetLegendPixels.html">Prev</a> </td><th width="60%" align="center">PHPlot Function Reference</th><td width="20%" align="right"> <aaccesskey="n" href="SetLegendReverse.html">Next</a></td></tr></table><hr /></div><div class="refentry"><a id="SetLegendPosition"></a><div class="titlepage"></div><div class="refnamediv"><h2><span class="refentrytitle">SetLegendPosition</span></h2><p>SetLegendPosition — Position the legend</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">$plot->SetLegendPosition(<em class="parameter"><code>$x</code></em>, <em class="parameter"><code>$y</code></em>, <em class="parameter"><code>$relative_to</code></em>, <em class="parameter"><code>$x_base</code></em>, <em class="parameter"><code>$y_base</code></em>,[<span class="optional"><em class="parameter"><code>$x_offset</code></em></span>], [<span class="optional"><em class="parameter"><code>$y_offset</code></em></span>])</pre></div><div class="refsect1"><a id="idp1378263996"></a><h2>Description</h2><p><code class="function">SetLegendPosition</code> lets you position the legend on theimage, using <a class="link" href="concepts.html#def-relativecoor">relative coordinates</a>,world coordinates, or device (pixel) coordinates.</p></div><div class="refsect1"><a id="idp1378265580"></a><h2>Parameters</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="replaceable"><code>$x</code></em>, </span><span class="term"><em class="replaceable"><code>$y</code></em></span></dt><dd><p>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 upperleft corner as (0.0, 0.0) and the lower right corner as (1.0, 1.0).</p></dd><dt><span class="term"><em class="replaceable"><code>$relative_to</code></em></span></dt><dd><p>A string indicating how the next two parameters ($x_base, $y_base) areinterpreted. Accepted values are: image, plot, world, or title. See thedescription of the next parameters for details.</p></dd><dt><span class="term"><em class="replaceable"><code>$x_base</code></em>, </span><span class="term"><em class="replaceable"><code>$y_base</code></em></span></dt><dd><p>Reference point for positioning the legend. The interpretation depends onthe previous parameter $relative_to as follows.</p><div class="informaltable"><table summary="Legend position relative to choices" border="1"><colgroup><col class="c1" /><col class="c2" /></colgroup><thead><tr><th>$relative_to</th><th>$x_base, $y_base</th></tr></thead><tbody><tr><td>image</td><td>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.</td></tr><tr><td>plot</td><td>Relative coordinates of a point on the plot area. (The plot area isgenerally 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.</td></tr><tr><td>title</td><td>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 mainplot title, with (0.0, 0.0) being the upper left corner of the title,and (1.0, 1.0) being the lower right corner.</td></tr><tr><td>world</td><td>World coordinates</td></tr></tbody></table></div><p></p></dd><dt><span class="term"><em class="replaceable"><code>$x_offset</code></em>, </span><span class="term"><em class="replaceable"><code>$y_offset</code></em></span></dt><dd><p>Optional arguments specifying an additional offset for the legend, in device(pixel) coordinates. After the legend position has been calculated usingthe preceding arguments, this offset is added to the position. It can beused to move the legend a little bit away from the edge of the image orplot, for example. If not specified, no offset is applied.</p></dd></dl></div></div><div class="refsect1"><a id="idp1378277564"></a><h2>Notes</h2><p>For examples of using <code class="function">SetLegendPosition</code>, see<a class="xref" href="ex-legendpos.html" title="5.36. Example - Legend Positioning">Section 5.36, “Example - Legend Positioning”</a>.</p><p>By default, PHPlot will position the legend in the upper right corner ofthe plot area, with a small offset. This is equivalent to:</p><pre class="programlisting">$plot->SetLegendPosition(1, 0, 'plot', 1, 0, -5, 5);</pre><p>The default behavior can be restored by using NULL for the $x and $y arguments(or the $x_offset and $y_offset arguments)in <code class="function">SetLegendPosition</code>.That is, using NULL for any of those arguments undoes any previous call toSetLegendPosition, SetLegendPixels, and SetLegendWorld.</p><p>See <a class="xref" href="SetLegendPixels.html" title="SetLegendPixels"><span class="refentrytitle">SetLegendPixels</span></a> and <a class="xref" href="SetLegendWorld.html" title="SetLegendWorld"><span class="refentrytitle">SetLegendWorld</span></a>for simpler forms of legend positioning.</p><p><code class="literal">SetLegendWorld($x, $y)</code> is equivalent to<code class="literal">SetLegendPosition(0, 0, 'world', $x, $y)</code>.</p><p><code class="literal">SetLegendPixels($x, $y)</code> is equivalent to<code class="literal">SetLegendPosition(0, 0, 'image', 0, 0, $x, $y)</code>.</p><p>The value of each of X and Y used in relative coordinates are usually in therange (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 torefer 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 thelegend 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.</p><p>Positioning relative to 'world' will not work with pie charts, because theyhave no valid world coordinates.</p></div><div class="refsect1"><a id="idp1378285148"></a><h2>History</h2><p>This function was added in PHPlot-5.4.0, and<a class="xref" href="SetLegendPixels.html" title="SetLegendPixels"><span class="refentrytitle">SetLegendPixels</span></a> and <a class="xref" href="SetLegendWorld.html" title="SetLegendWorld"><span class="refentrytitle">SetLegendWorld</span></a>were changed to be simple wrappers that call<code class="function">SetLegendPosition</code>.No other legend positioning methods were available in earlier releases.</p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="SetLegendPixels.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="reference.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="SetLegendReverse.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">SetLegendPixels </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> SetLegendReverse</td></tr></table></div></body></html>