Kirigami Addons Onboarding QML Types

The onboarding module highlights controls in an application-provided source area, dims and blurs the rest of that area, and displays guidance in a tooltip. Applications describe walkthroughs with Onboarding attached properties; the module creates and manages the overlay.

To use the module, import it in each QML file that declares a source, defines a step, or controls a walkthrough:

import org.kde.kirigamiaddons.onboarding

Defining a Walkthrough

A walkthrough consists of one source item and one or more descendant step items. Mark the common ancestor with Onboarding::isSource and provide guidance on each step with Onboarding::texts or Onboarding::additionalData.

Item {
    Onboarding.isSource: true

    Button {
        text: i18nc("@action:button", "Create")
        Onboarding.texts: [
            i18nc("@info", "Create a new document with this button.")
        ]
    }

    Button {
        text: i18nc("@action:button", "Start Tutorial")
        onClicked: Onboarding.start()
    }
}

Steps are visited in attached-object creation order. Disabled steps are skipped. The source and all of its step items must remain instantiated for the duration of the walkthrough.

Defining Groups

Groups allow an application to define multiple walkthroughs over the same source area. The empty string identifies the default group used by Onboarding::start(). A source lists the groups it owns in Onboarding::sourceGroups. Each step lists its groups in Onboarding::groups, with corresponding guidance at the same positions in Onboarding::texts.

Item {
    Onboarding.isSource: true
    Onboarding.sourceGroups: ["", "advanced"]

    Button {
        Onboarding.groups: ["", "advanced"]
        Onboarding.texts: [
            i18nc("@info", "Basic guidance for this control."),
            i18nc("@info", "Advanced guidance for this control.")
        ]
    }
}

A group must be declared by exactly one source item. Calling Onboarding::start(string) for a missing or ambiguous group does not start a walkthrough and produces a warning.

Navigation and Lifecycle

The default overlay provides Previous, Next, and Cancel buttons. The Left and Right arrow keys navigate between enabled steps, and Escape stops the walkthrough. Applications can also call Onboarding::next(), Onboarding::previous(), and Onboarding::stop().

Use Onboarding::aboutToShow on a step when its target must first be made visible, for example by changing a page in a SwipeView. The target is resolved on the next event-loop turn after the signal is emitted. Onboarding::hide is emitted when the step ceases to be current.

Custom Content and Appearance

Onboarding::additionalData stores application-defined metadata on each step. Set Onboarding::additionalDataComponent to a component that reads the current step's metadata through Onboarding.currentItem.additionalData. The component is inserted between the guidance text and the navigation controls.

The highlight can be expanded with Onboarding::padding. The background effect can be adjusted with Onboarding::blur and Onboarding::blurMax. The module clamps highlight padding so the highlighted rectangle remains inside the source area.