Fondest greetings, and welcome to the blog home of the Merlin Wizard Framework! In spite of some tangential posts, this blog will be geared toward getting you up and running with the slickest, simplest, and richest WinForms wizard framework for .NET. If you read the blog posts in chronological order, it may even read like a tutorial.

Saturday, January 17, 2009

Step Library! Part 2.

The last step in the step library for the 1.0 release is a simple text form. Merlin is all about getting you through your wizard creation quickly, so we wanted to give you a way to get text input from the user without needing build your own controls. Of course, if you do need more flexibility than the text form offers, the option to build your own UI is still there.

Ok, here’s a 5-second text form:

var textFormStep = new TextFormStep("Additional Information", 
    "Please answer the following questions:", "Name:", "Age:", "Hobby:");

Once the wizard controller executes this step, here's what we see:


After this step has run, the textFormStep.Answers property will return an IEnumerable<string> containing the answers in the order in which their respective questions were specified in the constructor. Here’s another way of defining exactly the same form:

var textFormStep = new TextFormStep("Additional Information",
    "Please answer the following questions");
var nameQuestion = textFormStep.AddQuestion("Name:");
var ageQuestion = textFormStep.AddQuestion("Age:");
var hobbyQuestion = textFormStep.AddQuestion("Hobby");

There are two advantages to this approach: one is that it allows me to retrieve the answers without going through an enumeration and remembering the question order. I can just do:

MessageBox.Show("Your age is: " + ageQuestion.Answer);

The second advantage for the longhand approach is that it allows you to provide some additional options. Have you noticed how the “Finish” button appears in the above wizard even though we haven’t typed anything? We’d probably want to impose some minimal validity criteria before we’re allowed to move on:

var nameQuestion = textFormStep.AddQuestion("Name:",
var ageQuestion = textFormStep.AddQuestion("Age:", Validation.NonEmpty);

Now, the “Next/Finish” button will not be enabled until at least 3 characters have been typed into the “Name” field and the “Age” field is non-empty. There are more validations available, and you can always plug in your own delegate/lambda expression that takes a string and returns a bool.

If you want to ask for a password, you can just as easily use a password masking character:

var hobbyQuestion = textFormStep.AddQuestion("Password:", 
     Validation.Length(6, 12), '*');

Disclaimer: this UI provides no more password security than a ye olde winform with a textbox.

And last but not least, you may want to pre-populate the textbox with a default answer or a previously-specified value. Easier done than said:

var nameQuestion = textFormStep.AddQuestion("Name:");            nameQuestion.Answer = "Merlin";

Now, “Merlin” will appear in the “Name:” textbox when this step is executed.

Oh, and one really last thing: if your questions are of very uneven length, the textboxes can appear quite far away from the text of the shorter questions:


If you’d like all the textboxes to start right next to their respective labels, just set the step’s LineUpQuestions property to false (it’s true by default). Then, your question will appear like this:


‘Till next time!

No comments:

Post a Comment