Class Location

Namespace

Ranorex

Assembly

Ranorex.Core.dll

Represents an abstract, relative location within an element or on the screen.

[TypeConverter(typeof(Location.LocationConverter))]
public class Location : IEquatable<Location>

Inheritance

object

Location

Implements

IEquatable<Location>

Inherited Members

object.Equals(object, object)

object.ReferenceEquals(object, object)

object.GetType()

object.MemberwiseClone()

Remarks

A location is a relative offset inside an element. It can either be specified by a fixed pixel value (x,y), a percentage of an element's height or width (e.g. Center, UpperRight), or an image that should be found inside the element.

Constructors

Location()

Initializes a new instance of the Location class. This is equivalent to using 'Location.Center'.

public Location()

Location(double, double)

Initializes a new instance of the Location class, using a proportional position.

public Location(double xFactor, double yFactor)

Parameters

xFactor double

A value between 0 and 1 representing the horizontal location within an element proportional to its width.

yFactor double

A value between 0 and 1 representing the vertical location within an element proportional to its height.

Location(Bitmap)

Initializes a new instance of the Location class specifying an image to search for.

public Location(Bitmap feature)

Parameters

feature Bitmap

The image that should be found inside the element. The location refers to the center of the image found in the element.

Location(Bitmap, FindOptions)

Initializes a new instance of the Location class specifying an image to search for using the specified options.

public Location(Bitmap feature, Imaging.FindOptions featureOptions)

Parameters

feature Bitmap

The image that should be found inside the element. The location refers to the center of the image found in the element.

featureOptions Imaging.FindOptions

A Imaging.FindOptions instance that defines the options for the search.

Location(Bitmap, Location)

Initializes a new instance of the Location class specifying an image to search for and a relative location inside the found image.

public Location(Bitmap feature, Location locationInFeature)

Parameters

feature Bitmap

The image that should be found inside the element. The location refers to the inner location inside the image found in the element.

locationInFeature Location

Specifies the location inside the image found in the element that this location refers to.

Location(Bitmap, Location, FindOptions)

Initializes a new instance of the Location class using an image to search for and a relative location inside the found image.

public Location(Bitmap feature, Location locationInFeature, Imaging.FindOptions featureOptions)

Parameters

feature Bitmap

The image that should be found inside the element. The location refers to the inner location inside the image found in the element.

locationInFeature Location

Specifies the location inside the image found in the element that this location refers to.

featureOptions Imaging.FindOptions

A Imaging.FindOptions instance that defines the options for the search.

Location(Point)

Initializes a new instance of the Location class, using a pixel value.

public Location(Point fixedLocation)

Parameters

fixedLocation Point

The fixed location, in pixels, relative to the upper left corner of the element.

Location(PointF)

Initializes a new instance of the Location class, using a proportional position.

public Location(PointF proportionalLocation)

Parameters

proportionalLocation PointF

The proportional location. The X value represents the horizontal location within an element proportional to its width, the Y value the vertical location within an element proportional to its height.

Location(int, int)

Initializes a new instance of the Location class, using a pixel value.

public Location(int dx, int dy)

Parameters

dx int

The horizontal distance from the upper left corner of the element in pixels.

dy int

The vertical distance from the upper left corner of the element in pixels.

Properties

Center

Represents the center of an element.

public static Location Center { get; }

Property Value

Location

The center.

CenterLeft

Represents the left center location of an element.

public static Location CenterLeft { get; }

Property Value

Location

The center left.

CenterRight

Represents the center right location of an element.

public static Location CenterRight { get; }

Property Value

Location

The center right.

Feature

Gets or sets an image that should be searched inside an element.

[Browsable(false)]
public Bitmap Feature { get; set; }

Property Value

Bitmap

Remarks

If this property is set (to a value different from null), this location refers to the image found inside an element. That mean, the FixedLocation and ProportionalLocation properties are relative to the location of the image found inside an element.

FeatureOptions

Gets or sets the options for searching the Feature image.

[Browsable(false)]
[TypeConverter(typeof(ExpandableObjectConverter))]
public Imaging.FindOptions FeatureOptions { get; set; }

Property Value

Imaging.FindOptions

Set this property to null to use the Default options.

FixedLocation

Gets the relative pixel location if IsFixed is true. Throws an exception if the location is proportional.

public Point FixedLocation { get; }

Property Value

Point

The fixed location.

Exceptions

InvalidOperationException

If the location is not fixed.

IsFixed

Gets a value indicating whether this instance is fixed, i.e. has a fixed pixel value.

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

Property Value

bool

true if this instance is fixed; otherwise, false.

IsImageBased

Gets a value indicating whether this instance searches for a Feature image inside an element to get a relative offset inside the element.

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

Property Value

bool

IsProportional

Gets a value indicating whether this instance is proportional, i.e. is proportional to the width and height of the element.

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

Property Value

bool

LowerCenter

Represents the lower center location of an element.

public static Location LowerCenter { get; }

Property Value

Location

The lower center.

LowerLeft

Represents the lower left corner of an element.

public static Location LowerLeft { get; }

Property Value

Location

The lower left.

LowerRight

Represents the lower right corner of an element.

