0
# Input Handling
1

2
Mouse and keyboard input handling, item state queries, and focus management. Provides detailed information about user interactions with widgets and windows, enabling responsive and interactive user interfaces.
3

4
## Capabilities
5

6
### Item State Queries
7

8
Functions to check the state of the last widget that was drawn.
9

10
```python { .api }
11
def is_item_hovered(flags: int = 0) -> bool:
12
    """Check if last item is hovered by mouse."""
13

14
def is_item_focused() -> bool:
15
    """Check if last item is focused (for keyboard input)."""
16

17
def is_item_active() -> bool:
18
    """Check if last item is active (being clicked or edited)."""
19

20
def is_item_clicked(mouse_button: int = 0) -> bool:
21
    """Check if last item was clicked this frame."""
22

23
def is_item_visible() -> bool:
24
    """Check if last item is visible (not clipped)."""
25

26
def is_item_edited() -> bool:
27
    """Check if last item value was modified this frame."""
28

29
def is_item_activated() -> bool:
30
    """Check if last item was activated this frame (started being active)."""
31

32
def is_item_deactivated() -> bool:
33
    """Check if last item was deactivated this frame (stopped being active)."""
34

35
def is_item_deactivated_after_edit() -> bool:
36
    """Check if last item was deactivated after being edited."""
37

38
def is_item_toggled_open() -> bool:
39
    """Check if last tree item open state was toggled."""
40

41
def is_any_item_hovered() -> bool:
42
    """Check if any item is hovered."""
43

44
def is_any_item_active() -> bool:
45
    """Check if any item is active."""
46

47
def is_any_item_focused() -> bool:
48
    """Check if any item is focused."""
49
```
50

51
### Focus Management
52

53
Functions to control keyboard focus and set default focus targets.
54

55
```python { .api }
56
def set_item_default_focus() -> None:
57
    """Set last item as default focus when window opens."""
58

59
def set_keyboard_focus_here(offset: int = 0) -> None:
60
    """Set keyboard focus to next widget or offset widgets ahead."""
61
```
62

63
### Keyboard Input
64

65
Functions for detecting keyboard input and key states.
66

67
```python { .api }
68
def get_key_index(key: int) -> int:
69
    """Map ImGuiKey to user key index."""
70

71
def is_key_pressed(key_index: int, repeat: bool = False) -> bool:
72
    """Check if key was pressed this frame."""
73

74
def is_key_down(key_index: int) -> bool:
75
    """Check if key is currently being held down."""
76
```
77

78
### Mouse Input
79

80
Functions for detecting mouse input, position, and interaction states.
81

82
```python { .api }
83
def is_mouse_clicked(button: int = 0, repeat: bool = False) -> bool:
84
    """Check if mouse button was clicked this frame."""
85

86
def is_mouse_double_clicked(button: int = 0) -> bool:
87
    """Check if mouse button was double-clicked this frame."""
88

89
def is_mouse_released(button: int = 0) -> bool:
90
    """Check if mouse button was released this frame."""
91

92
def is_mouse_down(button: int = 0) -> bool:
93
    """Check if mouse button is currently pressed."""
94

95
def is_mouse_dragging(button: int = 0, lock_threshold: float = -1.0) -> bool:
96
    """Check if mouse is dragging with specified button."""
97

98
def is_mouse_hovering_rect(r_min_x: float, r_min_y: float, r_max_x: float, r_max_y: float, clip: bool = True) -> bool:
99
    """Check if mouse is hovering over specified rectangle."""
100

101
def get_mouse_pos() -> tuple[float, float]:
102
    """Get current mouse position as (x, y)."""
103

104
def get_mouse_drag_delta(button: int = 0, lock_threshold: float = -1.0) -> tuple[float, float]:
105
    """Get mouse drag delta as (dx, dy)."""
106

107
def reset_mouse_drag_delta(button: int = 0) -> None:
108
    """Reset mouse drag delta for specified button."""
109

110
def get_mouse_cursor() -> int:
111
    """Get current mouse cursor type."""
112

113
def set_mouse_cursor(cursor_type: int) -> None:
114
    """Set mouse cursor type."""
115

116
def capture_mouse_from_app(want_capture_mouse_value: bool = True) -> None:
117
    """Set mouse capture flag."""
118
```
119

120
### Key and Mouse Constants
121

122
Constants for keyboard keys and mouse buttons.
123

124
```python { .api }
125
# Key constants
126
KEY_TAB: int
127
KEY_LEFT_ARROW: int
128
KEY_RIGHT_ARROW: int
129
KEY_UP_ARROW: int
130
KEY_DOWN_ARROW: int
131
KEY_PAGE_UP: int
132
KEY_PAGE_DOWN: int
133
KEY_HOME: int
134
KEY_END: int
135
KEY_INSERT: int
136
KEY_DELETE: int
137
KEY_BACKSPACE: int
138
KEY_SPACE: int
139
KEY_ENTER: int
140
KEY_ESCAPE: int
141
KEY_PAD_ENTER: int
142
KEY_A: int  # For Ctrl+A (select all)
143
KEY_C: int  # For Ctrl+C (copy)
144
KEY_V: int  # For Ctrl+V (paste)
145
KEY_X: int  # For Ctrl+X (cut)
146
KEY_Y: int  # For Ctrl+Y (redo)
147
KEY_Z: int  # For Ctrl+Z (undo)
148

149
# Key modifier constants
150
KEY_MOD_NONE: int
151
KEY_MOD_CTRL: int
152
KEY_MOD_SHIFT: int
153
KEY_MOD_ALT: int
154
KEY_MOD_SUPER: int
155

156
# Mouse button constants
157
MOUSE_BUTTON_LEFT: int
158
MOUSE_BUTTON_RIGHT: int
159
MOUSE_BUTTON_MIDDLE: int
160

161
# Mouse cursor constants
162
MOUSE_CURSOR_NONE: int
163
MOUSE_CURSOR_ARROW: int
164
MOUSE_CURSOR_TEXT_INPUT: int
165
MOUSE_CURSOR_RESIZE_ALL: int
166
MOUSE_CURSOR_RESIZE_NS: int
167
MOUSE_CURSOR_RESIZE_EW: int
168
MOUSE_CURSOR_RESIZE_NESW: int
169
MOUSE_CURSOR_RESIZE_NWSE: int
170
MOUSE_CURSOR_HAND: int
171
MOUSE_CURSOR_NOT_ALLOWED: int
172
```
173

174
### Hover and Focus Flags
175

176
Constants for controlling hover and focus detection behavior.
177

178
```python { .api }
179
# Hover flags
180
HOVERED_NONE: int
181
HOVERED_CHILD_WINDOWS: int
182
HOVERED_ROOT_WINDOW: int
183
HOVERED_ANY_WINDOW: int
184
HOVERED_ALLOW_WHEN_BLOCKED_BY_POPUP: int
185
HOVERED_ALLOW_WHEN_BLOCKED_BY_ACTIVE_ITEM: int
186
HOVERED_ALLOW_WHEN_OVERLAPPED: int
187
HOVERED_ALLOW_WHEN_DISABLED: int
188
HOVERED_RECT_ONLY: int
189
HOVERED_ROOT_AND_CHILD_WINDOWS: int
190

191
# Focus flags
192
FOCUS_NONE: int
193
FOCUS_CHILD_WINDOWS: int
194
FOCUS_ROOT_WINDOW: int
195
FOCUS_ANY_WINDOW: int
196
FOCUS_ROOT_AND_CHILD_WINDOWS: int
197
```
198

199
## Usage Examples
200

201
### Item State Detection
202

203
```python
204
import imgui
205

206
# Check button interaction
207
if imgui.button("My Button"):
208
    print("Button was clicked!")
209

210
# Additional state queries for the button
211
if imgui.is_item_hovered():
212
    print("Button is hovered")
213
    imgui.set_tooltip("This is a tooltip!")
214

215
if imgui.is_item_active():
216
    print("Button is being pressed")
217
```
218

