Class TextPrimitive

Represents a primitive element that renders text content with advanced formatting, layout, and styling capabilities.

Inheritance
System.Object
DisposableObject
RadObject
RadElement
VisualElement
BasePrimitive
TextPrimitive
TitleBarTextPrimitive
Inherited Members
System.Object.Equals(System.Object)
System.Object.Equals(System.Object, System.Object)
System.Object.ReferenceEquals(System.Object, System.Object)
System.Object.GetHashCode()
System.Object.GetType()
System.Object.MemberwiseClone()
Namespace: Telerik.WinControls.Primitives
Assembly: Telerik.WinControls.dll

Syntax

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

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.

Constructors

TextPrimitive()

Declaration
public TextPrimitive()

Fields

AutoEllipsisProperty

Declaration
public static RadProperty AutoEllipsisProperty
Field Value
RadProperty

DisabledTextRenderingHintProperty

Declaration
public static RadProperty DisabledTextRenderingHintProperty
Field Value
RadProperty

FlipTextProperty

Declaration
public static RadProperty FlipTextProperty
Field Value
RadProperty

LineLimitProperty

Declaration
public static RadProperty LineLimitProperty
Field Value
RadProperty

MeasureTrailingSpacesProperty

Declaration
public static RadProperty MeasureTrailingSpacesProperty
Field Value
RadProperty

ShadowProperty

Declaration
public static RadProperty ShadowProperty
Field Value
RadProperty

ShowKeyboardCuesProperty

Declaration
public static RadProperty ShowKeyboardCuesProperty
Field Value
RadProperty

TextAlignmentProperty

Declaration
public static RadProperty TextAlignmentProperty
Field Value
RadProperty

TextOrientationProperty

Declaration
public static RadProperty TextOrientationProperty
Field Value
RadProperty

TextProperty

Declaration
public static RadProperty TextProperty
Field Value
RadProperty

TextRenderingHintProperty

Declaration
public static RadProperty TextRenderingHintProperty
Field Value
RadProperty

TextWrapProperty

Declaration
public static RadProperty TextWrapProperty
Field Value
RadProperty

UseMnemonicProperty

Declaration
public static RadProperty UseMnemonicProperty
Field Value
RadProperty

Properties

AutoEllipsis

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

Declaration
[RadPropertyDefaultValue("AutoEllipsis", typeof(TextPrimitive))]
public bool AutoEllipsis { get; set; }
Property Value
System.Boolean

true if the additional label text is to be indicated by an ellipsis otherwise, false. Default value is true.
Implements

CachedForeColor

Declaration
public Color CachedForeColor { get; set; }
Property Value
System.Drawing.Color

DisabledTextRenderingHint

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

Declaration
[RadPropertyDefaultValue("TextRenderingHint", typeof(VisualElement))]
public virtual TextRenderingHint DisabledTextRenderingHint { get; set; }
Property Value
System.Drawing.Text.TextRenderingHint

A System.Drawing.Text.TextRenderingHint value that specifies the text rendering quality for disabled state. The default value is System.Drawing.Text.TextRenderingHint.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.

DisableHTMLRendering

Declaration
public bool DisableHTMLRendering { get; set; }
Property Value
System.Boolean

FlipText

Gets or sets a value indicating whether the text should be flipped (mirrored) during rendering.

Declaration
[RadPropertyDefaultValue("TextOrientation", typeof(TextPrimitive))]
public bool FlipText { get; set; }
Property Value
System.Boolean

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.

Impl

This property is used internally.

Declaration
public ITextPrimitive Impl { get; }
Property Value
ITextPrimitive

IsEmpty

Gets a value indicating whether this primitive contains any displayable content.

Declaration
public override bool IsEmpty { get; }
Property Value
System.Boolean

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
System.Boolean

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
System.Boolean

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
[RadPropertyDefaultValue("Shadow", typeof(TextPrimitive))]
public ShadowSettings Shadow { get; set; }
Property Value
ShadowSettings

Implements

ShowKeyboardCues

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

Declaration
[RadPropertyDefaultValue("ShowKeyboardCues", typeof(TextPrimitive))]
public bool ShowKeyboardCues { get; set; }
Property Value
System.Boolean

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
System.Boolean

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
System.Boolean

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
[RadPropertyDefaultValue("Text", typeof(TextPrimitive))]
public string Text { get; set; }
Property Value
System.String

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
[RadPropertyDefaultValue("TextAlignment", typeof(TextPrimitive))]
public ContentAlignment TextAlignment { get; set; }
Property Value
System.Drawing.ContentAlignment

A System.Drawing.ContentAlignment value that specifies how text is aligned within the available space. The default value is System.Drawing.ContentAlignment.MiddleLeft.
Implements
Remarks

This property controls both horizontal and vertical text alignment. Common values include System.Drawing.ContentAlignment.TopLeft, System.Drawing.ContentAlignment.MiddleCenter, and System.Drawing.ContentAlignment.BottomRight among others, providing flexible text positioning within the primitive's layout bounds.

TextBlock

Declaration
public virtual FormattedTextBlock TextBlock { get; set; }
Property Value
FormattedTextBlock

TextOrientation

Gets or sets the text orientation for rendering.

Declaration
[RadPropertyDefaultValue("TextOrientation", typeof(TextPrimitive))]
public Orientation TextOrientation { get; set; }
Property Value
System.Windows.Forms.Orientation

