0
# Application Lifecycle
1

2
Core application management functions for DearPyGui applications. These functions control the application lifecycle from initialization through the main loop to cleanup. Every DearPyGui application must use these functions in the proper sequence.
3

4
## Capabilities
5

6
### Context Management
7

8
Context creation and destruction manages the global application state and resources.
9

10
```python { .api }
11
def create_context() -> None:
12
    """
13
    Creates the DearPyGui context. Must be called before any other DearPyGui functions.
14
    
15
    This initializes the global state, memory allocators, and core systems.
16
    Only one context can exist at a time.
17
    """
18

19
def destroy_context() -> None:
20
    """
21
    Destroys the DearPyGui context and cleans up all resources.
22
    
23
    This should be called at the end of your application to ensure
24
    proper cleanup of GPU resources, memory, and platform handles.
25
    """
26
```
27

28
#### Usage Example
29

30
```python
31
import dearpygui.dearpygui as dpg
32

33
# Initialize DearPyGui
34
dpg.create_context()
35

36
# Your application code here
37
# ...
38

39
# Cleanup when done
40
dpg.destroy_context()
41
```
42

43
### Viewport Management
44

45
Viewport functions manage the main application window and its properties.
46

47
```python { .api }
48
def create_viewport(*, title: str = '', width: int = '', height: int = '', x_pos: int = '', y_pos: int = '', min_width: int = '', min_height: int = '', max_width: int = '', max_height: int = '', resizable: bool = '', vsync: bool = '', always_on_top: bool = '', decorated: bool = '', clear_color: Union[List[float], Tuple[float, ...]] = '', small_icon: str = '', large_icon: str = '') -> None:
49
    """
50
    Creates the main application viewport (window).
51
    
52
    Parameters:
53
    - title (str): Window title
54
    - width, height (int): Initial window size
55
    - x_pos, y_pos (int): Initial window position
56
    - min_width, min_height (int): Minimum window size
57
    - max_width, max_height (int): Maximum window size  
58
    - resizable (bool): Allow window resizing
59
    - vsync (bool): Enable vertical sync
60
    - always_on_top (bool): Keep window on top
61
    - decorated (bool): Show window decorations (title bar, etc.)
62
    - clear_color (tuple): Background clear color as (r, g, b, a)
63
    - small_icon, large_icon (str): Icon file paths
64
    """
65

66
def show_viewport() -> None:
67
    """
68
    Makes the viewport visible. Call after create_viewport() and setup_dearpygui().
69
    """
70

71
def maximize_viewport() -> None:
72
    """Maximizes the viewport window."""
73

74
def minimize_viewport() -> None:
75
    """Minimizes the viewport window."""
76

77
def toggle_viewport_fullscreen() -> None:
78
    """Toggles fullscreen mode for the viewport."""
79

80
def is_viewport_ok() -> bool:
81
    """
82
    Checks if the viewport is valid and not closed.
83
    
84
    Returns:
85
    bool: True if viewport is still valid
86
    """
87
```
88

89
### Application Setup and Control
90

91
Core setup and control functions for running the application.
92

93
```python { .api }
94
def setup_dearpygui() -> None:
95
    """
96
    Completes DearPyGui setup. Call after creating context and viewport,
97
    but before showing viewport and starting the main loop.
98
    
99
    This initializes the rendering backend and prepares the application
100
    for display.
101
    """
102

103
def start_dearpygui() -> None:
104
    """
105
    Starts the DearPyGui main loop. This is a blocking call that runs
106
    until the application is closed.
107
    
108
    Equivalent to:
109
    while dpg.is_dearpygui_running():
110
        dpg.render_dearpygui_frame()
111
    """
112

113
def stop_dearpygui() -> None:
114
    """
115
    Stops the DearPyGui main loop. Can be called from within the application
116
    to programmatically exit.
117
    """
118

119
def is_dearpygui_running() -> bool:
120
    """
121
    Checks if DearPyGui is currently running.
122
    
123
    Returns:
124
    bool: True if the main loop should continue
125
    """
126

127
def render_dearpygui_frame() -> None:
128
    """
129
    Renders a single frame. Use this for custom main loops instead of
130
    start_dearpygui() when you need more control over the execution.
131
    """
132

133
def split_frame() -> None:
134
    """
135
    Splits the current frame processing. Advanced usage for custom
136
    render loops with timing control.
137
    """
138
```
139

140
### Configuration Functions
141

142
Application-wide configuration and settings.
143

