ITextRangeProvider::GetEnclosingElement method (uiautomationcore.h)

Returns the innermost element that encloses the specified text range.

Syntax

HRESULT GetEnclosingElement(
  [out, retval] IRawElementProviderSimple **pRetVal
);

Parameters

[out, retval] pRetVal

Type: IRawElementProviderSimple**

The UI Automation provider of the innermost element that encloses the specified ITextRangeProvider.

Note

The enclosing element can span more than just the specified ITextRangeProvider.

If no enclosing element is found, the ITextProvider parent of the ITextRangeProvider is returned.

This parameter is passed uninitialized.

Return value

Type: HRESULT

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

Remarks

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

   • Both image and link are also descendents of the stream's ITextProvider, and either can be specified as the childElement in a call to ITextProvider::RangeFromChild.
   • Calling ITextRangeProvider::RangeFromChild, using either the image or the link, returns the same text range (Range1).
   • GetChildren does not return the link.
   • GetEnclosingElement does not return the image for any text range.
   • GetEnclosingElement on Range1 returns the link.
   • GetChildren on Range1 does not return any children.
   • GetEnclosingElement on the text range for the stream's ITextProvider returns the provider.
   • GetChildren on the text range for the stream's ITextProvider returns only the image.

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

   Start text

   Table Cell 1

   Table Cell 2

   End Text

   • Case 1: The stream's ITextProvider and entire text range
     • ITextRangeProvider::GetEnclosingElement on the entire text range returns the stream's ITextProvider.
     • GetChildren returns all child elements of the stream's ITextProvider, only the table element in this case.
   • Case 2: Text range obtained by calling ITextProvider::RangeFromChild on the table element:
     • ITextRangeProvider::GetEnclosingElement returns the table element.
     • ITextRangeProvider::GetChildren returns both table cells.
   • Case 3: Text range that spans the visual content of Table Cell 1 Table Cell 2:
     • ITextRangeProvider::GetEnclosingElement returns the table element.
     • ITextRangeProvider::GetChildren returns both table cells.
   • Case 4: Text range that spans the word Cell of Table Cell 1:
     • ITextRangeProvider::GetEnclosingElement returns the first cell element.
     • ITextRangeProvider::GetChildren returns no elements.
   • Case 5: A degenerate (empty) text range that represents both starts (table and first cell):
     • ITextRangeProvider::GetEnclosingElement returns the first cell element (the innermost element with a range that includes the degenerate range).
     • ITextRangeProvider::GetChildren returns no elements.

Requirements

Requirement	Value
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::GetChildren, UI Automation Providers Overview