0
# Mouse Control
1

2
Complete mouse automation functionality including clicking, movement, dragging, and scrolling operations with smooth animations and configurable timing. All mouse functions support coordinate specification, duration control, and easing functions for natural movement.
3

4
## Capabilities
5

6
### Basic Clicking
7

8
Perform mouse clicks at specified coordinates with configurable button, click count, and timing options.
9

10
```python { .api }
11
def click(x=None, y=None, clicks=1, interval=0.0, button='left', duration=0.0, tween=linear, logScreenshot=None, _pause=True):
12
    """
13
    Perform mouse click at specified coordinates.
14
    
15
    Parameters:
16
    - x, y (int): Screen coordinates. If None, uses current mouse position
17
    - clicks (int): Number of clicks to perform (default: 1)
18
    - interval (float): Seconds between clicks for multiple clicks (default: 0.0)
19
    - button (str): Mouse button - 'left', 'right', 'middle', 'primary', 'secondary' (default: 'left')
20
    - duration (float): Time to move to position in seconds (default: 0.0)
21
    - tween (function): Easing function for movement animation (default: linear)
22
    - logScreenshot (bool): Log screenshot for debugging (default: None)
23
    - _pause (bool): Apply global PAUSE after operation (default: True)
24
    
25
    Returns:
26
    None
27
    """
28

29
def leftClick(x=None, y=None, interval=0.0, duration=0.0, tween=linear, logScreenshot=None, _pause=True):
30
    """Left mouse button click. Equivalent to click() with button='left'."""
31

32
def rightClick(x=None, y=None, interval=0.0, duration=0.0, tween=linear, logScreenshot=None, _pause=True):
33
    """Right mouse button click. Equivalent to click() with button='right'."""
34

35
def middleClick(x=None, y=None, interval=0.0, duration=0.0, tween=linear, logScreenshot=None, _pause=True):
36
    """Middle mouse button click. Equivalent to click() with button='middle'."""
37
```
38

39
### Multi-Click Operations
40

41
Perform double-clicks and triple-clicks with customizable timing and button selection.
42

43
```python { .api }
44
def doubleClick(x=None, y=None, interval=0.0, button='left', duration=0.0, tween=linear, logScreenshot=None, _pause=True):
45
    """
46
    Perform double-click at specified coordinates.
47
    
48
    Parameters:
49
    - x, y (int): Screen coordinates. If None, uses current mouse position
50
    - interval (float): Seconds between the two clicks (default: 0.0)
51
    - button (str): Mouse button to use (default: 'left')
52
    - duration (float): Time to move to position in seconds (default: 0.0)
53
    - tween (function): Easing function for movement animation (default: linear)
54
    - logScreenshot (bool): Log screenshot for debugging (default: None)
55
    - _pause (bool): Apply global PAUSE after operation (default: True)
56
    
57
    Returns:
58
    None
59
    """
60

61
def tripleClick(x=None, y=None, interval=0.0, button='left', duration=0.0, tween=linear, logScreenshot=None, _pause=True):
62
    """
63
    Perform triple-click at specified coordinates.
64
    
65
    Parameters:
66
    - x, y (int): Screen coordinates. If None, uses current mouse position
67
    - interval (float): Seconds between clicks (default: 0.0)
68
    - button (str): Mouse button to use (default: 'left')
69
    - duration (float): Time to move to position in seconds (default: 0.0)
70
    - tween (function): Easing function for movement animation (default: linear)
71
    - logScreenshot (bool): Log screenshot for debugging (default: None)
72
    - _pause (bool): Apply global PAUSE after operation (default: True)
73
    
74
    Returns:
75
    None
76
    """
77
```
78

79
### Mouse Button State Control
80

81
Control mouse button press and release states independently for complex interactions.
82

