This is UltimateRPA Documentation
Public Member Functions | List of all members
urpa.VisualElement Class Reference

This class represents a visual GUI element in an application. More...

Public Member Functions

def send_mouse_click (self, action=default_mouse_action, position=None)
 This method simulates the mouse action specified in the action parameter. More...
 
def send_text (self, text, action=default_text_action, kl=default_kl, focus_action=default_focus_action)
 This method simulates the pressing and releasing of a key sequence, over a visual GUI element, represented by a string in the "text" parameter. More...
 
def send_key (self, text, type=default_key_action, focus_action=default_focus_action)
 This method simulates - over a visual GUI element - the pressing of a specified key combination. More...
 
def bounding_rectangle (self)
 This method returns the absolute coordinates of this visual GUI element on the desktop in the order left, top, right, bottom. More...
 
def size (self)
 This method returns the size of this visual GUI element in the order width, height. More...
 

Detailed Description

This class represents a visual GUI element in an application.

An instance of this class can be created by one of the AppElement class methods, such as AppElement.find_first_visual, AppElement.find_all_visual.

Member Function Documentation

◆ bounding_rectangle()

def urpa.VisualElement.bounding_rectangle (   self)

This method returns the absolute coordinates of this visual GUI element on the desktop in the order left, top, right, bottom.

Returns
Returns a tuple containing the absolute coordinates of this visual GUI element on the desktop in the order left, top, right, bottom.

◆ send_key()

def urpa.VisualElement.send_key (   self,
  text,
  type = default_key_action,
  focus_action = default_focus_action 
)

This method simulates - over a visual GUI element - the pressing of a specified key combination.

Prior to the simulation of the pressing of the specified key combination, the TP window tied to the visual GUI element is transferred to the foreground. The actual simulation of the pressing of the specified key combination is only tied to the TP window handle, i.e. if the GUI element does not gain or loses focus during the simulation, the simulation will not be executed correctly. While simulating the key press, first the string from the "text" parameter is divided into individual characters. The delimiter between characters is "+". A sequence is then created that represents key press ("down") and key release ("up") according to the characters in the "text" parameter. For example, the Ctrl+Shift+s combination is broken down into the sequence Ctrl(Down)+Shift(Down)+s(Down)+s(Up)+Shift(Up)+Ctrl(Up). A 100 ms delay is "processed" following the simulation of the press (Down) / release (Up) of each key. If a Hardware simulation mode is set in the "type" parameter, the simulation must take place in the foreground. If a simulation is running in the background, when the "type" parameter is set to Hardware it is automatically transferred to the foreground. When the "type" parameter is set to a Standard value, during a simulation individual characters are converted into virtual-key codes, and the simulation can also run in the background. This method is not suitable for direct text input.

Parameters
textString
  • "ALT"
  • "RALT" - right Alt
  • "CTRL"
  • "RCTRL" - right Ctrl
  • "TAB"
  • "ENTER", "RETURN"
  • "BACKSPACE"
  • "ESC", "ESCAPE"
  • "END"
  • "HOME"
  • "LEFT"
  • "UP"
  • "RIGHT"
  • "DOWN"
  • "INSERT"
  • "DELETE", "DEL"
  • "HELP"
  • "NUMLOCK"
  • "SCROLL"
  • "PGDOWN", "NEXT"
  • "PGUP", "PRIOR"
  • "CLEAR"
  • "SHIFT"
  • "RSHIFT" - right shift
  • "WIN"
  • "RWIN"
  • "APPS"
  • "SPACE"
  • or a key combination, e.g. "ALT+x"
typeString The way in which the keystrokes are to be simulated.
  • Hardware
  • Standard
focus_actionString The way in which control activation is to be simulated. See set_default_focus_action for options.
Exceptions
ValueErrorthe "text" or "type" parameters passed does not have a valid format.

Examples

The example of opening Internet Explorer on the about:blank page, invoking the "Show documents downloaded" dialogue box by simulating the pressing of the Ctrl+J keyboard shortcut and closing this dialogue box by simulating the Alt+Z keyboard shortcut.

app = urpa.exec_ie_app("about:blank")
verify_element = app.find_first(cf.value("about:blank"))
time.sleep(1)
verify_element.send_key("Ctrl+J")
time.sleep(1)
close_element = app.find_first(cf.button().access_key("Alt+Z"))
time.sleep(1)
close_element.send_key("Alt+Z")

◆ send_mouse_click()

def urpa.VisualElement.send_mouse_click (   self,
  action = default_mouse_action,
  position = None 
)

This method simulates the mouse action specified in the action parameter.

The mouse action is performed over the center of this visual GUI element. By default, this method makes an HW left mouse click in the center of the visual GUI element. Delays in sending individual messages that simulate the mouse action are set to 50 ms.

