Key Features

The purpose of this help article is to show you the key features of the RadRichTextEditor control.

HTML Source options

RichTextEditor exposes Source property of type RichTextSource used to load HTML content into the editor from a string as well as from a stream.

You can directly assign a string (containing HTML) as a Source of the editor - RadRichTextEditor will properly display the HTML content through the implemented in RichTextSource implicit converter. Check a simple example on this below:

this.richTextEditor.Source = "<b>Hello World!</b>";

Load HTML from a string

You can easily load the HTML content from a string by using the static FromString method of the RichTextSource class and assigning the result to the Source property of RadRichTextEditor:

var htmlSource = @"<h4>One of the Most Beautiful Islands on Earth - Tenerife</h4>
            <p><strong>Tenerife</strong> is the largest and most populated island of the eight <a href='https://en.wikipedia.org/wiki/Canary_Islands' target='_blank'>Canary Islands</a>.</p>
            <p style='color:#808080'>It is also the most populated island of <strong>Spain</strong>, with a land area of <i>2,034.38 square kilometers</i> and <i>904,713</i> inhabitants, 43% of the total population of the <strong>Canary Islands</strong>.</p>";
this.richTextEditor.Source = RichTextSource.FromString(htmlSource);

Alternatively, you can create a RichTextHtmlStringSource object and assign it to the Source property of the RichTextEditor.

Load HTML from a stream

Another option to preload HTML is by retrieving it from a stream through the static FromStream method of the RichTextSource and again, assign the result to the Source property of the RichTextEditor:

Func<CancellationToken, Task<Stream>> streamFunc = ct => Task.Run(() =>
{
    Assembly assembly = typeof(KeyFeatures).Assembly;
    string fileName = assembly.GetManifestResourceNames().FirstOrDefault(n => n.Contains("richtexteditor-htmlsource.html"));
    Stream stream = assembly.GetManifestResourceStream(fileName);
    return stream;
});

this.richTextEditor.Source = RichTextSource.FromStream(streamFunc);

In the example the HTML file is loaded as an EmbeddedResource

Alternatively, you can create a RichTextHtmlStreamSource object and set it as the Source of the RichTextEditor.

Retrieving HTML Content

Through GetHtmlAsync method of RadRichTextEditor you can obtain the created and updated inside the editor HTML content:

var htmlString = await this.richTextEditor.GetHtmlAsync();

RichText Editing Capabilities

RichTextEditor will help app users create and edit HTML content. You can apply provided by RichTextEditor editing features through the built-in UI, namely RadRichTextEditorToolbar, or you can create custom UI and manually execute the RadRichTextEditor Commands.

In addition, RichTextEditor provides flexible API to apply formatting at the current caret position or on the selected text inside the editing area.

• TextFormatting (of type RichTextFormatting): Defines the text formatting, such as heading, paragraph or quotation of the text at the current position or selection.

• TextColor: Specifies the color of the text at the current position or selection;

• HighlightTextColor: Defines the text background color at the current position or selection;

• SelectionRange (of type RichTextSelectionRange): Specifies the start and end position of the currently selected inside the editor text.

• FontSize: Sets the font size of the text at the current caret position or selection;

• FontAttributes (of type RichTextFontAttributes): Defines the font attributes, such as bold, italic, subscript and superscript at the current position or selection;

• TextDecorations (of type RichTextDecorations): Specifies text decorations, such as underline and strikethrough at the current position or selection;

• HorizontalTextAlignment (of type RichTextHorizontalAlignment): Specifies the text alignment, such as left, right, center or justify at the current position or selection;

• ListType (of type RichTextListType): Specifies the list type, such as numbered or bulleted list at the current position or selection.

Text Selection

RichTextEditor supports text selection functionality - the end user can initiate a selection action through the tap and hold gesture over the text. The selected text is marked with a different background color and two drag handles are available to the user to make it easier to modify the current selection.

In addition, as soon as the selection is made on Android and iOS, RichTextEditor displays a customizable ContextMenu with a few default commands. For more details on this go to Context Menu topic.

You can take advantage of the following API related to text selection:

• GetSelectionAsync method - returns asynchronously a RichTextSelection object which defines the current text selection inside the editor (null if there is no text selection). The RichTextSelection object contains the Text itself as well as the Start and End position of the text characters;

Hyperlink Support

