Tree navigation methods

Tree navigation methods allow you to programmatically traverse the UIA object hierarchy at runtime. You can retrieve parent, direct children, ancestor, or descendant objects.

When to use tree navigation

Use tree navigation in these scenarios:

Controls are dynamically added, removed, or reordered at runtime.
You need to discover objects based on runtime conditions.

Available navigation methods

The enhanced UIA Pro add-in provides the following methods for traversing the object hierarchy:

GetUIAParent returns the object's immediate parent object.
GetUIAAncestors returns all parent objects in the hierarchy up to the root. You can optionally specify a description, a minimum depth level, and a maximum depth level.
GetUIAChildren returns all immediate children within the object. You can optionally specify a description.
GetUIADescendants returns all objects contained or nested beneath the object. You can optionally specify a description, a minimum depth level, and a maximum depth level.

Note: These navigation methods are only compatible with the enhanced UIA Pro add-in.

If you attempt to call these methods with the previous version of UIA Pro, an exception is thrown that indicates the required UIA Pro version.

Code examples

The following examples demonstrate how to use the GetUIAAncestors method to retrieve all ancestor objects from a table control up to the root.

Java

Copy code

@Test
public void testGetUIAAncestors() throws GeneralLeanFtException {
    // Describe and identify a table control as the starting point
    Table uIAProTable = Desktop.describe(Pane.class, new PaneDescription.Builder()
            .processName("MyApp")
            .name("Main Window")
            .path("Pane")
            .frameworkId("Win32")
            .controlType("Pane").build())
    .describe(Pane.class, new PaneDescription.Builder()
            .processName("MyApp")
            .name("Content Pane")
            .path("Pane;Pane")
            .frameworkId("Win32")
            .controlType("Pane").build())
    .describe(Table.class, new TableDescription.Builder()
            .processName("MyApp")
            .path("Pane;Pane;Group;Group;Table")
            .frameworkId("Win32")
            .controlType("Table").build());
    
    // Get all ancestor objects from the table to the root
    UiObjectBase[] ancestors = uIAProTable.getUIAAncestors();
    
    // Iterate through ancestors and print their native class names
    Arrays.stream(ancestors).forEach((ancestor) -> {
        try {
            System.out.println(ancestor.getNativeClass());
        } catch (GeneralLeanFtException e) {
            throw new RuntimeException(e);
        }
    });
}

.NET

Copy code

[TestMethod]
public void TestGetUIAAncestors()
{
    // Describe and identify a table control as the starting point
    var table = Desktop.Describe<IPane>(new PaneDescription
    {
        ProcessName = @"MyApp",
        Name = @"Main Window",
        Path = @"Pane",
        FrameworkId = @"Win32",
        ControlType = @"Pane"
    })
    .Describe<IPane>(new PaneDescription
    {
        ProcessName = @"MyApp",
        Name = @"Content Pane",
        Path = @"Pane;Pane",
        FrameworkId = @"Win32",
        ControlType = @"Pane"
    })
    .Describe<ITable>(new TableDescription
    {
        ProcessName = @"MyApp",
        Path = @"Pane;Pane;Group;Group;Table",
        FrameworkId = @"Win32",
        ControlType = @"Table"
    });
    
    // Get all ancestor objects from the table to the root
    var ancestors = table.GetUIAAncestors();
    
    // Iterate through ancestors and print their native class names
    foreach (var ancestor in ancestors)
    {
        Console.WriteLine(ancestor.NativeClass);
    }
}

JavaScript

Copy code

it("Should test getUIAAncestors", function(done) {
    // Describe and identify a table control as the starting point
    var uIAProTable = Desktop.$(UIAPro.Pane({
        processName: "MyApp",
        name: "Main Window",
        path: "Pane",
        frameworkId: "Win32",
        controlType: "Pane"
    }))
    .$(UIAPro.Pane({
        processName: "MyApp",
        name: "Content Pane",
        path: "Pane;Pane",
        frameworkId: "Win32",
        controlType: "Pane"
    }))
    .$(UIAPro.Table({
        processName: "MyApp",
        path: "Pane;Pane;Group;Group;Table",
        frameworkId: "Win32",
        controlType: "Table"
    }));
    
    // Get all ancestor objects from the table to the root
    uIAProTable.getUIAAncestors().then(ancestors => {
        // Iterate through ancestors and print their native class names
        ancestors.forEach(ancestor => {
            console.log(ancestor.nativeClass);
        });
    });
    whenDone(done);
});

Important notes

Performance: Retrieving multiple objects is time consuming and may affect performance. Consider limiting the results using description or depth parameters.
Object availability: You can only access retrieved objects while the method's test object is available. Use them immediately.
UIA framework: The methods return test objects for any UI elements that the UIA framework exposes (as shown in Microsoft Inspect tool).

Method reference and additional examples

For a complete list of available navigation methods, method signatures, and comprehensive code examples in all supported SDKs (.NET, Java, and JavaScript), see: