0
# UIC Module
1
2
UI file loading and compilation functionality that provides cross-binding compatibility for working with Qt Designer UI files. This module handles the differences between PyQt and PySide approaches to loading UI files at runtime.
3
4
## Capabilities
5
6
### UI File Loading
7
8
Dynamically load UI files created with Qt Designer into Python widgets at runtime.
9
10
```python { .api }
11
def loadUi(
12
uifile: str,
13
baseinstance=None,
14
workingDirectory: str | None = None
15
):
16
"""
17
Dynamically load a user interface from the given uifile.
18
19
Args:
20
uifile: String containing a file name of the UI file to load
21
baseinstance: If None, creates new instance of top-level widget.
22
Otherwise, creates UI within the given baseinstance
23
workingDirectory: Working directory for relative paths
24
25
Returns:
26
baseinstance if provided, otherwise newly created widget instance
27
"""
28
```
29
30
Usage example:
31
32
```python
33
from qtpy.uic import loadUi
34
from qtpy.QtWidgets import QApplication, QMainWindow
35
36
app = QApplication([])
37
38
# Load UI into a new widget instance
39
widget = loadUi("mainwindow.ui")
40
41
# Or load UI into an existing widget
42
class MainWindow(QMainWindow):
43
def __init__(self):
44
super().__init__()
45
loadUi("mainwindow.ui", self)
46
47
window = MainWindow()
48
window.show()
49
app.exec()
50
```
51
52
### UI Type Loading
53
54
Generate form classes from UI files for subclassing and advanced usage patterns.
55
56
```python { .api }
57
def loadUiType(uifile: str, from_imports: bool = False):
58
"""
59
Load a .ui file and return the generated form class and Qt base class.
60
61
Available for PySide2 and PySide6. For PyQt5 and PyQt6, this function
62
is provided directly by the respective uic modules.
63
64
Args:
65
uifile: Path to the UI file to load
66
from_imports: Whether to use relative imports in generated code
67
68
Returns:
69
tuple[type, type]: (form_class, base_class) tuple where form_class
70
contains the UI setup methods and base_class is
71
the Qt widget class (QMainWindow, QDialog, etc.)
72
"""
73
```
74
75
Usage example:
76
77
```python
78
from qtpy.uic import loadUiType
79
from qtpy.QtWidgets import QApplication
80
81
# Generate classes from UI file
82
Ui_MainWindow, QtBaseClass = loadUiType("mainwindow.ui")
83
84
class MainWindow(QtBaseClass):
85
def __init__(self):
86
super().__init__()
87
self.ui = Ui_MainWindow()
88
self.ui.setupUi(self)
89
90
# Connect signals
91
self.ui.pushButton.clicked.connect(self.on_button_clicked)
92
93
def on_button_clicked(self):
94
print("Button clicked!")
95
96
app = QApplication([])
97
window = MainWindow()
98
window.show()
99
app.exec()
100
```
101
102
### Custom Widget Support
103
104
Support for custom widgets defined in UI files with automatic import and registration.
105
106
```python { .api }
107
class UiLoader:
108
"""
109
Subclass of QUiLoader to create user interface in a base instance.
110
111
Unlike QUiLoader itself, this class creates the user interface in an
112
existing instance of the top-level class if needed, mimicking the
113
behavior of PyQt4.uic.loadUi.
114
"""
115
116
def __init__(self, baseinstance, customWidgets: dict[str, type] | None = None):
117
"""
118
Create a loader for the given baseinstance.
119
120
Args:
121
baseinstance: Instance of the top-level class to load UI into
122
customWidgets: Dictionary mapping class names to class objects
123
for custom widgets
124
"""
125
126
def createWidget(self, class_name: str, parent=None, name: str = ""):
127
"""
128
Function called for each widget defined in UI file.
129
130
Args:
131
class_name: Name of the widget class to create
132
parent: Parent widget
133
name: Object name for the widget
134
135
Returns:
136
Created widget instance
137
"""
138
```
139
140
### Exception Classes
141
142
Exceptions specific to UIC module functionality.
143
144
```python { .api }
145
class NoCustomWidget(Exception):
146
"""
147
Raised when a custom widget class cannot be found during UI loading.
148
149
This exception is raised by UiLoader when a UI file references a custom
150
widget that is not available in the customWidgets dictionary.
151
"""
152
```
153
154
### Cross-Binding Compatibility
155
156
The UIC module automatically handles differences between Qt bindings:
157
158
**PyQt5/PyQt6:**
159
- Direct import from `PyQt5.uic.*` or `PyQt6.uic.*`
160
- Native `loadUi` and `loadUiType` support
161
162
**PySide2/PySide6:**
163
- Custom `loadUi` implementation using `QUiLoader`
164
- Custom `loadUiType` implementation using `compileUi` (PySide2) or native support (PySide6)
165
- Automatic custom widget discovery and loading
166
- Workarounds for PySide-specific issues
167
168
## Import Patterns
169
170
```python
171
# Import UIC functions
172
from qtpy.uic import loadUi, loadUiType
173
174
# For advanced usage, access the UiLoader class
175
from qtpy.uic import UiLoader
176
177
# All functions work identically across PyQt5/6 and PySide2/6
178
```
179
180
## Error Handling
181
182
```python
183
from qtpy.uic import loadUi, NoCustomWidget
184
185
try:
186
widget = loadUi("form_with_custom_widgets.ui")
187
except NoCustomWidget as e:
188
print(f"Custom widget not found: {e}")
189
# Handle missing custom widget
190
```
191
192
## UI File Workflow
193
194
1. **Design**: Create UI files using Qt Designer
195
2. **Load**: Use `loadUi()` for runtime loading or `loadUiType()` for class generation
196
3. **Connect**: Connect signals and implement business logic
197
4. **Deploy**: Ship UI files alongside Python code
198
199
This approach keeps UI design separate from code and allows for easy UI updates without code changes.