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.

mode<str>: The window match mode.

Valid options are:

• start: prefix matching

• substr: substring match

• exact: exact match

• reg: regular expression match

process_name<str>: The process name.

class_name<str>: The window class name.

timeout<int>: The timeout in seconds to wait for the window.

Returns

Returns the captured window object<Window>.

Example

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

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

Description

Performs a mouse click.

Parameters

button<str>: The mouse button to click.

Valid options are:

• left: Left button

• right: Right button

Example

rpa.ui.win32.click(x=500,y=500,button='left')

double_click(x=None, y=None)

Description

Performs a mouse double-click.

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 by a specified offset.

Parameters

start_x<int>: The starting x-coordinate.

start_y<int>: The starting y-coordinate.

x<int>: The offset on the x-axis.

y<int>: The offset on the y-axis.

speed_mode<str>: The drag speed mode.

Valid options are:

• uniform: Performs a uniform drag.

• fast-slow-pause: Accelerates, then decelerates, and finally pauses for alignment. This simulates human-like dragging behavior.

Example

# Note: Ensure the target window is active when this method is executed. This operation uses absolute screen coordinates.
rpa.ui.win32.drag(100,200,x=300,y=200, speed_mode='uniform')

rpa.ui.win32.input_text("test")

# Note: Driver input requires administrator privileges. If your application involves driver input, run the editor and robot as administrator.
rpa.ui.win32.drive_input("test")

# Note: Driver input requires administrator privileges. If your application involves driver input, run the editor and robot as administrator.
rpa.ui.win32.drive_input_hotkey("VK_RETURN")

mouse_move(x, y)

Description

Moves the mouse cursor.

Example

rpa.ui.win32.mouse_move(500,500)

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

Description

Takes a screenshot.

Example

path =  r'D:\2_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.

mode<str>: The window match mode.

Valid options are:

• start: prefix matching

• substr: substring match

• exact: exact match

• reg: regular expression match

Example

# Note: Ensure that the process for the target window exists before using this method.
# The following example activates a Notepad window and brings it to the foreground:
rpa.ui.win32.win_activate("test.txt - 记事本")

win_maximize(title, mode='start')

Description

Maximizes a window.

Parameters

title<str>: The window title.

mode<str>: The window match mode.

Valid options are:

• start: prefix matching

• substr: substring match

• exact: exact match

• reg: regular expression match

Example

# Note: Ensure that the process for the target window exists before using this method.
# The following example maximizes a Notepad window:
rpa.ui.win32.win_maximize("test.txt - 记事本")

win_minimize(title, mode='start')

Description

Minimizes a window.

Parameters

title<str>: The window title.

mode<str>: The window match mode.

Valid options are:

• start: prefix matching

• substr: substring match

• exact: exact match

• reg: regular expression match

Example

# Note: Ensure that the process for the target window exists before using this method.
# The following example minimizes a Notepad window:
rpa.ui.win32.win_minimize("test.txt - 记事本")

win_hide(title, mode='start')

Description

Hides a window.

Parameters

title<str>: The window title.

mode<str>: The window match mode.

Valid options are:

• start: prefix matching

• substr: substring match

• exact: exact match

• reg: regular expression match

Example

# Note: This method removes the window from the taskbar. The process can then only be found in the Task Manager.
rpa.ui.win32.win_hide("test.txt - 记事本")

win_show(title, mode='start')

Description

Shows a hidden window.

Parameters

title<str>: The window title.

mode<str>: The window match mode.

Valid options are:

• start: prefix matching

• substr: substring match

• exact: exact match

• reg: regular expression match

Example

rpa.ui.win32.win_show("test.txt - 记事本")

win_exists(title, mode='start')

Description

Checks if a window exists.

Parameters

title<str>: The window title.

mode<str>: The window match mode.

Valid options are:

• start: prefix matching

• substr: substring match

• exact: exact match

• reg: regular expression match

Returns

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

Example

exist_flag = rpa.ui.win32.win_exists("test.txt - 记事本")

win_close(title, mode='start')

Description

Closes a window.

Parameters

title<str>: The window title.

mode<str>: The window match mode.

Valid options are:

• start: prefix matching

• substr: substring match

• exact: exact match

• reg: regular expression match

Example

rpa.ui.win32.win_close("test.txt - 记事本")

win_wait_appear(title, timeout=30)

Description

Waits for a window to appear.

Parameters

title<str>: The window title.

timeout<int>: The timeout in seconds.

Example

rpa.ui.win32.win_wait_appear("test.txt - 记事本",timeout=10)

win_wait_disappear(title, timeout=30)

Description

Waits for a window to disappear.

Parameters

title<str>: The window title.

timeout<int>: The timeout in seconds.

Example

rpa.ui.win32.win_wait_disappear("test.txt - 记事本",timeout=10)

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

