En esta página

Creación de widgets personalizados para Qt Widgets Designer

Qt Widgets DesignerLa arquitectura basada en complementos permite editar widgets personalizados definidos por el usuario y de terceros igual que se hace con los Qt Widgets estándar. Todas las características del widget personalizado están disponibles en Qt Widgets Designer, incluidas las propiedades del widget, las señales y las ranuras. Dado que Qt Widgets Designer utiliza widgets reales durante el proceso de diseño de formularios, los widgets personalizados se mostrarán tal y como se ven en la vista previa.

El módulo QtDesigner te ofrece la posibilidad de crear widgets personalizados en Qt Widgets Designer.

Primeros pasos

Para integrar un widget personalizado en Qt Widgets Designer, necesitas una descripción adecuada para el widget y un archivo de proyecto apropiado.

Proporcionar una descripción de la interfaz

Para informar a Qt Widgets Designer sobre el tipo de widget que deseas proporcionar, crea una subclase de QDesignerCustomWidgetInterface que describa las distintas propiedades que expone tu widget. La mayoría de ellas se proporcionan mediante funciones que son puramente virtuales en la clase base, ya que solo el autor del complemento puede facilitar esta información.

FunciónDescripción del valor de retorno
name()El nombre de la clase que proporciona el widget.
group()El grupo del cuadro de widgets de Qt Widgets Designer al que pertenece el widget.
toolTip()Una breve descripción para ayudar a los usuarios a identificar el widget en Qt Widgets Designer.
whatsThis()Una descripción más detallada del widget para los usuarios de Qt Widgets Designer.
includeFile()El archivo de cabecera que debe incluirse en las aplicaciones que utilicen este widget. Esta información se almacena en los archivos de interfaz de usuario y será utilizada por uic para crear una instrucción #includes adecuada en el código que genera para el formulario que contiene el widget personalizado.
icon()Un icono que puede utilizarse para representar el widget en el cuadro de widgets de Qt Widgets Designer.
isContainer()Verdadero si el widget se utilizará para contener widgets hijos; falso en caso contrario.
createWidget()Un puntero de QWidget a una instancia del widget personalizado, construido con el padre proporcionado.

Nota: createWidget () es una función de fábrica encargada únicamente de crear el widget. Las propiedades del widget personalizado no estarán disponibles hasta que load() devuelva un resultado.

domXml()Una descripción de las propiedades del widget, como su nombre de objeto, indicación de tamaño y otras propiedades estándar de QWidget.
codeTemplate()Esta función está reservada para uso futuro por parte de Qt Widgets Designer.

También se pueden reimplementar otras dos funciones virtuales:

initialize()Configura extensiones y otras características para widgets personalizados. Las extensiones de contenedores personalizados (véase QDesignerContainerExtension) y las extensiones del menú de tareas (véase QDesignerTaskMenuExtension) deben configurarse en esta función.
isInitialized()Devuelve «true» si el widget se ha inicializado; en caso contrario, devuelve «false». Las reimplementaciones suelen comprobar si se ha llamado a la función initialize() y devuelven el resultado de esta comprobación.

Notas sobre la función domXml()

La función ` domXml() ` devuelve un fragmento de código de un archivo UI que utiliza la fábrica de widgets de Qt Widgets Designer para crear un widget personalizado y sus propiedades correspondientes.

Desde Qt 4.4, el cuadro de widgets de ` Qt Widgets Designer` permite utilizar un archivo UI completo para describir un widget personalizado. El archivo UI se puede cargar mediante la etiqueta ` <ui> `. Al especificar la etiqueta `<UI>`, se puede añadir el elemento `<CUSTOMWIDGET>`, que contiene información adicional sobre los widgets personalizados. La etiqueta ` <widget> ` es suficiente si no se requiere información adicional.

Si el widget personalizado no proporciona una indicación de tamaño razonable, es necesario especificar una geometría por defecto en la cadena devuelta por la función domXml() en tu subclase. Por ejemplo, el archivo AnalogClockPlugin proporcionado por el ejemplo «Custom Widget Plugin» define una geometría predeterminada del widget de la siguiente manera:

    ...
R"(
    <property name="geometry">
      <rect>
        <x>0</x>
        <y>0</y>
        <width>100</width>
        <height>100</height>
      </rect>
    </property>
")
    ...

Una característica adicional de la función ` domXml() ` es que, si devuelve una cadena vacía, el widget no se instalará en el cuadro de widgets de ` Qt Widgets Designer`. Sin embargo, otros widgets del formulario podrán seguir utilizándolo. Esta característica se utiliza para ocultar widgets que el usuario no debe crear explícitamente, pero que son necesarios para otros widgets.

