WidgetRef#

class omni.kit.ui_test.WidgetRef( widget: Widget, path: str, window: Window = None, )#

Bases: object

Reference to `omni.ui.Widget` and a path it was found with.

Parameters:

widget (ui.Widget) – The widget to reference.
path (str) – The path where the widget was found.
window (ui.Window, optional) – The window containing the widget. If not provided, it will be determined from the path.

Methods

`__init__`(widget, path[, window])	Initializes a WidgetRef object.
`bring_to_front`()	Bring window this widget belongs to on top.
`click`([pos, right_click, double, ...])	Emulate mouse click on the widget.
`double_click`([pos, human_delay_speed])	Emulates a double mouse click on the widget.
`drag_and_drop`(drop_target[, human_delay_speed])	Drag/drop for widget.centre to `drop_target`
`find`(path)	Find omni.ui Widget or Window by search query starting from this widget.
`find_all`(path)	Find all omni.ui Widget or Window by search query starting from this widget.
`find_first`(path)	Find the first omni.ui Widget or Window by search query starting from this widget.
`find_with_retry`(widget_id[, max_retries])	Find widget by retrying the search operation up to the specified number of times.
`focus`()	Focus on a window this widget belongs to.
`input`(text[, end_key, human_delay_speed, ...])	Emulate keyboard input of characters (text) into the widget.
`offset`(*kwargs)	Calculates an offset position from the widget's position.
`right_click`([pos, human_delay_speed])	Emulates a right mouse click on the widget.
`undock`()	Undock a window this widget belongs to.

Attributes

`center`	Gets the center of the widget.
`model`	Gets the model associated with the widget.
`path`	Gets the path this widget was found with.
`position`	Gets the screen position of widget's top left corner.
`realpath`	Gets the actual unique path to this widget from the window.
`size`	Gets the computed size of the widget.
`widget`	Gets the underlying omni.ui.Widget.
`window`	Gets the window containing the widget.

__init__( widget: Widget, path: str, window: Window = None, )#: Initializes a WidgetRef object.

async bring_to_front()#: Bring window this widget belongs to on top. Currently this is implemented as undock() + focus().

async click( pos: Vec2 = None, right_click=False, double=False, human_delay_speed: int = 2, )#

Emulate mouse click on the widget.

Parameters:

pos (Vec2) – Position to click; defaults to widget center.
right_click (bool) – Whether to perform a right click.
double (bool) – Whether to perform a double click.
human_delay_speed (int) – Delay speed for human-like interaction timing.

async double_click(pos=None, human_delay_speed: int = 2)#

Emulates a double mouse click on the widget.

Parameters:

pos (Vec2) – Position to double click; defaults to widget center.
human_delay_speed (int) – Delay speed for human-like interaction timing.

async drag_and_drop( drop_target: Vec2, human_delay_speed: int = 4, )#

Drag/drop for widget.centre to `drop_target`

Parameters:

drop_target (Vec2) – Target position to drop the widget.
human_delay_speed (int) – Delay speed for human-like interaction timing.

find(path: str) → WidgetRef#

Find omni.ui Widget or Window by search query starting from this widget.

stage_window = ui_test.find("Stage//Frame/**/ScrollingFrame/TreeView[*].visible==True")
label = stage_window.find("**/Label[*].text=='hello'")
await label.right_click()

Parameters:: path (str) – Search query to locate the widget.
Returns:: Found Widget or Window wrapped into WidgetRef object.
Return type:: WidgetRef

find_all( path: str, ) → List[WidgetRef]#

Find all omni.ui Widget or Window by search query starting from this widget.

stage_window = ui_test.find("Stage//Frame/**/ScrollingFrame/TreeView[*].visible==True")
labels = stage_window.find_all("**/Label[*]")
for label in labels:
    await label.right_click()

Parameters:: path (str) – Search query to locate the widgets.
Returns:: List of found Widget or Window wrapped into WidgetRef objects.
Return type:: List[WidgetRef]

find_first(path: str) → WidgetRef#

Find the first omni.ui Widget or Window by search query starting from this widget.

stage_window = ui_test.find("Stage//Frame/**/ScrollingFrame/TreeView[*].visible==True")
label = stage_window.find_first("**/Label[*]")
await label.right_click()

Parameters:: path (str) – Search query to locate the first widget.
Returns:: Widget or Window wrapped into WidgetRef object.
Return type:: WidgetRef

async find_with_retry(widget_id, max_retries=50)#

Find widget by retrying the search operation up to the specified number of times.

Retries the widget search operation with app frame updates between attempts until the widget is found or maximum retries is reached.

Parameters:

widget_id (str) – Widget identifier for the search query.
max_retries (int) – Maximum number of retry attempts.

Returns:

Found widget wrapped into WidgetRef object, or None if not found.

Return type:

WidgetRef

async focus()#: Focus on a window this widget belongs to.

async input( text: str, end_key=<KeyboardInput.ENTER: 51>, human_delay_speed: int = 2, clear_before_input: bool = False, force_input: bool = False, )#

Emulate keyboard input of characters (text) into the widget.

It is a helper function for the following sequence:

Double click on the widget

Input characters

Press enter

Parameters:

text (str) – Text to input into the widget.
end_key (KeyboardInput) – Key to press after text input; defaults to ENTER.
human_delay_speed (int) – Delay speed for human-like interaction timing.
clear_before_input (bool) – Whether to clear existing content before input.
force_input (bool) – Whether to force input by directly setting model value.

offset(*kwargs) → Vec2#

Calculates an offset position from the widget’s position.

Returns:: The widget’s position plus the specified offset, or None if invalid arguments.
Return type:: Vec2

async right_click(pos=None, human_delay_speed: int = 2)#

Emulates a right mouse click on the widget.

Parameters:

pos (Vec2) – Position to right click; defaults to widget center.
human_delay_speed (int) – Delay speed for human-like interaction timing.

async undock()#: Undock a window this widget belongs to.

property center: Vec2#

Gets the center of the widget.

Returns:: Center of the widget.
Return type:: Vec2

property model#

Gets the model associated with the widget.

Returns:: The widget’s model.

property path: str#

Gets the path this widget was found with.

Returns:: Path this widget was found with.
Return type:: str

property position: Vec2#

Gets the screen position of widget’s top left corner.

Returns:: Screen position of widget’s top left corner.
Return type:: Vec2

property realpath: str#

Gets the actual unique path to this widget from the window.

Returns:: Actual unique path to this widget from the window.
Return type:: str

property size: Vec2#

Gets the computed size of the widget.

Returns:: Computed size of the widget.
Return type:: Vec2

property widget: Widget#

Gets the underlying omni.ui.Widget.

Returns:: The widget instance.
Return type:: ui.Widget

property window: Window#

Gets the window containing the widget.

Returns:: The window instance.
Return type:: ui.Window