0
# Application Building
1
2
Framework for building full-featured interactive terminal applications with event loops, layouts, and user interfaces. The Application class serves as the central coordinator managing all aspects of terminal interaction.
3
4
## Capabilities
5
6
### Application Class
7
8
The main Application class provides the core framework for interactive terminal applications, managing the event loop, input/output, layout rendering, and user interaction.
9
10
```python { .api }
11
class Application:
12
def __init__(
13
self,
14
layout=None,
15
style=None,
16
key_bindings=None,
17
clipboard=None,
18
full_screen=False,
19
mouse_support=False,
20
enable_page_navigation_bindings=None,
21
color_depth=None,
22
min_redraw_interval=0.04,
23
max_render_postpone_time=0.01,
24
refresh_interval=0.5,
25
input=None,
26
output=None
27
):
28
"""
29
Create an Application instance.
30
31
Parameters:
32
- layout: Layout instance defining the UI structure
33
- style: Style instance for visual formatting
34
- key_bindings: KeyBindings instance for keyboard handling
35
- clipboard: Clipboard instance for copy/paste operations
36
- full_screen: bool, whether to use full screen mode
37
- mouse_support: bool, whether to enable mouse input
38
- color_depth: ColorDepth, color support level
39
- input: Input instance for reading user input
40
- output: Output instance for terminal output
41
"""
42
43
def run(self, pre_run=None, set_exception_handler=True):
44
"""
45
Run the application synchronously.
46
47
Parameters:
48
- pre_run: Optional callable to execute before starting
49
- set_exception_handler: bool, whether to set exception handler
50
51
Returns:
52
Application result value
53
"""
54
55
async def run_async(self, pre_run=None, set_exception_handler=True):
56
"""
57
Run the application asynchronously.
58
59
Parameters:
60
- pre_run: Optional async callable to execute before starting
61
- set_exception_handler: bool, whether to set exception handler
62
63
Returns:
64
Application result value
65
"""
66
67
def exit(self, result=None, exception=None, style=""):
68
"""
69
Exit the application with optional result.
70
71
Parameters:
72
- result: Return value for the application
73
- exception: Optional exception to raise
74
- style: Exit style specification
75
"""
76
77
def invalidate(self):
78
"""
79
Invalidate the application for redraw.
80
"""
81
82
def render_last(self):
83
"""
84
Render the last frame again.
85
"""
86
```
87
88
### Application Session Management
89
90
Functions for managing application context and accessing the current application instance.
91
92
```python { .api }
93
def get_app():
94
"""
95
Get the current Application instance.
96
97
Returns:
98
Current Application instance
99
100
Raises:
101
RuntimeError: If no application is running
102
"""
103
104
def get_app_or_none():
105
"""
106
Get the current Application instance or None.
107
108
Returns:
109
Current Application instance or None if no app running
110
"""
111
112
def set_app(app):
113
"""
114
Set the current Application instance.
115
116
Parameters:
117
- app: Application instance to set as current
118
"""
119
120
class AppSession:
121
"""
122
Application session context manager.
123
"""
124
def __init__(self, app, output=None):
125
"""
126
Create application session.
127
128
Parameters:
129
- app: Application instance
130
- output: Optional output instance
131
"""
132
133
def get_app_session():
134
"""
135
Get the current application session.
136
137
Returns:
138
Current AppSession instance
139
"""
140
141
def create_app_session(app=None, input=None, output=None):
142
"""
143
Create a new application session.
144
145
Parameters:
146
- app: Optional Application instance
147
- input: Optional Input instance
148
- output: Optional Output instance
149
150
Returns:
151
AppSession instance
152
"""
153
154
def create_app_session_from_tty():
155
"""
156
Create application session from TTY.
157
158
Returns:
159
AppSession instance configured for TTY
160
"""
161
```
162
163
### Terminal Operations
164
165
Functions for running operations within terminal context and managing terminal state.
166
167
```python { .api }
168
def in_terminal(func=None):
169
"""
170
Decorator for running function in terminal context.
171
172
Parameters:
173
- func: Function to wrap
174
175
Returns:
176
Decorated function or decorator
177
"""
178
179
def run_in_terminal(func, render_cli_done=False, in_executor=False):
180
"""
181
Run function in terminal mode.
182
183
Parameters:
184
- func: Function to execute
185
- render_cli_done: bool, whether to render completion message
186
- in_executor: bool, whether to run in thread executor
187
188
Returns:
189
Function result
190
"""
191
```
192
193
### Dummy Application
194
195
Test implementation for unit testing and development.
196
197
```python { .api }
198
class DummyApplication(Application):
199
"""
200
Dummy Application implementation for testing.
201
"""
202
def __init__(self):
203
"""
204
Create dummy application with minimal configuration.
205
"""
206
```
207
208
## Usage Examples
209
210
### Basic Application
211
212
```python
213
from prompt_toolkit.application import Application
214
from prompt_toolkit.layout import Layout
215
from prompt_toolkit.layout.containers import HSplit
216
from prompt_toolkit.layout.controls import FormattedTextControl
217
from prompt_toolkit.key_binding import KeyBindings
218
219
# Create key bindings
220
bindings = KeyBindings()
221
222
@bindings.add('c-c')
223
def exit_app(event):
224
event.app.exit()
225
226
@bindings.add('c-q')
227
def quit_app(event):
228
event.app.exit()
229
230
# Create layout
231
layout = Layout(
232
HSplit([
233
FormattedTextControl('Hello World!'),
234
FormattedTextControl('Press Ctrl-C or Ctrl-Q to exit.')
235
])
236
)
237
238
# Create and run application
239
app = Application(
240
layout=layout,
241
key_bindings=bindings,
242
full_screen=True
243
)
244
245
app.run()
246
```
247
248
### Application with Mouse Support
249
250
```python
251
from prompt_toolkit.application import Application
252
from prompt_toolkit.layout import Layout
253
from prompt_toolkit.layout.containers import HSplit, Window
254
from prompt_toolkit.layout.controls import FormattedTextControl
255
256
# Create layout with mouse-enabled components
257
layout = Layout(
258
HSplit([
259
Window(
260
FormattedTextControl('Click anywhere to see mouse position'),
261
height=3
262
),
263
Window(
264
FormattedTextControl('Mouse info will appear here'),
265
height=1
266
)
267
])
268
)
269
270
# Key bindings with mouse support
271
bindings = KeyBindings()
272
273
@bindings.add('c-c')
274
def exit_app(event):
275
event.app.exit()
276
277
# Create application with mouse support
278
app = Application(
279
layout=layout,
280
key_bindings=bindings,
281
mouse_support=True,
282
full_screen=True
283
)
284
285
app.run()
286
```
287
288
### Async Application
289
290
```python
291
import asyncio
292
from prompt_toolkit.application import Application
293
from prompt_toolkit.layout import Layout
294
from prompt_toolkit.layout.containers import HSplit
295
from prompt_toolkit.layout.controls import FormattedTextControl
296
297
async def main():
298
# Create layout
299
layout = Layout(
300
HSplit([
301
FormattedTextControl('Async Application'),
302
FormattedTextControl('Press Ctrl-C to exit')
303
])
304
)
305
306
# Key bindings
307
bindings = KeyBindings()
308
309
@bindings.add('c-c')
310
def exit_app(event):
311
event.app.exit()
312
313
# Create and run async application
314
app = Application(
315
layout=layout,
316
key_bindings=bindings,
317
full_screen=True
318
)
319
320
result = await app.run_async()
321
return result
322
323
# Run the async application
324
asyncio.run(main())
325
```
326
327
### Application with Custom Input/Output
328
329
```python
330
from prompt_toolkit.application import Application
331
from prompt_toolkit.input import create_pipe_input
332
from prompt_toolkit.output import create_output
333
from prompt_toolkit.layout import Layout
334
from prompt_toolkit.layout.controls import FormattedTextControl
335
336
# Create custom input/output
337
input_pipe = create_pipe_input()
338
output = create_output()
339
340
# Create application with custom I/O
341
app = Application(
342
layout=Layout(FormattedTextControl('Custom I/O Application')),
343
input=input_pipe,
344
output=output
345
)
346
347
# Send input programmatically
348
input_pipe.send_text('Hello\n')
349
350
# Run application
351
app.run()
352
```