Třída reprezentuje element GUI v aplikaci. ...

Diagram dědičnosti pro třídu urpa.AppElement

Veřejné metody
def	send_mouse_click (self, action=default_mouse_action, position=None)
	Metoda nasimuluje nad středem elementu GUI svázaného s instancí této třídy akci myši, která je specifikována v jejím parametru. ...

def	send_text (self, text, action=default_text_action, kl=default_kl, focus_action=default_focus_action)
	Metoda nasimuluje nad elementem GUI stisknutí a uvolnění posloupnosti kláves, která je reprezentována řetězcem v parametru "text". ...

def	send_key (self, text, type=default_key_action, focus_action=default_focus_action)
	Metoda nasimuluje nad elementem GUI stisknutí zadané kombinace kláves. ...

def	send_message (self, message, wparam, lparam)

def	post_message (self, message, wparam, lparam)

def	set_focus (self, focus_action=default_focus_action)
	Metoda nastaví focus elementu GUI svázanému s instancí této třídy. ...

def	name (self)
	Metoda vrací hodnotu atributu "name" elementu GUI svázaného s instancí této třídy. ...

def	value (self)
	Metoda vrací hodnotu atributu "value" elementu GUI svázaného s instancí této třídy. ...

def	class_name (self)
	Metoda vrací hodnotu atributu "class name" elementu GUI svázaného s instancí této třídy. ...

def	localized_control_type (self)
	Metoda vrací hodnotu atributu "localized control type" elementu GUI svázaného s instancí této třídy. ...

def	control_type (self)
	Metoda vrací hodnotu atributu "control type" elementu GUI svázaného s instancí této třídy. ...

def	bounding_rectangle (self)
	Metoda vrací absolutní souřadnice elementu GUI (svázaného s instancí této třídy) na desktopu v pořadí left, top, right, bottom. ...

def	size (self)
	Metoda vrací velikost elementu GUI svázaného s instancí této třídy v pořadí width, height. ...

def	access_key (self)
	Metoda vrací hodnotu atributu "access key" elementu GUI svázaného s instancí této třídy. ...

def	automation_id (self)
	Metoda vrací hodnotu atributu "automation ID" elementu GUI svázaného s instancí této třídy. ...

def	item_type (self)
	Metoda vrací hodnotu atributu "item type" elementu GUI svázaného s instancí této třídy. ...

def	toggle_state (self)
	Metoda vrací hodnotu atributu "toggle state" elementu GUI svázaného s instancí této třídy. ...

def	selected (self)
	Metoda vrací hodnotu atributu "selected" elementu GUI svázaného s instancí této třídy. ...

def	enabled (self)
	Metoda vrací hodnotu atributu "enabled" elementu GUI svázaného s instancí této třídy. ...

def	visual_data (self, rect=None, format="bmp")
	Metoda vytvoří obrázek z elementu GUI, který je svázaný s instancí této třídy. ...

def	parent (self)
	Metoda vrací rodiče toho elementu. ...

def	find_first (self, condition, timeout=default_timeout)
	Metoda vrací první element GUI, který vyhovuje podmínce condition a který se nachází v podstromu elementů GUI s kořenem, který reprezentuje element GUI svázaný s instancí této třídy. ...

def	find_all (self, condition, elements=0, timeout=default_timeout)
	Metoda vrací seznam (list) všech elementů GUI, které vyhovují podmínce condition a které se nachází v podstromu elementů GUI s kořenem, který reprezentuje element GUI svázaný s instancí této třídy. ...

def	find_from_point (self, x, y, condition=None, timeout=default_timeout)
	Metoda vyhledá element GUI, který vyhovuje podmínce condition a současně se nachází na pozici virtuálního bodu, definovaného posunutím (parametry x, y) levého horního rohu elementu GUI, který je svázaný s instancí této třídy. ...

def	find_first_right_to (self, condition, timeout=default_timeout, height=50, step=30)
	Metoda hledá element GUI, který splňuje podmínku condition a nachází se směrem napravo od elementu GUI, který je svázaný s instancí této třídy. ...

def	find_first_left_to (self, condition, timeout=default_timeout, height=50, step=30)

def	find_first_down_to (self, condition, timeout=default_timeout, width=50, step=30)
	Metoda hledá element GUI, který splňuje podmínku condition a nachází se směrem dolu od elementu GUI, který je svázaný s instancí této třídy. ...

def	find_first_up_to (self, condition, timeout=default_timeout, width=50, step=30)
	Metoda hledá element GUI, který splňuje podmínku condition a nachází se směrem nahoru od elementu GUI, který je svázaný s instancí této třídy. ...

def	find_first_visual (self, pattern, region=None, timeout=default_timeout, transformations=None)
	Metoda hledá vizuální element GUI (pattern) v dané oblasti (region) a vrací ho jako objekt VisualElement. ...

def	find_all_visual (self, pattern, region=None, elements=0, timeout=default_timeout, transformations=None)
	Metoda hledá vizuální elementy GUI (pattern) v dané oblasti (region) a vrací je jako seznam objektů VisualElement. ...

Detailní popis

Třída reprezentuje element GUI v aplikaci.

Instanci této třídy lze vytvořit některou z metod třídy App nebo metodami AppElement.find_first, AppElement.find_all, AppElement.find_from_point, AppElement.find_first_right_to.

