New to Telerik UI for WinForms? Start a free 30-day trial

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:

C#
public class TextPrimitive : BasePrimitive, IDisposable, INotifyPropertyChanged, ICustomTypeDescriptor, ISupportSystemSkin, IStylableNode, IPrimitive, ITextProvider, ITextPrimitive

Inheritance: objectDisposableObjectRadObjectRadElementVisualElementBasePrimitiveTextPrimitive...

Derived Classes: TitleBarTextPrimitive

Implements: ICustomTypeDescriptorIDisposableINotifyPropertyChangedIPrimitiveIStylableNodeISupportSystemSkinITextPrimitiveITextProvider...

Inherited Members BasePrimitive.BoxCategoryBasePrimitive.PaintElement(IGraphics, float, SizeF)VisualElement.DefaultSizePropertyVisualElement.ForeColorPropertyVisualElement.BackColorPropertyVisualElement.FontPropertyVisualElement.SmoothingModePropertyVisualElement.OpacityPropertyVisualElement.CustomFontPropertyVisualElement.CustomFontSizePropertyVisualElement.CustomFontStylePropertyVisualElement.OnFontChanged(EventArgs)VisualElement.OnPropertyChanging(RadPropertyChangingEventArgs)VisualElement.PaintChildren(IGraphics, Rectangle, float, SizeF, bool)VisualElement.PrePaintElement(IGraphics)VisualElement.PostPaintElement(IGraphics)VisualElement.GetScaledFont(float)VisualElement.GetScaledFont(float, Font)VisualElement.DefaultSizeVisualElement.ForeColorVisualElement.BackColorVisualElement.FontVisualElement.CustomFontVisualElement.CustomFontSizeVisualElement.CustomFontStyleVisualElement.SmoothingModeVisualElement.OpacityVisualElement.FontChangedRadElement.BoundsPropertyRadElement.BorderThicknessPropertyRadElement.PaddingPropertyRadElement.MarginPropertyRadElement.AlignmentPropertyRadElement.AutoSizeModePropertyRadElement.FitToSizeModePropertyRadElement.MinSizePropertyRadElement.EnabledPropertyRadElement.CanFocusPropertyRadElement.IsItemFocusedPropertyRadElement.IsFocusedPropertyRadElement.IsMouseOverPropertyRadElement.IsMouseOverElementPropertyRadElement.IsMouseDownPropertyRadElement.ShouldPaintPropertyRadElement.VisibilityPropertyRadElement.NamePropertyRadElement.ClassPropertyRadElement.ClipDrawingPropertyRadElement.ShapePropertyRadElement.MouseClickedEventRadElement.MouseDoubleClickedEventRadElement.MouseDownEventRadElement.MouseUpEventRadElement.MouseWheelEventRadElement.ChildElementAddedEventRadElement.ParentChangedEventRadElement.BoundsChangedEventRadElement.VisibilityChangingEventRadElement.EnabledChangedEventRadElement.ControlChangedEventRadElement.BackgroundShapePropertyRadElement.BackgroundShapePaintModePropertyRadElement.ContainsFocusPropertyRadElement.ContainsMousePropertyRadElement.MaxSizePropertyRadElement.RightToLeftPropertyRadElement.AutoSizePropertyRadElement.ZIndexPropertyRadElement.AngleTransformPropertyRadElement.ScaleTransformPropertyRadElement.PositionOffsetPropertyRadElement.TagPropertyRadElement.StretchHorizontallyPropertyRadElement.StretchVerticallyPropertyRadElement.UseCompatibleTextRenderingPropertyRadElement.ClickModePropertyRadElement.styleVersionRadElement.paintSystemSkinRadElement.SetPropertyValueCommandRadElement.GetPropertyValueCommandRadElement.StylePropertyRadElement.CallCreateChildElements()RadElement.SuspendReferenceUpdate()RadElement.ResumeReferenceUpdate()RadElement.CreateChildElements()RadElement.OnLoad(bool)RadElement.LoadCore()RadElement.OnLoaded()RadElement.OnUnload(ComponentThemableElementTree, bool)RadElement.UnloadCore(ComponentThemableElementTree)RadElement.OnUnloaded(ComponentThemableElementTree)RadElement.OnElementTreeChanged(ComponentThemableElementTree)RadElement.OnBeginDispose()RadElement.SetParent(RadElement)RadElement.OnParentChanged(RadElement)RadElement.UpdateReferences(ComponentThemableElementTree, bool, bool)RadElement.ResetLayout(bool)RadElement.HasInvisibleAncestor()RadElement.ResetLayoutCore()RadElement.InvalidateArrange()RadElement.InvalidateArrange(bool)RadElement.InvalidateMeasure()RadElement.InvalidateMeasure(bool)RadElement.UpdateLayout()RadElement.SuspendLayout()RadElement.SuspendLayout(bool)RadElement.ResumeLayout(bool)RadElement.ResumeLayout(bool, bool)RadElement.Arrange(RectangleF)RadElement.Measure(SizeF)RadElement.SetBounds(Rectangle)RadElement.SetBounds(int, int, int, int)RadElement.GetBoundingRectangle(Size)RadElement.GetBoundingRectangle(Rectangle)RadElement.GetDesiredSize(bool)RadElement.PointToScreen(Point)RadElement.PointFromScreen(Point)RadElement.PointToControl(Point)RadElement.PointFromControl(Point)RadElement.LocationToControl()RadElement.RectangleToScreen(Rectangle)RadElement.HitTest(Point)RadElement.OnRenderSizeChanged(SizeChangedInfo)RadElement.OnChildDesiredSizeChanged(RadElement)RadElement.OnLayoutPropertyChanged(RadPropertyChangedEventArgs)RadElement.MeasureCore(SizeF)RadElement.ShouldArrangeChild(RadElement)RadElement.ShouldMeasureChild(RadElement)RadElement.MeasureChildren(SizeF)RadElement.GetArrangeRect(RectangleF)RadElement.CanExecuteLayoutOperation()RadElement.CalcLayoutOffset(PointF)RadElement.LockBounds()RadElement.UnlockBounds()RadElement.SetBoundsCore(Rectangle)RadElement.IsInValidState(bool)RadElement.Invalidate()RadElement.Invalidate(bool)RadElement.GetInvalidateBounds()RadElement.NotifyInvalidate(RadElement)RadElement.OnTransformationInvalidated()RadElement.PerformLayoutTransformation(ref RadMatrix)RadElement.PerformPaintTransformation(ref RadMatrix)RadElement.IsInGetAsBitmap()RadElement.PaintElementSkin(IGraphics)RadElement.PaintOverride(IGraphics, Rectangle, float, SizeF, bool)RadElement.PaintBackgroundShape(IGraphics)RadElement.PostPaintChildren(IGraphics, Rectangle, float, SizeF)RadElement.PaintChild(RadElement, IGraphics, Rectangle, float, SizeF, bool)RadElement.PaintShadow(RadElement, IGraphics)RadElement.PaintShadowCore(Graphics, Rectangle, RadItem)RadElement.GetShadowRect(ref Rectangle, int)RadElement.PaintFocusCues(IGraphics, Rectangle)RadElement.GetAsBitmap(IGraphics, Brush, float, SizeF)RadElement.GetAsTransformedBitmap(IGraphics, Brush, float, SizeF)RadElement.GetAsTransformedBitmap(Brush, float, SizeF)RadElement.GetAsTransformedBitmap(Rectangle, Brush, float, SizeF)RadElement.GetAsBitmapEx(Color, float, SizeF)RadElement.GetAsBitmapEx(Brush, float, SizeF)RadElement.GetAsBitmap(Brush, float, SizeF)RadElement.IsInVisibleClipBounds(Rectangle)RadElement.SetClipping(Graphics)RadElement.GetClipRect()RadElement.ShouldPaintChild(RadElement)RadElement.GetFocusRect()RadElement.GetCurrentShape()RadElement.GetPaintRectangle(float, float, SizeF)RadElement.GetPatchedRect(RectangleF, float, SizeF)RadElement.GetXPVisualStyle()RadElement.GetVistaVisualStyle()RadElement.InitializeSystemSkinPaint()RadElement.UnitializeSystemSkinPaint()RadElement.GetSystemSkinPaintBounds()RadElement.OnUseSystemSkinChanged(EventArgs)RadElement.ShouldPaintSystemSkin()RadElement.ComposeShouldPaintSystemSkin()RadElement.ResetStyleSettings(bool)RadElement.ResetStyleSettings(bool, RadProperty)RadElement.ProcessBehaviors(RadPropertyChangedEventArgs)RadElement.AddBehavior(PropertyChangeBehavior)RadElement.GetBehaviors()RadElement.RemoveBehavior(PropertyChangeBehavior)RadElement.ClearBehaviors()RadElement.AddRangeBehavior(PropertyChangeBehaviorCollection)RadElement.SetThemeApplied(bool)RadElement.OnStyleChanged(RadPropertyChangedEventArgs)RadElement.UnapplyStyle()RadElement.RemoveRangeBehaviors(PropertyChangeBehaviorCollection)RadElement.RemoveBehaviors(PropertyChangeBehavior)RadElement.RemoveRangeRoutedEventBehaviors(RoutedEventBehaviorCollection)RadElement.GetThemeEffectiveType()RadElement.GetChildrenByType(Type)RadElement.GetChildrenByBaseType(Type)RadElement.FindAncestorByThemeEffectiveType(Type)RadElement.FindAncestor<T>()RadElement.IsAncestorOf(RadElement)RadElement.FindDescendant<T>()RadElement.FindDescendant(Predicate<RadElement>)RadElement.FindDescendant(Type)RadElement.EnumDescendants(TreeTraversalMode)RadElement.EnumDescendants(Predicate<RadElement>, TreeTraversalMode)RadElement.EnumDescendants(Filter, TreeTraversalMode)RadElement.GetDescendants(Predicate<RadElement>, TreeTraversalMode)RadElement.GetDescendants(Filter, TreeTraversalMode)RadElement.GetAncestors(Filter)RadElement.GetAncestors(Predicate<RadElement>)RadElement.RaiseRoutedEvent(RadElement, RoutedEventArgs)RadElement.RaiseTunnelEvent(RadElement, RoutedEventArgs)RadElement.RaiseBubbleEvent(RadElement, RoutedEventArgs)RadElement.OnTunnelEvent(RadElement, RoutedEventArgs)RadElement.OnBubbleEvent(RadElement, RoutedEventArgs)RadElement.IsEventInProcess(RaisedRoutedEvent)RadElement.RegisterRoutedEvent(string, Type)RadElement.GetRegisterRoutedEvent(string, Type)RadElement.GetRegisterRoutedEvent(string, string)RadElement.GetRegisterRoutedEvent(string)RadElement.OnChildrenChanged(RadElement, ItemsChangeOperation)RadElement.GetChildren(ChildrenListOptions)RadElement.SendToBack()RadElement.BringToFront()RadElement.IsChildOf(RadElement)RadElement.Focus()RadElement.Focus(bool)RadElement.SetFocusPropertySafe(bool)RadElement.KillFocus()RadElement.OnCLREventsRise(RoutedEventArgs)RadElement.OnMouseHover(EventArgs)RadElement.OnEnabledChanged(RadPropertyChangedEventArgs)RadElement.OnParentEnabledChanged(RadPropertyChangedEventArgs)RadElement.OnMouseDown(MouseEventArgs)RadElement.OnMouseUp(MouseEventArgs)RadElement.OnLostMouseCapture(MouseEventArgs)RadElement.OnClick(EventArgs)RadElement.OnDoubleClick(EventArgs)RadElement.OnMouseEnter(EventArgs)RadElement.OnMouseLeave(EventArgs)RadElement.PerformClick()RadElement.OnMouseWheel(MouseEventArgs)RadElement.DoMouseWheel(MouseEventArgs)RadElement.DoClick(EventArgs)RadElement.DoDoubleClick(EventArgs)RadElement.IsInputKey(InputKeyEventArgs)RadElement.MouseEventArgsFromControl(MouseEventArgs)RadElement.DoMouseDown(MouseEventArgs)RadElement.DoMouseUp(MouseEventArgs)RadElement.DoMouseMove(MouseEventArgs)RadElement.ShowScreenTip(ScreenTipNeededEventArgs)RadElement.HideScreenTip()RadElement.DoMouseHover(EventArgs)RadElement.OnShowScreenTip(ComponentInputBehavior)RadElement.RaiseClick(EventArgs)RadElement.RaiseDoubleClick(EventArgs)RadElement.RaiseMouseWheel(MouseEventArgs)RadElement.UpdateContainsFocus(bool)RadElement.DoMouseEnter(EventArgs)RadElement.DoMouseLeave(EventArgs)RadElement.GetValue(RadProperty)RadElement.AddStylePropertySetting(IPropertySetting)RadElement.SetValueCore(RadPropertyValue, object, object, ValueSource)RadElement.NotifyChildren(RadPropertyChangedEventArgs)RadElement.OnBoundsChanged(RadPropertyChangedEventArgs)RadElement.OnLocationChanged(RadPropertyChangedEventArgs)RadElement.OnDisplayPropertyChanged(RadPropertyChangedEventArgs)RadElement.CanRaisePropertyChangeNotifications(RadPropertyValue)RadElement.IsPropertyCancelable(RadPropertyMetadata)RadElement.OnParentPropertyChanged(RadPropertyChangedEventArgs)RadElement.ReplaceDefaultDescriptors(PropertyDescriptorCollection)RadElement.DisposeManagedResources()RadElement.PerformDispose(bool)RadElement.DisposeChildren()RadElement.GetStylableChildrenHierarchy()RadElement.GetStylableChildren()RadElement.GetClientRectangle(SizeF)RadElement.GetBorderThickness(BorderPrimitive)RadElement.DpiScaleChanged(SizeF)RadElement.ElementStateRadElement.DesiredSizeRadElement.IsLayoutSuspendedRadElement.BoundingRectangleRadElement.ControlBoundingRectangleRadElement.BypassLayoutPoliciesRadElement.IsArrangeValidRadElement.IsMeasureValidRadElement.TreeLevelRadElement.TransformRadElement.TotalTransformRadElement.ShouldPaintUsingParentShapeRadElement.UseSystemSkinRadElement.CanHaveOwnStyleRadElement.PropagateStyleToChildrenRadElement.ThemeEffectiveTypeRadElement.ElementTreeRadElement.ChildrenRadElement.ChildrenHierarchyRadElement.ParentRadElement.RoutedEventBehaviorsRadElement.LayoutableChildrenCountRadElement.ContainsFocusRadElement.ShouldHandleMouseInputRadElement.NotifyParentOnMouseInputRadElement.IsAbleToRespondToMouseEventsRadElement.AutoSizeRadElement.BoundsRadElement.LocationRadElement.SizeRadElement.BorderThicknessRadElement.PaddingRadElement.MarginRadElement.AlignmentRadElement.AutoSizeModeRadElement.FitToSizeModeRadElement.EnabledRadElement.CanFocusRadElement.IsFocusedRadElement.IsMouseOverRadElement.IsMouseOverElementRadElement.IsMouseDownRadElement.InvalidateChildrenOnChildChangedRadElement.ShouldPaintRadElement.VisibilityRadElement.IsElementVisibleRadElement.NameRadElement.ClassRadElement.ClipDrawingRadElement.ShapeRadElement.MinSizeRadElement.MaxSizeRadElement.ZIndexRadElement.RightToLeftRadElement.UseCompatibleTextRenderingRadElement.BackgroundShapeRadElement.BackgroundShapePaintModeRadElement.ContainsMouseRadElement.CaptureRadElement.ScaleTransformRadElement.AngleTransformRadElement.PositionOffsetRadElement.SerializePropertiesRadElement.SerializeElementRadElement.SerializeChildrenRadElement.RenderingMaxFramerateRadElement.IsThemeAppliedRadElement.ShouldApplyThemeRadElement.UseCenteredAngleTransformRadElement.TagRadElement.ClickModeRadElement.DoubleClickEnabledRadElement.CaptureOnMouseDownRadElement.IsItemHoveredRadElement.StyleRadElement.ToolTipTextRadElement.AutoToolTipRadElement.ScreenTipRadElement.AutoNumberKeyTipRadElement.DpiScaleFactorRadElement.LayoutUpdatedRadElement.MouseHoverRadElement.MouseMoveRadElement.MouseDownRadElement.MouseUpRadElement.ClickRadElement.DoubleClickRadElement.MouseEnterRadElement.MouseWheelRadElement.EnabledChangedRadElement.MouseLeaveRadElement.ChildrenChangedRadElement.LostMouseCaptureRadObject.BindingContextPropertyRadObject.RadTypeRadObject.ClearPropertyStore()RadObject.SuspendPropertyNotifications()RadObject.ResumePropertyNotifications()RadObject.GetPropertyValue(RadProperty)RadObject.SetDefaultValueOverride(RadProperty, object)RadObject.SetValue(RadProperty, object)RadObject.ResetValue(RadProperty)RadObject.ResetLocalValue(RadProperty)RadObject.ResetValue(RadProperty, ValueResetFlags)RadObject.UpdateValue(RadProperty)RadObject.GetValueSource(RadProperty)RadObject.GetRegisteredRadProperty(string)RadObject.UpdateValueCore(RadPropertyValue)RadObject.ResetValueCore(RadPropertyValue, ValueResetFlags)RadObject.GetDefaultValue(RadPropertyValue, object)RadObject.CoerceValue(RadPropertyValue, object)RadObject.ShouldSerializeProperty(RadProperty)RadObject.BindProperty(RadProperty, RadObject, RadProperty, PropertyBindingOptions)RadObject.UnbindProperty(RadProperty)RadObject.GetInheritedValue(RadProperty)RadObject.OnNotifyPropertyChanged(string)RadObject.OnNotifyPropertyChanged(PropertyChangedEventArgs)RadObject.OnShouldSerializeProperty(ShouldSerializePropertyEventArgs)RadObject.PropertyValuesRadObject.PropertyFilterRadObject.RadObjectTypeRadObject.BindingContextRadObject.PropertyChangedRadObject.RadPropertyChangedRadObject.RadPropertyChangingDisposableObject.GetBitState(long)DisposableObject.SetBitState(long, bool)DisposableObject.OnBitStateChanged(long, bool, bool)DisposableObject.Dispose()DisposableObject.Dispose(bool)DisposableObject.DisposeUnmanagedResources()DisposableObject.BitStateDisposableObject.EventsDisposableObject.IsDisposingDisposableObject.IsDisposedDisposableObject.DisposedDisposableObject.Disposing...

