Reference for the Mosaic class Views::AttrText

Views::AttrText
Alignment
AttrSet
AutoSize
Embedded
EnableBidiText
OnUpdate
Opacity
OpacityBL
OpacityBR
OpacityTL
OpacityTR
Padding
ScrollOffset
SlideHandler
String
Visible
WrapWidth
FindLinkAtPosition()
FindLinkByName()
GetContentArea()
GetLinkBaseline()
GetLinkName()
GetLinkRect()
GetLinkUnion()
GetNoOfLinkRegions()
GetNoOfLinks()
Core::RectView
Bounds
Core::View
Layout
Owner
StackingPriority
AdjustDrawingArea()
ArrangeView()
ChangeViewState()
CursorHitTest()
Draw()
GetClipping()
GetExtent()
GetRoot()
HandleEvent()
MoveView()

SEE ALSO

Using the Attributed Text view to display complex formatted text blocks.

The class Views::AttrText provides a kind of view specialized to print text enriched with attributes to control the text output. Similarly to HTML these attributes determine the alignment and the colors and fonts to print the text. Additionally the text can be combined with bitmaps and hyper-links can be defined. Thus the attributed text is very suitable for displaying help pages and other formatted information. The attributed text uses a special optimized syntax to code the attributes. All attributes are enclosed in curly braces. They begin with an operation-code consisting of 3 or 4 signs followed by none or more parameters. No blanks nor white-spaces are allowed in the attribute. For example:

"This is a {clr2}highlighted{clr0} word."

The attribute {clr2} forces the view to draw the word 'highlighted' with the color number 2. The value of the desired color is stored in so-called attribute set together with necessary fonts and bitmaps. The following list describes the available attributes. Please note the square brackets in the syntax below. They don't belong to the attributes and are used to enclose parts of the attributes which can be omitted.

The text can consist of several rows separated by the new-line sign '\\n'. Additionally an automatic text wrap will be performed. 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.

The text is determined by the property String. The property AttrSet refers to an object providing all the colors, fonts and bitmaps used in the text. When using the attributed text object you will also need to provide the Graphics::AttrSet object.

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 properties Opacity, OpacityTL, OpacityTR, OpacityBL and OpacityBR can be used to modulate the transparency of the shown text. For each view's corner different opacity can be set, so the text can be shown with fancy opacity gradients.

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.

With the property EnableBidiText the view can be configured to treat the original string String as containing bi-directional text. In such case, all enclosed paragraph contents are processed by the Unicode Bidirectional Algorithm. If the paragraphs contain Arabic characters, the algorithm performs the shaping and determines the obligatory Arabic ligatures.

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 attributed text provides an additional set of methods useful to access the hyper-links stored within the text, e.g. GetLinkName(), GetLinkRect(), etc. These methods can be invoked from a slot method assigned to the property OnUpdate. In this manner additional decorations can be drawn around the links, etc.

property Views::TextAlignment Alignment = Views::TextAlignment[AlignHorzCenter, AlignVertCenter];

The property 'Alignment' determines how the view should display the attributed text block if its size differ from the size of the view. In this manner the text block can be aligned horizontally and vertically. Please note, this property affects the alignment of the entire text block. The alignment of text rows is controlled exclusively by the attributes within the text.

Since this property controls the alignment of the entire block, the constraints 'AlignHorzJustified' as well as 'AlignVertCenterBaseline' have no effect. To enable the justified text alignment, the appropriate attribute (e.g. {parlj}) has to be used within the text. Concerning the baseline alignment, the attributed text view already aligns the contents of a text row on common base line. The possibility to center the resulting entire text block on the baseline, however, is not supported by the attributed text view.

property Graphics::AttrSet AttrSet = null;

The property 'AttrSet' refers to an object containing colors, fonts and bitmaps necessary for rendering and displaying of this attributed text.

property bool AutoSize = false;

The property 'AutoSize' determines whether Bounds of the view should be adjusted automatically in response to text or attribute changes. If AutoSize is 'true', the view will adapt its bounds area correspondingly to the area occupied by the drawn attributed text.

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 Attributed Text view should handle strings containing bidirectional or right-to-left (e.g. Arabic) contents. If this property is 'true', the view applies the 'Unicode Bidirectional Algorithm' individually on every paragraph found in 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 Attributed Text view displays the string as it is.

method int32 FindLinkAtPosition
(
arg point aPosition
);

The method FindLinkAtPosition() searches in the attributed string for the link with content enclosing the specified position aPosition. If the link could be found the method returns its number. If the link could not be found -1 is returned.

method int32 FindLinkByName
(
arg string aLinkName,
arg int32 aStartWith
);

The method FindLinkByName() searches in the attributed string for the first link with the specified name aLinkName. The search operation starts with the link number aStartWith. If no link with the given name could be found, the method returns -1.

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

Please note, the width of the returned area corresponds always to the width the text has been wrapped for. Usually this width results from the actual value of the property Bounds unless another width has been specified in the property WrapWidth.

method int32 GetLinkBaseline
(
arg int32 aLinkNo,
arg int32 aRegionNo
);

The method GetLinkBaseline() returns the vertical offset to the base line valid for the given region aRegionNo of the link aLinkNo. The offset is expressed in pixel relative to the top edge of the view's Owner. If the desired region or link are not available, the method returns zero. The number of available links and link regions can be queried by the methods GetNoOfLinks() and GetNoOfLinkRegions().

Links provide a useful feature to refer to text fragments and query their position and size at the runtime. Links are also useful to enrich attributed strings with interactive areas similar the them known from HTML. With this method the position of these areas can be queried and used e.g. to underline the link, etc. You can invoke this method e.g. from your OnUpdate slot method.

method string GetLinkName
(
arg int32 aLinkNo
);

The method GetLinkName() returns the name of the given link aLinkNo. If the desired link is not available, the method returns an empty string. The number of available links can be queried by the method GetNoOfLinks().

Links provide a useful feature to refer to text fragments and query their position and size at the runtime. Links are also useful to enrich attributed strings with interactive areas similar the them known from HTML. The name delivered by this method can be used to identify the link and if it has been selected by the user to decide which the operation should be performed.

method rect GetLinkRect
(
arg int32 aLinkNo,
arg int32 aRegionNo
);

The method GetLinkRect() returns the area of the region aRegionNo belonging to the link aLinkNo. The area is expressed in pixel relative to the top-left origin of the view's Owner. If the desired region or link are not available, the method returns an empty rectangle. The number of available links and link regions can be queried by the methods GetNoOfLinks() and GetNoOfLinkRegions().

Links provide a useful feature to refer to text fragments and query their position and size at the runtime. Links are also useful to enrich attributed strings with interactive areas similar the them known from HTML. With this method the position and the size of these areas can be queried and used e.g. to place a decoration margin around the link, etc. Unlike the method GetLinkUnion() this method returns the area occupied by a single region of the link if it has wrapped in several text rows. You can invoke this method e.g. from your OnUpdate slot method.

method rect GetLinkUnion
(
arg int32 aLinkNo
);

The method GetLinkUnion() returns the rectangular area containing the given link aLinkNo. The area is expressed in pixel relative to the top-left origin of the view's Owner. If the desired link is not available, the method returns an empty rectangle. The number of available links can be queried by the method GetNoOfLinks().

Links provide a useful feature to refer to text fragments and query their position and size at the runtime. Links are also useful to enrich attributed strings with interactive areas similar the them known from HTML. With this method the position and the size of these areas can be queried and used e.g. to place a decoration margin around the link, etc. You can invoke this method e.g. from your OnUpdate slot method.

method int32 GetNoOfLinkRegions
(
arg int32 aLinkNo
);

The method GetNoOfLinkRegions() returns the number of rectangular areas belonging to the given link aLinkNo. If the desired link is not available, the method returns zero. The number of available links can be queried by the method GetNoOfLinks(). Links provide a useful feature to refer to text fragments and query their position and size at the runtime. Links are also useful to enrich attributed strings with interactive areas similar the them known from HTML.

property slot OnUpdate = null;

The property 'OnUpdate' can refer to a slot method, which should be invoked by the view after the text or its position have been changed. This method is intended to update decorations, etc. around the hyper links of the attributed text. For this purpose methods GetLinkUnion(), GetLinkRect(), GetLinkBaseline() 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 opacity of the entire view. Thus this property is useful if no gradients are desired. 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 view. The resulting opacity can additionally be modulated by the values specified in the properties OpacityTL, OpacityTR, OpacityBL and OpacityBR.

property int32 OpacityBL = 255;

The property 'OpacityBL' controls the translucence of the view at its bottom-left corner. This property can take values in range of 0 .. 255. If the value is 255, the corner will appear with its full opacity. The value equal to zero results in a fully transparent corner. Other values in the range 1 .. 254 show a semitransparent view. This opacity value can additionally be modulated by the common opacity value stored in the property Opacity.

property int32 OpacityBR = 255;

The property 'OpacityBR' controls the translucence of the view at its bottom-right corner. This property can take values in range of 0 .. 255. If the value is 255, the corner will appear with its full opacity. The value equal to zero results in a fully transparent corner. Other values in the range 1 .. 254 show a semitransparent view. This opacity value can additionally be modulated by the common opacity value stored in the property Opacity.

property int32 OpacityTL = 255;

The property 'OpacityTL' controls the translucence of the view at its top-left corner. This property can take values in range of 0 .. 255. If the value is 255, the corner will appear with its full opacity. The value equal to zero results in a fully transparent corner. Other values in the range 1 .. 254 show a semitransparent view. This opacity value can additionally be modulated by the common opacity value stored in the property Opacity.

property int32 OpacityTR = 255;

The property 'OpacityTR' controls the translucence of the view at its top-right corner. This property can take values in range of 0 .. 255. If the value is 255, the corner will appear with its full opacity. The value equal to zero results in a fully transparent corner. Other values in the range 1 .. 254 show a semitransparent view. This opacity value can additionally be modulated by the common opacity value stored in the property Opacity.

property int32 Padding = 0;

The property 'Padding' determines additional gap in pixel to take in account at the left and right edges of the Text view (Bounds). 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.

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 display. Similar to HTML, the string may contain attributes to control the appearance and the flow of the text. All attributes are enclosed in curly braces and are not visible in the displayed text. Short overview of the available attributes:

The text can consist of several rows separated by the new-line sign '\\n'. Additionally an automatic text wrap will be performed. 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.

All colors, bitmaps and fonts are taken from the attribute set stored in the property AttrSet.

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