Class TextObject

Represents the Text object that may display one or several text lines.

Inheritance
System.Object
Base
ComponentBase
ReportComponentBase
BreakableComponent
TextObjectBase
TextObject
CellularTextObject
TableCell
Implements
Inherited Members
Namespace: FastReport
Assembly: FastReport.dll
Syntax
public class TextObject : TextObjectBase, IDisposable, IFRSerializable, ISearchable
Remarks

Specify the object's text in the Text property. Text may contain expressions and data items, for example: "Today is [Date]". When report is running, all expressions are calculated and replaced with actual values, so the text would be "Today is 01.01.2008".

The symbols used to find expressions in a text are set in the Brackets property. You also may disable expressions using the AllowExpressions property.

To format an expression value, use the FastReport.Format property.

Constructors

TextObject()

Initializes a new instance of the TextObject class with default settings.

Declaration
public TextObject()

Properties

Angle

Gets or sets the text angle, in degrees.

Declaration
public int Angle { get; set; }
Property Value
Type Description
System.Int32

AutoShrink

Gets or sets a value that indicates whether the font size should shrink to display the longest text line without word wrap.

Declaration
public AutoShrinkMode AutoShrink { get; set; }
Property Value
Type Description
AutoShrinkMode
Remarks

To limit the minimum size, use the AutoShrinkMinSize property.

AutoShrinkMinSize

Gets or sets the minimum size of font (or minimum width ratio) if the AutoShrink mode is on.

Declaration
public float AutoShrinkMinSize { get; set; }
Property Value
Type Description
System.Single
Remarks

This property determines the minimum font size (in case the AutoShrink property is set to FontSize), or the minimum font width ratio (if AutoShrink is set to FontWidth).

The default value is 0, that means no limits.

AutoWidth

Gets or sets a value that determines if the text object should handle its width automatically.

Declaration
public bool AutoWidth { get; set; }
Property Value
Type Description
System.Boolean

Clip

Gets or sets a value that indicates if text should be clipped inside the object's bounds.

Declaration
public bool Clip { get; set; }
Property Value
Type Description
System.Boolean

FirstTabOffset

Gets or sets the offset of the first TAB symbol. Negative value will not affect this property.

Declaration
public float FirstTabOffset { get; set; }
Property Value
Type Description
System.Single

Font

Gets or sets the font settings for this object.

Declaration
public Font Font { get; set; }
Property Value
Type Description
System.Drawing.Font

FontWidthRatio

Gets or sets the width ratio of the font.

Declaration
public float FontWidthRatio { get; set; }
Property Value
Type Description
System.Single
Remarks

Default value is 1. To make a font wider, set a value grether than 1; to make a font narrower, set a value less than 1.

ForceJustify

Forces justify for the last text line.

Declaration
[Browsable(false)]
public bool ForceJustify { get; set; }
Property Value
Type Description
System.Boolean

HasHtmlTags

Indicates handling html tags in the text.

Declaration
[Browsable(false)]
public bool HasHtmlTags { get; }
Property Value
Type Description
System.Boolean
Remarks

To set the value use the TextRenderer property.

Highlight

Gets the collection of conditional highlight attributes.

Declaration
public ConditionCollection Highlight { get; }
Property Value
Type Description
ConditionCollection
Remarks

Conditional highlight is used to change the visual appearance of the Text object depending on some condition(s). For example, you may highlight negative values displayed by the Text object with red color. To do this, add the highlight condition:

TextObject text1;
HighlightCondition highlight = new HighlightCondition();
highlight.Expression = "Value < 0";
highlight.Fill = new SolidFill(Color.Red);
highlight.ApplyFill = true;
text1.Highlight.Add(highlight);

HorzAlign

Gets or sets the horizontal alignment of a text in the TextObject object.

Declaration
public HorzAlign HorzAlign { get; set; }
Property Value
Type Description
HorzAlign

HtmlTags

Allows handling html tags in the text.

Declaration
[Browsable(false)]
[Obsolete("This method is deprecated please use TextRenderer")]
public bool HtmlTags { get; set; }
Property Value
Type Description
System.Boolean
Remarks

