F(x)

catch(title, mode='start', process_name=None, class_name=None, timeout=10)

Description

Captures a window object based on its title.

Parameters

title<str> The window title to match.

mode<str> The window matching mode.

Valid options:

• start: Matches a title that starts with the specified string.

• substr: Matches a title that contains the specified string.

• exact: Matches the exact window title.

• reg: Matches the title using regular expression matching.

process_name<str> The name of the process associated with the window.

class_name<str> The window class name.

timeout<int> The maximum time in seconds to wait for the window. Defaults to 10.

Returns

Returns a window object<Window>.

Code example

# Note: Ensure the target application window is open before using this method.
# Example:
wnd = rpa.ui.win32.catch('钉钉',mode='exact',process_name='DingTalk')

click(x=None, y=None, button='left')

Description

Performs a mouse click at the specified coordinates.

Parameters

button<str> The mouse button to use for the click.

Valid options:

• left: Left mouse button.

• right: Right mouse button.

Code example

# Note: None.
# Example:
rpa.ui.win32.click(x=500,y=500,button='left')

double_click(x=None, y=None)

Description

Performs a mouse double-click at the specified coordinates.

Code example

# Note: None.
# Example:
rpa.ui.win32.double_click(x=500,y=500)

drag(start_x, start_y, *, x=0, y=0, speed_mode='uniform')

Description

Drags the mouse from a starting point by a specified offset.

Parameters

start_x<int> The starting x-coordinate.

start_y<int> The starting y-coordinate.

x<int> The horizontal offset to drag.

y<int> The vertical offset to drag.

speed_mode<str> The speed profile of the drag operation.

Valid options:

• uniform: Drags at a constant speed.

• fast-slow-pause: Simulates human-like motion by accelerating, then decelerating, and finally pausing to align.

Code example

# Note: None.
# Example:
rpa.ui.win32.drag(100,200,x=300,y=200, speed_mode='uniform')

# Example:
rpa.ui.win32.input_text("test")

# Note: Driver-based input requires administrator privilege. To use driver-based input, you must run both the editor and the robot with administrator privilege.
# Example:
rpa.ui.win32.drive_input("test")

# Note: Driver-based input requires administrator privilege. To use driver-based input, you must run both the editor and the robot with administrator privilege.
# Example:
rpa.ui.win32.drive_input_hotkey("VK_RETURN")

mouse_move(x, y)

Description

Moves the mouse cursor to the specified coordinates.

Code example

# Note: None.
# Example:
rpa.ui.win32.mouse_move(500,500)

capture(file, x1, y1, x2, y2)

Description

Takes a screenshot of a specified rectangular area on the screen.

Code example

# Note: None.
# Example:
path =  r'D:\Test_File_Archive\screenshot.jpg'
rpa.ui.win32.capture(path,0,0,500,500)

win_activate(title, mode='start')

Description

Activates a window, bringing it to the foreground.

Parameters

title<str> The window title to match.

mode<str> The window matching mode.

Valid options:

• start: Matches a title that starts with the specified string.

• substr: Matches a title that contains the specified string.

• exact: Matches the exact window title.

• reg: Matches the title using regular expression matching.

Code example

# Note: Ensure the process for the target window exists.
# Example: The following brings the Notepad window to the foreground.
rpa.ui.win32.win_activate("test.txt - Notepad")

win_maximize(title, mode='start')

Description

Maximizes the specified window.

Parameters

title<str> The window title to match.

mode<str> The window matching mode.

Valid options:

• start: Matches a title that starts with the specified string.

• substr: Matches a title that contains the specified string.

• exact: Matches the exact window title.

• reg: Matches the title using regular expression matching.

Code example

# Note: Ensure the process for the target window exists.
# Example: The following maximizes the Notepad window.
rpa.ui.win32.win_maximize("test.txt - Notepad")

win_minimize(title, mode='start')

Description

Minimizes the specified window.

Parameters

title<str> The window title to match.

mode<str> The window matching mode.

Valid options:

• start: Matches a title that starts with the specified string.