Dokumentace k metodám

◆ access_key()

def urpa.AppElement.access_key ( self )

Metoda vrací hodnotu atributu "access key" elementu GUI svázaného s instancí této třídy.

Návratová hodnota: Vrací řetězec, který obsahuje hodnotu atributu "access key" elementu GUI svázaného s instancí této třídy.

◆ automation_id()

def urpa.AppElement.automation_id ( self )

Metoda vrací hodnotu atributu "automation ID" elementu GUI svázaného s instancí této třídy.

Návratová hodnota: Vrací řetězec, který obsahuje hodnotu atributu "automation ID" elementu GUI svázaného s instancí této třídy.

◆ bounding_rectangle()

def urpa.AppElement.bounding_rectangle ( self )

Metoda vrací absolutní souřadnice elementu GUI (svázaného s instancí této třídy) na desktopu v pořadí left, top, right, bottom.

Návratová hodnota: Vrací tuple, který obsahuje absolutní souřadnice elementu GUI (svázaného s instancí této třídy) na desktopu v pořadí left, top, right, bottom.

◆ class_name()

def urpa.AppElement.class_name ( self )

Metoda vrací hodnotu atributu "class name" elementu GUI svázaného s instancí této třídy.

Návratová hodnota: Vrací řetězec, který obsahuje hodnotu atributu "class name" elementu GUI svázaného s instancí této třídy.

◆ control_type()

def urpa.AppElement.control_type ( self )

Metoda vrací hodnotu atributu "control type" elementu GUI svázaného s instancí této třídy.

Návratová hodnota: Vrací řetězec, který obsahuje hodnotu atributu "control type" elementu GUI svázaného s instancí této třídy.

◆ enabled()

def urpa.AppElement.enabled ( self )

Metoda vrací hodnotu atributu "enabled" elementu GUI svázaného s instancí této třídy.

Návratová hodnota: Vrací True v případě, že je element GUI "povolen". Vrací False v případě, že element GUI není "povolen".

◆ find_all()

def urpa.AppElement.find_all	(	self,
		condition,
		elements = `0`,
		timeout = `default_timeout`
	)

Metoda vrací seznam (list) všech elementů GUI, které vyhovují podmínce condition a které se nachází v podstromu elementů GUI s kořenem, který reprezentuje element GUI svázaný s instancí této třídy.

Prohledávání podstromu elementů GUI probíhá v iteracích s prodlevou 50 ms po dobu definovanou v parametru timeout. U aplikací s rozsáhlým GUI se může doba zpracování jedné iterace, resp. prohledání podstromu GUI elementů, pohybovat v řádu vteřin. Pokud je počet nalezených elementů GUI během jedné iterace nenulový a současně je roven nebo větší než hodnota specifikovaná v parametru elements, vrací metoda seznam (list) nalezených objektů AppElement. Pokud není parametr elements nastaven na hodnotu 0 a do doby timeoutu není nalezen požadovaný počet elementů GUI, je vyvolána výjimka urpa.ElementNotFoundError. Pokud je parametr elements nastaven na hodnotu 0 a do doby timeoutu není nalezen alespoň jeden požadovaný element GUI, vrací metoda prázdný seznam (list). Pokud je parametr elements nastaven na hodnotu 0 proběhne vždy zpracování pouze jedné iterace.

Parametry

condition	String nebo Condition Výraz pro vyhledání elementů GUI.
elements	int Minimální počet elementů GUI, které je nutné do doby definované v parametru timeout nalézt.
timeout	int [ms] Maximální čas na vyhledání elementů GUI. Pokud není tento parametr zadán, použije se implicitní hodnota, tj. urpa.default_timeout.

Návratová hodnota: Vrací seznam (list) objektů typu AppElement

Výjimky

ElementNotFoundError požadovaný počet elementů GUI nebyl v požadovaném čase nalezen.

Examples

Příklad nalezení všech radiobuttonů, které se na stránce https://playground.ultimaterpa.com v aplikaci Internet Explorer nachází "pod" elementem GUI - pane "UltimateRPA Playground". Atributy nalezených elementů GUI jsou vypsány do výstupní konzole.

# pomocná třída pro vytváření složitějších podmínek
cf = urpa.condition_factory()
# spuštění aplikace Internet Explorer
app = urpa.exec_ie_app("https://playground.ultimaterpa.com")
# čekání na nalezení elementu GUI - pane "UltimateRPA Playground"
root_element = app.find_first(cf.pane().name(cf.regexp("UltimateRPA Playground")))
# nalezení radiobuttonů v podstromu elementů GUI
found_elements = root_element.find_all(cf.radio_button())
print(found_elements)

◆ find_all_visual()

def urpa.AppElement.find_all_visual	(	self,
		pattern,
		region = `None`,
		elements = `0`,
		timeout = `default_timeout`,
		transformations = `None`
	)

Metoda hledá vizuální elementy GUI (pattern) v dané oblasti (region) a vrací je jako seznam objektů VisualElement.

Parametry

