Table of Contents

Class Element

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.

[TypeConverter(typeof(ExpandableObjectConverter))]
public class Element : MarshalByRefObject, IElement, ISerializable
Inheritance
Element
Implements
Inherited Members

Constructors

Element(SerializationInfo, StreamingContext)

For Ranorex internal use only. Initializes a new instance of the Element class.

[Browsable(false)]
protected Element(SerializationInfo info, StreamingContext context)

Parameters

info SerializationInfo

The serialization information.

context StreamingContext

The streaming context.

Properties

Actions

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

[Browsable(false)]
[TypeConverter(typeof(CollectionConverter))]
public 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.

[Browsable(false)]
[TypeConverter(typeof(CollectionConverter))]
public IList<AttributeDescriptor> Attributes { get; }

Property Value

IList<AttributeDescriptor>

Capabilities

The list of the capabilities the element has.

[Browsable(false)]
[TypeConverter(typeof(CollectionConverter))]
public 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.

public int ChildIndex { get; }

Property Value

int

Children

The list of children the element has.

[Browsable(false)]
[TypeConverter(typeof(CollectionConverter))]
public IList<Element> Children { get; }

Property Value

IList<Element>

ClientRectangle

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

public Rectangle ClientRectangle { get; }

Property Value

Rectangle

DynamicCapability

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

public Capability DynamicCapability { get; }

Property Value

Capability

Enabled

True if the element is enabled.

public bool Enabled { get; }

Property Value

bool

FlavorElement

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

[Browsable(false)]
public FlavorElement FlavorElement { get; }

Property Value

FlavorElement

FlavorName

The name of the flavor this element belongs to.

public string FlavorName { get; }

Property Value

string

HasFocus

True if the element has the focus.

public bool HasFocus { get; }

Property Value

bool

IsRemote

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

[Browsable(false)]
public 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.

[Browsable(false)]
public bool IsSnapshot { get; }

Property Value

bool

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

this[string]

Indexer for attribute access.

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

[Browsable(false)]
[TypeConverter(typeof(CollectionConverter))]
public 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.

public Point Location { get; }

Property Value

Point

Parent

The parent of the element.

[Browsable(false)]
[TypeConverter(typeof(ExpandableObjectConverter))]
public Element Parent { get; }

Property Value

Element

Remarks

Is null if the element is a root element.

PreferredCapability

The preferred capability of the element.

public 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).

public Role Role { get; }

Property Value

Role

ScreenLocation

The location of the element in screen coordinates.

public Point ScreenLocation { get; }

Property Value

Point

ScreenRectangle

The bounding rectangle of the element in screen coordinates.

public Rectangle ScreenRectangle { get; }

Property Value

Rectangle

Size

The (x,y) size of element.

public Size Size { get; }

Property Value

Size

TopLevelAncestor

The top-level ancestor of the element.

[Browsable(false)]
[TypeConverter(typeof(ExpandableObjectConverter))]
public 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.

public bool Valid { get; }

Property Value

bool

Visible

True if the element is visible.

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

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

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

public bool EnsureVisible()

Returns

bool

True if the operation has succeeded.

Equals(Element, Element)

Returns true if the two instances are considered equal.

public static bool Equals(Element a, Element b)

Parameters

a Element

An instance.

b Element

Another instance.

Returns

bool

True if the two instances are equal, otherwise false.

Equals(object)

Compares the element to an object.

public override bool Equals(object obj)

Parameters

obj object

The object to compare to.

Returns

bool

True if obj and the element are the same.

Find(RxPath)

Applies a Ranorex Path to the element.

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

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

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

public 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).

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

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

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

public void Focus()

FromPath(string)

Converts a string to an element instance by searching the root.

public static Element FromPath(string path)

Parameters

path string

The search path.

Returns

Element

The result element.

Remarks

The DefaultSearchTimeout is used to search for the specified path.

Exceptions

ArgumentNullException

If path is null.

ElementNotFoundException

If no element is found.

RxPathException

If the specified path is not valid.

GetAttributeValue(string)

Returns the value of an attribute.

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

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

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

GetHashCode()

Default implementation override.

public override int GetHashCode()

Returns

int

The object hash code.

GetObjectData(SerializationInfo, StreamingContext)

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

[Browsable(false)]
public virtual 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.

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

public 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 RxPath to the element.

public RxPath GetRobustPath()

Returns

RxPath

The path of the element.

HasCapability(string)

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

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

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

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

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

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

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

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

ToString()

Returns a string that represents the current object.

public override string ToString()

Returns

string

A string that represents the current object.

TryFindSingle(RxPath, out Element)

Tries to apply a Ranorex Path to the element.

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

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

Operators

implicit operator Element(string)

Implicitly converts a string to an element instance by searching the root.

public static implicit operator Element(string path)

Parameters

path string

The search path.

Returns

Element

The result element.

Remarks

The DefaultSearchTimeout is used to search for the specified path.

Exceptions

ArgumentNullException

If path is null.

ElementNotFoundException

If no element is found.

RxPathException

If the specified path is not valid.