/dev/dreambox :: The Wizard is dying - A quick look at the new SetupGuide

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.

Python: Components/SetupGuide/BaseSteps.py
  1. class SetupBaseStep(object) #Is the Base class all steps are to be derived from
  2. class SetupTextStep(SetupBaseStep) #A simple "show me some text" step
  3. class SetupListStep(SetupBaseStep) #Show a list for selection
  4. class SetupListStepConfigSelection(SetupListStep) # show a config selection element as list for selection
  5. 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.

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)

  1. 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).

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