ITextRange ITextRange ITextRange Interface

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.

Syntax

Declaration

public interface ITextRangepublic interface ITextRangePublic Interface ITextRange

Properties summary

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

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

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

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

Gets or sets the gravity of the text range.

Gets the count of characters in the text range.

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

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

Gets or sets the start position of the text range.

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

Gets or sets the plain text of the text range.

Methods summary

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

Changes the case of letters in a text range.

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

Copies the text of the text range to the Clipboard.

Moves the text of the text range to the Clipboard.

Deletes text from the text range.

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.

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

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

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

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

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

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

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

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

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

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

Inserts an image into this range.

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

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

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

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.

Moves the end position of the text range.

Moves the start position of a text range.

Pastes text from the Clipboard into the text range.

Scrolls this text range into view.

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

Changes the text range based on the specified point.

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

Replaces the text in the text range.

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

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.

Properties

  • Character
    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 charpublic char Character { get; set; }

    Property 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
    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 ITextCharacterFormatpublic ITextCharacterFormat CharacterFormat { get; set; }

    Property Value

  • EndPosition
    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 intpublic int EndPosition { get; set; }

    Property 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
    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 ITextRangepublic ITextRange FormattedText { get; set; }

    Property Value

  • Gravity
    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 RangeGravitypublic RangeGravity Gravity { get; set; }

    Property Value

  • Length
    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 intpublic int Length { get; }

    Property Value

    • int
      int
      int

      The count of characters.

  • ParagraphFormat
    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 ITextParagraphFormatpublic ITextParagraphFormat ParagraphFormat { get; set; }

    Property Value

  • StartPosition
    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 intpublic int StartPosition { get; set; }

    Property 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
    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 intpublic int StoryLength { get; }

    Property Value

    • int
      int
      int

      The count of characters in the story.

  • Text
    Text
    Text
    Text

    Gets or sets the plain text of the text range.

    public string Text { get; set; }public string Text { get; set; }Public ReadWrite Property Text As stringpublic string Text { get; set; }

    Property Value

    • 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 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 Copy() and Paste(Int32) 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)
    CanPaste(Int32)

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

    public bool CanPaste(Int32 format)public bool CanPaste(Int32 format)Public Function CanPaste(format As Int32) As boolpublic bool CanPaste(Int32 format)

    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.

    Remarks

    Note

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

  • ChangeCase(LetterCase)
    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 voidpublic void ChangeCase(LetterCase value)

    Parameters

  • Collapse(Boolean)
    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 voidpublic void Collapse(Boolean value)

    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.

  • Copy()
    Copy()
    Copy()
    Copy()

    Copies the text of the text range to the Clipboard.

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

    Remarks

    Note

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

    The Cut(), Copy(), and Paste(Int32) 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 GetText(TextGetOptions, String) and SetText(TextSetOptions, String) methods. To copy formatted text from one range to another without using the Clipboard, you can use the Copy() and Paste(Int32) methods along with the FormattedText property. For example:

    textRange2.FormattedText = textRange1.FormattedText;
    
  • Cut()
    Cut()
    Cut()
    Cut()

    Moves the text of the text range to the Clipboard.

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

    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)
    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 intpublic int Delete(TextRangeUnit unit, Int32 count)

    Parameters

    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)
    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 intpublic int EndOf(TextRangeUnit unit, Boolean extend)

    Parameters

    • unit

      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.

    Remarks

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

  • Expand(TextRangeUnit)
    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 intpublic int Expand(TextRangeUnit unit)

    Parameters

    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(TextRangeUnit) method expands the range to include that word. If the range already includes one word and part of another, Expand(TextRangeUnit) expands the range to include both words.

  • FindText(String, Int32, FindOptions)
    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 intpublic int FindText(String value, Int32 scanLength, FindOptions options)

    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

      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)
    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 voidpublic void GetCharacterUtf32(UInt32 value, Int32 offset)

    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

    Remarks

    This method differs from 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()
    GetClone()

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

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

    Returns

    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)
    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 intpublic int GetIndex(TextRangeUnit unit)

    Parameters

    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(TextRangeUnit) 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(TextRangeUnit) 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)
    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 voidpublic void GetPoint(HorizontalCharacterAlignment horizontalAlign, VerticalCharacterAlignment verticalAlign, PointOptions options, Point point)

    Parameters

    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)
    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 voidpublic void GetRect(PointOptions options, Rect rect, Int32 hit)

    Parameters

    • options

      A value that indicates the rectangle to retrieve.

    • 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.

  • GetText(TextGetOptions, String)
    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 voidpublic void GetText(TextGetOptions options, String value)

    Parameters

  • GetTextViaStream(TextGetOptions, IRandomAccessStream)
    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 voidpublic void GetTextViaStream(TextGetOptions options, IRandomAccessStream value)

    Parameters

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

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

    public bool InRange(ITextRange range)public bool InRange(ITextRange range)Public Function InRange(range As ITextRange) As boolpublic bool InRange(ITextRange range)

    Parameters

    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.

    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 FindText(String, Int32, FindOptions) 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)
    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 voidpublic void InsertImage(Int32 width, Int32 height, Int32 ascent, VerticalCharacterAlignment verticalAlign, String alternateText, IRandomAccessStream value)

    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

      The vertical alignment of the image.

    • alternateText
      System.String
      System.String
      System.String

      The alternate text for the image.

    • value

      The stream that contains the image data.

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

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

    public bool InStory(ITextRange range)public bool InStory(ITextRange range)Public Function InStory(range As ITextRange) As boolpublic bool InStory(ITextRange range)

    Parameters

    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.

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

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

    public bool IsEqual(ITextRange range)public bool IsEqual(ITextRange range)Public Function IsEqual(range As ITextRange) As boolpublic bool IsEqual(ITextRange range)

    Parameters

    Returns

    • bool
      bool
      bool

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

  • MatchSelection()
    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 voidpublic void MatchSelection()
  • Move(TextRangeUnit, Int32)
    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 intpublic int Move(TextRangeUnit unit, Int32 count)

    Parameters

    • unit

      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.

    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 Move(TextRangeUnit, Int32) 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 MoveStart(TextRangeUnit, Int32) and MoveEnd(TextRangeUnit, Int32) methods, which move the range start or end position count unit s, respectively.

  • MoveEnd(TextRangeUnit, Int32)
    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 intpublic int MoveEnd(TextRangeUnit unit, Int32 count)

    Parameters

    • unit

      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.

    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 Move(TextRangeUnit, Int32).

  • MoveStart(TextRangeUnit, Int32)
    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 intpublic int MoveStart(TextRangeUnit unit, Int32 count)

    Parameters

    • unit

      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.

    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 Move(TextRangeUnit, Int32).

  • Paste(Int32)
    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 voidpublic void Paste(Int32 format)

    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.

    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)
    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 voidpublic void ScrollIntoView(PointOptions value)

    Parameters

  • SetIndex(TextRangeUnit, Int32, Boolean)
    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 voidpublic void SetIndex(TextRangeUnit unit, Int32 index, Boolean extend)

    Parameters

    • unit

      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.

    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)
    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 voidpublic void SetPoint(Point point, PointOptions options, Boolean extend)

    Parameters

    • point

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

    • options

      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.

  • SetRange(Int32, Int32)
    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 voidpublic void SetRange(Int32 startPosition, Int32 endPosition)

    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.

    Remarks

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

  • SetText(TextSetOptions, String)
    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 voidpublic void SetText(TextSetOptions options, String value)

    Parameters

    Remarks

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

  • SetTextViaStream(TextSetOptions, IRandomAccessStream)
    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 voidpublic void SetTextViaStream(TextSetOptions options, IRandomAccessStream value)

    Parameters

  • StartOf(TextRangeUnit, Boolean)
    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 intpublic int StartOf(TextRangeUnit unit, Boolean extend)

    Parameters

    • unit

      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.

    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.

Device family

Windows 10 (introduced v10.0.10240.0)

API contract

Windows.Foundation.UniversalApiContract (introduced v1)

Attributes

Windows.Foundation.Metadata.ContractVersionAttribute
Windows.Foundation.Metadata.GuidAttribute
Windows.Foundation.Metadata.WebHostHiddenAttribute

Details

Assembly

Windows.UI.Text.dll