TextControl

Qualified name: delphifmx.TextControl

class TextControl

Bases: StyledControl

Base class for all text controls such as TDateEdit. TTextControl is the base class for all graphical controls that display text, such as TTimeEdit, TListBoxItem, TTabItem, and so on. TTextControl encapsulates standard functionality to manipulate the displayed text, offering the possibility of changing the font, the alignment of the text, or enabling word wrapping. If you need to create a new control from scratch that displays text (for instance, an enhanced label graphical control or a custom redesigned check box control), then you should derive your component from TTextControl. TTextControl implements the ITextSettings interface. This interface provides methods and properties to manage the most common text representation properties of general text objects independently of the particular types of these objects. TTextControl and its descendants contain the public property TextSettings of the TTextSettings type. Using the methods and the properties declared in the ITextSettings interface, you can manage the text representation TFont.Family, TFont.Size, TFont.Style, FontColor, HorzAlign, VertAlign, Trimming, and WordWrap properties defining visual parameters of the text representation. For more information, see Setting Text Parameters in FireMonkey. TTextControl uses the TTextSettingsInfo service class to manage sets of styled text representation properties stored in the DefaultTextSettings, TextSettings, StyledSettings, and ResultingTextSettings properties. TTextControl implements the IAcceleratorKeyReceiver interface to allow the use of this control as an accelerator key receiver.

Methods

AfterConstruction	Responds after the last constructor has executed.
ApplyStyleLookup	Gets and applies the style of a TStyledControl.
Change	Calls DoChanged when any of the styled text representation properties of the current TTextControl control is changed.
Inflate	Call this procedure to get and apply its style lookup.
NeedStyleLookup	Call this procedure to indicate that this control requires to get and apply its style lookup.
ToString	Returns a string containing the class name followed by the text that is rendered over the surface of this TTextControl object.

Attributes

