Absolute and Relative Coordinates

Absolute coordinates are also known as Desktop Coordinates.

In CukeTest's desktop automation, there are two types of coordinate systems: Absolute Coordinates and Relative Coordinates.

  • Absolute Coordinates: A coordinate system with the origin at the top-left corner of the primary monitor. These are typically used for mouse operations in the Mouse library and for the Bounding Rectangle attribute in some object models.
  • Relative Coordinates: A coordinate system with the origin at the top-left corner of a specific control. All control operations, except for those in the Mouse library, use relative coordinates.

For automation, coordinates are generally measured using the following principles:

  • The basic unit of measurement is actual pixels, so values depend on resolution but are not affected by system scaling (DPI settings).
  • The horizontal x coordinate increases from left to right.
  • The vertical y coordinate increases from top to bottom.
  • The origin (0,0) depends on the coordinate type. For absolute coordinates, it is the top-left corner of the main screen. For relative coordinates, it is the top-left corner of the current control (or sometimes the parent control).

The Rect Object

To describe the position and size of a control, we use the Rect object, which consists of the top-left coordinates, width, and height.

  • x: number type. The horizontal pixel position (relative coordinate).
  • y: number type. The vertical pixel position (relative coordinate).
  • width: number type. The horizontal width in pixels.
  • height: number type. The vertical height in pixels.

Note: In the Windows API, there is another structure for coordinates called the RECT structure (windef.h). It also uses four values, but instead of width and height, it uses the coordinates of the bottom-right corner (left, top, right, bottom). CukeTest uses the x, y, width, height format.

Absolute Coordinates

In the automation operations provided by CukeTest, absolute coordinates are used only in a few specific cases related to screen dimensions:

  • Mouse Simulation API: Moves the mouse to a target position on the screen. Since the target is a single point (size is not relevant for movement), only x and y coordinates are used.
  • Screen Operation API: Used for capturing screenshots or getting pixel colors from the screen.
  • rect() method of controls: The rect() method returns the actual coordinates of the control on the desktop (as a Rect object), so these are absolute coordinates.
  • Pattern Object: Used to match and operate on regions of the screen that match a target image.
  • boundingRectangle in Cached Attributes: When a control is inspected, some properties are immediately fetched and cached. The boundingRectangle property represents the control's position on the desktop at that moment. Note that this property should generally not be used in automation scripts because it reflects the state at capture time and does not update if the control moves.

Relative Coordinates

Apart from the cases mentioned above, coordinates in CukeTest generally refer to relative coordinates. This includes, but is not limited to:

  • Coordinate parameters (x and y) in control operations:
    • click(x, y, mouseKey): Click on a specific point within the control.
    • dblClick(x, y, mouseKey): Double-click on a specific point within the control.
    • moveMouse(x, y, seconds): Move the mouse to a specific point within the control.
    • drag(x, y): Move the mouse to a relative position within the control and press down. Used with drop().
    • drop(x, y): Move the mouse to a relative position within the control and release. Used after drag().
  • Relative position of Virtual Controls: A virtual control designates a specific area within a target control as a separate actionable element. When defining this area, you can specify the origin for its relative coordinates (Top-Left (default), Top-Right, Bottom-Left, or Bottom-Right).