Description

Drags an element by a specified offset.

Parameters

element<str>: The name of the element.

x<int>: The offset on the x-axis.

y<int>: The offset on the y-axis.

speed_mode<str>: The drag speed mode.

Valid options are:

• uniform: Performs a uniform drag.

• fast-slow-pause: Accelerates, then decelerates, and finally pauses for alignment. This simulates human-like dragging behavior.

index<int>: The index of the element, if multiple elements share the same name.

parent_element<Element>: The parent element object.

timeout<int>: The timeout in seconds to wait for the element.

Example

# Note: Before using this method, capture the target UI element. During execution, ensure the target window is open and its title matches the one recorded at capture time.
rpa.ui.win32.elem_drag("滑动模块",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 an element.

Parameters

element<str>: The name of the element.

value<str>: The content to input.

index<int>: The index of the element, if multiple elements share the same name.

parent_element<Element>: The parent element object.

simulate<bool>: Specifies whether to use simulated input.

replace<bool>: Specifies whether to clear the existing content.

send_window_message<bool>: Specifies whether to send a Windows message.

sent_raw<bool>: Specifies whether to send raw keystrokes.

wait_mili_seconds<int>: The interval between character inputs, in milliseconds. This parameter applies only to simulated input. The default value is 20, and the maximum is 100. Setting this value too high may cause a timeout.

timeout<int>: The timeout in seconds to wait for the element.

Example

# Note: Before using this method, capture the target UI element. During execution, ensure the target window is open and its title matches the one recorded at capture time.
text = "RPA_Test"
rpa.ui.win32.elem_input_text("记事本输入区",text)

# Note:
# Before using this method, capture the target UI element. During execution, ensure the target window is open and its title matches the one recorded at capture time.
# For information on virtual key syntax, see: https://help.aliyun.com/document_detail/218003.html
rpa.ui.win32.elem_input_hotkeys("记事本输入区","VK_RETURN")

# Note: Driver input requires administrator privileges. If your application involves driver input, run the editor and robot as administrator.
# Before using this method, capture the target UI element. During execution, ensure the target window is open and its title matches the one recorded at capture time.
rpa.ui.win32.elem_drive_input("记事本输入区","TEST")

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

Description

Clicks an element.

Parameters

element<str>: The name of the element.

index<int>: The index of the element, if multiple elements share the same name.

simulate<bool>: Specifies whether to simulate the click.

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

Valid options are:

• left: Left button

• right: Right button

parent_element<Element>: The parent element object.

timeout<int>: The timeout in seconds to wait for the element.

Example

# Note: Before using this method, capture the target UI element. During execution, ensure the target window is open and its title matches the one recorded at capture time.
rpa.ui.win32.elem_click("记事本输入区")

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

Description

Gets the state of a checkbox.

Parameters

element<str>: The name of the element.

index<int>: The index of the element, if multiple elements share the same name.

parent_element<Element>: The parent element object.

timeout<int>: The timeout in seconds to wait for the element.

Returns

Returns True if the checkbox is selected; False otherwise<bool>.

Example

# Note: Before using this method, capture the target UI element. During execution, ensure the target window is open and its title matches the one recorded at capture time.
flag = rpa.ui.win32.elem_get_checked_state("复选框")

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

Description

Sets the state of a checkbox.

Parameters

element<str>: The name of the element.

value<bool>: Set to True to select the checkbox, or False to deselect it.

index<int>: The index of the element, if multiple elements share the same name.

parent_element<Element>: The parent element object.

timeout<int>: The timeout in seconds to wait for the element.

Example

# Note: Before using this method, capture the target UI element. During execution, ensure the target window is open and its title matches the one recorded at capture time.
rpa.ui.win32.elem_set_checked_state("复选框",value=False)

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

Description

Gets the text from an element.

Parameters

element<str>: The name of the element.

index<int>: The index of the element, if multiple elements share the same name.

parent_element<Element>: The parent element object.

timeout<int>: The timeout in seconds to wait for the element.

Returns

Returns the text from the element<str>.

Example

# Note: Before using this method, capture the target UI element. During execution, ensure the target window is open and its title matches the one recorded at capture time.
rpa.ui.win32.elem_text("标题栏")

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 element.

index<int>: The index of the element, if multiple elements share the same name.

parent_element<Element>: The parent element object.

timeout<int>: The timeout in seconds to wait for the element.

Returns

Returns the element object<Element>.

Example

element = rpa.ui.win32.get_element_by_name("记事本输入区")

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.

parent_element<Element>: The parent element object.

timeout<int>: The timeout in seconds to wait for the element.

Returns

Returns the number of matching elements<int>.

Example

# Note: Before using this method, capture the target UI element. During execution, ensure the target window is open and its title matches the one recorded at capture time.
count = rpa.ui.win32.elem_count("复选框")

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

Description

Waits for an element to load.

Parameters

element<str>: The name of the element.

index<int>: The index of the element, if multiple elements share the same name.

timeout<int>: The timeout in seconds to wait for the element.

Returns

Returns True if the element loads successfully within the timeout period; False otherwise<bool>.

Example

# Note: If the element is not located within the specified timeout, this method returns False.
flag = rpa.ui.win32.elem_wait_loaded("记事本输入区")

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

Description

Double-clicks an element.

Parameters

element<str>: The name of the element.

index<int>: The index of the element, if multiple elements share the same name.

parent_element<Element>: The parent element object.

timeout<int>: The timeout in seconds to wait for the element.

Example

# Before using this method, capture the target UI element. During execution, ensure the target window is open and its title matches the one recorded at capture time.
rpa.ui.win32.elem_double_click("记事本输入区")

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

Description

Moves the mouse cursor over an element.

Parameters

element<str>: The name of the element.

index<int>: The index of the element, if multiple elements share the same name.

timeout<int>: The timeout in seconds to wait for the element.

Example

# Before using this method, capture the target UI element. During execution, ensure the target window is open and its title matches the one recorded at capture time.
# The following example moves the mouse cursor to the center of the Notepad editing area:
rpa.ui.win32.elem_mouse_move("记事本输入区")

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

Description

Gets the coordinates of an element.

Parameters

element<str>: The name of the element.

index<int>: The index of the element, if multiple elements share the same name.

timeout<int>: The timeout in seconds to wait for the element.

Returns

Returns a dictionary containing the coordinates x1, y1, x2, and y2<dict>.

Example

# Before using this method, capture the target UI element. During execution, ensure the target window is open and its title matches the one recorded at capture time.
pos_dict = rpa.ui.win32.elem_pos("记事本输入区")

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

Description

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

Parameters

element<str>: The name of the element.

mode<str>: The selection mode.

index<int>: The index of the element, if multiple elements share the same name.

parent_element<Element>: The parent element object.

timeout<int>: The timeout in seconds to wait for the element.

Returns

Returns a list of the items<list>.

Example

# Before using this method, capture the target UI element. During execution, ensure the target window is open and its title matches the one recorded at capture time.
option_list = rpa.ui.win32.elem_get_selected_items("combox选项框")

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

Description

Selects an item in a combobox or drop-down list by its text.

Parameters

element<str>: The name of the element.

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

index<int>: The index of the element, if multiple elements share the same name.

parent_element<Element>: The parent element object.

timeout<int>: The timeout in seconds to wait for the element.

Example

# Before using this method, capture the target UI element. During execution, ensure the target window is open and its title matches the one recorded at capture time.
rpa.ui.win32.elem_set_selected_item_by_text("combox选项框","选项1")

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

Description

Gets the date and time from a datetime picker.

Parameters

element<str>: The name of the element.

index<int>: The index of the element, if multiple elements share the same name.

parent_element<Element>: The parent element object.

timeout<int>: The timeout in seconds to wait for the element.

Returns

Returns a list containing the year, month, day, hour, minute, and second, in that order<list>.

Example

# Before using this method, capture the target UI element. During execution, ensure the target window is open and its title matches the one recorded at capture time.
rpa.ui.win32.elem_get_datetimepicker("标准日期控件")

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 datetime picker.

Parameters

element<str>: The name of the element.

year<int>: The year.

month<int>: The month.

day<int>: The day.

hour<int>: The hour.

minute<int>: The minute.

second<int>: The second.

index<int>: The index of the element, if multiple elements share the same name.

parent_element<Element>: The parent element object.

timeout<int>: The timeout in seconds to wait for the element.

Example

# Before using this method, capture the target UI element. During execution, ensure the target window is open and its title matches the one recorded at capture time.
rpa.ui.win32.elem_set_datetimepicker("标准日期控件",year=2021,month=5,day=1,hour=0,minute=0,second=0)

save_file_dialog(path, title='Save File')

Description

Handles a save file dialog.

Parameters

path<str>: The file save path.

title<str> A regular expression that matches the window title. The default value is 'Save File'.

Example

# The following is a code example:
path = r"D:\2_test_file_archive\file_download_test.txt"
rpa.ui.win32.elem_click("下载按钮")
​
rpa.ui.win32.save_file_dialog(path,title='保存文件')

open_file_dialog(path, title='Open File')

Description

Handles an open file dialog.

Parameters

path<str>: The path of the file to select.

title<str> The window title, which is matched by using a regular expression and defaults to 'Open File'.

Example

# The following is a code example:
path = r"D:\2_test_file_archive\open_file_test.txt"
rpa.ui.win32.elem_click("打开文件按钮")
​
rpa.ui.win32.open_file_dialog(path,title='打开文件')