RichEditBox RichEditBox RichEditBox Class

Represents a rich text editing control that supports formatted text, hyperlinks, and other rich content.

Syntax

Declaration

public class RichEditBoxpublic class RichEditBoxPublic Class RichEditBox
<RichEditBox .../>

Inheritance Hierarchy

Inherited Members

Inherited properties

, , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , ,
Tag
Tag
Tag
, , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , ,

Inherited events

, , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , ,

Inherited methods

, , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , ,

Remarks

RichEditBox is a control that lets a user enter formatted text such as bold, italic, and underlined. RichEditBox can also display Rich Text Format (.rtf) documents including hyperlinks and images (.jpg, .png, etc). This control is designed for advanced text editing scenarios. For simple plain text input, like on a form, consider using TextBox.

You use the Document property of the RichEditBox to get its content. The content of a RichEditBox is a ITextDocument object, which gives you access to the underlying Text Object Model APIs.

For more info and examples, see the RichEditBox control guide.

Control style and template

You can modify the default Style and ControlTemplate to give the control a unique appearance. For information about modifying a control's style and template, see Styling controls. The default style, template, and resources that define the look of the control are included in the generic.xaml file. For design purposes, generic.xaml is available in the (Program Files)\Windows Kits\10\DesignTime\CommonConfiguration\Neutral\UAP&lt;SDK version>\Generic folder from a Windows Software Development Kit (SDK) installation. Styles and resources from different versions of the SDK might have different values.

Starting in Windows 10, version 1607 (Windows Software Development Kit (SDK) version 10.0.14393.0), generic.xaml includes resources that you can use to modify the colors of a control in different visual states without modifying the control template. In apps that target this software development kit (SDK) or later, modifying these resources is preferred to setting properties such as Background and Foreground. For more info, see the Light-weight styling section of the Styling controls article.

This table shows the resources used by the RichEditBox control. Resources that start with "TextControl" are shared by TextBox, PasswordBox, RichEditBox, and AutoSuggestBox.

Resource keyDescription
TextControlForegroundText color at rest and not focused
TextControlForegroundPointerOverText color on hover
TextControlForegroundFocusedText color when focused
TextControlForegroundDisabledText color when disabled
TextControlBackgroundBackground color at rest and not focused
TextControlBackgroundPointerOverBackground color on hover
TextControlBackgroundFocusedBackground color when focused
TextControlBackgroundDisabledBackground color when disabled
TextControlBorderBrushBorder color at rest and not focused
TextControlBorderBrushPointerOverBorder color on hover
TextControlBorderBrushFocusedBorder color when focused
TextControlBorderBrushDisabledBorder color when disabled
TextControlPlaceholderForegroundPlaceholder text color at rest and not focused
TextControlPlaceholderForegroundPointerOverPlaceholder text color on hover
TextControlPlaceholderForegroundFocusedPlaceholder text color when focused
TextControlPlaceholderForegroundDisabledPlaceholder text color when disabled
TextControlHeaderForegroundHeader text color
TextControlHeaderForegroundDisabledHeader text color when disabled
TextControlSelectionHighlightColorHighlight color of selected text
TextControlButtonBackgroundBackground color of delete button at rest
TextControlButtonBackgroundPointerOverBackground color of delete button on hover
TextControlButtonBackgroundPressedBackground color of delete button when pressed
TextControlButtonBorderBrushBorder color of delete button at rest
TextControlButtonBorderBrushPointerOverBorder color of delete button on hover
TextControlButtonBorderBrushPressedBorder color of delete button when pressed
TextControlButtonForegroundForeground color of delete button at rest
TextControlButtonForegroundPointerOverForeground color of delete button on hover
TextControlButtonForegroundPressedForeground color of delete button when pressed

Examples

This example shows how to use the SetText(TextSetOptions, String) method to programmatically add text to a RichEditBox.

<RichEditBox x:Name="richEditBox" Width="500" Header="Notes"/>
richEditBox.Document.SetText(Windows.UI.Text.TextSetOptions.None, "This is some sample text");

This example shows how to edit, load, and save a Rich Text Format (.rtf) file in a RichEditBox.

 <RelativePanel Margin="20" HorizontalAlignment="Stretch">
     <RelativePanel.Resources>
         <Style TargetType="AppBarButton">
             <Setter Property="IsCompact" Value="True"/>
         </Style>
     </RelativePanel.Resources>
     <AppBarButton x:Name="openFileButton" Icon="OpenFile" 
                   Click="OpenButton_Click" ToolTipService.ToolTip="Open file"/>
     <AppBarButton Icon="Save" Click="SaveButton_Click" 
                   ToolTipService.ToolTip="Save file" 
                   RelativePanel.RightOf="openFileButton" Margin="8,0,0,0"/>

     <AppBarButton Icon="Bold" Click="BoldButton_Click" ToolTipService.ToolTip="Bold" 
                   RelativePanel.LeftOf="italicButton" Margin="0,0,8,0"/>
     <AppBarButton x:Name="italicButton" Icon="Italic" Click="ItalicButton_Click" 
                   ToolTipService.ToolTip="Italic" RelativePanel.LeftOf="underlineButton" Margin="0,0,8,0"/>
     <AppBarButton x:Name="underlineButton" Icon="Underline" Click="UnderlineButton_Click" 
                   ToolTipService.ToolTip="Underline" RelativePanel.AlignRightWithPanel="True"/>


     <RichEditBox x:Name="editor" Height="200" RelativePanel.Below="openFileButton" 
                  RelativePanel.AlignLeftWithPanel="True" RelativePanel.AlignRightWithPanel="True"/>
 </RelativePanel>