pattern	string nebo bytearray například "img/pattern.bmp" Cesta na obrázek ve formátu png, bmp nebo hodnota vrácená metodou visual_data (bytearray).
region	tuple obsahující čtyři int například (10, 10, 20, 20) nebo None. Nepovinný argument, defaultně nastavený na None. Tuple definuje (left, top, right, bottom) souřadnice obdélníku, který určuje vybranou oblast v px. Souřadnice jsou relativní vůči levému hornímu rohu elementu GUI, se kterým je svázána instance třídy AppElement. Hodnota None znamená, že vybraná oblast je shodná s velikostí elementu GUI, se kterým je svázána instance třídy AppElement.
elements	int Minimální počet vizuálních elementů GUI, které je nutné do doby definované v parametru timeout nalézt.
timeout	int [ms] Maximální doba, do které musí být vyhledány vizuální elementy GUI. Pokud není tento parametr specifikován, použije se implicitní hodnota viz urpa.default_timeout.
transformations	objekt transformace, který může obsahovat několik operací modifikujících zdrojový pattern i prohledávanou oblast. Viz TransformationFactory.

Návratová hodnota: Vrací seznam objektů typu VisualElement

Výjimky

ElementNotFoundError Požadované vizuální elementy GUI nebyly v požadovaném čase nalezeny.

Examples

Příklad

element = app.find_first(cf.name("Red Rectangle"))
region = (-10, -12, 42, 40)
# Definujeme si, kolik vizuálních elementů GUI chceme minimálně nalézt.
elements = 2
timeout = 60000
tf = urpa.transformation_factory()
# Definujeme, že jako první se provede inverze barev a potom 50% práh.
transformations = tf.colors_inversion().binary_image(0.5)
visuals = element.find_all_visual("img/template.png", region, elements, timeout, transformations)
# Nad posledním vyhledaným elementem GUI nasimulujeme kliknutí myší.
visuals[-1].send_mouse_click()

◆ find_first()

def urpa.AppElement.find_first	(	self,
		condition,
		timeout = `default_timeout`
	)

Metoda vrací první element GUI, který vyhovuje podmínce condition a který se nachází v podstromu elementů GUI s kořenem, který reprezentuje element GUI svázaný s instancí této třídy.

Vyhledávání elementu GUI probíhá v iteracích s prodlevou 50 ms. K prohledávání podstromu elementů GUI je použita metoda "prohledávání do hloubky - depth-first search". U aplikací s rozsáhlým GUI se může doba zpracování jedné iterace, resp. prohledání podstromu GUI elementů, pohybovat v řádu vteřin. Metoda není vhodná na identifikaci elementů GUI, které pouze "probliknou" v GUI řízené aplikace. Pokud metoda žádný vyhovující element GUI nenajde, vyvolá výjimku urpa.ElementNotFoundError. Jinak metoda vrací první vyhovující element GUI, i pokud vyhovuje podmínce definované v parametru condition více elementů GUI.

Parametry

condition	String nebo Condition Výraz pro vyhledání elementu GUI.
timeout	int [ms] Maximální čas na vyhledání elementu GUI. Pokud není tento parametr zadán, použije se implicitní hodnota, tj. urpa.default_timeout.

Návratová hodnota: Vrací jeden objekt typu AppElement

Výjimky

ElementNotFoundError požadovaný element GUI nebyl v požadovaném čase nalezen.

Examples

Příklad nalezení prvního radiobuttonu, který se na stránce https://playground.ultimaterpa.com v aplikaci Internet Explorer nachází "pod" elementem GUI - pane "UltimateRPA Playground". Atributy nalezeného elementu GUI jsou vypsány do výstupní konzole.

# pomocná třída pro vytváření složitějších podmínek
cf = urpa.condition_factory()
# spuštění aplikace Internet Explorer
app = urpa.exec_ie_app("https://playground.ultimaterpa.com")
# čekání na nalezení elementu GUI - pane "UltimateRPA Playground"
root_element = app.find_first(cf.pane().name(cf.regexp("UltimateRPA Playground")))
# nalezení radiobuttonu v podstromu elementů GUI
found_element = root_element.find_first(cf.radio_button())
print(found_element)

◆ find_first_down_to()

def urpa.AppElement.find_first_down_to	(	self,
		condition,
		timeout = `default_timeout`,
		width = `50`,
		step = `30`
	)

Metoda hledá element GUI, který splňuje podmínku condition a nachází se směrem dolu od elementu GUI, který je svázaný s instancí této třídy.

Vyhledávání elementu GUI probíhá v iteracích s prodlevou 50 ms po dobu specifikovanou v parametru timeout. Hledaný element GUI se musí vyskytovat ve shodném TP okně jako element GUI svázaný s instancí této třídy. Na začátku zpracování této metody je TP okno, které je s instancí této třídou svázáno, přeneseno na popředí. Následně jsou vypočteny nad TP oknem souřadnice virtuálních bodů, ve kterých je vyhledáván element GUI, splňující podmínku condition. Virtuální body, nad kterými je vyhledáván element GUI splňující podmínku condition, mají vertikální rozestup definovaný parametrem step (v pixelech). Počet virtuálních bodů je dán velikostí TP okna a parametrem step, resp. y-ová souřadnice každého virtuálního bodu musí být menší než y-ová souřadnice dolní hrany TP okna, které je svázáno s hledaným elementem GUI. Současně musí být y-ová souřadnice každého virtuálního bodu větší než y-ová souřadnice spodní hrany elementu GUI, který je svázaný s instancí této třídy. První virtuální bod má vždy y-ovou souřadnici posunutou o 5 pixelů směrem dolu od spodní hrany elementu GUI, který je svázaný s instancí této třídy. Horizontální (x-ová) souřadnice všech virtuálních bodů je defaultně nastavena na střed referenčního elementu GUI (height = 50) a je u všech virtuálních bodů vždy shodná. Pokud současně splňují podmínku condition elementy GUI nad větším množstvím virtuálních bodů, je vrácen element GUI, který je nejblíže elementu GUI svázaným s instancí této třídy. Pokud metoda požadovaný element GUI nenajde, vyvolá výjimku urpa.ElementNotFoundError.

