OnScreenElement

Description
The general idea of the BaseModel is that everything that is shown on the screen inherits from the OnScreenElement. The most important functionalities supported by the OnScreenElement class are the possibility to wait for the element, which ensures the element is displayed on the screen before interacting with it, and the Do method, which ensures the interactions with the element are verified and retried if necessary.‌
OnScreenElement Class (abstract)
Namespace: Progile.TRIO.BaseModel
Assembly: Progile.TRIO.BaseModel (in Progile.TRIO.BaseModel.dll)‌
Inheritance Hierarchy:
​Object
   Progile.TRIO.BaseModel.OnScreenElement‌
Constructors
OnScreenElement(ITester, string, bool ,ImageReference[])
Syntax:
public OnScreenElement(
	ITester tester,
	string displayName,
	bool useVisualSense,
	params ImageReference[] imageReference
)
Parameter
Description
tester
Type: ITester​
The tester interface.
displayName
Type: String​
The name of the element that will be used for logging and reporting of exceptions (customer facing).
useVisualSense
Type: Boolean
Set to true if VisualSense should be used to find the element
imageReference
Type: ImageReference​
One or multiple image references that will be used to locate the element on the screen.
Exceptions:
Exception
Condition
ArgumentNullException
testerInterface, displayName and imageReference cannot be null or empty.
OnScreenElement(ITester, string, ImageReference[])
Syntax:
public OnScreenElement(
	ITester tester,
	string displayName,
	params ImageReference[] imageReference
)
Parameter
Description
tester
Type: ITester​
The tester interface.
displayName
Type: String​
The name of the element that will be used for logging and reporting of exceptions (customer facing).
imageReference
Type: ImageReference​
One or multiple image references that will be used to locate the element on the screen.
Exceptions:
Exception
Condition
ArgumentNullException
testerInterface, displayName and imageReference cannot be null or empty.
OnScreenElement(ITester, string, bool, string)
Syntax:
public OnScreenElement(
	ITester tester,
	string displayName,
	bool useVisualSense,
	string searchText
)
Parameter
Description
tester
Type: ITester​
The tester interface.
displayName
Type: String​
The name of the element that will be used for logging and reporting of exceptions (customer facing).
useVisualSense
Type: Boolean
Set to true if VisualSense should be used to find the element
searchText
Type: String​
The searchText that will be used to locate the element on the screen.
Exceptions:
Exception
Condition
ArgumentNullException
testerInterface, displayName and searchText cannot be null or empty.
OnScreenElement(ITester, string, string)
Syntax:
public OnScreenElement(
	ITester tester,
	string displayName,
	string searchText
)
Parameter
Description
tester
Type: ITester​
The tester interface.
displayName
Type: String​
The name of the element that will be used for logging and reporting of exceptions (customer facing).
searchText
Type: String​
The searchText that will be used to locate the element on the screen.
Exceptions:
Exception
Condition
ArgumentNullException
testerInterface, displayName and searchText cannot be null or empty.
Methods
Name
Description
​FindAllInstances​
Finds all instances of the element that are visible on the screen.
​IsOnScreen​
Determines whether the element is currently shown on the screen using the WaitFor method with a very short wait time.
Note: Do not use this if you expect the element to appear after an action (e.g. as verify method of another action), only if the screen is expected to be static.
​ScrollAndFindElement​
Uses the provided IScroller (if available) to find the OnScreenElement in a scrollable area. If the element is not found at current position, scrolls to top and then down in steps.
​SetSelectFilter​
Adds the select filter to Filters or replaces any existing Select filter. Other filter types in Filters are not changed.
​ToString​
Returns a string that represents this instance, usually the DisplayName. Used for logging; just use $"{this}".
​WaitFor​
Waits for the element to appear on screen and returns an IEngineResult. If the element is found, it will call the Initialize method to initialize potential child elements that depend on the Position found by WaitFor. By default throws an exception if the element is not found after WaitTimeInSeconds.
​WaitForAppear​
Shorthand notation for WaitFor(false).HasSucceeded;
Can be used as verify function without lambda operator (e.g. Buttton.Click(element.WaitForDisappear);)
Note: This method logs, whereas WaitFor() does not log.
​WaitForDisappear​
Waits for the element to disappear from the screen. Returns false if element is still found after DisappearWaitTimeInSeconds.
Can be used as verify function without lambda operator (e.g. Buttton.Click(element.WaitForDisappear);)
​WaitForDisappearOrOtherElement​
Waits for the element to disappear from the screen or any element from elements to appear.
This is often used as verify method of an interaction that closes a dialog or similar but can also show a warning instead.
Returns false if this element is still found after DisappearWaitTimeInSeconds and no element from elements was found. Will return the element that was found in foundElement.
Protected Methods
Name
Description
​WaitForImpl​
The implementation for WaitFor that performs the actual search of the element on the screen.
WaitFor
Waits for a specific imageReference of the element to appear on screen and returns an IEngineResult. This method is intended for elements like Button or Checkbox to Wait for a certain state (like inactive or checked). If the image reference is found, it will call the Initialize method to initialize potential child elements that depend on the Position found by WaitFor. If imageReference is null, it behaves like WaitFor. By default throws an exception if element is not found after waitTime.
​Do​
Executes the specified interact method on the element and verifies the interaction with the verify function. Performs RetryCount retries if the verify is not successful.
​Initialize​
Initializes potential child controls on this Element. This method is called when WaitFor() did find the element. Has no implementation on OnScreenElement.
Properties
Name
Description
​DefaultDisappearWaitTime​
Default value for DisappearWaitTimeInSeconds of new OnScreenElements. Default is 20 seconds.
​DefaultWaitTime​
Default value for WaitTimeInSeconds of new OnScreenElements. Default is 60 seconds.
​DisappearWaitTimeInSeconds​
How long to wait for the element to disappear from the screen. Defaults to DefaultDisappearWaitTime.
​Filters​
The image filters that will be used to find the element on screen (e.g. Select filter to limit the search to a specific rectangle). Should be used in all methods on derived elements for finding the element.
​ImageParameters​
Parameters for the image search to find the element on screen. Should be used in all methods on derived elements for finding the element.
​ParentElement​
The  BaseScreen which contains this element. This is used to wait for the parent screen before finding this element.
Typically this property is directly set to the screen (this) from which the element is instantiated.
​Position​
The search result of WaitFor. Gives the IEngineResult with the Position of the image or text that locates the element on the screen. Is only set if WaitFor succeeded, thus it should always be Position.HasSucceeded() = true;
​RetryCount​
Determines how many times an interaction shall be attempted, 1 meaning 1 attempt, so no retries. Default = 3.
​TextParameters​
Parameters for the text search to find the element on screen. Should be used in all methods on derived elements for finding the element.
​WaitTimeInSeconds​
How long to wait for the element to appear on screen. Defaults to DefaultWaitTime.
Protected Properties
Name
Description
DisplayName
The name of the element that will be used for logging and reporting of exceptions (customer facing).
RetryDelay
The delay to wait before a retry in miliseconds. Defaults to t.Properties.SearchRetryWaitTimeInMs​
FindElementBeforeRetry
Determines whether the element should be searched again before doing a retry. Default is false, however most predefined Elements such as Button and TextBox have this property set to true.
ImageReferences
The image reference(s) that will be used to locate the element on the screen.
SearchText
The search text that will be used to locate the element on the screen.
SearchType
The searchType (Image or Text) that will be used to locate the element on the screen.

BaseScreen Methods

OnScreenElement Methods

Last modified 4mo ago

Parameter	Description
tester	Type: ITester The tester interface.
displayName	Type: String The name of the element that will be used for logging and reporting of exceptions (customer facing).
useVisualSense	Type: Boolean Set to true if VisualSense should be used to find the element
imageReference	Type: ImageReference One or multiple image references that will be used to locate the element on the screen.

Parameter	Description
tester	Type: ITester The tester interface.
displayName	Type: String The name of the element that will be used for logging and reporting of exceptions (customer facing).
imageReference	Type: ImageReference One or multiple image references that will be used to locate the element on the screen.

Parameter	Description
tester	Type: ITester The tester interface.
displayName	Type: String The name of the element that will be used for logging and reporting of exceptions (customer facing).
useVisualSense	Type: Boolean Set to true if VisualSense should be used to find the element
searchText	Type: String The searchText that will be used to locate the element on the screen.

Parameter	Description
tester	Type: ITester The tester interface.
displayName	Type: String The name of the element that will be used for logging and reporting of exceptions (customer facing).
searchText	Type: String The searchText that will be used to locate the element on the screen.

Exception	Condition
ArgumentNullException	testerInterface, displayName and imageReference cannot be null or empty.

Name	Description
FindAllInstances	Finds all instances of the element that are visible on the screen.
IsOnScreen	Determines whether the element is currently shown on the screen using the WaitFor method with a very short wait time. Note: Do not use this if you expect the element to appear after an action (e.g. as verify method of another action), only if the screen is expected to be static.
ScrollAndFindElement	Uses the provided IScroller (if available) to find the OnScreenElement in a scrollable area. If the element is not found at current position, scrolls to top and then down in steps.
SetSelectFilter	Adds the select filter to Filters or replaces any existing Select filter. Other filter types in Filters are not changed.
ToString	Returns a string that represents this instance, usually the DisplayName. Used for logging; just use `$"{this}"`.
WaitFor	Waits for the element to appear on screen and returns an IEngineResult. If the element is found, it will call the Initialize method to initialize potential child elements that depend on the Position found by WaitFor. By default throws an exception if the element is not found after WaitTimeInSeconds.
WaitForAppear	Shorthand notation for `WaitFor(false).HasSucceeded;` Can be used as verify function without lambda operator (e.g. `Buttton.Click(element.WaitForDisappear);`) Note: This method logs, whereas WaitFor() does not log.
WaitForDisappear	Waits for the element to disappear from the screen. Returns false if element is still found after DisappearWaitTimeInSeconds. Can be used as verify function without lambda operator (e.g. `Buttton.Click(element.WaitForDisappear);`)
WaitForDisappearOrOtherElement	Waits for the element to disappear from the screen or any element from elements to appear. This is often used as verify method of an interaction that closes a dialog or similar but can also show a warning instead. Returns false if `this` element is still found after DisappearWaitTimeInSeconds and no element from elements was found. Will return the element that was found in foundElement.