private async void OpenButton_Click(object sender, RoutedEventArgs e)
{
    // Open a text file.
    Windows.Storage.Pickers.FileOpenPicker open =
        new Windows.Storage.Pickers.FileOpenPicker();
    open.SuggestedStartLocation =
        Windows.Storage.Pickers.PickerLocationId.DocumentsLibrary;
    open.FileTypeFilter.Add(".rtf");

    Windows.Storage.StorageFile file = await open.PickSingleFileAsync();

    if (file != null)
    {
        try
        {
            Windows.Storage.Streams.IRandomAccessStream randAccStream =
        await file.OpenAsync(Windows.Storage.FileAccessMode.Read);

            // Load the file into the Document property of the RichEditBox.
            editor.Document.LoadFromStream(Windows.UI.Text.TextSetOptions.FormatRtf, randAccStream);
        }
        catch (Exception)
        {
            ContentDialog errorDialog = new ContentDialog()
            {
                Title = "File open error",
                Content = "Sorry, I couldn't open the file.",
                PrimaryButtonText = "Ok"
            };

            await errorDialog.ShowAsync();
        }
    }
}

private async void SaveButton_Click(object sender, RoutedEventArgs e)
{
    Windows.Storage.Pickers.FileSavePicker savePicker = new Windows.Storage.Pickers.FileSavePicker();
    savePicker.SuggestedStartLocation = Windows.Storage.Pickers.PickerLocationId.DocumentsLibrary;

    // Dropdown of file types the user can save the file as
    savePicker.FileTypeChoices.Add("Rich Text", new List<string>() { ".rtf" });

    // Default file name if the user does not type one in or select a file to replace
    savePicker.SuggestedFileName = "New Document";

    Windows.Storage.StorageFile file = await savePicker.PickSaveFileAsync();
    if (file != null)
    {
        // Prevent updates to the remote version of the file until we 
        // finish making changes and call CompleteUpdatesAsync.
        Windows.Storage.CachedFileManager.DeferUpdates(file);
        // write to file
        Windows.Storage.Streams.IRandomAccessStream randAccStream =
            await file.OpenAsync(Windows.Storage.FileAccessMode.ReadWrite);

        editor.Document.SaveToStream(Windows.UI.Text.TextGetOptions.FormatRtf, randAccStream);

        // Let Windows know that we're finished changing the file so the 
        // other app can update the remote version of the file.
        Windows.Storage.Provider.FileUpdateStatus status = await Windows.Storage.CachedFileManager.CompleteUpdatesAsync(file);
        if (status != Windows.Storage.Provider.FileUpdateStatus.Complete)
        {
            Windows.UI.Popups.MessageDialog errorBox =
                new Windows.UI.Popups.MessageDialog("File " + file.Name + " couldn't be saved.");
            await errorBox.ShowAsync();
        }
    }
}

private void BoldButton_Click(object sender, RoutedEventArgs e)
{
    Windows.UI.Text.ITextSelection selectedText = editor.Document.Selection;
    if (selectedText != null)
    {
        Windows.UI.Text.ITextCharacterFormat charFormatting = selectedText.CharacterFormat;
        charFormatting.Bold = Windows.UI.Text.FormatEffect.Toggle;
        selectedText.CharacterFormat = charFormatting;
    }
}

private void ItalicButton_Click(object sender, RoutedEventArgs e)
{
    Windows.UI.Text.ITextSelection selectedText = editor.Document.Selection;
    if (selectedText != null)
    {
        Windows.UI.Text.ITextCharacterFormat charFormatting = selectedText.CharacterFormat;
        charFormatting.Italic = Windows.UI.Text.FormatEffect.Toggle;
        selectedText.CharacterFormat = charFormatting;
    }
}

private void UnderlineButton_Click(object sender, RoutedEventArgs e)
{
    Windows.UI.Text.ITextSelection selectedText = editor.Document.Selection;
    if (selectedText != null)
    {
        Windows.UI.Text.ITextCharacterFormat charFormatting = selectedText.CharacterFormat;
        if (charFormatting.Underline == Windows.UI.Text.UnderlineType.None)
        {
            charFormatting.Underline = Windows.UI.Text.UnderlineType.Single;
        }
        else {
            charFormatting.Underline = Windows.UI.Text.UnderlineType.None;
        }
        selectedText.CharacterFormat = charFormatting;
    }
}

Constructors summary

Initializes a new instance of the RichEditBox class.

Properties summary

Gets or sets a value that indicates whether the RichEditBox allows and displays the newline or return characters when the ENTER or RETURN keys are pressed.

Identifies the AcceptsReturn dependency property.

Gets or sets a value that specifies whether text is copied with all formats, or as plain text only.

Identifies the ClipboardCopyFormat dependency property.

Gets or sets a value that indicates the preferred alignment of the Input Method Editor (IME).

Identifies the DesiredCandidateWindowAlignment dependency property.

Gets an object that enables access to the text object model for the text contained in a RichEditBox.

Gets or sets the content for the control's header.

Identifies the Header dependency property.

Gets or sets the DataTemplate used to display the content of the control's header.

Identifies the HeaderTemplate dependency property.

Gets or sets the context for input used by this RichEditBox.

Identifies the InputScope dependency property.

Gets or sets a value that determines whether font glyphs that contain color layers, such as Segoe UI Emoji, are rendered in color.

Identifies the IsColorFontEnabled dependency property.

Gets or sets a value that indicates whether the user can change the text in the RichEditBox.

Identifies the IsReadOnly dependency property.

Gets or sets a value that indicates whether the text input should interact with a spell check engine.

Identifies the IsSpellCheckEnabled dependency property.

Gets or sets a value that indicates whether text prediction features ("autocomplete") are enabled for this RichEditBox.

Identifies the IsTextPredictionEnabled dependency property.

Prerelease. Gets or sets the value that specifies the maximum number of characters allowed for user input.

Prerelease. Identifies the MaxLength dependency property.

Gets or sets the text that is displayed in the control until the value is changed by a user action or some other operation.

Identifies the PlaceholderText dependency property.

Gets or sets a value that indicates whether the on-screen keyboard is shown when the control receives focus programmatically.

