Setting Text Parameters in FireMonkey

Author: Сергей

One of small but rather useful new features of FireMonkey introduced in XE3 version is the FMX.Types.ITextSettings interface.
Often we need to change some parameters of an output text for a component, which class is not known a priori. For example, a component can be of the TText or TTextControl classes. These classes have Color or FontColor properties respectively. In general case, to set color to one of these properties, one need first check the type of an object instance and then cast the type:

if Obj is Ttext then
  TText(Obj).Color := MyColor
else if Obj is TTextControl then
  TTextControl(Obj).FontColor := MyColor;

Also you can access public properties using RTTI (Working with RTTI Index), but this looks not too fine especially taking into account that Color is not the only property of a text.

ITextSettings Interface

Usage of the ITextSettings interface makes such task much more simple and universal:
var
  Settings: ITextSettings;
  Instance: TComponent;
begin
...
  if IInterface(Instance).QueryInterface(ITextSettings, Settings) = S_OK then
  begin
    // Obtained ITextSettings interface for the component
  end;
You can use numerous ways to obtain the value of the Settings interface variable. In case of success, Settings has not nil value. In this case, the particular type of Instance is not important. What is important is that the obtained IInterface(Instance) interface contains the following properties: DefaultTextSettings, TextSettings, and StyledSettings.

These properties have the following meaning:

• DefaultTextSettings: TTextSettings — the default values of text properties. For styled controls, the DefaultTextSettings are set during the style loading in the FMX.Controls.TStyledControl.ApplyStyle method. For primitive controls (do not having styles), DefaultTextSettings are the same as TextSettings. In general case of a styled control, whether DefaultTextSettings are the same as TextSettings depends upon a particular realization of the control’s class. Notice that for the FMX.Objects.TText class, DefaultTextSettings and TextSettings are equal.
• TextSettings: TTextSettings — are customized text properties set manually.
• StyledSettings: TStyledSettings — This property defines, which text properties are taken from a style (see DefaultTextSettings) and which are set manually (see TextSettings) FMX.Types.TStyledSettings.

You can also use the following constants:

• DefaultStyledSettings – specifies the set of styled text settings that are usually set by default.
• AllStyledSettings – specifies the full set of styled text settings.

These constants have the following declarations:

unit FMX.Types;
...
type
  TStyledSetting = (ssFamily, ssSize, ssStyle, ssFontColor, ssOther);
  TStyledSettings = set of TStyledSetting;
const
  AllStyledSettings: TStyledSettings = [TStyledSetting.ssFamily,
                                        TStyledSetting.ssSize,
                                        TStyledSetting.ssStyle,
                                        TStyledSetting.ssFontColor,
                                        TStyledSetting.ssOther];
  DefaultStyledSettings: TStyledSettings = [TStyledSetting.ssFamily,
                                            TStyledSetting.ssSize,
                                            TStyledSetting.ssStyle,
                                            TStyledSetting.ssFontColor];

Keep in mind that, for example, when you are changing the value of the TextSettings.FontColor property, then the actual changing of the control’s view happens only if the StyledSettings property does not contain the TStyledSetting.ssFontColor property. Descendants of TTextControl, for example, TLabel provide possibility to edit the publishedStyledSetting property in the Object Inspector. When you change the color value, from the default value, the Object Inspector automatically sets ssFontColor = False. But such automatic changing of the ssFontColor property is made by the Object Inspector only at design time.


This is the fragment of code executed when a property influencing onto a text view is changed:

FTextObject.QueryInterface(ITextSettings, LISettings);
LISettings.TextSettings.Assign(FDefaultTextSettings);
LISettings.TextSettings.AssignNoStyled(TextSettings, FStyledSettings);

You see that this code:
1. First, set s all default values to the internal FTextObject text object and then
2. Sets values of some properties that were specified manually. During this process, the code takes into account the StyledSettings property (FMX.Types.ITextSettings.StyledSettings).

TTextSettings Class

