QML

Introductie tot QML modules in Qt6

1. QML-modules

Wat zijn QML-modules?

Een QML-module is een verzameling QML-componenten/-elementen, JavaScript-bestanden en assets die kunnen worden geïmporteerd en gebruikt in andere QML-applicaties. Modules maken het mogelijk om code te kapselen en te hergebruiken via namespaces en versiebeheer. Kortom: ze zorgen voor een nette en gemodulariseerde projectstructuur.

 
import QtQuick
import InvistoControls 1.3

Window {
  width: 640
  height: 480
  visible: true
  title: qsTr("Hello World")
  
  IvProgressBar {
  value: 50
  }
}

In het bovenstaande codefragment importeren we de InvistoControls-module, versie 1.3. IvProgressBar is een van de componenten die in deze module zijn opgenomen.

Met Qt 6.2 werd een gebruiksvriendelijkere manier geïntroduceerd om modules te maken. De CMake-API werd afgerond en introduceerde het qt_add_qml_module-commando. Laten we eens kijken naar dit nieuwe commando.

2. CMake-ondersteuning

qt_add_qml_module is een CMake-functie die door het Qt-framework wordt aangeboden en wordt gebruikt om een nieuwe QML-module te creëren en te definiëren. Het genereert de nodige CMake-regels om de module en de bijbehorende componenten te bouwen en te installeren.

De functie qt_add_qml_module accepteert verschillende argumenten, waaronder de modulenaam, de QML-bronbestanden en eventuele extra afhankelijkheden. De functie maakt het ook mogelijk om een plug-intype op te geven, dat kan worden ingesteld op “qmltypes” of “qmlplugin”, afhankelijk van het type module dat je wil aanmaken.

Hier is een voorbeeld van het gebruik van qt_add_qml_module:

 
qt_add_qml_module(InvistoControls
  URI be.invsito.controls
  VERSION 1.0
  QML_FILES
  InvistoButton.qml
  InvistoProgressBar.qml
  PLUGIN_TYPE qmltypes
  DEPENDENCIES
  QtQuick
)

In dit voorbeeld wordt een nieuwe QML-module genaamd “InvistoControls” gedefinieerd met een URI van “be.invsito.controls” en een versie 1.0. De QML-bronbestanden voor de module zijn opgegeven als “InvistoButton.qml” en “InvistoProgressBar.qml”. Het plug-intype is ingesteld op “qmltypes”, en de module heeft een afhankelijkheid van de “QtQuick”-module.

Zodra deze functie wordt aangeroepen, genereert het CMake-buildsysteem de benodigde regels om de QML-module en de bijbehorende componenten te bouwen en te installeren. De module kan vervolgens worden geïmporteerd en gebruikt in QML-applicaties via de opgegeven URI.

Wat zijn de belangrijkste voordelen van dit nieuwe commando?

We hoeven de qmldir- en qmltypes-bestanden niet zelf te schrijven.
We hoeven geen qrc-resourcebestand te maken.
Een module kan eenvoudig een mix zijn van QML- en C++-componenten. C++-types die zijn voorzien van QML_ELEMENT (en vergelijkbare annotaties) worden automatisch geregistreerd.
qmlcachegen en qmllint worden automatisch uitgevoerd.

3. Enkele voorbeelden

De onderstaande voorbeelden dienen als introductie tot QML-modules en het qt_add_qml_module-commando. Hoewel er nog veel meer over te vertellen valt, is dit simpelweg een introductie tot de meest gebruikte scenario’s.

3.1 Een QML-applicatie bouwen

De titel spreekt voor zich, denk ik. Je wilt een zeer performante, vloeiend geanimeerde en visueel aantrekkelijke applicatie in QML bouwen. Met qt_add_qml_module kun je je QML- en resourcebestanden eenvoudig opnemen in het project. Simpel, geen trucjes nodig.

Laten we eens kijken naar het voorbeeld hieronder:

De volledige broncode is hier te vinden.

Eerst hebben we het main.qml-bestand.

 
import QtQuick

