I​Text​Range I​Text​Range I​Text​Range Interface

Definition

Represents a span of continuous text in a document, and provides powerful editing and data-binding properties and methods that allow an app to select, examine, and change document text.

public interface ITextRangepublic interface ITextRangePublic Interface ITextRange
Attributes
Windows 10 requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

Properties

Character Character Character

Gets or sets the first character of the text range; that is, the character associated with the StartPosition property.

public char Character { get; set; }public char Character { get; set; }Public ReadWrite Property Character As char
Value
char char char

The value of the first character in the text range.

Attributes

Remarks

When setting this property, the new character overwrites the first character in the text range.

CharacterFormat CharacterFormat CharacterFormat

Gets or sets the character formatting attributes of the text range.

public ITextCharacterFormat CharacterFormat { get; set; }public ITextCharacterFormat CharacterFormat { get; set; }Public ReadWrite Property CharacterFormat As ITextCharacterFormat
Value
ITextCharacterFormat ITextCharacterFormat ITextCharacterFormat

The character formatting attributes.

Attributes

EndPosition EndPosition EndPosition

Gets or sets the end character position of the text range.

public int EndPosition { get; set; }public int EndPosition { get; set; }Public ReadWrite Property EndPosition As int
Value
int int int

The end character position.

Attributes

Remarks

A text range object remains valid when the text is edited, but a character position is volatile. That is, a character position becomes invalid when text is inserted or deleted before the character position. Be careful when using character positions, especially if you store them for a significant length of time.

FormattedText FormattedText FormattedText

Gets or sets an ITextRange object with the formatted text of the specified range.

public ITextRange FormattedText { get; set; }public ITextRange FormattedText { get; set; }Public ReadWrite Property FormattedText As ITextRange
Value
ITextRange ITextRange ITextRange

The formatted text.

Attributes

Gravity Gravity Gravity

Gets or sets the gravity of the text range.

public RangeGravity Gravity { get; set; }public RangeGravity Gravity { get; set; }Public ReadWrite Property Gravity As RangeGravity
Value
RangeGravity RangeGravity RangeGravity

The gravity of the text range.

Attributes

Length Length Length

Gets the count of characters in the text range.

public int Length { get; }public int Length { get; }Public ReadOnly Property Length As int
Value
int int int

The count of characters.

Attributes

Link Link Link

Gets or sets the URL text associated with a text range.

public PlatForm::String Link { get; set; }public string Link { get; set; }Public ReadWrite Property Link As string
Value
string string string

The URL as text.

Attributes

Remarks

This method sets the start and end of the text range to include the entire hyperlink, including the friendly name, if any.

The URL string isn't validated. The text it contains must be enclosed in quotes, optionally preceded by the sentinel character 0xFDDF. For example: "http://www.msn.com" or 0xFDDF"http://www.msn.com".

The text range must be nondegenerate. The following actions are possible:

  • If part of a link's friendly name is selected, the URL part is replaced with the Link property value.
  • If part of a regular URL is selected, it becomes the link's friendly name, with the Link property value as the URL.
  • If nonlink text is selected: + If the text immediately follows a link's friendly name and the Link property value matches the URL, the text is appended to the friendly name.

    • Otherwise, the text becomes the friendly name of a link with the Link property value as the URL.

    The text range can be adjusted to different character positions after this method is called.

ParagraphFormat ParagraphFormat ParagraphFormat

Gets or sets the paragraph formatting attributes of the text range.

public ITextParagraphFormat ParagraphFormat { get; set; }public ITextParagraphFormat ParagraphFormat { get; set; }Public ReadWrite Property ParagraphFormat As ITextParagraphFormat
Value
ITextParagraphFormat ITextParagraphFormat ITextParagraphFormat

The paragraph formatting attributes.

Attributes

StartPosition StartPosition StartPosition

Gets or sets the start position of the text range.

public int StartPosition { get; set; }public int StartPosition { get; set; }Public ReadWrite Property StartPosition As int
Value
int int int

The character position to set as the start position of the text range.

Attributes

Remarks

If the start position is greater than the end position, this method sets the end position to be equal to the start position, resulting in a degenerate range (insertion point).

If this text range represents the active selection, the start position becomes the active end of the selection and is scrolled into view if the display is not frozen.

The following example shows how to convert a nondegenerate range into a degenerate range. range.End = range.Start

Similarly, the following example converts the text range into a degenerate range at the end of the range. range.Start = range.End

The following example adds 1 to end of the text range, if the range is not at the end of the story. range.End = range.End + 1