AbsoluteClipRect	Specifies the absolute rectangle of the control after all its parent controls clip it.
AbsoluteEnabled	Specifies whether the control is absolutely enabled.
AbsoluteHeight	Specifies the absolute height of the control.
AbsoluteMatrix	Specifies the absolute transformation matrix of the control.
AbsoluteOpacity	Specifies the absolute opacity of the control.
AbsoluteRect	Specifies the absolute rectangle that bounds the control.
AbsoluteScale	Specifies the absolute scale of the control.
AbsoluteWidth	Specifies the absolute width of the control.
ActionClient	Specifies whether the component object has an associated action.
AdjustSizeValue	Updates the width and height of this control according to its current style
AdjustType	Determines if and how the width and height of this control should be modified to take the fixed space dictated by the style of this control
Align	Specifies the alignment options (top, left, client, and so on) of this control.
Anchors	Specifies how the control is anchored to its parent.
ApplyingEffect	A flag that signals when a control is in the process of applying an effect.
AutoCapture	Specifies whether the control captures mouse events.
AutoTranslate	Specifies whether the control's text should be translated
AxisAlignedRect	A TRectF defined by the width and height of the control.
BoundsRect	Specifies the bounding rectangle of the control.
CanParentFocus	Specifies whether the parent of this control should be evaluated to receive focus.
Canvas	Provides the drawing surface of the control.
Children	Stores an array of children attached to this parent component.
ChildrenCount	Read-only property that specifies the number of children in the children list.
ChildrenRect	Specifies the bigger rectangle area occupied by parent and children controls.
ClassName	Returns the TObject.ClassName
ClipChildren	Specifies if children of the control should be clipped to the control's on-screen region.
ClipParent	Specifies whether the current control has clipped its parent.
ClipRect	Specifies the bound rectangle to be clipped.
ComObject	Specifies the interface reference implemented by the component.
ComponentCount	Returns the owned component count
ComponentIndex	Indicates the position of the component in its owner's Components property array.
ComponentState	Describes the current state of the component, indicating when a component needs to avoid certain actions.
ComponentStyle	Governs the behavior of the component.
Components	Returns an iterator over the owned components
Controls	Returns an iterator over contained controls
ControlsCount	Returns the count of contained controls
Cursor	Image to use to represent the mouse pointer when it passes into the region covered by the control.
Data	Stores a Tvalue, which is a data structure that can store different kinds of data types.
DefaultSize	Embarcadero Technologies does not currently have any additional information.
DefaultStyleLookupName	Returns a string with the name of the default style of this control
DefaultTextSettings	Stores a TTextSettings type object keeping the default values of the text representation properties.
DesignInfo	Contains information used by the Form designer.
DisableDisappear	Embarcadero Technologies does not currently have any additional information.
DisableFocusEffect	Specifies whether the control has the focus effect disabled.
DragMode	Specifies how the control initiates drag-and-drop operations.
EnableDragHighlight	Specifies whether the control is highlighted when the dragged object is over it.
Enabled	Specifies whether the control responds to mouse, keyboard, and timer events.
FixedSize	Embarcadero Technologies does not currently have any additional information.
Font	Specifies the font to use when rendering the text.
FontColor	Specifies the font color of the text in this TTextControl control.
HasAfterPaintEffect	Specifies whether the control has an effect that is applied after the control is painted.
HasClipParent	Control that is a direct child of this control and has clipped this control.
HasDisablePaintEffect	Specifies whether the control's effect is painted.
HasEffect	Specifies whether the control has an applied effect.
Height	Height specifies the vertical size of the control (in dp).
HelpContext	Contains the numeric context ID that identifies the Help topic for the control.
HelpKeyword	Contains the keyword string that identifies the Help topic for the control.
HelpType	Specifies whether the control's context-sensitive Help topic is identified by a context ID or by keyword.
Hint	Specifies the text string that appears when the user moves the mouse over a control.
HitTest	Enables the control to capture mouse events.
InPaintTo	Specifies whether the control is currently being painted.
Index	Specifies the index of the child object in the children array attached to this object.
InheritedCursor	Image used to represent the mouse pointer when it passes into the region covered by the control.
InvertAbsoluteMatrix	Specifies the inverse matrix of AbsoluteMatrix.
IsDragOver	Specifies whether a dragged object is over the area of the current control.
IsFocused	Determines whether the control has input focus.
IsInflated	Whether the current style of this control has been actually applied to the control.
IsMouseOver	Specifies whether the mouse cursor is over the control.
IsVisible	Specifies whether the control is visible.
LocalRect	Specifies the local rectangle for painting the control.
Locked	Specifies whether the control is locked at design time.
Margins	Aligns the component to the margins points of other components.
Name	Specifies the name of the component as referenced in code.
Observers	Indicates the TObservers object added to the TComponent.
OnGesture	Callable[[Object, GestureEventInfo, bool], None]:
Opacity	Specifies the control opacity.
Owner	Returns the Component Owner
Padding	Aligns the component to the padding points of other components.
Parent	Returns/Sets the Control Visibility
ParentClassStyleLookupName	The name of the default style of the parent class of this control.
ParentControl	Specifies the parent control of this control.
ParentedRect	Specifies the bounding rectangle of the control within its parent.
ParentedVisible	Specifies whether all the control's parents are visible.
PopupMenu	Specifies the context (pop-up) menu object.
Position	Returns an access to the position of the control inside its parent
PrefixStyle	Determines whether the ampersand character (&) is considered as a special prefix character.
Pressed	Indicates whether the control is currently pressed.
PressedPosition	A point that indicates where exactly on the control the click occured.
ResultingTextSettings	Keeps final values of text representation properties.
Root	Specifies the root parent of this object.
Scene	Specifies the current scene in which the control is drawn.
ShowHint	Specifies whether the Hint can be shown.
Size	Specifies the vertical and horizontal size (Size.Height and Size.Width) of the control (in pixels).
Stored	Specifies whether this object is stored in the .XFM file.
StyleLookup	Specifies the name of the resource object to which the current TStyledControl is linked
StyleName	Specifies the style name for this FMX component.
StyleState	This property allows you to define the current state of style
StyledSettings	Defines the set of styled text representation properties whose values are loaded from the current style and cannot be changed manually.
StylesData	Value:
TabOrder	Indicates the position of the control in its parent's tab order.
TabStop	Embarcadero Technologies does not currently have any additional information.
Tag	Stores a NativeInt integral value as a part of a component.
TagFloat	Custom property that stores any floating-point value.
TagObject	Custom property that stores any object value.
TagString	Custom property that stores any string value.
Text	Specifies the text that will be rendered over the surface of this TTextControl object.
TextAlign	Specifies how the text will be displayed in terms of horizontal alignment.
TextSettings	Keeps the values of styled text representation properties that are set in the Object Inspector or programmatically.
Touch	Specifies the touch manager component associated with the control.
TouchTargetExpansion	Set of optional pixel values you can specify to expand the touch target of a FireMonkey styled control.
Trimming	Specifies the behavior of the text, when it overflows the area for drawing the text.
UpdateRect	Specifies the rectangle area of the control that needs to be updated.
VCLComObject	Represents information used internally by components that support COM.
VertTextAlign	Specifies how the text will be displayed in terms of vertical alignment.
Visible	Returns/Sets the Control Visibility
Width	Specifies the horizontal size of the control (in pixels).
WordWrap	Specifies whether the text inside the TTextControl object wraps when it is longer than the width of the control.