The following html tags can be used in the object's text: <b>, <i>, <u>, <strike>, <sub>, <sup>, </b>, </i>, </u>, </strike>, </sub>, </sup>, <font color=&...&>, </font>. Font size cannot be changed due to limitations in the rendering engine.

InlineImageCache

Cache for inline images

Declaration
[Browsable(false)]
public InlineImageCache InlineImageCache { get; }
Property Value
Type Description
InlineImageCache

LineHeight

Gets or sets the height of single text line, in pixels.

Declaration
public float LineHeight { get; set; }
Property Value
Type Description
System.Single

MergeMode

Gets or sets a value indicating whether the text should be merged with other nearby text objects.

Declaration
public MergeMode MergeMode { get; set; }
Property Value
Type Description
MergeMode

ParagraphFormat

Gets or sets a paragraph format for a new html rendering type, not for others rendering

Declaration
public ParagraphFormat ParagraphFormat { get; set; }
Property Value
Type Description
ParagraphFormat

ParagraphOffset

Gets or sets the paragraph offset, in pixels. For HtmlParagraph use ParagraphFormat.FirstLineIndent.

Declaration
[TypeConverter("FastReport.TypeConverters.UnitsConverter, FastReport")]
public float ParagraphOffset { get; set; }
Property Value
Type Description
System.Single

RightToLeft

Gets or sets a value that indicates whether the component should draw right-to-left for RTL languages.

Declaration
public bool RightToLeft { get; set; }
Property Value
Type Description
System.Boolean

TabPositions

Gets or sets a collection of TAB symbol positions, in pixels. Negative values will not affect this property.

Declaration
public FloatCollection TabPositions { get; set; }
Property Value
Type Description
FloatCollection
Remarks

Use collection methods to add or remove TAB positions.

TabWidth

Gets or sets the width of TAB symbol, in pixels. Negative values will not affect this property.

Declaration
public float TabWidth { get; set; }
Property Value
Type Description
System.Single

TextColor

Gets or sets the text color in a simple manner.

Declaration
[Browsable(false)]
public Color TextColor { get; set; }
Property Value
Type Description
System.Drawing.Color
Remarks

This property can be used in a report script to change the text color of the object. It is equivalent to: 

textObject1.TextFill = new SolidFill(color);

TextFill

Gets or sets the fill color used to draw a text.

Declaration
public FillBase TextFill { get; set; }
Property Value
Type Description
FillBase
Remarks

Default fill is SolidFill. You may specify other fill types, for example:

text1.TextFill = new HatchFill(Color.Black, Color.White, HatchStyle.Cross);

Use the TextColor property to set the solid text color.

TextOutline

Gets or sets the text outline.

Declaration
public TextOutline TextOutline { get; set; }
Property Value
Type Description
TextOutline

TextRenderType

The type of text render

Declaration
public TextRenderType TextRenderType { get; set; }
Property Value
Type Description
TextRenderType
Remarks

The following html tags can be used in the object's text: <b>, <i>, <u>, <strike>, <sub>, <sup>, </b>, </i>, </u>, </strike>, </sub>, </sup>, <font color=&...&>, </font>. Font size cannot be changed due to limitations in the rendering engine.

Trimming

Gets or sets the string trimming options.

Declaration
public StringTrimming Trimming { get; set; }
Property Value
Type Description
System.Drawing.StringTrimming

Underlines

Gets or sets a value that determines if the text object will underline each text line.

Declaration
public bool Underlines { get; set; }
Property Value
Type Description
System.Boolean

VertAlign

Gets or sets the vertical alignment of a text in the TextObject object.

Declaration
public VertAlign VertAlign { get; set; }
Property Value
Type Description
VertAlign

WordWrap

Gets or sets a value that indicates if lines are automatically word-wrapped.

Declaration
public bool WordWrap { get; set; }
Property Value
Type Description
System.Boolean

Wysiwyg

Gets or sets a value that indicates if the text object should display its contents similar to the printout.

Declaration
public bool Wysiwyg { get; set; }
Property Value
Type Description
System.Boolean

Methods

ApplyStyle(Style)

Applies the style settings.

Declaration
public override void ApplyStyle(Style style)
Parameters
Type Name Description
Style style