219
### Input Field Handling
220

221
```python
222
text_value = ""
223
changed, text_value = imgui.input_text("Input", text_value, 256)
224

225
if changed:
226
    print(f"Text changed to: {text_value}")
227

228
if imgui.is_item_focused():
229
    print("Input field is focused")
230

231
if imgui.is_item_edited():
232
    print("Input field was edited this frame")
233
```
234

235
### Mouse Interaction
236

237
```python
238
# Custom mouse handling
239
mouse_pos = imgui.get_mouse_pos()
240
imgui.text(f"Mouse position: {mouse_pos[0]:.1f}, {mouse_pos[1]:.1f}")
241

242
if imgui.is_mouse_clicked(imgui.MOUSE_BUTTON_LEFT):
243
    print("Left mouse button clicked!")
244

245
if imgui.is_mouse_dragging(imgui.MOUSE_BUTTON_LEFT):
246
    drag_delta = imgui.get_mouse_drag_delta(imgui.MOUSE_BUTTON_LEFT)
247
    imgui.text(f"Dragging: {drag_delta[0]:.1f}, {drag_delta[1]:.1f}")
248
```
249

250
### Keyboard Input
251

252
```python
253
# Check for specific key presses
254
if imgui.is_key_pressed(imgui.KEY_SPACE):
255
    print("Space key was pressed!")
256

257
if imgui.is_key_down(imgui.KEY_CTRL) and imgui.is_key_pressed(imgui.KEY_S):
258
    print("Ctrl+S was pressed!")
259

260
# Set focus programmatically
261
if imgui.button("Focus Next"):
262
    imgui.set_keyboard_focus_here(1)  # Focus next widget
263

264
imgui.input_text("Will be focused", "", 256)
265
```
266

267
### Custom Mouse Cursor
268

269
```python
270
# Change mouse cursor based on context
271
if imgui.is_item_hovered():
272
    imgui.set_mouse_cursor(imgui.MOUSE_CURSOR_HAND)
273
else:
274
    imgui.set_mouse_cursor(imgui.MOUSE_CURSOR_ARROW)
275
```
276

277
### Focus Management
278

279
```python
280
# Set default focus when window first appears
281
imgui.set_item_default_focus()
282
changed, text = imgui.input_text("Default Focus", "", 256)
283

284
# Focus management with buttons
285
if imgui.button("Focus Input"):
286
    imgui.set_keyboard_focus_here(1)
287

288
imgui.input_text("Target Input", "", 256)
289

290
# Check global focus state
291
if imgui.is_any_item_focused():
292
    imgui.text("Something has keyboard focus")
293
```
294

295
### Advanced State Queries
296

297
```python
298
if imgui.button("State Demo"):
299
    pass
300

301
# Detailed state information
302
states = []
303
if imgui.is_item_hovered(): states.append("Hovered")
304
if imgui.is_item_active(): states.append("Active")
305
if imgui.is_item_focused(): states.append("Focused")
306
if imgui.is_item_clicked(): states.append("Clicked")
307
if imgui.is_item_visible(): states.append("Visible")
308

309
if states:
310
    imgui.text(f"Button states: {', '.join(states)}")
311
else:
312
    imgui.text("Button states: None")
313
```
314

315
### Drag and Drop Detection
316

317
```python
318
# Detect dragging for custom drag and drop
319
if imgui.button("Drag Me"):
320
    pass
321

322
if imgui.is_item_active() and imgui.is_mouse_dragging(imgui.MOUSE_BUTTON_LEFT):
323
    drag_delta = imgui.get_mouse_drag_delta(imgui.MOUSE_BUTTON_LEFT)
324
    imgui.text(f"Dragging button: {drag_delta[0]:.1f}, {drag_delta[1]:.1f}")
325
```