ITextProvider::RangeFromChild method

Retrieves a text range that encloses the specified child element (for example, an image, hyperlink, or other embedded object).

Syntax

HRESULT RangeFromChild(
  IRawElementProviderSimple *childElement,
  ITextRangeProvider        **pRetVal
);

Parameters

childElement

Type: IRawElementProviderSimple*

The UI Automation provider of the specified child element.

pRetVal

Type: ITextRangeProvider**

The text range that encloses the child element.

This range completely encloses the content of the child element such that:

  1. ITextRangeProvider::GetEnclosingElement returns the child element itself, or the innermost descendant of the child element that shares the same text range as the child element
  2. ITextRangeProvider::GetChildren returns children of the element from (1) that are completely enclosed within the range
  3. Both endpoints of the range are at the boundaries of the child element

This parameter is passed uninitialized.

Return Value

Type: HRESULT

If this method succeeds, it returns S_OK. Otherwise, it returns an HRESULT error code.

Note

E_INVALIDARG is returned if childElement is not a descendent of an ITextProvider, or is not enclosed by a valid text range.

Remarks

Each element retrieved with ITextRangeProvider::GetChildren also has a valid text range that can be retrieved through RangeFromChild. This includes any elements in the UI Automation tree between the ITextProvider and the child element.

Examples

  1. This example shows a text stream that contains an image link. The link is a child of the image, but both span the same text range and are exposed as embedded objects within the text stream.

    Hello <Image Link> World

  2. This example shows a text stream that contains a two-cell table surrounded by text.

    Start text

    Table Cell 1Table Cell 2

    End Text

Requirements

   
Minimum supported client Windows XP [desktop apps | UWP apps]
Minimum supported server Windows Server 2003 [desktop apps | UWP apps]
Target Platform Windows
Header uiautomationcore.h (include UIAutomation.h)

See Also

ITextProvider, ITextRangeProvider, ITextRangeProvider::GetEnclosingElement, ITextRangeProvider::GetChildren, UI Automation Providers Overview