hoffstadt
dearpygui.dearpygui.window tag parameter must be > 0
The current documentation for window has the following for the tag parameter:
tag (Union[int, str], optional) – Unique id used to programmatically refer to the item.If label is unused this will be the label.
https://dearpygui.readthedocs.io/en/latest/reference/dearpygui.html#dearpygui.dearpygui.window
My Improvement
tag (Union[int, str], optional) – Unique id used to programmatically refer to the item. If label is unused this will be the label. If using an integer, it must be greater than 0.
Necessary Assets
The following code works as expected.
import dearpygui.dearpygui as dpg
dpg.create_context()
with dpg.window(tag=1):
dpg.add_text("Hello, world")
dpg.add_button(label="Save")
dpg.add_input_text(label="string", default_value="Quick brown fox")
dpg.add_slider_float(label="float", default_value=0.273, max_value=1)
dpg.create_viewport(title='Custom Title', width=600, height=200)
dpg.setup_dearpygui()
dpg.show_viewport()
dpg.set_primary_window(1, True)
dpg.start_dearpygui()
dpg.destroy_context()
Setting tag to -1 will result in the following error:
OverflowError: can't convert negative int to unsigned
The above exception was the direct cause of the following exception:
Traceback (most recent call last):
File "/home/alex/py313/lib/python3.13/site-packages/dearpygui/dearpygui.py", line 2969, in window
widget = internal_dpg.add_window(label=label, user_data=user_data, use_internal_label=use_internal_label, tag=tag, width=width, height=height, indent=indent, show=show, pos=pos, delay_search=delay_search, min_size=min_size, max_size=max_size, menubar=menubar, collapsed=collapsed, autosize=autosize, no_resize=no_resize, unsaved_document=unsaved_document, no_title_bar=no_title_bar, no_move=no_move, no_scrollbar=no_scrollbar, no_collapse=no_collapse, horizontal_scrollbar=horizontal_scrollbar, no_focus_on_appearing=no_focus_on_appearing, no_bring_to_front_on_focus=no_bring_to_front_on_focus, no_close=no_close, no_background=no_background, modal=modal, popup=popup, no_saved_settings=no_saved_settings, no_open_over_existing_popup=no_open_over_existing_popup, no_scroll_with_mouse=no_scroll_with_mouse, on_close=on_close, **kwargs)
SystemError: <built-in function add_window> returned a result with an exception set
During handling of the above exception, another exception occurred:
Exception: Error: [1009] Message: No container to pop.
The above exception was the direct cause of the following exception:
Traceback (most recent call last):
File "/home/alex/source/gui-test/test.py", line 5, in <module>
with dpg.window(tag=-1):
~~~~~~~~~~^^^^^^^^
File "/usr/lib/python3.13/contextlib.py", line 141, in __enter__
return next(self.gen)
File "/home/alex/py313/lib/python3.13/site-packages/dearpygui/dearpygui.py", line 2973, in window
internal_dpg.pop_container_stack()
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~^^
SystemError: <built-in function pop_container_stack> returned a result with an exception set
Setting tag to 0 will result in the following error:
Exception:
Error: [1005]
Command: set_primary_window
Item: 0
Label: Not found
Item Type: Unknown
Message: Item not found: 0
The above exception was the direct cause of the following exception:
Traceback (most recent call last):
File "/home/alex/source/gui-test/test.py", line 14, in <module>
dpg.set_primary_window(0, True)
~~~~~~~~~~~~~~~~~~~~~~^^^^^^^^^
File "/home/alex/py313/lib/python3.13/site-packages/dearpygui/dearpygui.py", line 9523, in set_primary_window
return internal_dpg.set_primary_window(window, value, **kwargs)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^
SystemError: <built-in function set_primary_window> returned a result with an exception set
The way documentation is generated for API functions, such a change will pop up in every description of the tag argument for every function. That's why I'd avoid a too wordy description in there. IMHO it would be better to improve the following doc article:
https://dearpygui.readthedocs.io/en/latest/documentation/item-id-system.html
Technically you should not be passing "tags" -1, 0, 1, or any other integer your application generated, since it will eventually conflict with UUIDs auto-generated by DPG. If you need a numeric ID, use dpg.generate_uuid(), or better yet, just don't pass tag and DPG will return you a UUID - like this:
with dpg.window() as wnd:
...
it will eventually conflict with UUIDs auto-generated by DPG
Is this a legitimate concern?
Not sure that I follow your question... If you mean whether this can become a problem, then yes - here's a simple demonstration:
with dpg.window(label="Window"):
dpg.add_button(label="Button 1", tag=23)
dpg.add_button(label="Button 2", callback=lambda: print("Clicked!"))
Here, the tag on the 1st button matches the automatic UUID on the 2nd, i.e. both receive a UUID of 23. When you click Button 2, you'd expect a message to be printed, but nothing happens. If you remove tag=23, the callback on Button 2 starts working as expected.
That answers my question.
For context, whenever I'm told there is a UUID conflict or collision at work this tends to fall into the "statistical improbability" category and not "deterministically and easily demonstrated".
Getting back to the issue at hand. I agree that my suggested documentation update is a bad idea given that only integers generated by generate_uuid() should be assigned to the tag parameter.
In that case maybe adding a clarification to the effect of:
"To avoid collisions with automatically generated tags and otherwise unexpected behaviors, tags should only be generated using the dearpygui.dearpygui.generate_uuid() function"
To the page you suggested would be beneficial
adding a clarification to the effect of...
Yep, I agree, except that we typically use dpg instead of dearpygui.dearpygui. I myself don't have time for doc updates at the moment (I'm even not sure what a doc update involves in terms of build/publishing); feel free to push a PR if you feel comfortable with making such changes. Or just leave the ticket open so that eventually somebody picks it up.