Wizard's Apprentice





SourceForge.net Logo

*  The Wizard's Apprentice  *

Adding a face to your scripts


Scripts are everywhere. As long as you use the right tool for the right job, scripts are short, fast and effective. There is one area where they usually lack: user interactivity. It is difficult to create a good user interface in most script languages.

Now there is the Wizard's Apprentice. It will allow you to ask questions from a script file, using Windows dialog boxes in the so-called Wizard style: large dialogs asking one question at a time, with a Back button, a Next button and a Cancel button. Using a well-described and portable API you can create a wealth of commonly used dialog controls. With a few common scripting techniques, the Wizard's Apprentice will allow you to create wizards with style!

-What does it look like?

Here is a screenshot of the Wizard's Apprentice showing a welcome text.

Screenshot of Welcome dialog

Here is another screenshot from the same program, asking to choose a language from a list.

Screenshot of language
    selection dialog

Here's a message box, that allows you to ask Yes/No questions:

Screenshot of messagebox

-How does it work?

Communication with the Wizard's Apprentice is done through environment variables and error levels. Here's how you would code the messagebox above in Perl:

  1.  $ENV{"watitle"}="Cancel installer";
  2.  $ENV{"watext"}="This will abort the installation.~Are you sure?~~Press OK to abort the installation.~Press Cancel to continue installing.";
  3.  system("wizapp LB");
  4.  $errlevel = $? >> 8;
  5.  print("You're not sure.") if ($errlevel == 2);
  6.  print("You're sure.") if ($errlevel == 0);

The following batch code could be used to display the language selection dialog:

  1.   set watitle=Choose a language
  2.   set watext=~~~~Choose a language you want the program to run in:
  3.   set wainput= ^&English; ^&French; ^&German; ^&Italian; ^&Spanish; ^&Dutch
  4.   set waoutnum=0
  5.   set wabmp=language.bmp
  6.   set wabat=%TEMP%\wabat.bat
  7.   start /w wizapp RB
  8.   if errorlevel 2 goto :cancel
  9.   if errorlevel 1 goto :previous
  10.   call %wabat%
  11.   if "%waoutnum%"=="0" echo Choice is English
  12.   if "%waoutnum%"=="1" echo Choice is French
  13.   if "%waoutnum%"=="2" echo Choice is German
  14.   if "%waoutnum%"=="3" echo Choice is Italian
  15.   if "%waoutnum%"=="4" echo Choice is Spanish
  16.   if "%waoutnum%"=="5" echo Choice is Dutch


  • When you run the Wizard's Apprentice, it will display a dialog on the screen. The Wizard's Apprentice can display the following types of dialogs.
    Message box
    A Message box with the information, exclamation or stop icon, or with the question icon and an OK and a Cancel button.
    Text screen
    A wizard-style dialog displaying only text, e.g. a welcome screen.
    File contents
    A wizard-style dialog with a box with a scroll bar on it, in which a file is displayed. Can be used to display a license text.
    Edit field
    A wizard-style dialog with an edit field on it, where the user can type text.
    Radio buttons
    A wizard-style dialog with a set of radio buttons on it.
    A wizard-style dialog with a set of check boxes on it.
    A wizard-style dialog with a listbox on it. This listbox is either a single-selection box, where you can select exactly one item, or a multiple-selection listbox, from which you can select zero or more items.
    Combo box
    A wizard-style dialog with a combo box on it. A combo box allows you to select an item from a list, or type it yourself.
    File- or directory browser
    A wizard-style dialog with an edit field on it with a Browse button next to it. Pressing the Browse button will either show an open file dialog, or a directory tree dialog.
    Progress bar
    A dialog with a progress bar to display during lengthy operations. In between parts of the operation you can update the progress bar to a new percentage.
    Splash screen
    A splash screen that appears e.g. at program startup. Your program can perform initialisation in the background, after which you close the splash screen.
  • The Wizard's Apprentice will return an errorlevel that indicates which button the user pressed.
  • The appearance of the wizard-style dialog can be completely controlled:
    • Set the title of the dialog
    • Set the text contents of the dialog
    • Set the sidebar picture of the dialog
    • Set the labels of the buttons
    • Set the icon of the dialog
    • Set the signature text on the bottom-left corner of the dialog
    • You can even play a sound when the dialog appears.
  • The choice that the user made, or the text that was typed, is returned in environment variables.

-What's new

June 2012

Version 1.61 was released. It fixes a bug cancelling progress bar dialogs.

May 2012

Version 1.6 was released. Improvements in this version:
  • Text and appearance of progress bar and splash screen will change when an UPDATE command is done.
  • Fixed a bug which would make it impossible to open a progress bar dialog or a splash screen.

February 2006

After a long period of silence the Wizard's Apprentice 1.5 was released. The Wizard's Apprentice is no longer strictly for batch files, but can be used with any script language, e.g. Perl, PHP, VB or batch language. The manual was largely rewritten to reflect that change. Other changes include:
  • A progress bar to display during long operations.
  • A splash screen to show at program startup.
  • 'Continuation variables' to display longer texts with less code.
All in all, the Wizard's Apprentice makes it even easier to make your scripts look professional!

April 2003

The latest version of the Wizard's Apprentice is version 1.3. These are the most important improvements in this version:
  • The Wizard's Apprentice now supports unlimited size for the value of environment variables. This is especially useful if you select many items from a listbox.
  • A new feature was added to the file browser: filter strings. They will allow you to let the user choose files with a certain extension more easily.

Dion Nicolaas

The Wizard's Apprentice's Home