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

.. seealso::
    | For more information on containers:
    | :doc:`../documentation/item-creation`
    | :doc:`../documentation/container-context-manager`
    | :doc:`../documentation/container-slots`
    | :doc:`../documentation/container-stack`

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`