autopilot.input.Pointer

class autopilot.input.Pointer(device)

A wrapper class that represents a pointing device which can either be a mouse or a touch, and provides a unified API.

This class is useful if you want to run tests with either a mouse or a touch device, and want to write your tests to use a single API. Create this wrapper by passing it either a mouse or a touch device, like so:

pointer_device = Pointer(Mouse.create())

or, like so:

pointer_device = Pointer(Touch.create())

Warning

Some operations only make sense for certain devices. This class attempts to minimise the differences between the Mouse and Touch APIs, but there are still some operations that will cause exceptions to be raised. These are documented in the specific methods below.

x

Pointer X coordinate.

If the wrapped device is a Touch device, this will return the last known X coordinate, which may not be a sensible value.

y

Pointer Y coordinate.

If the wrapped device is a Touch device, this will return the last known Y coordinate, which may not be a sensible value.

press(button=1)

Press the pointer at it’s current location.

If the wrapped device is a mouse, you may pass a button specification. If it is a touch device, passing anything other than 1 will raise a ValueError exception.

release(button=1)

Releases the pointer at it’s current location.

If the wrapped device is a mouse, you may pass a button specification. If it is a touch device, passing anything other than 1 will raise a ValueError exception.

click(button=1, press_duration=0.1, time_between_events=0.1)

Press and release at the current pointer location.

If the wrapped device is a mouse, the button specification is used. If it is a touch device, passing anything other than 1 will raise a ValueError exception.

Parameters:time_between_events – takes floating point to represent the delay time between subsequent clicks/taps. Default value 0.1 represents tenth of a second.
move(x, y)

Moves the pointer to the specified coordinates.

If the wrapped device is a mouse, the mouse will animate to the specified coordinates. If the wrapped device is a touch device, this method will determine where the next press, release or click will occur.

click_object(object_proxy, button=1, press_duration=0.1, time_between_events=0.1)

Attempts to move the pointer to ‘object_proxy’s centre point. and click a button

It does this by looking for several attributes, in order. The first attribute found will be used. The attributes used are (in order):

  • globalRect (x,y,w,h)
  • center_x, center_y
  • x, y, w, h

    • If the wrapped device is a mouse, the button specification is used. If it is a touch device, passing anything other than 1 will raise a ValueError exception.

    Parameters:time_between_events – takes floating point to represent the delay time between subsequent clicks/taps. Default value 0.1 represents tenth of a second.
    move_to_object(object_proxy)

    Attempts to move the pointer to ‘object_proxy’s centre point.

    It does this by looking for several attributes, in order. The first attribute found will be used. The attributes used are (in order):

  • globalRect (x,y,w,h)
  • center_x, center_y
  • x, y, w, h
    • Raises:ValueError if none of these attributes are found, or if an attribute is of an incorrect type.
    position()

    Returns the current position of the pointer.

    Returns:(x,y) tuple
    drag(x1, y1, x2, y2, rate=10, time_between_events=0.01)

    Perform a press, move and release.

    This is to keep a common API between Mouse and Finger as long as possible.

    The pointer will be dragged from the starting point to the ending point with multiple moves. The number of moves, and thus the time that it will take to complete the drag can be altered with the rate parameter.

    Parameters:
    • x1 – The point on the x axis where the drag will start from.
    • y1 – The point on the y axis where the drag will starts from.
    • x2 – The point on the x axis where the drag will end at.
    • y2 – The point on the y axis where the drag will end at.
    • rate – The number of pixels the mouse will be moved per iteration. Default is 10 pixels. A higher rate will make the drag faster, and lower rate will make it slower.
    • time_between_events – The number of seconds that the drag will wait between iterations.