DPG Structure Overview

.. meta:: :description lang=en: General overview of the structure of dpg items.

A DPG app will have an overall structure as follows: * Setup * Context * Viewport * Render Loop * Items * Primary Window

Setup

All DPG apps must do 3 things: * Create & Destroy context * Create & Show Viewport * Setup & Start DearPyGui

The Context

To access any DPG commands the context must be created with :py:func:create_context <dearpygui.dearpygui.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 :py:func:destroy_context <dearpygui.dearpygui.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 :py:func:create_context <dearpygui.dearpygui.create_context> is not first DPG will not start (and will probably crash).

The Viewport

The viewport is the window created by the operating system.

The viewport needs to be explicitly created using :py:func:create_viewport <dearpygui.dearpygui.create_viewport> and shown using :py:func:show_viewport <dearpygui.dearpygui.show_viewport>

Code:

.. code-block:: python

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()

.. seealso:: For more information on the viewport :doc:../documentation/viewport

The Render Loop

The render loop is responsible for displaying items, partially maintaining state and callbacks.

The render loop is completely handled by the :py:func:start_dearpygui <dearpygui.dearpygui.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:

.. code-block:: python

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 :py:func:setup_dearpygui <dearpygui.dearpygui.setup_dearpygui>

.. seealso:: For more information on the render loop :doc:../documentation/render-loop

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).

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:

.. code-block:: python

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()

.. seealso:: for more information on the primary window :doc:../documentation/primary-window