Staging

The staging system is used to create items or item hierarchies where the parent/root is to be decided at a later time.

Staged items are not submitted for rendering.

Staged items will show up in the item registry.

Items can be moved out of staging by using move_item.

The most basic example can be found below:

import dearpygui.dearpygui as dpg

dpg.create_context()

def stage_items():
    with dpg.stage(tag="stage1"):
        dpg.add_text("hello, i was added from a stage", tag="text_tag")

def present_stage_items():
    dpg.move_item("text_tag", parent="main_win")

with dpg.window(label="Tutorial", tag="main_win"):
    dpg.add_button(label="stage items", callback=stage_items)
    dpg.add_button(label="present stages items", callback=present_stage_items)

dpg.show_item_registry()

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

Prefered way to “unstage” items is using unstage. This will place the items as if they were newly created items according to the standard rules of Container Stack.

Also using the unstage command will automatically clean up the stage container.

Using push_container_stack and pop_container_stack is recomended here as it provides better performance when unstaging.

import dearpygui.dearpygui as dpg

dpg.create_context()

def stage_items():
    with dpg.stage(tag="stage1"):
        dpg.add_text("hello, i was added from a stage")
        dpg.add_text("hello, i was added from a stage")
        dpg.add_text("hello, i was added from a stage")
        dpg.add_text("hello, i was added from a stage")
        dpg.add_text("hello, i was added from a stage")

def present_stage_items():
    dpg.push_container_stack("main_win")
    dpg.unstage("stage1")
    dpg.pop_container_stack()

with dpg.window(label="Tutorial", tag="main_win", height=400, width=400):
    dpg.add_button(label="stage items", callback=stage_items)
    dpg.add_button(label="present stages items", callback=present_stage_items)

dpg.show_item_registry()

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

Wrapping Items with Classes

The most obvious benefit of this system is for advanced users who are wrapping DPG items into classes. Rather than having to duplicate the various configurable options as members of the class (to avoid making calls to configure_item or get_item_configuration before the item is actually created), you can create and stage the item in the constructor of the wrapping class!

Below are 2 examples:

Example 1

import dearpygui.dearpygui as dpg

dpg.create_context()


class Button:

    def __init__(self, label):
        with dpg.stage() as self._staging_container_id:
            self._id = dpg.add_button(label=label)

    def set_callback(self, callback):
        dpg.set_item_callback(self._id, callback)

    def get_label(self):
        return dpg.get_item_label(self._id)

    def submit(self, parent):
        dpg.push_container_stack(parent)
        dpg.unstage(self._staging_container_id)
        dpg.pop_container_stack()

my_button = Button("Press me")
my_button.set_callback(lambda: print("I've been pressed!"))

print(my_button.get_label())

with dpg.window(label="Tutorial", tag="main_win"):
    dpg.add_text("hello world")

my_button.submit("main_win")

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

Example 2

import dearpygui.dearpygui as dpg

dpg.create_context()


class Window:

    def __init__(self, label):
        self._children = []
        with dpg.stage() as stage:
            self.id = dpg.add_window(label=label)
        self.stage = stage

    def add_child(self, child):
        dpg.move_item(child.id, parent=self.id)

    def submit(self):
        dpg.unstage(self.stage)


class Button:

    def __init__(self, label):
        with dpg.stage():
            self.id = dpg.add_button(label=label)

    def set_callback(self, callback):
        dpg.set_item_callback(self.id, callback)


my_button = Button("Press me")
my_button.set_callback(lambda: print("I've been pressed!"))

my_window = Window("Tutorial")

my_window.add_child(my_button)

my_window.submit()

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