Constructors

C#
public TextPrimitive()

Fields

Identifies whether overflowing text is truncated with an end ellipsis; the default is true.

C#
public static RadProperty AutoEllipsisProperty

Identifies the inheritable text-rendering hint used while disabled; the default is AntiAliasGridFit.

C#
public static RadProperty DisabledTextRenderingHintProperty

Identifies the inherited text-flip property, which defaults to false.

C#
public static RadProperty FlipTextProperty

Identifies whether rendering is limited to the lines that fit in the layout bounds; the default is false.

C#
public static RadProperty LineLimitProperty

Identifies whether the compatible-text-rendering path includes trailing spaces in measurement; the default is true.

C#
public static RadProperty MeasureTrailingSpacesProperty

Identifies the optional text-shadow settings; changes affect display without invalidating measurement.

C#
public static RadProperty ShadowProperty

Identifies whether mnemonic keyboard cues are shown; the default is true.

C#
public static RadProperty ShowKeyboardCuesProperty

Identifies the alignment of text within the primitive's bounds; the default is MiddleLeft.

C#
public static RadProperty TextAlignmentProperty

Identifies the inherited text-orientation property, which defaults to horizontal and affects measurement and layout.

C#
public static RadProperty TextOrientationProperty

Identifies the text content property; changes invalidate text and parent layout measurement, arrangement, and display.

