Table of Contents

Interface IElement

Namespace
Ranorex.Core
Assembly
Ranorex.Core.dll

Represents an UI item in the global UI tree. Instances of this class dynamically implement a Role and optional Capabilities, as well as numerous standard properties.

public interface IElement

Properties

Actions

A list of actions the element supports. This list is aggregated from the role and the capabilities.

IList<ActionDescriptor> Actions { get; }

Property Value

IList<ActionDescriptor>

Attributes

A list of attributes the element supports. This list is aggregated from the role and the capabilities.

IList<AttributeDescriptor> Attributes { get; }

Property Value

IList<AttributeDescriptor>

Capabilities

The list of the capabilities the element has.

IList<Capability> Capabilities { get; }

Property Value

IList<Capability>

ChildIndex

The index of this element in the parent's child list. Is '-1' if the index is unknown.

int ChildIndex { get; }

Property Value

int

Children

The list of children the element has.

IList<Element> Children { get; }

Property Value

IList<Element>

ClientRectangle

The bounding rectangle of the element, relative to the parent.

Rectangle ClientRectangle { get; }

Property Value

Rectangle

DynamicCapability

Gets a capability providing dynamic attributes and actions that the element supports.

Capability DynamicCapability { get; }

Property Value

Capability

Enabled

True if the element is enabled.

bool Enabled { get; }

Property Value

bool

FlavorElement

The flavor element associated with the element. This can be null, for example when using static snapshots.

FlavorElement FlavorElement { get; }

Property Value

FlavorElement

FlavorName

The name of the flavor this element belongs to.

string FlavorName { get; }

Property Value

string

HasFocus

True if the element has the focus.

bool HasFocus { get; }

Property Value

bool

IsRemote

Gets a value indicating whether the element resides on a remote device.

bool IsRemote { get; }

Property Value

bool

true if this instance resides on a remote device; otherwise, false.

IsSnapshot

Gets a value indicating whether this instance is a snapshot.

bool IsSnapshot { get; }

Property Value

bool

true if this instance is a snapshot; otherwise, false.

this[string]

Indexer for attribute access.

object this[string name] { get; set; }

Parameters

name string

Name of the attribute to return.

Property Value

object

The value of the attribute.

Limitations

Gets a list of technology specify limitations that are associated with this element.

IList<TechnologyLimitation> Limitations { get; }

Property Value

IList<TechnologyLimitation>

Remarks

The list implementation checks for duplicates and null entries and does not add/insert such entries.

Location

The location of the element, relative to its parent.

Point Location { get; }

Property Value

Point

Parent

The parent of the element.

Element Parent { get; }

Property Value

Element

Remarks

Is null if the element is a root element.

PreferredCapability

The preferred capability of the element.

Capability PreferredCapability { get; }

Property Value

Capability

Remarks

Usually, this is the role, but it can be any of the capabilities. This property is used when building RxPaths.

Role

The role of the element (= main capability).

Role Role { get; }

Property Value

Role

ScreenLocation

The location of the element in screen coordinates.

Point ScreenLocation { get; }

Property Value

Point

ScreenRectangle

The bounding rectangle of the element in screen coordinates.

Rectangle ScreenRectangle { get; }

Property Value

Rectangle

Size

The (x,y) size of element.

Size Size { get; }

Property Value

Size

TopLevelAncestor

The top-level ancestor of the element.

Element TopLevelAncestor { get; }

Property Value

Element

Remarks

Is null if the element is a root element.

Valid

Returns true if the element is believed to be valid.

bool Valid { get; }

Property Value

bool

Visible

True if the element is visible.

bool Visible { get; }

Property Value

bool

Remarks

Note that even if the element is visible, it might be covered by another visible element.

Methods

As<T>()

Returns an adapter of the specified type for the element.

T As<T>() where T : Adapter

Returns

T

The specified adapter for the element or null if the element does not provide the capabilities required for the adapter.

Type Parameters

T

The adapter type. The supplied type must inherit from Adapter, but most not be the Adapter type itself.

CaptureCompressedImage()

Captures a PNG image of the element.

CompressedImage CaptureCompressedImage()

