TextElement Class

Definition

An abstract class used as the base class for the also-abstract Block and Inline classes. TextElement supports common API for classes involved in the XAML text object model, such as properties that control text size, font families and so on.

Equivalent WinUI class: Microsoft.UI.Xaml.Documents.TextElement.

public ref class TextElement : DependencyObject
/// [Windows.Foundation.Metadata.ContractVersion(Windows.Foundation.UniversalApiContract, 65536)]
/// [Windows.Foundation.Metadata.MarshalingBehavior(Windows.Foundation.Metadata.MarshalingType.Agile)]
/// [Windows.Foundation.Metadata.Threading(Windows.Foundation.Metadata.ThreadingModel.Both)]
class TextElement : DependencyObject
[Windows.Foundation.Metadata.ContractVersion(typeof(Windows.Foundation.UniversalApiContract), 65536)]
[Windows.Foundation.Metadata.MarshalingBehavior(Windows.Foundation.Metadata.MarshalingType.Agile)]
[Windows.Foundation.Metadata.Threading(Windows.Foundation.Metadata.ThreadingModel.Both)]
public class TextElement : DependencyObject
Public Class TextElement
Inherits DependencyObject
Inheritance
Object IInspectable DependencyObject TextElement
Derived
Attributes

Windows requirements

Device family
Windows 10 (introduced in 10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced in v1.0)

Remarks

The various properties defined by TextElement support a common API for classes involved in the XAML text object model. Here's a list of the most commonly used properties:

By setting TextElement properties, you can apply common text formatting properties to text, both in blocks and in inlines. There are also additional ways to format text, but these aren't directly supported by TextElement. Instead, you can use the attached properties of the Typography class. Typography attached properties typically support advanced typographic features or conventions, such as accessing typographic features defined at the font level that are not necessarily supported by all fonts. For example, you could set Typography.Variants as an attached property on any text block or inline, and this would influence the font-variants behavior as enabled by the particular font you chose for setting FontFamily on that text element.

TextElement doesn't inherently define a connection point to a XAML visual tree. In other words a TextElement defines text and text object model within that text, but it doesn't yet enable the display of that text within a UI. For that, you need to use one of the controls or elements that are descendants of UIElement and can be connected to the XAML tree and the root visual of your app window. There are two such elements in the Windows Runtime:

  • TextBlock: Supports a text object model of inlines only with its Inlines collection.
  • RichTextBlock: Supports a block text object model with its Blocks collection. The blocks can contain blocks and inlines.

Note

PasswordBox, RichEditBox and TextBox don't support a text object model that's based on TextElement. RichEditBox does enable programmatic access to a different text object model through the ITextDocument interface.

TextElement defines API that support examining the text object model as programming objects after the XAML is parsed. In particular TextElement implements Name and Language, which parallel properties of the same name on FrameworkElement. TextElement also implements FindName (a utility method for finding objects at run time based on how Name was set in initial XAML), and OnDisconnectVisualChildren (for advanced scenarios and designer support).

TextElement has four properties that provide access to TextPointer objects from within text. These properties are: ContentStart, ContentEnd, ElementStart, ElementEnd. A Windows Runtime TextPointer object gives you an entry point for traversal of content. For more info, see TextPointer.

TextElement is a class derived from DependencyObject. That means it can define dependency properties, and each of the read-write properties of TextElement is a dependency property, with its property identifier also defined by TextElement. For more info on what dependency properties enable, see Dependency properties overview.

TextElement derived classes