Parametry

condition	String nebo Condition Výraz pro vyhledání elementu GUI, který se nachází směrem dolu od elementu GUI, který je svázaný s intancí této třídy.
timeout	int [ms] Maximální doba, do které musí být vyhledán element GUI, který splňuje podmínku condition. Pokud není tento parametr specifikován, použije se implicitní hodnota viz urpa.default_timeout.
width	int [%] Udává v procentech posunutí horizontální souřadnice všech virtuálních bodů nad TP oknem od levé hrany referenčního elementu GUI. 100 procent představuje šířku referenčního elementu GUI.
step	int [px] Udává v pixelech vertikální rozestup virtuálních bodů nad TP oknem, ze kterých bude vyhledáván element GUI splňující podmínku condition.

Návratová hodnota: Vrací jeden objekt typu AppElement

Výjimky

ElementNotFoundError Požadovaný element GUI nebyl v požadovaném čase nalezen.

◆ find_first_left_to()

def urpa.AppElement.find_first_left_to	(	self,
		condition,
		timeout = `default_timeout`,
		height = `50`,
		step = `30`
	)

◆ find_first_right_to()

def urpa.AppElement.find_first_right_to	(	self,
		condition,
		timeout = `default_timeout`,
		height = `50`,
		step = `30`
	)

Metoda hledá element GUI, který splňuje podmínku condition a nachází se směrem napravo od elementu GUI, který je svázaný s instancí této třídy.

Vyhledávání elementu GUI probíhá v iteracích s prodlevou 50 ms po dobu specifikovanou v parametru timeout. Hledaný element GUI se musí vyskytovat ve shodném TP okně jako element GUI svázaný s instancí této třídy. Na začátku zpracování této metody je TP okno, které je s instancí této třídou svázáno, přeneseno na popředí. Následně jsou vypočteny nad TP oknem souřadnice virtuálních bodů, ve kterých je vyhledáván element GUI, splňující podmínku condition. Virtuální body, nad kterými je vyhledáván element GUI splňující podmínku condition, mají horizontální rozestup definovaný parametrem step (v pixelech). Počet virtuálních bodů je dán velikostí TP okna, resp. x-ová souřadnice každého virtuálního bodu musí být menší než x-ová souřadnice pravé hrany TP okna, které je svázáno s hledaným elementem GUI. Současně musí být x-ová souřadnice každého virtuálního bodu větší než x-ová souřadnice pravé hrany elementu GUI, který je svázaný s instancí této třídy. První virtuální bod má vždy x-ovou souřadnici posunutou o 5 pixelů směrem napravo od pravé hrany elementu GUI, který je svázaný s instancí této třídy. Vertikální (y-ová) souřadnice všech virtuálních bodů je nastavena na střed elementu GUI svázaného s instancí této třídy a je u všech virtuálních bodů vždy shodná. Pokud současně splňují podmínku condition elementy GUI nad větším množstvím virtuálních bodů, je vrácen element GUI, který je nejblíže elementu GUI svázaným s instancí této třídy. Pokud metoda požadovaný element GUI nenajde, vyvolá výjimku urpa.ElementNotFoundError.

Parametry

condition	String nebo Condition Výraz pro vyhledání elementu GUI, který se nachází směrem napravo od elementu GUI, který je svázaný s intancí této třídy.
timeout	int [ms] Maximální doba, do které musí být vyhledán element GUI, který splňuje podmínku condition. Pokud není tento parametr specifikován, použije se implicitní hodnota viz urpa.default_timeout.
height	int [%] Udává v procentech posunutí vertikální souřadnice všech virtuálních bodů nad TP oknem od horní hrany referenčního elementu GUI. 100 procent představuje výška referenčního elementu GUI.
step	int [px] Udává v pixelech horizontální rozestup virtuálních bodů nad TP oknem, ze kterých bude vyhledáván element GUI splňující podmínku condition.

Návratová hodnota: Vrací jeden objekt typu AppElement

Výjimky

ElementNotFoundError Požadovaný element GUI nebyl v požadovaném čase nalezen.

Examples

Příklad nalezení nejbližšího textu směrem napravo od radiobuttonu "Normal" na stránce https://playground.ultimaterpa.com v aplikaci Internet Explorer. Atributy nalezeného elementu GUI jsou vypsány do výstupní konzole.

# pomocná třída pro vytváření složitějších podmínek
cf = urpa.condition_factory()
# spuštění aplikace Internet Explorer
app = urpa.exec_ie_app("https://playground.ultimaterpa.com")
# čekání na nalezení elementu GUI - radiobuttonu "Normal"
found_element = app.find_first(cf.radio_button().name("Normal"))
# nalezení nejblížšího textu napravo od elementu GUI found_element
right_element = found_element.find_first_right_to(cf.text())
# výpis atributů nalezeného elementu GUI
print(right_element)

