ITextRangeProvider.Move(TextUnit, Int32) Method

Reference

Definition

Namespace:: System.Windows.Automation.Provider

Assembly:: UIAutomationProvider.dll

Assemblies:: UIAutomationProvider.dll, UIAutomationTypes.dll

Assembly:: UIAutomationTypes.dll

Important

Some information relates to prerelease product that may be substantially modified before it’s released. Microsoft makes no warranties, express or implied, with respect to the information provided here.

Moves the text range the specified number of text units.

public:
 int Move(System::Windows::Automation::Text::TextUnit unit, int count);

public int Move (System.Windows.Automation.Text.TextUnit unit, int count);

abstract member Move : System.Windows.Automation.Text.TextUnit * int -> int

Public Function Move (unit As TextUnit, count As Integer) As Integer

Parameters

unit: TextUnit

The text unit boundary.

count: 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 0 has no effect.

Returns

Int32

The number of units actually moved. This can be less than the number requested if either of the new text range endpoints is greater than or less than the DocumentRange endpoints.

Remarks

When it is necessary to traverse the content of a text range, a series of steps are involved behind the scenes in order for the Move method to execute successfully.

The text range is normalized; that is, the text range is collapsed to a degenerate range at the Start endpoint, which makes the End endpoint superfluous. This step is necessary to remove ambiguity in situations where a text range spans unit boundaries; for example, "{The U}RL https://www.microsoft.com/ is embedded in text" where "{" and "}" are the text range endpoints.
The resulting range is moved backward in the DocumentRange to the beginning of the requested unit boundary.
The range is moved forward or backward in the DocumentRange by the requested number of unit boundaries.
The range is then expanded from a degenerate range state by moving the End endpoint by one requested unit boundary.

Range adjustments by Move & ExpandToEnclosingUnit
Examples of how a text range is adjusted for Move() and ExpandToEnclosingUnit()

The textual content (or inner text) of a text container and an embedded object, such as a hyperlink or table cell, is exposed as a single, continuous text stream in both the control view and the content view of the UI Automation tree; object boundaries are ignored.

Text ranges spanned by embedded objects.
Example of a text stream with embedded objects and their range spans

Move respects both hidden and visible text.

Move defers to the next largest TextUnit supported if the given TextUnit is not supported by the control.

The order, from smallest unit to largest, is listed below.

The text is not altered in any way, the text range just spans a different part of the text.

Applies to