3. Item Usage

3.1. Creating Items

Items are created using their add_*** commands.

All items must have a tag which can either be specified or are automatically generated by DPG.

Tags can be either integers or strings and are used to refer to the item after it has been created.

Items return their tag when they are created.

Warning

Item tags must be unique if specified using the tag keyword. Integers 0-10 are reserved for DPG internal items.

import dearpygui.dearpygui as dpg

dpg.create_context()

with dpg.window(label="Tutorial"):
    b0 = dpg.add_button(label="button 0")
    b1 = dpg.add_button(tag=100, label="Button 1")
    dpg.add_button(tag="Btn2", label="Button 2")

print(b0)
print(b1)
print(dpg.get_item_label("Btn2"))

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

Note

Items can be created and delete at runtime see Item Creation

See also

For more information on the creating items:

Item Creation

Tag System

3.2. Creating Containers

Below we will add a window, a group and a child window to the code. Items can either be added directly to the context manager or later by specifying the parent.

import dearpygui.dearpygui as dpg

dpg.create_context()

with dpg.window(label="Tutorial"):
    dpg.add_button(label="Button 1")
    dpg.add_button(label="Button 2")
    with dpg.group():
        dpg.add_button(label="Button 3")
        dpg.add_button(label="Button 4")
        with dpg.group() as group1:
            pass
dpg.add_button(label="Button 6", parent=group1)
dpg.add_button(label="Button 5", parent=group1)

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

See also

For more information on containers:

Item Creation

Containers & Context Managers

Container Slots & Children

Container Stack

3.3. Configuration, State, Info

DPG items consist of configuration, state and info. (AND value but we will cover that separately)

Each of these can be accessed by their corresponding function

get_item_configuration

keywords that control its appearance and behavior (label, callback, width, height)

get_item_state

keywords that reflect its interaction (visible, hovered, clicked, etc)

get_item_info

keywords that reflect its information (item type, children, theme, etc)

Note

configuration, state and info are broken into separate commands that access each individual keyword, instead of returning the entire dictionary.

Examples:

get_item_label

is_item_hovered

get_item_children

Below we will demonstrate the ways to configure items and how to check their state by viewing them through the item registry tool.

Code:

import dearpygui.dearpygui as dpg

dpg.create_context()

with dpg.window(label="Tutorial"):

    # configuration set when button is created
    dpg.add_button(label="Apply", width=300)

    # user data and callback set any time after button has been created
    btn = dpg.add_button(label="Apply 2")
    dpg.set_item_label(btn, "Button 57")
    dpg.set_item_width(btn, 200)

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

See also

For more information on the these topics:

Item Configuration

IO, Handlers, State Polling

3.4. Callbacks

Callbacks give items functionality by assigning a function to run when they are activated and almost all UI Items in DPG can run callbacks.

Functions or methods are assigned as UI item callbacks when an item is created or at a later runtime using set_item_callback

Callbacks may have up to 3 arguments in the following order.

sender:

the id of the UI item that submitted the callback

app_data:

occasionally UI items will send their own data (ex. file dialog)

user_data:

any python object you want to send to the function

Note

Because they are optional positional arguments you must use the sender and app_data if you want to use user_data standard keyword arguments

Code:

import dearpygui.dearpygui as dpg

dpg.create_context()

def button_callback(sender, app_data, user_data):
    print(f"sender is: {sender}")
    print(f"app_data is: {app_data}")
    print(f"user_data is: {user_data}")

with dpg.window(label="Tutorial"):
    # user data and callback set when button is created
    dpg.add_button(label="Apply", callback=button_callback, user_data="Some Data")

    # user data and callback set any time after button has been created
    btn = dpg.add_button(label="Apply 2", )
    dpg.set_item_callback(btn, button_callback)
    dpg.set_item_user_data(btn, "Some Extra User Data")

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

See also

For more information on the item callbacks Item Callbacks

3.5. Item Values

Almost all UI items have a value which can be accessed or set.

All UI items that have a value also have the default_value parameter which will set the items’ initial starting value.

Values can be accessed using get_value.

Below is an example of setting the default_value for two different items, setting a callback to the items and printing their values.

import dearpygui.dearpygui as dpg

dpg.create_context()

def print_value(sender):
    print(dpg.get_value(sender))

with dpg.window(width=300):
    input_txt1 = dpg.add_input_text()
    # The value for input_text2 will have a starting value
    # of "This is a default value!"
    input_txt2 = dpg.add_input_text(
        label="InputTxt2",
        default_value="This is a default value!",
        callback=print_value
    )

    slider_float1 = dpg.add_slider_float()
    # The slider for slider_float2 will have a starting value
    # of 50.0.
    slider_float2 = dpg.add_slider_float(
        label="SliderFloat2",
        default_value=50.0,
        callback=print_value
    )

    dpg.set_item_callback(input_txt1, print_value)
    dpg.set_item_callback(slider_float1, print_value)

    print(dpg.get_value(input_txt1))
    print(dpg.get_value(input_txt2))
    print(dpg.get_value(slider_float1))
    print(dpg.get_value(slider_float2))

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

An input item’s value is changed by interacting with it. In the above example, moving slider_float1 slider to 30.55 sets its’ value to 30.55.

We can set the position of the slider by changing items’ value at runtime using set_value.

import dearpygui.dearpygui as dpg

dpg.create_context()

with dpg.window(width=300):
    # Creating a slider_int widget and setting the
    # default value to 15.
    dpg.add_slider_int(default_value=15, tag="slider_int")

# On second thought, we're gonna set the value to 40
# instead - for no reason in particular...
dpg.set_value("slider_int", 40)

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

Note

The values’ type depends on the widget. (ex.) input_int default value needs to be an integer.

See also

For more information on item values Values

3.6. Using Item Handlers

UI item handlers listen for events (changes in state) related to a UI item then submit a callback.

import dearpygui.dearpygui as dpg

dpg.create_context()

def change_text(sender, app_data):
    dpg.set_value("text item", f"Mouse Button ID: {app_data}")

with dpg.window(width=500, height=300):
    dpg.add_text("Click me with any mouse button", tag="text item")
    with dpg.item_handler_registry(tag="widget handler") as handler:
        dpg.add_item_clicked_handler(callback=change_text)
    dpg.bind_item_handler_registry("text item", "widget handler")

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

See also

For more information on item handlers IO, Handlers, State Polling