This version of the manual was produced for the
PHPlot Sourceforge project web service site, which requires the logo on each
page.
To download a logo-free copy of the manual, see the
PHPlot project downloads
area.
DrawMessage — Draw a text message on the image, discarding the plot
$plot->DrawMessage($text, [$options])
DrawMessage draws a text message on the image,
effectively replacing the plot with a message. It can be used instead of
DrawGraph to handle an application-level error condition,
for example.
$textThe text message to display. This can include newlines, which will result in line breaks.
$optionsOptional associative array of settings to control the appearance of the message image. If missing or empty, the defaults result in small black text on a white background, with word wrapping. If provided, the options array may contain the following keys and values:
| Option name (array key) | Default value | Description |
|---|---|---|
| draw_background | False | If true, draw the image background |
| draw_border | False | If true, draw the image border |
| force_print | True | If true, ignore SetPrintImage(False) and always output |
| reset_font | True | If true, reset fonts to standard sizes and type |
| text_color | '' | If not empty, color to use for the text |
| text_wrap | True | If true, word-wrap the text |
| wrap_width | 75 | Width in characters for word-wrapping the text |
The default option values are chosen to be appropriate for error messages, and are designed to be 'fail-safe'. (For example, resetting fonts to use the built-in GD fonts ensures that there will be no error with TrueType font files while displaying an error message.)
If the draw_background option is False
or defaulted, the image will have a white background.
If draw_background is True,
then the image will have a background as specified by prior calls to
SetBackgroundColor or SetBgImage.
If neither of those has been called before DrawMessage,
then the background will be white regardless of the
draw_background option value.
Note that if an input file was given to the PHPlot constructor to set a
background, that will not be used with a message image, regardless of the
options.
If the draw_border option is False
or defaulted, no border will be drawn.
If draw_border is True,
then the the image will have a border as specified by prior calls to
SetImageBorderType, SetImageBorderWidth,
and SetImageBorderColor.
Note that if SetImageBorderType was not used to enable
a border before DrawMessage, then there will be no border,
regardless of the draw_border option value.
The message text will be drawn using the PHPlot generic
font settings.
But if the reset_font option is True
or defaulted, all fonts will be reset to defaults first,
resulting in the use of GD font #2 (a small monospaced font).
If reset_font is False,
the generic font settings will be used without reset.
Use SetFont, SetFontGD, or
SetFontTTF in this case to select the font.
For example, to use a TrueType font for your message, call
$plot->SetFontTTF('generic', $font_name, $font_size),
then set the reset_font option to False
when calling DrawMessage().
If the text_color option is empty or defaulted,
the text will be black. To use a different color for the message text,
set text_color to any valid PHPlot color specification,
such as a color name or "#rrggbb" form
(see Section 3.5.1, “Color Parameter Forms”).
If the force_print option is True or
defaulted, the message image will be output after creating it - ignoring
any setting made with SetPrintImage.
If force_print is False,
and SetPrintImage(False) was previously called,
the message image will created but not output.
This would be appropriate when using PrintImage or
EncodeImage to output the image.
Note that if SetPrintImage(False) was not called,
the image will be output regardless of the force_print
option value.
The text may contain newlines, which will produce separate lines of text
in the message image.
The text will be word-wrapped (unless the text_wrap
option is set to False).
Each line of text will be left aligned, and the bounding box
of the text will be centered in the image. PHPlot makes no attempt to make
sure the text will fit, but the upper left corner will always be visible.
After using DrawMessage and automatic or subsequent
output of the image, the PHPlot object should not be reused.
See Section 5.42, “Example - DrawMessage” for an example of this function.
This version of the manual was produced for the
PHPlot Sourceforge project web service site, which requires the logo on each
page.
To download a logo-free copy of the manual, see the
PHPlot project downloads
area.