The Mosaic class Views::Text implements a graphical object specialized to display text. This so-called Text view can be used to compose the appearance of a GUI component, in particular to add any kinds of captions, labels, message text blocks, etc. to it. The following screenshot demonstrates few examples of how Text views appear in the canvas area of Composer (and accordingly on the screen in your target device):

The following sections are intended to provide you an introduction and useful tips of how to work with the Text view. For the complete reference please see the documentation of the Views::Text class.

To add a new Text view just at the design time of a GUI component do following:

As long as the Text view is selected you can inspect and modify its properties conveniently in the Inspector window as demonstrated with the property Bounds in the screenshot below:

Once added, you can freely move the Text view, or you simply grab one of its corners and resize it in this way. You can control the position and the size of the view also by directly modifying its property Bounds. If you want the Text view to appear behind other views you can reorder it explicitly.

The Text view renders the text by using the font information specified in its property Font. Usually, you initialize this property with the name of an existing font resource member. With the Inspector Assistant you can conveniently select the right resource when you edit the initialization expression for the property Font.

The text to display by the Text view is determined by its property String. This property expects an initialization expression resulting in a valid string operand. This is usually a string literal (e.g. "Caption") or the name of an existing string constant member. In particular, the usage of a constant is preferable wherever you plan to localize the text for different languages.

Please note, that there are few special characters, the Text view interprets as format instructions instead of displaying them. This affects the signs: ^ (circumflex), ~ (tilde) and % (percent). In order to display such sign, you have to prefix it within the string explicitly by an additional % (percent) character. For example:

If the specified text contains \n (new-line) characters, the text portions lying in-between are treated and displayed as individual text rows. In other words, if you intend to display a multiline text block, you separate the rows simply by \n (new-line) characters. The \n (new-line) character itself is not visible in the resulting text:

Please note, that to appear correctly, all signs used within the text should also be available in the specified font. In order to reduce the size of the resulting application, you have to determine for every font resource, which glyphs you intend to use at the runtime of your application. Not specified glyphs are then excluded. Trying to show them anyway will result in dummy signs, usually small boxes, displayed on the screen. For example, if the font resource doesn't include the typical German Umlaut ÄÖÜ nor the Eszett ß signs, the German text appears incomplete:

Per default the characters within the specified text are displayed from left-to-right (LTR) according to their original storage order. To display text with right-to-left (RTL) direction as it is usual for the Arabic and Hebrew languages you have to explicitly enable the bidirectional text processing. For this purpose set the property EnableBidiText of the affected Text view to the value true.

With the enabled bidirectional text processing the Text view performs the Unicode Bidirectional Algorithm according to the rules specified in Unicode Standard Annex #9. This includes reordering of text fragments containing RTL characters, shaping of Arabic glyphs and building of Arabic mandatory ligatures. If you leave the property EnableBidiText initialized with its default value false none of these steps are applied.

With the enabled bidirectional text processing it is sometimes useful to know more details resulting from the algorithm. For example, you can query the actual base direction of the paragraph. The Views::Text class provides for such application cases various useful methods. You can call those methods whenever your GUI component implementation requires the corresponding information. The following table gives you a short overview of them:

Method	Description
IsBidiText()	Returns true if the specified text contains any right-to-left contents or any other Bidi algorithm relevant control codes requiring the Bidi processing of this text.
IsBaseDirectionRTL()	Returns true if the specified text starts with an RTL (right-to-left) character. This implies the base direction of the entire text paragraph.
IsCharDirectionRTL()	Queries the writing direction of the given character within the specified text.

As described in the section Specify the text you can separate the text rows by \n (new-line) characters and so layout multiline text blocks easily. More sophisticated is to instruct the Text view to wrap the rows automatically according to the available space (usually the width of the Text view). To enable this feature, you simply initialize the property WrapText with the value true. The following figure demonstrates how the same text is displayed depending on the value of the WrapText property and the size of the Text view area (indicated by the thin blue borders):

The automatic text wrap applies primarily to space characters (blanks). The words, in turn, are not split unless the word contains special format characters. The following table provides an overview of the available format characters and the resulting effects. Using them, you can control the text layout more accurately:

