qmlbook / qt6book

The Qt 6 Book - A book about QML

Qt6 Book

Copyright(C) 2012-2021 Johan Thelin and Jürgen Bocklage-Ryannel

The new home for the Qt6 book (based on QmlBook)

You can always find the latest released version of the book built at https://www.qt.io/product/qt6/qml-book, and the latest snapshot at https://distracted-dijkstra-f5d508.netlify.app/.

Contents

1. Building the Book Locally
2. Building for Release
3. For Reviewers
4. For Authors

1. Building the Book Locally

The contents is built into a static site using VuePress. The packages are managed using Yarn.

To build the contents locally, run:

$ yarn
$ yarn run docs:dev

Then visit localhost:8080 to view the book.

To build the examples, run:

$ yarn run examples:build

This will create the _examples/ directory with the build. It assumes Qt6 can be found by CMake. My typical command line on a Debian Linux machine looks like this:

$ CMAKE_PREFIX_PATH=/path/to/Qt/6.2.0/gcc_64/lib/cmake/ yarn run examples:build

Subsequent calls do not need CMAKE_PREFIX_PATH to be specified.

2. Building for Release

To build for release, first build the docs, then package the examples into a tar-ball:

$ yarn run docs:build
$ yarn run examples:package

This creates examples.tar.gz in your package root, as well as where VuePress places the output, i.e. docs/.vuepress/dist/.

Notice that the examples:package command assumes that the VuePress dist/ directory exists.

3. For Reviewers

Pick chapters to review from the Project Board. Also look for issues tagged as Questions in the project.

Reviews are welcome both as issues, or as pull requests. Pick the approach that is the easiest for you!

4. For Authors

Chapters are outlined in docs/.vuepress/config.js. Please tag chapters as Qt5, Qt6 Draft, and Qt 6 respectively.

qt6book's Issues

ch11: convert

ch04: example code is duplicated

I noticed that docs/ch04-qmlstart/transformations.md has an example which also exists at docs/ch04-qmlstart/src/transformation/TransformationExample.qml. Can we reuse the example in the src folder somehow?

Add spacing between the words in Qt product names

It looks a bit odd having the words joined together, as the standard way of referring to them is with spaces between the words. So I propose doing a find + replace:

"Qt5" => "Qt 5"
"QtQuick" => "Qt Quick"
etc.

rework the screenshot tool

Add discussion of different UI technologies (widgets/controls vs desktop/mobile/embedded/mcu).

E.g. use widgets if you know only C++/ desktop style UI/trees, use QML: animations/design/mobile like ui, use MCU if you target small HW without gfx accel.

move qmlbook to maintenance mode

adapt to cmake

there shall be a root CMake file and build all examples using qt6

ch04: testing code visible in examples

In docs/ch04-qmlstart/transformations.md there are two functions beginning with "_test" that are used in docs/ch04-qmlstart/src/transformation/tst_transformation.qml for testing purposes. These should not be visible to users reading the generated documentation.

ch18: convert

ch06: convert examples to cmake

the examples have been converted to Qt6 but not converted yet to cmake

ch14: convert

ch04: attached properties

There is a section that says:

(8) Some properties are attached to the element itself. This is done for global relevant elements which appear only once in the application (e.g. keyboard input). The writing is .: .

What does "global relevant" mean?

The text also suggests that the elements that only appear once in the application, which sort of implies singletons, but the example looks more like attached properties.

This needs some clarification.

write readme on vuepress usage

convert ch02 qml content

ch06: Not using modern Qt 6 techniques

If I understand correctly this chapter should already be ported to Qt 6 (albeit without examples using CMake yet).

Here are some of the things that should probably be changed:

• We discourage users from directly accessing QML properties from C++ now (See this part of our latest docs).
• The section does not consistently use declarative registration via QML_ELEMENT and friends which is very important in order for tooling and many other features to work properly (among being just plainly more transparent)
• (Does not encorporate the principle of optional plugins). This is less severe since we don't have any public documentation on it. We now recommend moving all your types to a separate library and linking it from the plugin, thus making it optional and allowing for better static linking (See this change for an example).

Qt uses essentials/addon/qml/C++ wording we should follow this when thinking about chapters

C++: Change to new register format using header macros: https://doc-snapshots.qt.io/qt6-dev/qtqml-tutorials-extending-qml-example.html

Qt Design Studio

