Skip to main content
Drag gestures let you move elements across the screen, reorder items, or interact with sliders and controls.

Basic Drag

Drag from one point to another:
# Drag from (100, 200) to (300, 400)
phone.drag((100, 200), (300, 400))

# Using Point objects
from tapkit.geometry import Point
start = Point(100, 200)
end = Point(300, 400)
phone.drag(start, end)

Parameters

ParameterTypeDescription
from_pointtuple/PointStarting coordinates
to_pointtuple/PointEnding coordinates

Hold and Drag

For operations that require holding before dragging (like reordering):
# Hold for 500ms, then drag
phone.hold_and_drag(
    from_point=(100, 200),
    to_point=(100, 400),
    hold_duration_ms=500
)

# Longer hold for items that need more time to "pick up"
phone.hold_and_drag(
    from_point=(100, 200),
    to_point=(100, 400),
    hold_duration_ms=1000
)

Parameters

ParameterTypeDefaultDescription
from_pointtuple/PointrequiredStarting coordinates
to_pointtuple/PointrequiredEnding coordinates
hold_duration_msint500Time to hold before dragging

Use Cases

Reorder List Items

# Pick up item at position 1 and move to position 3
item_1_y = 200
item_3_y = 400

phone.hold_and_drag(
    from_point=(phone.width // 2, item_1_y),
    to_point=(phone.width // 2, item_3_y),
    hold_duration_ms=500
)

Adjust a Slider

# Move slider from 25% to 75%
slider_y = 300
start_x = phone.width // 4
end_x = phone.width * 3 // 4

phone.drag((start_x, slider_y), (end_x, slider_y))

Move an App Icon

# Long press and drag to rearrange home screen
phone.hold_and_drag(
    from_point=(100, 200),   # Original position
    to_point=(300, 200),     # New position
    hold_duration_ms=800     # iOS needs longer hold for icons
)

Drag to Delete

# Drag item to trash area
phone.hold_and_drag(
    from_point=(200, 400),
    to_point=(phone.width // 2, phone.height - 100),
    hold_duration_ms=500
)

Pull to Refresh

# Drag down from top to refresh
phone.drag(
    (phone.width // 2, 200),
    (phone.width // 2, 600)
)

Combining with Coordinates

Use with bounding boxes from vision models:
from tapkit.geometry import BBox

# Detected element positions
source_element = BBox(x1=50, y1=200, x2=150, y2=250)
target_area = BBox(x1=50, y1=400, x2=350, y2=450)

# Drag from element center to target center
phone.hold_and_drag(
    from_point=source_element.center,
    to_point=target_area.center,
    hold_duration_ms=500
)

Tips

When reordering items in a list, use hold_and_drag with at least 500ms hold time. This gives the UI time to recognize the drag operation.
Some apps require longer hold times before allowing drag. Start with 500ms and increase if the drag doesn’t work.
When dragging to screen edges, ensure your end coordinates are within bounds using screen.clamp().

Next Steps