Share via

IUIAutomationTextRange::Move Method

  • Article

Moves the text range the specified number of text units.

Syntax

HRESULT Move(      
    TextUnit unit,
    int count,
    int *moved
);

Parameters

  • unit
    [in] A value from the TextUnit enumerated type specifying the text unit, such as line or paragraph.
  • count
    [in] 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.
  • moved
    [out, retval] The address of a variable that receives 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 endpoints of the document range.

Return Value

Returns S_OK if successful, or an error value otherwise.

Remarks

When the content of a text range is traversed, the following steps happen in the background so that the IUIAutomationTextRange::Move method can run successfully.

  1. The text range is normalized; that is, the text range is collapsed to a degenerate (empty) 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.
  2. The resulting range is moved backward in the DocumentRange to the beginning of the requested unit boundary.
  3. The range is moved forward or backward in the DocumentRange by the requested number of unit boundaries.
  4. The range is then expanded from a degenerate range state by moving the End endpoint by one requested unit boundary.