TextElement is the parent class for two derived classes that split the text object model into two text usage conventions: Block, and Inline. Block and Inline are both considered base classes (you don't typically see a <Block> tag in XAML) and exist in the hierarchy mainly to be the parent class of other practical text elements. For example, Block is the parent class of Paragraph. For more info on how to use block and inline elements, see Quickstart: Displaying text.

Version history

Windows version SDK version Value added
1607 14393 AccessKey
1607 14393 AllowFocusOnInteraction
1607 14393 ExitDisplayModeOnAccessKeyInvoked
1703 15063 AccessKeyDisplayDismissed
1703 15063 AccessKeyDisplayRequested
1703 15063 AccessKeyInvoked
1703 15063 AccessKeyScopeOwner
1703 15063 IsAccessKeyScope
1703 15063 KeyTipHorizontalOffset
1703 15063 KeyTipPlacementMode
1703 15063 KeyTipVerticalOffset
1703 15063 TextDecorations
1903 18362 XamlRoot

Properties

AccessKey

Gets or sets the access key for this element.

Equivalent WinUI property: Microsoft.UI.Xaml.Documents.TextElement.AccessKey.

AccessKeyProperty

Identifies the AccessKey dependency property.

Equivalent WinUI property: Microsoft.UI.Xaml.Documents.TextElement.AccessKeyProperty.

AccessKeyScopeOwner

Gets or sets a source element that provides the access key scope for this element, even if it's not in the visual tree of the source element.

Equivalent WinUI property: Microsoft.UI.Xaml.Documents.TextElement.AccessKeyScopeOwner.

AccessKeyScopeOwnerProperty

Identifies the AccessKeyScopeOwner dependency property.

Equivalent WinUI property: Microsoft.UI.Xaml.Documents.TextElement.AccessKeyScopeOwnerProperty.

AllowFocusOnInteraction

Gets or sets a value that indicates whether the element automatically gets focus when the user interacts with it.

Equivalent WinUI property: Microsoft.UI.Xaml.Documents.TextElement.AllowFocusOnInteraction.

AllowFocusOnInteractionProperty

Identifies the AllowFocusOnInteraction dependency property.

Equivalent WinUI property: Microsoft.UI.Xaml.Documents.TextElement.AllowFocusOnInteractionProperty.

CharacterSpacing

Gets or sets the uniform spacing between characters, in units of 1/1000 of an em.

Equivalent WinUI property: Microsoft.UI.Xaml.Documents.TextElement.CharacterSpacing.

CharacterSpacingProperty

Identifies the CharacterSpacing dependency property.

Equivalent WinUI property: Microsoft.UI.Xaml.Documents.TextElement.CharacterSpacingProperty.

ContentEnd

Gets a TextPointer that represents the end of the content in the element.

Equivalent WinUI property: Microsoft.UI.Xaml.Documents.TextElement.ContentEnd.

ContentStart

Gets a TextPointer that represents the start of content in the element.

Equivalent WinUI property: Microsoft.UI.Xaml.Documents.TextElement.ContentStart.

Dispatcher

Gets the CoreDispatcher that this object is associated with. The CoreDispatcher represents a facility that can access the DependencyObject on the UI thread even if the code is initiated by a non-UI thread.

Equivalent WinUI property: Microsoft.UI.Xaml.DependencyObject.Dispatcher.

(Inherited from DependencyObject)
ElementEnd

Gets a TextPointer that represents the position just after the end of the element.

Equivalent WinUI property: Microsoft.UI.Xaml.Documents.TextElement.ElementEnd.

ElementStart

Gets a TextPointer that represents the position just before the start of the element.

Equivalent WinUI property: Microsoft.UI.Xaml.Documents.TextElement.ElementStart.

ExitDisplayModeOnAccessKeyInvoked

Gets or sets a value that specifies whether the access key display is dismissed when an access key is invoked.

Equivalent WinUI property: Microsoft.UI.Xaml.Documents.TextElement.ExitDisplayModeOnAccessKeyInvoked.

ExitDisplayModeOnAccessKeyInvokedProperty

Identifies the ExitDisplayModeOnAccessKeyInvoked dependency property.

Equivalent WinUI property: Microsoft.UI.Xaml.Documents.TextElement.ExitDisplayModeOnAccessKeyInvokedProperty.

FontFamily

Gets or sets the preferred top-level font family for the content of the element.

Equivalent WinUI property: Microsoft.UI.Xaml.Documents.TextElement.FontFamily.

FontFamilyProperty

Identifies the FontFamily dependency property.

Equivalent WinUI property: Microsoft.UI.Xaml.Documents.TextElement.FontFamilyProperty.

FontSize

Gets or sets the font size for the content of the element.

Equivalent WinUI property: Microsoft.UI.Xaml.Documents.TextElement.FontSize.

FontSizeProperty

Identifies the FontSize dependency property.

Equivalent WinUI property: Microsoft.UI.Xaml.Documents.TextElement.FontSizeProperty.

FontStretch

Gets or sets the glyph width of the font in a family to select.

Equivalent WinUI property: Microsoft.UI.Xaml.Documents.TextElement.FontStretch.

FontStretchProperty

Identifies the FontStretch dependency property.

Equivalent WinUI property: Microsoft.UI.Xaml.Documents.TextElement.FontStretchProperty.

FontStyle

Gets or sets the font style for the content in this element.

Equivalent WinUI property: Microsoft.UI.Xaml.Documents.TextElement.FontStyle.

FontStyleProperty

Identifies the FontStyle dependency property.

Equivalent WinUI property: Microsoft.UI.Xaml.Documents.TextElement.FontStyleProperty.

FontWeight

Gets or sets the top-level font weight to select from the font family for the content in this element.

Equivalent WinUI property: Microsoft.UI.Xaml.Documents.TextElement.FontWeight.

FontWeightProperty

Identifies the FontWeight dependency property.

Equivalent WinUI property: Microsoft.UI.Xaml.Documents.TextElement.FontWeightProperty.

Foreground

Gets or sets the Brush to apply to the content in this element.

Equivalent WinUI property: Microsoft.UI.Xaml.Documents.TextElement.Foreground.

ForegroundProperty

Identifies the Foreground dependency property.

Equivalent WinUI property: Microsoft.UI.Xaml.Documents.TextElement.ForegroundProperty.

IsAccessKeyScope

Gets or sets a value that indicates whether an element defines its own access key scope.

Equivalent WinUI property: Microsoft.UI.Xaml.Documents.TextElement.IsAccessKeyScope.

IsAccessKeyScopeProperty

Identifies the IsAccessKeyScope dependency property.

Equivalent WinUI property: Microsoft.UI.Xaml.Documents.TextElement.IsAccessKeyScopeProperty.

IsTextScaleFactorEnabled

Gets or sets whether automatic text enlargement, to reflect the system text size setting, is enabled.

Equivalent WinUI property: Microsoft.UI.Xaml.Documents.TextElement.IsTextScaleFactorEnabled.

IsTextScaleFactorEnabledProperty

Identifies the IsTextScaleFactorEnabled  dependency property.

Equivalent WinUI property: Microsoft.UI.Xaml.Documents.TextElement.IsTextScaleFactorEnabledProperty.

KeyTipHorizontalOffset

Gets or sets a value that indicates how far left or right the keytip is placed in relation to the text element.

Equivalent WinUI property: Microsoft.UI.Xaml.Documents.TextElement.KeyTipHorizontalOffset.

KeyTipHorizontalOffsetProperty

Identifies the KeyTipHorizontalOffset dependency property.

Equivalent WinUI property: Microsoft.UI.Xaml.Documents.TextElement.KeyTipHorizontalOffsetProperty.

KeyTipPlacementMode

Gets or sets a value that indicates where the KeyTip is placed in relation to the text element.

Equivalent WinUI property: Microsoft.UI.Xaml.Documents.TextElement.KeyTipPlacementMode.

KeyTipPlacementModeProperty

Identifies the KeyTipPlacementMode dependency property.

Equivalent WinUI property: Microsoft.UI.Xaml.Documents.TextElement.KeyTipPlacementModeProperty.

KeyTipVerticalOffset

Gets or sets a value that indicates how far up or down the keytip is placed in relation to the text element.

Equivalent WinUI property: Microsoft.UI.Xaml.Documents.TextElement.KeyTipVerticalOffset.

KeyTipVerticalOffsetProperty

Identifies the KeyTipVerticalOffset dependency property.

Equivalent WinUI property: Microsoft.UI.Xaml.Documents.TextElement.KeyTipVerticalOffsetProperty.

Language

Gets or sets localization/globalization language information that applies to a TextElement.

Equivalent WinUI property: Microsoft.UI.Xaml.Documents.TextElement.Language.

LanguageProperty

Identifies the Language dependency property.

Equivalent WinUI property: Microsoft.UI.Xaml.Documents.TextElement.LanguageProperty.

Name

Gets or sets a unique identification for the object. Name can only be set from initial parsing of XAML.

Equivalent WinUI property: Microsoft.UI.Xaml.Documents.TextElement.Name.

TextDecorations

Gets or sets a value that indicates what decorations are applied to the text.

Equivalent WinUI property: Microsoft.UI.Xaml.Documents.TextElement.TextDecorations.

TextDecorationsProperty

Identifies the TextDecorations dependency property.

Equivalent WinUI property: Microsoft.UI.Xaml.Documents.TextElement.TextDecorationsProperty.

XamlRoot

Gets or sets the XamlRoot in which this element is being viewed.

Equivalent WinUI property: Microsoft.UI.Xaml.Documents.TextElement.XamlRoot.

Methods

ClearValue(DependencyProperty)

Clears the local value of a dependency property.

Equivalent WinUI method: Microsoft.UI.Xaml.DependencyObject.ClearValue.

(Inherited from DependencyObject)
FindName(String)

Retrieves an object in the object model / runtime object graph by referencing the object's x:Name or Name attribute value.

Equivalent WinUI method: Microsoft.UI.Xaml.Documents.TextElement.FindName.

GetAnimationBaseValue(DependencyProperty)

Returns any base value established for a dependency property, which would apply in cases where an animation is not active.

Equivalent WinUI method: Microsoft.UI.Xaml.DependencyObject.GetAnimationBaseValue.

(Inherited from DependencyObject)
GetValue(DependencyProperty)

Returns the current effective value of a dependency property from a DependencyObject.

Equivalent WinUI method: Microsoft.UI.Xaml.DependencyObject.GetValue.

(Inherited from DependencyObject)
OnDisconnectVisualChildren()

Override this method to implement how layout and logic should behave when items are removed from a class-specific content or child property.

Equivalent WinUI method: Microsoft.UI.Xaml.Documents.TextElement.OnDisconnectVisualChildren.

ReadLocalValue(DependencyProperty)

Returns the local value of a dependency property, if a local value is set.

Equivalent WinUI method: Microsoft.UI.Xaml.DependencyObject.ReadLocalValue.

(Inherited from DependencyObject)
RegisterPropertyChangedCallback(DependencyProperty, DependencyPropertyChangedCallback)

Registers a notification function for listening to changes to a specific DependencyProperty on this DependencyObject instance.

Equivalent WinUI method: Microsoft.UI.Xaml.DependencyObject.RegisterPropertyChangedCallback.

(Inherited from DependencyObject)
SetValue(DependencyProperty, Object)

Sets the local value of a dependency property on a DependencyObject.

Equivalent WinUI method: Microsoft.UI.Xaml.DependencyObject.SetValue.

(Inherited from DependencyObject)
UnregisterPropertyChangedCallback(DependencyProperty, Int64)

Cancels a change notification that was previously registered by calling RegisterPropertyChangedCallback.

Equivalent WinUI method: Microsoft.UI.Xaml.DependencyObject.UnregisterPropertyChangedCallback.

(Inherited from DependencyObject)

Events

AccessKeyDisplayDismissed

Occurs when the access key sequence is complete to notify controls that they should hide access key visuals.

Equivalent WinUI event: Microsoft.UI.Xaml.Documents.TextElement.AccessKeyDisplayDismissed.

AccessKeyDisplayRequested

Occurs when the access key sequence is started to notify controls that they should show access key visuals.

Equivalent WinUI event: Microsoft.UI.Xaml.Documents.TextElement.AccessKeyDisplayRequested.

AccessKeyInvoked

Occurs when a user completes an access key sequence to notify the element that the access key action should be invoked.

Equivalent WinUI event: Microsoft.UI.Xaml.Documents.TextElement.AccessKeyInvoked.

Applies to

See also