ensure LICENSES are right

QML: Come up with best strategy for new QML imports (e.g. Import QtQuick 2), don't like auto., see https://doc.qt.io/qt-6/qtqml-syntax-imports.html

Recommend qml instead of qmlscene

qmlscene is considered deprecated and will be removed in Qt 7 (Mentioned in chapter 2 for example).

How to install QML plugins using CMake

Currently, the project wizard generates a QMake based project for QtQuick 2 Extension Plugins.

Since I want to use CMake, I'm using the qt_add_qml_module CMake macro in a custom CMakeLists.txt to build the module. However, with QMake, you get an install target that you can use to move the qmldir and associated dynamic library into the main Qt import path, instead of having to fiddle with the QML_IMPORT_PATH environment variable.

Is there any correct way of doing this, i.e. figure out where the Qt import path is and copy the correct files there using CMake?

Convert all examples to Qt6 / CMake

ch8: complement with chapter on shapes

propose new chapters based on new features in Qt 6

What is the story for QtQuick UI Project? qmlscene will be deprecated.

Convert ch08 (Canvas)

Convert chapter 8 and emphasis the use case to migrate HTML5 contents to QML.

review all qml modules from ch01-06

TableViewColumn is not a type

It seems that the TableViewColumn approach to select what to show from a table model has been dropped in Qt 6, see https://doc.qt.io/qt-6/qml-qtquick-tableview.html .

Used from here: https://github.com/qmlbook/qt6book/blob/main/docs/ch17-extensions/src/CityUI/main.qml

ch16-17: convert

ch04/Advanced Techniques: Link slightly broken

The ahead of time compilation link points at http://doc.qt.io/qt-6/qtquick-deployment.html#compiling-qml-ahead-of-time when it should be https://doc.qt.io/qt-6/qtquick-deployment.html#ahead-of-time-compilation.

ch04: default properties

There is a section that says:

TIP

You can also declare one property to be the default property if no property name is given by prepending the property declaration with the default keyword. This is used for example when you add child elements; the child elements are added automatically to the default property children of type list if they are visible elements.

This is a bit confusing or lacks context - if no property name is given to what? I'm not sure how to rephrase it yet though.

Perhaps @Inkane has an idea.

QtGraphicalEffects is not available anymore, what to use?

Qt for MCU

ch9-10: replace with chapter on new shaders, incorporate particles

ch12: explain QML_XHR_ALLOW_FILE_READ more in depth

QML_XHR_ALLOW_FILE_READ is currently mentioned in a tip, but it is not explained. I propose two sentences to explain what it does, and also why it might be a bad idea in some cases.

ch07: convert

add existing vuepress content to repo

Write preface

• List TQC as sponsor
• Include biographies of authors

ch06: validate examples for android

The android examples need to be converted. Also the chapter needs to be reviewed as controls1 dialogs do not exists anymore.

How relevant are widgets

There is quite a lot of widget content, e.g. different kind of widgets. Is all this needed for the QML book? Comparing widgets, QML, Quick Controls in different use cases make sense though.

ch12: convert

convert ch01 qml content

QML: Discuss about new rendering pipeline and rework shader chapter: https://doc-snapshots.qt.io/qt6-dev/topics-graphics.html

What does a kit need to build a QtQuick2 extension?

I don't want to create a bug report for this, because I'm not sure anything is broken, so I'll add it as a question here instead.

Using Qt 6.2.0-beta2 and Qt Creator 4.15.2, I try to create a QtQuick 2 Extension Plugin project. This does not work, as it cannot find a suitable kit, as shown below:

I'd like to use the Desktop or Desktop Qt 6.2.0 MinGW 64-bit kit for this which is available as shown below:

I can build various projects using this kit, e.g. desktop applications. I can also create C++ libraries, which I guess is quite close to a QML extension, e.g.:

So the question is, what does a kit need to allow building QtQuick 2 Extension Plugins?

XmlListModel misses the xml property and get() function

In the serialization / deserialization example (chapter 14, Dynamic QML), the XmlListModel's xml property is used when serializing the scene. This property is now missing. Do you have any tips on a nice in-memory source that can be used instead, or do I have to write some sort of file handler extension thing?

Also, the get function is missing...

ch15: convert

Foreword

ch13: convert

QVector vs QList: See https://www.qt.io/blog/qlist-changes-in-qt-6