Character	Effect
~	The signs ~ (tilde) are treated as soft-hyphens. They determine potential candidates to wrap a word. These signs are not displayed until the text wrap took place at their position. In such case the affected text row is terminated with an additional hyphen - sign indicating that the word has been broken there.
^	The signs ^ (circumflex) are treated as silent soft-hyphens. They determine potential candidates to wrap a word. These signs are never displayed nor replaced by any hyphen even if the text wrap took place at their position. They are simply silent.
\x00AD	The standardized character code for a soft-hyphen. It has the same effect as described above with the sign ~ (tilde) and exists for compatibility purpose with UNICODE character set.
\x00A0	The standardized character code for a non-breaking space (NBSP). The character is displayed as a blank without being taken in account as potential wrap position.

The following figure demonstrates the effect of the above described special characters to automatically wrap the words. As you see, enriching the text with ~ and ^ characters allows the Text view to automatically determine the ideal positions for the syllabication depending on the available space (indicated by the thin blue borders):

Per default, the text wrap is calculated depending on the actual width of the Text view. Changing the size of the Text view will thus cause the text layout to update accordingly. With the property WrapWidth you can override this behavior and specify explicitly other width to wrap the text irrespective of the actual size of the Text view. This is in particular useful, if you intend to align or scroll horizontally the resulting text block. By assigning the value 0 (zero) to the property WrapWidth the Text view restores again its default wrap behavior. For example:

Within a multiline text block all rows are arranged per default at a distance determined by the size of the font used to display the text. With the property RowDistance you can override this behavior and specify explicitly other line spacing. Changing this property causes thus the text rows to appear more closely or loosely. By assigning the value 0 (zero) to this property the Text view restores again its default behavior. For example:

Per default, the Text view displays the text centered within the area determined by the property Bounds. If the text is larger than the available area, the parts lying outside it are simply clipped and are not visible. If desired, with the property Alignment you can determine other behavior.

The property Alignment is declared as a set data type, which means that it is possible to activate and deactivate the various alignment options individually. Primarily, with these options you specify how to align every displayed text row horizontally and how to align the entire text block vertically. The following figure demonstrates few examples of how the initialization of the property Alignment affects the text layout (the thin blue borders indicate the view areas):

If the Text view is intended to show bidirectional text with horizontal alignment depending on the actually displayed content, you should activate the option AlignHorzAuto instead of AlignHorzLeft or AlignHorzRight. In such case the correct alignment is derived from the base direction of the affected text (which depends on the first strong LTR or RTL character found in the original text). Consequently right-to-left (RTL) scripts like Arabic and Hebrew will appear right aligned while left-to-right (LTR) text is automatically left aligned.

Regardless of the specified horizontal alignment you can additionally activate the option AlignHorzJustified. With this option you instruct the view to justify the space signs (blanks) lying between words of an automatically wrapped text rows, so the rows appear filling the entire available width of the Text view. The following figure demonstrates the effect of the additionally enabled AlignHorzJustified option (the thin blue borders indicate the view areas):

You should remind, that the text alignment does depend on the metric information provided by the original designer of the selected TrueType font. Especially italic fonts designed to appear slanted may cause problems with the last glyph in a right aligned row. Such glyph may appear clipped. The following figure demonstrates the problem (the thin blue borders indicate the areas of the Text views):

To help you to deal with such problems, the Text view implements the property Padding where you can specify a margin the Text view should additionally add at its left and right edges. With this margin you win additional space where the unexpectedly clipped glyphs can appear as expected. In the following figure you see the Text view with the right aligned text and additionally specified padding:

The property Padding expects its value being expressed in pixel. However, which value you specify, is particular to the used font. Usually you will need to try several values until you get the expected results. Also please note, specifying the padding does shrink the available area where text can be displayed within the Text view. Therefore it is reasonable to enlarge the Text view to compensate the additional padding. For example, if you set the property Padding to the value 12 then enlarge the Text view by 24 pixel horizontally. With this the Text view will appear as if it were configured without padding.

With the property Orientation you can determine the rotation of the displayed text in steps of 90 degrees (0, 90, 180 and 270 degrees). The following figure demonstrates how the initialization of the property Orientation affects the text layout (the thin blue borders indicate the view areas):

Modifying the Orientation property has also an effect on how the text is aligned within the view's area. For example, if you have configured the Text view to align the text at its top-left corner and then you rotate the text 90 degrees counterclockwise, the text will in fact appear aligned to the bottom-left corner of the view. The following figure demonstrates it (the thin blue borders indicate the view areas):

In such case the simplest is you consider the specified alignment constrainst as being valid in context of original text instead of the edges of the Text view. Accordingly, regardless of how you initialize the property Orientation, a left aligned text will stick at its original left edge.

Besides the possibility to align the text within a Text view you can also scroll it pixel-wise. For this purpose use the property ScrollOffset. You can determine the vertical and the horizontal displacement individually. With positive values the text is scrolled right/down. With negative values left/up. For example (the thin blue borders indicate the view areas):