An System.Windows.Forms.Orientation value that specifies whether text is rendered horizontally or vertically. The default value is System.Windows.Forms.Orientation.Horizontal.
Implements
Remarks

When set to System.Windows.Forms.Orientation.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.

TextParams

Gets an instance of the TextParams structure which contains information on how to render the text in this element

Declaration
public TextParams TextParams { get; }
Property Value
TextParams

TextRenderingHint

Gets or sets the text rendering hint that controls the quality and appearance of text rendering.

Declaration
[RadPropertyDefaultValue("TextRenderingHint", typeof(VisualElement))]
public virtual TextRenderingHint TextRenderingHint { get; set; }
Property Value
System.Drawing.Text.TextRenderingHint

A System.Drawing.Text.TextRenderingHint value that specifies the text rendering quality. The default value is System.Drawing.Text.TextRenderingHint.SystemDefault.
Remarks

This property determines the quality of text rendering, affecting anti-aliasing, hinting, and overall text appearance. Use System.Drawing.Text.TextRenderingHint.AntiAlias for smooth text rendering or System.Drawing.Text.TextRenderingHint.ClearTypeGridFit for optimal LCD display quality.

TextWrap

Gets or sets a value indicating whether the text should wrapped to the available layout rectangle.

Declaration
[RadPropertyDefaultValue("TextWrap", typeof(TextPrimitive))]
public bool TextWrap { get; set; }
Property Value
System.Boolean

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
[RadPropertyDefaultValue("UseMnemonic", typeof(TextPrimitive))]
public bool UseMnemonic { get; set; }
Property Value
System.Boolean

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

AllowHTMLRendering()

Declaration
public bool AllowHTMLRendering()
Returns
System.Boolean

ArrangeCore(RectangleF)

Declaration
protected override void ArrangeCore(RectangleF finalRect)
Parameters
System.Drawing.RectangleF finalRect

Overrides

ArrangeOverride(SizeF)

Declaration
protected override SizeF ArrangeOverride(SizeF finalSize)
Parameters
System.Drawing.SizeF finalSize

Returns
System.Drawing.SizeF

Overrides

CreateStringFormat()

Declaration
public StringFormat CreateStringFormat()
Returns
System.Drawing.StringFormat

CreateTextParams()

Declaration
protected virtual TextParams CreateTextParams()
Returns
TextParams

GetFaceRectangle()

Declaration
public RectangleF GetFaceRectangle()
Returns
System.Drawing.RectangleF

Implements

GetStylablePropertiesFilter()

Declaration
public override Filter GetStylablePropertiesFilter()
Returns
Filter

Overrides

GetTextSize()

Declaration
public SizeF GetTextSize()
Returns
System.Drawing.SizeF

GetTextSize(SizeF)

Declaration
public SizeF GetTextSize(SizeF proposedSize)
Parameters
System.Drawing.SizeF proposedSize

Returns
System.Drawing.SizeF

GetTextSize(SizeF, TextParams)

Declaration
public SizeF GetTextSize(SizeF proposedSize, TextParams textParams)
Parameters
System.Drawing.SizeF proposedSize

TextParams textParams

Returns
System.Drawing.SizeF

Implements

GetTextSize(TextParams)

Declaration
public SizeF GetTextSize(TextParams textParams)
Parameters
TextParams textParams

Returns
System.Drawing.SizeF

Implements

InitializeFields()

Declaration
protected override void InitializeFields()
Overrides

MeasureOverride(SizeF)

Declaration
protected override SizeF MeasureOverride(SizeF availableSize)
Parameters
System.Drawing.SizeF availableSize

Returns
System.Drawing.SizeF

Overrides

MeasureOverride(SizeF, TextParams)

Declaration
public SizeF MeasureOverride(SizeF availableSize, TextParams textParams)
Parameters
System.Drawing.SizeF availableSize

TextParams textParams

Returns
System.Drawing.SizeF

Implements

OnMouseMove(Object, MouseEventArgs)

Declaration
public void OnMouseMove(object sender, MouseEventArgs e)
Parameters
System.Object sender

System.Windows.Forms.MouseEventArgs e

Implements

OnMouseMove(MouseEventArgs)

Declaration
protected override void OnMouseMove(MouseEventArgs e)
Parameters
System.Windows.Forms.MouseEventArgs e

Overrides

OnPropertyChanged(RadPropertyChangedEventArgs)

Declaration
protected override void OnPropertyChanged(RadPropertyChangedEventArgs e)
Parameters
RadPropertyChangedEventArgs e

Overrides

PaintPrimitive(IGraphics, Single, SizeF)

Draws the primitive on the screen.

Declaration
public override void PaintPrimitive(IGraphics graphics, float angle, SizeF scale)
Parameters
IGraphics graphics

System.Single angle

System.Drawing.SizeF scale

Overrides

PaintPrimitive(IGraphics, Single, SizeF, TextParams)

Declaration
public void PaintPrimitive(IGraphics graphics, float angle, SizeF scale, TextParams textParams)
Parameters
IGraphics graphics

System.Single angle

System.Drawing.SizeF scale

TextParams textParams

Implements

PaintPrimitive(IGraphics, TextParams)

Declaration
public void PaintPrimitive(IGraphics graphics, TextParams textParams)
Parameters
IGraphics graphics

TextParams textParams

Implements

ToggleHTML(String)

Declaration
public void ToggleHTML(string text)
Parameters
System.String text

ToString()

Returns the text as a string.

Declaration
public override string ToString()
Returns
System.String

Overrides

Extension Methods