Adds a block of HTML styled text to the current page.
This method works in a manner similar to the AddText method, but it allows you to add
multi-styled text by inserting simple HTML tags. A listing of
supported tags is given in the HTML Styled Text section
of the documentation.
You can chain together multiple HTML blocks so that text flows
from one to the next. To do this, you need to first add a block of
HTML. Then add multiple new HTML blocks each time passing in the ID
obtained from the previous call.
When no more text is available, the AddHtml method will return
zero. Alternatively, you can query the Truncated property of
the Text object before adding a new item to the chain.
This method returns the Object ID of the newly added Text
object. If no text could be added, then zero is returned. This will
happen if a zero length string was supplied or if the rectangle was
too small for even one character to be displayed.
Typically, you will get a return value of zero if your text was
too large to fit in your Rect or if the Pos was at the end of the Rect.
Text styles for the entire HTML content are determined at the
point at which the first item in a text chain is created. This
means that varying document styles will not affect the way in which
subsequent items in the chain are displayed.
For an example of chaining, see the Text Flow Example.
Note that there is no requirement that blocks be organized in a
linear chain. That means that you can use the same ID as the
ChainID parameter to multiple calls to this method. If you wish,
you can create trees of HTML blocks, flowing text from a chain head
through multiple display areas on your document.