PageOutline(1-5, Contents)

Table of Contents Text Elements Text encoding HTML characters Setting an element's text Retrieving an element's text String generation

Rocket uses text elements (elements derived from Rocket::Core::ElementText) to store and render loose text. Text elements are generated automatically for text in RML documents, and can be created dynamically by using the '#text' element instancer through the Rocket factory, or through the CreateTextNode() function on a document.

The string type used through the majority of Rocket's interfaces, EMP::Core::String, stores 8-bit wide characters. In order to store wider characters efficiently, text elements store their contents as a Rocket::Core::String type. The Rocket string stores 16-bit wide characters in UCS-2 format; while not sufficient to store every possible UTF-8 character, it can store every useful one, so is a good compromise between size and usefulness.

When a Rocket string is constructed from an EMP string, it interprets the EMP string as being UTF-8 encoded and will convert it to UCS-2.

Rocket text nodes support a subset of the full HTML-encoding for special characters to allow XML characters to be present in loose text. The characters supported are:

 * ''&lt;'' The less-than symbol, '<'.
 * ''&gt;'' The greater-than symbol, '>'.
 * ''&amp;'' The ampersand symbol, '&'.
 * ''&nbsp;'' A non-breaking space.

You should use these symbols instead of their literal equivalents when putting them into RML. For example, the following RML fragment will most likely generate a parse error:

The following fragment puts the characters in correctly:

The SetText() function on a Rocket::Core::ElementText will change the text on the text element to a new string.

If you pass in a constant string or an EMP::Core::String, it will be converted to a Rocket string as described above (interpreted as UTF-8 encoding). This means it will interpret standard ASCII characters OK.

Note that this sets the raw text on the element; the actual rendered text may differ due to whitespace processing.

The GetText() function will return the element's raw text.

This will return the raw text as a UCS-2 encoded Rocket string. To convert the string to a UTF-8 encoded string, call ToUTF8() on the string.

Text elements are capable of generating formatted sub-sections of their content. This is generally only required by custom elements placing text internally; see the section on [wiki:documentation/C++Manual/HiddenElements#Formattinghiddentextelements] for more information.