TextPrimitive
Represents a primitive element that renders text content with advanced formatting, layout, and styling capabilities.
TextPrimitive is the primary text rendering component in the Telerik WinControls framework, providing comprehensive text display functionality including word wrapping, text alignment, mnemonics, ellipsis, orientation control, and multiple rendering hints.
The primitive supports various text formatting options such as HTML rendering, shadow effects, keyboard cues, and both horizontal and vertical text orientation. It automatically handles text measurement and layout based on available space and configured properties.
TextPrimitive is widely used throughout Telerik controls for displaying labels, captions, button text, menu items, and other textual content with consistent styling and behavior.
Definition
Namespace:Telerik.WinControls.Primitives
Assembly:Telerik.WinControls.dll
Syntax:
public class TextPrimitive : BasePrimitive, IDisposable, INotifyPropertyChanged, ICustomTypeDescriptor, ISupportSystemSkin, IStylableNode, IPrimitive, ITextProvider, ITextPrimitive
Inheritance: objectDisposableObjectRadObjectRadElementVisualElementBasePrimitiveTextPrimitive...
Derived Classes:
Implements:
Inherited Members
Constructors
public TextPrimitive()
Fields
Identifies whether overflowing text is truncated with an end ellipsis; the default is true.
public static RadProperty AutoEllipsisProperty
Identifies the inheritable text-rendering hint used while disabled; the default is AntiAliasGridFit.
public static RadProperty DisabledTextRenderingHintProperty
Identifies the inherited text-flip property, which defaults to false.
public static RadProperty FlipTextProperty
Identifies whether rendering is limited to the lines that fit in the layout bounds; the default is false.
public static RadProperty LineLimitProperty
Identifies whether the compatible-text-rendering path includes trailing spaces in measurement; the default is true.
public static RadProperty MeasureTrailingSpacesProperty
Identifies the optional text-shadow settings; changes affect display without invalidating measurement.
public static RadProperty ShadowProperty
Identifies whether mnemonic keyboard cues are shown; the default is true.
public static RadProperty ShowKeyboardCuesProperty
Identifies the alignment of text within the primitive's bounds; the default is MiddleLeft.
public static RadProperty TextAlignmentProperty
Identifies the inherited text-orientation property, which defaults to horizontal and affects measurement and layout.
public static RadProperty TextOrientationProperty
Identifies the text content property; changes invalidate text and parent layout measurement, arrangement, and display.
public static RadProperty TextProperty
Identifies the inheritable text-rendering hint; the default is SystemDefault.
public static RadProperty TextRenderingHintProperty
Identifies whether text wraps to the available layout size; the default is false.
public static RadProperty TextWrapProperty
Identifies whether ampersands introduce access-key mnemonics instead of being displayed literally; the default is true.
public static RadProperty UseMnemonicProperty
Properties
Gets or sets a value indicating whether the additional label text is to be indicated by an ellipsis.
public bool AutoEllipsis { get; set; }
true if the additional label text is to be indicated by an ellipsis otherwise, false. Default value is true.
Implements:
[Browsable(false)]
public Color CachedForeColor { get; set; }
Gets or sets the text rendering hint used when this primitive is disabled.
public virtual TextRenderingHint DisabledTextRenderingHint { get; set; }
A TextRenderingHint value that specifies the text rendering quality for disabled state. The default value is AntiAliasGridFit.
This property allows for different text rendering quality when the primitive is disabled, often providing a softer appearance that visually indicates the disabled state.
Gets or sets whether markup-like text is rendered literally instead of using the HTML renderer.
public bool DisableHTMLRendering { get; set; }
Changing this property selects a renderer for the current text.
Gets or sets a value indicating whether the text should be flipped (mirrored) during rendering.
public bool FlipText { get; set; }
true if the text should be flipped; otherwise, false. The default value is false.
Implements:
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.
Gets a value indicating whether this primitive contains any displayable content.
public override bool IsEmpty { get; }
true if the Text property is null or empty; otherwise, false.
Overrides:
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.
Gets or sets a value indicating whether text rendering is limited to a specific number of lines.
public bool LineLimit { get; set; }
true if line limiting is enabled; otherwise, false.
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.
Gets or sets a value indicating whether trailing spaces at the end of each line are included in text measurement calculations.
public bool MeasureTrailingSpaces { get; set; }
true to include trailing spaces in text measurement; otherwise, false.
The default value is true.
Implements:
With compatible text rendering enabled, this setting controls whether
Graphics.MeasureStringincludes trailing spaces at the end of each line. The default value, true, includes them. The TextRenderer and HTML-rendering paths do not use this setting.This property is particularly useful when working with text that needs to maintain exact spacing or when implementing custom text layout algorithms.
Gets or sets the shadow settings.
[TypeConverter("Telerik.WinControls.UI.Design.ShadowSettingsConverter, Telerik.WinControls.UI.Design, Version=2026.3.1026.48, Culture=neutral, PublicKeyToken=5bb2a467cbec794e")]
public ShadowSettings Shadow { get; set; }
Implements:
Gets or sets a value indicating whether if the keyboard accelerators are visible.
public bool ShowKeyboardCues { get; set; }
true if if the keyboard accelerators are visible otherwise, false.
Implements:
Gets or sets a value indicating whether this primitive stretches horizontally within its parent layout.
public override bool StretchHorizontally { get; set; }
true if the primitive should stretch horizontally; otherwise, false.
The default value is false.
Overrides:
For text primitives, horizontal stretching is typically disabled to maintain text layout integrity and prevent unwanted text spacing or alignment issues.
Gets or sets a value indicating whether this primitive stretches vertically within its parent layout.
public override bool StretchVertically { get; set; }
true if the primitive should stretch vertically; otherwise, false.
The default value is false.
Overrides:
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.
Gets or sets the text content displayed by this primitive.
public string Text { get; set; }
A string containing the text to display. Returns an empty string if the value is null.
Implements:
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.
Gets or sets the text alignment within the primitive's bounds.
public ContentAlignment TextAlignment { get; set; }
A ContentAlignment value that specifies how text is aligned within the available space. The default value is MiddleLeft.
Implements:
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.
Gets or sets the text orientation for rendering.
public Orientation TextOrientation { get; set; }
An Orientation value that specifies whether text is rendered horizontally or vertically. The default value is Horizontal.
Implements:
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.
Gets or sets the text rendering hint that controls the quality and appearance of text rendering.
public virtual TextRenderingHint TextRenderingHint { get; set; }
A TextRenderingHint value that specifies the text rendering quality. The default value is SystemDefault.
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.
Gets or sets a value indicating whether the text should wrapped to the available layout rectangle.
public bool TextWrap { get; set; }
true if the text should wrapped to the available layout rectangle otherwise, false.
Implements:
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.
public bool UseMnemonic { get; set; }
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
Gets whether the current text is recognized as HTML and HTML rendering has not been disabled.
Saves the requested final size before the base class arranges the text primitive.
protected override void ArrangeCore(RectangleF finalRect)
The final bounds assigned by the layout system.
Overrides:
Creates a StringFormat from the primitive's current text settings.
public StringFormat CreateStringFormat()
The caller owns the returned object and should dispose it when finished.
Creates the rendering parameters from the primitive's current text properties.
protected virtual TextParams CreateTextParams()
A snapshot of the settings used to measure and paint the current text.
The generated parameters include a DPI-scaled font and use the disabled-state rendering hint when the primitive is disabled.
Gets the text area inside the primitive's bounds after its padding is removed.
public RectangleF GetFaceRectangle()
The rectangle available for the primitive's content.
Implements:
Gets the property filter used to limit theme styling to text, appearance, and behavior properties.
Measures the current text without a caller-specified size constraint.
Measures text using the supplied proposed size as a constraint.
public SizeF GetTextSize(SizeF proposedSize, TextParams textParams)
The size available for measuring the text.
textParamsTextParamsThe text content and settings that affect measurement.
Returns:The measured size of the text.
Implements:
Measures the text without a caller-specified size constraint.
public SizeF GetTextSize(TextParams textParams)
The text content and settings that affect measurement.
Returns:The measured size of the text.
Implements:
Initializes the primitive with no stretching and the plain-text renderer.
protected override void InitializeFields()
Overrides:
Measures the desired text size within the available layout size.
public SizeF MeasureOverride(SizeF availableSize, TextParams textParams)
The maximum size available to the text.
textParamsTextParamsThe text content and settings that affect measurement.
Returns:The desired size of the rendered text.
Implements:
Measures child elements and then asks the active text renderer for this primitive's desired size.
Forwards pointer movement to the active renderer after the base element processes it.
protected override void OnMouseMove(MouseEventArgs e)
The mouse-event data.
Overrides:
Notifies the backend of pointer movement so it can update text-specific interaction state.
public void OnMouseMove(object sender, MouseEventArgs e)
The object associated with the pointer event.
eMouseEventArgsThe pointer coordinates and other mouse-event data.
Implements:
Updates text-rendering mode and alignment when relevant properties change.
protected override void OnPropertyChanged(RadPropertyChangedEventArgs e)
The changed property and its old and new values.
Overrides:
Text, font, alignment, and foreground-color changes can switch the active HTML renderer. Auto-size mode changes also adjust the text alignment.
Paints text using the supplied graphics context and parameters. The built-in backends do not apply the supplied angle and scale.
public void PaintPrimitive(IGraphics graphics, float angle, SizeF scale, TextParams textParams)
The graphics context used to draw the text.
anglefloatThe rotation angle supplied for the paint operation.
scaleSizeFThe scale supplied for the paint operation.
textParamsTextParamsThe text content, layout, and rendering settings.
Implements:
Paints text using the supplied text parameters without an explicit transform.
public void PaintPrimitive(IGraphics graphics, TextParams textParams)
The graphics context used to draw the text.
textParamsTextParamsThe text content, layout, and rendering settings.
Implements:
Updates the active text renderer to match whether the supplied string is recognized as HTML.
public void ToggleHTML(string text)
The text used to determine the rendering mode.
When HTML rendering is disabled, the recognized mode is recorded but the active renderer is not replaced.
Returns the text as a string.