Skip to content

XPath Navigator

Wraps the C# AutomationElementXPathNavigator for manual XPath-based navigation of the UI Automation tree. For most use cases prefer find_first_by_x_path / find_all_by_x_path; obtain a navigator with element.get_x_path_navigator().

flaui.core.xpath_navigator.AutomationElementXPathNavigator

Bases: BaseModel

Wraps the C# AutomationElementXPathNavigator for XPath-based tree navigation.

current_element property

Return the element at the navigator's current position.

Returns:

Type Description
'AutomationElement'

The current :class:~flaui.core.automation_elements.AutomationElement.

name property

Return the name of the current node (its control type, or attribute name).

Returns:

Type Description
str

The node name.

node_type property

Return the XPath node type of the current node (e.g. Root, Element).

Returns:

Type Description
str

The node type as a string.

value property

Return the string value of the current node.

Returns:

Type Description
str

The node value.

clone()

Return an independent copy of this navigator at the same position.

Returns:

Type Description
'AutomationElementXPathNavigator'

A cloned navigator.
Source code in flaui/core/xpath_navigator.py 
78
79
80
81
82
83
84
@handle_csharp_exceptions
def clone(self) -> "AutomationElementXPathNavigator":
    """Return an independent copy of this navigator at the same position.

    :return: A cloned navigator.
    """
    return AutomationElementXPathNavigator(raw_navigator=self.raw_navigator.Clone())

from_element(element) classmethod

Create a navigator rooted at the given element.

Parameters:

Name Type Description Default
element 'AutomationElement'

The element to use as the navigation root.

 required

Returns:

Type Description
'AutomationElementXPathNavigator'

A new :class:AutomationElementXPathNavigator.
Source code in flaui/core/xpath_navigator.py 
29
30
31
32
33
34
35
36
37
38
@classmethod
def from_element(cls, element: "AutomationElement") -> "AutomationElementXPathNavigator":
    """Create a navigator rooted at the given element.

    :param element: The element to use as the navigation root.
    :return: A new :class:`AutomationElementXPathNavigator`.
    """
    from FlaUI.Core import AutomationElementXPathNavigator as CSNavigator  # pyright: ignore

    return cls(raw_navigator=CSNavigator(element.raw_element))

get_attribute(name)

Return the value of a named attribute on the current element.

Supported attribute names mirror the C# navigator: AutomationId, Name, ClassName, HelpText, IsPassword, FullDescription, ItemType, AcceleratorKey, AccessKey, IsEnabled, IsOffscreen, ProcessId.

Parameters:

Name Type Description Default
name str

The attribute name.

 required

Returns:

Type Description
Optional[str]

The attribute value, or an empty string when unset.
Source code in flaui/core/xpath_navigator.py 
123
124
125
126
127
128
129
130
131
132
133
134
@handle_csharp_exceptions
def get_attribute(self, name: str) -> Optional[str]:
    """Return the value of a named attribute on the current element.

    Supported attribute names mirror the C# navigator: ``AutomationId``, ``Name``, ``ClassName``,
    ``HelpText``, ``IsPassword``, ``FullDescription``, ``ItemType``, ``AcceleratorKey``,
    ``AccessKey``, ``IsEnabled``, ``IsOffscreen``, ``ProcessId``.

    :param name: The attribute name.
    :return: The attribute value, or an empty string when unset.
    """
    return self.raw_navigator.GetAttribute(name, "")

move_to_first_child()

Move to the first child of the current element.

Returns:

Type Description
bool

True if moved, False if there is no child.
Source code in flaui/core/xpath_navigator.py 
91
92
93
94
95
96
97
@handle_csharp_exceptions
def move_to_first_child(self) -> bool:
    """Move to the first child of the current element.

    :return: ``True`` if moved, ``False`` if there is no child.
    """
    return self.raw_navigator.MoveToFirstChild()

move_to_next()

Move to the next sibling of the current element.

Returns:

Type Description
bool

True if moved, False if there is no next sibling.
Source code in flaui/core/xpath_navigator.py 
107
108
109
110
111
112
113
@handle_csharp_exceptions
def move_to_next(self) -> bool:
    """Move to the next sibling of the current element.

    :return: ``True`` if moved, ``False`` if there is no next sibling.
    """
    return self.raw_navigator.MoveToNext()

move_to_parent()

Move to the parent of the current element.

Returns:

Type Description
bool

True if moved, False if already at the root.
Source code in flaui/core/xpath_navigator.py 
 99
100
101
102
103
104
105
@handle_csharp_exceptions
def move_to_parent(self) -> bool:
    """Move to the parent of the current element.

    :return: ``True`` if moved, ``False`` if already at the root.
    """
    return self.raw_navigator.MoveToParent()

move_to_previous()

Move to the previous sibling of the current element.

Returns:

Type Description
bool

True if moved, False if there is no previous sibling.
Source code in flaui/core/xpath_navigator.py 
115
116
117
118
119
120
121
@handle_csharp_exceptions
def move_to_previous(self) -> bool:
    """Move to the previous sibling of the current element.

    :return: ``True`` if moved, ``False`` if there is no previous sibling.
    """
    return self.raw_navigator.MoveToPrevious()

move_to_root()

Move the navigator to the root element.

Source code in flaui/core/xpath_navigator.py 
86
87
88
89
@handle_csharp_exceptions
def move_to_root(self) -> None:
    """Move the navigator to the root element."""
    self.raw_navigator.MoveToRoot()