Selection of Drag and Drop Methods

CukeTest provides several ways to perform drag and drop operations, each suitable for different occasions. So which method should you choose? This document describes the criteria for choosing between these two types of drag and drop methods, as well as the specific calling methods for each API.

Different ways to implement drag and drop

CukeTest provides several different drag and drop methods, which can be divided into: Object-oriented approach and Screen-oriented approach.

• Object-oriented approach: Drags a control, acting as a method of the test object; coordinates are usually relative to the top-left corner of the control.
• Screen-oriented approach: Completes a drag operation requiring only the screen coordinates of the start and end points (with the top-left corner of the screen as the origin), without concerning the target being manipulated.

Specific similarities and differences can be referenced in the following table:

Composition of drag and drop actions

The entire process of a drag and drop action can be broken down as follows:

1. Move to start position
2. Press left mouse button (hold)
3. Move to end position
4. Release left mouse button

Implementation of Drag and Drop Controls

The most common situation is dragging a control to a specific location. In this case, the object operation APIs provided by every control——drag and drop methods——are undoubtedly the best way to implement it.

drag(x, y, mouseKey)

This method marks the start of the drag operation, simulating pressing and holding the left mouse button at the target position.

Parameters

• x: (Optional) number. The horizontal pixel offset of the drag start point relative to the control's top-left corner. When x and y are both 0 or omitted, it defaults to clicking the control center.
• y: (Optional) number. The vertical pixel offset of the drag start point relative to the control's top-left corner.
• mouseKey: (Optional) number. The mouse button used during dragging. 1 for left button, 2 for right button. Default is left button (1).

Returns

• Asynchronous method that returns no value.

drop(x, y, options)

The ending step of the drag operation, simulating moving the mouse to the specified position and releasing it.

Parameters

• x: (Optional) number. The horizontal pixel offset of the release position relative to the control's top-left corner. When x and y are both 0 or omitted, it defaults to clicking the control center.
• y: (Optional) number. The vertical pixel offset of the release position relative to the control's top-left corner.
• options: (Optional) object. Configuration object to customize drag behavior. Supported options include:
  • duration: number. The duration of mouse movement to the target position, in seconds. Default is 1 (1 second).
  • mouseKeys: number. The mouse button used in the drag operation. 1 for left button, 2 for right button. Default is left button (1).

Returns

• Asynchronous method that returns no value.

Example: Drag and drop desktop icons

Suppose we want to drag the "Recycle Bin" icon on the desktop horizontally to the right by 400 pixels. After adding the control in the Model Manager, use the following script to complete the drag and drop:

const { WinAuto } = require('leanpro.win');
const model = WinAuto.loadModel(__dirname + "\\model1.tmodel");

(async function () {
    let item = model.getListItem("Recycle Bin");
    await item.drag();
    await item.drop(400, 0);
})();

import os
from leanproAuto import WinAuto

modelWin = WinAuto.loadModel(os.path.dirname(__file__) + "/model1.tmodel")

if __name__ == "__main__":
    item = modelWin.getListItem("Recycle Bin")
    item.drag()
    item.drop(400, 0)

If you want to use right-click drag, you can change the last two lines to:

await item.drag(0, 0, 2);
await item.drop(400, 0, { mouseKey: 2 });

item.drag(0, 0, 2)
item.drop(400, 0, {"mouseKey": 2})

The above script can move the "Recycle Bin" icon on the desktop horizontally to the right by 400 pixels.

Implementation of Mouse Dragging

In addition to control dragging, CukeTest also provides a way to simulate user mouse operations for dragging, completed by the Mouse module in leanpro.common. This method operates directly on screen coordinates and does not depend on specific controls.

Method Description

• Mouse.move(x, y): Move mouse to screen coordinates (x, y).
• Mouse.keyDown(key): Press mouse button.
• Mouse.keyUp(key): Release mouse button.
• Mouse.drag(x, y, mouseKey): While mouse button is pressed, drag (move) to new screen coordinates (x, y).
• Mouse.drop(x, y, {duration, mouseKey}): Release the drag operation at the specified location.

Example

Suppose we use the simulated operation method to complete the operation on the "Recycle Bin" icon from the previous section. It should be written as follows:

const { Mouse } = require('leanpro.common');
const { WinAuto } = require('leanpro.win');
const model = WinAuto.loadModel(__dirname + "\\model1.tmodel");

(async function () {
    let item = model.getListItem("Recycle Bin");
    // Get screen coordinates of the control center
    let x = await item.x();
    let y = await item.y();

    await Mouse.move(x, y);
    await Mouse.keyDown(1);
    await Mouse.move(x + 400, y); // Drag 400 pixels horizontally to the right
    await Mouse.keyUp(1);
})();

import os
from leanproAuto import WinAuto, Mouse

modelWin = WinAuto.loadModel(os.path.dirname(__file__) + "/model1.tmodel")

if __name__ == "__main__":
    item = modelWin.getListItem("Recycle Bin")
    # Get screen coordinates of the control center
    x = item.x()
    y = item.y()

    Mouse.move(x, y)
    Mouse.keyDown(1)
    Mouse.move(x + 400, y) # Drag 400 pixels horizontally to the right
    Mouse.keyUp(1)

Note: In this method, x and y parameters represent absolute positions in the Screen Coordinate System. You need to pass in specific coordinate values to achieve more flexible dragging operations.

By comparing the characteristics and applicable scenarios of different methods, you can more effectively choose the appropriate drag and drop method to meet your testing needs.