RichTextEditor provides built-in support for creating and managing hyperlinks (hyperlinks are presented with the RichTextHyperlink class). Through the exposed commands related to hyperlinks, namely ApplyHyperlinkCommand, RemoveHyperlinkCommand, and OpenHyperlinkCommand, users can manipulate the hyperlinks inside the RichTextEditor content.

In addition, RichTextEditorToolbar exposes predefined toolbar items wired to the hyperlink commands. For more details on this check RichTextEditor Custom Toolbar topic.

You can also take advantage of the following API related to hyperlinks:

• GetHyperlinkAsync method - returns asynchronously a RichTextHyperlink under the caret in the editor (or null in case there is no hyperlink). The RichTextHyperlink object contains the Url and Title of the link;

Hyperlink Error Handling

In case users try to open invalid urls (for example, the url is not absolute, the domain does not exist or is incomplete, etc) the following message is shown by default indicating there is an error with the url:

You can override the default behavior by handling the RichTextEditor's OpenHyperlinkError event:

• OpenHyperlinkError event - raised when users try to open invalid urls in the editor. The OpenHyperlinkError event handler receives two parameters:

  • The Sender which is the RichTextEditor control;
  • OpenHyperlinkErrorEventArgs provides the following properties:
    • Error - of type System.Exception, can be used to get the exact error message;
    • Url - of type string, defining the url of the hyperlink;
    • Handled - boolean property indicating whether the event is handled.

Subscribe to the event, set Handled property of the event args to True to prevent the default message and add custom implementation.

Here is a quick example on the OpenHyperlinkError event usage:

<telerikRichTextEditor:RadRichTextEditor x:Name="richTextEditor" 
                                         OpenHyperlinkError="RichTextEditor_OpenHyperlinkError"
                                         Grid.Row="1" />

And the event handler which shows a custom message:

private void RichTextEditor_OpenHyperlinkError(object sender, OpenHyperlinkErrorEventArgs e)
{
    e.Handled = true;
    Application.Current.MainPage.DisplayAlert(string.Format("Error opening {0}", e.Url), e.Error.Message, "Ok");
}

Here is the custom message:

Working With Images

You can easily add insert, delete, copy, paste, cut, edit images in the editor using the predefined toolbar items. For more details please check Workin with Images article.

Read-Only State

IsReadOnly(bool) property of the RichTextEditor indicating whether the control is in a read-only mode. Setting IsReadOnly="True" means that the Toolbar Items will be disabled and the content of the document cannot be changed. The default the value is False.

Example

For the example we will trigger the IsReadOnly State using a Switch. Here is the XAML Definition:

<Grid>
    <Grid.RowDefinitions>
        <RowDefinition Height="Auto" />
        <RowDefinition />
        <RowDefinition Height="Auto" />
    </Grid.RowDefinitions>
    <StackLayout VerticalOptions="Center" HorizontalOptions="Center" Orientation="Horizontal">
        <Label Text="IsReadOnly State:" TextColor="Black" FontSize="20"/>
        <Switch IsToggled="{Binding IsReadOnly, Source={x:Reference richTextEditor}}"/>
    </StackLayout>
    <telerikRichTextEditor:RadRichTextEditor x:Name="richTextEditor" 
                                             IsReadOnly="True"
                                             Grid.Row="1" />
    <telerikRichTextEditor:RadRichTextEditorToolbar x:Name="richTextToolbar" 
                                                    IsVisible="{Binding IsReadOnly, Source={x:Reference richTextEditor}, Converter={StaticResource invertedBooleanConverter}}"
                                                    RichTextEditor="{x:Reference richTextEditor}" 
                                                    Grid.Row="2" />
</Grid>

For the example we will use a converter to hide the Toolbar when the control is in read-only state:

<telerikCommon:InvertedBooleanConverter x:Key="invertedBooleanConverter" />

defining the Source of the RichTextEditor:

Func<CancellationToken, Task<Stream>> streamFunc = ct => Task.Run(() =>
{
    Assembly assembly = typeof(ReadOnlyState).Assembly;
    string fileName = assembly.GetManifestResourceNames().FirstOrDefault(n => n.Contains("richtexteditor-htmlsource.html"));
    Stream stream = assembly.GetManifestResourceStream(fileName);
    return stream;
});

this.richTextEditor.Source = RichTextSource.FromStream(streamFunc);

The richtexteditor-htmlsource.html file is visualized in the Editor as an EmbeddedResource.

The sample Read-Only State demo can be found in our SDK Browser Application.

See Also

• RichTextEditor Toolbar
• Commands
• Context Menu