The preceding example also makes the end of the text range the active end, and can turn a degenerate range into a nondegenerate one.

StoryLength StoryLength StoryLength

Gets the count of characters in the story of the text range.

public int StoryLength { get; }public int StoryLength { get; }Public ReadOnly Property StoryLength As int
Value
int int int

The count of characters in the story.

Attributes

Text Text Text

Gets or sets the plain text of the text range.

public PlatForm::String Text { get; set; }public string Text { get; set; }Public ReadWrite Property Text As string
Value
string string string

The plain text.

Attributes

Remarks

The Text property is the default property for ITextRange. As such, it is automatically invoked for the text range. For example: Some of the examples below use this fact. print range

The Text method substitutes a string for the range text. For processing a single character, the ITextRange.Character property is more efficient than the Text property and doesn't require creating a single character range for storing a character.

If the range is degenerate, the Text property lets you insert text easily. You can also delete the text in a range:range.delete range = ""

You can use the Text property to copy plain text from one place to another, simply by setting one range equal to another. The following statement sets the text of one range to that of another:range1 = range2

These ranges can be in different stories or even in different apps. However, they do imply copying the text first into a string and then from that string to the target location.

For large amounts of text, the ITextRange.Copy and ITextRange.Paste methods can be faster, because they can perform the copy directly from source to target and with any format supported by the source and target.

The text returned by the Text property is given in Unicode. The end-of-paragraph mark may be given by one of the following depending on the original file:

  • 0x2029 (the Unicode paragraph separator)
  • carriage return/line feed (CRLF) (0xd, 0xa)
  • CR alone (0xd)

The placeholder for an embedded object is given by the special character, WCH_EMBEDDING, which has the official Unicode value 0xFFFC.

Methods

CanPaste(Int32) CanPaste(Int32) CanPaste(Int32)

Determines whether the Clipboard contains content that can be pasted, using a specified format, into the current text range.

public PlatForm::Boolean CanPaste(Int32 format)public bool CanPaste(Int32 format)Public Function CanPaste(format As Int32) As bool
Parameters
format
System.Int32 System.Int32 System.Int32

The clipboard format. Zero represents the best format, which usually is Rich Text Format (RTF), but CF_UNICODETEXT and other formats are also possible. The default value is zero.

Returns
bool bool bool

True if the Clipboard content can be pasted into the text range in the specified format, and otherwise false.

Attributes

Remarks

Note

On Windows Phone, CanPaste always returns false. Programmatic access to the clipboard is not supported on Windows Phone.

ChangeCase(LetterCase) ChangeCase(LetterCase) ChangeCase(LetterCase)

Changes the case of letters in a text range.

public void ChangeCase(LetterCase value)public void ChangeCase(LetterCase value)Public Function ChangeCase(value As LetterCase) As void
Parameters
value
LetterCase LetterCase LetterCase

The new case of letters in the text range. The default value is Lower.

Attributes

Collapse(Boolean) Collapse(Boolean) Collapse(Boolean)

Collapses the text range into a degenerate point at either the beginning or end of the range.

public void Collapse(Boolean value)public void Collapse(Boolean value)Public Function Collapse(value As Boolean) As void
Parameters
value
System.Boolean System.Boolean System.Boolean

True collapses at the start of the text range, and false collapses at the end of the range. The default value is true.

Attributes

Copy() Copy() Copy()

Copies the text of the text range to the Clipboard.

public void Copy()public void Copy()Public Function Copy() As void
Attributes

Remarks

Note

On Windows Phone, this method throws an exception. Programmatic access to the clipboard is not supported on Windows Phone.

The ITextRange.Cut, Copy, and Paste methods let you perform the usual cut, copy, and paste operations on a text range. The clipboard formats that are typically supported include CF_TEXT and CF_RTF. You can also use private clipboard formats to access text in custom formats.

To copy and replace plain text, you can use the ITextRange.GetText and SetText methods. To copy formatted text from one range to another without using the Clipboard, you can use the Copy and Paste methods along with the FormattedText property. For example:

textRange2.FormattedText = textRange1.FormattedText;

Cut() Cut() Cut()

Moves the text of the text range to the Clipboard.

public void Cut()public void Cut()Public Function Cut() As void
Attributes

Remarks

Note

On Windows Phone, this method throws an exception. Programmatic access to the clipboard is not supported on Windows Phone.

Delete(TextRangeUnit, Int32) Delete(TextRangeUnit, Int32) Delete(TextRangeUnit, Int32)

Deletes text from the text range.