• substr: Matches a title that contains the specified string.

• exact: Matches the exact window title.

• reg: Matches the title using regular expression matching.

Code example

# Note: Ensure the process for the target window exists.
# Example: The following minimizes the Notepad window.
rpa.ui.win32.win_minimize("test.txt - Notepad")

win_hide(title, mode='start')

Description

Hides the specified window.

Parameters

title<str> The window title to match.

mode<str> The window matching mode.

Valid options:

• start: Matches a title that starts with the specified string.

• substr: Matches a title that contains the specified string.

• exact: Matches the exact window title.

• reg: Matches the title using regular expression matching.

Code example

# Note: This method removes the window from the taskbar. A hidden window's process is only visible in Task Manager.
# Example:
rpa.ui.win32.win_hide("test.txt - Notepad")

win_show(title, mode='start')

Description

Shows a previously hidden window.

Parameters

title<str> The window title to match.

mode<str> The window matching mode.

Valid options:

• start: Matches a title that starts with the specified string.

• substr: Matches a title that contains the specified string.

• exact: Matches the exact window title.

• reg: Matches the title using regular expression matching.

Code example

# Note: None.
# Example:
rpa.ui.win32.win_show("test.txt - Notepad")

win_exists(title, mode='start')

Description

Checks if a window exists.

Parameters

title<str> The window title to match.

mode<str> The window matching mode.

Valid options:

• start: Matches a title that starts with the specified string.

• substr: Matches a title that contains the specified string.

• exact: Matches the exact window title.

• reg: Matches the title using regular expression matching.

Returns

Returns True if the window exists; otherwise, returns False<bool>.

Code example

# Note: None.
# Example:
exist_flag = rpa.ui.win32.win_exists("test.txt - Notepad")

win_close(title, mode='start')

Description

Closes the specified window.

Parameters

title<str> The window title to match.

mode<str> The window matching mode.

Valid options:

• start: Matches a title that starts with the specified string.

• substr: Matches a title that contains the specified string.

• exact: Matches the exact window title.

• reg: Matches the title using regular expression matching.

Code example

# Note: None.
# Example:
rpa.ui.win32.win_close("test.txt - Notepad")

win_wait_appear(title, timeout=30)

Description

Waits for a specified window to appear.

Parameters

title<str> The window title to wait for.

timeout<int> The maximum time in seconds to wait. Defaults to 30.

Code example

# Note: None.
# Example:
rpa.ui.win32.win_wait_appear("test.txt - Notepad",timeout=10)

win_wait_disappear(title, timeout=30)

Description

Waits for a specified window to disappear.

Parameters

title<str> The window title to wait for.

timeout<int> The maximum time in seconds to wait. Defaults to 30.

Code example

# Note: None.
# Example:
rpa.ui.win32.win_wait_disappear("test.txt - Notepad",timeout=10)

elem_drag(element, *, x=0, y=0, speed_mode='uniform', index=1, parent_element=None, timeout=10)

Description

Drags a specified element by a given offset.

Parameters

element<str> The name of the element to drag.

x<int> The horizontal offset to drag.

y<int> The vertical offset to drag.

speed_mode<str> The speed profile of the drag operation.

Valid options:

• uniform: Drags at a constant speed.

• fast-slow-pause: Simulates human-like motion by accelerating, then decelerating, and finally pausing to align.

index<int> If multiple elements share the same name, specifies the 1-based index of the target element.

parent_element<Element> A parent element object that limits the search scope.

timeout<int> The maximum time in seconds to wait for the element. Defaults to 10.

Code example

# Note:
# Before using this method, capture the target UI element.
# When the method runs, ensure the corresponding window is open and its title matches the one recorded during capture.
# Example:
rpa.ui.win32.elem_drag("Slider_Control",x=100,y=0, speed_mode='uniform', index=1)

elem_input_text(element, value, index=1, parent_element=None, simulate=True, replace=True, send_window_message=True, sent_raw=False, wait_mili_seconds=20, timeout=10)

Description

Inputs text into a specified element.

Parameters

element<str> The name of the target element.