Returns

CompressedImage

A compressed image of the element.

EnsureVisible()

Tries to make the element visible to the user. This is usually accomplished by bringing the element or one of its ancestors to foreground.

bool EnsureVisible()

Returns

bool

True if the operation has succeeded.

Find(RxPath)

Applies a Ranorex Path to the element.

IList<Element> Find(RxPath path)

Parameters

path RxPath

The RxPath to apply.

Returns

IList<Element>

The list of elements found for that path.

Exceptions

ArgumentNullException

If path is null.

Find(RxPath, Duration)

Applies a Ranorex Path to the element.

IList<Element> Find(RxPath path, Duration timeout)

Parameters

path RxPath

The RxPath to apply.

timeout Duration

The time to keep looking for at least one element matching the path.

Returns

IList<Element>

The list of elements found for that path.

Exceptions

ArgumentNullException

If path is null.

FindFromPoint(Point)

Find an element by screen location. The found element is a descendant of this instance or this instance itself.

Element FindFromPoint(Point screenLocation)

Parameters

screenLocation Point

The location where the element is located.

Returns

Element

The element at the specified location or null if nothing was found.

Remarks

This method requires a Ranorex Professional/Premium license.

FindFromPoint(Point, out RxPath)

Find an element by screen location and build its RxPath. The found element is a descendant of this instance or this instance itself.

Element FindFromPoint(Point screenLocation, out RxPath resultPath)

Parameters

screenLocation Point

The location where the element is located.

resultPath RxPath

The result RxPath.

Returns

Element

The element at the specified location or null if nothing was found.

Remarks

This method requires a Ranorex Professional/Premium license.

FindFromUid(string, out Element)

Finds a descendant element by its unique identifier attribute (defined by the owner flavor UidAttribute name).

bool FindFromUid(string uidValue, out Element result)

Parameters

uidValue string

The unique id value.

result Element

The result element, if anything was found.

Returns

bool

Returns true if an element was found for the given unique id value.

Remarks

For this to work, the underlying flavor element has to implement GetChildLineageFromUid() and has to set IsUidDomainRoot properly.

FindSingle(RxPath)

Applies a Ranorex Path to the element.

Element FindSingle(RxPath path)

Parameters

path RxPath

The RxPath to apply.

Returns

Element

The first element found.

Exceptions

ArgumentNullException

If path is null.

ElementNotFoundException

If no element is found.

FindSingle(RxPath, Duration)

Applies a Ranorex Path to the element.

Element FindSingle(RxPath path, Duration timeout)

Parameters

path RxPath

The RxPath to apply.

timeout Duration

The time to keep looking for the element.

Returns

Element

The first element found.

Exceptions

ArgumentNullException

If path is null.

ElementNotFoundException

If no element is found within the timeout.

Focus()

Tries to set the focus on the element.

void Focus()

GetAttributeValue(string)

Returns the value of an attribute.

object GetAttributeValue(string name)

Parameters

name string

The name of the attribute.

Returns

object

The value of the attribute.

Exceptions

ArgumentNullException

If name is null.

GetAttributeValueText(string)

Returns the value of an attribute converted to its string representation.

string GetAttributeValueText(string name)

Parameters

name string

The name of the attribute.

Returns

string

The value of the attribute converted to its string representation.

Remarks

This method internally calls GetAttributeValue(string) and converts the returned value to its string representation using the ValueConverter.

Exceptions

ArgumentNullException

If name is null.

GetAttributeValueText(string, Regex)

Returns the value of an attribute converted to its string representation. If a regex is provided, only the part of the string representation matching the regular expression is returned.

string GetAttributeValueText(string name, Regex regex)

Parameters

name string

The name of the attribute.

regex Regex

A regular expression that defines which part of the attribute value string representation should be returned. If more than a single group (= whole match) is captured by the regex, the second group (mark using "(?<1>expression)") is returned.

Returns

string

The value of the attribute converted to its string representation and optionally matched by the provided regex regular expression.

Remarks

This method internally calls GetAttributeValue(string) and converts the returned value to its string representation using the ValueConverter.

Exceptions

ArgumentNullException

