DrawMessage
Prev | PHPlot Function Reference | Next

## DrawMessage

DrawMessage — Draw a text message on the image, discarding the plot

## Synopsis

    $plot->DrawMessage($text, [$options])

## Description

`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.

## Parameters

`$text`

  The text message to display. This can include newlines, which will result in line breaks.

`$options`

  Optional 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

## Notes

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.

## History

This function was added in PHPlot-5.7.0.

Prev | Up | Next
DrawGraph | Home | EncodeImage