int error = MeasureText(APTR handle, STRPTR str, int count, int encoding,
                struct hwTextExtent *te, struct hwTextLayout *tl, struct
                hwTagList *tags);

If the plugin hasn't set the HWFONTFLAGS_LAYOUT flag for the font in its LoadFont() implementation, the string passed in str will never contain any line breaks. Handling line breaks is only necessary if your plugin has requested to do its own layouting by setting the HWFONTFLAGS_LAYOUT flag in LoadFont().

Your MeasureText() implementation has to return the dimensions of the text in the te parameter that points to a struct hwTextExtent which looks like this:

struct hwTextExtent { int MinX; [out] int MinY; [out] int MaxX; [out] int MaxY; [out] int Width; [out] int Height; [out] };

Your implementation of MeasureText() must set all the structure members to the correct dimensions. Here is a description of the individual structure members:

MinX:

Set this to the offset to the left side of the bounding box. This can be negative when characters extend to the previous character's area. This often happens with character such as "j".

MinY:

Set this to the offset from the baseline to the top of the bounding box. This should always be negative.

MaxX:

Set this to the offset to the right side of the bounding box.

MaxY:

Set this to the offset from the baseline to the bottom of the bounding box.

Width:

Set this to the cursor advance that rendering the text will cause.

Height:

This should be set to the font height.

All values are in struct hwTextExtent are in pixels.

The tl parameter contains a pointer to a struct hwTextLayout. This structure contains detailed information about the text layout. Most of the structure members are only initialized for fonts that have requested to do their own layouting by setting the HWFONTFLAGS_LAYOUT flag in LoadFont(). The only structure members that are supported for fonts that haven't set HWFONTFLAGS_LAYOUT are CharSpacing and Style but the only style flag that can be set for fonts that haven't set HWFONTFLAGS_LAYOUT is HWFONTSTYLE_ANTIALIAS.

struct hwTextLayout looks like this:

struct hwTextLayout { ULONG Color; [in] ULONG Style; [in] int Align; [in] int WrapWidth; [in] int LineSpacing; [in] int CharSpacing; [in] int Indent; [in] int AdvanceX; [out] int AdvanceY; [out] int *Tabs; [in] int TabCount; [in] };

Here is a description of the individual structure members:

Color:

The desired font color as an RGB value.

Style:

A bit combination of style flags. The following style flags are currently defined:

HWFONTSTYLE_ANTIALIAS:

Use anti-aliasing.

HWFONTSTYLE_BOLD:

Bold text.

HWFONTSTYLE_ITALIC:

Italic text.

HWFONTSTYLE_UNDERLINED:

Underlined text.

Align:

The desired text alignment. This can be one of the following alignment types:

HWTEXTALIGN_LEFT:

Left alignment.

HWTEXTALIGN_RIGHT:

Right alignment.

HWTEXTALIGN_CENTER:

Centered alignment.

HWTEXTALIGN_JUSTIFIED:

Justified alignment.

WrapWidth:

The maximum number of pixels per line. If a word exceeds this number of pixels, it should be moved to the next line. If this is 0, then no wordwrapping should take place.

LineSpacing:

Adjustment pixels between lines. This can be a positive or negative value. A negative value moves lines closer together, whereas a positive value increases the spacing between lines. A value of 0 means no custom line adjustment.

CharSpacing:

Adjustment pixels between characters. This can be a positive or negative value. A negative value moves characters closer together, whereas a positive value increases the spacing between characters. A value of 0 means no custom character adjustment.

Indent:

The indentation in pixels for the very first line of text. If this is greater than 0, text on the very first line should be indented by this number of pixels.

AdvanceX:

This must be set to the number of pixels the cursor should be advanced horizontally after drawing the text.

AdvanceY:

This must be set to the number of pixels the cursor should be advanced vertically after drawing the text.

Tabs:

An integer array containing a number of tab stops. Whenever a tab character is encountered, your text layouter should advance to the next tab stop. The number of tab stops in the Tabs array is indicated by the TabCount member (see below). Note that this can also be NULL.

TabCount:

Number of tab stops in the Tab member (see above).

handle

the font handle allocated by LoadFont()

str

text to measure (this is not null-terminated!)

count

length of the text to measure in bytes

encoding

character encoding of the text (see above)

te

pointer to a struct hwTextExtent that receives the text's dimensions

tl

pointer to a struct hwTextLayout that contains layout information

tags

tag list containing further options or NULL

error

error code or 0 for success