Reference for the Mosaic class Views::Text

Views::Text
Alignment
AutoSize
Color
ColorBL
ColorBR
ColorTL
ColorTR
Ellipsis
Embedded
Font
OnUpdate
Opacity
RowDistance
ScrollOffset
SlideHandler
String
Visible
WrapText
WrapWidth
GetContentArea()
GetNoOfRows()
GetRowArea()
GetRowString()
Position2RowCol()
RowCol2Position()
RowCol2StringIndex()
StringIndex2RowCol()
Core::RectView
Bounds
Core::View
Layout
Owner
ArrangeView()
ChangeViewState()
CursorHitTest()
Draw()
GetExtent()
GetRoot()
HandleEvent()
MoveView()

SEE ALSO

Using the Text view to display ordinary, not formatted text blocks.

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 '\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.

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. 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.

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.

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. Changes of this property will be immediately reflected in the properties ColorTL, ColorTR, ColorBL and ColorBR. Thus this property is useful if no gradients are desired.

property color ColorBL = #FFFFFFFF;

The property 'ColorBL' stores the color at the bottom-left corner of the views's Bounds area.

property color ColorBR = #FFFFFFFF;

The property 'ColorBR' stores the color at the bottom-right corner of the view's Bounds area.

property color ColorTL = #FFFFFFFF;

The property 'ColorTL' stores the color at the top-left corner of the view's Bounds area.

property color ColorTR = #FFFFFFFF;

The property 'ColorTR' stores the color at the top-right corner of the view's Bounds area.

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 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, 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 an area where the view will show a text row. The number of the text row is 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 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, 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.

The returned string is already processed --> it contains only the visible signs. Any control signs, like the hyphen sign or the '%' escape sign as well as any superfluous terminal space signs are removed from the string. In other words, the returned string corresponds to the text displayed in the row.

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.

method point Position2RowCol
(
arg point aPoint
);

The method Position2RowCol() tries to determine the number of the text row and column 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, ScrollOffset, WrapText, etc.

The returned value contains in 'x' the column number and in 'y' the row number. The first row/column has the number 0, the second has the number 1, and so far. This method is useful, if e.g. a text fragment touched by the user should be determined.

method point RowCol2Position
(
arg point aRowCol
);

The method RowCol2Position() returns the baseline-position where the view will draw the glyph 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. 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, ScrollOffset, WrapText, etc.

This method is useful, if e.g. additional decoration should be drawn around the glyph like a blinking caret in a text editor, etc.

method int32 RowCol2StringIndex
(
arg point aRowCol
);

The method RowCol2StringIndex() tries to determine from a row/column position the corresponding index in the origin string String. The position is specified in the parameter aRowCol. This parameter contains in 'x' the number of the column and in 'y' the number of the row. The first row/column has the number 0, the second the number 1, and so far.

The returned index refers within String the sign which is shown on the specified row/column position. If the sign is introduced with a '%' escape sign, the returned index will refer to this escape sign. All signs which are not visible like the hyphen or the eliminated terminal blanks are ignored by the method.

The method is useful if e.g. a text fragment lying on the given row/column position should be modified. The typical application case could be a text editor.

property int32 RowDistance = 0;

This property 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 a row/column position which does correspond to a sign from the origin string String identified by the index aIndex. Within the String the first sign has the index 0, the second 1, and so far. The returned value defines the row/column position where the sign is displayed. This value contains in 'x' the number of the column and in 'y' the number of the row. The first row/column has the number 0, the second the number 1, and so far.

Please note, that control signs like the hyphen or the '%' escape sign are usually not visible and thus there is no way to determine their row/column position. In such case the position of the next following (visible) sign is returned.

The method is useful if e.g. a text fragment corresponding to a given string index should be determined. The typical application case could be a text editor.

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 determined by its property Bounds. Whether the automatic text wrap is performed or not is controlled by the property WrapText.