DRAWTEXT draws the specified text into the display panel using the currently selected font (using SELECTFONT). It can optionally constrain the output to a bounding rectangle specified by X, Y and Width, Height.

When DRAWTEXT is called without a Width or Height parameter, the supplied text is drawn on a single line. When a Width and Height parameter is supplied, DRAWTEXT formats the text so that it fits within the specified rectangle. In other words, the text is formatted onto multiple lines with proper word-breaks so that it best fits the required space. The number of lines used is calculated by dividing the Height parameter by the pixel height of the current font. Therefore to ensure DRAWTEXT outputs text on one line but is bounded horizontally (by width), use the return value of getfontheight as the Height parameter.

This statement is only valid in the Render handler.

Parameters

Text

The text to render

X

The X position to begin rendering the text at. 0 is the top left corner of the display panel.

Y

The Y position to begin rendering the text at. 0 is the top left corner of the display panel.

Width

An optional constraint width in pixels. Any text that falls outside of this maximum width will be clipped (not drawn).

Height

An optional constraint height in pixels. Any text that falls outside of this maximum height will be clipped (not drawn).

 

Return Value

The resulting height of the text in pixels when drawn. This return value differs from the return value of getfontheight as follows. getfontheight returns the pixel height of a representative single line string of text in the current font. The return value of DRAWTEXT provides the exact pixel height required to fit the string in the specified line width. This is identical to the return value of the getstringheight statement.

For example, to display a string of text that always fits inside the display panel you may specify 0, 0 as the X and Y parameters and getpanelwidth(), getpanelheight() as the Width and Height parameters. DRAWTEXT will then reformat the supplied string onto multiple lines so that no one line is wider than the width of the panel. Once the number of lines required has been calculated, DRAWTEXT draws the string and returns the height of one line of text multiplied by the number of lines required to display the text. In real terms:

- The panel width is 200 pixels
- The panel height is 400 pixels
- The current font height is 10 pixels
- DRAWTEXT is called as follows: int Height = drawtext("A long string", 0, 0, getpanelwidth, getpanelheight);
- DRAWTEXT determines 2 lines are required for the string (example)
- DRAWTEXT returns: lines required * font height == 2 * 10 == 20 pixels

This return value is useful for determining the positioning and formatting of any items below text drawn by DRAWTEXT, as well as the real height of a string compared to the requested maximum bounding height. Note that using DRAWTEXT to simply calculate the height of a string is inefficient, use getstringheight instead.

Example Code

font MyFont;
createfont(MyFont, "Arial", 12);
selectfont(MyFont);

// Draw the text string to the display panel
drawtext("Example", 10, 10);

// Draw the text constrained to a 25 pixel square
int Height = drawtext("Example", 10, 10, 25, 25);