value<str> The text content to input.

index<int> If multiple elements share the same name, specifies the 1-based index of the target element.

parent_element<Element> A parent element object that limits the search scope.

simulate<bool> Specifies whether to simulate human-like typing.

replace<bool> If set to True, clears any existing content before inputting new text.

send_window_message<bool> Specifies whether to send a Windows message for the input.

sent_raw<bool> Specifies whether to send raw key events.

wait_mili_seconds<int> The delay interval between characters in milliseconds. This parameter is effective only when simulate is True. The default is 20, and the maximum is 100. Setting this value too high may cause a timeout.

timeout<int> The maximum time in seconds to wait for the element. Defaults to 10.

Code example

# Note:
# Before using this method, capture the target UI element.
# When the method runs, ensure the corresponding window is open and its title matches the one recorded during capture.
# Example:
text = "RPA_Test"
rpa.ui.win32.elem_input_text("Notepad_Input_Area",text)

# Note:
# Before using this method, capture the target UI element.
# When the method runs, ensure the corresponding window is open and its title matches the one recorded during capture.
# For information on virtual-key code format, see: https://help.aliyun.com/document_detail/218003.html
# Example:
rpa.ui.win32.elem_input_hotkeys("Notepad_Input_Area","VK_RETURN")

# Note:
# Driver-based input requires administrator privilege. To use driver-based input, you must run both the editor and the robot with administrator privilege.
# Before using this method, capture the target UI element.
# When the method runs, ensure the corresponding window is open and its title matches the one recorded during capture.
# Example:
rpa.ui.win32.elem_drive_input("Notepad_Input_Area","TEST")

elem_click(element, index=1, simulate=True, button='left', parent_element=None, timeout=10)

Description

Clicks a specified element.

Parameters

element<str> The name of the element to click.

index<int> If multiple elements share the same name, specifies the 1-based index of the target element.

simulate<bool> Specifies whether to simulate the click.

button<str> The mouse button to use for the click.

Valid options:

• left: Left mouse button.

• right: Right mouse button.

parent_element<Element> A parent element object that limits the search scope.

timeout<int> The maximum time in seconds to wait for the element. Defaults to 10.

Code example

# Note:
# Before using this method, capture the target UI element.
# When the method runs, ensure the corresponding window is open and its title matches the one recorded during capture.
# Example:
rpa.ui.win32.elem_click("Notepad_Input_Area")

elem_get_checked_state(element, index=1, parent_element=None, timeout=10)

Description

Gets the state of a checkbox element.

Parameters

element<str> The name of the checkbox element.

index<int> If multiple elements share the same name, specifies the 1-based index of the target element.

parent_element<Element> A parent element object that limits the search scope.

timeout<int> The maximum time in seconds to wait for the element. Defaults to 10.

Returns

Returns True if the checkbox is checked; otherwise, returns False<bool>.

Code example

# Note:
# Before using this method, capture the target UI element.
# When the method runs, ensure the corresponding window is open and its title matches the one recorded during capture.
# Example:
flag = rpa.ui.win32.elem_get_checked_state("Checkbox_Element")

elem_set_checked_state(element, value=True, index=1, parent_element=None, timeout=10)

Description

Sets the state of a checkbox element.

Parameters

element<str> The name of the checkbox element.

value<bool> Set to True to check the checkbox, or False to uncheck it.

index<int> If multiple elements share the same name, specifies the 1-based index of the target element.

parent_element<Element> A parent element object that limits the search scope.

timeout<int> The maximum time in seconds to wait for the element. Defaults to 10.

Code example

# Note:
# Before using this method, capture the target UI element.
# When the method runs, ensure the corresponding window is open and its title matches the one recorded during capture.
# Example:
rpa.ui.win32.elem_set_checked_state("Checkbox_Element",value=False)

elem_text(element, index=1, parent_element=None, timeout=10)

Description

Gets the text content of a specified element.

Parameters

element<str> The name of the target element.

index<int> If multiple elements share the same name, specifies the 1-based index of the target element.

parent_element<Element> A parent element object that limits the search scope.