Style to apply.
Overrides

Assign(Base)

Copies the contents of another, similar object.

Declaration
public override void Assign(Base source)
Parameters
Type Name Description
Base source

Source object to copy the contents from.
Overrides
Remarks

Call Assign to copy the properties from another object of the same type. The standard form of a call to Assign is

destination.Assign(source);

which tells the destination object to copy the contents of the source object to itself. In this method, all child objects are ignored. If you want to copy child objects, use the AssignAll method.

See Also

Break(BreakableComponent)

Breaks the contents of the object.

Declaration
public override bool Break(BreakableComponent breakTo)
Parameters
Type Name Description
BreakableComponent breakTo

Object to put the part of content to that does not fit in this object. These two objects must have the same type.
Returns
Type Description
System.Boolean

true if there is enough space in this object to display at least one text line.
Overrides
Remarks

Do not call this method directly, it is used by the report engine. You should override it if you are writing a new FastReport object.

This method must break the contents of the object. The part of content that fit in current object's bounds should remain in this object, the part that does not fit should be transferred to breakTo object.

CalcHeight()

Calculates the object's height.

Declaration
public override float CalcHeight()
Returns
Type Description
System.Single

Actual object's height, in pixels.
Overrides
Remarks

Applicable to objects that contain several text lines, such as TextObject. Returns the height needed to display all the text lines.

CalcWidth()

Calculates the object's width.

Declaration
public float CalcWidth()
Returns
Type Description
System.Single

The width, in pixels.

Deserialize(FRReader)

Declaration
public override void Deserialize(FRReader reader)
Parameters
Type Name Description
FRReader reader
Overrides

DeserializeSubItems(FRReader)

Deserializes nested object properties.

Declaration
protected override void DeserializeSubItems(FRReader reader)
Parameters
Type Name Description
FRReader reader

Reader object.
Overrides
Remarks

Typically the object serializes all properties to the single xml item:

<TextObject Name="Text2" Left="18.9" Top="37.8" Width="283.5" Height="28.35"/>

Some objects like DataBand have child objects that serialized in subitems:

<DataBand Name="Data1" Top="163" Width="718.2" Height="18.9">
  <TextObject Name="Text3" Left="18.9" Top="37.8" Width="283.5" Height="28.35"/>
</DataBand>

To read such subitems, the DeserializeSubItems method is used. Base implementation reads the child objects. You may override it to read some specific subitems.

Draw(FRPaintEventArgs)

Draws the object.

Declaration
public override void Draw(FRPaintEventArgs e)
Parameters
Type Name Description
FRPaintEventArgs e

Paint event args.
Overrides
Remarks

This method is widely used in the FastReport. It is called each time when the object needs to draw or print itself.

In order to draw the object correctly, you should multiply the object's bounds by the scale parameter.

cache parameter is used to optimize the drawing speed. It holds all items such as pens, fonts, brushes, string formats that was used before. If the item with requested parameters exists in the cache, it will be returned (instead of create new item and then dispose it).

DrawText(FRPaintEventArgs)

Draws a text.

Declaration
public void DrawText(FRPaintEventArgs e)
Parameters
Type Name Description
FRPaintEventArgs e

Paint event data.

FinalizeComponent()

Declaration
public override void FinalizeComponent()
Overrides

GetConvertedObjects()

Used to get an enumeration of the objects to which this object will be converted, before calling this function, the IsHaveToConvert function will be called

Declaration
public override IEnumerable<Base> GetConvertedObjects()
Returns
Type Description
System.Collections.Generic.IEnumerable<Base>

By default returns this object
Overrides
Remarks

The functions IsHaveToConvert and GetConvertedObjects allow you to convert objects from one to another, for example the export will convert object before adding it to the file and convert recursive, i.e. If the new object has the ability to convert, it will be converted again but limit is 10 times. At the time of export it is called, only on objects inside the band, the child objects of converted object will be returned, and the child objects of old object will be ignored.

GetData()

Gets the data from a datasource that the object is connected to.

Declaration
public override void GetData()
Overrides
Remarks

This method is called by the report engine before processing the object.

Do not call it directly. You may override it if you are developing a new FastReport component. In this method you should get the data from a datasource that the object is connected to.

