Home#include <lua/gfx.lh>
- gcx:text(x, y, text [, flags])
- gcx:text(x, y, w, h, text [, flags])
- gcx:text(rect, text [, flags])
- fit, x, y, w, h = gcx:textsize(...)
SYNOPSIS
DESCRIPTION
The function gcx:text() is a versatile text painter. It supports several alignment options, word-wrap, justification and bidirectional text (e.g. Arabic or Hebrew).
The second function gcx:textsize() accepts the same arguments as gcx:text(), but does only the calculation steps without actually painting anything. As a result, it returns a flag indicating if the text did fit into the provided bounding box and also returns the final bounding box of the calculated output.
First form, no rectangle size specified
The first form draws text at position x, y using the stored font and colors. It supports three alignment modes:
| Mode | x specifies |
|---|---|
| "left" | Left edge of text |
| "right" | Right edge of text |
| "center" | Horizontal center of text |
The y coordinate specifies the position of the baseline of the font. The baseline is at the lower edge of the upper case letter A. If there are newlines in the text string, the y coordinate is advanced by the font's height and the alignment is calculated anew for the next line.
Forms 2 and 3: With box size given
Draws text into the specified rectangle using the stored font and colors.
flags specifies the alignment and text parsing flags. The default alignment is top/left, while there is no text parsing by default.
The function supports automatic word-wrapping. A new line is automatically started when a word will not fit in the current line.
As an extension to word-wrap, there is the justified mode, where whitespace between words is made equal in size so the text is aligned to both left and right edges. Justified mode always includes word-wrap mode.
For the justified mode, it is still possible to specify left, right or centered alignment. This alignment is only applied to hard line breaks. A hard line break happens wherever there is a newline character in the text, and also for the last line of the text.
Advanced text parsing can optionally be used to render text in a language that is written right-to-left, it can automatically handle the arabic joining algorithm and knows about arabic numerals.
The flags parameter is expected to be a string. Each character in the flags modifies the behaviour of the text drawing:
| Alignment flags | |
|---|---|
| 't' | Top alignment |
| 'b' | Bottom alignment |
| 'l' | Left alignment |
| 'r' | Right alignment |
| 'm' | Centers the whole block of text horizontally. Compare with normal horizontal center via 'c', which centers each line by itself. |
| 'c' | In combination with 't' or 'b': each line horizontally centered. In combination with 'l' or 'r': vertically centered. To center in both directions, give two 'c' characters. |
| Word-wise alignment | |
| 'w' | Automatically word-wrap the text inside the given horizontal width. |
| 'j' | Justified text, implies word-wrap. |
| Text parsing | |
| 'J' | Perform arabic joining. |
| 'A' | Any ASCII digits that are encountered within arabic text are converted to arabic numerals. |
| 'R' | Default rendering direction is Right-To-Left. |
| 'L' | Default rendering direction is Left-To-Right. |
| 'M' | Measure mode. Makes gcx:text() also do the same calculations and returns the same result as gcx:textsize() in addition to rendering. |
Any of the letter 'J', 'A', 'R' or 'L' will cause the text to be processed by the bidirectional algorithm. See string.utf8bidi() for more information.
It is possible to set a default value for flags by calling gcx:textformat(). The default value is processed by each call to gcx:text(). When there are both default and specific flags, then the default flags are processed first, then the specific flags.
For backward compatibility, the following keywords can be used for mode:
| Mode |
|---|
| "topleft" as alias for "tl" |
| "topright" as alias for "tr" |
| "bottomleft" as alias for "bl" |
| "bottomright" as alias for "br" |
| "topcenter" as alias for "tc" |
| "bottomcenter" as alias for "bc" |
| "centerleft" as alias for "cl" |
| "centerright" as alias for "cr" |
| "middle" as alias for "cc" |
It is not possible to combine these aliases with any of the other flags listed above. The default flags specified with gcx:textformat() are ignored when using the compatibility values.
RETURN VALUE
The function gcx:textsize() and, optionally, the function gcx:text() return five values. The first is a flag that is true if the result did fit in the bounding box that was provided to the function. The final four are the bounding box actually occupied by the generated text. The four values are x, y, w and h. The coordinates x and y indicate the top-left corner of the calculated boundary box, while w and h contain the width and height.
ERRORS
Raises an error if gcx is not a graphics context.
NOTES
When working with non-western languages, the background color should be set to fully transparent.
Some writing systems use combining letters, where one letter is painted over another. When the background color is not set to fully transparent, this will not work, as one letter erases the other instead of combining with it. (An example would be arabic "Thank you" = "\u0634\u0643\u0631\u0627\u064B" = شكراً.)
Incorporates code from the UCData package under a BSD style License.
EXAMPLE
>
gcx:text(gcx:width()/2, gcx:height()/2, "Hello World", "center")