ClassTextPrimitive
Represents a primitive element that renders text content with advanced formatting, layout, and styling capabilities.
Definition
Namespace:Telerik.WinControls.Primitives
Assembly:Telerik.WinControls.dll
Syntax:
public class TextPrimitive : BasePrimitive, IDisposable, INotifyPropertyChanged, ICustomTypeDescriptor, ISupportSystemSkin, IStylableNode, IPrimitive, ITextProvider, ITextPrimitiveInheritance: objectDisposableObjectRadObjectRadElementVisualElementBasePrimitiveTextPrimitive
Derived Classes:
Implements:
Inherited Members
Constructors
TextPrimitive()
Declaration
public TextPrimitive()Fields
AutoEllipsisProperty
Declaration
public static RadProperty AutoEllipsisPropertyField Value
DisabledTextRenderingHintProperty
Declaration
public static RadProperty DisabledTextRenderingHintPropertyField Value
MeasureTrailingSpacesProperty
Declaration
public static RadProperty MeasureTrailingSpacesPropertyField Value
ShowKeyboardCuesProperty
Declaration
public static RadProperty ShowKeyboardCuesPropertyField Value
TextAlignmentProperty
Declaration
public static RadProperty TextAlignmentPropertyField Value
TextOrientationProperty
Declaration
public static RadProperty TextOrientationPropertyField Value
TextRenderingHintProperty
Declaration
public static RadProperty TextRenderingHintPropertyField Value
Properties
AutoEllipsis
Gets or sets a value indicating whether the additional label text is to be indicated by an ellipsis.
Declaration
public bool AutoEllipsis { get; set; }Property Value
true if the additional label text is to be indicated by an ellipsis otherwise, false. Default value is true.
Implements
CachedForeColor
Declaration
[Browsable(false)]
public Color CachedForeColor { get; set; }Property Value
DisabledTextRenderingHint
Gets or sets the text rendering hint used when this primitive is disabled.
Declaration
public virtual TextRenderingHint DisabledTextRenderingHint { get; set; }Property Value
A TextRenderingHint value that specifies the text rendering quality for disabled state. The default value is AntiAliasGridFit.
Remarks
This property allows for different text rendering quality when the primitive is disabled, often providing a softer appearance that visually indicates the disabled state.
FlipText
Gets or sets a value indicating whether the text should be flipped (mirrored) during rendering.
Declaration
public bool FlipText { get; set; }Property Value
true if the text should be flipped; otherwise, false. The default value is false.
Implements
Remarks
Text flipping creates a mirror image of the text, which can be useful for special visual effects or when implementing right-to-left language support with custom rendering requirements. This property works in conjunction with TextOrientation for advanced text transformations.
IsEmpty
Gets a value indicating whether this primitive contains any displayable content.
Declaration
public override bool IsEmpty { get; }Property Value
true if the Text property is null or empty; otherwise, false.
Overrides
Remarks
This property is used by the layout system and rendering engine to optimize operations by skipping empty text primitives during layout calculations and paint operations.
LineLimit
Gets or sets a value indicating whether text rendering is limited to a specific number of lines.
Declaration
public bool LineLimit { get; set; }Property Value
true if line limiting is enabled; otherwise, false.
Remarks
When enabled, this property works in conjunction with other text formatting options to control the maximum number of lines displayed, providing better control over text layout in constrained spaces.
MeasureTrailingSpaces
Gets or sets a value indicating whether trailing spaces at the end of each line are included in text measurement calculations.
Declaration
public bool MeasureTrailingSpaces { get; set; }Property Value
true to include trailing spaces in text measurement; otherwise, false.
The default value is true.
Implements
Remarks
By default, the boundary rectangle returned by text measurement methods excludes trailing spaces
at the end of each line. Setting this property to true includes that space in measurement,
which can be important for precise layout calculations and text alignment scenarios.
This property is particularly useful when working with text that needs to maintain exact spacing or when implementing custom text layout algorithms.
Shadow
Gets or sets the shadow settings.
Declaration
[TypeConverter("Telerik.WinControls.UI.Design.ShadowSettingsConverter, Telerik.WinControls.UI.Design, Version=2026.1.217.48, Culture=neutral, PublicKeyToken=5bb2a467cbec794e")]
public ShadowSettings Shadow { get; set; }Property Value
Implements
ShowKeyboardCues
Gets or sets a value indicating whether if the keyboard accelerators are visible.
Declaration
public bool ShowKeyboardCues { get; set; }Property Value
true if if the keyboard accelerators are visible otherwise, false.
Implements
StretchHorizontally
Gets or sets a value indicating whether this primitive stretches horizontally within its parent layout.
Declaration
public override bool StretchHorizontally { get; set; }Property Value
true if the primitive should stretch horizontally; otherwise, false.
The default value is false.
Overrides
Remarks
For text primitives, horizontal stretching is typically disabled to maintain text layout integrity and prevent unwanted text spacing or alignment issues.
StretchVertically
Gets or sets a value indicating whether this primitive stretches vertically within its parent layout.
Declaration
public override bool StretchVertically { get; set; }Property Value
true if the primitive should stretch vertically; otherwise, false.
The default value is false.
Overrides
Remarks
For text primitives, vertical stretching is typically disabled to maintain proper text positioning and prevent text from being improperly aligned within the available vertical space.
Text
Gets or sets the text content displayed by this primitive.
Declaration
public string Text { get; set; }Property Value
A string containing the text to display. Returns an empty string if the value is null.
Implements
Remarks
The text property supports various formatting features including mnemonics (ampersand characters), HTML rendering capabilities, and automatic layout adjustments based on the available space.
Setting this property automatically triggers layout invalidation and may enable HTML rendering if the text contains HTML markup and HTML rendering is not explicitly disabled.
TextAlignment
Gets or sets the text alignment within the primitive's bounds.
Declaration
public ContentAlignment TextAlignment { get; set; }Property Value
A ContentAlignment value that specifies how text is aligned within the available space. The default value is MiddleLeft.
Implements
Remarks
This property controls both horizontal and vertical text alignment. Common values include TopLeft, MiddleCenter, and BottomRight among others, providing flexible text positioning within the primitive's layout bounds.
TextOrientation
Gets or sets the text orientation for rendering.
Declaration
public Orientation TextOrientation { get; set; }Property Value
An Orientation value that specifies whether text is rendered horizontally or vertically. The default value is Horizontal.
Implements
Remarks
When set to Vertical, the text is rotated 90 degrees counterclockwise. This property is useful for creating vertical labels, headers, or other UI elements that require rotated text display.
TextRenderingHint
Gets or sets the text rendering hint that controls the quality and appearance of text rendering.
Declaration
public virtual TextRenderingHint TextRenderingHint { get; set; }Property Value
A TextRenderingHint value that specifies the text rendering quality. The default value is SystemDefault.
Remarks
This property determines the quality of text rendering, affecting anti-aliasing, hinting, and overall text appearance. Use AntiAlias for smooth text rendering or ClearTypeGridFit for optimal LCD display quality.
TextWrap
Gets or sets a value indicating whether the text should wrapped to the available layout rectangle.
Declaration
public bool TextWrap { get; set; }Property Value
true if the text should wrapped to the available layout rectangle otherwise, false.
Implements
UseMnemonic
Gets or sets a value indicating whether the control interprets an ampersand character (&) in the control's Text property to be an access key prefix character.
Declaration
public bool UseMnemonic { get; set; }Property Value
true if the label doesn't display the ampersand character and underlines the character after the ampersand in its displayed text and treats the underlined character as an access key; otherwise, false if the ampersand character is displayed in the text of the control. The default is true.
Implements
Methods
ArrangeCore(RectangleF)
Performs the core arrangement logic for the element within the specified final rectangle.
Declaration
protected override void ArrangeCore(RectangleF finalRect)Parameters
finalRect
The final rectangular area allocated for this element.
Overrides
ArrangeOverride(SizeF)
Arranges the RadElement to its final location. The element must call the Arrange method of each of its children.
Declaration
protected override SizeF ArrangeOverride(SizeF finalSize)Parameters
finalSize
The size that is available for element.
Returns
The rectangle occupied by the element. Usually finalSize. Should you return different size, the Layout system will restart measuring and rearranging the items. That could lead to infinite recursion.
Overrides
Remarks
In this method call to the Arrange method of each child must be made.
GetStylablePropertiesFilter()
Gets the IFilter instance that may be used to filter the properties, treated as Stylable for this element.
Declaration
public override Filter GetStylablePropertiesFilter()Returns
Overrides
GetTextSize(SizeF, TextParams)
Declaration
public SizeF GetTextSize(SizeF proposedSize, TextParams textParams)Parameters
proposedSize
textParams
Returns
Implements
GetTextSize(TextParams)
Declaration
public SizeF GetTextSize(TextParams textParams)Parameters
textParams
Returns
Implements
InitializeFields()
Initializes member fields to their default values. This method is called prior the CreateChildItems one and allows for initialization of members on which child elements depend.
Declaration
protected override void InitializeFields()Overrides
MeasureOverride(SizeF)
Measures the space required by the RadElement
Used by the layout system.
Declaration
protected override SizeF MeasureOverride(SizeF availableSize)Parameters
availableSize
The size that is available to the RadElement. The available size can be infinity (to take the full size of the element)
Returns
The minimum size required by the element to be completely visible. Cannot be infinity.
Overrides
Remarks
In this method call to the Measure method of each child must be made.
MeasureOverride(SizeF, TextParams)
Declaration
public SizeF MeasureOverride(SizeF availableSize, TextParams textParams)Parameters
availableSize
textParams
Returns
Implements
OnMouseMove(MouseEventArgs)
Declaration
protected override void OnMouseMove(MouseEventArgs e)Parameters
e
Overrides
OnMouseMove(object, MouseEventArgs)
Declaration
public void OnMouseMove(object sender, MouseEventArgs e)Parameters
sender
e
Implements
OnPropertyChanged(RadPropertyChangedEventArgs)
Called when a property value has changed, allowing for custom response to property changes.
Declaration
protected override void OnPropertyChanged(RadPropertyChangedEventArgs e)Parameters
e
The property changed event arguments.
Overrides
PaintPrimitive(IGraphics, TextParams)
Declaration
public void PaintPrimitive(IGraphics graphics, TextParams textParams)Parameters
graphics
textParams
Implements
PaintPrimitive(IGraphics, float, SizeF)
Draws the primitive on the screen.
PaintPrimitive(IGraphics, float, SizeF, TextParams)
Declaration
public void PaintPrimitive(IGraphics graphics, float angle, SizeF scale, TextParams textParams)Parameters
graphics
angle
scale
textParams
Implements
ToString()
Returns the text as a string.