public int Delete(TextRangeUnit unit, Int32 count)public int Delete(TextRangeUnit unit, Int32 count)Public Function Delete(unit As TextRangeUnit, count As Int32) As int
Parameters
unit
TextRangeUnit TextRangeUnit TextRangeUnit

The unit of text to delete.

count
System.Int32 System.Int32 System.Int32

The number of units to delete. See Remarks.

Returns
int int int

The number of units deleted. Deleting the text in a nondegenerate text range counts as one unit.

Attributes

Remarks

If count is zero, this method deletes all text in the text range. Nothing is deleted if the text range is only an insertion point (that is, a degenerate range).

If count is not zero, and the range is an insertion point, | count | (absolute value of count) units are deleted in the logical direction given by the sign of count, where a positive value is toward the end of the story, and a negative value is toward the start of the story.

If count is not zero, and the range is nondegenerate (contains text), the text in the range is deleted regardless of the values of unit and count, resulting in an insertion point. Then, | count | - 1 units are deleted in the logical direction given by the sign of count.

The text in the range can also be deleted by assigning a null string to the range.

Deleting the CR results in the following behavior:

  • If you delete just the CR but the paragraph includes text, the CR is deleted, and the following paragraph gets the same paragraph formatting as the current one.
  • If you delete the CR as well as some, but not all, of the characters in the following paragraph, the characters left over from the current paragraph get the paragraph formatting of the following paragraph.
  • If you select to the end of a paragraph, but not the whole paragraph, the CR is not deleted.
  • If you delete the whole paragraph (from the beginning through the CR), you delete the CR as well (unless it is the final CR in the file).

EndOf(TextRangeUnit, Boolean) EndOf(TextRangeUnit, Boolean) EndOf(TextRangeUnit, Boolean)

Moves or extends the text range to the end of the nearest specified text unit. The text range is moved or extended forward in the document.

public int EndOf(TextRangeUnit unit, Boolean extend)public int EndOf(TextRangeUnit unit, Boolean extend)Public Function EndOf(unit As TextRangeUnit, extend As Boolean) As int
Parameters
unit
TextRangeUnit TextRangeUnit TextRangeUnit

The unit by which to move the end position of the text range.

extend
System.Boolean System.Boolean System.Boolean

True extends the text range by moving just the end position of the range to the end of the specified unit. False moves both ends of the text range to the end of the specified unit. The default value is false.

Returns
int int int

The number of character positions that the range was moved or extended, plus 1 if the text range collapsed to the start of the range. If the text range includes the final carriage return (CR) at the end of the story, and extend is false, the return value is set to –1 to indicate that the collapse occurred before the end of the range. This is because an insertion point cannot exist beyond the final CR.

Attributes

Remarks

If the range is an insertion point on a boundary between units, the EndOf method does not change the end position of the range.

Expand(TextRangeUnit) Expand(TextRangeUnit) Expand(TextRangeUnit)

Expands a text range to completely contain any partial text units.

public int Expand(TextRangeUnit unit)public int Expand(TextRangeUnit unit)Public Function Expand(unit As TextRangeUnit) As int
Parameters
unit
TextRangeUnit TextRangeUnit TextRangeUnit

The text unit to use to expand the range. The default value is Word.

Returns
int int int

The number of characters added to the text range, if the range was expanded to include a partially contained unit.

Attributes

Remarks

For example, if the insertion point is at the beginning, the end, or inside a word, the Expand method expands the range to include that word. If the range already includes one word and part of another, Expand expands the range to include both words.

FindText(String, Int32, FindOptions) FindText(String, Int32, FindOptions) FindText(String, Int32, FindOptions)

Searches for a particular text string in a range and, if found, selects the string.

public int FindText(String value, Int32 scanLength, FindOptions options)public int FindText(String value, Int32 scanLength, FindOptions options)Public Function FindText(value As String, scanLength As Int32, options As FindOptions) As int
Parameters
value
System.String System.String System.String

The text string to search for.

scanLength
System.Int32 System.Int32 System.Int32

The maximum number of characters to search. It can be one of the following.

options
FindOptions FindOptions FindOptions

The options to use when doing the text search.

Returns
int int int

The length of the matching text string, or zero if no matching string is found.

Attributes

GetCharacterUtf32(UInt32, Int32) GetCharacterUtf32(UInt32, Int32) GetCharacterUtf32(UInt32, Int32)

Retrieves the Unicode Transformation Format (UTF)-32 character code of the character at the specified offset from the end of the text range.

