Version

Managing Selection (xamRichTextEditor)

Topic Overview

Purpose

This topic covers the xamRichTextEditor ™ control’s selection feature from the developer’s perspective.

Required background

The following topics are prerequisites to understanding this topic:

Topic Purpose

This topic provides an overview of the features supported by the xamRichTextEditor control.

This topic explains the document’s content logical structure you can use to edit the contents in the xamRichTextEditor programmatically.

This topic provides detailed instructions to help you get up and running as quickly as possible with the xamRichTextEditor .

Introduction

Selection summary

The xamRichTextEditor control’s selection feature allows you or the user to select content from a document. You can select either a single area from the content or multiple areas, called ranges. The range is an object which represents part of the document’s content and is defined by its start and end positions. These positions are, in fact, the offsets from the beginning of the document’s content. Each rich content type (like characters, words, paragraph ends, list item indicators, images or tables) occupies a document offset.

You can access the single selection using the Selection.Range property or use the Selection.Ranges collection, with multiple selection enabled via the IsMultiSelectEnabled property, to obtain multiple selection ranges.

Note
Note

The Selection.Range property refers to the selection range when using single selection. When using the multiple selection mode, this property refers to the most recent selection made, which is also the last entry in the Selection.Ranges collection.

Obtaining Single Selection Programmatically

Overview

The following information describes how to obtain the single selection’s range. You can also access the selection range (or the primary selected range of the multiple selection) using the Selection.Range property. Use the Selection.Text property to obtain the plain text content of the selection.

Property settings

The following table maps the desired behaviors to its respective property settings.

In order to: Use this property: And obtain:

Obtain selection start

The start offset of the selection range

Obtain selection end

End

The end offset of the selection range

Obtain selection content

Text

The content as string

Code snippet

In C#:

// obtains the start and the end of the selection
int startIndex = this.xamRichTextEditor1.ActiveDocumentView.Selection.Start;
int endOffset = this.xamRichTextEditor1.ActiveDocumentView.Selection.End;
string text = this.xamRichTextEditor1.ActiveDocumentView.Selection.Text;

In Visual Basic:

' obtains the start and the end of the selection
Dim startIndex As Integer = Me.xamRichTextEditor1.ActiveDocumentView.Selection.Start
Dim endOffset As Integer = Me.xamRichTextEditor1.ActiveDocumentView.Selection.[End]
Dim text As String = Me.xamRichTextEditor1.ActiveDocumentView.Selection.Text

Set Single Selection Programmatically

Overview

The following information describes how to set the single selection’s range. You can also set the selection content using the Selection.Text property, which replaces the existing selected content.

Property settings

The following table maps the desired behaviors to their respective properties.

In order to: Use this property: And set it to:

Set selection start

Start

The start offset of the selection range

Set selection end

End

The end offset of the selection range

Set selection new content

Text

To a value of type string

Note
Note

The selection can also be changed using the Selection.SetRange method. There are also a lot of helper methods in the Selection object, which can be used to select characters, words and other parts of the document. Please see the API documentation for specific help on each method.

Note
Note

To clear the selection you can use the Selection.Collapse method and specify which position of the range to collapse (the start or the end). After collapsing the range, the starting and ending point of the selection will be equal.

Code snippet

In C#:

// set the start and the end of the selection
this.xamRichTextEditor1.ActiveDocumentView.Selection.Start = startOffset;
this.xamRichTextEditor1.ActiveDocumentView.Selection.End = endOffset;

In Visual Basic:

' set the start and the end of the selection
Me.xamRichTextEditor1.ActiveDocumentView.Selection.Start = startOffset
Me.xamRichTextEditor1.ActiveDocumentView.Selection.End = endOffset

Obtaining Multiple Selection Programmatically

Overview

The following information describes how to obtain multiple selections’ ranges. The most recent range made is also available using the Selection.Range property.

Property settings

The following table maps the desired behaviors to their respective properties.

In order to: Use this property: And:

Obtain multiple selection ranges

Access the elements of this collection of type Range

Code snippet

In C#:

foreach (Range selRange in
    this.xamRichTextEditor1.ActiveDocumentView.Selection.Ranges)
{
   int rangeStart = selRange.Start;
   int rangeEnd = selRange.End;
   string rangeText = selRange.Text;
}

In Visual Basic:

For Each selRange As Range In Me.xamRichTextEditor1.ActiveDocumentView.Selection.Ranges
        Dim rangeStart As Integer = selRange.Start
        Dim rangeEnd As Integer = selRange.[End]
        Dim rangeText As String = selRange.Text
Next

Set Multiple Selection Programmatically

Overview

The following information describes how to set the multiple selection ranges. New selection ranges can be added to the selection and, if needed, the current selection ranges can be kept.

Property settings

The following table maps the desired behaviors to methods.

In order to: Use this method: And:

Add or replace multiple selection ranges

Specify the new selection ranges as document spans. Also specify whether the old selection ranges should be kept using the replaceEntireSelection Boolean argument.

Related Topics

The following topic provides additional information related to this topic.

Topic Purpose

This topic explains how to turn on the xamRichTextEditor control’s multiple selection functionality.