◆ find_first_up_to()

def urpa.AppElement.find_first_up_to	(	self,
		condition,
		timeout = `default_timeout`,
		width = `50`,
		step = `30`
	)

Metoda hledá element GUI, který splňuje podmínku condition a nachází se směrem nahoru od elementu GUI, který je svázaný s instancí této třídy.

Vyhledávání elementu GUI probíhá v iteracích s prodlevou 50 ms po dobu specifikovanou v parametru timeout. Hledaný element GUI se musí vyskytovat ve shodném TP okně jako element GUI svázaný s instancí této třídy. Na začátku zpracování této metody je TP okno, které je s instancí této třídou svázáno, přeneseno na popředí. Následně jsou vypočteny nad TP oknem souřadnice virtuálních bodů, ve kterých je vyhledáván element GUI, splňující podmínku condition. Virtuální body, nad kterými je vyhledáván element GUI splňující podmínku condition, mají vertikální rozestup definovaný parametrem step (v pixelech). Počet virtuálních bodů je dán velikostí TP okna a parametrem step, resp. y-ová souřadnice každého virtuálního bodu musí být větší než y-ová souřadnice horní hrany TP okna, které je svázáno s hledaným elementem GUI. Současně musí být y-ová souřadnice každého virtuálního bodu menší než y-ová souřadnice horní hrany elementu GUI, který je svázaný s instancí této třídy. První virtuální bod má vždy y-ovou souřadnici posunutou o 5 pixelů směrem nahoru od horní hrany elementu GUI, který je svázaný s instancí této třídy. Horizontální (x-ová) souřadnice všech virtuálních bodů je defaultně nastavena na střed referenčního elementu GUI (height = 50) a je u všech virtuálních bodů vždy shodná. Pokud současně splňují podmínku condition elementy GUI nad větším množstvím virtuálních bodů, je vrácen element GUI, který je nejblíže elementu GUI svázaným s instancí této třídy. Pokud metoda požadovaný element GUI nenajde, vyvolá výjimku urpa.ElementNotFoundError.

Parametry

condition	String nebo Condition Výraz pro vyhledání elementu GUI, který se nachází směrem nahoru od elementu GUI, který je svázaný s intancí této třídy.
timeout	int [ms] Maximální doba, do které musí být vyhledán element GUI, který splňuje podmínku condition. Pokud není tento parametr specifikován, použije se implicitní hodnota viz urpa.default_timeout.
width	int [%] Udává v procentech posunutí horizontální souřadnice všech virtuálních bodů nad TP oknem od levé hrany referenčního elementu GUI. 100 procent představuje šířku referenčního elementu GUI.
step	int [px] Udává v pixelech vertikální rozestup virtuálních bodů nad TP oknem, ze kterých bude vyhledáván element GUI splňující podmínku condition.

Návratová hodnota: Vrací jeden objekt typu AppElement

Výjimky

ElementNotFoundError Požadovaný element GUI nebyl v požadovaném čase nalezen.

◆ find_first_visual()

def urpa.AppElement.find_first_visual	(	self,
		pattern,
		region = `None`,
		timeout = `default_timeout`,
		transformations = `None`
	)

Metoda hledá vizuální element GUI (pattern) v dané oblasti (region) a vrací ho jako objekt VisualElement.

Parametry

pattern	string nebo bytearray například "img/pattern.bmp" Cesta na obrázek ve formátu png, bmp nebo hodnota vrácená metodou visual_data (bytearray).
region	tuple obsahující čtyři int například (10, 10, 20, 20) nebo None. Nepovinný argument, defaultně nastavený na hodnotu None. Tuple definuje (left, top, right, bottom) souřadnice obdélníku, který určuje vybranou oblast v px. Souřadnice jsou relativní vůči levému hornímu rohu elementu GUI, se kterým je svázána instance třídy AppElement. Hodnota None znamená, že vybraná oblast je shodná s velikostí elementu GUI, se kterým je svázána instance třídy AppElement.
timeout	int [ms] Maximální doba, do které musí být vyhledán vizuální element GUI. Pokud není tento parametr specifikován, použije se implicitní hodnota viz urpa.default_timeout.
transformations	objekt transformace, který může obsahovat několik operací modifikujících zdrojový pattern i prohledávanou oblast. Viz TransformationFactory.

Návratová hodnota: Vrací jeden objekt typu VisualElement

Výjimky

ElementNotFoundError Požadovaný vizuální element GUI nebyl v požadovaném čase nalezen.

Examples

Příklad

# Nejprve najdeme AppElement s názvem Red Rectangle.
element = app.find_first(cf.name("Red Rectangle"))
# Definujeme cestu k souboru se vzorem.
template_path = "img/template.bmp"
visual = element.find_first_visual(template_path)

◆ find_from_point()

def urpa.AppElement.find_from_point	(	self,
		x,
		y,
		condition = `None`,
		timeout = `default_timeout`
	)

Metoda vyhledá element GUI, který vyhovuje podmínce condition a současně se nachází na pozici virtuálního bodu, definovaného posunutím (parametry x, y) levého horního rohu elementu GUI, který je svázaný s instancí této třídy.

