ITextRange ITextRange ITextRange 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 ITextRange
public interface ITextRange
Public 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.

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.

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.

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.

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.

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.

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
Platform::String string string

The URL as text.

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.

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.

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.

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
Platform::String string string

The plain text.

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(int format)
public bool CanPaste(Int32 format)
Public Function CanPaste(format As Int32) As bool
Parameters
format
int Int32 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
Platform::Boolean bool bool

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

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.

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(bool value)
public void Collapse(Boolean value)
Public Function Collapse(value As Boolean) As void
Parameters
value
bool Boolean Boolean

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

Copy() Copy() Copy()

Copies the text of the text range to the Clipboard.

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

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;
See Also

Cut() Cut() Cut()

Moves the text of the text range to the Clipboard.

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

Remarks

Note

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

See Also

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

Deletes text from the text range.

public : int Delete(TextRangeUnit unit, int 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
int Int32 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.

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, bool 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
bool Boolean 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.

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.

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(Platform::String value, int 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
Platform::String String String

The text string to search for.

scanLength
int Int32 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.

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(unsigned int value, int offset)
public void GetCharacterUtf32(UInt32 value, Int32 offset)
Public Function GetCharacterUtf32(value As UInt32, offset As Int32) As void
Parameters
value
unsigned int UInt32 UInt32

The character value.

offset
int Int32 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

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.

See Also

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.

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.

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.

See Also

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.

Remarks

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

See Also

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, int 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
int Int32 Int32

The hit-test value for the text range.

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, Platform::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
Platform::String String String

The text in the text range.

See Also

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.

See Also

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
Platform::Boolean 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.

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.

See Also

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(int width, int height, int ascent, VerticalCharacterAlignment verticalAlign, Platform::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
int Int32 Int32

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

height
int Int32 Int32

The height of the image, in DIPs.

ascent
int Int32 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
Platform::String String String

The alternate text for the image.

value
IRandomAccessStream IRandomAccessStream IRandomAccessStream

The stream that contains the image data.

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
Platform::Boolean 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.

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
Platform::Boolean bool bool

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

See Also

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

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, int 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
int Int32 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.

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.

See Also

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

Moves the end position of the text range.

public : int MoveEnd(TextRangeUnit unit, int 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
int Int32 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.

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.

See Also

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

Moves the start position of a text range.

public : int MoveStart(TextRangeUnit unit, int 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
int Int32 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.

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.

See Also

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

Pastes text from the Clipboard into the text range.

public : void Paste(int format)
public void Paste(Int32 format)
Public Function Paste(format As Int32) As void
Parameters
format
int Int32 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.

Remarks

Note

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

See Also

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.

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, int index, bool 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
int Int32 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
bool Boolean 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.

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.

See Also

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, bool 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
bool Boolean 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.

See Also

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

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

public : void SetRange(int startPosition, int endPosition)
public void SetRange(Int32 startPosition, Int32 endPosition)
Public Function SetRange(startPosition As Int32, endPosition As Int32) As void
Parameters
startPosition
int Int32 Int32

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

endPosition
int Int32 Int32

The character position for the end of the text range.

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, Platform::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
Platform::String String String

The new text.

Remarks

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

See Also

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.

See Also

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, bool 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
bool Boolean 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.

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.

See Also