Item Usage

.. meta:: :description lang=en: General overview of DPG items.

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.

.. code-block:: python

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 :doc:../documentation/item-creation

.. seealso:: | For more information on the creating items: | :doc:../documentation/item-creation | :doc:../documentation/item-id-system

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.

.. code-block:: python

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

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

:py:func:get_item_configuration <dearpygui.dearpygui.get_item_configuration> keywords that control its appearance and behavior (label, callback, width, height)

:py:func:get_item_state <dearpygui.dearpygui.get_item_state> keywords that reflect its interaction (visible, hovered, clicked, etc)

:py:func:get_item_info <dearpygui.dearpygui.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:
| :py:func:`get_item_label <dearpygui.dearpygui.get_item_label>`
| :py:func:`is_item_hovered <dearpygui.dearpygui.is_item_hovered>`
| :py:func:`get_item_children <dearpygui.dearpygui.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:

.. code-block:: python

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

.. seealso:: | For more information on the these topics: | :doc:../documentation/item-configuration | :doc:../documentation/io-handlers-state

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

.. code-block:: python

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

.. seealso:: For more information on the item callbacks :doc:../documentation/item-callbacks

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

.. code-block:: python

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

.. image:: https://raw.githubusercontent.com/Atlamillias/DearPyGui-Stuff/main/wiki%20images/dpg_using_widgets_ex1.png

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

.. code-block:: python

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

.. image:: https://raw.githubusercontent.com/Atlamillias/DearPyGui-Stuff/main/wiki%20images/dpg_using_widgets_ex2.png

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

.. seealso:: For more information on item values :doc:../documentation/item-value

Using Item Handlers

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

.. code-block:: python

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

.. seealso:: For more information on item handlers :doc:../documentation/io-handlers-state