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

Definition

Exposes methods and properties to support Microsoft UI Automation client access to a span of continuous text in a text container that implements ITextProvider.

public : interface ITextRangeProviderpublic interface ITextRangeProviderPublic Interface ITextRangeProvider
Attributes
Windows 10 requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

Remarks

For more info on this pattern, see Text and TextRange Control Patterns.

ITextProvider, ITextProvider2 and ITextRangeProvider aren't implemented by any existing Windows Runtime automation peers using this definition of the interface. The text models supported by Windows Runtime text controls such as TextBox and RichTextBlock do implement some of these patterns, but do so at a native level that doesn't appear in the Windows Runtime definitions of the API surface. For more info, see the peer classes for the various Windows Runtime text controls.

The ITextRangeProvider pattern doesn't have a Windows Runtime property identifier class.

Methods

AddToSelection() AddToSelection() AddToSelection()

Adds to the collection of highlighted text in a text container that supports multiple disjoint selections.

public : void AddToSelection()public void AddToSelection()Public Function AddToSelection() As void
Attributes

Clone() Clone() Clone()

Returns a new ITextRangeProvider that is identical to the original ITextRangeProvider and that inherits all the properties of the original.

public : ITextRangeProvider Clone()public ITextRangeProvider Clone()Public Function Clone() As ITextRangeProvider
Returns

The new text range. This method never returns null.

Attributes

Compare(ITextRangeProvider) Compare(ITextRangeProvider) Compare(ITextRangeProvider)

Returns a value that indicates whether the start and end points of a text range are the same as another text range.

public : PlatForm::Boolean Compare(ITextRangeProvider textRangeProvider)public bool Compare(ITextRangeProvider textRangeProvider)Public Function Compare(textRangeProvider As ITextRangeProvider) As bool
Parameters
textRangeProvider
ITextRangeProvider ITextRangeProvider ITextRangeProvider

A text range to compare to the implementing peer's text range.

Returns
PlatForm::Boolean bool bool

true if the span of both text ranges is identical; otherwise, false.

Attributes

CompareEndpoints(TextPatternRangeEndpoint, ITextRangeProvider, TextPatternRangeEndpoint) CompareEndpoints(TextPatternRangeEndpoint, ITextRangeProvider, TextPatternRangeEndpoint) CompareEndpoints(TextPatternRangeEndpoint, ITextRangeProvider, TextPatternRangeEndpoint)

Returns a value that indicates whether two text ranges have identical endpoints.

public : int CompareEndpoints(TextPatternRangeEndpoint endpoint, ITextRangeProvider textRangeProvider, TextPatternRangeEndpoint targetEndpoint)public int CompareEndpoints(TextPatternRangeEndpoint endpoint, ITextRangeProvider textRangeProvider, TextPatternRangeEndpoint targetEndpoint)Public Function CompareEndpoints(endpoint As TextPatternRangeEndpoint, textRangeProvider As ITextRangeProvider, targetEndpoint As TextPatternRangeEndpoint) As int
Parameters
endpoint
TextPatternRangeEndpoint TextPatternRangeEndpoint TextPatternRangeEndpoint

The Start or End endpoint of the caller.

textRangeProvider
ITextRangeProvider ITextRangeProvider ITextRangeProvider

The target range for comparison.

targetEndpoint
TextPatternRangeEndpoint TextPatternRangeEndpoint TextPatternRangeEndpoint

The Start or End endpoint of the target.

Returns
int int int

Returns a negative value if the caller's endpoint occurs earlier in the text than the target endpoint. Returns zero if the caller's endpoint is at the same location as the target endpoint. Returns a positive value if the caller's endpoint occurs later in the text than the target endpoint.

Attributes

ExpandToEnclosingUnit(TextUnit) ExpandToEnclosingUnit(TextUnit) ExpandToEnclosingUnit(TextUnit)

Expands the text range to the specified text unit.

public : void ExpandToEnclosingUnit(TextUnit unit)public void ExpandToEnclosingUnit(TextUnit unit)Public Function ExpandToEnclosingUnit(unit As TextUnit) As void
Parameters
unit
TextUnit TextUnit TextUnit

