Uploaded image for project: 'Qt'
  1. Qt
  2. QTBUG-116804

QML incubation documentation issues



    • 589d0fa5d (dev), 56ec9ac86 (6.6), 91c940650 (6.5)


      I'm looking into a question someone had about incubators and I noticed something interesting in its documentation:

      The use of QQmlIncubator gives more control over the creation of a QML object, including allowing it to be created asynchronously using application idle time. The following example shows a simple use of QQmlIncubator.

          QQmlIncubator incubator;
          while (!incubator.isReady()) {
              QCoreApplication::processEvents(QEventLoop::AllEvents, 50);
          QObject *object = incubator.object();

      When looking at https://doc.qt.io/qt-6/qcoreapplication.html#processEvents-1, I see:

      Use of this function is discouraged. Instead, prefer to move long operations out of the GUI thread into an auxiliary one and to completely avoid nested event loop processing. If event processing is really necessary, consider using QEventLoop instead.

      Why are we using this in one of our examples if it's discouraged?

      The next paragraph after that example says:

      Asynchronous incubators are controlled by a QQmlIncubationController that is set on the QQmlEngine, which lets the engine know when the application is idle and incubating objects should be processed. If an incubation controller is not set on the QQmlEngine, QQmlIncubator creates objects synchronously regardless of the specified IncubationMode.

      So my conclusion after reading this, as a user, is that this seems like the "proper" way of doing it (although it should say that a controller is not set by default). Looking at the example on https://doc.qt.io/qt-6/qqmlincubationcontroller.html, then:

      For example, this is an example of a incubation controller that will incubate for a maximum of 5 milliseconds out of every 16 milliseconds.

      class PeriodicIncubationController : public QObject,
                                           public QQmlIncubationController
          PeriodicIncubationController() {
          void timerEvent(QTimerEvent *) override {

      Although the previous example would work, it is not optimal. Real world incubation controllers should try and maximize the amount of idle time they consume - rather than a static amount like 5 milliseconds - while not disturbing the application.

      This documentation gives an example, says that it's not optimal, and then provides vague advice about what should actually be done with no concrete solution for how to do it.


        Issue Links

          No reviews matched the request. Check your Options in the drop-down menu of this sections header.



              ulherman Ulf Hermann
              mitch_curtis Mitch Curtis
              0 Vote for this issue
              4 Start watching this issue



                Gerrit Reviews

                  There are no open Gerrit changes