Qt Designer Guide

Using Custom Widgets

How to add a custom widget to .ui files through Qt Designer:

1. Add the base class of your custom widget to the layout in the place you want your custom widget to appear. (In many cases this will be plain "Widget" that can be found under the "Containers" header in the "Widget Box" pane.)
2. Once you are satisfied with its placement in the layout, left click the widget and select "Promote to Custom Widget." This will cause a window to appear.
3. Under "New Promoted Class," enter the base class of the custom widget and the name of the widget. (This will be used to automatically generate import statements and declarations in your Python files to the capitalisation needs to match)
4. (This is the weird part). For the "Header file" box, pretend that your Python file is actually a C header file and give the directory of your widget in the form of location/of/custom/widget.h with location being the root directory of the Python application. (This is also used for import statements so the capitalisation needs to match here as well).
5. Press "Add." Now under "Class" in the "Object Inspector" pane (top-right of the main window) you should see your custom widget listed.
6. Once this is complete, generating a Python file from your .ui file should result in the custom widget being used automatically.

Note: This seems to assume that the widget will need parent as an argument. To work around this you can make your custom widget take parent as an argument and do nothing with it.