public void GetCharacterUtf32(UInt32 value, Int32 offset)public void GetCharacterUtf32(UInt32 value, Int32 offset)Public Function GetCharacterUtf32(value As UInt32, offset As Int32) As void
Parameters
value
System.UInt32 System.UInt32 System.UInt32

The character value.

offset
System.Int32 System.Int32 System.Int32

The offset from the end of the text range.

If offset isThe method returns this character
0The character at the end of the range
in the middle of a surrogate pairThe corresponding UTF-32 character

Attributes

Remarks

This method differs from ITextRange.Character in the following ways:

  • It returns the Unicode Transformation Format (UTF)-32 character code for a Unicode Transformation Format (UTF)-16 surrogate pair instead of the pair’s lead code (see Sections 3.8 and 3.9 and Table 3-5 in The Unicode Standard for explanations of this notation).
  • It gets the code for the character at the specified offset from the end of the text range instead of the character at the start of the range.

If you try to retrieve a character that is before the start of the story or at the end of the story, value is set to the character code 0.

If offset is 0, this method retrieves the character at the end of the range.

If offset is in the middle of a surrogate pair, this method retrieves the corresponding Unicode Transformation Format (UTF)-32 character.

GetClone() GetClone() GetClone()

Creates a new object that is identical to this text range object.

public ITextRange GetClone()public ITextRange GetClone()Public Function GetClone() As ITextRange
Returns

The duplicate text range object.

Attributes

Remarks

To create an insertion point to traverse a text range, first clone the range and then collapse the duplicate at its starting character position.

GetIndex(TextRangeUnit) GetIndex(TextRangeUnit) GetIndex(TextRangeUnit)

Retrieves the story index of the text unit (word, line, sentence, paragraph, and so on) at the starting character position of the text range.

public int GetIndex(TextRangeUnit unit)public int GetIndex(TextRangeUnit unit)Public Function GetIndex(unit As TextRangeUnit) As int
Parameters
unit
TextRangeUnit TextRangeUnit TextRangeUnit

The text unit that is indexed.

Returns
int int int

The index value. The value is zero if unit does not exist.

Attributes

Remarks

The first unit in a story has an index value of 1. The index of a unit is the same for all character positions from the position immediately preceding the unit, up to the last character in the unit.

For a text range at the end of a story, the index retrieved by GetIndex indicates the number of units in the story, such as the number of words, lines, objects, and so on.

The index value returned by the GetIndex method is not valid if the text is subsequently edited. Be careful when using retrieved index values, especially if you store the values for a significant length of time.

GetPoint(HorizontalCharacterAlignment, VerticalCharacterAlignment, PointOptions, Point) GetPoint(HorizontalCharacterAlignment, VerticalCharacterAlignment, PointOptions, Point) GetPoint(HorizontalCharacterAlignment, VerticalCharacterAlignment, PointOptions, Point)

Retrieves the screen coordinates of a particular location in the text range.

public void GetPoint(HorizontalCharacterAlignment horizontalAlign, VerticalCharacterAlignment verticalAlign, PointOptions options, Point point)public void GetPoint(HorizontalCharacterAlignment horizontalAlign, VerticalCharacterAlignment verticalAlign, PointOptions options, Point point)Public Function GetPoint(horizontalAlign As HorizontalCharacterAlignment, verticalAlign As VerticalCharacterAlignment, options As PointOptions, point As Point) As void
Parameters
horizontalAlign
HorizontalCharacterAlignment HorizontalCharacterAlignment HorizontalCharacterAlignment

The horizontal position to retrieve, relative to the bounding rectangle of the text range.

verticalAlign
VerticalCharacterAlignment VerticalCharacterAlignment VerticalCharacterAlignment

The vertical position to retrieve, relative to the bounding rectangle of the text range.

options
PointOptions PointOptions PointOptions

The options for retrieving the coordinates of the specified location in the text range.

point
Point Point Point

A structure that receives the coordinates of the specified location in the text range, represented as an ordered pair of floating-point x- and y-coordinates that define a point in a two-dimensional plane.

Attributes

Remarks

This method lets an app emulate pointer commands, which is particularly useful for implementing accessibility scenarios.

GetRect(PointOptions, Rect, Int32) GetRect(PointOptions, Rect, Int32) GetRect(PointOptions, Rect, Int32)

Retrieves the bounding rectangle that encompasses the text range on the screen.

public void GetRect(PointOptions options, Rect rect, Int32 hit)public void GetRect(PointOptions options, Rect rect, Int32 hit)Public Function GetRect(options As PointOptions, rect As Rect, hit As Int32) As void
Parameters
options
PointOptions PointOptions PointOptions

A value that indicates the rectangle to retrieve.