timeout<int> The maximum time in seconds to wait for the element. Defaults to 10.

Returns

Returns the text of the element<str>.

Code example

# Note:
# Before using this method, capture the target UI element.
# When the method runs, ensure the corresponding window is open and its title matches the one recorded during capture.
# Example:
rpa.ui.win32.elem_text("Title_Bar")

get_element_by_name(element, index=1, parent_element=None, timeout=10)

Description

Gets an element object by its name.

Parameters

element<str> The name of the target element.

index<int> If multiple elements share the same name, specifies the 1-based index of the target element.

parent_element<Element> A parent element object that limits the search scope.

timeout<int> The maximum time in seconds to wait for the element. Defaults to 10.

Returns

Returns the element object<Element>.

Code example

# Note: None.
# Example:
element = rpa.ui.win32.get_element_by_name("Notepad_Input_Area")

elem_count(element, parent_element=None, timeout=10)

Description

Gets the number of elements that match the specified name.

Parameters

element<str> The name of the element to count.

parent_element<Element> A parent element object that limits the search scope.

timeout<int> The maximum time in seconds to wait for the element. Defaults to 10.

Returns

Returns the count of matching elements<int>.

Code example

# Note:
# Before using this method, capture the target UI element.
# When the method runs, ensure the corresponding window is open and its title matches the one recorded during capture.
# Example:
count = rpa.ui.win32.elem_count("Checkbox_Element")

elem_wait_loaded(element, index=1, timeout=10)

Description

Waits for a specified element to load.

Parameters

element<str> The name of the element to wait for.

index<int> If multiple elements share the same name, specifies the 1-based index of the target element.

timeout<int> The maximum time in seconds to wait for the element. Defaults to 10.

Returns

Returns True if the element is found and loaded within the timeout; otherwise, returns False<bool>.

Code example

# Note: If the element is not found within the timeout, this method returns `False`.
# Example:
flag = rpa.ui.win32.elem_wait_loaded("Notepad_Input_Area")

elem_double_click(element, index=1, parent_element=None, timeout=10)

Description

Double-clicks a specified element.

Parameters

element<str> The name of the element to double-click.

index<int> If multiple elements share the same name, specifies the 1-based index of the target element.

parent_element<Element> A parent element object that limits the search scope.

timeout<int> The maximum time in seconds to wait for the element. Defaults to 10.

Code example

# Note:
# Before using this method, capture the target UI element.
# When the method runs, ensure the corresponding window is open and its title matches the one recorded during capture.
# Example:
rpa.ui.win32.elem_double_click("Notepad_Input_Area")

elem_mouse_move(element, index=1, timeout=10)

Description

Moves the mouse cursor over a specified element.

Parameters

element<str> The name of the target element.

index<int> If multiple elements share the same name, specifies the 1-based index of the target element.

timeout<int> The maximum time in seconds to wait for the element. Defaults to 10.

Code example

# Note:
# Before using this method, capture the target UI element.
# When the method runs, ensure the corresponding window is open and its title matches the one recorded during capture.
# Example: The following moves the mouse cursor to the center of the Notepad editing area.
rpa.ui.win32.elem_mouse_move("Notepad_Input_Area")

elem_pos(element, index=1, timeout=10)

Description

Gets the screen coordinates of a specified element.

Parameters

element<str> The name of the target element.

index<int> If multiple elements share the same name, specifies the 1-based index of the target element.

timeout<int> The maximum time in seconds to wait for the element. Defaults to 10.

Returns

Returns a dictionary containing the coordinates of the element's bounding box: {x1, y1, x2, y2}<dict>.

Code example

# Note:
# Before using this method, capture the target UI element.
# When the method runs, ensure the corresponding window is open and its title matches the one recorded during capture.
# Example:
pos_dict = rpa.ui.win32.elem_pos("Notepad_Input_Area")

elem_get_selected_items(element, mode='all', index=1, parent_element=None, timeout=10)

Description

Gets all available items or only the selected items from a combobox element.

Parameters

element<str> The name of the combobox element.

