Documentación para migrar de QtQuick Controls 1.X a 2.X

Artículo traducido de la documentación de Qt

Los cambios en Qt Quick Controls son el resultado del esfuerzo consciente por hacer el marco más eficiente y fácil de usar.

Se ha intentado mantener la compatibilidad de todas las API públicas en cada versión, pero algunos cambios han sido inevitables.

En este capítulo resumimos esos cambios en Qt Quick Controls, y proporcionamos una guía para manejarlos.

Migración desde Qt Quick Controls 1

Qt Quick Controls 1 quedó obsoleto en Qt 5.11 y se eliminará en Qt 6.0. Utilice Qt Quick Controls (anteriormente conocido como Qt Quick Controls 2) en su lugar. Para más información, consulte la guía Qt 5.15: Qt Quick Controls vs Qt Quick Controls 1 en la documentación de Qt 5.

Cambios en el registro de tipos

Qt Quick Controls ha sufrido algunos cambios importantes, sobre todo internos, en Qt 6. Al hacer uso del registro de tipos mejorado introducido en Qt 5.15, allanamos el camino para la compilación de los archivos QML del módulo a C++ y permitimos que las herramientas sean más eficaces. En particular, el modelo de código QML de Qt Creator debería tener una imagen más completa de los tipos, haciendo más fiable su completado y la comprobación de errores del código de Qt Quick Controls. Las herramientas de análisis estático como qmllint y qmlformat también se benefician al conocer los tipos que ahora se declaran en tiempo de compilación en C++.

Los estilos personalizados son ahora módulos QML

Para permitir el registro de tipos en tiempo de compilación, cada estilo de Qt Quick Controls es ahora un módulo QML propiamente dicho. Anteriormente, un simple Button.qml era suficiente para crear tu propio estilo. Aunque conveniente, esto requería alguna API no estándar, que a su vez requería adaptación en herramientas como Qt Designer.

Ahora, todos los tipos QML que implementa un estilo deben declararse en el archivo qmldir de ese estilo:

module MyStyle
Button 1.0 Button.qml

Al unificar esto con el resto del mundo QML, los estilos resultan más familiares para los desarrolladores y, con suerte, más fáciles de entender para los principiantes. Como consecuencia, se ha tenido que eliminar la siguiente API:

QQuickStyle::addStylePath()
QQuickStyle::availableStyles()
QQuickStyle::path()
QQuickStyle::stylePathList()
QT_QUICK_CONTROLS_STYLE_PATH

Ahora que los estilos deben encontrarse en la ruta de importación del motor QML como cualquier otro módulo QML, ya no es necesario ni posible soportar esta API.

Nombres de estilo

Además, ahora sólo hay una forma válida, que distingue entre mayúsculas y minúsculas, para los nombres de estilo: "Material", "MyStyle", etc. Es decir: el nombre del estilo debe coincidir exactamente con el nombre del módulo QML. Esto también se aplica a los selectores de archivo, donde antes todos los nombres de estilo se escribían en minúsculas. Por ejemplo, donde lo siguiente era una estructura válida para un proyecto Qt 5:

MyProject
├── main.qml
├── HomePage.qml
└── +material
    └───HomePage.qml

En Qt 6, +material se convierte en +Material:

MyProject
├── main.qml
├── HomePage.qml
└── +Material
    └───HomePage.qml

Todas las formas existente de All of the existing ways to run an application with a specific style are still supported.

Todas las formas existentes de ejecutar una aplicación con un estilo específico siguen siendo compatibles.

Selección de estilos en tiempo de ejecución y de compilación

Importar un estilo tiene ahora un significado extra debido a la forma en que las importaciones funcionan internamente. Anteriormente, importar QtQuick.Controls registraba los tipos de control del estilo actual con el motor QML:

import QtQuick.Controls

Nos referimos a esto como selección de estilo en tiempo de ejecución, ya que el estilo se selecciona en tiempo de ejecución.

La importación explícita de QtQuick.Controls.Material simplemente expondría cualquier API extra proporcionada por ese estilo (por ejemplo, el tipo Material adjunto):

import QtQuick.Controls.Material

Ahora, importar explícitamente un estilo hace ambas cosas.

Esto significa que se utilizarán los tipos de control (como Button) del último estilo importado. Nos referimos a esto como selección de estilo en tiempo de compilación.

Esto tiene implicaciones para el código existente. Es decir, si su aplicación soporta más de un estilo, mueva estas importaciones a sus propios archivos QML que son seleccionados por archivo.

Por ejemplo, si tienes el siguiente main.qml:

import QtQuick.Controls
import QtQuick.Controls.Material
import QtQuick.Controls.Universal

ApplicationWindow {
    width: 600
    height: 400
    visible: true

    Material.theme: darkMode ? Material.Dark : Material.Light
    Universal.theme: darkMode ? Universal.Dark : Universal.Light

    // Child items, etc.
}

Puede trasladar el código común a un componente "base":

// MainWindow.qml

import QtQuick.Controls

ApplicationWindow {}

Luego, agregue un subdirectorio +Material, y en él, agregue el código específico de Material en MainWindow.qml:

// +Material/MainWindow.qml

import QtQuick.Controls.Material

ApplicationWindow {
    Material.theme: darkMode ? Material.Dark : Material.Light
}

Y hacer lo mismo para Universal:

// +Universal/MainWindow.qml

import QtQuick.Controls.Universal

ApplicationWindow {
    Universal.theme: darkMode ? Universal.Dark : Universal.Light
}

Luego, en main.qml:

import QtQuick.Controls

MainWindow {
    width: 600
    height: 400
    visible: true

    // Child items, etc.
}

Ver también: Using File Selectors with Qt Quick Controls.

Default style

El estilo predeterminado (Default style) ha sido renombrado como "Basic", puesto que ya no es el estilo predeterminado. En su lugar, el estilo predeterminado se elige ahora en función de la plataforma para la que se creó Qt:

Android: Material Style
Linux: Fusion Style
macOS: macos Style
Windows: Windows Style
Resto de plataformas: Basic Style

Por lo tanto, las aplicaciones que no especificaron un estilo en Qt 5 y tienen controles personalizados deben especificar explícitamente el estilo Basic en Qt 6 para asegurarse de que esos controles se ven y se comportan como lo hacían con Qt 5.

Paleta

La API de la paleta se ha movido a QQuickItem. Las diversas API que utilizan paletas en Qt Quick Controls no se han modificado.

Controles

Cambios en ApplicationWindow

Se han eliminado las propiedades de overlay y la API adjunta obsoletas. En su lugar, usar el tipo Overlay attached.

Cambios en ComboBox

La propiedad pressed es ahora de sólo lectura. Para modificar el estado visual pulsado de un ComboBox, utilice en su lugar la propiedad down.

Cambios en Contenedor

Se ha eliminado la función obsoleta removeItem(var). En su lugar se puede utilizar removeItem(Item) o takeItem(int).

Cambios en Dialog

Las señales de diálogo accepted() and rejected() se emiten ahora antes de closed() cuando se llama a done(), accept() y reject().

Se ha eliminado la función obsoleta removeItem(var). En su lugar se puede utilizar removeItem(Item) o takeItem(int).

El tiempo de espera de ToolTip ahora comienza sólo después de que opened() ha sido emitido. Esto hace que las tooltips con transiciones enter sean visibles durante toda la duración de la propiedad timeout. Esto significa que son visibles un poco más de lo que eran antes, por lo que puede valer la pena comprobar visualmente las tooltips en su aplicación y ajustar los tiempos de espera si es necesario.

Cambios en StackView

El valor enum StackView.Transition ha quedado obsoleto. El argumento operación puede omitirse para utilizar la transición por defecto para cualquier operación dada.

Cambios en Tumbler

implicitWidth e implicitHeight ahora deben ser proporcionados para el contentItem del Tumbler, haciéndolo consistente con todos los otros controles.

Más información

https://doc.qt.io/qt-6/qtquickcontrols-changes-qt6.html

Última actualización hace 9 meses