Identifies the PreventKeyboardDisplayOnProgrammaticFocus dependency property.

Gets or sets the brush used to highlight the selected text.

Identifies the SelectionHighlightColor dependency property.

Prerelease. Gets or sets the brush used to highlight the selected text when it doesn't have focus.

Prerelease. Identifies the SelectionHighlightColorWhenNotFocused dependency property.

Gets or sets a value that indicates how text is aligned in the RichEditBox.

Identifies the TextAlignment dependency property.

Gets or sets a value that indicates how the reading order is determined for the RichEditBox.

Identifies the TextReadingOrder dependency property.

Gets or sets a value that indicates how text wrapping occurs if a line of text extends beyond the available width of the RichEditBox.

Identifies the TextWrapping dependency property.

Methods summary

Asynchronously gets a list of candidate words based on the provided phonetic characters in an Input Method Editor (IME).

Events summary

Occurs when the Input Method Editor (IME) window open, updates, or closes.

Occurs when the system processes an interaction that displays a context menu.

Occurs when text is pasted into the control.

Occurs when the text selection has changed.

Occurs when content changes in the RichEditBox.

Occurs synchronously when the text in the edit box starts to change, but before it is rendered.

Occurs when text being composed through an Input Method Editor (IME) changes.

Occurs when a user stops composing text through an Input Method Editor (IME).

Occurs when a user starts composing text through an Input Method Editor (IME).

Constructors

  • RichEditBox()
    RichEditBox()
    RichEditBox()
    RichEditBox()

    Initializes a new instance of the RichEditBox class.

    public RichEditBox()public New()Public Sub New()public RichEditBox()