mode<str> The selection mode.

index<int> If multiple elements share the same name, specifies the 1-based index of the target element.

parent_element<Element> A parent element object that limits the search scope.

timeout<int> The maximum time in seconds to wait for the element. Defaults to 10.

Returns

Returns a list of item texts<list>.

Code example

# Note:
# Before using this method, capture the target UI element.
# When the method runs, ensure the corresponding window is open and its title matches the one recorded during capture.
# Example:
option_list = rpa.ui.win32.elem_get_selected_items("Combobox_Element")

elem_set_selected_item_by_text(element, text, index=1, parent_element=None, timeout=10)

Description

Selects an item in a combobox based on its text.

Parameters

element<str> The name of the combobox element.

text<str> The text of the item to select.

index<int> If multiple elements share the same name, specifies the 1-based index of the target element.

parent_element<Element> A parent element object that limits the search scope.

timeout<int> The maximum time in seconds to wait for the element. Defaults to 10.

Code example

# Note:
# Before using this method, capture the target UI element.
# When the method runs, ensure the corresponding window is open and its title matches the one recorded during capture.
# Example:
rpa.ui.win32.elem_set_selected_item_by_text("Combobox_Element","Option 1")

elem_get_datetimepicker(element, index=1, parent_element=None, timeout=10)

Description

Gets the date and time from a date time picker element.

Parameters

element<str> The name of the date time picker element.

index<int> If multiple elements share the same name, specifies the 1-based index of the target element.

parent_element<Element> A parent element object that limits the search scope.

timeout<int> The maximum time in seconds to wait for the element. Defaults to 10.

Returns

Returns a list representing the date and time: [year, month, day, hour, minute, second]<list>.

Code example

# Note:
# Before using this method, capture the target UI element.
# When the method runs, ensure the corresponding window is open and its title matches the one recorded during capture.
# Example:
rpa.ui.win32.elem_get_datetimepicker("Standard_Date_Picker")

elem_set_datetimepicker(element, year=1970, month=1, day=1, hour=0, minute=0, second=0, index=1, parent_element=None, timeout=10)

Description

Sets the date and time of a date time picker element.

Parameters

element<str> The name of the date time picker element.

year<int> The year to set.

month<int> The month to set.

day<int> The day to set.

hour<int> The hour to set.

minute<int> The minute to set.

second<int> The second to set.

index<int> If multiple elements share the same name, specifies the 1-based index of the target element.

parent_element<Element> A parent element object that limits the search scope.

timeout<int> The maximum time in seconds to wait for the element. Defaults to 10.

Code example

# Note:
# Before using this method, capture the target UI element.
# When the method runs, ensure the corresponding window is open and its title matches the one recorded during capture.
# Example:
rpa.ui.win32.elem_set_datetimepicker("Standard_Date_Picker",year=2021,month=5,day=1,hour=0,minute=0,second=0)

save_file_dialog(path, title='Save As')

Description

Handles a "Save As" dialog by entering the specified file path and confirming the action.

Parameters

path<str> The full file path to save the file to.

title<str> The title of the dialog to match (supports regular expressions). Defaults to 'Save As'.

Code example

# Note:
# This method should be called after an action that triggers a "Save As" dialog.
# The dialog must be the active window when this method runs.
# Example:
path = r"D:\Test_File_Archive\file_download_test.txt"
rpa.ui.win32.elem_click("Download_Button")
rpa.ui.win32.save_file_dialog(path,title='Save As')

open_file_dialog(path, title='Open')

Description

Handles an open file dialog by entering the specified file path and confirming the action, typically for file uploads.

Parameters

path<str> The full path of the file to open or upload.

title<str> The title of the dialog to match (supports regular expressions). Defaults to 'Open'.

Code example

# Note:
# This method should be called after an action that triggers an "Open" file dialog.
# The dialog must be the active window when this method runs.
# Example:
path = r"D:\Test_File_Archive\open_file_test.txt"
rpa.ui.win32.elem_click("Open_File_Button")
rpa.ui.win32.open_file_dialog(path,title='Open')