Una especificación completa de un widget personalizado tiene el siguiente aspecto:

<ui language="c++"> displayname="MyWidget">
    <widget class="widgets::MyWidget" name="mywidget"/>
    <customwidgets>
        <customwidget>
            <class>widgets::MyWidget</class>
            <addpagemethod>addPage</addpagemethod>
            <propertyspecifications>
                <stringpropertyspecification name="fileName" notr="true" type="singleline"/>
                <stringpropertyspecification name="text" type="richtext"/>
                <tooltip name="text">Explanatory text to be shown in Property Editor</tooltip>
            </propertyspecifications>
        </customwidget>
    </customwidgets>
</ui>

Atributos de la etiqueta ` <ui> `:

AtributoPresenciaValoresComentario
languageopcional«c++», «jambi»Este atributo especifica el lenguaje para el que está destinado el widget personalizado. Su principal finalidad es evitar que los complementos de C++ aparezcan en Qt Jambi.
displaynameopcionalNombre de la claseEl valor de este atributo aparece en el cuadro «Widget» y puede utilizarse para eliminar los espacios de nombres.

La etiqueta « <addpagemethod> » indica a Qt Widgets Designer y a uic qué método debe utilizarse para añadir páginas a un widget contenedor. Esto se aplica a los widgets contenedores que requieren llamar a un método concreto para añadir un elemento hijo, en lugar de añadirlo pasando el elemento padre. En concreto, esto es relevante para los contenedores que no son una subclase de los contenedores proporcionados en Qt Widgets Designer, sino que se basan en el concepto de «Página actual». Además, es necesario proporcionar una extensión de contenedor para ellos.

El elemento « <propertyspecifications> » puede contener una lista de metainformación sobre propiedades.

La etiqueta <tooltip> puede utilizarse para especificar una información sobre herramientas que se mostrará en el Editor de propiedades al pasar el cursor por encima de la propiedad. El nombre de la propiedad se indica en el atributo name y el texto del elemento es la información sobre herramientas. Esta funcionalidad se añadió en Qt 5.6.

Para las propiedades de tipo cadena, se puede utilizar la etiqueta ` <stringpropertyspecification> `. Esta etiqueta tiene los siguientes atributos:

AtributoPresenciaValoresComentario
nameobligatorioNombre de la propiedad
typeobligatorioVéase la tabla siguienteEl valor del atributo determina cómo los gestionará el editor de propiedades.
notropcional«true», «false»Si el atributo es «true», el valor no debe traducirse.

Valores del atributo « type » de la propiedad «string»:

ValorTipo
"richtext"Texto enriquecido.
"multiline"Texto sin formato de varias líneas.
"singleline"Texto sin formato de una sola línea.
"stylesheet"Una hoja de estilo CSS.
"objectname"Un nombre de objeto (conjunto restringido de caracteres válidos).
"url"URL, nombre de archivo.

Requisitos del complemento

Para que los complementos funcionen correctamente en todas las plataformas, debes asegurarte de que exporten los símbolos que necesita Qt Widgets Designer.

En primer lugar, la clase del complemento debe exportarse para que Qt Widgets Designer pueda cargarlo. Para ello, utiliza la macro Q_PLUGIN_METADATA(). Además, debe utilizarse la macro QDESIGNER_WIDGET_EXPORT para definir cada clase de widget personalizada dentro de un complemento, que Qt Widgets Designer instanciará.

Creación de widgets que funcionen correctamente

Algunos widgets personalizados tienen características especiales de interfaz de usuario que pueden hacer que se comporten de forma diferente a muchos de los widgets estándar que se encuentran en Qt Widgets Designer. En concreto, si un widget personalizado bloquea el teclado como resultado de una llamada a QWidget::grabKeyboard(), el funcionamiento de Qt Widgets Designer se verá afectado.

Para dotar a los widgets personalizados de un comportamiento especial en Qt Widgets Designer, proporciona una implementación de la función initialize() con el fin de configurar el proceso de construcción del widget para un comportamiento específico de Qt Widgets Designer. Esta función se llamará por primera vez antes de cualquier llamada a createWidget() y podría, por ejemplo, establecer un indicador interno que se pueda comprobar más tarde cuando Qt Widgets Designer llame a la función createWidget() del complemento.

Compilación e instalación del complemento

Un complemento sencillo

El plugin «Custom Widget » es un ejemplo de plugin sencillo de Qt Widgets Designer.

El archivo de proyecto de un complemento debe especificar los encabezados y los archivos fuente tanto del widget personalizado como de la interfaz del complemento. Normalmente, este archivo solo tiene que especificar que el proyecto del complemento se compilará como una biblioteca, pero con soporte específico para Qt Widgets Designer. En el caso de CMake, esto se hace con las siguientes declaraciones:

find_package(Qt6 REQUIRED COMPONENTS Core Gui UiPlugin Widgets)

qt_add_plugin(customwidgetplugin)
target_sources(customwidgetplugin PRIVATE
    analogclock.cpp analogclock.h
    customwidgetplugin.cpp customwidgetplugin.h
)
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 a las bibliotecas Qt Widgets Designer y tenga una dependencia en tiempo de ejecución de las mismas.

También es necesario asegurarse de que el complemento se instale junto con otros complementos de widgets de Qt Widgets Designer:

   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}"
)

Para qmake:

CONFIG      += plugin
TEMPLATE    = lib
HEADERS     = analogclock.h \
              customwidgetplugin.h
SOURCES     = analogclock.cpp \
              customwidgetplugin.cpp
OTHER_FILES += analogclock.json

La variable « QT » contiene la palabra clave « uiplugin », que es el equivalente a la biblioteca « Qt::UiPlugin ».

También es necesario asegurarse de que el complemento se instale junto con otros complementos de widgets de Qt Widgets Designer:

target.path = $$[QT_INSTALL_PLUGINS]/designer
INSTALLS += target

La variable « $[QT_INSTALL_PLUGINS] » es un marcador de posición que indica la ubicación de los complementos de Qt instalados. Puedes configurar « Qt Widgets Designer » para que busque complementos en otras ubicaciones estableciendo la variable de entorno « QT_PLUGIN_PATH » antes de ejecutar la aplicación.

Nota: Qt Widgets Designer buscará un subdirectorio designer en cada ruta indicada.

Consulte QCoreApplication::libraryPaths() para obtener más información sobre cómo personalizar las rutas de acceso a bibliotecas y complementos en aplicaciones Qt.

Si los complementos se compilan en un modo incompatible con Qt Widgets Designer, no se cargarán ni se instalarán. Para obtener más información sobre los complementos, consulta el documento «Plugins HOWTO ».

División del complemento

El enfoque sencillo explicado anteriormente plantea un problema, especialmente cuando se utilizan otras interfaces de Qt Widgets Designer que tienen enlaces: la aplicación que utilice el widget personalizado dependerá entonces de los encabezados y las bibliotecas de Qt Widgets Designer. En un escenario real, esto no es deseable.

En las siguientes secciones se describe cómo resolverlo.

Enlace del widget a la aplicación

Al utilizar qmake, el archivo fuente y el archivo de cabecera del widget personalizado se pueden compartir entre la aplicación y Qt Widgets Designer creando un archivo .pri para su inclusión:

INCLUDEPATH += $$PWD
HEADERS += $$PWD/analogclock.h
SOURCES += $$PWD/analogclock.cpp

A continuación, este archivo sería incluido por el archivo ` .pro ` del complemento y de la aplicación:

include(customwidget.pri)

Al utilizar ` CMake`, los archivos fuente del widget también se pueden añadir al proyecto de la aplicación.

Compartir el widget mediante una biblioteca

Otra forma de hacerlo es incluir el widget en una biblioteca que esté vinculada tanto al complemento Qt Widgets Designer como a la aplicación. Se recomienda utilizar bibliotecas estáticas para evitar problemas a la hora de localizar la biblioteca en tiempo de ejecución.

Para obtener más información sobre las bibliotecas compartidas, consulta «Creación de bibliotecas compartidas».

Uso del complemento con QUiLoader

La forma recomendada de añadir widgets personalizados a QUiLoader es crear una subclase que reimplemente QUiLoader::createWidget().

Sin embargo, también es posible utilizar los complementos de widgets personalizados de Qt Widgets Designer (véase QUiLoader::pluginPaths() y las funciones relacionadas). Para evitar tener que implementar las bibliotecas de Qt Widgets Designer en el dispositivo de destino, dichos complementos no deben tener ningún vínculo con las bibliotecas de Qt Widgets Designer (QT = uiplugin, véase «Creación de widgets personalizados» en Qt Widgets Designer#BuildingandInstallingthePlugin).

Para obtener más información sobre el uso de widgets personalizados en Qt Widgets Designer, consulte los ejemplos «Complemento de widgets personalizados» y «Extensión del menú de tareas » en Qt Widgets Designer. Además, puede utilizar la clase QDesignerCustomWidgetCollectionInterface para combinar varios widgets personalizados en una única biblioteca.

© 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.