Widget Objects

The wrapper object system used to provide an object-oriented API for DearPyGui.

Summary

Widget	This is the abstract base class for all GUI item wrapper objects.
ContainerWidgetMx	Mixin for widgets that use the DPG parent stack.
ContainerFinalizedError	Raised when a ContainerWidgetMx is used after being finalized.
ItemWidgetMx	Mixin class for all widgets that can belong to containers.
DefaultWidget	Fallback type for getting a widget that does not have a wrapper class.
ConfigProperty	Descriptor used to get or set an item’s configuration.

Widget

class dearpygui_obj.wrapper.widget.Widget(*, id: Optional[int] = 0, callback: PyGuiCallback = None, **kwargs: Any)

Bases: abc.ABC

This is the abstract base class for all GUI item wrapper objects.

Keyword arguments passed to __init__ will be used to set the initial values of any config properties that belong to the class. Any left over keywords will be passed to the __setup_add_widget__() method to be given to DPG.

You can find out what config properties there are using the get_config_properties() method.

It’s important that any subclasses can be instantiated with only the name_id argument being passed to __init__. This allows get_item_by_id() to work.

Parameters

• name_id – optionally specify the unique widget ID.

• callback – provide a callback that will be set with set_callback().

ID and Existence

id	The unique name used by DearPyGui to reference this GUI item.
is_valid	This property is False if the GUI item has been deleted.
delete	Delete the item, this will invalidate the item and all its children.

Callbacks

callback	A decorator that sets the item’s callback, and optionally, the callback data.
get_callback	Get the callback used by DearPyGui.
set_callback	Set the callback used by DearPyGui.
callback_data	Get or set the callback data.

Other Properties and Status

show	Enable/disable rendering of the item.
width	Read or modify the ‘width’ config property.
height	Read or modify the ‘height’ config property.
size	The item’s current size as (width, height).
max_size	An item’s maximum allowable size as (width, height).
min_size	An item’s minimum allowable size as (width, height).
tooltip	The content of the tooltip that is shown when the widget is hovered.
enabled	If not enabled, display greyed out text and disable interaction.
is_visible	Checks if an item is visible on screen.
is_hovered	Checks if an item is hovered.
is_focused	Checks if an item is focused.

abstract __setup_add_widget__(dpg_args: MutableMapping[str, Any]) → int

This should create the widget using DearPyGui’s add_*() functions and return the widget ID.

__setup_preexisting__() → None

This can be overriden by subclasses to setup an object wrapper that has been created for a pre-existing GUI item.

Since we want to avoid duplicating state that already exists in DearPyGui, this method should rarely be needed.

classmethod get_config_properties() → Sequence[str]

Get the names of configuration properties as a list.

This can be useful to check which attributes are configuration properties and therefore can be given as keywords to __init__.

__eq__(other: Any) → bool

Two wrapper objects are considered equal if their IDs are equal.

property id: int

The unique name used by DearPyGui to reference this GUI item.

property is_valid: bool

This property is False if the GUI item has been deleted.

delete() → None

Delete the item, this will invalidate the item and all its children.

get_config() → ItemConfigData

set_config(**config: Any) → None

set_callback(callback: PyGuiCallback) → None

Set the callback used by DearPyGui.

get_callback() → PyGuiCallback

Get the callback used by DearPyGui.

property callback_data: Any

Get or set the callback data.

callback(_cb: PyGuiCallback = None, *, data: Optional[Any] = None) → Callable

A decorator that sets the item’s callback, and optionally, the callback data.

For example:

with Window('Example Window'):
    button = Button('Callback Button')

    # don't need callback data!
    @button.callback
    def callback(sender):
        ...

    # if data is a callable, it is invoked each time the callback fires
    # and the result is supplied to the callback.
    @button.callback(data='this could also be a callable')
    def callback(sender, data):
        ...

is_container() → bool

Checks if DPG considers this item to be a container.

tooltip: str

The content of the tooltip that is shown when the widget is hovered. To remove the tooltip, assign an empty string.

enabled: bool

If not enabled, display greyed out text and disable interaction.

property active: bool

Get whether the item is being interacted with.

show: bool

Enable/disable rendering of the item.

width: int

Read or modify the ‘width’ config property.

height: int

Read or modify the ‘height’ config property.

size: Tuple[float, float]

The item’s current size as (width, height).

property max_size: Tuple[float, float]

An item’s maximum allowable size as (width, height).

property min_size: Tuple[float, float]

An item’s minimum allowable size as (width, height).

is_visible() → bool

Checks if an item is visible on screen.

is_hovered() → bool

Checks if an item is hovered.

is_focused() → bool

Checks if an item is focused.

was_clicked() → bool

Checks if an item was just clicked (this frame?)

was_activated() → bool

Checks if an item just became active (this frame?)

was_deactivated() → bool

Checks if an item just stopped being active (this frame?).

was_edited() → bool