rect
Rect Rect Rect

A structure that contains four floating-point numbers that represent the location and size of the bounding rectangle.

hit
System.Int32 System.Int32 System.Int32

The hit-test value for the text range.

Attributes

GetText(TextGetOptions, String) GetText(TextGetOptions, String) GetText(TextGetOptions, String)

Retrieves the text in a text range according to the specified conversion flags.

public void GetText(TextGetOptions options, String value)public void GetText(TextGetOptions options, String value)Public Function GetText(options As TextGetOptions, value As String) As void
Parameters
options
TextGetOptions TextGetOptions TextGetOptions

The conversion flags that control how the text is retrieved.

value
System.String System.String System.String

The text in the text range.

Attributes

GetTextViaStream(TextGetOptions, IRandomAccessStream) GetTextViaStream(TextGetOptions, IRandomAccessStream) GetTextViaStream(TextGetOptions, IRandomAccessStream)

Retrieves the text in the text range according to the specified conversion flags, as a random access stream.

public void GetTextViaStream(TextGetOptions options, IRandomAccessStream value)public void GetTextViaStream(TextGetOptions options, IRandomAccessStream value)Public Function GetTextViaStream(options As TextGetOptions, value As IRandomAccessStream) As void
Parameters
options
TextGetOptions TextGetOptions TextGetOptions

The conversion flags that control how the text is retrieved. A value of default retrieves the plain text in the text range.

Attributes

InRange(ITextRange) InRange(ITextRange) InRange(ITextRange)

Determines whether this range is in or at the same text as a specified range.

public PlatForm::Boolean InRange(ITextRange range)public bool InRange(ITextRange range)Public Function InRange(range As ITextRange) As bool
Parameters
range
ITextRange ITextRange ITextRange

Text that is compared to the current range.

Returns
bool bool bool

The comparison result. The result can be null. The method returns True if the range is in or at the same text as ITextRange; otherwise it returns False.

Attributes

Remarks

For one range (range2) to be contained in another (range1), both ranges must be in the same story, and:

  • Both ranges must be degenerate and have identical insertion points, or
  • Range2 must be a nondegenerate range with start and end positions at or within those of the range1.

When the ITextRange.FindText method is used, you can use one range to walk another by specifying the appropriate limit count of characters.

InsertImage(Int32, Int32, Int32, VerticalCharacterAlignment, String, IRandomAccessStream) InsertImage(Int32, Int32, Int32, VerticalCharacterAlignment, String, IRandomAccessStream) InsertImage(Int32, Int32, Int32, VerticalCharacterAlignment, String, IRandomAccessStream)

Inserts an image into this range.

public void InsertImage(Int32 width, Int32 height, Int32 ascent, VerticalCharacterAlignment verticalAlign, String alternateText, IRandomAccessStream value)public void InsertImage(Int32 width, Int32 height, Int32 ascent, VerticalCharacterAlignment verticalAlign, String alternateText, IRandomAccessStream value)Public Function InsertImage(width As Int32, height As Int32, ascent As Int32, verticalAlign As VerticalCharacterAlignment, alternateText As String, value As IRandomAccessStream) As void
Parameters
width
System.Int32 System.Int32 System.Int32

The width of the image, in Device-independent pixels (DIPs).

height
System.Int32 System.Int32 System.Int32

The height of the image, in DIPs.

ascent
System.Int32 System.Int32 System.Int32

If verticalAlign is Baseline, this parameter is the distance, in DIPs, that the top of the image extends above the text baseline. If verticalAlign is Baseline and ascent is zero, the bottom of the image is placed at the text baseline.

verticalAlign
VerticalCharacterAlignment VerticalCharacterAlignment VerticalCharacterAlignment

The vertical alignment of the image.

alternateText
System.String System.String System.String

The alternate text for the image.

value
IRandomAccessStream IRandomAccessStream IRandomAccessStream

The stream that contains the image data.

Attributes

InStory(ITextRange) InStory(ITextRange) InStory(ITextRange)

Determines whether this range's story is the same as a specified range's story.

public PlatForm::Boolean InStory(ITextRange range)public bool InStory(ITextRange range)Public Function InStory(range As ITextRange) As bool
Parameters
range
ITextRange ITextRange ITextRange

The ITextRange object whose story is compared to this range's story.

Returns
bool bool bool

The comparison result. The result can be null. The method returns True if this range's story is the same as that of the ITextRange; otherwise it returns False.

Attributes

IsEqual(ITextRange) IsEqual(ITextRange) IsEqual(ITextRange)