Window {
  width: 640
  height: 480
  visible: true
  title: qsTr("Hello World")

  Logo {
  anchors.centerIn: parent
  }
}

En dan de main.cpp die onze qml file laadt.

 
#include 
#include 

int main(int argc, char *argv[])
{
  QGuiApplication app(argc, argv);
  
  QQmlApplicationEngine engine;
  const QUrl url(u"qrc:/invisto/main.qml"_qs);
  engine.load(url);
  return app.exec();
}

En om af te sluiten is er de CMakeLists.txt om het project te bouwen.

 
cmake_minimum_required(VERSION 3.16)

project(QMLModuleApplicationDemo VERSION 1.0 LANGUAGES CXX)

set(CMAKE_AUTOMOC ON)
set(CMAKE_CXX_STANDARD 17)
set(CMAKE_CXX_STANDARD_REQUIRED ON)

find_package(Qt6 6.2 COMPONENTS Quick Gui REQUIRED)

qt_add_executable(app
	main.cpp
)

qt_add_qml_module(app
  URI invsito
  VERSION 1.0
  QML_FILES
    main.qml
    Logo.qml
  RESOURCES
    images/Invisto-Logo.svg
)
target_link_libraries(myapp PRIVATE Qt6::Gui Qt6::Quick)

De app die we hier bouwen, toont het Invisto-logo in het midden van het scherm. Het logo zelf is verpakt in een Logo.qml.

Wat is hier belangrijk, als we kijken naar ons CMake-bestand en het qt_add_qml_module-commando?

URI: dit zorgt ervoor dat onze QML- en resourcebestanden worden geplaatst in qrc:/${URI} binnen het resource-bestandssysteem.
VERSION: de versie van de module.
QML_FILES: een lijst van de QML-bestanden die je in de module wilt opnemen.
RESOURCES: een lijst van de resourcebestanden die je aan de module wilt toevoegen.

3.2 Een QML-module bouwen die een C++-klasse registreert als QML-type

In dit voorbeeld willen we laten zien hoe je een C++-klasse schrijft en registreert als een QML-type.

De volledige broncode is hier te vinden.

De headerfile van onze C++-klasse:

 
#pragma once

#include 
#include 

class CustomElement : public QObject
{
  Q_OBJECT
  QML_ELEMENT
  Q_PROPERTY(int counter READ counter WRITE setCounter
NOTIFY counterChanged)

  public:
    CustomElement();
    int counter() const;
    void setCounter(int value);
    
signals:
  void counterChanged();
  
private:
  int m_counter;
};

En de CMakeLists.txt

 
qt6_add_qml_module(demolib
  URI qmllibs.demolib
  VERSION 1.0
  SOURCES
    custom_element.h custom_element.cpp
)

Zoals je ziet is het registreren heel eenvoudig:

In het headerbestand moet je QML_ELEMENT toevoegen.
QML_ELEMENT is een C++-macro van het Qt-framework die wordt gebruikt om een nieuw aangepast QML-element te registreren.
In het CMakeLists.txt-bestand voeg je je bronbestanden toe aan de SOURCES-parameter.

4. Conclusie

Dit zijn slechts twee kleine voorbeelden van wat mogelijk is met qt_add_qml_module. Legacy-projecten die een migratie ondergaan van Qt5 naar Qt6 kunnen zeker profiteren van de nieuwe API. De nieuwe CMake-ondersteuning is veel eenvoudiger om mee te werken: je hoeft minder bestanden zelf te schrijven. Qmllint wordt automatisch uitgevoerd, wat je dwingt om je QML-code schoon te houden.

Projecten met Qt 6.2 (en hoger) zouden dit vanaf het begin moeten gebruiken.

Meer documentatie is beschikbaar op de website van de Qt Group. Neem zeker een kijkje op:

https://doc.qt.io/qt-6/qt-add-qml-module.html

https://doc.qt.io/qt-6/qtqml-writing-a-module.html

‍

Download de volledige case

Download

Ook interesse in een state-of-the-art interface die uw product naar een hoger niveau tilt?

Let's talk!