Item Creation

DPG can be broken down into Items, UI Items, Containers.

Items

Everything created in DPG is an item. New items can be created by calling various add_*** or draw_*** functions. These commands return a unique identifier that can be used to later refer to the item. UI items and containers are also items - but not every item is necessarily a UI item or container.

All items have the following optional parameters: label, tag, user_data, and use_internal_label. The tag is generated automatically or can be specified. A label serves as the display name for an item. user_data can be any value and is frequently used for callbacks.

Note

Event handlers, registries, group, and themes are also items. These are under-the-hood items for customizing the functionality, flow, and overall look of your APP.

Containers

Container items that can contain other (allowable) items.

In addition to creating them by calling their corresponding add_*** function, they can also be created by calling their corresponding context manager.

Note

Containers are more useful (and recommended) when used as context managers.

Below is an example of creating two new window items using their context manager and starting the application:

import dearpygui.dearpygui as dpg

dpg.create_context()

with dpg.window(label="Window1", pos=(0,0)):
    pass

with dpg.window(label="Window2", pos=(100,0)):
    pass

dpg.create_viewport(title='Custom Title', width=600, height=200)
dpg.setup_dearpygui()
dpg.show_viewport()
dpg.start_dearpygui()
dpg.destroy_context()
https://raw.githubusercontent.com/Atlamillias/DearPyGui-Stuff/main/wiki%20images/dpg_creating_appitems_ex2.png

UI Items

UI items are items that are considered to be a visual and usually interactable element in your user interface.

These include buttons, sliders, inputs, and even other containers such as windows and tree nodes.

Below is an example for creating a window container that contains a few other items:

import dearpygui.dearpygui as dpg

dpg.create_context()

with dpg.window(label="Tutorial") as window:
    # When creating items within the scope of the context
    # manager, they are automatically "parented" by the
    # container created in the initial call. So, "window"
    # will be the parent for all of these items.

    button1 = dpg.add_button(label="Press Me!")

    slider_int = dpg.add_slider_int(label="Slide to the left!", width=100)
    slider_float = dpg.add_slider_float(label="Slide to the right!", width=100)

    # An item's unique identifier (tag) is returned when
    # creating items.
    print(f"Printing item tag's: {window}, {button1}, {slider_int}, {slider_float}")

# If you want to add an item to an existing container, you
# can specify it by passing the container's tag as the
# "parent" parameter.
button2 = dpg.add_button(label="Don't forget me!", parent=window)

dpg.create_viewport(title='Custom Title', width=600, height=200)
dpg.setup_dearpygui()
dpg.show_viewport()
dpg.start_dearpygui()
dpg.destroy_context()
https://raw.githubusercontent.com/Atlamillias/DearPyGui-Stuff/main/wiki%20images/dpg_creating_widgets_ex1.png

Runtime Adding and Deleting

With DPG you can dynamically add, delete, and move items at runtime.

This can be done by using a callback to run the desired item’s add_*** command and specifying the parent the item will belong to.

By using the before keyword when adding a item you can control which item in the parent the new item will come before. Default will place the new widget at the end.

Below is an example demonstrating adding and deleting items during runtime:

import dearpygui.dearpygui as dpg

dpg.create_context()

def add_buttons():
    global new_button1, new_button2
    new_button1 = dpg.add_button(label="New Button", before="delete_button", tag="new_button1")
    new_button2 = dpg.add_button(label="New Button 2", parent="secondary_window", tag="new_button2")


def delete_buttons():
    dpg.delete_item("new_button1")
    dpg.delete_item("new_button2")


with dpg.window(label="Tutorial", pos=(200, 200)):
    dpg.add_button(label="Add Buttons", callback=add_buttons)
    dpg.add_button(label="Delete Buttons", callback=delete_buttons, tag="delete_button")

with dpg.window(label="Secondary Window", tag="secondary_window", pos=(100, 100)):
    pass

dpg.create_viewport(title='Custom Title', width=600, height=400)
dpg.setup_dearpygui()
dpg.show_viewport()
dpg.start_dearpygui()
dpg.destroy_context()

Hint

When deleting a container the container and its’ children are deleted by default, unless the keyword children_only is set to True, i.e.:

import dearpygui.dearpygui as dpg

dpg.create_context()

def delete_children():
    dpg.delete_item("window", children_only=True)

with dpg.window(label="Tutorial", pos=(200, 200), tag="window"):
    dpg.add_button(label="Delete Children", callback=delete_children)
    dpg.add_button(label="Button_1")
    dpg.add_button(label="Button_2")
    dpg.add_button(label="Button_3")

dpg.create_viewport(title='Custom Title', width=600, height=400)
dpg.setup_dearpygui()
dpg.show_viewport()
dpg.start_dearpygui()
dpg.destroy_context()