AdjustSizeValue

Updates the width and height of this control according to its current style

AdjustType

Determines if and how the width and height of this control should be modified to take the fixed space dictated by the style of this control

AfterConstruction()

Responds after the last constructor has executed. FMX.Controls.TTextControl.AfterConstruction inherits from System.TObject.AfterConstruction. All content below this line refers to System.TObject.AfterConstruction. Responds after the last constructor has executed. AfterConstruction is called automatically after the object’s last constructor has executed. Do not call it explicitly in your applications. The AfterConstruction method implemented in TObject does nothing. Override this method when creating a class that performs an action after the object is created. For example, TCustomForm overrides AfterConstruction to generate an OnCreate event.

ApplyStyleLookup()

Gets and applies the style of a TStyledControl.

AutoTranslate

Specifies whether the control’s text should be translated

Change()

Calls DoChanged when any of the styled text representation properties of the current TTextControl control is changed. Change is called when any of the Font, FontColor, VertTextAlign, Trimming or WordWrap properties is changed. If the control is not in a loading or destroying state (csLoading or csDestroying), Change calls DoChanged to update the representation of the text on the control.

DefaultStyleLookupName

Returns a string with the name of the default style of this control

DefaultTextSettings

Stores a TTextSettings type object keeping the default values of the text representation properties. DefaultTextSettings is set during the loading of the style in the ApplyStyle method. DefaultTextSettings is initialized in Create with the following values:

Font.Size := 11 ; // depends on the platform Font.Family = ‘Tahoma’; // depends on the platform Font.Style := [] ; FontColor := TAlphaColorRec.Black; TextAlign := TTextAlign.Leading; VertTextAlign := TTextAlign.Center; Trimming := TTextTrimming.None; WordWrap := False;

Type:

TextSettings

Font

Specifies the font to use when rendering the text. Set Font to specify the font to use when rendering the text. To change to a new font, specify a new TFont object. To modify a font, change the value of the Family, Size, or Style of the TFont object.

Type:

Font

FontColor

Specifies the font color of the text in this TTextControl control. Use the FontColor property to read or change the font color of the text in this TTextControl control. The default value of the FontColor property is TAlphaColorRec.Black.

Type:

int

Inflate()

Call this procedure to get and apply its style lookup.

NeedStyleLookup()

Call this procedure to indicate that this control requires to get and apply its style lookup.

PrefixStyle

