Reference for the Mosaic class Views::Text
The class Views::Text provides a kind of view specialized to print the text. The text is stored in the property String. It can consist of several rows separated by the new-line sign '\\n'. Optionally an automatic text wrap ca be performed if the property WrapText is 'true'. The automatic text wrap takes place primarily between words. More sophisticated text wrap can be controlled by following special signs used within the text:
In order to be able to output the special characters '^' and '~' and as regular signs, the character '%' can be applied in front of the affected sign to convert it to a regular sign. To show the '%' sign itself, use '%%' sequence.
Beside the automatic text wrap, an explicit linefeed is possible when the '\n' sign has been found in the string.
The text output is performed with the font specified in the property Font. The position and the size of the area where the text is drawn is determined by the property Bounds. If the size of this area differs from the size of the text, the text can be aligned. This is controlled by the property Alignment. With the property Orientation the displayed content can be rotated. The color to print the text is defined by the property Color. Alternatively, the text can be drawn with a color gradient specified by the properties ColorTL, ColorTR, ColorBL and ColorBR. For each view's corner different color can be set.
The property SlideHandler permits the text view to be connected together with an interactive Core::SlideTouchHandler. In this manner the user can scroll the displayed text by simply touching the slide handler on the screen. Alternatively, the scroll position can be controlled by the value of the property ScrollOffset.
The visibility of the text is controlled by the properties Visible and Embedded. In particular the property Embedded can determine whether the corresponding view is limited (== embedded) to the boundary of a sibling Core::Outline view or not. The embedding of views within a Core::Outline allows a kind of sub-groups within the GUI component itself. Very useful for any kind of scrollable lists, menus, etc.
With the property EnableBidiText the view can be configured to treat the original string String as containing bi-directional text. In such case, the string is processed by the Unicode Bidirectional Algorithm. If the text contains Arabic characters, the algorithm performs the shaping and determines the obligatory Arabic ligatures. With the method IsBidiText(), IsBaseDirectionRTL() and IsCharDirectionRTL() the resulting state of the processed text can be determined.
The text provides an additional set of methods useful to access the text rows and glyphs, e.g. GetNoOfRows(), GetRowArea(), RowCol2Position(), RowCol2StringIndex(), StringIndex2RowCol(), etc. These methods can be invoked from a slot method assigned to the property OnUpdate. In this manner text position can be calculated or additional decorations can be drawn.
property Views::TextAlignment Alignment = Views::TextAlignment[AlignHorzCenter, AlignVertCenter];
The property 'Alignment' determines how the view should display the text rows if their size differ from the size of the view. In this manner the rows can be aligned horizontally. The entire text block can be aligned vertically.
Please note, the orientation of the area in context of which the text is aligned is affected by the property Orientation. For example, if the view is configured to rotate the text 90 degrees counter-clockwise and to align it to the left edge, all text rows will be arranged consequently at the bottom edge of the view.
property bool AutoSize = false;
The property 'AutoSize' determines whether Bounds of the view should be adjusted automatically in response to text or font changes. If AutoSize is 'true', the view will adapt its bounds area correspondingly to the area occupied by the drawn text.
property color Color = #FFFFFFFF;
The property 'Color' controls the color of the entire view. Thus this property is useful if no gradients are desired. The resulting colors can additionally be modulated by the values specified in the properties ColorTL, ColorTR, ColorBL and ColorBR.
property color ColorBL = #FFFFFFFF;
The property 'ColorBL' stores the color at the bottom-left corner of the views's Bounds area. This color value can additionally be modulated by the common color value stored in the property Color.
property color ColorBR = #FFFFFFFF;
The property 'ColorBR' stores the color at the bottom-right corner of the view's Bounds area. This color value can additionally be modulated by the common color value stored in the property Color.
property color ColorTL = #FFFFFFFF;
The property 'ColorTL' stores the color at the top-left corner of the view's Bounds area. This color value can additionally be modulated by the common color value stored in the property Color.
property color ColorTR = #FFFFFFFF;
The property 'ColorTR' stores the color at the top-right corner of the view's Bounds area. This color value can additionally be modulated by the common color value stored in the property Color.
property bool Ellipsis = false;
The property 'Ellipsis' determines whether leading and/or closing characters of the string String should be replaced with ellipsis '...', if necessary, so that the result fits in the specified Bounds area.
property bool Embedded = false;
The property 'Embedded' controls how the view should appear and behave within its superior Owner. If this property == 'true', the affected view will be embedded (limited) to the boundary of a preceding Core::Outline sibling view. This is as if the view had been embedded within this outline. Beside the appearance limitation of the outline boundary, the outline also provides more sophisticated arrangement mechanisms and the content scrolling. It is therefore useful to create scrollable menus or lists.
If this property is 'false', the view is considered as a regular view of its Owner - it doesn't belong to any outline.
property bool EnableBidiText = false;
The property 'EnableBidiText' controls how the Text view should handle strings containing bidirectional or right-to-left (e.g. Arabic) contents. If this property is 'true', the Text view applies the 'Unicode Bidirectional Algoritm' on the specified string. This includes the shaping of Arabic glyphs and building of Arabic mandatory ligatures. If this property is 'false', none of the here described steps is applied - the Text view displays the string as it is.
property Resources::Font Font = null;
The property 'Font' refers to the font object used to print the text. The text is determined by the property String.
method rect GetContentArea();
The method GetContentArea() returns the position and the size of an area where the view will show the text. This area is expressed in coordinates relative to the top-left corner of the view's Owner. The method takes in account all properties which do affect the position and the alignment of the text, e.g. Alignment, Orientation, ScrollOffset, WrapText, etc.
method int32 GetNoOfRows();
The method GetNoOfRows() returns the total number of text rows currently displayed in the text view. It is useful when the application needs to iterate through the text rows and to evaluate their position and content. To get the position and the content of a row the methods GetRowArea() and GetRowString() are intended.
method rect GetRowArea
(
arg int32 aRow
);
The method GetRowArea() returns the position and the size of the area where the view displays the text row with number specified in the parameter aRow. The first row has the number 0, the second 1, and so far. If the row is not available, an empty area <0,0,0,0> is returned.
The returned area is expressed in coordinates relative to the top-left corner of the view's Owner. The method takes in account all properties which do affect the position and the alignment of the text, e.g. Alignment, Orientation, ScrollOffset, WrapText, etc.
method string GetRowString
(
arg int32 aRow
);
The method GetRowString() returns the content of the row with the number specified in the parameter aRow. The first row has the number 0, the second 1, and so far. If the row is not available, an empty string is returned. Please note, if the view is configured with EnableBidiText to process and display bi-directional text and the affected text row is reversed, the method returns the Bidi processed string as it appears on the screen.
All invisible signs, like the soft-hyphen sign, the '%' escape sign, the new-line sign, Bidi control codes as well as the superfluous space signs found eventually after a line wrap are removed from the returned string. In other words, the returned string corresponds to the text displayed in the row.
method int32 GetSmallestRow();
The method GetSmallestRow() returns the number of the row with the smallest width. The rows are counted starting with 0 for the first row. This method is useful to find the smallest row in a Text view displaying multi-line text. If there are several equal small rows, the method returns the number of the first found row.
method int32 GetWidestRow();
The method GetWidestRow() returns the number of the row with the largest width. The rows are counted starting with 0 for the first row. This method is useful to find the widest row in a Text view displaying multi-line text. If there are several equal large rows, the method returns the number of the first found row.
method bool IsBaseDirectionRTL();
The method IsBaseDirectionRTL() returns 'true' if the text specified in String starts with an RTL (right-to-left) character. This implies the base direction of the entire text paragraph. If the text starts with an LTR (left-to-right) sign or the property EnableBidiText is 'false', this method returns 'false'.
method bool IsBidiText();
The method IsBidiText() returns 'true' if the text specified in the property String contains any right-to-left contents or any other Bidi algorithm specific control codes requiring the Bidi processing of this text. Please note, if the property EnableBidiText is false, the text is not processed by the Bidi algorithm and this method returns 'false'.
method bool IsCharDirectionRTL
(
arg int32 aStringIndex
);
The method IsCharDirectionRTL() returns 'true' if the character stored at the position aStringIndex within String has the RTL (right-to-left) writing direction. If aStringIndex addresses a non existing character, the value resulting from the paragraph direction (IsBaseDirectionRTL()) is returned. If the addressed character has the LTR (left-to-right) direction or the property EnableBidiText is 'false', this method returns 'false'.
property slot OnUpdate = null;
The property 'OnUpdate' can refer to a slot method, which should be invoked by the view after the displayed String or the position of the view have been changed. This method is intended to update decorations, like the position of a blinking caret in a text editor, etc. For this purpose methods GetContentArea(), GetRowArea(), RowCol2Position(), Position2RowCol(), GetNoOfRows(), GetRowString(), RowCol2StringIndex() can be used. It's up to you to provide the slot method and to fill it with the desired behavior.
property int32 Opacity = 255;
The property 'Opacity' controls the translucence of the view. This property can take values in range of 0 .. 255. If the value is 255, the view will appear with its full opacity. The value equal to zero results in a fully transparent view. Other values in the range 1 .. 254 show a semitransparent views.
property Views::Orientation Orientation = Views::Orientation.Normal;
The property 'Orientation' determines whether the text should be displayed with normal or rotated orientation.
property int32 Padding = 0;
The property 'Padding' determines additional gap in pixel to take in account at the left and right edges of the displayed text. This property can assume values greater than or equal 0 (zero).
Usually this property is used when you intend to display text with italic (cursive) font and the glyphs appear clipped at the left or right view edges. Increasing the value of this property adds additional leading and final gap preventing in this manner the unexpected clipping of glyphs at text begin or end.
method point Position2RowCol
(
arg point aPoint
);
The method Position2RowCol() tries to determine the row and column numbers for the specified pixel position aPoint. The position aPoint is expressed in coordinates relative to the top-left corner of the view's Owner. The method takes in account all properties which do affect the position and the alignment of the text, e.g. Alignment, Orientation, ScrollOffset, WrapText, etc. The returned value contains in 'x' the column number and in 'y' the row number of the affected sign as it is displayed on the screen. The first row/column has the number 0, the second has the number 1, and so far.
If the specified position points above the first or below the last row, the corresponding row is selected. If the position points before the first sign of the affected row, the first column 0 is selected. If the position points behind the last sign in the row, the method returns the column number of the last sign in the row +1.
This method is useful, e.g. to determine which sign lies at a position touched by the user.
method point RowCol2Position
(
arg point aRowCol
);
The method RowCol2Position() returns the baseline-position where the view will draw the sign for the row and column specified in the parameter aRowCol. This parameter contains in 'x' the number of the column and in 'y' the number of the row as it is displayed on the screen. The first row/column has the number 0, the second the number 1, and so far. The returned position is expressed in coordinates relative to the top-left corner of the view's Owner. The method takes in account all properties which do affect the position and the alignment of the text, e.g. Alignment, Orientation, ScrollOffset, WrapText, etc.
If the specified row is negative, the method returns the position of the first sign in the first text row. If the specified row is not existing, the method returns the position behind the last sign in the last text row. If the column is negative, the method returns the position of the first sign in the corresponding row. If the row does not contain the specified column, the position behind the last sign in the row is returned.
This method is useful, if e.g. additional decoration should be drawn around the signs like a blinking caret in a text editor, etc.
method int32 RowCol2StringIndex
(
arg point aRowCol
);
The method RowCol2StringIndex() tries to determine from the given row/column position the index of the corresponding character in the original string String. The position is specified in the parameter aRowCol. This parameter contains in its 'x' component the column number and in the 'y' component the row number as it is displayed on the screen. The columns and rows are counted starting with 0. The returned index refers within String the character which is displayed at the specified row/column position.
Please note, the passed row/column position identifies visible signs only in the order as they appear on the screen. Any zero-width signs (e.g. eliminated soft-hyphen, new-line, Bidi control marks, the escape sign '%', etc.) are ignored. If the specified row is negative, the method returns the index corresponding to the first sign in the first row. If the specified row does not exist, the method returns the index corresponding to the character following the last sign in the last row. If the specified column is negative, the method returns the index corresponding to the first sign within the affected row. If the specified column does not exist, the method returns the index of the character following the last sign within the row. Furthermore, if the Text view is configured with the property Ellipsis set 'true', the method fails and returns the value 0 regardless of the specified aRowCol parameter.
This method is useful if e.g. a text fragment found at the given row/column position should be evaluated or modified.
property int32 RowDistance = 0;
The property 'RowDistance' determines the distance between two text rows regardless of the metrics information provided in the font resource specified in the property Font.
The original metrics information is used only when the property 'RowDistance' is equal 0. Assigning a value != 0 forces the text view to ignore the original metrics information and to arrange text rows with the specified distance.
property point ScrollOffset = <0,0>;
The property 'ScrollOffset' stores an additional displacement in pixel to move the text within the view's area. It is useful to create e.g. marquee text.
property Core::SlideTouchHandler SlideHandler = null;
The property 'SlideHandler' provides an interface, where a slide handler can be attached. In this manner the handler can control the view and the user can scroll the text by simply touching the slide handler on the screen.
property string String = "";
The property 'String' stores the text to print in this view. The corresponding font is determined by the property Font. The text can consist of several rows separated by the new-line sign '\n'. Optionally an automatic text wrap can be performed if the property WrapText is 'true'. The automatic text wrap takes place primarily between words. More sophisticated text wrap can be controlled by following special signs used within the text:
In order to be able to output the special characters '^', '~' and '\x00AD' as regular signs, the character '%' can be applied in front of the affected sign to convert it to a regular sign. To show the '%' sign itself, use '%%' sequence.
method point StringIndex2RowCol
(
arg int32 aIndex
);
The method StringIndex2RowCol() tries to determine the row and column display position of a sign corresponding to a character with the given number aIndex stored in the original string String. Within the string the first character has the index 0, the second 1, and so far. The returned value defines the row/column position where the affected sign is displayed after the string is processed and wrapped in several text rows. This value contains in its 'x' component the column number and in the 'y' component the row number. The columns and rows are counted starting with 0.
Please note, that the returned row/column position identifies visible signs only. If aIndex addresses a zero-width sign (e.g. eliminated soft-hyphen, new-line, Bidi control marks, the escape sign '%', etc.), the method returns in 'x' the column position identifying the next visible sign existing within the same text row. If starting at the estimated column position there is no other visible sign until the end of the text row, the method returns in 'x' the column number of the last visible sign + 1 (means: the returned position addresses the column behind the last visible sign). Furthermore, if the Text view is configured with the property Ellipsis set 'true', the method fails and returns the value <0,0> regardless of the specified aIndex parameter.
The method is useful to determine the displayed text fragment corresponding to a given string index. Knowing the row number you can use the method GetRowString() to obtain the corresponding row text and with the known column number you can evaluate the corresponding character in this row. Furthermore, by using the method RowCol2Position() you can obtain the pixel position where the sign at the estimated row/column is displayed.
property bool Visible = true;
The property 'Visible' determines the visibility state of the view. Invisible views will not appear on the screen. Whether a view is really visible depends on the visibility of its Owner and the position of the view within the owners boundary area.
property bool WrapText = false;
The property 'WrapText' determines whether long text rows should be wrapped automatically. If this property is 'true', the view will wrap the text rows which are longer than the value resulting from the property WrapWidth.
property int32 WrapWidth = 0;
The property 'WrapWidth' determines the maximum width in pixel a single text row can assume after the automatic text wrap. If this property is zero, the maximum width corresponds to the current width of the view's area (or its current height if Orientation configures the text to be rotated 90 or 270 degrees) determined by its property Bounds minus the eventually specified Padding. Whether the automatic text wrap is performed or not is controlled by the property WrapText.
