Start Options Example

Demonstrates configuring the full set of QOhosStartOptions fields when starting another ability.

A configuration pane offers every option of QOhosStartOptions behind individual Set checkboxes: window mode, display id, animation, window geometry, process mode with startup visibility, start window icon and background color, supported window modes, minimum and maximum window sizes, hiding the start window, and window creation parameters with QOhosWindowCreateParams::setAnimationType(). The selected options are assembled through QtOhosExtras::createStartOptions() and the ability is started with QtOhosExtras::startAbility(). When the completion handler is enabled, the options are wrapped with QtOhosExtras::createStartRequest() and the QOhosStartRequest::requestSucceeded() and requestFailed() signals are logged.

Options are created and populated field by field:

     auto startOptions = QtOhosExtras::createStartOptions();

     if (m_setWindowModeCheckBox->isChecked()) {
         startOptions->setWindowMode(static_cast<QtOhosExtras::QOhosStartOptions::WindowMode>(m_windowModeComboBox->currentData().toInt()));
     }
     if (m_displayId.setCheckBox->isChecked()) {
         startOptions->setDisplayId(m_displayId.spinBox->value());
     }
     if (m_setWithAnimationCheckBox->isChecked()) {
         startOptions->setWithAnimation(m_withAnimationValueComboBox->currentData().toBool());
     }

Without a completion handler the ability is started directly with the options:

     auto operationStatus = QtOhosExtras::startAbility(want, *startOptions);
     appendLog(operationStatusText(QStringLiteral("startAbility(want, configuredStartOptions)"), operationStatus));

With a completion handler the options are wrapped in a start request whose signals report the outcome:

         auto startRequest = QtOhosExtras::createStartRequest(*startOptions);

         m_pendingStartRequests.append(startRequest);
         auto *requestPtr = startRequest.get();
         QObject::connect(
             requestPtr, &QtOhosExtras::QOhosStartRequest::requestSucceeded, this,
             [this, requestPtr](QtOhosExtras::QOhosElementName elementName, const QString &message) {
                 appendLog(QStringLiteral("requestSucceeded: %1/%2/%3 %4")
                     .arg(elementName.bundleName)
                     .arg(elementName.moduleName)
                     .arg(elementName.abilityName)
                     .arg(message));
                 releaseStartRequest(requestPtr);
             });
         QObject::connect(
             requestPtr, &QtOhosExtras::QOhosStartRequest::requestFailed, this,
             [this, requestPtr](QtOhosExtras::QOhosElementName elementName, const QString &message) {
                 appendLog(QStringLiteral("requestFailed: %1/%2/%3 %4")
                     .arg(elementName.bundleName)
                     .arg(elementName.moduleName)
                     .arg(elementName.abilityName)
                     .arg(message));
                 releaseStartRequest(requestPtr);
             });

         auto operationStatus = QtOhosExtras::startAbility(want, *startRequest);
         appendLog(operationStatusText(QStringLiteral("startAbility(want, startRequest)"), operationStatus));
         if (!operationStatus->success()) {
             releaseStartRequest(requestPtr);
         }

Note: The startup visibility only takes effect together with the process mode. A QOhosStartRequest has to be kept alive until its completion signal fires; the example stores pending requests and releases them from the signal handlers.

Images:

abilitycontext/startoptions/qt-logo.png