83
```python { .api }
84
def mouseDown(x=None, y=None, button='left', duration=0.0, tween=linear, logScreenshot=None, _pause=True):
85
    """
86
    Press mouse button down (without releasing).
87
    
88
    Parameters:
89
    - x, y (int): Screen coordinates. If None, uses current mouse position
90
    - button (str): Mouse button to press - 'left', 'right', 'middle', 'primary', 'secondary' (default: 'left')
91
    - duration (float): Time to move to position in seconds (default: 0.0)
92
    - tween (function): Easing function for movement animation (default: linear)
93
    - logScreenshot (bool): Log screenshot for debugging (default: None)
94
    - _pause (bool): Apply global PAUSE after operation (default: True)
95
    
96
    Returns:
97
    None
98
    """
99

100
def mouseUp(x=None, y=None, button='left', duration=0.0, tween=linear, logScreenshot=None, _pause=True):
101
    """
102
    Release mouse button (without pressing).
103
    
104
    Parameters:
105
    - x, y (int): Screen coordinates. If None, uses current mouse position
106
    - button (str): Mouse button to release - 'left', 'right', 'middle', 'primary', 'secondary' (default: 'left')
107
    - duration (float): Time to move to position in seconds (default: 0.0)
108
    - tween (function): Easing function for movement animation (default: linear)
109
    - logScreenshot (bool): Log screenshot for debugging (default: None)
110
    - _pause (bool): Apply global PAUSE after operation (default: True)
111
    
112
    Returns:
113
    None
114
    """
115
```
116

117
### Mouse Movement
118

119
Move mouse cursor to absolute or relative positions with smooth animation support.
120

121
```python { .api }
122
def moveTo(x, y, duration=0.0, tween=linear, logScreenshot=False, _pause=True):
123
    """
124
    Move mouse to absolute screen coordinates.
125
    
126
    Parameters:
127
    - x, y (int): Target screen coordinates
128
    - duration (float): Time to complete movement in seconds (default: 0.0 for instant)
129
    - tween (function): Easing function for smooth animation (default: linear)
130
    - logScreenshot (bool): Log screenshot for debugging (default: False)
131
    - _pause (bool): Apply global PAUSE after operation (default: True)
132
    
133
    Returns:
134
    None
135
    """
136

137
def moveRel(xOffset, yOffset, duration=0.0, tween=linear, logScreenshot=False, _pause=True):
138
    """
139
    Move mouse relative to current position.
140
    
141
    Parameters:
142
    - xOffset, yOffset (int): Relative movement distances in pixels
143
    - duration (float): Time to complete movement in seconds (default: 0.0)
144
    - tween (function): Easing function for smooth animation (default: linear)
145
    - logScreenshot (bool): Log screenshot for debugging (default: False)
146
    - _pause (bool): Apply global PAUSE after operation (default: True)
147
    
148
    Returns:
149
    None
150
    """
151

152
def move(xOffset, yOffset, duration=0.0, tween=linear, logScreenshot=False, _pause=True):
153
    """Alias for moveRel() - move mouse relative to current position."""
154
```
155

156
### Mouse Dragging
157

158
Drag operations that combine mouse button press, movement, and release for drag-and-drop functionality.
159

160
```python { .api }
161
def dragTo(x, y, duration=0.0, tween=linear, button='left', logScreenshot=None, _pause=True, mouseDownUp=True):
162
    """
163
    Drag from current position to absolute coordinates.
164
    
165
    Parameters:
166
    - x, y (int): Target screen coordinates
167
    - duration (float): Time to complete drag in seconds (default: 0.0)
168
    - tween (function): Easing function for smooth movement (default: linear)
169
    - button (str): Mouse button to use for dragging (default: 'left')
170
    - logScreenshot (bool): Log screenshot for debugging (default: None)
171
    - _pause (bool): Apply global PAUSE after operation (default: True)
172
    - mouseDownUp (bool): Whether to press/release button automatically (default: True)
173
    
174
    Returns:
175
    None
176
    """
177

178
def dragRel(xOffset, yOffset, duration=0.0, tween=linear, button='left', logScreenshot=None, _pause=True, mouseDownUp=True):
179
    """
180
    Drag relative to current position.
181
    
182
    Parameters:
183
    - xOffset, yOffset (int): Relative drag distances in pixels
184
    - duration (float): Time to complete drag in seconds (default: 0.0)
185
    - tween (function): Easing function for smooth movement (default: linear)
186
    - button (str): Mouse button to use for dragging (default: 'left')
187
    - logScreenshot (bool): Log screenshot for debugging (default: None)
188
    - _pause (bool): Apply global PAUSE after operation (default: True)
189
    - mouseDownUp (bool): Whether to press/release button automatically (default: True)
190
    
191
    Returns:
192
    None
193
    """
194

195
def drag(xOffset, yOffset, duration=0.0, tween=linear, button='left', logScreenshot=None, _pause=True, mouseDownUp=True):
196
    """Alias for dragRel() - drag relative to current position."""
197
```
198