Properties

  • AcceptsReturn
    AcceptsReturn
    AcceptsReturn
    AcceptsReturn

    Gets or sets a value that indicates whether the RichEditBox allows and displays the newline or return characters when the ENTER or RETURN keys are pressed.

    public bool AcceptsReturn { get; set; }public bool AcceptsReturn { get; set; }Public ReadWrite Property AcceptsReturn As boolpublic bool AcceptsReturn { get; set; }
    <RichEditBox AcceptsReturn="bool"/>
    

    Property Value

    • bool
      bool
      bool

      True if the RichEditBox allows newline characters; otherwise, false. The default is true.

  • AcceptsReturnProperty
    AcceptsReturnProperty
    AcceptsReturnProperty
    AcceptsReturnProperty

    Identifies the AcceptsReturn dependency property.

    public static DependencyProperty AcceptsReturnProperty { get; }public static DependencyProperty AcceptsReturnProperty { get; }Public Static ReadOnly Property AcceptsReturnProperty As DependencyPropertypublic static DependencyProperty AcceptsReturnProperty { get; }

    Property Value

  • ClipboardCopyFormat
    ClipboardCopyFormat
    ClipboardCopyFormat
    ClipboardCopyFormat

    Gets or sets a value that specifies whether text is copied with all formats, or as plain text only.

    public RichEditClipboardFormat ClipboardCopyFormat { get; set; }public RichEditClipboardFormat ClipboardCopyFormat { get; set; }Public ReadWrite Property ClipboardCopyFormat As RichEditClipboardFormatpublic RichEditClipboardFormat ClipboardCopyFormat { get; set; }

    Property Value

    Remarks

    By default, text copied from a RichEditBox is copied as both plain text and rich text. When the text is pasted into another app, the receiving app determines whether the plain text or rich text is used. To ensure that only plain text is pasted into a receiving app, set this property to PlainText to copy only plain text from the RichEditBox.

    Examples

    <RichEditBox ClipboardCopyFormat="PlainText"/>
    
    RichEditBox editBox1 = new RichEditBox();
    editBox1.ClipboardCopyFormat = RichEditClipboardFormat.PlainText;
    
  • ClipboardCopyFormatProperty
    ClipboardCopyFormatProperty
    ClipboardCopyFormatProperty
    ClipboardCopyFormatProperty

    Identifies the ClipboardCopyFormat dependency property.

    public static DependencyProperty ClipboardCopyFormatProperty { get; }public static DependencyProperty ClipboardCopyFormatProperty { get; }Public Static ReadOnly Property ClipboardCopyFormatProperty As DependencyPropertypublic static DependencyProperty ClipboardCopyFormatProperty { get; }

    Property Value

  • DesiredCandidateWindowAlignment
    DesiredCandidateWindowAlignment
    DesiredCandidateWindowAlignment
    DesiredCandidateWindowAlignment

    Gets or sets a value that indicates the preferred alignment of the Input Method Editor (IME).

    public CandidateWindowAlignment DesiredCandidateWindowAlignment { get; set; }public CandidateWindowAlignment DesiredCandidateWindowAlignment { get; set; }Public ReadWrite Property DesiredCandidateWindowAlignment As CandidateWindowAlignmentpublic CandidateWindowAlignment DesiredCandidateWindowAlignment { get; set; }
    <RichEditBox DesiredCandidateWindowAlignment="candidateWindowAlignmentMemberName"/>
    

    Property Value

    Remarks

    Users sometimes enter text through an Input Method Editor (IME) that shows in a window just below a text input box (typically for East Asian languages). The Input Method Editor (IME) window can cover important parts of your app UI that the user might need to see while entering text. Use the DesiredCandidateWindowAlignment property to specify a preferred placement of the Input Method Editor (IME) window in relation to the text input box.

    By default, when the hardware keyboard is used, the Input Method Editor (IME) follows the cursor. You can set DesiredCandidateWindowAlignment to CandidateWindowAlignment to align the Input Method Editor (IME) to the bottom edge and left side of the text edit control.

    When the Soft Input Panel (SIP) is used, DesiredCandidateWindowAlignment doesn't have any effect. The Input Method Editor (IME) remains docked to the Soft Input Panel (SIP) whenever the Soft Input Panel (SIP) is used.

    You can also handle the CandidateWindowBoundsChanged event to adapt your UI to the placement of the Input Method Editor (IME).

  • DesiredCandidateWindowAlignmentProperty
    DesiredCandidateWindowAlignmentProperty
    DesiredCandidateWindowAlignmentProperty
    DesiredCandidateWindowAlignmentProperty

    Identifies the DesiredCandidateWindowAlignment dependency property.

    public static DependencyProperty DesiredCandidateWindowAlignmentProperty { get; }public static DependencyProperty DesiredCandidateWindowAlignmentProperty { get; }Public Static ReadOnly Property DesiredCandidateWindowAlignmentProperty As DependencyPropertypublic static DependencyProperty DesiredCandidateWindowAlignmentProperty { get; }

    Property Value

  • Document
    Document
    Document
    Document

    Gets an object that enables access to the text object model for the text contained in a RichEditBox.

    public ITextDocument Document { get; }public ITextDocument Document { get; }Public ReadOnly Property Document As ITextDocumentpublic ITextDocument Document { get; }

    Property Value

  • Header
    Header
    Header
    Header

    Gets or sets the content for the control's header.

    public object Header { get; set; }public object Header { get; set; }Public ReadWrite Property Header As objectpublic object Header { get; set; }
    <RichEditBox Header="headerString"/>
    
    

    Property Value

    • object
      object
      object

      The content of the control's header. The default is null.

    Remarks

    You can set a data template for the Header by using the HeaderTemplate property.

  • HeaderProperty
    HeaderProperty
    HeaderProperty
    HeaderProperty

    Identifies the Header dependency property.

    public static DependencyProperty HeaderProperty { get; }public static DependencyProperty HeaderProperty { get; }Public Static ReadOnly Property HeaderProperty As DependencyPropertypublic static DependencyProperty HeaderProperty { get; }

    Property Value

  • HeaderTemplate
    HeaderTemplate
    HeaderTemplate
    HeaderTemplate

    Gets or sets the DataTemplate used to display the content of the control's header.

    public DataTemplate HeaderTemplate { get; set; }public DataTemplate HeaderTemplate { get; set; }Public ReadWrite Property HeaderTemplate As DataTemplatepublic DataTemplate HeaderTemplate { get; set; }
    <RichEditBox>
      <RichEditBox.HeaderTemplate>
        singleDataTemplate
      </RichEditBox.HeaderTemplate>
    </RichEditBox>
    

    Property Value

  • HeaderTemplateProperty
    HeaderTemplateProperty
    HeaderTemplateProperty
    HeaderTemplateProperty

    Identifies the HeaderTemplate dependency property.

    public static DependencyProperty HeaderTemplateProperty { get; }public static DependencyProperty HeaderTemplateProperty { get; }Public Static ReadOnly Property HeaderTemplateProperty As DependencyPropertypublic static DependencyProperty HeaderTemplateProperty { get; }

    Property Value

  • InputScope
    InputScope
    InputScope
    InputScope

    Gets or sets the context for input used by this RichEditBox.

    public InputScope InputScope { get; set; }public InputScope InputScope { get; set; }Public ReadWrite Property InputScope As InputScopepublic InputScope InputScope { get; set; }
    <RichEditBox InputScope="inputScopeName" .../>
    

    Property Value

    Remarks

    The input scope provides a hint at the type of text input expected by the control. Various elements of the system can respond to the hint provided by the input scope and provide a specialized UI for the input type. For example, the soft keyboard might show a number pad for text input when the control has its InputScope set to Number.

    The control might also interpret the data being entered differently (typically for East Asian related input scopes). The input scope does not perform any validation, and does not prevent the user from providing any input through a hardware keyboard or other input device.

    Examples

    Here's how to set the InputScope in XAML and in code.

    <RichEditBox InputScope="Formula"/>
    
    
    RichEditBox editBox = new RichEditBox();
    
    InputScope scope = new InputScope();
    InputScopeName scopeName = new InputScopeName();
    scopeName.NameValue = InputScopeNameValue.Formula;
    scope.Names.Add(scopeName);
    editBox.InputScope = scope;
    
  • InputScopeProperty
    InputScopeProperty
    InputScopeProperty
    InputScopeProperty

    Identifies the InputScope dependency property.

    public static DependencyProperty InputScopeProperty { get; }public static DependencyProperty InputScopeProperty { get; }Public Static ReadOnly Property InputScopeProperty As DependencyPropertypublic static DependencyProperty InputScopeProperty { get; }

    Property Value

  • IsColorFontEnabled
    IsColorFontEnabled
    IsColorFontEnabled
    IsColorFontEnabled

    Gets or sets a value that determines whether font glyphs that contain color layers, such as Segoe UI Emoji, are rendered in color.

    public bool IsColorFontEnabled { get; set; }public bool IsColorFontEnabled { get; set; }Public ReadWrite Property IsColorFontEnabled As boolpublic bool IsColorFontEnabled { get; set; }
    <RichEditBox IsColorFontEnabled="bool" />
    

    Property Value

    • bool
      bool
      bool

      true if color glyphs show in color; otherwise, false. The default is true.

    Remarks

    Windows 8.1 introduces the ability for fonts to include multiple colored layers for each glyph. For example, the Segoe UI Emoji font defines color versions of the Emoticon and other Emoji characters. By default, the IsColorFontEnabled property is true and fonts with these additional layers are rendered in color.

    In Windows 8, Extensible Application Markup Language (XAML) text controls don't render multi-color fonts in color. When an app that was compiled for Windows 8 is recompiled for Windows 8.1, color rendering of multi-color fonts is enabled by default. Some glyphs in multi-color fonts have different layout metrics when rendered in color. This could cause different layout in apps when they are recompiled for Windows 8.1. To retain the Windows 8 behavior when your app is recompiled for Windows 8.1, set IsColorFontEnabled to false.

  • IsColorFontEnabledProperty
    IsColorFontEnabledProperty
    IsColorFontEnabledProperty
    IsColorFontEnabledProperty

    Identifies the IsColorFontEnabled dependency property.

    public static DependencyProperty IsColorFontEnabledProperty { get; }public static DependencyProperty IsColorFontEnabledProperty { get; }Public Static ReadOnly Property IsColorFontEnabledProperty As DependencyPropertypublic static DependencyProperty IsColorFontEnabledProperty { get; }

    Property Value

  • IsReadOnly
    IsReadOnly
    IsReadOnly
    IsReadOnly

    Gets or sets a value that indicates whether the user can change the text in the RichEditBox.

    public bool IsReadOnly { get; set; }public bool IsReadOnly { get; set; }Public ReadWrite Property IsReadOnly As boolpublic bool IsReadOnly { get; set; }
    <RichEditBox IsReadOnly="bool"/>
    

    Property Value

    • bool
      bool
      bool

      ** True** if the RichEditBox is read-only; otherwise, false. The default is false.

  • IsReadOnlyProperty
    IsReadOnlyProperty
    IsReadOnlyProperty
    IsReadOnlyProperty

    Identifies the IsReadOnly dependency property.

    public static DependencyProperty IsReadOnlyProperty { get; }public static DependencyProperty IsReadOnlyProperty { get; }Public Static ReadOnly Property IsReadOnlyProperty As DependencyPropertypublic static DependencyProperty IsReadOnlyProperty { get; }

    Property Value

  • IsSpellCheckEnabled
    IsSpellCheckEnabled
    IsSpellCheckEnabled
    IsSpellCheckEnabled

    Gets or sets a value that indicates whether the text input should interact with a spell check engine.

    public bool IsSpellCheckEnabled { get; set; }public bool IsSpellCheckEnabled { get; set; }Public ReadWrite Property IsSpellCheckEnabled As boolpublic bool IsSpellCheckEnabled { get; set; }
    <RichEditBox IsSpellCheckEnabled="bool" />
    

    Property Value

    • bool
      bool
      bool

      True if the text input should interact with a spell check engine; otherwise, false. The default is true.

  • IsSpellCheckEnabledProperty
    IsSpellCheckEnabledProperty
    IsSpellCheckEnabledProperty
    IsSpellCheckEnabledProperty

    Identifies the IsSpellCheckEnabled dependency property.

    public static DependencyProperty IsSpellCheckEnabledProperty { get; }public static DependencyProperty IsSpellCheckEnabledProperty { get; }Public Static ReadOnly Property IsSpellCheckEnabledProperty As DependencyPropertypublic static DependencyProperty IsSpellCheckEnabledProperty { get; }

    Property Value

  • IsTextPredictionEnabled
    IsTextPredictionEnabled
    IsTextPredictionEnabled
    IsTextPredictionEnabled

    Gets or sets a value that indicates whether text prediction features ("autocomplete") are enabled for this RichEditBox.

    public bool IsTextPredictionEnabled { get; set; }public bool IsTextPredictionEnabled { get; set; }Public ReadWrite Property IsTextPredictionEnabled As boolpublic bool IsTextPredictionEnabled { get; set; }
    <RichEditBox IsTextPredictionEnabled="bool" />
    

    Property Value

    • bool
      bool
      bool

      True to enable text prediction features; otherwise, false. The default is true.

    Remarks

    This property doesn't affect Input Method Editor (IME) for Japanese or Chinese languages. Text prediction for these languages is shown even if this property is false.

  • IsTextPredictionEnabledProperty
    IsTextPredictionEnabledProperty
    IsTextPredictionEnabledProperty
    IsTextPredictionEnabledProperty

    Identifies the IsTextPredictionEnabled dependency property.

    public static DependencyProperty IsTextPredictionEnabledProperty { get; }public static DependencyProperty IsTextPredictionEnabledProperty { get; }Public Static ReadOnly Property IsTextPredictionEnabledProperty As DependencyPropertypublic static DependencyProperty IsTextPredictionEnabledProperty { get; }

    Property Value

  • MaxLength
    MaxLength
    MaxLength
    MaxLength

    Prerelease. Gets or sets the value that specifies the maximum number of characters allowed for user input.

    public int MaxLength { get; set; }public int MaxLength { get; set; }Public ReadWrite Property MaxLength As intpublic int MaxLength { get; set; }
    <RichEditBox MaxLength="int"/>
    

    Property Value

    • int
      int
      int

      The maximum number of characters allowed for user input. The default is 0 (no limit).

    Remarks

    A MaxLength value of 0 specifies that there is no limit on the number of characters allowed for user input.

  • MaxLengthProperty
    MaxLengthProperty
    MaxLengthProperty
    MaxLengthProperty

    Prerelease. Identifies the MaxLength dependency property.

    public static DependencyProperty MaxLengthProperty { get; }public static DependencyProperty MaxLengthProperty { get; }Public Static ReadOnly Property MaxLengthProperty As DependencyPropertypublic static DependencyProperty MaxLengthProperty { get; }

    Property Value

  • PlaceholderText
    PlaceholderText
    PlaceholderText
    PlaceholderText

    Gets or sets the text that is displayed in the control until the value is changed by a user action or some other operation.

    public string PlaceholderText { get; set; }public string PlaceholderText { get; set; }Public ReadWrite Property PlaceholderText As stringpublic string PlaceholderText { get; set; }
    <RichEditBox PlaceholderText="placeholderString"/>
    
    

    Property Value

    • string
      string
      string

      The text that is displayed in the control when no value is entered. The default is an empty string ("").

  • PlaceholderTextProperty
    PlaceholderTextProperty
    PlaceholderTextProperty
    PlaceholderTextProperty

    Identifies the PlaceholderText dependency property.

    public static DependencyProperty PlaceholderTextProperty { get; }public static DependencyProperty PlaceholderTextProperty { get; }Public Static ReadOnly Property PlaceholderTextProperty As DependencyPropertypublic static DependencyProperty PlaceholderTextProperty { get; }

    Property Value

  • PreventKeyboardDisplayOnProgrammaticFocus
    PreventKeyboardDisplayOnProgrammaticFocus
    PreventKeyboardDisplayOnProgrammaticFocus
    PreventKeyboardDisplayOnProgrammaticFocus

    Gets or sets a value that indicates whether the on-screen keyboard is shown when the control receives focus programmatically.

    public bool PreventKeyboardDisplayOnProgrammaticFocus { get; set; }public bool PreventKeyboardDisplayOnProgrammaticFocus { get; set; }Public ReadWrite Property PreventKeyboardDisplayOnProgrammaticFocus As boolpublic bool PreventKeyboardDisplayOnProgrammaticFocus { get; set; }
    <RichEditBox PreventKeyboardDisplayOnProgrammaticFocus="bool"/>
    

    Property Value

    • bool
      bool
      bool

      true if the on-screen keyboard is not shown when the control receives focus programmatically; otherwise, false. The default is false.

    Remarks

    Set this property to true to prevent the onscreen touch keyboard from showing when focus is programmatically set on a text box. By default, the onscreen touch keyboard is displayed whenever focus moves to an editable text box and the most recent input was generated by touch. This happens whether focus is set programmatically or by user interaction. In some situations, you might not want the keyboard to show when focus is set programmatically. For example, you might want to prevent the keyboard from covering part of your UI until the user is ready to continue their interaction.

  • PreventKeyboardDisplayOnProgrammaticFocusProperty
    PreventKeyboardDisplayOnProgrammaticFocusProperty
    PreventKeyboardDisplayOnProgrammaticFocusProperty
    PreventKeyboardDisplayOnProgrammaticFocusProperty

    Identifies the PreventKeyboardDisplayOnProgrammaticFocus dependency property.

    public static DependencyProperty PreventKeyboardDisplayOnProgrammaticFocusProperty { get; }public static DependencyProperty PreventKeyboardDisplayOnProgrammaticFocusProperty { get; }Public Static ReadOnly Property PreventKeyboardDisplayOnProgrammaticFocusProperty As DependencyPropertypublic static DependencyProperty PreventKeyboardDisplayOnProgrammaticFocusProperty { get; }

    Property Value

  • SelectionHighlightColor
    SelectionHighlightColor
    SelectionHighlightColor
    SelectionHighlightColor

    Gets or sets the brush used to highlight the selected text.

    public SolidColorBrush SelectionHighlightColor { get; set; }public SolidColorBrush SelectionHighlightColor { get; set; }Public ReadWrite Property SelectionHighlightColor As SolidColorBrushpublic SolidColorBrush SelectionHighlightColor { get; set; }
    <RichEditBox SelectionHighlightColor="{StaticResource resourceName}"/>
    
    

    Property Value

    Remarks

    The control template sets the default selection highlight color to the system resource TextSelectionHighlightColorThemeBrush. To change the selection highlight color for all editable text controls in your app, you can override the TextSelectionHighlightColorThemeBrush system resource in App.xaml. This will affect PasswordBox, TextBox, and RichEditBox controls. For more info, see XAML theme resources or RichEditBox styles and templates.

  • SelectionHighlightColorProperty
    SelectionHighlightColorProperty
    SelectionHighlightColorProperty
    SelectionHighlightColorProperty

    Identifies the SelectionHighlightColor dependency property.

    public static DependencyProperty SelectionHighlightColorProperty { get; }public static DependencyProperty SelectionHighlightColorProperty { get; }Public Static ReadOnly Property SelectionHighlightColorProperty As DependencyPropertypublic static DependencyProperty SelectionHighlightColorProperty { get; }

    Property Value

  • SelectionHighlightColorWhenNotFocused
    SelectionHighlightColorWhenNotFocused
    SelectionHighlightColorWhenNotFocused
    SelectionHighlightColorWhenNotFocused

    Prerelease. Gets or sets the brush used to highlight the selected text when it doesn't have focus.

    public SolidColorBrush SelectionHighlightColorWhenNotFocused { get; set; }public SolidColorBrush SelectionHighlightColorWhenNotFocused { get; set; }Public ReadWrite Property SelectionHighlightColorWhenNotFocused As SolidColorBrushpublic SolidColorBrush SelectionHighlightColorWhenNotFocused { get; set; }
    <RichEditBox SelectionHighlightColorWhenNotFocused="{StaticResource resourceName}"/>
    
    

    Property Value

  • SelectionHighlightColorWhenNotFocusedProperty
    SelectionHighlightColorWhenNotFocusedProperty
    SelectionHighlightColorWhenNotFocusedProperty
    SelectionHighlightColorWhenNotFocusedProperty

    Prerelease. Identifies the SelectionHighlightColorWhenNotFocused dependency property.

    public static DependencyProperty SelectionHighlightColorWhenNotFocusedProperty { get; }public static DependencyProperty SelectionHighlightColorWhenNotFocusedProperty { get; }Public Static ReadOnly Property SelectionHighlightColorWhenNotFocusedProperty As DependencyPropertypublic static DependencyProperty SelectionHighlightColorWhenNotFocusedProperty { get; }

    Property Value

  • TextAlignment
    TextAlignment
    TextAlignment
    TextAlignment

    Gets or sets a value that indicates how text is aligned in the RichEditBox.

    public TextAlignment TextAlignment { get; set; }public TextAlignment TextAlignment { get; set; }Public ReadWrite Property TextAlignment As TextAlignmentpublic TextAlignment TextAlignment { get; set; }
    <RichEditBox TextAlignment="textAlignmentValue"/>
    

    Property Value

  • TextAlignmentProperty
    TextAlignmentProperty
    TextAlignmentProperty
    TextAlignmentProperty

    Identifies the TextAlignment dependency property.

    public static DependencyProperty TextAlignmentProperty { get; }public static DependencyProperty TextAlignmentProperty { get; }Public Static ReadOnly Property TextAlignmentProperty As DependencyPropertypublic static DependencyProperty TextAlignmentProperty { get; }

    Property Value

  • TextReadingOrder
    TextReadingOrder
    TextReadingOrder
    TextReadingOrder

    Gets or sets a value that indicates how the reading order is determined for the RichEditBox.

    public TextReadingOrder TextReadingOrder { get; set; }public TextReadingOrder TextReadingOrder { get; set; }Public ReadWrite Property TextReadingOrder As TextReadingOrderpublic TextReadingOrder TextReadingOrder { get; set; }
    <RichEditBox TextReadingOrder="textReadingOrderValue"/>
    

    Property Value

    Remarks

    This property can be useful when the base direction of the text is unknown, and may not match the user's language or direction. For more info, see the Remarks section of the TextReadingOrder enumeration or How to support bidirectional UI.

  • TextReadingOrderProperty
    TextReadingOrderProperty
    TextReadingOrderProperty
    TextReadingOrderProperty

    Identifies the TextReadingOrder dependency property.

    public static DependencyProperty TextReadingOrderProperty { get; }public static DependencyProperty TextReadingOrderProperty { get; }Public Static ReadOnly Property TextReadingOrderProperty As DependencyPropertypublic static DependencyProperty TextReadingOrderProperty { get; }

    Property Value

  • TextWrapping
    TextWrapping
    TextWrapping
    TextWrapping

    Gets or sets a value that indicates how text wrapping occurs if a line of text extends beyond the available width of the RichEditBox.

    public TextWrapping TextWrapping { get; set; }public TextWrapping TextWrapping { get; set; }Public ReadWrite Property TextWrapping As TextWrappingpublic TextWrapping TextWrapping { get; set; }
    <RichEditBox TextWrapping="Wrap"/>
    -or-
    <RichEditBox TextWrapping="NoWrap"/>
    

    Property Value

    Remarks

    TextBox and RichEditBox don't support the WrapWholeWords value for their TextWrapping properties. If you try to use WrapWholeWords as a value for TextWrapping or TextWrapping an invalid argument exception is thrown.

  • TextWrappingProperty
    TextWrappingProperty
    TextWrappingProperty
    TextWrappingProperty

    Identifies the TextWrapping dependency property.

    public static DependencyProperty TextWrappingProperty { get; }public static DependencyProperty TextWrappingProperty { get; }Public Static ReadOnly Property TextWrappingProperty As DependencyPropertypublic static DependencyProperty TextWrappingProperty { get; }

    Property Value