Vyhledávání elementu GUI probíhá v iteracích s prodlevou 50 ms po dobu specifikovanou v parametru timeout. V první fázi zpracování této metody je TP okno, které je svázáno s instancí této třídy, přeneseno na popředí. Ze zjištěných absolutních souřadnic elementu GUI svázaného s instancí této třídy a parametrů x, y jsou následně vypočteny souřadnice virtuálního bodu, nad kterým je hledán element GUI podle podmínky condition. Pokud element GUI nad virtuálním bodem splňuje podmínku condition, je vrácen touto metodou. Oba hledané elementy GUI se musí současně vyskytovat ve shodném TP okně. Pokud je condition == None provede se pouze první iterace a metoda vrátí element GUI z pozice virtuálního bodu. Pokud metoda žádný vyhovující element GUI nenajde, vyvolá výjimku urpa.ElementNotFoundError.

Parametry

x	int [px] Souřadnice specifikující horizontální posun, resp. souřadnice definující x-ovou relativní polohu virtuálního bodu, na které se musí nacházet element GUI splňující podmínku condition.
y	int [px] Souřadnice specifikující vertikální posun, resp. souřadnice definující y-ovou relativní polohu virtuálního bodu, na které se musí nacházet element GUI splňující podmínku condition.
condition	String nebo Condition Výraz pro vyhledání elementu GUI.
timeout	int [ms] Maximální čas na vyhledávání elementu GUI, pokud parametr není zadán, použije se implicitní hodnota urpa.default_timeout.

Návratová hodnota: Vrací jeden objekt typu AppElement.

Výjimky

ElementNotFoundError požadovaný element GUI nebyl v požadovaném čase nalezen.

Examples

Příklad nalezení obrázku, který se na stránce https://playground.ultimaterpa.com v aplikaci Internet Explorer nachází 0 pixelů směrem doprava a 60 pixelů směrem nahoru od levého horního rohu elementu GUI, který reprezentuje text "Normal". Atributy nalezeného elementu GUI jsou vypsány do výstupní konzole.

# pomocná třída pro vytváření složitějších podmínek
cf = urpa.condition_factory()
# spuštění aplikace Internet Explorer
app = urpa.exec_ie_app("https://playground.ultimaterpa.com")
# čekání na nalezení elementu GUI - textu "Normal"
found_element = app.find_first(cf.text().name("Normal"))
# nalezení obrázku - elementu GUI, který je na pozici specifikované posunutím (0,-60) levého horního rohu elementu GUI - textu "Normal"
point_element = found_element.find_from_point(0, -60, cf.image())
# výpis atributů nalezeného elementu GUI
print(point_element)

◆ item_type()

def urpa.AppElement.item_type ( self )

Metoda vrací hodnotu atributu "item type" elementu GUI svázaného s instancí této třídy.

Návratová hodnota: Vrací řetězec, který obsahuje hodnotu atributu "item type" elementu GUI svázaného s instancí této třídy.

◆ localized_control_type()

def urpa.AppElement.localized_control_type ( self )

Metoda vrací hodnotu atributu "localized control type" elementu GUI svázaného s instancí této třídy.

Návratová hodnota: Vrací řetězec, který obsahuje hodnotu atributu "localized control type" elementu GUI svázaného s instancí této třídy.

◆ name()

def urpa.AppElement.name ( self )

Metoda vrací hodnotu atributu "name" elementu GUI svázaného s instancí této třídy.

Návratová hodnota: Vrací řetězec, který obsahuje hodnotu atributu "name" elementu GUI svázaného s instancí této třídy.

◆ parent()

def urpa.AppElement.parent ( self )

Metoda vrací rodiče toho elementu.

V případě, že rodič neexistuje vrací None.

◆ post_message()

def urpa.AppElement.post_message	(	self,
		message,
		wparam,
		lparam
	)

◆ selected()

def urpa.AppElement.selected ( self )

Metoda vrací hodnotu atributu "selected" elementu GUI svázaného s instancí této třídy.

Atribut "selected" reprezentuje např. stav označení ovládacího prvku typu "radio button" nebo "list item".

Návratová hodnota: Vrací True v případě, že je element GUI "vybrán". Vrací False v případě, že element GUI není "vybrán". Vrací None v případě, že element GUI tuto vlastnost nepodporuje.

◆ send_key()

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

Metoda nasimuluje nad elementem GUI stisknutí zadané kombinace kláves.

Před nasimulováním stisknutí zadané kombinace kláves je TP okno svázané s elementem GUI přeneseno na popředí a je automaticky zavolána metoda set_focus() nad elementem GUI, který je svázaný s instancí této třídy. Vlastní simulace stisknutí zadané kombinace kláves je vázána pouze na handle TP okna tzn., pokud element GUI nezíská nebo ztratí během simulace fokus, neproběhne simulace korektně. V první fázi zpracování této metody je nejprve řetězec z parametru "text" rozložen na jednotlivé znaky. Oddělovač mezi jednotlivými znaky představuje znak '+'. Následně je vytvořena posloupnost, která reprezentuje stisknutí kláves "down" a uvolnění kláves "up" podle znaků parametru "text". Např. kombinace Ctrl+Shift+s je rozložena na posloupnost Ctrl(Down)+Shift(Down)+s(Down)+s(Up)+Shift(Up)+Ctrl(Up). Po simulaci stisknutí(Down)/uvolnění(Up) každé klávesy je vždy "zpracována" prodleva 100 ms. Pokud je v parametru "type" nastaven způsob simulace Hardware, musí simulace probíhat tzv. na popředí. Pokud běží simulace tzv. na pozadí, je při nastavení parametru "type" na hodnotu Hardware automaticky přepnuta na popředí. Při nastavení parametru "type" na hodnotu Standard dochází při simulaci k převodu jednotlivých znaků na tzv. virtual-key codes a simulace může probíhat i tzv. na pozadí. Metoda se nehodí pro přímé zadávání textu.

