IO, Handlers, State Polling

Handlers

Handlers are items that submit a callback when the specified state of an item changes.

Handlers can be activated or deactivated by showing or hiding them.

Handlers are required to be added to a handler registry.

Item Handlers

Item handlers listen for states related to a specific item.

Events:

Activated
Active
Clicked
Deactivated
Deactivated After Edited
Focus
Hover
Resize
Toggled
Visible

Item handlers are required to be added to a item handler registry.

Item handler registries can be bound to an item. They can be bound to multiple items to prevent having to duplicate handlers for every item.

.. 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}")

def visible_call(sender, app_data):
    print("I'm visible")

with dpg.item_handler_registry(tag="widget handler") as handler:
    dpg.add_item_clicked_handler(callback=change_text)
    dpg.add_item_visible_handler(callback=visible_call)

with dpg.window(width=500, height=300):
    dpg.add_text("Click me with any mouse button", tag="text item")
    dpg.add_text("Close window with arrow to change visible state printing to console", tag="text item 2")

# bind item handler registry to item
dpg.bind_item_handler_registry("text item", "widget handler")
dpg.bind_item_handler_registry("text item 2", "widget handler")

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/hoffstadt/DearPyGui/assets/examples_wiki_0.8.x/widget_handlers.gif

Global Handlers (IO Input)

Global handlers listen for actions not tied to a specific item:

Keys:

Down
Press
Release

Mouse:

Click
Double Click
Down
Drag
Move
Release
Wheel

Global handlers are required to be added to a handler registry.

Registries provide a grouping aspect to handlers allowing separation by input device. They also provide the ability to turn on and off the entire registry.

For example this can allow a mouse input registry or a keyboard input registry. Registries also give the ability to deactivate all their children handlers by simply hiding the registry.

.. 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: {app_data[0]}, Down Time: {app_data[1]} seconds")

with dpg.handler_registry():
    dpg.add_mouse_down_handler(callback=change_text)

with dpg.window(width=500, height=300):
    dpg.add_text("Press any mouse button", tag="text_item")

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/hoffstadt/DearPyGui/assets/examples_wiki_0.8.x/global_hanlders_global_registries.gif

Polling Item State

Polling item state is accessible through :py:func:get_item_state <dearpygui.dearpygui.get_item_state>. These can be very powerful when combined with handlers as shown below.

.. code-block:: python

import dearpygui.dearpygui as dpg

dpg.create_context()

def change_text(sender, app_data):
    if dpg.is_item_hovered("text item"):
        dpg.set_value("text item", f"Stop Hovering Me, Go away!!")
    else:
        dpg.set_value("text item", f"Hover Me!")

with dpg.handler_registry():
    dpg.add_mouse_move_handler(callback=change_text)

with dpg.window(width=500, height=300):
    dpg.add_text("Hover Me!", tag="text item")


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