Parameters
actionString A parameter specifying the type of mouse action that will be simulated over the visual GUI element. For possible parameter values, see the urpa.set_default_mouse_action method.
positiona tuple with 2 int-type elements (left, top). Specifies the mouse click position in the format left, top. The coordinates are relative to the upper left corner of the visual GUI element.

Examples

The example of opening https://playground.ultimaterpa.com in Internet Explorer, finding an "authentication" visual GUI element called "Continue", waiting for 3 seconds, simulating a click on the "Continue" visual GUI element found, finding the "Success" authentication element.

app = urpa.exec_ie_app("https://playground.ultimaterpa.com")
verify_element = app.find_first_visual("img/continue.bmp")
time.sleep(3)
verify_element.send_mouse_click("Left")
verify_element_success = app.find_first("Success")

◆ send_text()

def urpa.VisualElement.send_text (   self,
  text,
  action = default_text_action,
  kl = default_kl,
  focus_action = default_focus_action 
)

This method simulates the pressing and releasing of a key sequence, over a visual GUI element, represented by a string in the "text" parameter.

Prior to the simulation of the key press and release, the TP window tied to the visual GUI element is transferred to the foreground. The actual key press/release simulation is only tied to the TP window handle, i.e. if the GUI element does not gain or loses focus during the simulation, the simulation will not be executed correctly. While processing the key simultation, first the string from the "text" parameter is divided into individual characters. A sequence is then created that represents key press ("down") and key release ("up") according to the characters in the "text" parameter. For example, the string "Lev" is broken down into the sequence Shift(Down)+l(Down)+l(Up)+Shift(Up)+e(Down)+e(Up)+v(Down)+v(Up). A 100 ms delay is "processed" following the simulation of the press (Down) / release (Up) of each key. If one of the "hw" simulation modes is set in the "type" parameter, the simulation must take place in the foreground. If a simulation is running in the background, when the "type" parameter is set to one of the "hw" values it is automatically transferred to the foreground. When the "type" parameter is set to one of the "standard" values, during a simulation individual characters are converted into virtual-key codes or alt-codes, and then the simulation can also run in the background. When the "type" parameter is set to "wm_char", the string from the "text" parameter splits directly into individual characters in the simulation.

Parameters
textString Text, the writing of which will be simulated over an application tied to a visual GUI element represented by an instance of this class.
actionString The mode for the simulation of individual keystrokes, represented by a string in the "text" parameter.
  • "hw_alt_code" This option uses the classic disassembly of text characters into Alt-code and their sequential simulation. The Windows API keybd_event() function is invoked over an application tied to a visual GUI element during the simulation.
  • "hw_scan_virtual" This option draws on the decomposition of characters from the "text" parameter using *.xml conversion files from the KeybLayoutTranslate directory. If, for the "kl" parameter, a keyboard layout is set for which there is no KeybLayoutTranslate\00000*.xml file, this file needs to be created for that keyboard layout, otherwise the user activity simulation will not work correctly. The Windows API keybd_event() function is invoked over an application tied to a visual GUI element during the simulation.
  • "standard_alt_code" This option uses the classic decomposition of text characters into Alt-code and their sequential simulation. Messages with WM_KEYDOWN and WM_KEYUP parameters are sent to an application tied to a visual GUI element via the Windows API PostMessage() function.
  • "standard_scan_virtual" This option draws on the decomposition of characters from the "text" parameter using *.xml conversion files from the KeybLayoutTranslate directory. If, for the "kl" parameter, a keyboard layout is set for which there is no KeybLayoutTranslate\00000*.xml file, this file needs to be created for that keyboard layout, otherwise the user activity simulation will not work correctly. Messages with WM_KEYDOWN and WM_KEYUP parameters are sent to an application tied to a visual GUI element via the Windows API PostMessage() function.
  • "wm_char" This option is appropriate when the Keyboard Layout specification is unclear and when characters accessible with different keyboard contexts need to be transferred to an application. Setting this option results only in the direct splitting of the string from the "text" parameter in the simulation. The keyboard layout set in the "kl" parameter is ignored when this simulation mode is used.
klString Represents the keyboard layout that is automatically set for an application tied to a visual GUI element when simulating text input.
focus_actionString The way in which control activation is to be simulated. See set_default_focus_action for options.
Exceptions
ValueErrorone of the parameters passed does not have a valid format.

Examples

The example of opening Internet Explorer on the about:blank page, simulating the input of the text https://playground.ultimaterpa.com in the address bar, and going to this page by pressing the Enter key.

app = urpa.exec_ie_app("about:blank")
verify_element = app.find_first(cf.value("about:blank"))
time.sleep(1)
verify_element.send_text("https://playground.ultimaterpa.com")
verify_element.send_key("ENTER")
time.sleep(1)
ready_element = app.find_first(cf.button().name("Continue"))

◆ size()

def urpa.VisualElement.size (   self)

This method returns the size of this visual GUI element in the order width, height.

Returns
Returns a tuple containing the size of this visual GUI element in the order width, height.
The documentation for this class was generated from the following file: