QDesignerCustomWidgetInterface Class
La clase `QDesignerCustomWidgetInterface` permite a ` Qt Widgets Designer ` acceder a widgets personalizados y crearlos. Más información...
| Encabezado: | #include <QDesignerCustomWidgetInterface> |
| CMake: | find_package(Qt6 REQUIRED COMPONENTS Designer) target_link_libraries(mytarget PRIVATE Qt6::Designer) |
| qmake: | QT += designer |
Funciones públicas
| virtual | ~QDesignerCustomWidgetInterface() |
| virtual QString | codeTemplate() const |
| virtual QWidget * | createWidget(QWidget *parent) = 0 |
| virtual QString | domXml() const |
| virtual QString | group() const = 0 |
| virtual QIcon | icon() const = 0 |
| virtual QString | includeFile() const = 0 |
| virtual void | initialize(QDesignerFormEditorInterface *formEditor) |
| virtual bool | isContainer() const = 0 |
| virtual bool | isInitialized() const |
| virtual QString | name() const = 0 |
| virtual QString | toolTip() const = 0 |
| virtual QString | whatsThis() const = 0 |
Macros
Descripción detallada
QDesignerCustomWidgetInterface proporciona una interfaz para un widget personalizado. La clase contiene un conjunto de funciones que deben implementarse en una subclase para devolver información básica sobre el widget, como el nombre de su clase y el nombre de su archivo de cabecera. Se deben implementar otras funciones para inicializar el complemento cuando se cargue y para crear instancias del widget personalizado que pueda utilizar Qt Widgets Designer.
Al implementar un widget personalizado, debes crear una subclase de QDesignerCustomWidgetInterface para exponer tu widget a Qt Widgets Designer. Por ejemplo, esta es la declaración del complemento utilizado en el ejemplo «Complemento de widget personalizado», que permite que Qt Widgets Designer utilice un widget personalizado de reloj analógico:
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;
};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. Además, dado que estamos implementando una interfaz, debemos asegurarnos de que el sistema de metaobjetos tenga constancia de ella mediante la macro ` Q_INTERFACES()`. Esto permite que ` Qt Widgets Designer ` utilice la función ` qobject_cast()` para consultar las interfaces compatibles utilizando únicamente un puntero ` QObject `.
Una vez que Qt Widgets Designer carga un complemento de widget personalizado, llama a la función initialize() de la interfaz para que esta pueda configurar los recursos que pueda necesitar. Esta función se invoca con un parámetro QDesignerFormEditorInterface que proporciona al complemento una puerta de acceso a toda la API de Qt Widgets Designer.
Qt Widgets Designer Crea instancias del widget personalizado llamando a la función createWidget() del complemento con un widget padre adecuado. Los complementos deben crear y devolver una instancia de un widget personalizado con el widget padre especificado.
Exportación del complemento de widget personalizado a Qt Widgets Designer mediante la macro Q_PLUGIN_METADATA(). Por ejemplo, si una biblioteca llamada libcustomwidgetplugin.so (en Unix) o libcustomwidget.dll (en Windows) contiene una clase de widget llamada MyCustomWidget, podemos exportarla añadiendo la siguiente línea al archivo que contiene el encabezado del complemento:
Q_PLUGIN_METADATA(IID "org.qt-project.Qt.QDesignerCustomWidgetInterface")Esta macro garantiza que Qt Widgets Designer pueda acceder al widget personalizado y crearlo. Sin esta macro, Qt Widgets Designer no podría utilizarlo.
Al implementar un complemento de widget personalizado, se compila como una biblioteca independiente. Si deseas incluir varios complementos de widgets personalizados en la misma biblioteca, debes, además, crear una subclase de ` QDesignerCustomWidgetCollectionInterface`.
Advertencia: Si tu complemento de widget personalizado contiene propiedades de QVariant, ten en cuenta que solo se admiten los siguientes types:
- QVariant::ByteArray
- QVariant::Bool
- QVariant::Color
- QVariant::Cursor
- QVariant::Date
- QVariant::Fecha y hora
- QVariant::Double
- QVariant::Int
- QVariant::Punto
- QVariant::Rect
- QVariant::Size
- QVariant::PolíticaDeTamaño
- QVariant::String
- QVariant::Time
- QVariant::UInt
Para ver un ejemplo completo del uso de la clase `QDesignerCustomWidgetInterface`, consulta el ejemplo de widget personalizado. El ejemplo muestra cómo crear un complemento de widget personalizado para Qt Widgets Designer.
Véase también QDesignerCustomWidgetCollectionInterface y «Creación de widgets personalizados» en Qt Widgets Designer.
Documentación de las funciones de miembro
[virtual constexpr noexcept default] QDesignerCustomWidgetInterface::~QDesignerCustomWidgetInterface()
Elimina la interfaz del widget personalizado.
[virtual] QString QDesignerCustomWidgetInterface::codeTemplate() const
Esta función está reservada para su uso futuro por parte de Qt Widgets Designer.
[pure virtual] QWidget *QDesignerCustomWidgetInterface::createWidget(QWidget *parent)
Devuelve una nueva instancia del widget personalizado, con el ` parent` especificado.
[virtual] QString QDesignerCustomWidgetInterface::domXml() const
Devuelve el XML que se utiliza para describir las propiedades del widget personalizado a Qt Widgets Designer.
[pure virtual] QString QDesignerCustomWidgetInterface::group() const
Devuelve el nombre del grupo al que pertenece el widget personalizado.
[pure virtual] QIcon QDesignerCustomWidgetInterface::icon() const
Devuelve el icono que se utiliza para representar el widget personalizado en el panel de widgets de Qt Widgets Designer.
[pure virtual] QString QDesignerCustomWidgetInterface::includeFile() const
Devuelve la ruta al archivo de inclusión que utiliza uic al generar el código para el widget personalizado.
Para los widgets personalizados utilizados en C++ y Qt for Python, utiliza prefijos para especificar información específica del lenguaje en la cadena devuelta, tal y como se muestra a continuación:
"C++:myheader.h,Python:MyModule"[virtual] void QDesignerCustomWidgetInterface::initialize(QDesignerFormEditorInterface *formEditor)
Inicializa el widget para su uso con la interfaz formEditor especificada.
Véase también isInitialized().
[pure virtual] bool QDesignerCustomWidgetInterface::isContainer() const
Devuelve «true» si el widget personalizado está diseñado para utilizarse como contenedor; en caso contrario, devuelve «false».
La mayoría de los widgets personalizados no se utilizan para contener otros widgets, por lo que sus implementaciones de esta función devolverán «false», pero los contenedores personalizados devolverán «true» para garantizar que se comporten correctamente en Qt Widgets Designer.
[virtual] bool QDesignerCustomWidgetInterface::isInitialized() const
Devuelve «true» si el widget se ha inicializado; en caso contrario, devuelve «false».
Véase también initialize().
[pure virtual] QString QDesignerCustomWidgetInterface::name() const
Devuelve el nombre de la clase del widget personalizado proporcionado por la interfaz.
El nombre devuelto debe ser idéntico al nombre de la clase utilizada para el widget personalizado.
[pure virtual] QString QDesignerCustomWidgetInterface::toolTip() const
Devuelve una breve descripción del widget que puede utilizar Qt Widgets Designer en una ventana emergente.
[pure virtual] QString QDesignerCustomWidgetInterface::whatsThis() const
Devuelve una descripción del widget que Qt Widgets Designer puede utilizar en la sección «¿Qué es esto?» de la ayuda correspondiente al widget.
Documentación de macros
QDESIGNER_WIDGET_EXPORT
Esta macro se utiliza al definir widgets personalizados para garantizar que se exporten correctamente desde los complementos para su uso con Qt Widgets Designer.
En algunas plataformas, el sistema de compilación elimina de los complementos los símbolos que necesita Qt Widgets Designer para crear nuevos widgets, lo que los hace inutilizables. El uso de esta macro garantiza que los símbolos se conserven en esas plataformas y no tiene efectos secundarios en otras plataformas.
Por ejemplo, el ejemplo del complemento «Custom Widget Plugin » exporta una clase de widget personalizado con la siguiente declaración:
class QDESIGNER_WIDGET_EXPORT AnalogClock : public QWidget
{
Q_OBJECT
...
};Véase también «Creación de widgets personalizados para Qt Widgets Designer ».
© 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.