GetDataAsync(CancellationToken)

Declaration
public override async Task GetDataAsync(CancellationToken cancellationToken)
Parameters
Type Name Description
System.Threading.CancellationToken cancellationToken
Returns
Type Description
System.Threading.Tasks.Task
Overrides

GetExpressions()

Gets all expressions contained in the object.

Declaration
public override string[] GetExpressions()
Returns
Type Description
System.String[]

Array of expressions or null if object contains no expressions.
Overrides
Remarks

Do not call this method directly. You may override it if you are developing a new component for FastReport.

This method is called by FastReport each time before run a report. FastReport do this to collect all expressions and compile them. For example, GetExpressions method of the TextObject class parses the text and returns all expressions found in the text.

GetHtmlTextRenderer(Single, Single)

Returns an instance of html text renderer.

Declaration
public HtmlTextRenderer GetHtmlTextRenderer(float scale, float fontScale)
Parameters
Type Name Description
System.Single scale

Scale ratio.
System.Single fontScale

Font scale ratio.
Returns
Type Description
HtmlTextRenderer

The html text renderer.

GetStringFormat(GraphicCache, StringFormatFlags)

Returns StringFormat object.

Declaration
public StringFormat GetStringFormat(GraphicCache cache, StringFormatFlags flags)
Parameters
Type Name Description
GraphicCache cache

Report graphic cache.
System.Drawing.StringFormatFlags flags

StringFormat flags.
Returns
Type Description
System.Drawing.StringFormat

StringFormat object.

InitializeComponent()

Declaration
public override void InitializeComponent()
Overrides

IsHaveToConvert(Object)

Used to get information of the need to convertation if the function returns true, then the GetConvertedObjects function is called

Declaration
public override bool IsHaveToConvert(object sender)
Parameters
Type Name Description
System.Object sender

The export or the object, that call this method
Returns
Type Description
System.Boolean

By default returns false
Overrides
Remarks

The functions IsHaveToConvert and GetConvertedObjects allow you to convert objects from one to another, for example the export will convert object before adding it to the file and convert recursive, i.e. If the new object has the ability to convert, it will be converted again but limit is 10 times. At the time of export it is called, only on objects inside the band, the child objects of converted object will be returned, and the child objects of old object will be ignored.

RestoreState()

Restores the object's state after printing it.

Declaration
public override void RestoreState()
Overrides
Remarks

This method is called by the report engine after processing the object.

Do not call it directly. You may override it if you are developing a new FastReport component. In this method you should restore the object properties that were saved by the SaveState() method.

RestoreStyle()

Restores the current style.

Declaration
public override void RestoreStyle()
Overrides

SaveState()

Saves the object's state before printing it.

Declaration
public override void SaveState()
Overrides
Remarks

This method is called by the report engine before processing the object.

Do not call it directly. You may override it if you are developing a new FastReport component. In this method you should save any object properties that may be changed during the object printing. The standard implementation saves the object's bounds, visibility, bookmark and hyperlink.

SaveStyle()

Saves the current style.

Declaration
public override void SaveStyle()
Overrides

SearchText(String, Boolean, Boolean)

Finds the specified text inside the object.

Declaration
public override CharacterRange[] SearchText(string text, bool matchCase, bool wholeWord)
Parameters
Type Name Description
System.String text

Text to find.
System.Boolean matchCase

true to perform case-sensitive search.
System.Boolean wholeWord

true to find whole words only.
Returns
Type Description
System.Drawing.CharacterRange[]

Array of character ranges that describes the occurences of text found; null if text not found.
Overrides

Serialize(FRWriter)

Serializes the object.

Declaration
public override void Serialize(FRWriter writer)
Parameters
Type Name Description
FRWriter writer

Writer object.
Overrides
Remarks

Do not call this method directly. You should override it if you are developing a new component for FastReport.

This method is called when the object needs to save the state. It may happen when:

  • saving the report to the file or stream;
  • saving the report to the designer's undo buffer;
  • assigning the object to another object using the Assign(Base) or AssignAll methods;
  • saving the object to the designer's clipboard;
  • saving the object to the preview (when run a report).

Implements