0
# Touch Simulation
1

2
Touch event simulation system for iOS devices, providing hardware-level touch event generation, drag gesture support, and precise touch interaction capabilities.
3

4
## Capabilities
5

6
### Basic Touch Events
7

8
Core touch event functions for simulating finger interactions on iOS devices.
9

10
```kotlin { .api }
11
/**
12
 * Simulates a touch-down event at the specified position
13
 * @param position - Location to touch in density-independent pixels
14
 * @return UITouch instance for further gesture operations
15
 */
16
fun UIKitInstrumentedTest.touchDown(position: DpOffset): UITouch
17

18
/**
19
 * Simulates a complete tap gesture (touch down + touch up) at specified position
20
 * @param position - Location to tap in density-independent pixels
21
 * @return UITouch instance after completing the tap
22
 */
23
fun UIKitInstrumentedTest.tap(position: DpOffset): UITouch
24
```
25

26
**Usage Examples:**
27

28
```kotlin
29
runUIKitInstrumentedTest {
30
    setContent {
31
        Button(onClick = { /* action */ }) {
32
            Text("Tap me!")
33
        }
34
    }
35
    
36
    // Simple tap
37
    tap(DpOffset(100.dp, 200.dp))
38
    
39
    // Touch down for complex gestures
40
    val touch = touchDown(DpOffset(50.dp, 50.dp))
41
    // ... perform drag operations with touch
42
    touch.up()
43
}
44
```
45

46
### Drag Gestures
47

48
Advanced drag gesture simulation with duration control and precise positioning.
49

50
```kotlin { .api }
51
/**
52
 * Drags touch to target location over specified duration
53
 * @param location - Target location in density-independent pixels
54
 * @param duration - Duration of drag operation (default: 0.5.seconds)
55
 * @return UITouch instance after completing the drag
56
 */
57
fun UITouch.dragTo(location: DpOffset, duration: Duration = 0.5.seconds): UITouch
58

59
/**
60
 * Drags touch by specified offset from current position over specified duration
61
 * @param offset - Offset to drag by in density-independent pixels
62
 * @param duration - Duration of drag operation (default: 0.5.seconds)
63
 * @return UITouch instance after completing the drag
64
 */
65
fun UITouch.dragBy(offset: DpOffset, duration: Duration = 0.5.seconds): UITouch
66

67
/**
68
 * Drags touch by specified x and y components over specified duration
69
 * @param dx - Horizontal offset in density-independent pixels (default: 0.dp)
70
 * @param dy - Vertical offset in density-independent pixels (default: 0.dp)
71
 * @param duration - Duration of drag operation (default: 0.5.seconds)
72
 * @return UITouch instance after completing the drag
73
 */
74
fun UITouch.dragBy(dx: Dp = 0.dp, dy: Dp = 0.dp, duration: Duration = 0.5.seconds): UITouch
75
```
76

77
**Usage Examples:**
78

79
```kotlin
80
runUIKitInstrumentedTest {
81
    setContent {
82
        LazyColumn {
83
            items(100) { index ->
84
                Text("Item $index")
85
            }
86
        }
87
    }
88
    
89
    // Drag to scroll list
90
    val touch = touchDown(DpOffset(200.dp, 400.dp))
91
    touch.dragTo(DpOffset(200.dp, 100.dp), durationMillis = 500)
92
    touch.up()
93
    
94
    // Drag by offset for precise movements
95
    val touch2 = touchDown(DpOffset(100.dp, 100.dp))
96
    touch2.dragBy(DpOffset(50.dp, 100.dp))
97
    touch2.up()
98
}
99
```
100

101
### Touch State Management
102

103
Low-level touch state management functions for complex gesture sequences.
104

105
```kotlin { .api }
106
/**
107
 * Moves touch to new location in window coordinates
108
 * @param location - New location in density-independent pixels
109
 */
110
fun UITouch.moveToLocationOnWindow(location: DpOffset)
111

112
/**
113
 * Holds touch in stationary phase
114
 * @return UITouch instance after holding
115
 */
116
fun UITouch.hold(): UITouch
117

118
/**
119
 * Lifts touch, ending the touch interaction
120
 * @return UITouch instance after lifting
121
 */
122
fun UITouch.up(): UITouch
123
```
124

125
### Window-Level Touch Operations
126

127
Window-level touch operations for precise control over touch event generation.
128

129
```kotlin { .api }
130
/**
131
 * Creates a touch event at specified point in window
132
 * @param location - Location in window coordinates as DpOffset
133
 * @return UITouch instance for gesture operations
134
 */
135
internal fun UIWindow.touchDown(location: DpOffset): UITouch
136
```
137

138
### Touch Properties
139

140
Properties for accessing touch state and location information.
141

142
```kotlin { .api }
143
/**
144
 * Current touch location in hosting view coordinates
145
 */
146
val UITouch.location: DpOffset
147
```
148

149
**Usage Example:**
150

151
```kotlin
152
runUIKitInstrumentedTest {
153
    val touch = touchDown(DpOffset(100.dp, 100.dp))
154
    
155
    println("Touch started at: ${touch.location}")
156
    
157
    touch.moveToLocationOnWindow(DpOffset(200.dp, 200.dp))
158
    println("Touch moved to: ${touch.location}")
159
    
160
    touch.hold(500) // Hold for half a second
161
    touch.up()
162
}
163
```
164

165
## Advanced Gesture Patterns
166

167
### Multi-Touch Gestures
168

169
```kotlin
170
// Simulate pinch gesture
171
val touch1 = touchDown(DpOffset(100.dp, 100.dp))
172
val touch2 = touchDown(DpOffset(200.dp, 200.dp))
173

174
// Move touches apart (zoom out)
175
touch1.dragTo(DpOffset(50.dp, 50.dp))
176
touch2.dragTo(DpOffset(250.dp, 250.dp))
177

178
touch1.up()
179
touch2.up()
180
```
181

182
### Complex Scroll Gestures
183

184
```kotlin
185
// Simulate fling scroll
186
val touch = touchDown(DpOffset(200.dp, 400.dp))
187
touch.dragTo(DpOffset(200.dp, 100.dp), durationMillis = 100) // Fast drag
188
touch.up()
189
```
190

191
### Long Press Gestures
192

193
```kotlin
194
// Simulate long press
195
val touch = touchDown(DpOffset(150.dp, 150.dp))
196
touch.hold(1000) // Hold for 1 second
197
touch.up()
198
```
199

200
## Platform Integration
201

202
- **UIKit Touch System**: Direct integration with iOS UIKit touch event handling
203
- **Hardware Simulation**: Accurately simulates hardware-level touch events
204
- **Coordinate Systems**: Seamless conversion between Compose and UIKit coordinate systems
205
- **Event Timing**: Precise timing control for realistic gesture simulation
206
- **Multi-Touch Support**: Full support for multi-finger gestures and complex interactions