Parametry

text	String Kombinace kláves, jejíž stisknutí bude nad elementem GUI svázaným s instancí této třídy simulováno, např. 'ALT+x'. "ALT" "RALT" - right Alt "CTRL" "RCTRL" - right Ctrl "TAB" "ENTER", "RETURN" "BACKSPACE" "ESC", "ESCAPE" "PAUSE" "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"
type	String Způsob, jakým bude nasimulováno stisknutí jednotlivých kláves. Hardware Standard
focus_action	String Způsob, jakým bude nasimulována aktivace ovládacího prvku. Možnosti viz set_default_focus_action.

Výjimky

ValueError předaný parametr "text" nebo "type" nemá validní formát.

Examples

Příklad otevření aplikace Internet Explorer na stránce about:blank, vyvolání dialogu "Zobrazit stahované dokumenty" pomocí simulace stisknutí klávesové zkratky Ctrl+J a zavření tohoto dialogu pomocí simulace stisknutí klávesové zkratky Alt+Z.

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)
zavrit_element = app.find_first(cf.button().access_key("Alt+Z"))
time.sleep(1)
zavrit_element.send_key("Alt+Z")

◆ send_message()

def urpa.AppElement.send_message	(	self,
		message,
		wparam,
		lparam
	)

◆ send_mouse_click()

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

Metoda nasimuluje nad středem elementu GUI svázaného s instancí této třídy akci myši, která je specifikována v jejím parametru.

Implicitně provede metoda HW Left mouse click do středu elementu GUI. Prodlevy při zasílání jednotlivých zpráv, které simulují akci myši, jsou nastaveny na 50 ms.

Parametry

action	String Parametr specifikující typ akce myši, která bude nad elementem GUI nasimulována. Možné hodnoty parametru viz metoda urpa.set_default_mouse_action.
position	tuple s právě 2 prvky typu int - (left, top). Udává pozici kliku myši, ve formátu left, top. Souřádnice jsou relativní vzhledem k levému hornímu rohu elementu.

Examples

Příklad otevření stránky https://playground.ultimaterpa.com v aplikaci Internet Explorer, vyhledání "ověřovacího" elementu GUI s názvem "Continue", čekání 3 vteřiny, nasimulování klepnutí na nalezený element GUI "Continue", vyhledání ověřovacího elementu "Success".

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

◆ send_text()

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

Metoda nasimuluje nad elementem GUI stisknutí a uvolnění posloupnosti kláves, která je reprezentována řetězcem v parametru "text".

Před nasimulováním stisknutí a uvolnění kláves je TP okno svázané s elementem GUI přeneseno na popředí a je automaticky zavolána metoda set_focus() nad elementem GUI, který je svázaný s instancí této třídy. Vlastní simulace stisknutí/uvolnění kláves je vázána pouze na handle TP okna tzn., pokud element GUI nezíská nebo ztratí během simulace fokus, neproběhne simulace korektně. V první fázi zpracování této metody je nejprve řetězec z parametru "text" rozložen na jednotlivé znaky. Následně je vytvořena posloupnost, která reprezentuje stisknutí kláves "down" a uvolnění kláves "up" podle znaků v parametru "text". Např. řetězec "Lev" je rozložen na posloupnost Shift(Down)+l(Down)+l(Up)+Shift(Up)+e(Down)+e(Up)+v(Down)+v(Up). Po simulaci stisknutí(Down)/uvolnění(Up) každé klávesy je vždy "zpracována" prodleva 100 ms. Pokud je v parametru "type" nastaven jeden ze způsobů simulace "hw", musí simulace probíhat tzv. na popředí. Pokud běží simulace tzv. na pozadí, je při nastavení parametru "type" na jednu z hodnot "hw" automaticky přepnuta na popředí. Při nastavení parametru "type" na jednu z hodnot "standard" dochází při simulaci k převodu jednotlivých znaků na tzv. virtual-key codes nebo alt-codes a simulace může probíhat i tzv. na pozadí. Při nastavení parametru "type" na hodnotu "wm_char" dochází při simulaci k přímému rozkladu řetězce z parametru "text" na jednotlivé znaky.

Parametry