199
### Mouse Scrolling
200

201
Scroll mouse wheel vertically and horizontally (platform-dependent).
202

203
```python { .api }
204
def scroll(clicks, x=None, y=None, logScreenshot=None, _pause=True):
205
    """
206
    Scroll mouse wheel at specified position.
207
    
208
    Parameters:
209
    - clicks (int): Number of scroll clicks. Positive for up/right, negative for down/left
210
    - x, y (int): Screen coordinates to center scroll. If None, uses current position
211
    - logScreenshot (bool): Log screenshot for debugging (default: None)
212
    - _pause (bool): Apply global PAUSE after operation (default: True)
213
    
214
    Returns:
215
    None
216
    
217
    Note: Direction depends on platform. On Windows/Mac this is vertical.
218
    On Linux, use vscroll() or hscroll() for explicit direction control.
219
    """
220

221
def vscroll(clicks, x=None, y=None, logScreenshot=None, _pause=True):
222
    """
223
    Vertical scroll (Linux only).
224
    
225
    Parameters:
226
    - clicks (int): Number of scroll clicks. Positive for up, negative for down
227
    - x, y (int): Screen coordinates to center scroll. If None, uses current position
228
    - logScreenshot (bool): Log screenshot for debugging (default: None)
229
    - _pause (bool): Apply global PAUSE after operation (default: True)
230
    
231
    Returns:
232
    None
233
    """
234

235
def hscroll(clicks, x=None, y=None, logScreenshot=None, _pause=True):
236
    """
237
    Horizontal scroll (Linux only).
238
    
239
    Parameters:
240
    - clicks (int): Number of scroll clicks. Positive for right, negative for left
241
    - x, y (int): Screen coordinates to center scroll. If None, uses current position
242
    - logScreenshot (bool): Log screenshot for debugging (default: None)
243
    - _pause (bool): Apply global PAUSE after operation (default: True)
244
    
245
    Returns:
246
    None
247
    """
248
```
249

250
## Usage Examples
251

252
```python
253
import pyautogui
254

255
# Basic clicking
256
pyautogui.click(100, 200)  # Click at coordinates
257
pyautogui.rightClick()     # Right-click at current position
258
pyautogui.doubleClick(150, 300, interval=0.1)  # Double-click with timing
259

260
# Smooth movement with animation
261
pyautogui.moveTo(500, 500, duration=2.0, tween=pyautogui.easeInOutQuad)
262

263
# Dragging operations
264
pyautogui.dragTo(400, 300, duration=1.0)  # Drag to absolute position
265
pyautogui.dragRel(100, 0, duration=0.5)   # Drag 100 pixels right
266

267
# Scrolling
268
pyautogui.scroll(3)        # Scroll up 3 clicks
269
pyautogui.scroll(-2, 300, 400)  # Scroll down 2 clicks at position
270

271
# Complex mouse operations
272
pyautogui.mouseDown(button='left')  # Press and hold
273
pyautogui.moveTo(200, 200, duration=1.0)  # Move while holding
274
pyautogui.mouseUp()        # Release button
275
```
276

277
## Mouse Button Constants
278

279
```python { .api }
280
LEFT: str = 'left'
281
RIGHT: str = 'right'
282
MIDDLE: str = 'middle'
283
PRIMARY: str = 'primary'    # Usually left button
284
SECONDARY: str = 'secondary'  # Usually right button
285
```