144
```python { .api }
145
def configure_app(*, manual_callback_management: bool = '', load_init_file: str = '', init_file: str = '', auto_save_init_file: bool = '', auto_device: bool = '', device: int = '', allow_alias_overwrites: bool = '', auto_render_delay_time: int = '', skip_required_args: bool = '', skip_positional_args: bool = '', skip_keyword_args: bool = '', wait_for_input: bool = '', docking: bool = '', docking_space: bool = '') -> None:
146
    """
147
    Configures global application settings.
148
    
149
    Parameters:
150
    - manual_callback_management (bool): Disable automatic callback processing
151
    - load_init_file (str): Load settings from file on startup
152
    - init_file (str): Settings file path
153
    - auto_save_init_file (bool): Automatically save settings on exit
154
    - auto_device (bool): Automatically select graphics device
155
    - device (int): Specific graphics device index
156
    - allow_alias_overwrites (bool): Allow alias name collisions
157
    - auto_render_delay_time (int): Delay between render calls (ms)
158
    - skip_required_args (bool): Skip required argument validation
159
    - skip_positional_args (bool): Skip positional argument validation  
160
    - skip_keyword_args (bool): Skip keyword argument validation
161
    - wait_for_input (bool): Wait for user input before rendering
162
    - docking (bool): Enable window docking
163
    - docking_space (bool): Create docking space
164
    """
165

166
def get_app_configuration() -> dict:
167
    """
168
    Gets current application configuration.
169
    
170
    Returns:
171
    dict: Configuration settings dictionary
172
    """
173

174
def configure_viewport(item: Union[int, str], *, title: str = '', width: int = '', height: int = '', x_pos: int = '', y_pos: int = '', min_width: int = '', min_height: int = '', max_width: int = '', max_height: int = '', resizable: bool = '', vsync: bool = '', always_on_top: bool = '', decorated: bool = '', clear_color: Union[List[float], Tuple[float, ...]] = '', small_icon: str = '', large_icon: str = '') -> None:
175
    """
176
    Configures viewport properties after creation.
177
    
178
    Parameters: Same as create_viewport()
179
    """
180

181
def get_viewport_configuration() -> dict:
182
    """
183
    Gets current viewport configuration.
184
    
185
    Returns:
186
    dict: Viewport settings dictionary
187
    """
188
```
189

190
### Callback Management
191

192
Advanced callback system control for custom event handling.
193

194
```python { .api }
195
def set_frame_callback(frame: int, callback: Callable) -> None:
196
    """
197
    Sets a callback to be executed on a specific frame.
198
    
199
    Parameters:
200
    - frame (int): Frame number to execute callback
201
    - callback (Callable): Function to call
202
    """
203

204
def set_exit_callback(callback: Callable) -> None:
205
    """
206
    Sets a callback to be executed when the application exits.
207
    
208
    Parameters:
209
    - callback (Callable): Function to call on exit
210
    """
211

212
def set_viewport_resize_callback(callback: Callable) -> None:
213
    """
214
    Sets a callback for viewport resize events.
215
    
216
    Parameters:
217
    - callback (Callable): Function to call with (sender, width, height)
218
    """
219

220
def get_callback_queue() -> list:
221
    """
222
    Gets the current callback queue for manual processing.
223
    
224
    Returns:
225
    list: List of pending callbacks
226
    """
227

228
def run_callbacks(jobs: list) -> None:
229
    """
230
    Manually processes a list of callbacks.
231
    
232
    Parameters:
233
    - jobs (list): List of callback jobs to process
234
    """
235
```
236

237
### System Information
238

239
Functions to get system and runtime information.
240

241
```python { .api }
242
def get_platform() -> int:
243
    """
244
    Gets the current platform identifier.
245
    
246
    Returns:
247
    int: Platform constant (Windows=0, Linux=1, Apple=2)
248
    """
249

250
def get_frame_count() -> int:
251
    """
252
    Gets the current frame number.
253
    
254
    Returns:
255
    int: Number of frames rendered since start
256
    """
257

258
def get_frame_rate() -> float:
259
    """
260
    Gets the current frame rate in FPS.
261
    
262
    Returns:
263
    float: Frames per second
264
    """
265

266
def get_delta_time() -> float:
267
    """
268
    Gets the time elapsed since the last frame.
269
    
270
    Returns:
271
    float: Delta time in seconds
272
    """
273

274
def get_total_time() -> float:
275
    """
276
    Gets the total time since application start.
277
    
278
    Returns:
279
    float: Total elapsed time in seconds
280
    """
281
```
282