C#
public static RadProperty TextProperty

Identifies the inheritable text-rendering hint; the default is SystemDefault.

C#
public static RadProperty TextRenderingHintProperty

Identifies whether text wraps to the available layout size; the default is false.

C#
public static RadProperty TextWrapProperty

Identifies whether ampersands introduce access-key mnemonics instead of being displayed literally; the default is true.

C#
public static RadProperty UseMnemonicProperty

Properties

Gets or sets a value indicating whether the additional label text is to be indicated by an ellipsis.

C#
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: ITextProvider.AutoEllipsis

C#
[Browsable(false)]
public Color CachedForeColor { get; set; }

Gets or sets the text rendering hint used when this primitive is disabled.

C#
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.

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.

C#
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.

C#
public bool FlipText { get; set; }
Property Value:

true if the text should be flipped; otherwise, false. The default value is false.

Implements: ITextProvider.FlipText

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.

C#
public override bool IsEmpty { get; }
Property Value:

true if the Text property is null or empty; otherwise, false.

Overrides: BasePrimitive.IsEmpty

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.

C#
public bool LineLimit { get; set; }
Property Value:

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.

C#
public bool MeasureTrailingSpaces { get; set; }
Property Value:

true to include trailing spaces in text measurement; otherwise, false. The default value is true.

