0
# Event Handling
1

2
Comprehensive event system for user interactions including mouse events, keyboard input, and item-specific callbacks. DearPyGui provides both global event handlers and item-specific event handling.
3

4
## Capabilities
5

6
### Handler Registries
7

8
```python { .api }
9
def add_handler_registry(*, tag: Union[int, str] = '', **kwargs) -> Union[int, str]:
10
    """Creates a registry for global event handlers."""
11

12
def add_item_handler_registry(*, tag: Union[int, str] = '', **kwargs) -> Union[int, str]:
13
    """Creates a registry for item-specific event handlers."""
14
```
15

16
### Mouse Event Handlers
17

18
```python { .api }
19
def add_mouse_click_handler(*, button: int = '', callback: Callable = '', tag: Union[int, str] = '', **kwargs) -> Union[int, str]:
20
    """Handles mouse click events."""
21

22
def add_mouse_down_handler(*, button: int = '', callback: Callable = '', tag: Union[int, str] = '', **kwargs) -> Union[int, str]:
23
    """Handles mouse button press events."""
24

25
def add_mouse_release_handler(*, button: int = '', callback: Callable = '', tag: Union[int, str] = '', **kwargs) -> Union[int, str]:
26
    """Handles mouse button release events."""
27

28
def add_mouse_move_handler(*, callback: Callable = '', tag: Union[int, str] = '', **kwargs) -> Union[int, str]:
29
    """Handles mouse movement events."""
30

31
def add_mouse_drag_handler(*, button: int = '', threshold: float = '', callback: Callable = '', tag: Union[int, str] = '', **kwargs) -> Union[int, str]:
32
    """Handles mouse drag events."""
33
```
34

35
### Keyboard Event Handlers
36

37
```python { .api }
38
def add_key_press_handler(*, key: int = '', callback: Callable = '', tag: Union[int, str] = '', **kwargs) -> Union[int, str]:
39
    """Handles key press events."""
40

41
def add_key_down_handler(*, key: int = '', callback: Callable = '', tag: Union[int, str] = '', **kwargs) -> Union[int, str]:
42
    """Handles key down events."""
43

44
def add_key_release_handler(*, key: int = '', callback: Callable = '', tag: Union[int, str] = '', **kwargs) -> Union[int, str]:
45
    """Handles key release events."""
46
```
47

48
### Item Event Handlers
49

50
```python { .api }
51
def add_item_clicked_handler(*, button: int = '', callback: Callable = '', tag: Union[int, str] = '', **kwargs) -> Union[int, str]:
52
    """Handles item click events."""
53

54
def add_item_hover_handler(*, callback: Callable = '', tag: Union[int, str] = '', **kwargs) -> Union[int, str]:
55
    """Handles item hover events."""
56

57
def add_item_focus_handler(*, callback: Callable = '', tag: Union[int, str] = '', **kwargs) -> Union[int, str]:
58
    """Handles item focus events."""
59

60
def add_item_edited_handler(*, callback: Callable = '', tag: Union[int, str] = '', **kwargs) -> Union[int, str]:
61
    """Handles item edit events."""
62

63
def add_item_activated_handler(*, label: str = '', user_data: Any = '', use_internal_label: bool = '', tag: Union[int, str] = '', parent: Union[int, str] = '', callback: Callable = '', show: bool = '') -> Union[int, str]:
64
    """
65
    Handles item activation events (double-click or Enter key).
66
    
67
    Parameters:
68
    - callback (Callable): Function to call when item is activated
69
    
70
    Returns:
71
    Union[int, str]: Handler ID
72
    """
73

74
def add_item_deactivated_handler(*, label: str = '', user_data: Any = '', use_internal_label: bool = '', tag: Union[int, str] = '', parent: Union[int, str] = '', callback: Callable = '', show: bool = '') -> Union[int, str]:
75
    """
76
    Handles item deactivation events.
77
    
78
    Parameters:
79
    - callback (Callable): Function to call when item is deactivated
80
    
81
    Returns:
82
    Union[int, str]: Handler ID
83
    """
84

85
def add_item_visible_handler(*, label: str = '', user_data: Any = '', use_internal_label: bool = '', tag: Union[int, str] = '', parent: Union[int, str] = '', callback: Callable = '', show: bool = '') -> Union[int, str]:
86
    """
87
    Handles item visibility change events.
88
    
89
    Parameters:
90
    - callback (Callable): Function to call when item visibility changes
91
    
92
    Returns:
93
    Union[int, str]: Handler ID
94
    """
95

96
def add_item_toggled_open_handler(*, label: str = '', user_data: Any = '', use_internal_label: bool = '', tag: Union[int, str] = '', parent: Union[int, str] = '', callback: Callable = '', show: bool = '') -> Union[int, str]:
97
    """
98
    Handles toggle events for collapsible items.
99
    
100
    Parameters:
101
    - callback (Callable): Function to call when item is toggled
102
    
103
    Returns:
104
    Union[int, str]: Handler ID
105
    """
106
```
107