public static Location LowerRight { get; }

Property Value

Location

The lower right.

ProportionalLocation

Gets the proportional location if IsFixed is false. Throws an exception if the location is fixed.

public PointF ProportionalLocation { get; }

Property Value

PointF

The proportional location.

Exceptions

InvalidOperationException

If the location is not proportional.

StandardValues

Gets an array of the standard locations.

public static Location[] StandardValues { get; }

Property Value

Location[]

UpperCenter

Represents the upper center location of an element.

public static Location UpperCenter { get; }

Property Value

Location

The upper center.

UpperLeft

Represents the upper left corner of an element.

public static Location UpperLeft { get; }

Property Value

Location

The upper left.

UpperRight

Represents the upper right corner of an element.

public static Location UpperRight { get; }

Property Value

Location

The upper right.

Methods

Clone()

Creates a new instance that is equal to this instance.

public Location Clone()

Returns

Location

A clone of this instance.

Equals(Location)

Indicates whether the current object is equal to another object of the same type.

public virtual bool Equals(Location other)

Parameters

other Location

An object to compare with this object.

Returns

bool

true if the current object is equal to the other parameter; otherwise, false.

Exceptions

NotImplementedException

Equals(object)

Determines whether the specified object is equal to the current Location.

public override bool Equals(object obj)

Parameters

obj object

The object to compare with the current Location.

Returns

bool

true if the specified object is equal to the current Location; otherwise, false.

GetElementLocation(Element, bool)

Gets the coordinates of a given Location corresponding to the specified element.

public Point GetElementLocation(Element element, bool relative)

Parameters

element Element

The element.

relative bool

A value specifying if the returned coordinates are relative to the element location or absolute (=screen) coordinates.

Returns

Point

The coordinates resulting from the location and the specified element.

GetHashCode()

Serves as a hash function for a particular type.

public override int GetHashCode()

Returns

int

A hash code for the current Location.

GetLocationForRect(Rectangle)

Gets the coordinates of a given Location corresponding to the specified rectangle.

public Point GetLocationForRect(Rectangle rect)

Parameters

rect Rectangle

The rectangle.

Returns

Point

The coordinates resulting from the location and the specified rectangle.

Exceptions

NotSupportedException

If the location is image based.

GetScreenLocation(Element)

Gets the screen coordinates of a given Location corresponding to the specified element.

public Point GetScreenLocation(Element element)

Parameters

element Element

The element.

Returns

Point

The screen location resulting from the location and the specified element.

Parse(string)

Creates a new instance of the Location class from its string representation.

public static Location Parse(string locationString)

Parameters

locationString string

The location string. Supports various different formats.

Returns

Location

The new instance.

Examples

Examples for location strings:
'1;2' or '1,2' results in a fixed relative location in pixels.
'0.4;0.6' or '.3,.7' results in a location proportional to the elements size.
Use of the names of location presets (e.g. 'center') is also permitted.

Exceptions

FormatException

If the string representation is not valid.

ToString()

Returns a string that represents the current Location.

public override string ToString()

Returns

string

A string that represents the current object.

Remarks

The string created by this method is always a valid location string.

TryParse(string, out Location)

Tries to creates a new instance of the Location class from its string representation.

public static bool TryParse(string locationString, out Location location)

Parameters

locationString string

The location string. Supports various different formats.

location Location

When this method returns, contains the new Location instance if conversion was successful, otherwise null.

Returns

bool

True if the conversion was successful, otherwise false.

Examples

Examples for location strings:
'1;2' or '1,2' results in a fixed relative location in pixels.
'0.4;0.6' or '.3,.7' results in a location proportional to the elements size.
Use of the names of location presets (e.g. 'center') is also permitted.

Operators

operator ==(Location, Location)

Implements the operator ==.

public static bool operator ==(Location l1, Location l2)

Parameters

l1 Location

The l1.

l2 Location

The l2.

Returns

bool

The result of the operator.

implicit operator Location(Bitmap)

Performs an implicit conversion from Bitmap to Location.

public static implicit operator Location(Bitmap feature)

Parameters

feature Bitmap

A bitmap to search for inside an element.

Returns

Location

A Location instance that refers to the center of the image found in an element.

implicit operator Location(Point)

Performs an implicit conversion from Point to Location.

public static implicit operator Location(Point fixedLocation)

Parameters

fixedLocation Point

The location (with fixed relative position).

Returns

Location

The result of the conversion.

implicit operator Location(PointF)

Performs an implicit conversion from PointF to Location.

public static implicit operator Location(PointF proportionalLocation)

Parameters

proportionalLocation PointF

The location (with a position proportional to an element's size).

Returns

Location

The result of the conversion.

implicit operator Location(string)

Performs an implicit conversion from string to Location.

public static implicit operator Location(string location)

Parameters

location string

The location (as string).

Returns

Location

The result of the conversion.

Exceptions

FormatException

If the string representation is not valid.

operator !=(Location, Location)

Implements the operator !=.

public static bool operator !=(Location l1, Location l2)

Parameters

l1 Location

The first parameter of the comparison.

l2 Location

The second parameter of the comparison.

Returns

bool

The result of the operator.