Determines whether the ampersand character (&) is considered as a special prefix character. The default value is TPrefixStyle.HidePrefix, which means that the (first) ampersand is hidden at run-time.

Type:

PrefixStyle

ResultingTextSettings

Keeps final values of text representation properties. These values are really used to draw texts in a control. ResultingTextSettings keeps a TTextSettings object that manages the final values of the text representation properties. These values are really used to draw texts in a control. To obtain values stored in ResultingTextSettings, a control uses the StyledSettings property. For example, if StyledSettings contains the TStyledSetting.Family value, then the TFont.Family value is taken from the DefaultTextSettings. (That is the font family name defined in the loaded style is used. The font family name defined by the programmer in the Object Editor is ignored.) Oppositely, if StyledSettings does not contain TStyledSetting.Family, then the font family name defined by the programmer in the Object Editor is used and the font family name defined in the loaded style is ignored. The TTextSettings class define properties keeping values of the FontColor, TextAlign, VertTextAlign, Trimming, WordWrap, and Font (TFont.Family, TFont.Size, TFont.Style) elements defining visual parameters of a text representation. RecalculateTextSettings updates the ResultingTextSettings.

Type:

TextSettings

StyleLookup

Specifies the name of the resource object to which the current TStyledControl is linked

StyleState

This property allows you to define the current state of style

StyledSettings

Defines the set of styled text representation properties whose values are loaded from the current style and cannot be changed manually. Text representation properties are used as parameters for drawing texts in controls. The StyledSettings property is used in FMX controls such as TButton, TSpeedButton, TCheckBox, and others. Styles, for example Metropolis UI styles, define the default values of the text representation properties like font name, font size, word-wrapping, and others. The TTextSettings class define properties keeping values of the FontColor, TextAlign, VertTextAlign, Trimming, WordWrap, and Font (TFont.Family, TFont.Size, TFont.Style) elements defining visual parameters of a text representation. StyledSettings can contain the Family, Size, Style, FontColor, and Other values defined in TStyledSetting. The “Relation between TStyledSetting constants and TTextSettings properties” table shows which of the TStyledSetting constants control the handling of these TTextSettings text representation properties. Keep in mind that the values of all styled text representation properties listed in the StyledSettings are taken from a style and cannot be changed manually. For example, if you set a new value of the FontColor property of a TTextControl control, then the real updating of the font color takes place only if the StyledSettings property of this control does not contain TStyledSetting.FontColor. For more details, see the example in Setting Text Parameters in FireMonkey. To switch OFF a font property for a control, select the control in the Form Designer. In the Object Inspector, expand the StyledSettings property. Clear the check mark before the property. For example, the following figure shows a TButton control with Size turned OFF (for Button1) and ON (for Button2):

With StyledSettings you can also use the DefaultStyledSettings constant that defines the values of the styled properties that are taken from a style by default. Remember that the HorzAlign and VertAlign text representation properties stored in the TextSettings property of a control correspond to the TextAlign and VertTextAlign properties of the control.

Type:

StyledSettings

Text

Specifies the text that will be rendered over the surface of this TTextControl object. Set the Text property to specify the text that will be displayed by this TTextControl. Text can be any string. If there are any effects already applied before changing the Text property, they will be preserved for the new text. Also, the surface of this TTextControl is repainted. In the Text property you can define an accelerator key. On Windows platforms, an accelerator key is shown as an underlined letter. To specify an accelerator key, precede an <accelerator_letter> with an ampersand & character. The letter after the ampersand appears underlined. For example, to set the S character as an accelerator key for a Save button, type &Save. On Windows platforms, accelerator keys enable the user to access controls pressing Alt+<accelerator_letter> key combination. When run on not Windows platforms, a single ampersand is simply stripped from the text. To show a single ampersand & character in a Text property specify doubled ampersand && characters.

