QUiLoader Class | Qt UI Tools | Qt 6.11.2
Description: Loads and instantiates Qt Widgets Designer forms at runtime.

- Qt 6.11
- Qt UI Tools
- C++ Classes
- QUiLoader
- Qt 6.11.2 Reference Documentation

# QUiLoader Class

Loads and instantiates Qt Widgets Designer forms at runtime. More...

Header: | `#include <QUiLoader>`
CMake: | `find_package(Qt6 REQUIRED COMPONENTS UiTools)` `target_link_libraries(mytarget PRIVATE Qt6::UiTools)`
qmake: | `QT += uitools`
Inherits: | QObject

- List of all members, including inherited members

## Public Functions

| QUiLoader(QObject *parent = nullptr)
virtual | ~QUiLoader() override
void | addPluginPath(const QString &path)
QStringList | availableLayouts() const
QStringList | availableWidgets() const
void | clearPluginPaths()
virtual QAction * | createAction(QObject *parent = nullptr, const QString &name = QString())
virtual QActionGroup * | createActionGroup(QObject *parent = nullptr, const QString &name = QString())
virtual QLayout * | createLayout(const QString &className, QObject *parent = nullptr, const QString &name = QString())
virtual QWidget * | createWidget(const QString &className, QWidget *parent = nullptr, const QString &name = QString())
QString | errorString() const
bool | isLanguageChangeEnabled() const
QWidget * | load(QIODevice *device, QWidget *parentWidget = nullptr)
QStringList | pluginPaths() const
void | setLanguageChangeEnabled(bool enabled)
void | setWorkingDirectory(const QDir &dir)
QDir | workingDirectory() const

## Detailed Description

Use QUiLoader to dynamically create QWidget-based user interfaces based on the information stored in UI files (created with Qt Widgets Designer).

The load() function reads the content of a UI file, instantiates the widgets described in the file, and returns a pointer to the top-level QWidget. This widget can then be shown:

     MyWidget::MyWidget(QWidget *parent)
         : QWidget(parent)
     {
         QFile file(":/forms/myform.ui");
         if (!file.open(QFile::ReadOnly))
             qFatal("Cannot open resource file");

         QUiLoader loader;
         QWidget *myWidget = loader.load(&file, this);

         QVBoxLayout *layout = new QVBoxLayout;
         layout->addWidget(myWidget);
         setLayout(layout);
     }

If the instantiation fails, the function returns a `nullptr`; use the errorString() function to retrieve a human-readable description of the error that occurred.

#### Loading forms with custom widgets

If the UI file contains custom widgets implemented in a Qt Widgets Designer plugin, loading will fail by default. To work around this, you can subclass QUiLoader and override the createWidget() function. If this is not possible, you can also let the module load Qt Widgets Designer plugins by adding their locations via addPluginPath() or the `QT_PLUGIN_PATH` environment variable. See the Creating Custom Widgets for Qt Widgets Designer page for more details.

#### Loading a particular widget from a UI file

You can load a specific widget from a UI file, instead of a complete UI file. Use the availableWidgets() function to retrieve the names of the available widgets, and the createWidget() function to instantiate a specific one. For example:

     QWidget *loadCustomWidget(const QString &className, QWidget *parent)
     {
         QUiLoader loader;
         QStringList availableWidgets = loader.availableWidgets();

         if (!availableWidgets.contains(className)) {
             qWarning() << "Cannot create widget" << className;
             return nullptr;
         }

         return loader.createWidget(className, parent);
     }

#### Customizing the widget creation

The createAction(), createActionGroup(), createLayout(), and createWidget() functions are used internally by the QUiLoader class whenever it has to create an action, action group, layout, or widget respectively. You can subclass QUiLoader and reimplement these functions to customize the UI creation workflow. For example, you might want to have a list of the actions created when loading a form or creating a custom widget.

#### Example

For a complete example using the QUiLoader class, see the Calculator Builder.

See also Qt UI Tools and QFormBuilder.

## Member Function Documentation

### `[explicit]` QUiLoader::QUiLoader(QObject *parent = nullptr)

Creates a form loader with the given parent.

### `[override virtual noexcept]` QUiLoader::~QUiLoader()

Destroys the loader.

### void QUiLoader::addPluginPath(const QString &path)