Implements: ITextProvider.MeasureTrailingSpaces

With compatible text rendering enabled, this setting controls whether Graphics.MeasureString includes 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.

C#
[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: ITextProvider.Shadow

Gets or sets a value indicating whether if the keyboard accelerators are visible.

C#
public bool ShowKeyboardCues { get; set; }
Property Value:

true if if the keyboard accelerators are visible otherwise, false.

Implements: ITextProvider.ShowKeyboardCues

Gets or sets a value indicating whether this primitive stretches horizontally within its parent layout.

C#
public override bool StretchHorizontally { get; set; }
Property Value:

true if the primitive should stretch horizontally; otherwise, false. The default value is false.

Overrides: RadElement.StretchHorizontally

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.

C#
public override bool StretchVertically { get; set; }
Property Value:

true if the primitive should stretch vertically; otherwise, false. The default value is false.

Overrides: RadElement.StretchVertically

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.

C#
public string Text { get; set; }
Property Value:

A string containing the text to display. Returns an empty string if the value is null.

Implements: ITextProvider.Text

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.

C#
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: ITextProvider.TextAlignment

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.

C#
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: ITextProvider.TextOrientation

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.

C#
public virtual TextRenderingHint TextRenderingHint { get; set; }
Property Value:

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.

C#
public bool TextWrap { get; set; }
Property Value:

true if the text should wrapped to the available layout rectangle otherwise, false.

Implements: ITextProvider.TextWrap

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.

C#
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: ITextProvider.UseMnemonic

Methods

Gets whether the current text is recognized as HTML and HTML rendering has not been disabled.

C#
public bool AllowHTMLRendering()
Returns:

bool

Saves the requested final size before the base class arranges the text primitive.

C#
protected override void ArrangeCore(RectangleF finalRect)
Parameters:finalRectRectangleF

The final bounds assigned by the layout system.

Overrides: RadElement.ArrangeCore(RectangleF)

Applies line limiting when wrapped text with automatic ellipsis is arranged at a different size.

C#
protected override SizeF ArrangeOverride(SizeF finalSize)
Parameters:finalSizeSizeF

The size assigned by the layout system.

Returns:

SizeF

The size used to arrange the text primitive.

Overrides: RadElement.ArrangeOverride(SizeF)

Creates a StringFormat from the primitive's current text settings.

C#
public StringFormat CreateStringFormat()
Returns:

StringFormat

The caller owns the returned object and should dispose it when finished.

Creates the rendering parameters from the primitive's current text properties.

C#
protected virtual TextParams CreateTextParams()
Returns:

TextParams

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.

C#
public RectangleF GetFaceRectangle()
Returns:

RectangleF

The rectangle available for the primitive's content.

Implements: ITextProvider.GetFaceRectangle()

Gets the property filter used to limit theme styling to text, appearance, and behavior properties.

C#
public override Filter GetStylablePropertiesFilter()
Returns:

Filter

Overrides: RadElement.GetStylablePropertiesFilter()

Measures the current text without a caller-specified size constraint.

C#
public SizeF GetTextSize()
Returns:

SizeF

The measured text size from the active renderer.

Measures text using the supplied proposed size as a constraint.

C#
public SizeF GetTextSize(SizeF proposedSize, TextParams textParams)
Parameters:proposedSizeSizeF

The size available for measuring the text.

textParamsTextParams

The text content and settings that affect measurement.

Returns:

SizeF

The measured size of the text.

Implements: ITextPrimitive.GetTextSize(SizeF, TextParams)

Measures the current text using the proposed size as a constraint.

C#
public SizeF GetTextSize(SizeF proposedSize)
Parameters:proposedSizeSizeF

The available size used by the active text renderer.

Returns:

SizeF

The measured text size.

Measures the text without a caller-specified size constraint.

C#
public SizeF GetTextSize(TextParams textParams)
Parameters:textParamsTextParams

The text content and settings that affect measurement.

Returns:

SizeF

The measured size of the text.

Implements: ITextPrimitive.GetTextSize(TextParams)

Initializes the primitive with no stretching and the plain-text renderer.

C#
protected override void InitializeFields()

Overrides: BasePrimitive.InitializeFields()

Measures the desired text size within the available layout size.

C#
public SizeF MeasureOverride(SizeF availableSize, TextParams textParams)
Parameters:availableSizeSizeF

The maximum size available to the text.

textParamsTextParams

The text content and settings that affect measurement.

Returns:

SizeF

The desired size of the rendered text.

Implements: ITextPrimitive.MeasureOverride(SizeF, TextParams)

Measures child elements and then asks the active text renderer for this primitive's desired size.

C#
protected override SizeF MeasureOverride(SizeF availableSize)
Parameters:availableSizeSizeF

The size available to the primitive.

Returns:

SizeF

The desired size returned by the active text renderer.

Overrides: RadElement.MeasureOverride(SizeF)

Forwards pointer movement to the active renderer after the base element processes it.

C#
protected override void OnMouseMove(MouseEventArgs e)
Parameters:eMouseEventArgs

The mouse-event data.

Overrides: RadElement.OnMouseMove(MouseEventArgs)

Notifies the backend of pointer movement so it can update text-specific interaction state.

C#
public void OnMouseMove(object sender, MouseEventArgs e)
Parameters:senderobject

The object associated with the pointer event.

eMouseEventArgs

The pointer coordinates and other mouse-event data.

Implements: ITextPrimitive.OnMouseMove(object, MouseEventArgs)

Updates text-rendering mode and alignment when relevant properties change.

C#
protected override void OnPropertyChanged(RadPropertyChangedEventArgs e)
Parameters:eRadPropertyChangedEventArgs

The changed property and its old and new values.

Overrides: VisualElement.OnPropertyChanged(RadPropertyChangedEventArgs)

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.

C#
public void PaintPrimitive(IGraphics graphics, float angle, SizeF scale, TextParams textParams)
Parameters:graphicsIGraphics

The graphics context used to draw the text.

anglefloat

The rotation angle supplied for the paint operation.

scaleSizeF

The scale supplied for the paint operation.

textParamsTextParams

The text content, layout, and rendering settings.

Implements: ITextPrimitive.PaintPrimitive(IGraphics, float, SizeF, TextParams)

Draws the primitive on the screen.

C#
public override void PaintPrimitive(IGraphics graphics, float angle, SizeF scale)
Parameters:graphicsIGraphicsanglefloatscaleSizeF

Overrides: BasePrimitive.PaintPrimitive(IGraphics, float, SizeF)

Paints text using the supplied text parameters without an explicit transform.

C#
public void PaintPrimitive(IGraphics graphics, TextParams textParams)
Parameters:graphicsIGraphics

The graphics context used to draw the text.

textParamsTextParams

The text content, layout, and rendering settings.

Implements: ITextPrimitive.PaintPrimitive(IGraphics, TextParams)

Updates the active text renderer to match whether the supplied string is recognized as HTML.

C#
public void ToggleHTML(string text)
Parameters:textstring

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.

C#
public override string ToString()
Returns:

string

Overrides: RadElement.ToString()