If you try to display text, which is larger than the available Text view area, then text parts lying outside this area are simply clipped at its edges resulting in text signs or even entire rows being half visible. With the property Ellipsis you can instruct the Text view to replace, if necessary, the leading and/or final parts of the text by an ellipsis sign ..., so that the displayed text fits automatically in the Text view area Bounds without being clipped ugly. To enable this mode, initialize the property Ellipsis with the value true.

The effect of this mode depends directly on the specified text alignment. For example, if the text is aligned at the top-left corner of the text view, the algorithm will remove all invisible or partially clipped rows at the bottom of the text and all signs at the right end of the last visible row until there is enough space to display one ellipsis sign. In turn, if the text is centered vertically, the algorithm affects the text rows at the top and at the bottom edges. The following figure demonstrates the effect (the thin blue borders indicate the view areas):

With the property AutoSize you can instruct the Text view to automatically adjust its size and eventually its position when new text or font is assigned to it. In other words, the Text view will assume the size of the displayed content. Similarly, changing the wrap width while AutoSize is true will adjust the size and eventually the position of the view.

You can combine AutoSize with the alignment options. For example, if you have configured the Text view to align the text at its bottom-right corner, changing the font will move the left and top edges of the view by maintaining the bottom-right corner fixed. This is demonstrated in the following screenshot (the thin blue borders indicate the actual view area):

Since with AutoSize mode enabled the Text view assumes automatically the size of the entire text, truncate the text with ellipsis is not useful in such case.

To specify the color of the Text view you change its property Color. Alternatively you can configure the text to be drawn with a color gradient. For this purpose you specify the colors for the four corners of the view (top-left, top-right, bottom-right and bottom-left) individually by using the corresponding properties ColorTL, ColorTR, ColorBR and ColorBL. The gradient colors are interpolated linearly between the specified values. Using color values with alpha < 255 causes the text to appear semi- or even transparent. For example:

Using the property Opacity you can modulate the opacity of the displayed text, so that it appears semi-transparent even if the originally specified colors were opaque. The valid values for the property Opacity are 0 .. 255, whereby the smaller the value the more transparent the resulting text. For example:

Sometimes it is necessary to know the position of the text fragments displayed within the Text view in order to e.g. automatically align other views with them. For example, you can arrange an image view to appear always side by side with a text row, so that when the text changes, the image view is moved accordingly. The Views::Text class provides for such application cases various useful methods. The following table gives you a short overview of them:

Method	Description
GetContentArea()	Returns the position and the size of the area occupied by the entire text block.
GetNoOfRows()	Returns the total number of text rows within a multiline text block.
GetRowArea()	Returns the position and the size of the area occupied by a text row.
RowCol2Position()	Calculates from a given row/column number the origin pixel position of the corresponding sign.
Position2RowCol()	Calculates from a given pixel position the row/column number of the corresponding sign.
RowCol2StringIndex()	Calculates from a given row/column number the corresponding character index within the originally specified text.
StringIndex2RowCol()	Calculates from a given character index the corresponding row/column number.
GetRowString()	Returns a text portion corresponding to a text row.
IsCharDirectionRTL()	Queries the writing direction of the given character within the specified text. If the character has RTL (right-to-left) direction (e.g. Arabic glyph), the method returns true. See also Enable RTL (right-to-left) and bidirectional text processing.

You can call those methods whenever your GUI component implementation requires the corresponding information. More sophisticated, however, is to join the update mechanism provided natively by the Text view. Precisely, when you assign a slot method to the Text view property OnUpdate, the slot method will receive postsignals every time the text content, its layout or position changes. Accordingly, within the slot method you can react on this notification and e.g. arrange other views at the new text position. The following steps describe how to do this:

Assuming, your GUI component contains a Text view named Message and a border view named Border. Furthermore let's assume your want the border to appear arranged automatically around the text with an additional small margin. In such application case implement the slot method with following Chora code:

With such implementation, every time the text in the Text view changes, the border is updated automatically:

For your convenience the Views::Text class implements an interface for easy coupling Text views with Slide Touch Handlers. In this manner, the user can scroll the content displayed within the Text view by simply touching the associated Slide Touch Handler. Assuming that you have already a Text view in your GUI component, then:

The visibility of the Text view is determined primarily by the property Visible, the specified text and the associated font. Also the opacity and the color values, if they are not opaque, may affect the resulting appearance of the Text view.