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>DrawMessage</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="DrawGraph.html" title="DrawGraph" /><link rel="next" href="EncodeImage.html" title="EncodeImage" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">DrawMessage</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="DrawGraph.html">Prev</a> </td><th width="60%" align="center">PHPlot Function Reference</th><td width="20%" align="right"> <a accesskey="n" href="EncodeImage.html">Next</a></td></tr></table><hr /></div><div class="refentry"><a id="DrawMessage"></a><div class="titlepage"></div><div class="refnamediv"><h2><span class="refentrytitle">DrawMessage</span></h2><p>DrawMessage — Draw a text message on the image, discarding the plot</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">$plot->DrawMessage(<em class="parameter"><code>$text</code></em>, [<span class="optional"><em class="parameter"><code>$options</code></em></span>])</pre></div><div class="refsect1"><a id="idp1377641892"></a><h2>Description</h2><p><code class="function">DrawMessage</code> draws a text message on the image,effectively replacing the plot with a message. It can be used instead of<a class="xref" href="DrawGraph.html" title="DrawGraph"><span class="refentrytitle">DrawGraph</span></a> to handle an application-level error condition,for example.</p></div><div class="refsect1"><a id="idp1377643356"></a><h2>Parameters</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="replaceable"><code>$text</code></em></span></dt><dd><p>The text message to display. This can include newlines, which will resultin line breaks.</p></dd><dt><span class="term"><em class="replaceable"><code>$options</code></em></span></dt><dd><p>Optional associative array of settings to control the appearance of themessage image. If missing or empty, the defaults result in small blacktext on a white background, with word wrapping. If provided, the optionsarray may contain the following keys and values:</p><div class="informaltable"><table summary="DrawMessage options" border="1"><colgroup><col class="c1" /><col class="c2" /><col class="c3" /></colgroup><thead><tr><th>Option name (array key)</th><th>Default value</th><th>Description</th></tr></thead><tbody><tr><td>draw_background</td><td>False</td><td>If true, draw the image background</td></tr><tr><td>draw_border</td><td>False</td><td>If true, draw the image border</td></tr><tr><td>force_print</td><td>True</td><td>If true, ignore SetPrintImage(False) and alwaysoutput</td></tr><tr><td>reset_font</td><td>True</td><td>If true, reset fonts to standard sizes and type</td></tr><tr><td>text_color</td><td>''</td><td>If not empty, color to use for the text</td></tr><tr><td>text_wrap</td><td>True</td><td>If true, word-wrap the text</td></tr><tr><td>wrap_width</td><td>75</td><td>Width in characters for word-wrapping the text</td></tr></tbody></table></div><p></p></dd></dl></div></div><div class="refsect1"><a id="idp1377655156"></a><h2>Notes</h2><p>The default option values are chosen to be appropriate for error messages,and are designed to be 'fail-safe'. (For example, resetting fonts to usethe built-in GD fonts ensures that there will be no error with TrueTypefont files while displaying an error message.)</p><p>If the <code class="literal">draw_background</code> option is <code class="literal">False</code>or defaulted, the image will have a white background.If <code class="literal">draw_background</code> is <code class="literal">True</code>,then the image will have a background as specified by prior calls to<a class="xref" href="SetBackgroundColor.html" title="SetBackgroundColor"><span class="refentrytitle">SetBackgroundColor</span></a> or <a class="xref" href="SetBgImage.html" title="SetBgImage"><span class="refentrytitle">SetBgImage</span></a>.If neither of those has been called before <code class="function">DrawMessage</code>,then the background will be white regardless of the<code class="literal">draw_background</code> option value.Note that if an input file was given to the PHPlot constructor to set abackground, that will not be used with a message image, regardless of theoptions.</p><p>If the <code class="literal">draw_border</code> option is <code class="literal">False</code>or defaulted, no border will be drawn.If <code class="literal">draw_border</code> is <code class="literal">True</code>,then the the image will have a border as specified by prior calls to<a class="xref" href="SetImageBorderType.html" title="SetImageBorderType"><span class="refentrytitle">SetImageBorderType</span></a>, <a class="xref" href="SetImageBorderWidth.html" title="SetImageBorderWidth"><span class="refentrytitle">SetImageBorderWidth</span></a>,and <a class="xref" href="SetImageBorderColor.html" title="SetImageBorderColor"><span class="refentrytitle">SetImageBorderColor</span></a>.Note that if <code class="function">SetImageBorderType</code> was not used to enablea border before <code class="function">DrawMessage</code>, then there will be no border,regardless of the <code class="literal">draw_border</code> option value.</p><p>The message text will be drawn using the PHPlot <code class="literal">generic</code>font settings.But if the <code class="literal">reset_font</code> option is <code class="literal">True</code>or defaulted, all fonts will be reset to defaults first,resulting in the use of GD font #2 (a small monospaced font).If <code class="literal">reset_font</code> is <code class="literal">False</code>,the <code class="literal">generic</code> font settings will be used without reset.Use <a class="xref" href="SetFont.html" title="SetFont"><span class="refentrytitle">SetFont</span></a>, <a class="xref" href="SetFontGD.html" title="SetFontGD"><span class="refentrytitle">SetFontGD</span></a>, or<a class="xref" href="SetFontTTF.html" title="SetFontTTF"><span class="refentrytitle">SetFontTTF</span></a> in this case to select the font.For example, to use a TrueType font for your message, call<code class="literal">$plot->SetFontTTF('generic', $font_name, $font_size)</code>,then set the <code class="literal">reset_font</code> option to <code class="literal">False</code>when calling <code class="function">DrawMessage()</code>.</p><p>If the <code class="literal">text_color</code> option is empty or defaulted,the text will be black. To use a different color for the message text,set <code class="literal">text_color</code> to any valid PHPlot color specification,such as a color name or "#rrggbb" form(see <a class="xref" href="conc-colors.html#conc-colors-forms" title="3.5.1. Color Parameter Forms">Section 3.5.1, “Color Parameter Forms”</a>).</p><p>If the <code class="literal">force_print</code> option is <code class="literal">True</code> ordefaulted, the message image will be output after creating it - ignoringany setting made with <a class="xref" href="SetPrintImage.html" title="SetPrintImage"><span class="refentrytitle">SetPrintImage</span></a>.If <code class="literal">force_print</code> is <code class="literal">False</code>,and <code class="function">SetPrintImage(False)</code> was previously called,the message image will created but not output.This would be appropriate when using <a class="xref" href="PrintImage.html" title="PrintImage"><span class="refentrytitle">PrintImage</span></a> or<a class="xref" href="EncodeImage.html" title="EncodeImage"><span class="refentrytitle">EncodeImage</span></a> to output the image.Note that if <code class="function">SetPrintImage(False)</code> was not called,the image will be output regardless of the <code class="literal">force_print</code>option value.</p><p>The text may contain newlines, which will produce separate lines of textin the message image.The text will be word-wrapped (unless the <code class="literal">text_wrap</code>option is set to <code class="literal">False</code>).Each line of text will be left aligned, and the bounding boxof the text will be centered in the image. PHPlot makes no attempt to makesure the text will fit, but the upper left corner will always be visible.</p><p>After using <code class="function">DrawMessage</code> and automatic or subsequentoutput of the image, the PHPlot object should not be reused.</p><p>See <a class="xref" href="ex-drawmessage.html" title="5.42. Example - DrawMessage">Section 5.42, “Example - DrawMessage”</a> for an example of this function.</p></div><div class="refsect1"><a id="idp1377676692"></a><h2>History</h2><p>This function was added in PHPlot-5.7.0.</p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="DrawGraph.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="EncodeImage.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">DrawGraph </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> EncodeImage</td></tr></table></div></body></html>