Adds the given path to the list of paths in which the loader will search when locating plugins.

Warning: Only set paths that you trust. Allowing untrusted users to create or add content in a specified path may lead to security vulnerabilities.

See also pluginPaths() and clearPluginPaths().

### QStringList QUiLoader::availableLayouts() const

Returns a list of all available layouts that can be built using the createLayout() function.

See also createLayout().

### QStringList QUiLoader::availableWidgets() const

Returns a list of all available widgets that can be built using the createWidget() function, that is, all the widgets specified within the given plugin paths.

See also pluginPaths() and createWidget().

### void QUiLoader::clearPluginPaths()

Clears the list of paths in which the loader will search when locating plugins.

See also addPluginPath() and pluginPaths().

### `[virtual]` QAction *QUiLoader::createAction(QObject *parent = nullptr, const QString &name = QString())

Creates a new action with the given parent and name.

The function is also used internally by the QUiLoader class whenever it creates an action. Therefore, you can subclass QUiLoader and reimplement this function to intervene in the process of constructing a user interface or widget. However, in your implementation, ensure that you call QUiLoader's version first.

See also createActionGroup(), createWidget(), and load().

### `[virtual]` QActionGroup *QUiLoader::createActionGroup(QObject *parent = nullptr, const QString &name = QString())

Creates a new action group with the given parent and name.

The function is also used internally by the QUiLoader class whenever it creates an action group. Therefore, you can subclass QUiLoader and reimplement this function to intervene in the process of constructing a user interface or widget. However, in your implementation, ensure that you call QUiLoader's version first.

See also createAction(), createWidget(), and load().

### `[virtual]` QLayout *QUiLoader::createLayout(const QString &className, QObject *parent = nullptr, const QString &name = QString())

Creates a new layout with the given parent and name using the class specified by className.

The function is also used internally by the QUiLoader class whenever it creates a layout. Therefore, you can subclass QUiLoader and reimplement this function to intervene in the process of constructing a user interface or widget. However, in your implementation, ensure that you call QUiLoader's version first.

See also createWidget() and load().

### `[virtual]` QWidget *QUiLoader::createWidget(const QString &className, QWidget *parent = nullptr, const QString &name = QString())

Creates a new widget with the given parent and name using the class specified by className. You can use this function to create any of the widgets returned by the availableWidgets() function.

The function is also used internally by the QUiLoader class whenever it creates a widget. Therefore, you can subclass QUiLoader and reimplement this function to intervene in the process of constructing a user interface or widget. However, in your implementation, ensure that you call QUiLoader's version first.

See also availableWidgets() and load().

### QString QUiLoader::errorString() const

Returns a human-readable description of the last error that occurred in load().

See also load().

### bool QUiLoader::isLanguageChangeEnabled() const

Returns `true` if dynamic retranslation on language change is enabled; returns `false` otherwise.

The default is `false`.

See also setLanguageChangeEnabled().

### QWidget *QUiLoader::load(QIODevice *device, QWidget *parentWidget = nullptr)

Instantiates a form from the given device. Returns a new QWidget with the given parentWidget if successful. Returns `nullptr` otherwise.

Warning: Only load forms from trusted sources, like the Qt resource system. Loading `.ui` files from untrusted sources can lead to security threats in your application, such as denial of service attacks, UI deception, or the loading of unexpected plugins.

See also createWidget() and errorString().

### QStringList QUiLoader::pluginPaths() const

Returns a list naming the paths in which the loader will search when locating custom widget plugins.

See also addPluginPath() and clearPluginPaths().

### void QUiLoader::setLanguageChangeEnabled(bool enabled)

If enabled is true, user interfaces loaded by this loader will automatically retranslate themselves upon receiving a language change event. Otherwise, the user interfaces will not be retranslated.

See also isLanguageChangeEnabled().

### void QUiLoader::setWorkingDirectory(const QDir &dir)

Sets the working directory of the loader to dir. The loader will look for other resources, such as icons and resource files, in paths relative to this directory.

Warning: Only set a directory that you trust. Allowing untrusted users to create or add content in the working directory may lead to security vulnerabilities.

See also workingDirectory().

### QDir QUiLoader::workingDirectory() const

Returns the working directory of the loader.

See also setWorkingDirectory().