If name is null.

GetObjectData(SerializationInfo, StreamingContext)

For Ranorex internal use only. Populates a SerializationInfo with the data needed to serialize the target object.

void GetObjectData(SerializationInfo info, StreamingContext context)

Parameters

info SerializationInfo

The SerializationInfo to populate with data.

context StreamingContext

The destination (see StreamingContext) for this serialization.

GetPath(PathBuildMode)

Builds an absolute RxPath to the element.

RxPath GetPath(PathBuildMode buildMode)

Parameters

buildMode PathBuildMode

Specifies how the path should be built. (optimization vs. runtime tradeoff)

Returns

RxPath

The path of the element.

GetPath(PathBuildMode, Element)

Builds an RxPath to the element, relative to another element.

RxPath GetPath(PathBuildMode buildMode, Element relativeToElement)

Parameters

buildMode PathBuildMode

Specifies how the path should be built. (optimization vs. runtime tradeoff)

relativeToElement Element

The element to which the path is relative to.

Returns

RxPath

The path of the element.

GetRobustPath()

Builds an absolute robust RxPath to the element.

RxPath GetRobustPath()

Returns

RxPath

HasCapability(string)

Tests if the element possesses a certain capability (or role), by name.

bool HasCapability(string capName)

Parameters

capName string

The name of the capability to look for.

Returns

bool

True if the element has the capability or role.

InvokeAction(string, params object[])

Invokes an action on the element.

object InvokeAction(string name, params object[] args)

Parameters

name string

The name of the action to invoke.

args object[]

The list of parameters for the action.

Returns

object

The invocation result.

Remarks

The types of the parameters and return value are as defined by the ActionDescriptor.

Exceptions

ArgumentNullException

If name is null.

ActionFailedException

Thrown if invoking the action failed.

InvokeActionWithText(string, params string[])

Invokes an action on the element.

object InvokeActionWithText(string name, params string[] args)

Parameters

name string

The name of the action to invoke.

args string[]

The list of parameters for the action, as strings.

Returns

object

The invocation result.

Remarks

The string values of the parameters are converted to the types defined by the ActionDescriptor.

Exceptions

ArgumentNullException

If name is null.

ActionFailedException

Thrown if invoking the action failed, or argument type conversion failed.

IsAncestor(Element)

Determines whether the current element is an ancestor of the specified child element.

bool IsAncestor(Element child)

Parameters

child Element

The child element to test.

Returns

bool

true if the this element is an ancestor; otherwise, false.

IsEqual(Element)

Compares two elements by comparing their flavor elements or their screen rectangles if no flavor comparison is possible.

bool IsEqual(Element elem)

Parameters

elem Element

The element to compare to.

Returns

bool

True if the elements are equal.

SetAttributeValue(string, object)

Sets the value of an attribute.

void SetAttributeValue(string name, object value)

Parameters

name string

The name of the attribute.

value object

The value to set.

Exceptions

ArgumentNullException

If name is null.

SetAttributeFailedException

Thrown if setting the attribute value failed.

SetAttributeValue(string, string)

Sets the value of an attribute.

void SetAttributeValue(string name, string value)

Parameters

name string

The name of the attribute.

value string

The value to set as string.

Exceptions

ArgumentNullException

If name is null.

SetAttributeFailedException

Thrown if setting the attribute value failed or the string value could not be converted to the attribute's type.

TryFindSingle(RxPath, out Element)

Tries to apply a Ranorex Path to the element.

bool TryFindSingle(RxPath path, out Element foundElement)

Parameters

path RxPath

The RxPath to apply.

foundElement Element

The first element found or null if no element is found.

Returns

bool

True if an element is found for the specified path, otherwise false.

TryFindSingle(RxPath, Duration, out Element)

Tries to apply a Ranorex Path to the element.

bool TryFindSingle(RxPath path, Duration timeout, out Element foundElement)

Parameters

path RxPath

The RxPath to apply.

timeout Duration

The time to keep looking for the element.

foundElement Element

The first element found or null if no element is found within the timeout.

Returns

bool

True if an element is found for the specified path within the specified timeout, otherwise false.