283
### Application Patterns
284

285
Common application structure patterns for different use cases.
286

287
#### Basic Application Pattern
288

289
```python
290
import dearpygui.dearpygui as dpg
291

292
# Setup
293
dpg.create_context()
294
dpg.create_viewport(title="My App", width=800, height=600)
295
dpg.setup_dearpygui()
296

297
# Create UI
298
with dpg.window(label="Main Window", width=400, height=300):
299
    dpg.add_text("Hello, DearPyGui!")
300
    dpg.add_button(label="Click Me!")
301

302
# Run
303
dpg.show_viewport()
304
dpg.start_dearpygui()
305

306
# Cleanup
307
dpg.destroy_context()
308
```
309

310
#### Custom Main Loop Pattern
311

312
```python
313
import dearpygui.dearpygui as dpg
314

315
# Setup
316
dpg.create_context()
317
dpg.create_viewport(title="Custom Loop", width=800, height=600)
318
dpg.setup_dearpygui()
319

320
# Create UI
321
with dpg.window(label="Main Window"):
322
    dpg.add_text("Custom main loop example")
323

324
# Custom main loop
325
dpg.show_viewport()
326
while dpg.is_dearpygui_running():
327
    # Custom logic here
328
    frame_time = dpg.get_delta_time()
329
    
330
    # Process callbacks manually if needed
331
    # dpg.run_callbacks(dpg.get_callback_queue())
332
    
333
    # Render frame
334
    dpg.render_dearpygui_frame()
335

336
dpg.destroy_context()
337
```
338

339
#### Configuration Example
340

341
```python
342
import dearpygui.dearpygui as dpg
343

344
dpg.create_context()
345

346
# Configure application
347
dpg.configure_app(
348
    docking=True,
349
    docking_space=True,
350
    auto_device=True,
351
    wait_for_input=False
352
)
353

354
# Configure viewport
355
dpg.create_viewport(
356
    title="Configured App",
357
    width=1200,
358
    height=800,
359
    min_width=400,
360
    min_height=300,
361
    resizable=True,
362
    vsync=True,
363
    clear_color=(0.1, 0.1, 0.1, 1.0)
364
)
365

366
dpg.setup_dearpygui()
367

368
# Create dockable windows
369
with dpg.window(label="Window 1", width=300, height=200):
370
    dpg.add_text("Dockable window 1")
371

372
with dpg.window(label="Window 2", width=300, height=200):
373
    dpg.add_text("Dockable window 2")
374

375
dpg.show_viewport()
376
dpg.start_dearpygui()
377
dpg.destroy_context()
378
```
379

380
## Error Handling
381

382
Application lifecycle functions may raise exceptions for:
383

384
- **Context errors**: Calling functions before `create_context()` or after `destroy_context()`
385
- **Viewport errors**: Invalid viewport parameters or calling viewport functions without a viewport
386
- **Resource errors**: Graphics device initialization failures
387
- **Platform errors**: Platform-specific window creation failures
388

389
Always wrap application lifecycle calls in try-catch blocks for production applications:
390

391
```python
392
import dearpygui.dearpygui as dpg
393

394
try:
395
    dpg.create_context()
396
    dpg.create_viewport(title="Safe App", width=800, height=600)
397
    dpg.setup_dearpygui()
398
    
399
    # Your UI code here
400
    
401
    dpg.show_viewport()
402
    dpg.start_dearpygui()
403
    
404
except Exception as e:
405
    print(f"Application error: {e}")
406
    
407
finally:
408
    if dpg.is_dearpygui_running():
409
        dpg.destroy_context()
410
```
411

412
## Performance Considerations
413

414
- Call `create_context()` only once per application
415
- Use `configure_app()` before `setup_dearpygui()` for best performance
416
- Enable vsync for smoother animations: `create_viewport(vsync=True)`
417
- Use `wait_for_input=True` for applications that don't need continuous rendering
418
- Consider `auto_render_delay_time` for applications with heavy processing
419

420
## Platform-Specific Notes
421

422
### Windows
423
- Supports DirectX 11/12 backends for best performance
424
- Window icons should be .ico format
425
- DPI awareness is handled automatically
426

427
### macOS  
428
- Uses Metal backend
429
- Window icons should be .icns format
430
- Retina display support is automatic
431

432
### Linux
433
- Uses OpenGL backend
434
- Window icons should be .png format
435
- X11 and Wayland support