Name	Description
WaitForImpl	The implementation for WaitFor that performs the actual search of the element on the screen.
WaitFor	Waits for a specific imageReference of the element to appear on screen and returns an IEngineResult. This method is intended for elements like Button or Checkbox to Wait for a certain state (like inactive or checked). If the image reference is found, it will call the Initialize method to initialize potential child elements that depend on the Position found by WaitFor. If imageReference is null, it behaves like WaitFor. By default throws an exception if element is not found after waitTime.
Do	Executes the specified interact method on the element and verifies the interaction with the verify function. Performs RetryCount retries if the verify is not successful.
Initialize	Initializes potential child controls on this Element. This method is called when WaitFor() did find the element. Has no implementation on OnScreenElement.

Name	Description
DefaultDisappearWaitTime	Default value for DisappearWaitTimeInSeconds of new OnScreenElements. Default is 20 seconds.
DefaultWaitTime	Default value for WaitTimeInSeconds of new OnScreenElements. Default is 60 seconds.
DisappearWaitTimeInSeconds	How long to wait for the element to disappear from the screen. Defaults to DefaultDisappearWaitTime.
Filters	The image filters that will be used to find the element on screen (e.g. Select filter to limit the search to a specific rectangle). Should be used in all methods on derived elements for finding the element.
ImageParameters	Parameters for the image search to find the element on screen. Should be used in all methods on derived elements for finding the element.
ParentElement	The BaseScreen which contains this element. This is used to wait for the parent screen before finding this element. Typically this property is directly set to the screen (`this`) from which the element is instantiated.
Position	The search result of WaitFor. Gives the IEngineResult with the Position of the image or text that locates the element on the screen. Is only set if WaitFor succeeded, thus it should always be `Position.HasSucceeded() = true;`
RetryCount	Determines how many times an interaction shall be attempted, 1 meaning 1 attempt, so no retries. Default = 3.
TextParameters	Parameters for the text search to find the element on screen. Should be used in all methods on derived elements for finding the element.
WaitTimeInSeconds	How long to wait for the element to appear on screen. Defaults to DefaultWaitTime.

Name	Description
DisplayName	The name of the element that will be used for logging and reporting of exceptions (customer facing).
RetryDelay	The delay to wait before a retry in miliseconds. Defaults to `t.Properties.SearchRetryWaitTimeInMs`
FindElementBeforeRetry	Determines whether the element should be searched again before doing a retry. Default is false, however most predefined Elements such as Button and TextBox have this property set to true.
ImageReferences	The image reference(s) that will be used to locate the element on the screen.
SearchText	The search text that will be used to locate the element on the screen.
SearchType	The searchType (Image or Text) that will be used to locate the element on the screen.