108
### Input State Queries
109

110
```python { .api }
111
def is_mouse_button_down(button: int) -> bool:
112
    """Checks if mouse button is currently pressed."""
113

114
def is_mouse_button_clicked(button: int) -> bool:
115
    """Checks if mouse button was clicked this frame."""
116

117
def is_mouse_button_double_clicked(button: int) -> bool:
118
    """Checks if mouse button was double-clicked this frame."""
119

120
def is_mouse_button_released(button: int) -> bool:
121
    """Checks if mouse button was released this frame."""
122

123
def is_mouse_button_dragging(button: int, threshold: float) -> bool:
124
    """
125
    Checks if mouse button is being dragged.
126
    
127
    Parameters:
128
    - button (int): Mouse button constant
129
    - threshold (float): Minimum drag distance
130
    
131
    Returns:
132
    bool: True if dragging
133
    """
134

135
def is_key_down(key: int) -> bool:
136
    """Checks if key is currently pressed."""
137

138
def get_mouse_pos() -> Union[List[int], Tuple[int, ...]]:
139
    """Gets current mouse position."""
140

141
def get_mouse_drag_delta(button: int = '', lock_threshold: float = '') -> Union[List[float], Tuple[float, ...]]:
142
    """Gets mouse drag distance."""
143
```
144

145
### Frame and Capture Functions
146

147
```python { .api }
148
def set_frame_callback(frame: int, callback: Callable, *, user_data: Any = '') -> str:
149
    """
150
    Sets a callback to execute at a specific frame number.
151
    
152
    Parameters:
153
    - frame (int): Frame number to execute callback
154
    - callback (Callable): Function to call
155
    - user_data (Any): Data to pass to callback
156
    
157
    Returns:
158
    str: Callback ID
159
    """
160

161
def capture_next_item(callback: Callable, *, user_data: Any = '') -> None:
162
    """
163
    Captures the next item created and passes it to callback.
164
    
165
    Parameters:
166
    - callback (Callable): Function to receive captured item
167
    - user_data (Any): Data to pass to callback
168
    """
169
```
170

171
## Usage Example
172

173
```python
174
import dearpygui.dearpygui as dpg
175

176
def on_key_press(sender, key):
177
    print(f"Key pressed: {key}")
178

179
def on_mouse_click(sender, button):
180
    pos = dpg.get_mouse_pos()
181
    print(f"Mouse clicked at {pos}")
182

183
def on_button_clicked(sender):
184
    print(f"Button {sender} was clicked!")
185

186
# Create handler registry
187
with dpg.handler_registry():
188
    dpg.add_key_press_handler(callback=on_key_press)
189
    dpg.add_mouse_click_handler(callback=on_mouse_click)
190

191
# Window with widgets
192
with dpg.window(label="Event Example", width=400, height=300):
193
    dpg.add_text("Press keys or click mouse")
194
    dpg.add_button(label="Click Me!", callback=on_button_clicked)
195
```
196

197
## Constants
198

199
```python { .api }
200
# Mouse buttons
201
mvMouseButton_Left: int
202
mvMouseButton_Right: int
203
mvMouseButton_Middle: int
204

205
# Key codes
206
mvKey_A: int
207
mvKey_B: int
208
# ... (full key set available)
209
```