Determines whether this range has the same character positions and story as those of a specified range.

public PlatForm::Boolean IsEqual(ITextRange range)public bool IsEqual(ITextRange range)Public Function IsEqual(range As ITextRange) As bool
Parameters
range
ITextRange ITextRange ITextRange

The text range to compare to this text range.

Returns
bool bool bool

True if this text range has the same character positions and story as range, and otherwise false.

Attributes

MatchSelection() MatchSelection() MatchSelection()

Sets the start and end positions of this range to match the active selection.

public void MatchSelection()public void MatchSelection()Public Function MatchSelection() As void
Attributes

Move(TextRangeUnit, Int32) Move(TextRangeUnit, Int32) Move(TextRangeUnit, Int32)

Moves the insertion point forward or backward by the specified number of units. If the text range is nondegenerate, it is collapsed to an insertion point at the start or end position of the text range, depending on count, and then is moved.

public int Move(TextRangeUnit unit, Int32 count)public int Move(TextRangeUnit unit, Int32 count)Public Function Move(unit As TextRangeUnit, count As Int32) As int
Parameters
unit
TextRangeUnit TextRangeUnit TextRangeUnit

The units to move the insertion point. The default value is Character.

count
System.Int32 System.Int32 System.Int32

The number of units to move the insertion point. The default value is 1. If count is greater than zero, the insertion point moves forward, toward the end of the story. If count is less than zero, the insertion point moves backward, toward the beginning of the story. If count is zero, the range is unchanged.

Returns
int int int

The actual number of units the insertion point moves. For more information, see the Remarks section.

Attributes

Remarks

If the range is degenerate (an insertion point), this method tries to move the insertion point the number of units specified by count.

