Onboarding Tutorial

The example opens a Kirigami window and marks target controls with Onboarding attached properties. The overlay draws a highlight around the current focus area, and the tooltip text is driven by the current target's attached Onboarding::texts property.

Workflow

• Mark a source item with Onboarding::isSource.
• Add grouped Onboarding attached properties directly to controls inside Page1.qml, Page2.qml, and Page3.qml.
• Use Onboarding::start() or Onboarding::start(string) to begin walking the target items in a group.
• Use Onboarding::aboutToShow handlers to keep the swipe view synchronized with tutorial progression.
• Supply Onboarding::additionalDataComponent so the tooltip can show context-sensitive media from each step's Onboarding::additionalData.

Key Snippets

Start the default onboarding flow from a keyboard shortcut:

 Shortcut {
     context: Qt.ApplicationShortcut
     sequence: "F1"

     onActivated: Onboarding.start()
 }

Add attached properties with media content displayed in the tooltip:

 Onboarding.texts: [qsTr("This button starts the default onboarding tutorial.")]
 Onboarding.additionalData: ({
     video: "qrc:/qt/qml/org/kde/kirigamiaddons/examples/onboardingtutorial/onboarding-video.webp",
     videoCaption: "This is a video caption",
 })

Run a per-step callback before focusing an item:

 Onboarding.groups: ["advanced"]
 Onboarding.texts: [qsTr("This checkbox is on the second page of the advanced flow.")]
 Onboarding.onAboutToShow: item.swipeView.currentIndex = 1

Bind Onboarding::additionalDataComponent to dynamic media from the current item:

 ColumnLayout {
     readonly property var additionalData: Onboarding.currentItem?.additionalData ?? ({})

     Platform.Theme.colorSet: Platform.Theme.Tooltip
     Platform.Theme.inherit: false

     implicitWidth: Math.max(video.Layout.preferredWidth, videoCaption.implicitWidth)
     spacing: 0
     visible: video.source.toString().length > 0

     AnimatedImage {
         id: video

         Layout.alignment: Qt.AlignHCenter
         Layout.maximumHeight: Kirigami.Units.gridUnit * 7
         Layout.maximumWidth: Kirigami.Units.gridUnit * 14
         Layout.preferredHeight: implicitWidth > 0 ? Math.min(Layout.preferredWidth * implicitHeight / implicitWidth, Layout.maximumHeight) : 0
         Layout.preferredWidth: implicitHeight > 0 && implicitWidth > 0 ? Math.min(implicitWidth, Layout.maximumWidth, Layout.maximumHeight * implicitWidth / implicitHeight) : 0
         fillMode: Image.PreserveAspectFit
         sourceSize.width: Layout.maximumWidth
         source: parent.additionalData.video ?? ""
     }

     QQC2.Label {
         id: videoCaption

         Layout.alignment: Qt.AlignHCenter
         Layout.preferredWidth: Math.min(implicitWidth, video.Layout.preferredWidth)
         color: Platform.Theme.textColor
         horizontalAlignment: Text.AlignHCenter
         text: parent.additionalData.videoCaption ?? ""
         visible: text.length > 0
         wrapMode: Text.WordWrap
     }
 }

Keep the tutorial pages instantiated so targets remain available during onboarding:

 Item {
     id: pageHost

     anchors.fill: parent
     Onboarding.isSource: true
     Onboarding.sourceGroups: ["", "advanced"]

     ColumnLayout {
         anchors.fill: parent
         spacing: 0

         QQC2.SwipeView {
             id: swipeView

             Layout.fillHeight: true
             Layout.fillWidth: true
             interactive: !Onboarding.active

             Page1 {
                 swipeView: swipeView
             }

             Page2 {
                 swipeView: swipeView
             }

             Page3 {
                 swipeView: swipeView
             }
         }

         QQC2.PageIndicator {
             Layout.alignment: Qt.AlignHCenter
             Layout.bottomMargin: Kirigami.Units.largeSpacing
             count: swipeView.count
             currentIndex: swipeView.currentIndex
         }
     }
 }

Summary

This example shows how to:

• Combine attached onboarding metadata with standard Qt Quick controls to drive an onboarding flow.
• Define default and named walkthrough groups over the same source.
• Highlight controls while blurring the surrounding source area.
• Synchronize dynamically visible pages before target lookup.
• Extend the visible tooltip content with Onboarding::additionalDataComponent.

Files:

• OnboardingTutorial/CMakeLists.txt
• OnboardingTutorial/Main.qml
• OnboardingTutorial/Page1.qml
• OnboardingTutorial/Page2.qml
• OnboardingTutorial/Page3.qml
• OnboardingTutorial/main.cpp

Images:

• OnboardingTutorial/onboarding-video.webp