Complemento de widget personalizado
Creación de un plugin de widget personalizado para Qt Widgets Designer.

En este ejemplo, el widget personalizado utilizado se basa en el ejemplo del reloj analógico y no proporciona ninguna señal ni ranura personalizada.
Preparación
Para ofrecer un widget personalizado que se pueda utilizar con Qt Widgets Designer, debemos proporcionar una implementación autónoma y definir una interfaz de complemento. En este ejemplo, reutilizamos el ejemplo «Analog Clock» por comodidad.
Archivos del proyecto
CMake
Los archivos del proyecto deben indicar que se va a compilar un complemento vinculado a las bibliotecas de Qt Widgets Designer:
find_package(Qt6 REQUIRED COMPONENTS Core Gui UiPlugin Widgets)
qt_add_plugin(customwidgetplugin)
target_link_libraries(customwidgetplugin PUBLIC
Qt::Core
Qt::Gui
Qt::UiPlugin
Qt::Widgets
)La lista de bibliotecas de enlace especifica Qt::UiPlugin. Esto indica que el complemento utiliza únicamente las interfaces abstractas QDesignerCustomWidgetInterface y QDesignerCustomWidgetCollectionInterface y no tiene ningún enlace con las bibliotecas Qt Widgets Designer. Al acceder a otras interfaces de Qt Widgets Designer que sí tienen enlace, se debe utilizar en su lugar Designer; esto garantiza que el complemento se enlace dinámicamente con las bibliotecas Qt Widgets Designer y tenga una dependencia en tiempo de ejecución respecto a ellas.
El siguiente ejemplo muestra cómo añadir los archivos de cabecera y de código fuente del widget:
target_sources(customwidgetplugin PRIVATE
analogclock.cpp analogclock.h
customwidgetplugin.cpp customwidgetplugin.h
)Proporcionamos una implementación de la interfaz del complemento para que Qt Widgets Designer pueda utilizar el widget personalizado.
También es importante asegurarse de que el complemento se instale en una ubicación en la que Qt Widgets Designer realice la búsqueda. Para ello, especificamos una ruta de destino para el proyecto y la añadimos a la lista de elementos que se van a instalar:
set(INSTALL_EXAMPLEDIR "${QT6_INSTALL_PREFIX}/${QT6_INSTALL_PLUGINS}/designer")
install(TARGETS customwidgetplugin
RUNTIME DESTINATION "${INSTALL_EXAMPLEDIR}"
BUNDLE DESTINATION "${INSTALL_EXAMPLEDIR}"
LIBRARY DESTINATION "${INSTALL_EXAMPLEDIR}"
)El widget personalizado se crea como una biblioteca. Se instalará junto con los demás complementos de Qt Widgets Designer cuando se instale el proyecto (utilizando ninja install o un procedimiento de instalación equivalente).
Para obtener más información sobre los complementos, consulta la documentación «Cómo crear complementos de Qt ».
qmake
El siguiente ejemplo muestra cómo vincular un complemento a las bibliotecas de Qt Widgets Designer:
CONFIG += plugin
TEMPLATE = lib
QT += widgets uipluginLa variable « QT » contiene la palabra clave « uiplugin », que es el equivalente a la biblioteca « Qt::UiPlugin ».
El siguiente ejemplo muestra cómo añadir los archivos de cabecera y de código fuente del widget:
HEADERS = analogclock.h \
customwidgetplugin.h
SOURCES = analogclock.cpp \
customwidgetplugin.cpp
OTHER_FILES += analogclock.jsonEl siguiente ejemplo muestra cómo instalar un complemento en la ruta de complementos de Qt Widgets Designer:
TARGET = $$qtLibraryTarget($$TARGET)
target.path = $$[QT_INSTALL_PLUGINS]/designer
INSTALLS += targetDefinición e implementación de la clase AnalogClock
La clase AnalogClock se define e implementa exactamente de la misma manera que se describe en el ejemplo del reloj analógico. Dado que la clase es autónoma y no requiere ninguna configuración externa, puede utilizarse sin modificaciones como un widget personalizado en Qt Widgets Designer.
Definición de la clase AnalogClockPlugin
La clase ` AnalogClock ` se expone a Qt Widgets Designer a través de la clase ` AnalogClockPlugin `. Esta clase hereda tanto de ` QObject ` como de la clase ` QDesignerCustomWidgetInterface `, e implementa una interfaz definida por QDesignerCustomWidgetInterface.
Para garantizar que Qt reconozca el widget como un complemento, exporta la información relevante sobre el widget añadiendo la macro Q_PLUGIN_METADATA():
class AnalogClockPlugin : public QObject, public QDesignerCustomWidgetInterface
{
Q_OBJECT
Q_PLUGIN_METADATA(IID "org.qt-project.Qt.QDesignerCustomWidgetInterface")
Q_INTERFACES(QDesignerCustomWidgetInterface)
public:
explicit AnalogClockPlugin(QObject *parent = nullptr);
bool isContainer() const override;
bool isInitialized() const override;
QIcon icon() const override;
QString domXml() const override;
QString group() const override;
QString includeFile() const override;
QString name() const override;
QString toolTip() const override;
QString whatsThis() const override;
QWidget *createWidget(QWidget *parent) override;
void initialize(QDesignerFormEditorInterface *core) override;
private:
bool initialized = false;
};Las funciones proporcionan información sobre el widget que Qt Widgets Designer puede utilizar en el cuadro del widget. La variable miembro privada initialized se utiliza para registrar si el complemento ha sido inicializado mediante Qt Widgets Designer.
Ten en cuenta que la única parte de la definición de la clase que es específica de este widget personalizado en particular es el nombre de la clase.
Implementación de AnalogClockPlugin
El constructor de la clase simplemente llama al constructor de la clase base ` QObject ` y establece la variable ` initialized ` en ` false`.
Qt Widgets Designer Inicializará el complemento cuando sea necesario llamando a la función ` initialize() `:
void AnalogClockPlugin::initialize(QDesignerFormEditorInterface * /* core */)
{
if (initialized)
return;
initialized = true;
}En este ejemplo, se comprueba la variable privada ` initialized ` y solo se establece en ` true ` si el complemento aún no se ha inicializado. Aunque este complemento no requiere que se ejecute ningún código especial al inicializarse, podríamos incluir dicho código tras la comprobación de inicialización.
La función ` isInitialized() ` indica a ` Qt Widgets Designer ` si el complemento está listo para su uso:
bool AnalogClockPlugin::isInitialized() const
{
return initialized;
}La función ` createWidget() ` proporciona las instancias del widget personalizado. La implementación del reloj analógico es sencilla:
En este caso, el widget personalizado solo requiere que se especifique un ` parent `. Si es necesario proporcionar otros argumentos al widget, pueden introducirse aquí.
Las siguientes funciones proporcionan información que Qt Widgets Designer utiliza para representar el widget en el cuadro de widgets. La función name() devuelve el nombre de la clase que proporciona el widget personalizado:
QString AnalogClockPlugin::name() const
{
return u"AnalogClock"_s;
}La función ` group() ` se utiliza para describir el tipo de widget al que pertenece el widget personalizado:
QString AnalogClockPlugin::group() const
{
return u"Display Widgets [Examples]"_s;
}El complemento del widget se colocará en una sección identificada por el nombre de su grupo en el cuadro de widgets de Qt Widgets Designer. El icono utilizado para representar el widget en el cuadro de widgets es el devuelto por la función icon():
QIcon AnalogClockPlugin::icon() const
{
return {};
}En este caso, devolvemos un icono nulo para indicar que no disponemos de ningún icono que pueda utilizarse para representar el widget.
Se puede proporcionar una descripción emergente y una ayuda del tipo «¿Qué es esto?» para la entrada del widget personalizado en el panel de widgets. La función toolTip() debe devolver un mensaje breve que describa el widget:
QString AnalogClockPlugin::toolTip() const
{
return {};
}La función ` whatsThis() ` puede devolver una descripción más extensa:
QString AnalogClockPlugin::whatsThis() const
{
return {};
}La función ` isContainer() ` indica a ` Qt Widgets Designer ` si el widget debe utilizarse como contenedor de otros widgets. De no ser así, ` Qt Widgets Designer ` no permitirá al usuario colocar widgets en su interior.
bool AnalogClockPlugin::isContainer() const
{
return false;
}La mayoría de los widgets de Qt pueden contener widgets hijos, pero solo tiene sentido utilizar widgets contenedores específicos para este fin en Qt Widgets Designer. Al devolver false, indicamos que el widget personalizado no puede contener otros widgets; si devolviéramos true, Qt Widgets Designer permitiría colocar otros widgets dentro del reloj analógico y definir un diseño.
La función domXml() permite incluir la configuración predeterminada del widget en el formato XML estándar utilizado por Qt Widgets Designer. En este caso, solo especificamos la geometría del widget:
QString AnalogClockPlugin::domXml() const
{
return uR"(
<ui language="c++">
<widget class="AnalogClock" name="analogClock">
)"
R"(
<property name="geometry">
<rect>
<x>0</x>
<y>0</y>
<width>100</width>
<height>100</height>
</rect>
</property>
")
R"(
<property name="toolTip">
<string>The current time</string>
</property>
<property name="whatsThis">
<string>The analog clock widget displays the current time.</string>
</property>
</widget>
</ui>
)"_s;
}Si el widget proporciona una indicación de tamaño razonable, no es necesario definirlo aquí. Además, devolver una cadena vacía en lugar de un elemento ` <widget> ` indicará a Qt Widgets Designer que no instale el widget en el cuadro de widgets.
Para que las aplicaciones puedan utilizar el widget de reloj analógico, implementamos la función ` includeFile() ` para que devuelva el nombre del archivo de cabecera que contiene la definición de la clase del widget personalizado:
QString AnalogClockPlugin::includeFile() const
{
return u"analogclock.h"_s;
}© 2026 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.