Checks if an item was just edited (this frame?)

was_deactivated_after_edit() → bool

Checks if an item was edited and deactivated (this frame?).

class dearpygui_obj.wrapper.widget.DefaultWidget(*, id: Optional[int] = 0, callback: PyGuiCallback = None, **kwargs: Any)

Bases: dearpygui_obj.wrapper.widget.Widget, dearpygui_obj.wrapper.widget.ItemWidgetMx

Fallback type for getting a widget that does not have a wrapper class.

When get_item_by_id() is called to retrieve an item whose widget type does not have a wrapper object class associated with it, an instance of this type is created as a fallback.

ContainerWidgetMx

class dearpygui_obj.wrapper.widget.ContainerWidgetMx(*args, **kwds)

Bases: abc.ABC, Generic[dearpygui_obj.wrapper.widget._TSelf]

Mixin for widgets that use the DPG parent stack.

Typically when widgets are instantiated they are added to a container based on context. This behavior is a result of DPG’s parent stack and it makes it simple to create declarative-style GUIs.

After a container is used as a context manager, it is popped from DPG’s parent stack and cannot be re-added. Attempting to use it as a context manager for a second time will raise a ContainerFinalizedError. This can also be checked using the finalized property.

Once a container is finalized, additional children can still be added using the add_child() method.

abstract property id: str

__enter__() → dearpygui_obj.wrapper.widget._TSelf

__exit__(exc_type, exc_val, exc_tb) → None

property finalized: bool

Whether this container has already been used as a context manager.

iter_children() → Iterable[ItemWidget]

Iterates all of the item’s children.

add_child(child: ItemWidget) → None

Move an ItemWidget into this container.

Equivalent to calling ItemWidget.set_parent() on the child.

exception dearpygui_obj.wrapper.widget.ContainerFinalizedError

Bases: Exception

Raised when a ContainerWidgetMx is used after being finalized.

ItemWidgetMx

class dearpygui_obj.wrapper.widget.ItemWidgetMx(*args, parent: str, before: str, **kwargs)

Bases: abc.ABC

Mixin class for all widgets that can belong to containers.

This mixin class is used to mark Widget subtypes that can belong to a container (currently this includes all DPG widgets except for Window). It provides its subtypes with methods to move widgets between different containers (re-parent) or within their own container.

Typically when widgets are instantiated they are added to a container based on context. This behavior is a result of DPG’s parent stack and it makes it simple to create declarative-style GUIs.

If you need to add a new widget directly to a specific parent container, or just prefer a more OOP-style of specifying a widget’s parent, you can use the add_to() and add_before() constructor methods.

abstract property id: str

get_parent() → Optional[ContainerWidget]

Get this item’s parent.

set_parent(parent: ContainerWidget) → None

Re-parent the item, moving it.

Equivalent to calling ContainerWidgetMx.add_child() on the parent.

move_up() → None

Move the item up within its parent, if possible.

move_down() → None

Move the item down within its parent, if possible.

move_item_before(other: ItemWidget) → None

Attempt to place the item before another item, re-parenting it if necessary.

classmethod add_to(parent: Widget, *args: Any, **kwargs: Any) → Any

Create a widget and add it to the given parent instead of using context.

Returns

the newly created widget.

classmethod insert_before(sibling: ItemWidget, *args: Any, **kwargs: Any) → Any

Create a widget and insert it before the given sibling widget.

Returns

the newly created widget.

ValueWidgetMx

class dearpygui_obj.wrapper.widget.ValueWidgetMx(*args, **kwds)

Bases: abc.ABC, Generic[dearpygui_obj.wrapper.widget._TValue]

Mixin for all widgets that use the DPG value system.

The use of the value property depends on the specific kind of widget.

ValueWidgets can be linked together or to a DataValue by setting the data_source config property.

abstract property id: str

abstract get_config() → ItemConfigData

data_source: dearpygui_obj.DataValue

Get or set the data source.

When retrieved, a DataValue referencing the data source will be produced.

If a widget object or a DataValue is assigned as the data source, this widget will become linked to the provided source. Otherwise, if None is assigned, this widget will have its own value.

property value: dearpygui_obj.wrapper.widget._TValue

Get or set the widget’s value.

ConfigProperty

class dearpygui_obj.wrapper.widget.ConfigProperty(key: Optional[str] = None, *, no_init: bool = False, doc: str = '')

Bases: object

Descriptor used to get or set an item’s configuration.

__get__(instance: Optional[Widget], owner: Type[Widget]) → Any

__set__(instance: Widget, value: Any) → None

__call__(fvalue: GetValueFunc)

Allows the ConfigProperty itself to be used as a decorator equivalent to getvalue.

getvalue(fvalue: GetValueFunc)

getconfig(fconfig: GetConfigFunc)

fvalue(instance: Widget) → Any

fconfig(instance: Widget, value: Any) → ItemConfigData