If the range is nondegenerate and count is greater than zero, this method collapses the range to an insertion point at the end of the range, moves the resulting insertion point forward to a unit boundary (if it is not already at one), and then tries to move count – 1 unit s forward. If the range is nondegenerate and count is less than zero, this method collapses the range to an insertion point at the start of the range, moves the resulting insertion point backward to a unit boundary (if it isn't already at one), and then tries to move count – 1 unit s backward. Thus, in both cases, collapsing a nondegenerate range to an insertion point, whether moving to the start or end of the unit following the collapse, counts as a unit.

This method returns the number of unit s actually moved. This method never moves the insertion point beyond the story of this range. If count unit s would move the insertion point before the beginning of the story, the insertion point is moved to the story beginning and the result is set accordingly. Similarly, if count unit s would move the insertion point beyond the end of the story, it is moved to the story end.

Count corresponds to the number of times you press Ctrl+Right Arrow.

For example, if you press Ctrl+Right Arrow for the selections shown in both of the following figures, you end up with an insertion point at character position 8, because this command collapses the selections at their ends (7 and 8, respectively) and moves to the next Word boundary.

Character positions for text string The first selection does not include the blank space at character position 7, so Ctrl+Right Arrow moves past the space to the Word boundary at character position 8. The end position of the range is already at a Word boundary for the second selection, so Ctrl+Right Arrow just collapses the selection at that boundary. Similarly, Ctrl+Left Arrow, which for this text acts like Move(Word, -1). But Ctrl+Left Arrow collapses the second selection at character position 4 and then moves to zero, because that's the next Word boundary in the direction of motion.

The return argument is set equal to the number of unit s that the insertion point is moved, including one unit for collapsing a nondegenerate range and moving it to a unit boundary. So, if no motion and no collapse occur, as when the range is an insertion point at the end of the story, the result is set equal to zero. This approach is useful for controlling app loops that process a whole story.

In both of the cases mentioned previously, calling Move(Word, 1) sets the result equal to 1 because the ranges were collapsed. Similarly, calling Move(Word, -1) sets the result equal to – 1 for both cases. Collapsing, with or without moving part of a unit to a unit boundary, counts as a unit moved.

The direction of motion refers to the logical character ordering in the plain-text backing store. This approach avoids the problems of geometrical ordering, such as left versus right and up versus down, in international software. Such geometrical methods are still needed in the edit engine, of course, because keyboards have arrow keys to invoke geometrical movements.

The ITextSelection UI methods back up over a carriage return/line feed (CR/LF) as if it were a single character, but the ITextRange.Move methods count carriage return/line feed (CR/LF) as two characters. It's clearly better to use a single character as a paragraph separator, which is represented by CR, although the Unicode paragraph separator character, 0x2029, is accepted. In general, the rich edit control supports carriage return/line feed (CR/LF), CR, LF, VT (vertical tab), FF (form feed), and 0x2029. Microsoft Rich Edit 2.0 also supports CR/CR/LF for backward compatibility.

See also the ITextRange.MoveStart and ITextRange.MoveEnd methods, which move the range start or end position count unit s, respectively.

MoveEnd(TextRangeUnit, Int32) MoveEnd(TextRangeUnit, Int32) MoveEnd(TextRangeUnit, Int32)

Moves the end position of the text range.

public int MoveEnd(TextRangeUnit unit, Int32 count)public int MoveEnd(TextRangeUnit unit, Int32 count)Public Function MoveEnd(unit As TextRangeUnit, count As Int32) As int
Parameters
unit
TextRangeUnit TextRangeUnit TextRangeUnit

The unit by which to move the end position of the text range. The default value is Character.

count
System.Int32 System.Int32 System.Int32

The number of unit s to move the end position of the text range. The default value is 1. If count is greater than zero, the end position moves forward, toward the end of the story. If count is less than zero, the end position move backward, toward the beginning of the story. If count is zero, the end position does not move.

Returns
int int int

The actual number of unit s that the end position of the text range moved.

Attributes

Remarks

If you move the end position of the text range so that it precedes the original start position, this method sets the start position to be equal to the new end position; that is, the text range becomes a degenerate range (insertion point).

This method moves the end position in a logical direction rather than a physical direction. That is, movement is toward the end or start of a story. Depending on the language, moving the end position toward the end of the story could result in the end position moving either left or right.

For more information, see the discussion in ITextRange and the Remarks section of ITextRange.Move.

MoveStart(TextRangeUnit, Int32) MoveStart(TextRangeUnit, Int32) MoveStart(TextRangeUnit, Int32)

Moves the start position of a text range.

public int MoveStart(TextRangeUnit unit, Int32 count)public int MoveStart(TextRangeUnit unit, Int32 count)Public Function MoveStart(unit As TextRangeUnit, count As Int32) As int
Parameters
unit
TextRangeUnit TextRangeUnit TextRangeUnit

The unit by which to move the start position of the text range. The default value is Character.

count
System.Int32 System.Int32 System.Int32

The number of unit s to move the start position of the text range. The default value is 1. If count is greater than zero, the start position of the text range moves forward, toward the end of the story. If count is less than zero, the start position of the text range moves backward, toward the beginning of the story. If count is zero, the start position doesn't move.

Returns
int int int

The actual number of unit s that the start position moved. The pointer can be NULL.

Attributes

Remarks

If you move the start position of the text range so that it follows the original end position, this method sets the end position to be equal to the new start position; that is, the text range becomes a degenerate range (insertion point).

This method moves the start position in a logical direction rather than a physical direction. That is, movement is toward the end or start of a story. Depending on the language, moving the start position toward the end of the story could result in the start position moving either left or right.

For more information, see the discussion in ITextRange and the Remarks section of ITextRange.Move.

Paste(Int32) Paste(Int32) Paste(Int32)

Pastes text from the Clipboard into the text range.

public void Paste(Int32 format)public void Paste(Int32 format)Public Function Paste(format As Int32) As void
Parameters
format
System.Int32 System.Int32 System.Int32

The clipboard format to use in the paste operation. Zero represents the best format, which usually is Rich Text Format (RTF), but CF_UNICODETEXT and other formats are also possible. The default value is zero.

Attributes

Remarks

Note

On Windows Phone, this method throws an exception. Programmatic access to the clipboard is not supported on Windows Phone.

ScrollIntoView(PointOptions) ScrollIntoView(PointOptions) ScrollIntoView(PointOptions)

Scrolls this text range into view.

public void ScrollIntoView(PointOptions value)public void ScrollIntoView(PointOptions value)Public Function ScrollIntoView(value As PointOptions) As void
Parameters
value
PointOptions PointOptions PointOptions

The end of the text range to scroll into view. This function uses only the Start, NoHorizontalScroll, and NoVerticalScroll values of the PointOptions enumeration.

Attributes

SetIndex(TextRangeUnit, Int32, Boolean) SetIndex(TextRangeUnit, Int32, Boolean) SetIndex(TextRangeUnit, Int32, Boolean)

Moves the text range to the specified unit of the story.

public void SetIndex(TextRangeUnit unit, Int32 index, Boolean extend)public void SetIndex(TextRangeUnit unit, Int32 index, Boolean extend)Public Function SetIndex(unit As TextRangeUnit, index As Int32, extend As Boolean) As void
Parameters
unit
TextRangeUnit TextRangeUnit TextRangeUnit

The unit used to move the text range.

index
System.Int32 System.Int32 System.Int32

The index of the specified unit. The text range is relocated to the unit that has this index. If unit is positive, the numbering of units begins at the start of the story and proceeds forward. If negative, the numbering begins at the end of the story and proceeds backward. The start of the story corresponds to index = 1 for all existing units, and the last unit in the story corresponds to index = – 1.

extend
System.Boolean System.Boolean System.Boolean

Indicates how to change the text range. True extends the text range to include the unit by moving only the end position of the text range. False collapses the text range to an insertion point and then moves the insertion point. The default value is false.

Attributes

Remarks

This method allows an app to work with line-oriented text, such as source code listings, in a convenient way. For example, ITextRange.SetIndex(Line, 10, 0) converts the text range to an insertion point at the start of the tenth line.

SetPoint(Point, PointOptions, Boolean) SetPoint(Point, PointOptions, Boolean) SetPoint(Point, PointOptions, Boolean)

Changes the text range based on the specified point.

public void SetPoint(Point point, PointOptions options, Boolean extend)public void SetPoint(Point point, PointOptions options, Boolean extend)Public Function SetPoint(point As Point, options As PointOptions, extend As Boolean) As void
Parameters
point
Point Point Point

An ordered pair of floating-point x- and y-coordinates that defines a point in a two-dimensional plane.

options
PointOptions PointOptions PointOptions

The alignment type of the specified point.

extend
System.Boolean System.Boolean System.Boolean

Indicates how to set the endpoints of the text range. If extend is 0, the text range is an insertion point located at the specified point, or at the nearest point with selectable text. If extend is 1, the endpoint specified by options is moved to the point and the other endpoint is left alone. The default value is 0.

Attributes

SetRange(Int32, Int32) SetRange(Int32, Int32) SetRange(Int32, Int32)

Sets the endpoints of the text range to the specified values.

public void SetRange(Int32 startPosition, Int32 endPosition)public void SetRange(Int32 startPosition, Int32 endPosition)Public Function SetRange(startPosition As Int32, endPosition As Int32) As void
Parameters
startPosition
System.Int32 System.Int32 System.Int32

The character position for the start of the text range. This parameter must be less than endPosition.

endPosition
System.Int32 System.Int32 System.Int32

The character position for the end of the text range.

Attributes

Remarks

If the text range is a nondegenerate selection, endPosition is the active end.

SetText(TextSetOptions, String) SetText(TextSetOptions, String) SetText(TextSetOptions, String)

Replaces the text in the text range.

public void SetText(TextSetOptions options, String value)public void SetText(TextSetOptions options, String value)Public Function SetText(options As TextSetOptions, value As String) As void
Parameters
options
TextSetOptions TextSetOptions TextSetOptions

The conversion flags that control how the text is inserted in the text range.

value
System.String System.String System.String

The new text.

Attributes

Remarks

If value is null, the text in the range is deleted.

SetTextViaStream(TextSetOptions, IRandomAccessStream) SetTextViaStream(TextSetOptions, IRandomAccessStream) SetTextViaStream(TextSetOptions, IRandomAccessStream)

Sets the text in the text range based on the contents of a random access stream.

public void SetTextViaStream(TextSetOptions options, IRandomAccessStream value)public void SetTextViaStream(TextSetOptions options, IRandomAccessStream value)Public Function SetTextViaStream(options As TextSetOptions, value As IRandomAccessStream) As void
Parameters
options
TextSetOptions TextSetOptions TextSetOptions

The text options.

Attributes

StartOf(TextRangeUnit, Boolean) StartOf(TextRangeUnit, Boolean) StartOf(TextRangeUnit, Boolean)

Moves or extends the text range to the start of the nearest specified text unit. The text range is moved or extended backward in the document.

public int StartOf(TextRangeUnit unit, Boolean extend)public int StartOf(TextRangeUnit unit, Boolean extend)Public Function StartOf(unit As TextRangeUnit, extend As Boolean) As int
Parameters
unit
TextRangeUnit TextRangeUnit TextRangeUnit

The unit by which to move the start position of the text range. The default value is Word.

extend
System.Boolean System.Boolean System.Boolean

True extends the text range by moving just the start position of the range to the start of the specified unit. False moves both ends of the text range to the start of the specified unit. The default value is false.

Returns
int int int

The number of characters the insertion point or start position is moved. Note that this value is always less than or equal to zero, since the motion is always toward the beginning of the story.

Attributes

Remarks

If the text range is an insertion point on a boundary between unit s, this method does not change the start position.

The start position does not change if unit is set to Character.