The text measure unit.

Attributes

FindAttribute(Int32, Object, Boolean) FindAttribute(Int32, Object, Boolean) FindAttribute(Int32, Object, Boolean)

Returns a text range subset that has the specified attribute ID and attribute value.

public : ITextRangeProvider FindAttribute(int attributeId, PlatForm::Object value, bool backward)public ITextRangeProvider FindAttribute(Int32 attributeId, Object value, Boolean backward)Public Function FindAttribute(attributeId As Int32, value As Object, backward As Boolean) As ITextRangeProvider
Parameters
attributeId
int Int32 Int32

The attribute ID to search for.

value
PlatForm::Object Object Object

The attribute value to search for. This value must match the type specified for the attribute.

backward
bool Boolean Boolean

true if the last occurring text range should be returned instead of the first; otherwise, false.

Returns

A text range that has a matching attribute ID and attribute value; otherwise null.

Attributes

FindText(String, Boolean, Boolean) FindText(String, Boolean, Boolean) FindText(String, Boolean, Boolean)

Returns a text range subset that contains the specified text.

public : ITextRangeProvider FindText(PlatForm::String text, bool backward, bool ignoreCase)public ITextRangeProvider FindText(String text, Boolean backward, Boolean ignoreCase)Public Function FindText(text As String, backward As Boolean, ignoreCase As Boolean) As ITextRangeProvider
Parameters
text
PlatForm::String String String

The text string to search for.

backward
bool Boolean Boolean

true to return the last occurring text range instead of the first; otherwise, false.

ignoreCase
bool Boolean Boolean

true to ignore case; otherwise, false.

Returns

A text range that matches the specified text; otherwise null.

Attributes

GetAttributeValue(Int32) GetAttributeValue(Int32) GetAttributeValue(Int32)

Retrieves the value of the specified attribute ID across the text range.

public : PlatForm::Object GetAttributeValue(int attributeId)public object GetAttributeValue(Int32 attributeId)Public Function GetAttributeValue(attributeId As Int32) As object
Parameters
attributeId
int Int32 Int32

The text attribute ID.

Returns
PlatForm::Object object object

Retrieves an object that represents the value of the specified attribute.

Attributes

GetBoundingRectangles(Double[]) GetBoundingRectangles(Double[]) GetBoundingRectangles(Double[])

Retrieves a collection of bounding rectangles for each fully or partially visible line of text in a text range.

public : void GetBoundingRectangles(double[] returnValue)public void GetBoundingRectangles(Double[] returnValue)Public Function GetBoundingRectangles(returnValue As Double[]) As void
Parameters
returnValue
double[] Double[] Double[]

An array of bounding rectangles for each full or partial line of text in a text range. An empty array for a degenerate range. An empty array for a text range that has screen coordinates placing it completely off-screen, scrolled out of view, or obscured by an overlapping window.

Attributes

GetChildren() GetChildren() GetChildren()

Retrieves a collection of all the embedded objects that exist within the text range.

public : IRawElementProviderSimple[] GetChildren()public IRawElementProviderSimple[] GetChildren()Public Function GetChildren() As IRawElementProviderSimple[]
Returns
IRawElementProviderSimple[] IRawElementProviderSimple[] IRawElementProviderSimple[]

A collection of child objects that exist within the range. Child objects that overlap with the text range but are not completely enclosed by it are also included in the collection. Returns an empty collection if no child objects exist.

Attributes

GetEnclosingElement() GetEnclosingElement() GetEnclosingElement()

Returns the innermost element that encloses the text range.

public : IRawElementProviderSimple GetEnclosingElement()public IRawElementProviderSimple GetEnclosingElement()Public Function GetEnclosingElement() As IRawElementProviderSimple
Returns

The enclosing control, typically the text provider that provides the text range. However, if the text provider supports child text elements such as tables or hyperlinks, the enclosing element can be a descendant of the text provider.

Attributes

GetText(Int32) GetText(Int32) GetText(Int32)

Retrieves the plain text of the range.

public : PlatForm::String GetText(int maxLength)public string GetText(Int32 maxLength)Public Function GetText(maxLength As Int32) As string
Parameters
maxLength
int Int32 Int32