Methods

  • GetLinguisticAlternativesAsync()
    GetLinguisticAlternativesAsync()
    GetLinguisticAlternativesAsync()
    GetLinguisticAlternativesAsync()

    Asynchronously gets a list of candidate words based on the provided phonetic characters in an Input Method Editor (IME).

    public IAsyncOperation<IVectorView<string>> GetLinguisticAlternativesAsync()public IAsyncOperation<IVectorView<string>> GetLinguisticAlternativesAsync()Public Function GetLinguisticAlternativesAsync() As IAsyncOperation( Of IVectorViewstring )public IAsyncOperation<IVectorView<string>> GetLinguisticAlternativesAsync()

    Returns

    • A list of candidate words based on the provided phonetic characters in an Input Method Editor (IME).

Events

  • CandidateWindowBoundsChanged
    CandidateWindowBoundsChanged
    CandidateWindowBoundsChanged
    CandidateWindowBoundsChanged

    Occurs when the Input Method Editor (IME) window open, updates, or closes.

    public event TypedEventHandler CandidateWindowBoundsChangedpublic event TypedEventHandler CandidateWindowBoundsChangedPublic Event CandidateWindowBoundsChangedpublic event TypedEventHandler CandidateWindowBoundsChanged
    <RichEditBox CandidateWindowBoundsChanged="eventhandler" />
    

    Remarks

    For event data, see CandidateWindowBoundsChangedEventArgs.

    Users sometimes enter text through an Input Method Editor (IME) that shows in a window just below a text input box (typically for East Asian languages). The Input Method Editor (IME) window can cover important parts of your app UI that the user might need to see while entering text. This event notifies your app of the coordinates where the Input Method Editor (IME) window is currently displayed. You can use this info to draw your UI in a location that doesn't conflict with the Input Method Editor (IME) window.

    You can also use the DesiredCandidateWindowAlignment property to specify a preferred placement of the Input Method Editor (IME) window in relation to the text input box.

    Examples

    Here, a rectangle is placed below a RichEditBox. When the Input Method Editor (IME) window bounds change, the bottom Margin of the RichEditBox is increased by the height of the Input Method Editor (IME) candidate window. As a result, the rectangle is pushed down by that amount and is not covered by the candidate window.

    <Grid Background="{ThemeResource ApplicationPageBackgroundThemeBrush}">
        <StackPanel>
            <RichEditBox x:Name="editBox1" Width="300" HorizontalAlignment="Left" 
                     DesiredCandidateWindowAlignment="BottomEdge"
                     CandidateWindowBoundsChanged="OnCandidateWindowBoundsChanged"/>
            <Rectangle Height="100" Width="100" Fill="Red" 
                       HorizontalAlignment="Left"/>
        </StackPanel>
    </Grid> 
    
    private void OnCandidateWindowBoundsChanged(RichEditBox sender, CandidateWindowBoundsChangedEventArgs args) 
    { 
        editBox1.Margin = new Thickness 
        { 
            Left = 0, 
            Top = 0, 
            Right = 0, 
            Bottom = Math.Max(0, args.Bounds.Bottom - editBox1.ActualHeight) 
        };
    } 
    
  • ContextMenuOpening
    ContextMenuOpening
    ContextMenuOpening
    ContextMenuOpening

    Occurs when the system processes an interaction that displays a context menu.

    public event ContextMenuOpeningEventHandler ContextMenuOpeningpublic event ContextMenuOpeningEventHandler ContextMenuOpeningPublic Event ContextMenuOpeningpublic event ContextMenuOpeningEventHandler ContextMenuOpening
    <RichEditBox ContextMenuOpening="eventhandler" />
    
  • Paste
    Paste
    Paste
    Paste

    Occurs when text is pasted into the control.

    public event TextControlPasteEventHandler Pastepublic event TextControlPasteEventHandler PastePublic Event Pastepublic event TextControlPasteEventHandler Paste
    <RichEditBox Paste="eventhandler"/>
    

    Remarks

    The Paste event occurs before any content is inserted into the control. You can handle this event to check the contents of the clipboard and perform any actions on the content before it's inserted. If you perform any action, set the handled property to true; otherwise, the default paste action is performed. If you set the handled property to true, then it's assumed the app has handled the insertion, and no default action is performed. You are responsible for determining the insertion point and clipboard content to insert, and inserting the content.

  • SelectionChanged
    SelectionChanged
    SelectionChanged
    SelectionChanged

    Occurs when the text selection has changed.

    public event RoutedEventHandler SelectionChangedpublic event RoutedEventHandler SelectionChangedPublic Event SelectionChangedpublic event RoutedEventHandler SelectionChanged
    <RichEditBox SelectionChanged="eventhandler"/>
    
  • TextChanged
    TextChanged
    TextChanged
    TextChanged

    Occurs when content changes in the RichEditBox.

    public event RoutedEventHandler TextChangedpublic event RoutedEventHandler TextChangedPublic Event TextChangedpublic event RoutedEventHandler TextChanged
    <RichEditBox TextChanged="eventhandler"/>
    
  • TextChanging
    TextChanging
    TextChanging
    TextChanging

    Occurs synchronously when the text in the edit box starts to change, but before it is rendered.

    public event TypedEventHandler TextChangingpublic event TypedEventHandler TextChangingPublic Event TextChangingpublic event TypedEventHandler TextChanging
    <RichEditBox TextChanging="eventhandler"/>
    

    Remarks

    For event data, see RichEditBoxTextChangingEventArgs.

    The TextChanging event occurs synchronously before the new text is rendered. In contrast, the TextChanged event is asynchronous and occurs after the new text is rendered.

    When the TextChanging event occurs, the Document property already reflects the new value (but it's not rendered in the UI). You typically handle this event to update the text value and selection before the text is rendered. This prevents the text flickering that can happen when text is rendered, updated, and re-rendered rapidly.

    Note

    This is a synchronous event that can occur at times when changes to the XAML visual tree are not allowed, such as during layout. Therefore, you should limit code within the TextChanging event handler primarily to inspecting and updating the Document property. Attempting to perform other actions, such as showing a popup or adding/removing elements from the visual tree, might cause potentially fatal errors that can lead to a crash. We recommend that you perform these other changes either in a TextChanged event handler, or run them as a separate asynchronous operation.

  • TextCompositionChanged
    TextCompositionChanged
    TextCompositionChanged
    TextCompositionChanged

    Occurs when text being composed through an Input Method Editor (IME) changes.

    public event TypedEventHandler TextCompositionChangedpublic event TypedEventHandler TextCompositionChangedPublic Event TextCompositionChangedpublic event TypedEventHandler TextCompositionChanged

    Remarks

    For event data, see TextCompositionChangedEventArgs.

    This event occurs only when text is composed through an . Text composition events occur in the following order:

    After the TextCompositionStarted event, the TextChanging > TextChanged > TextCompositionChanged event cycle can occur multiple times before the TextCompositionEnded event occurs.

  • TextCompositionEnded
    TextCompositionEnded
    TextCompositionEnded
    TextCompositionEnded

    Occurs when a user stops composing text through an Input Method Editor (IME).

    public event TypedEventHandler TextCompositionEndedpublic event TypedEventHandler TextCompositionEndedPublic Event TextCompositionEndedpublic event TypedEventHandler TextCompositionEnded

    Remarks

    For event data, see TextCompositionEndedEventArgs.

    This event occurs only when text is composed through an . Text composition events occur in the following order:

    After the TextCompositionStarted event, the TextChanging > TextChanged > TextCompositionChanged event cycle can occur multiple times before the TextCompositionEnded event occurs.

  • TextCompositionStarted
    TextCompositionStarted
    TextCompositionStarted
    TextCompositionStarted

    Occurs when a user starts composing text through an Input Method Editor (IME).

    public event TypedEventHandler TextCompositionStartedpublic event TypedEventHandler TextCompositionStartedPublic Event TextCompositionStartedpublic event TypedEventHandler TextCompositionStarted

    Remarks

    For event data, see TextCompositionStartedEventArgs.

    This event occurs only when text is composed through an . Text composition events occur in the following order:

    After the TextCompositionStarted event, the TextChanging > TextChanged > TextCompositionChanged event cycle can occur multiple times before the TextCompositionEnded event occurs.

Device family

Windows 10 (introduced v10.0.10240.0)

API contract

Windows.Foundation.UniversalApiContract (introduced v1)

Attributes

Windows.Foundation.Metadata.ComposableAttribute
Windows.Foundation.Metadata.ContractVersionAttribute
Windows.Foundation.Metadata.MarshalingBehaviorAttribute
Windows.Foundation.Metadata.StaticAttribute
Windows.Foundation.Metadata.StaticAttribute
Windows.Foundation.Metadata.StaticAttribute
Windows.Foundation.Metadata.StaticAttribute
Windows.Foundation.Metadata.StaticAttribute
Windows.Foundation.Metadata.ThreadingAttribute
Windows.Foundation.Metadata.WebHostHiddenAttribute

Details

Assembly

Windows.UI.Xaml.Controls.dll