The Wizard was designed to be super flexible.

But at some point complexity got in the way and made it hard to understand and use.

For that reason we've created

The SetupGuide

SetupGuide consists of two Major "parts".

The Screen, which shows and controls setup steps. You can find it in Screens.SetupGuide.

The Setup Steps themselves which are based on a defined API to help minimize the code you have to write for a step

With the release of enigma2 4.4 we have replaced all of the initial setup "Wizardry" with SetupGuide.

If you think about creating some kind of initial, or generic guided setup for a plugin here's how it works.

Create your setup steps

The base classes for steps are to be found in Components.SetupGuide.BaseStep.There is a bunch of already defined base steps for everything that was needed for the factory setup guide.

class SetupBaseStep(object) #Is the Base class all steps are to be derived from
class SetupTextStep(SetupBaseStep) #A simple "show me some text" step
class SetupListStep(SetupBaseStep) #Show a list for selection
class SetupListStepConfigSelection(SetupListStep) # show a config selection element as list for selection
class SetupConfigStep(SetupBaseStep) #show a list of config elements in a typical ConfigListScreen like fashion

Based on these steps you can create your own steps.

Here's some exmaples taken from the actual initial setup.

from Components.SetupGuide.BaseStep import SetupListStepConfigSelection, SetupTextStep, SetupListStep
from Components.config import config
from Screens.ScanSetup import ScanSimple, ScanSetup
from Components.NimManager import nimmanager

class WelcomeStep(SetupTextStep):
    def __init__(self, parent):
        SetupTextStep.__init__(self, parent)

    def prepare(self):
        self.title = _("Welcome...")
        self.text = _("to your new Dreambox!\nLet's start setting it up...\n\n[Press OK]")
        return True

class AutomaticStandbyStep(SetupListStepConfigSelection):
    def prepare(self):
        self._configSelection = config.usage.inactivity_shutdown
        self.title = _("Auto Standby")
        self.text = _("Automatic standby mode\n\nIf you don't press any button on the remote control, your Dreambox can enter the standby mode automatically. You can choose the period after which the standby mode will be activated or disable this functionality now.")
        return True

    def onOk(self):
        config.usage.inactivity_shutdown_initialized.value = True
        config.usage.inactivity_shutdown_initialized.save()
        return SetupListStepConfigSelection.onOk(self)

class UsageLevelStep(SetupListStepConfigSelection):
    def prepare(self):
        self._configSelection = config.usage.setup_level
        self.title = _("User Level")
        self.text = _("Your Dreambox offers three levels of configuration options:\n\nSimple - We suggest this level if this is your first contact with a Dreambox.\nIntermediate - This level enables you to change some more options, mainly the graphical user interface and the behaviour of your Dreambox.\nExpert - This gives you full control over all available settings of your Dreambox.\n\nWarning: Higher levels may lead to increased usage complexity.")
        return True

WelcomeStep is pretty much the most basic possible kind of a proper SetupStep.

The most important method of a SetupStep is "prepare". It is called before every invocation (even on "back") of the actual step.

And here's the super simple core things about it

• You have to set self.title and self.text inside prepare or they will be missing/wrong
• Whenever it doesn't return True, the step will be skipped > conditional steps
  • You define the conditions. SetupGuide only checks for the return value of <currentStep>.prepare()
• If you require some async operation after the user pressed OK, return False in onOk of your step and manually advance to the next step once the async-operation was finished (please make sure you always land at that call or your guide will be stalled)

self.parent.nextStep()

There's plenty of simple to more complex working examples in Components/SetupGuide, go have look to learn more about it.

Open SetupGuide with your Steps

Once all your steps are ready you simply open the actual SetupGuide screen with simple dictionary of {int(prio) : YourStepClass, ...} (ordering is done by priority).

session.open(SetupGuide, steps={1: MyFirstStepClass, 2: MySecondStepClass})