The obligatory Hello, World

Those who prefer to beat around the bush best step off here, for we shall plunge head-first into the magical world of Merlin. All examples here, like Merlin itself, are written in C# 3.0.

Starting with a new winforms application, let's add a reference to Merlin.dll and

Using Merlin;

to the top of the main class file. Now we go inside the Main(...) method.

var steps = new List<IStep>(); //We'll define wizard steps here.
var t = new TextBox();
steps.Add(new TemplateStep(t, "Name Entry"));
new WizardController(steps).StartWizard("My SuperCoolWizard");
MessageBox.Show("Hello, " + t.Text);

When you run this, you should see something like this:

Enter your name into the sole textbox in the page, click "Finish", and you will be greeted plainly but warmly. So what exactly happened?

var steps = new List<IStep>();

A "step" in the wizard correlates to a single screen that you see. The "Next" and "Previous" buttons navigate the user from one step to another. Because the step we see in the wizard is the last one, it appears with a "Finish" button instead of a "Next" button.

var t = new TextBox();
steps.Add(new TemplateStep(t, "Name Entry"));

The UI of a step is represented by a control. TemplateStep, a simple step implementation, requires (at a minimum) that control as its constructor argument. It attempts to size this control to take up all the space available. Of course, we don't always want the control to be flushed against the edges of the step area. So we can provide a margin around it by changing the statement above to:

steps.Add(new TemplateStep(t, 10, "Name Entry"));

This creates a margin of 10 pixels from each edge of the control. But let's go on examining our code:

new WizardController(steps).StartWizard("My SuperCoolWizard");

Once we have our sequence of steps, we need to execute them. The WizardController object does just that. It accepts as its constructor an IList of steps. When the StartWizard method is invoked, it goes through the steps as the user clicks the "Back" and "Next/Finish" buttons.

Ok, simple enough, but now let's run this wizard again, but instead of the "Finish" button, click the "Cancel" button. Whoops! You still get greeted. The cancel button aborts the wizard, but you still have to check afterward to make sure the wizard exited successfully. So let's rewrite the last two lines in our example as follows:

var result = new WizardController(steps).StartWizard("My SuperCoolWizard");
if (result == WizardController.WizardResult.Finish)
{
    MessageBox.Show("Hello, " + t.Text);
}

Of course, there's a lot more to wizards than single-control steps. Join us next time for more Merlin magic.