Tip: If you specify a new text string that is exactly the same as the one already displayed, the effects will not be re-updated and this TTextControl object will not be repainted. Note: FMX.ExtCtrls.TPopupBox.Text is not a writable property in the same way as FMX.Controls.TTextControl.Text. The FMX.ExtCtrls.TPopupBox.Text property cannot be “any string”, but instead must be just one of the strings in the FMX.ExtCtrls.TPopupBox.Items property and, in this case, FMX.ExtCtrls.TPopupBox.ItemIndex is updated accordingly.

Type:

str

TextAlign

Specifies how the text will be displayed in terms of horizontal alignment. The TextAlign property specifies how the TTextControl object will display the text in terms of horizontal alignment. TextAlign can have one of the following values (defined in TTextAlign):

Center (default)–aligns the text on a horizontal axis, at the middle of the TTextControl object. Leading–aligns the text on a horizontal axis, at the leftmost position inside the TTextControl object. Trailing–aligns the text on a horizontal axis, at the rightmost position inside the TTextControl object. When you use text representation properties stored in ITextSettings.TextSettings, remember that TextAlign corresponds to HorzAlign.

Type:

TextAlign

TextSettings

Keeps the values of styled text representation properties that are set in the Object Inspector or programmatically. TextSettings references a TTextSettings type object that handles values of styled text representation properties that are set in the Object Inspector or programmatically. TextSettings references a TTextSettings type object, which handles styled text representation properties to be used for drawing texts in this control. TTextSettings type objects provide all styled text representation properties and methods to manage them. The styled text representation properties are FontColor, TextAlign, VertTextAlign, Trimming, WordWrap, and Font (TFont.Family, TFont.Size, and TFont.Style). TTextSettings objects provide both styled text representation properties, whose values are loaded from a style (specified in StyledSettings), so all other styled text representation properties, whose values can be set manually, and methods to manage these text representation properties. The text representation properties identified in StyledSettings are loaded from the style and cannot be set manually. Remember that the HorzAlign and VertAlign text representation properties stored in the TextSettings property of a control correspond to the TextAlign and VertTextAlign properties of the control.

Type:

TextSettings

ToString()

Returns a string containing the class name followed by the text that is rendered over the surface of this TTextControl object. ToString returns a string containing the concatenation of two substrings:

The first substring contains the class name of the instance that is being called (retrieved by TObject.ToString). For example, calling on a TCheckBox instance returns a substring containing TCheckBox. The second substring contains the text from the Text property. This is the text that will be rendered over the surface of the object in which ToString is called.

Trimming

Specifies the behavior of the text, when it overflows the area for drawing the text. Trimming may take the following values defined in the TTextTrimming type: None, Character, and Word. If the value of this property is not None and the text does not fit in the drawing area, then it is trimmed to fit the area and an ellipsis sign is printed after the trimmed text.

Note: Under the iOS platform, Trimming works only when WordWrap = False.

Type:

TextTrimming

VertTextAlign

Specifies how the text will be displayed in terms of vertical alignment. The VertTextAlign property specifies how the TTextControl control displays the text in terms of vertical alignment. VertTextAlign can have one of the following values (defined in TTextAlign):

Center (default)–aligns the text on a vertical axis, at the middle of the TTextControl object. Leading–aligns the text on a vertical axis, at the topmost position inside the TTextControl object. Trailing–aligns the text on a vertical axis, at the bottommost position inside the TTextControl object. When you use text representation properties stored in ITextSettings.TextSettings, remember that VertTextAlign corresponds to VertAlign.

Type:

TextAlign

WordWrap

Specifies whether the text inside the TTextControl object wraps when it is longer than the width of the control. Set WordWrap to True to allow the TTextControl control to display multiple lines of text. When WordWrap is True, text that is too long for the TTextControl object wraps at the right margin and continues in additional lines. Set WordWrap to False for the text to span onto a single line of the TTextControl. However, in this case, the text that is too long for TTextControl appears truncated. The default value for the WordWrap property is False.

Type:

bool