0
# Events and Interactivity
1
2
Event system for handling user interactions including clicks, form changes, focus events, and custom events. Lona's event system enables real-time interactivity by allowing views to wait for and respond to user actions asynchronously.
3
4
## Capabilities
5
6
### Event Constants
7
8
Predefined event types for common user interactions.
9
10
```python { .api }
11
# Event type constants
12
CLICK: int # Click events on interactive elements
13
CHANGE: int # Change events on form inputs
14
FOCUS: int # Focus events when elements gain focus
15
BLUR: int # Blur events when elements lose focus
16
```
17
18
### Event Classes
19
20
Classes for representing and handling user input events.
21
22
```python { .api }
23
class InputEvent:
24
def __init__(self, event_type: int, node: 'Node', data: dict = None):
25
"""
26
Represents a user input event with complete context information.
27
28
Args:
29
event_type (int): Type of event (CLICK, CHANGE, etc.)
30
node (Node): HTML node that triggered the event
31
data (dict): Additional event data
32
"""
33
34
# Properties
35
event_type: int # Event type constant
36
node: 'Node' # Source HTML node
37
data: dict # Event-specific data
38
timestamp: float # Event timestamp
39
request: 'Request' # Associated request object
40
payload: dict # Raw event payload from client
41
document: 'Document' # Document containing the node
42
connection: object # Client connection object
43
window_id: str # Browser window identifier
44
nodes: list # List of involved nodes
45
target_node: 'Node' # Primary target node
46
tag_name: str # HTML tag name of target
47
id_list: list # CSS IDs of target node
48
class_list: list # CSS classes of target node
49
event_id: int # Unique event identifier
50
type: int # Alias for event_type
51
name: str # Event name string
52
node_info: dict # Additional node information
53
target_node_info: dict # Target node metadata
54
55
class EventType:
56
def __init__(self, name: str, code: int):
57
"""
58
Base event type definition.
59
60
Args:
61
name (str): Event type name
62
code (int): Numeric event code
63
"""
64
65
class ChangeEventType(EventType):
66
def __init__(self, input_delay: float = 0.0):
67
"""
68
Change event with optional input delay.
69
70
Args:
71
input_delay (float): Delay in seconds before firing change events
72
"""
73
```
74
75
### View Event Methods
76
77
Methods available in View classes for waiting for and handling user events.
78
79
```python { .api }
80
# Event waiting methods (available in View class)
81
def await_input_event(self, *nodes, html=None, timeout=None) -> 'InputEvent':
82
"""
83
Wait for any input event on specified nodes.
84
85
Args:
86
*nodes: HTML nodes to monitor for events
87
html: Optional HTML to show before waiting
88
timeout: Optional timeout in seconds
89
90
Returns:
91
InputEvent: Event details when triggered
92
"""
93
94
def await_click(self, *nodes, html=None, timeout=None) -> 'InputEvent':
95
"""
96
Wait for click events on specified nodes.
97
98
Args:
99
*nodes: HTML nodes to monitor for clicks
100
html: Optional HTML to show before waiting
101
timeout: Optional timeout in seconds
102
103
Returns:
104
InputEvent: Click event details
105
"""
106
107
def await_change(self, *nodes, html=None, timeout=None) -> 'InputEvent':
108
"""
109
Wait for change events on specified nodes.
110
111
Args:
112
*nodes: HTML nodes to monitor for changes
113
html: Optional HTML to show before waiting
114
timeout: Optional timeout in seconds
115
116
Returns:
117
InputEvent: Change event details
118
"""
119
120
def await_focus(self, *nodes, html=None, timeout=None) -> 'InputEvent':
121
"""
122
Wait for focus events on specified nodes.
123
124
Args:
125
*nodes: HTML nodes to monitor for focus
126
html: Optional HTML to show before waiting
127
timeout: Optional timeout in seconds
128
129
Returns:
130
InputEvent: Focus event details
131
"""
132
133
def await_blur(self, *nodes, html=None, timeout=None) -> 'InputEvent':
134
"""
135
Wait for blur events on specified nodes.
136
137
Args:
138
*nodes: HTML nodes to monitor for blur
139
html: Optional HTML to show before waiting
140
timeout: Optional timeout in seconds
141
142
Returns:
143
InputEvent: Blur event details
144
"""
145
146
def fire_view_event(self, name: str, data=None):
147
"""
148
Fire a custom view event.
149
150
Args:
151
name (str): Event name
152
data: Event data payload
153
"""
154
```
155
156
#### Interactive View Usage Example
157
158
```python
159
from lona import App, View
160
from lona.html import HTML, H1, Button, TextInput, P
161
from lona.events import CLICK, CHANGE
162
163
app = App(__file__)
164
165
@app.route('/interactive')
166
class InteractiveView(View):
167
def handle_request(self, request):
168
# Create interactive elements
169
name_input = TextInput(placeholder='Enter your name')
170
greet_button = Button('Greet')
171
result_text = P('')
172
173
html = HTML(
174
H1('Interactive Example'),
175
name_input,
176
greet_button,
177
result_text
178
)
179
180
self.show(html)
181
182
while True:
183
# Wait for either button click or input change
184
event = self.await_input_event(name_input, greet_button)
185
186
if event.node == greet_button:
187
# Button was clicked
188
name = name_input.value or 'World'
189
result_text.set_text(f'Hello, {name}!')
190
191
elif event.node == name_input:
192
# Input was changed
193
if name_input.value:
194
result_text.set_text(f'Hi {name_input.value}...')
195
else:
196
result_text.set_text('')
197
```
198
199
## Types
200
201
```python { .api }
202
from typing import Union, Optional, Dict, Any, Callable
203
from lona.html import Node
204
205
# Event types
206
EventCode = int
207
EventData = Dict[str, Any]
208
EventHandler = Callable[['InputEvent'], None]
209
EventTimeout = Optional[float]
210
211
# Node collections for event monitoring
212
EventNodes = Union[Node, tuple, list]
213
HTMLNodes = Union[Node, tuple, list]
214
215
# Custom event types
216
CustomEventName = str
217
CustomEventData = Any
218
```