text	String Text, jehož zápis bude simulován nad aplikací svázanou s elementem GUI, který je reprezentován instancí této třídy.
action	String Způsob, jakým bude nasimulováno stisknutí jednotlivých kláves, které reprezentuje řetězec v parametru "text". "hw_alt_code" Tato volba používá klasický rozklad znaků textu na Alt−code a jejich postupnou simulaci. Nad aplikací svázanou s elementem GUI je volána při simulaci Windows API funkce keybd_event(). "hw_scan_virtual" Tato volba používá rozklad znaků z parametru "text" za pomoci převodních .xml souborů z adresáře KeybLayoutTranslate. Pokud bude nastaveno v parametru "kl" rozložení klávesnice, pro které neexistuje soubor KeybLayoutTranslate\00000.xml, je nutné tento soubor pro příslušné rozložení klávesnice vytvořit, jinak nebude simulace uživatelské aktivity fungovat korektně. Nad aplikací svázanou s elementem GUI je volána při simulaci Windows API funkce keybd_event(). "standard_alt_code" Tato volba používá klasický rozklad znaků textu na Alt−code a jejich postupnou simulaci. Aplikaci svázané s elementem GUI jsou zaslány pomocí Windows API funkce PostMessage() zprávy s parametry WM_KEYDOWN a WM_KEYUP. "standard_scan_virtual" Tato volba používá rozklad znaků z parametru "text" za pomoci převodních .xml souborů z adresáře KeybLayoutTranslate. Pokud bude nastaveno v parametru "kl" rozložení klávesnice, pro které neexistuje soubor KeybLayoutTranslate\00000.xml, je nutné tento soubor pro příslušné rozložení klávesnice vytvořit, jinak nebude simulace uživatelské aktivity fungovat korektně. Aplikaci svázané s elementem GUI jsou zaslány pomocí Windows API funkce PostMessage() zprávy s parametry WM_KEYDOWN a WM_KEYUP. "wm_char" Tato volba je vhodná při nejednoznačnosti určení Keyboard layoutu a při potřebě předat aplikaci znaky, které jsou přístupné u různých kontextů klávesnic. Při simulaci dochází po nastavení této volby pouze k přímému rozkladu řetězce z parametru text. Rozložení klávesnice, nastavené v parametru "kl", je při použití tohoto způsobu simulace ignorováno.
kl	String Reprezentuje rozložení klávesnice, které je při simulaci zadávání textu automaticky nastaveno aplikaci, svázané s elementem GUI.
focus_action	String Způsob, jakým bude nasimulována aktivace ovládacího prvku. Možnosti viz set_default_focus_action.

Výjimky

ValueError jeden z předaných parametrů nemá validní formát.

Examples

Příklad otevření aplikace Internet Explorer na stránce about:blank, nasimulování zadání textu https://playground.ultimaterpa.com do adresního řádku a přechod na tuto stránku pomocí simulace stisknutí tlačítka Enter.

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"))

◆ set_focus()

def urpa.AppElement.set_focus	(	self,
		focus_action = `default_focus_action`
	)

Metoda nastaví focus elementu GUI svázanému s instancí této třídy.

Parametry

focus_action String Způsob, jakým bude nasimulována aktivace ovládacího prvku. Možnosti viz set_default_focus_action.

◆ size()

def urpa.AppElement.size ( self )

Metoda vrací velikost elementu GUI svázaného s instancí této třídy v pořadí width, height.

Návratová hodnota: Vrací tuple, který obsahuje velikost elementu GUI svázaného s instancí této třídy v pořadí width, height.

◆ toggle_state()

def urpa.AppElement.toggle_state ( self )

Metoda vrací hodnotu atributu "toggle state" elementu GUI svázaného s instancí této třídy.

Atribut "toggle state" reprezentuje nejčastěji stav zaškrtnutí checkboxu.

Návratová hodnota: Vrací True v případě, že je element GUI "zaškrtnut". Vrací False v případě, že element GUI není "zaškrtnut". Vrací None v případě, že je element GUI v neurčitém (indeterminate) stavu nebo v případě, že tuto vlastnost nepodporuje.

◆ value()

def urpa.AppElement.value ( self )

Metoda vrací hodnotu atributu "value" elementu GUI svázaného s instancí této třídy.

Návratová hodnota: Vrací řetězec, který obsahuje hodnotu atributu "value" elementu GUI svázaného s instancí této třídy.

◆ visual_data()

def urpa.AppElement.visual_data	(	self,
		rect = `None`,
		format = `"bmp"`
	)

Metoda vytvoří obrázek z elementu GUI, který je svázaný s instancí této třídy.

Parametry

rect	tuple s právě 4 prvky typu int - (left, top, right, bottom). Relativní souřadnice (vzhledem k levému hornímu rohu elementu GUI) pro definování výřezu. Implicitně se použije celý výřez elementu viz bounding_rectangle.
format	String Určuje formát dat "bmp" nebo "png".

Návratová hodnota: Vrací obrázek ve formátu bmp jako bytearray.

Examples

Příklad načtení obrázku pomocí modulu PIL (https://python-pillow.org/):

image_data = element_start.visual_data()
image = Image.open(io.BytesIO(image_data))
image.show()

Dokumentace pro tuto třídu byla generována z následujícího souboru:

urpa.py

Veřejné metody

Detailní popis

Dokumentace k metodám

◆ access_key()

◆ automation_id()

◆ bounding_rectangle()

◆ class_name()

◆ control_type()

◆ enabled()

◆ find_all()

◆ find_all_visual()

◆ find_first()

◆ find_first_down_to()

◆ find_first_left_to()

◆ find_first_right_to()

◆ find_first_up_to()

◆ find_first_visual()

◆ find_from_point()

◆ item_type()

◆ localized_control_type()

◆ name()

◆ parent()

◆ post_message()

◆ selected()

◆ send_key()

◆ send_message()

◆ send_mouse_click()

◆ send_text()

◆ set_focus()

◆ size()

◆ toggle_state()

◆ value()

◆ visual_data()