The main aim of the TTextSettings class is to manage appearance properties of text objects. TTextSettings is the descendant of TPersistent. Classes using text objects TTextControl (FMX.Controls.TTextControl), TMemo (FMX.Memo.TMemo), TCustomEdit (FMX.Edit.TCustomEdit) , and their descendants have the public TextSettings property. That is, if you know the component type a priory, for example TLabel (FMX.StdCtrls.TLabel), then you do not obliged to retrieve the ITextSettings interface; you can use the appropriate text property of the particular component, as follows:

Label1.TextSettings.FontColor := claDarkkhaki;

Actually, the public TLabel.FontColor property “is raised” from the corresponding property of TTextSettings class (FMX.Types.TTextSettings.FontColor).

Notice that not all controls support all TTextSettings properties in the full extent. For example, TButton (FMX.StdCtrls.TButton) cannot change the text color correctly (because the color is changed when a button is pointed by the mouse cursor). Therefore, only fully supported properties are declared published. As the result, the TextSettings property is declared in the TTextControl (FMX.Controls.TTextControl) class as public, and the TextSettings property is kept public in standard controls. However, creating your own descendants of TTextControl, you can re-declare the TextSettings property as published. Then the Object Inspector provides possibility to edit values of sub-properties of the TextSettings property.

Let Us Shortly Review What the TTextSettings Class Contains

• Equals—Checks whether all properties of the current TTextSettings instance and of the specified TObject object are equal. If values of all properties are equal, then Equals returns True.
• DoChanged—This virtual method is called from other methods when changes of some text object properties happen. In descendants, you can override the DoChanged method and execute appropriate update of the component view basing on results of analysis of the IsChanged and IsAdjustChanged properties. Do not call DoChanged explicitly–to enforce an explicit control updating, call the Change method.
• Change—This method is called when any of the styled properties of the current TTextSettings object is changed. Method Change sets IsChanged = True, then, if the object is not in an updating state (UpdateCount = 0), calls DoChanged and then clears IsChanged and IsAdjustChanged (sets to False).

BeginUpdate and EndUpdate

• BeginUpdate increases by one the UpdateCount number of started and not accomplished updates of text properties of the current TTextSettings object. Till UpdateCount > 0, FireMonkey does no execute any update of the visual representation of the TTextSettings object.
• EndUpdate decreases UpdateCount. If UpdateCount becomes = 0 and any text property of the current TTextSettings object is changed (IsChanged or IsAdjustChanged is True), then EndUpdate calls DoChanged — to fire the OnChanged event. Then EndUpdate clears IsChanged and IsAdjustChanged (sets them to False).

Therefore if you need to change several text properties at once and do not want to redraw the visual representation of the TTextSettings object after changing of each property, then you can use the code like this:

TextSettings.BeginUpdate;
try
  TextSettings.FontColor := MyColor;
  TextSettings.Trimming := True;
  ...
finally
  TextSettings.EndUpdate;
end;

• IsChanged — This property becomes True, when any styled text property (Font.Family, Font.Size, Font.Style, FontColor, HorzAlign, HorzAlign, Trimming or WordWrap) is changed.
• IsAdjustChanged — This property becomes True, when any styled text property that can modify geometry parameters of a text. For example, the font color cannot modify the text size, but the font size
• Assign — This method copies the parameters of the specified Source object to the current TTextSettings (FMX.Types.TTextSettings) object. The specified Source parameter should contain whether the TTextSettings type object or nil. If Source is nil, then all properties obtain the default values. The TTextSettings constructor calls Assign(nil), if your descendant class should be initiated with some parameters having not the default values, then you need to override the Assign method in your class.
• AssignNoStyled — This method is similar to Assign, but it copies, from the specified TextSettings object, values only of that styled text properties, which are not pointed in the StyledSettings parameter.
• Trimming — If the value of this property is not ttNone and the text does not fit to the drawing area, then it is trimmed to fit the area and ellipsis sign is printed after the trimmed text.
• HorzAlign, VertAlign — These properties define parameters of horizontal and vertical text alignment.
• WordWrap — If this property is True, then the text wraps when it longer than the the drawing area.
• FontColor — The color to draw a text.
• Font — The font to draw a text.
• OnChanged — This event is fired when any styled text property is changed.