2. DPG Structure Overview¶
- A DPG app will have an overall structure as follows:
Setup
Context
Viewport
Render Loop
Items
Primary Window
2.1. Setup¶
- All DPG apps must do 3 things:
Create & Destroy context
Create & Show Viewport
Setup & Start DearPyGui
2.2. The Context¶
To access any DPG commands the context must be created with create_context
This should be the first DPG command and it’s typical to perform this with an import.
Proper clean up of DPG can be done using destroy_context
.
Creating and destroying the context and also setup and start dearpygui are useful when the DPG needs to be started and stopped multiple times in one python session.
Warning
If create_context
is not first DPG will not start (and will probably crash).
2.3. The Viewport¶
The viewport is the window created by the operating system.
The viewport needs to be explicitly created
using create_viewport
and shown using show_viewport
Code:
import dearpygui.dearpygui as dpg
dpg.create_context()
with dpg.window(label="Example Window"):
dpg.add_text("Hello, world")
dpg.add_button(label="Save")
dpg.add_input_text(label="string", default_value="Quick brown fox")
dpg.add_slider_float(label="float", default_value=0.273, max_value=1)
dpg.create_viewport(title='Custom Title', width=600, height=200)
dpg.setup_dearpygui()
dpg.show_viewport()
dpg.start_dearpygui()
dpg.destroy_context()
See also
For more information on the viewport Viewport
2.4. The Render Loop¶
The render loop is responsible for displaying items, partially maintaining state and callbacks.
The render loop is completely handled
by the start_dearpygui
command.
In some cases it’s necessary to explicitly create the render loop so you can call python commands that may need to run every frame. Such as per-frame ticker or counter update functions.
Code:
import dearpygui.dearpygui as dpg
dpg.create_context()
with dpg.window(label="Example Window"):
dpg.add_text("Hello, world")
dpg.add_button(label="Save")
dpg.add_input_text(label="string", default_value="Quick brown fox")
dpg.add_slider_float(label="float", default_value=0.273, max_value=1)
dpg.create_viewport(title='Custom Title', width=600, height=200)
dpg.setup_dearpygui()
dpg.show_viewport()
# below replaces, start_dearpygui()
while dpg.is_dearpygui_running():
# insert here any code you would like to run in the render loop
# you can manually stop by using stop_dearpygui()
print("this will run every frame")
dpg.render_dearpygui_frame()
dpg.destroy_context()
Warning
The manual render loop must be created after setup_dearpygui
See also
For more information on the render loop Render Loop
2.5. Item Overview¶
DPG can be broken down into Items, UI Items, Containers
- Items:
Items are anything in the library (i.e. button, registries, windows, etc).
- UI Items:
Any item in DPG that has a visual component (i.e. button, listbox, window, etc).
- Containers:
Items that can hold other items. (i.e. window, groups, registries, etc).
2.6. The Primary Window¶
DPG can assign one window to be the primary window. The primary window will fill the viewport and always be drawn behind other windows.
Code:
import dearpygui.dearpygui as dpg
dpg.create_context()
with dpg.window(tag="Primary Window"):
dpg.add_text("Hello, world")
dpg.add_button(label="Save")
dpg.add_input_text(label="string", default_value="Quick brown fox")
dpg.add_slider_float(label="float", default_value=0.273, max_value=1)
dpg.create_viewport(title='Custom Title', width=600, height=200)
dpg.setup_dearpygui()
dpg.show_viewport()
dpg.set_primary_window("Primary Window", True)
dpg.start_dearpygui()
dpg.destroy_context()
See also
for more information on the primary window Primary Window