The maximum length of the string to return. Use – 1 to specify an unlimited length.

Returns
PlatForm::String string string

The plain text of the text range, which might represent a portion of the full string truncated at the specified maxLength.

Attributes

Move(TextUnit, Int32) Move(TextUnit, Int32) Move(TextUnit, Int32)

Moves the text range the specified number of text units.

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

The text unit boundary.

count
int Int32 Int32

The number of text units to move. A positive value moves the text range forward; a negative value moves the text range backward; and a value of 0 has no effect.

Returns
int int int

The number of units actually moved. This value can be less than the count requested if either of the new text range endpoints is greater than or less than the DocumentRange endpoints. This value can be negative if navigation is happening in the backward direction.

Attributes

MoveEndpointByRange(TextPatternRangeEndpoint, ITextRangeProvider, TextPatternRangeEndpoint) MoveEndpointByRange(TextPatternRangeEndpoint, ITextRangeProvider, TextPatternRangeEndpoint) MoveEndpointByRange(TextPatternRangeEndpoint, ITextRangeProvider, TextPatternRangeEndpoint)

Moves one endpoint of a text range to the specified endpoint of a second text range.

public : void MoveEndpointByRange(TextPatternRangeEndpoint endpoint, ITextRangeProvider textRangeProvider, TextPatternRangeEndpoint targetEndpoint)public void MoveEndpointByRange(TextPatternRangeEndpoint endpoint, ITextRangeProvider textRangeProvider, TextPatternRangeEndpoint targetEndpoint)Public Function MoveEndpointByRange(endpoint As TextPatternRangeEndpoint, textRangeProvider As ITextRangeProvider, targetEndpoint As TextPatternRangeEndpoint) As void
Parameters
textRangeProvider
ITextRangeProvider ITextRangeProvider ITextRangeProvider

Another range from the same text provider.

targetEndpoint
TextPatternRangeEndpoint TextPatternRangeEndpoint TextPatternRangeEndpoint

An endpoint on the other range.

Attributes

MoveEndpointByUnit(TextPatternRangeEndpoint, TextUnit, Int32) MoveEndpointByUnit(TextPatternRangeEndpoint, TextUnit, Int32) MoveEndpointByUnit(TextPatternRangeEndpoint, TextUnit, Int32)

Moves one endpoint of the text range the specified number of text units within the document range.

public : int MoveEndpointByUnit(TextPatternRangeEndpoint endpoint, TextUnit unit, int count)public int MoveEndpointByUnit(TextPatternRangeEndpoint endpoint, TextUnit unit, Int32 count)Public Function MoveEndpointByUnit(endpoint As TextPatternRangeEndpoint, unit As TextUnit, count As Int32) As int
Parameters
unit
TextUnit TextUnit TextUnit

The text measure unit for moving.

count
int Int32 Int32

The number of units to move. A positive value moves the endpoint forward. A negative value moves it backward. A value of 0 has no effect.

Returns
int int int

The number of units actually moved, which can be less than the number requested if moving the endpoint runs into the beginning or end of the document.

Attributes

RemoveFromSelection() RemoveFromSelection() RemoveFromSelection()

From the collection of highlighted text in a text container that supports multiple disjoint selections, removes a highlighted section of text that corresponds to the caller's text range endpoints.

public : void RemoveFromSelection()public void RemoveFromSelection()Public Function RemoveFromSelection() As void
Attributes

ScrollIntoView(Boolean) ScrollIntoView(Boolean) ScrollIntoView(Boolean)

Causes the text control to scroll vertically until the text range is visible in the viewport.

public : void ScrollIntoView(bool alignToTop)public void ScrollIntoView(Boolean alignToTop)Public Function ScrollIntoView(alignToTop As Boolean) As void
Parameters
alignToTop
bool Boolean Boolean

true if the text control should be scrolled so that the text range is flush with the top of the viewport; false if the text range is flush with the bottom of the viewport.

Attributes

Select() Select() Select()

Highlights text in the text control that corresponds to the start and end endpoints of the text range.

public : void Select()public void Select()Public Function Select() As void
Attributes

See Also