IUIAutomationTextRange::Move method (uiautomationclient.h)
Moves the text range forward or backward by the specified number of text units .
Syntax
HRESULT Move(
[in] TextUnit unit,
[in] int count,
[out, retval] int *moved
);
Parameters
[in] unit
Type: TextUnit
A value specifying the type of text units, such as character, word, paragraph, and so on.
[in] count
Type: int
The number of text units to move. A positive value moves the text range forward. A negative value moves the text range backward. Zero has no effect.
[out, retval] moved
Type: int*
Receives the number of text 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 endpoints retrieved by the IUIAutomationTextPattern::DocumentRange method. This value can be negative if navigation is happening in the backward direction.
Return value
Type: HRESULT
If this method succeeds, it returns S_OK. Otherwise, it returns an HRESULT error code.
Remarks
IUIAutomationTextRange::Move moves the text range to span a different part of the text; it does not alter the text in any way.
For a non-degenerate (non-empty) text range, IUIAutomationTextRange::Move normalizes and moves the range by performing the following steps.
- The text range is collapsed to a degenerate (empty) range at the starting endpoint.
- If necessary, the resulting text range is moved backward in the document to the beginning of the requested text unit boundary.
- The text range is moved forward or backward in the document by the requested number of text unit boundaries.
- The text range is expanded from the degenerate state by moving the ending endpoint forward by one requested text unit boundary.
For a degenerate text range, IUIAutomationTextRange::Move simply moves the text insertion point by the specified number of text units.
When moving a text range, IUIAutomationTextRange::Move ignores the boundaries of any embedded objects in the text.
IUIAutomationTextRange::Move respects both hidden and visible text.
If a text-based control does not support the text unit specified by the unit parameter, IUIAutomationTextRange::Move substitutes the next larger supported text unit.
The size of the text units, from smallest unit to largest, is as follows.
- Character
- Format
- Word
- Line
- Paragraph
- Page
- Document
Range behavior when unit is TextUnit::Format
TextUnit::Format
as a unit value positions the boundary of a text range to expand or move the range based on shared text attributes (format) of the text within the range. However, using the format text unit will not move or expand a text range across the boundary of an embedded object, such as an image or hyperlink. For more info, see UI Automation Text Units or UI Automation Support for Textual Content.
Requirements
Requirement | Value |
---|---|
Minimum supported client | Windows 7, Windows Vista with SP2 and Platform Update for Windows Vista, Windows XP with SP3 and Platform Update for Windows Vista [desktop apps only] |
Minimum supported server | Windows Server 2008 R2, Windows Server 2008 with SP2 and Platform Update for Windows Server 2008, Windows Server 2003 with SP2 and Platform Update for Windows Server 2008 [desktop apps only] |
Target Platform | Windows |
Header | uiautomationclient.h (include UIAutomation.h) |