Wizard's Apprentice

Main

Manual

Overview
Syntax
Using the Wizard's Apprentice
Control flow
Advanced batch techniques
An annotated example
Command reference

Download



SourceForge.net Logo


*  The Wizard's Apprentice  *

Making batch files interactive

*Overview

The Wizard's Apprentice is a 32-bits Windows application (i.e. it works on Windows 95/98/Me/NT/200/Xp) that lets you display a dialog box on the screen. It is meant to be executed from a batch file, adding a way to ask the user questions in a friendly way.

The Wizard's Apprentice shows dialogs in the so-called 'wizard-style': large dialogs with a Back, a Next and a Cancel button, some explanatory text and one control where the user can choose something. You can choose from several different controls:

Text screen
No extra control, but an extra large text box, e.g. for a welcome text.
File contents
A box with a scroll bar on it, in which a file is displayed. Can be used to display a license text.
Edit field
An edit field where the user can type text.
Radio buttons
A set of up to ten radio buttons.
Checkboxes
A set of up to ten check boxes.
Listbox
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. Stand-in for radio buttons or checkboxes if you have more than ten.
Combo box
A combo box allows you to select an item from a list, or type it yourself.
File- or directory browser
An edit field with a Browse button next to it. Pressing the Browse button will either show an open file dialog, or a directory tree dialog.

Apart from that, the Wizard's Apprentice can also display a simple message box with the information, exclamation or stop icon, or with the question icon and an OK and a Cancel button.

With a little batch programming, you can use the Wizard's Apprentice to create simple wizards for installing things, starting programs, or automating simple tasks. If you need to do serious text processing, or complicated calculations, the Wizard's Apprentice won't help; but if you want to write attractive batch files with user interaction, the Wizard's Apprentice might be just for you.

This manual is divided into two parts: the first half is an elaborate tutorial on how to use the Wizard's Apprentice in batch files, with a lot of information in batch programming techniques to get the most out if it. The second half is a reference manual for the Wizard's Apprentice, with a full explanation of all commands.

*Syntax

wizapp MB <type>

type = INFORMATION | EXCLAMATION | STOP | QUESTION

or

wizapp [ NOBACK ] [ FINISH ] <command> [ <options> ]

command = CB | CL | EB | FB | FT | LB | MB | RB
options are command specific options

-Environment variables

watitleSets the title of the dialog
watextSets the text of the dialog
wasigSets the bottom-left signature text of the dialog
waeolSets the End-of-Line character for watext
wainputSets the list for radiobuttons, checkboxes, listboxes and comboboxes
walistsepSets the list separator for wainput and other lists
wafileAlternatively sets the list for radiobuttons, checkboxes, listboxes and comboboxes
wabmpSets the picture for wizard-style dialogs
waicoSets the icon for wizard-style dialogs
walabelsSets the labels for the Back, Next, Finish and Browse button for wizard-style dialogs
wabatSets the batch file that returns user choices
waoutputSets a control's default; contains the user's string after calling wabat
waoutnumSets a control's default; contains the user's index after calling wabat
waprefixSets the variables's prefix to something else than wa

-Error level returned

0The Next button or OK button was pressed
1The Back button was pressed
2The Cancel button was pressed
255An error ocurred

*Using the Wizard's Apprentice

Using the Wizard's Apprentice is a four-step process:

  1. Set the environment variables
  2. Call the program with the correct command line parameters
  3. Examine the errorlevel returned
  4. Examine the environment variables returned

Let's look at a small example:

  1.  set watitle=Important question
  2.  set watext=This is an important question.~Are you sure?~~Press OK if you are.~Press Cancel if you're not sure.
  3.  start /w wizapp MB QUES
  4.  if errorlevel 2 echo You're not sure.
  5.  if errorlevel 0 if not errorlevel 2 echo You're sure.

This batch file will show a message box on the screen that looks like this:

Screenshot of a messagebox

It will then print (on the console window you started the batch file from) either "You're not sure", if you pressed Cancel, or "You're sure" if you pressed OK.

Line 1 and 2 set two environment variables, watitle and watext, which contain the title and the text of the dialog box, respectively. The next line calls the application. This is done using the start command; start /w makes sure that the batch file waits until the application is finished. This is not necessary on Windows NT, but on Windows 95/98 the batch file will go on running otherwise.

The application is called with two command line parameters: MB to display a message box, and QUES to indicate that it should have the question mark icon and two buttons, OK and Cancel.

Line 4 and 5 look at the errorlevel returned by the application. Errorlevel 2 means "Cancel is pressed", errorlevel 1 means "OK is pressed". Errorlevel 1 was left out here; it means "Back pressed" in wizard-style dialogs, but a message box does not have a Back button.

Note the way line 5 is written: if errorlevel 2 is true, that means that errorlevel 1 and errorlevel 0 are also true; all lower errorlevels are always true when an errorlevel is set. That's why it is explicitly stated that errorlevel 2 should not be true.

For another example, let's take a look at the code for a typical 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

watitle and watext are set just as in the previous example. watext contains some '~' characters, which are converted to a line break in the output. This moves the line a little bit downwards; the text area in wizard-style dialogs is always the same size, so if you have only little text it looks nicer that way.

In line 3, wainput is set, which contains the choices the user will have. In every choice, you can precede a character with an '&' character; this character will be underlined in the dialog box and can be used as a hotkey for that choice. In a batch file, '&' characters have a special meaning; that's why they must be escaped using the '^' character.

Line 4 sets the environment variable waoutnum. It has two functions; when you set it before the dialog is displayed, it sets the default choice in the dialog; afterwards, it will contain the choice the user made. Here we set it to '0', which denotes the first choice in the list, in this case English.

Line 5 sets the picture of the dialog. It is a drawing that appears on the left side in the dialog. It should be a .bmp file. The picture is not resized, so you should make sure it more or less fits the dialog. If you do not specify a picture you will get the default picture.

Line 6 sets the variable wabat, which contains the name of the batch file used to return values. The batch file is called in line 10, directly after the Wizard's Apprentice was executed. This is the only way to set variables in the batch file's environment; the Wizard's Apprentice cannot directly change variables in the batch file's environment, as it only receives a copy of that environment when it is executed. Therefore it creates another batch file, which you can call to retrieve the results of the dialog.

If you do not set wabat to a valid batch file name, you will not be able to find out what the user answered. %TEMP%\wabat.bat probably is a safe name, but the choice is yours.

Here's the dialog that will be displayed when you run this batch file:

Screenshot of a language 
    selection dialog

Line 8 and 9 examine the errorlevel set by the dialog. In this case, we do have a Back button, so we go to another place in the batch file when that button is pressed (the label :previous in this case.) Since the lines after a goto are not reached, we do not need to use the if errorlevel if not errorlevel construct here.

Line 11 to 16 evaluate the value of the environment variable waoutnum to see which choice the user made. I this case, the choice is only printed to the screen; in reality, you would probably write something like:

  1.   :english
  2.   if not "%waoutnum"=="0" goto :french
  3.   rem Do things for English
  4.   goto :endlang
  5.   :french
  6.   if not "%waoutnum"=="1" goto :german
  7.   rem Do things for French
  8.   goto :endlang
  9.   :german
  10.   if not ...
  11.   etc.
  12.  
  13.   :endlang
  14.   rem Rest of batch file
  15.   ...

In a typical wizard, you would probably have more than one wizard page. The following section will explain how you can create a wizard that behaves as you would expect.

*Control flow

The previous section showed the basic use of the Wizard's Apprentice. In this section, it is shown how to use a batch file to create a wizard-like application.

A wizard usually starts with a welcome screen, telling the user what will follow. It then asks the user to make choices, allowing him or her to go back and forth to review these choices, until in the end the actual work is done. If at any moment the user presses the Cancel button, a confirmation dialog is shown, where the user can choose to really quit or to go on where he or she left. It is of course possible that the answer to a question changes the question asked afterwards; if the answer to "Do you want to make a backup of the old files?" is "No", you don't have to ask in which directory to make the backup.

All of these principles can be easily expressed in batch files. You have to think of a lot of details to make it work as intended, though. This section will explain how to do it.

-Basic outline of the batch file

When creating a wizard, you should keep in mind that the user expects to be able to go back and forth between pages, reviewing his or her choices, until finally he or she is satisfied with it and hits the Finish button. Usually, the title and the picture of the wizard pages don't change in between. A basic outline for a batch file should be as follows:

  1.   set wabmp=picture.bmp
  2.   set watitle=My Wizard version 0.1
  3.   set wabat=%TEMP%wabat.bat

These values only need to be set once, so why no do it right in the beginning.

  1.   set waeol=
  2.   set wainput=
  3.   set walistsep=
  4.   set wafile=
  5.   set walabels=
  6.   set waico=
  7.   set wasig=
  8.   set waoutput=
  9.   set waoutnum=

It is alway possible that these variables were set in previous sessions. Here we make sure that no unintended things happen.

  1.   set name=
  2.   set lang=0
  3.   ...

Here you set your own defaults, if any. These are of course examples only.

  1.   :page1
  2.   ...
  3.   :page2
  4.   ...

The actual pages of your wizard.

  1.   ... Do the actual work, based on the values gathered!
  2.   :exit
  3.   if exist %wabat% del %wabat%
  4.   set watitle=
  5.   set watext=
  6.   set wainput=
  7.   set wafile=
  8.   set wabmp=
  9.   set walabels=
  10.   set waico=
  11.   set wasig=
  12.   set wabat=
  13.   set waoutput=
  14.   set waoutnum=

After the wizard, you do the actual work; and after everything is finished, you clean up the stuff you left behind.

-The welcome screen and the finish page

Usually, the first page of a wizard contains a welcome text, outlining what is going to happen next. However, it is very well possible that the first screen contains a control, and asks a first question already. The only thing that makes the first page special is that it doesn't have a Back button.

This is achieved in the Wizard's Apprentice with the NOBACK parameter. If you call the Wizard's Apprentice as follows:

    start /w wizapp NOBACK TB

it will show a textbox (because of the TB parameter), but no Back button.

Similarly, if you call the Wizard's apprentice like this:

    start /w wizapp FINISH TB

it will use a Finish button instead of a Next button. The only difference between a Finish button and a Next button is the label; the Wizard's Apprentice will return errorlevel 0, just as if the Next button was pressed.

You can also have both:

    start /w wizapp NOBACK FINISH CL

This is a very short wizard, asking only one question and finishing immediately.

-Going back and forth

If you have more than one page in your wizard, you must make sure that the Back button and the Next button work as intended. The trick to accomplish this is to look at the errorlevel that is returned. Here's an outline for a wizard with three pages:

  1.   :page1
  2.   start /w wizapp NOBACK TB
  3.   if errorlevel 2 goto :cancel
  4.   rem errorlevel 1 is impossible, no back button!
  5.   :page2
  6.   start /w wizapp LB
  7.   if errorlevel 2 goto :cancel
  8.   if errorlevel 1 goto :page1
  9.   :page3
  10.   start /w wizapp FINISH TB
  11.   if errorlevel 2 goto :cancel
  12.   if errorlevel 1 goto :page2
  13.   rem The wizard has ended: do the work!
  14.   ...
  15.   :cancel

Line 1, 5 and 9 are labels, set in the beginning of a page's handling. If in any page the Back button is hit, the batch file jumps back to the label of the previous page, redisplaying that page. Those jumps are in line 8 and 12. If the Next button is hit, the errorlevel is 0; in that case, no jump is done, so the batch file execution just continues with the next line. If the errorlevel is 2, the cancel button is pressed; here we just jump to the :cancel label, which terminates the batch file without doing anything.

A really nice wizard always remembers the choices that you made earlier, so that if you go back and forth, you don't have to make your choices again. This is done by setting the variables waoutput or waoutnum before displaying a wizard page; the values set serve as a default. Here's an example of how to handle that:
  1.   rem Beginning of batch file: set defaults
  2.   set name=Nobody
  3.   ...
  4.   :page12
  5.   set page=:page12
  6.   set wabat=%TEMP%\wabat.bat
  7.   set watext=Enter your name:
  8.   set waoutput=%name%
  9.   start /w wizapp EB
  10.   if errorlevel 2 goto :cancel
  11.   if errorlevel 1 goto :page11
  12.   call %wabat%
  13.   set name=%waoutput%
  14.   ...

Before the wizard is started, the batch file sets defaults for all the information needed. As an example, her name is set to "Nobody" in line 2.

Before asking the user to enter his or her name, waoutput is set to the value of name that we now have; initially that is "Nobody". Setting waoutput has the effect that that value is filled in in the editbox when it is displayed.

After the page was displayed, name is set to the value the user entered (in line 13.) This makes sure that if we ever return to this page (e.g. by pressing the Back button in page 13) that value is used as the initial value in the edit box.

-The Cancel confirmation dialog

For a more sophisticated handling of the cancel button, a slightly more complex batch file is needed:

  1.   :page6
  2.   set page=:page6
  3.   start /w wizapp LB
  4.   if errorlevel 2 goto :cancel
  5.   if errorlevel 1 goto :page5
  6.   ...
  7.   goto :exit
  8.   :cancel
  9.   set watext=Do you want to abort this wizard?
  10.   start /w wizapp MB QUES
  11.   if errorlevel 2 goto %page%
  12.   :exit

In line 2, we set the environment variable page to :page6. This is the label of the page that is currently handled. Then the page is displayed in line 3. If the user hit the Cancel button, we jump to the :cancel label just as before, but this time a message box is displayed, with a confirmation question (lines 9 and 10.) If the user answers "No" to the question, we jump back to the label %page%, which is of course the label :page6.

We can now include the set page= statement for every page, and go to the same :cancel label every time; we then always return to the page where we left. If the user confirms the question, though, the batch file execution continues at line 12, where the batch file ends.

The goto :exit in line 7 is needed to make sure we don't fall through into the cancel dialog handling after the whole wizard is finished. Together with setting page to the return point, this is a common technique to simulate subroutines in batch files.

-Skipping pages

Sometimes, the answer to one question takes away the need of displaying another page of a wizard. We then need a way to skip a certain page in the wizard. The main complication here is that a wizard can be traversed in two directions, since the user can press the Next or the Back button. Here's an outline that shows how to handle that situation.

  1.   :page4
  2.   set page=:page4
  3.   set wabat=%TEMP%\wabat.bat
  4.   set watext=Should a backup be made?
  5.   set wainput=Make a backup;Don't make a backup
  6.   set waoutnum=%dobackup%
  7.   start /w wizapp RB
  8.   if errorlevel 2 goto :cancel
  9.   if errorlevel 1 goto :page3
  10.   call %wabat%
  11.   if "%waoutnum"=="1" set dobackup=1
  12.   if "%waoutnum"=="0" set dobackup=0
  13.   :page5
  14.   if "%dobackup%"=="0" if %page%==:page4 goto page6
  15.   if "%dobackup%"=="0" if %page%==:page6 goto page4
  16.   set page=:page5
  17.   set watext=Choose a directory for the backup.
  18.   start /w wizapp FB DIR
  19.   if errorlevel 2 goto :cancel
  20.   if errorlevel 1 goto :page5
  21.   ...
  22.   :page6
  23.   set page=:page6

In line 3 to 6, the environment variables are set to show radio buttons on the screen, offering the choices "Make a backup" and "Don't make a backup" to the user. Line 11 and 12 examine the answer given, and set the variable dobackup accordingly.

If the user chose not to make a backup, page 5 can be skipped. This is what is done in line 14. However, line 14 also check from which page the user came; if page is :page4, the user pressed the Next button on that page, so we should skip to page 6. Line 15 handles the case where the user pressed the Back button in page 6 in a similar way; it then jumps back to page 4.

*Advanced batch techniques

Now that we have a nice way to add a user interface to batch files, a lot of possibilities open up. Although it strictly is not within the scope of this manual to teach batch programming, this section outlines a few useful but sometimes strange techniques to get things done in batch files. For more elaborate work on batch programming, consult the following websites:

-Checking whether a filename or directory name is valid

This seemingly simple problem has a lot of strange subtleties. First of all, there are two different cases: checking whether a file exists, or checking whether it could be created. Then there is a difference between Windows 95/98 and Windows NT. A solution that works for all cases does not exist, but these techniques come close.

Here's a simple check whether a file exists:

    rem Check if file exists
    if exist "%file%" echo File exists!

That is the most easy case. However, on Windows NT this will also work when %file% is a directory. The old trick of checking for %file%\nul is not working with long file names, so there is no other choice than to use dir and find:

    dir "%file%" | find "Directory of" | find /i "%file%"
    if errorlevel 1 echo Directory does not exist!

What is done here is that a directory listing of the specified file is made; Then we search the line containing Directory of <dir>, and check whether the name appears on that line. A catch here is that if %file% contains double quotes, the find command does not work.

A simple batch file to remove double quotes that are not necessary:

    @echo off
    rem UnQuote.bat: removes quotes from %1,
    rem setting the variable in %2
    mkdir TMP###TMP
    cd TMP###TMP
    echo Test > %1
    for %%f in (*.*) do set %2=%%f
    cd ..
    rmdir /s /q TMP###TMP

Here's how to use it:

    @echo off
    set file="A long file name"
    echo %file%
    call unquote %file% file
    echo %file%

The output of this batch file is

    "A long file name"
    A long file name

Another way to check whether a directory exists is to write a file to it:

    echo This is a test > "%file%\tmp.tmp"
    if exist "%file%\tmp.tmp" echo Directory is writable!
    if exist "%file%\tmp.tmp" del "%file%\tmp.tmp"

Caution: If the file tmp.tmp already existed in the directory, it is lost, so you should first check for that.

A similar trick can be used to see whether a file is writable:
    echo This is a test > "%file%"
    if exist "%file%" echo File is writable!
    if exist "%file%" del "%file%"

Before doing this, you should check whether a file of that name already exists, or else it will be deleted.

A similar problem is to check whether a filename contains wildcards, e.g. '?' or '*'. Here is how to do that:

    for %%f in ("%file%") do if %%f=="%file" goto :nowild
    echo "%file%" contains wildcards!
    goto :end
    :nowild
    echo "%file%" contains no wildcards!
    :end 

This for command matches %%f with every file that is in the set %file%. If that is only one file, %%f equals "%file%" in the test. Note that this again only works if %file% does not contain quotes.

-pushd, popd, extended for command

If you are using Windows NT, 2000 or Xp there are a few more commands that are worth looking at. Here is a short summary; refer to the Windows Help file for a detailed explanation.

CommandMeaning
pushdSwitch to another directory, but remember the directory we come from.
popdSwitch back to the directory we came from with the last pushd.
for /dSame as for %%f in (), but loops only over directories.
for /rSame as for %%f in (), but loops over a whole directory tree.
for /f Loop over the lines in a file, or over the lines of the output of a command.

-.inf file for creating shortcuts

Creating a shortcut in a batch file involves some very black magic, even though it seems simple. For a good explanation of how to do it, read the following web site:

Basically, it involves creating a .inf file and then calling RunDLL to do the job. I'll give an example here.

Assume you want a shortcut to the file "c:\winnt\notepad.exe" in the directory "c:\temp", and you want it named "Another Notepad Shortcut". You'd write the following .inf file:

  1.   [version]
  2.   signature=$chicago$
  3.   [DefaultInstall]
  4.   UpdateInis=AddLink
  5.   [AddLink]
  6.   setup.ini, progman.groups,, ""group1="c:\temp\"""
  7.   setup.ini, group1,,"""Another Notepad Shortcut"",""c:\winnt\notepad.exe"""

Don't get distracted by all the double quotes; there is some system in this mess. First of all, both lines in the [AddLink] section consist of four, comma-separated parts: setup.ini, a group name, an empty part and one last part, that is enclosed in quotes. Secondly, witin this last part, every sub-part is quoted; and thirdly, every filename and the shortcut name is quoted.

To actually create this shortcut, you run the following command:

            
    start /w rundll32.exe setupapi,InstallHinfSection
        DefaultInstall 132 <inffile>

All on one line, with no spaces but one comma between setupapi and InstallHinfSection, and with the full path name of your .inf file as the last argument. This will magically create a shortcut file, which you can then move around if you want to.

*An annotated example

This section contains an example batch file that illustrates most of the techniques explained before. Note that this batch file comes with your Wizard's Apprentice distribution as wainstall.cmd; you can actually run it to see how it works.

This batch file is a simple installer for the Wizard's Apprentice itself. It will first show a welcome screen and a license text. It will then ask to user for a directory to install the program in, and ask whether the user wants to create some shortcuts. Finally, it will install the program according to the options set.

  1.  @echo off
  2.  rem The Wizard's Apprentice Installer 1.00
  3.  rem Example file that goes with the Wizard's Apprentice.
  4.  rem The Wizard's Apprentice may be freely distributed.
  5.  rem See license for details.
  6.  
  7.  rem Set the title, the bitmap and the return batch file
  8.  rem for this wizard, and initialise all ather wa
  9.  rem variables in case any old values are left over.
  10.  set wabmp=
  11.  set watitle=Wizard's Apprentice Installation 1.00
  12.  set wabat=%TEMP%\wabat.bat
  13.  rem remove any leftovers
  14.  set waprefix=
  15.  set waeol=
  16.  set wainput=
  17.  set wafile=
  18.  set walistsep=
  19.  set walabels=
  20.  set wasig=
  21.  set waico=
  22.  set waoutput=
  23.  set waoutnum=
  24.  rem Initialise the variables this wizard needs.
  25.  set notinpath=0
  26.  set installdir=
  27.  set i0=1
  28.  set i1=1
  29.  set installgroup=Wizard's Apprentice
  30.  rem Start the wizard.
  31.  
  32.  :page1
  33.  rem We set the page variable to be able to return here
  34.  rem after a Cancel request.
  35.  set page=:page1
  36.  set watext=Welcome to the Wizard's Apprentice setup
  37.  set watext=%watext%~~~The Wizard's Apprentice adds an interface to your batch programs:
  38.  set watext=%watext%~~* Use message boxes for simple questions
  39.  set watext=%watext%~* Tickboxes, radiobuttons and listboxes
  40.  set watext=%watext%~* Display files, e.g. licenses
  41.  set watext=%watext%~* Configurable buttons, picture and title
  42.  set watext=%watext%~* File and directory box with Browse button
  43.  set watext=%watext%~* Sample batch files and comprehensive manual
  44.  set watext=%watext%~~... and the Wizard's Apprentice is free!
  45.  set watext=%watext%~~~Press the [Next] button to start the installation.
  46.  start /w wizapp NOBACK TB
  47.  if errorlevel 2 goto :cancel
  48.  rem no Back possible
  49.  
  50.  :page2
  51.  set page=:page2
  52.  set watext=Software License Agreement
  53.  set watext=%watext%~~Although the Wizard's Apprentice is free, there still is a license, which means as much as: "Don't blame me when anything goes wrong". Hit the [I Accept] button to continue installing.
  54.  rem wafile contains the contents for the license box.
  55.  set wafile=license.txt
  56.  set wainput=
  57.  rem The ^ is necessary to escape the ampersand on NT,
  58.  rem The ampersand puts in a hotkey.
  59.  if "%OS%"=="Windows_NT" set walabels=;I ^&Accept;;I ^&Disagree;
  60.  if not "%OS%"=="Windows_NT" set walabels=;I &Accept;;I &Disagree;
  61.  start /w wizapp FT
  62.  rem Don't forget to immediately set wafile to empty;
  63.  rem if both wafile and wainput are set, wafile wins.
  64.  set wafile=
  65.  rem And set the labels back to normal.
  66.  set walabels=
  67.  if errorlevel 2 goto :exit
  68.  if errorlevel 1 goto page1
  69.  
  70.  :page3
  71.  set page=:page3
  72.  set watext=Do you want to install the Wizard's Apprentice in a directory in your PATH?
  73.  set watext=%watext%~~If you install in your PATH, the Wizard's Apprentice will be available everywhere on you computer.
  74.  set watext=%watext%~If you don't, it has to reside in the same directory as the batch file that uses it.
  75.  rem Set the radiobutton options
  76.  if "%OS%"=="Windows_NT" set wainput=Install in my ^&PATH;Install in ^&another directory
  77.  if not "%OS%"=="Windows_NT" set wainput=Install in my &PATH;Install in &another directory
  78.  rem Set the initially checked choice
  79.  set waoutnum=%notinpath%
  80.  set waoutput=
  81.  start /w wizapp RB
  82.  if errorlevel 2 goto :cancel
  83.  if errorlevel 1 goto page2
  84.  rem Retrieve the user's choice
  85.  call %wabat%
  86.  rem and store it
  87.  set notinpath=%waoutnum%
  88.  
  89.  rem Now we have the choice: Either we show a dialog
  90.  rem that shows all directories in the path, or we show
  91.  rem a normal directory browser. First comes the PATH
  92.  rem chooser.
  93.  :page4
  94.  rem Check whether we should display this page at all;
  95.  rem skip it if we shouldn't. The user can come from
  96.  rem the previous page (after pressing the Next button)
  97.  rem or from the next page (with the Back button);
  98.  rem handle both case.
  99.  if %notinpath%==1 if %page%==:page3 goto :page5
  100.  if %notinpath%==1 if %page%==:page5 goto :page3
  101.  rem Now that we got here, we do want to display this
  102.  rem page.
  103.  set page=:page4
  104.  set watext=Select Destination Directory in your PATH
  105.  set watext=%watext%~~~~Please select the directory in your PATH where the Wizard's Apprentice should be installed.
  106.  set waoutput=%installdir%
  107.  set waoutnum=
  108.  set wainput=%PATH%
  109.  start /w wizapp LB SINGLE
  110.  if errorlevel 2 goto :cancel
  111.  if errorlevel 1 goto page3
  112.  rem Retrieve the user's choice
  113.  call %wabat%
  114.  rem and store it
  115.  set installdir=%waoutput%
  116.  
  117.  rem Next comes the normal directory browser.
  118.  :page5
  119.  if %notinpath%==0 if %page%==:page4 goto :page6
  120.  if %notinpath%==0 if %page%==:page6 goto :page4
  121.  set page=:page5
  122.  set watext=Select Destination Directory
  123.  set watext=%watext%~~~~Please select the directory where the Wizard's Apprentice should be installed.
  124.  set waoutput=%installdir%
  125.  set waoutnum=
  126.  start /w wizapp FB DIR
  127.  if errorlevel 2 goto :cancel
  128.  if errorlevel 1 goto page4
  129.  rem Retrieve the user's choice
  130.  call %wabat%
  131.  rem and store it
  132.  set installdir=%waoutput%
  133.  
  134.  :page6
  135.  set page=:page6
  136.  set watext=Icon Creation
  137.  set watext=%watext%~~~~Should the installer create a desktop icon or a shortcut in the start menu for the Wizard's Apprentice's Manual?
  138.  if "%OS%"=="Windows_NT" set wainput=Add manual to ^&Start Menu;Add manual icon to ^&Desktop
  139.  if not "%OS%"=="Windows_NT" set wainput=Add manual to &Start Menu;Add manual icon to &Desktop
  140.  rem By setting waoutnum we specify the default value.
  141.  set waoutnum=
  142.  if %i0%==1 set waoutnum=0;
  143.  if %i1%==1 set waoutnum=%waoutnum%1;
  144.  set waoutput=
  145.  start /w wizapp CL
  146.  if errorlevel 2 goto :cancel
  147.  if errorlevel 1 goto page5
  148.  call %wabat%
  149.  rem Here's a trick to dissect the list that was
  150.  rem returned. These for commands create variables named
  151.  rem i0, i1
  152.  for %%n in (0 1) do set i%%n=0
  153.  rem i0 is only set if 0 is in the list. i1 will only be
  154.  rem set if 1 is in the list, etc.
  155.  for %%n in (%waoutnum%) do set i%%n=1
  156.  
  157.  :page7
  158.  rem Here we have another page that we sometimes must
  159.  rem skip, depending on the value of i0.
  160.  if "%i0%"=="0" if %page%==:page6 goto page8
  161.  if "%i0%"=="0" if %page%==:page8 goto page6
  162.  set page=:page7
  163.  rem find all the groups in the user's start menu.
  164.  set userdir=%USERPROFILE%
  165.  rem USERPROFILE is not set on Windows 95/98.
  166.  rem This solution isn't entirely correct on
  167.  rem Windows 9x, as you might have profiles
  168.  rem enabled, but it is better than nothing.
  169.  rem For a better solution, see the websites
  170.  rem referred to in the manual.
  171.  if "%USERPROFILE%"=="" set userdir=%windir%
  172.  rem If wafile is set, it's contents will be
  173.  rem used instead of wainput. So we build the
  174.  rem directory list in a file. Note that
  175.  rem walistsep is not used then; every line
  176.  rem is an item.
  177.  set wafile=%TEMP%\wafile
  178.  rem dir /ad lists only directories, /b means
  179.  rem bare output (only names)
  180.  dir /ad /b "%userdir%\Start Menu\Programs" > %wafile%
  181.  set wainput=
  182.  rem Now we have the list for the combobox; Setting
  183.  rem waoutput sets the default for the combobox's
  184.  rem editfield.
  185.  set waoutput=%installgroup%
  186.  set waoutnum=
  187.  set watext=Select Group
  188.  set watext=%watext%~~~~Enter the name of program group to add the manual icon to.
  189.  start /w wizapp CB
  190.  rem Don't forget to immediately set wafile to empty;
  191.  rem if both wafile and wainput are set, wafile wins.
  192.  set wafile=
  193.  if errorlevel 2 goto :cancel
  194.  if errorlevel 1 goto page6
  195.  call %wabat%
  196.  set installgroup=%waoutput%
  197.  
  198.  :page8
  199.  set page=:page8
  200.  set watext=Ready to Install!
  201.  set watext=%watext%~~~~Press the [Install] button to begin the installation or the [Back] button to reenter the installation information.~
  202.  set wainput=Installation directory: %installdir%
  203.  if %i0%==1 set wainput=%wainput%~Install a shortcut to the manual in program group: %installgroup%
  204.  if %i1%==1 set wainput=%wainput%~Install a shortcut to the manual on your Desktop
  205.  if "%OS%"=="Windows_NT" set walabels=;;^&Install;;
  206.  if not "%OS%"=="Windows_NT" set walabels=;;&Install;;
  207.  rem Here we use a file text box with only a few
  208.  rem lines of text, so we use wainput instead of
  209.  rem wafile.
  210.  start /w wizapp FINISH FT
  211.  if errorlevel 2 goto :cancel
  212.  if errorlevel 1 goto page7
  213.  
  214.  rem Here we are, after the user pressed the Install
  215.  rem button. Let's install! Just create the directory
  216.  rem and ignore the error message if it does not work.
  217.  mkdir "%installdir%"
  218.  rem By specifying a complete path name for the
  219.  rem destination we make sure the copy fails if the
  220.  rem directory name is not valid.
  221.  for %%f in ("wizapp.exe" "wainstall.bat" "wizapp.css" "index.html" "manual.html" "download.html" "*.png" "*.txt") do copy "%%f" "%installdir%\%%f"
  222.  rem No create the shortcut, first in %TEMP%
  223.  set linkname=The Wizard's Apprentice's Manual
  224.  rem Create an .inf file, also in %TEMP%
  225.  echo [version] > %TEMP%\tmp.inf
  226.  echo signature=$chicago$ >> %TEMP%\tmp.inf
  227.  echo [DefaultInstall] >> %TEMP%\tmp.inf
  228.  echo UpdateInis=AddLink >> %TEMP%\tmp.inf
  229.  echo [AddLink] >> %TEMP%\tmp.inf
  230.  echo setup.ini, progman.groups,, ""group1="%TEMP%""" >> %TEMP%\tmp.inf
  231.  echo setup.ini, group1,, """%linkname%"", ""%installdir%\manual.html""" >> %TEMP%\tmp.inf
  232.  rem Create the link
  233.  start /w rundll32.exe setupapi,InstallHinfSection DefaultInstall 132 %TEMP%\tmp.inf
  234.  del %TEMP%\tmp.inf
  235.  rem Copy it to wherever we wanted
  236.  if i0==0 goto :desktop
  237.  rem Just create the directory and ignore the error
  238.  rem message if it does work.
  239.  mkdir "%userdir%\Start Menu\Programs\%installgroup%"
  240.  rem Again, by using the full name the copying is
  241.  rem reasonably safe.
  242.  copy "%TEMP%\%linkname%.lnk" "%userdir%\Start Menu\Programs\%installgroup%\%linkname%.lnk"
  243.  :desktop
  244.  if i1==0 goto :linkdone
  245.  copy "%TEMP%\%linkname%.lnk" "%userdir%\Desktop\%linkname%.lnk"
  246.  :linkdone
  247.  set watext=Installation completed!
  248.  start /w wizapp MB INFO
  249.  
  250.  goto :exit
  251.  
  252.  :cancel
  253.  set watext=Do you want to abort this installation?
  254.  start /w wizapp MB QUES
  255.  if errorlevel 2 goto %page%
  256.  
  257.  :exit
  258.  if exist %wabat% del %wabat%
  259.  set userdir=
  260.  set installdir=
  261.  set installgroup=
  262.  set linkname=
  263.  set notinpath=
  264.  set page=
  265.  set i0=
  266.  set i1=
  267.  
  268.  set watitle=
  269.  set watext=
  270.  set wainput=
  271.  set wafile=
  272.  set wabmp=
  273.  set walabels=
  274.  set wasig=
  275.  set waico=
  276.  set wabat=
  277.  set waoutput=
  278.  set waoutnum=

*Command reference

This section contains a complete reference of all commands the Wizard's Apprentice knows, in alphabetical order. For each command, it is explained what environment variables it uses and what it does.

-General

Global options

You can specify global options before the command on the command line.

NOBACKDo not display a Back button on a wizard-style dialog.
FINISHDisplay a Finish button on a wizard-style dialog, instead of a Next button.

Command line abbreviations

Every option to the Wizard's Apprentice, both global options and command specific options, can be abbreviated by leaving out letters, as long as the result is unambiguous. e.g.

    start /w wizapp NOB LB S
    start /w wizapp MB INFO

is the same as

    start /w wizapp NOBACK LB SINGLE
    start /w wizapp MB INFORMATION

It is recommended not to abbreviate too much; MULTI instead of MULTIPLE is understandable, but

    start /w wizapp N F FB F

is not so easy to grok at first sight.

Errorlevel returned

For each command, the Wizard's Apprentice returns the same errorlevel:

0The Next button or OK button was pressed.
1The Back button was pressed.
2The Cancel button was pressed.
255An error ocurred.

If the NOBACK option was used, errorlevel 1 will never be returned. If the FINISH option was used, and the Finish button was pressed, the Wizard's Apprentice returns errorlevel 0, just as if the Next button was pressed.

The waico variable

Just as you can set the sidebar bitmap of the wizard style dialogs, you can set the icon of these dialogs using the waico variable. It should contain the filename of an .ico file which will be used as the icon for the application. If you do not specify an icon, the default icon will be used.

waico Sets the icon for wizard-style dialogs

The wasig variable

In the bottom-left corner of the wizard-style dialogs the name and version number of the application is shown. You can replace this text with one of your own by setting the wasig variable. You should make sure the text is not too long, or it will be truncated.

wasig Sets the bottom-left signature text of the dialog

wainput and wafile

Usually you set the contents of a listbox, checklist, radiobutton set or combobox using the wainput variable, but if the wafile variable is set, the contents of the file it points to are used. The items in this file are not separated by the list separator; instead, every line in the file denotes one item.

The returned values for waoutput and waoutnum will still use list separators if they contain multiple values, e.g. from a checklist.

Similarly, you usually use wafile for a filetext box, but you can also use wainput for that if you have only little text. In that case, the list separator is just displayed, but the End-of-line character is used to split the input into lines.

If you set both wafile and wainput, wafile wins; that means the contents of the file are used, and the contents of wainput are discarded.

The walabels variable

The labels for the Back, Next, Finish and Browse buttons in wizard-style dialogs are normally "Back", "Next", "Finish" and "Browse" respectively. The walabels variable can be set to a list of other names for the buttons, by specifying the names in this order: Back, Next, Finish, Browse.

walabels Sets the labels for the Back, Next, Finish and Browse button for wizard-style dialogs

If you leave a label empty, the Wizard's Apprentice will use the default label, so you can change only the label of the Next button as follows:

    set walabels=;I accept

You can set hotkeys for the buttons by prefixing a letter in the button label with an '&' character. If you use Windows NT, you have to escape the '&' character with a '^' character in your batch file. E.g.

    set walabels=Vo^&rige;^&Volgende;^&Einde;^&Blader

sets the labels in Dutch, with 'R', 'V', 'E' and 'B' as hotkeys, respectively.

On Windows 95/98 you should not escape the '&' characters. If you want to write a batch file that works on both Windows 95/98 and NT, you can use the following test:

    if "%OS%"=="Windows_NT" set walabels=;;^&Install;
    if not "%OS%"=="Windows_NT" set walabels=;;&Install;

the OS variable is also set to Windows_NT on Windows 2000.

The waeol variable

watext and wainput specify the contents of your dialog. You can use the character '~' to put a line break in your contents. If you want to display a '~' character in your contents, you need another character to denote a line break. The line break character can be specified by setting the waeol variable.

waeol Sets the End-of-Line character for watext

The walistsep variable

The wainput variable is used to set the contents of listboxes, radiobuttons, checklists and comboboxes. The default separator between list items is the character ';'. This means you cannot have a ';' character in your list items. You can set a different list separator by specifying the walistsep variable.

walistsep Sets the list separator for wainput and other lists

Note that this character will be used in all lists; this includes the lists that are returned in waoutput annd waoutput, and the list of button labels you specify for walabels.

The waprefix variable

The standard names for the environment variables used by the Wizard's Apprentice all start with wa. It is possible to change this prefix by setting the waprefix variable.

waprefix Sets the variables's prefix to something else than wa

E.g. if you have environment variables with the same names as Wizard's Apprentice variables that you don't want to change, you can use the following code:

    set waprefix=wizapp
    set wizapptext=Are you sure?
    start /w wizapp MB QUESTION

This way, you don't have to use or change the variable watext.

Note that the variable waprefix itself never changes; it always has the prefix wa. If you have another variable of the same name, you should store its value if you want to keep it:

    set oldwaprefix=%waprefix%
    set waprefix=wizapp
    set wizapptext=Are you sure?
    ...
    rem Rest of the Wizard's Apprentice batch file
    ...
    :exit
    set waprefix=%oldwaprefix%

Command overview

CommandMeaningOptions
CBCombobox
CLChecklist
EBEditbox
FBFilebrowserFILE | DIR
FTFiletext
LBListboxSINGLE | MULTI
MBMessageboxINFORMATION | EXCLAMATION | STOP | QUESTION
RBRadiobuttons
TBTextbox

-CB -- Combobox

Syntax

wizapp CB

Variables used

watitle Sets the title of the dialog box.
wasig Sets the bottom-left signature text of the dialog
watext Sets the text of the dialog box.
wabmp Sets the sidebar picture of the dialog box.
waico Sets the icon for wizard-style dialogs
wainput Sets the contents of the listbox part of the combobox.
wafile Alternatively sets the contents of the listbox part of the combobox.
wabat Sets the batch file that is used to return selection information.
waoutput In: Sets the initial (default) text of the editbox part of the combobox;
Out: Returns the item selected or typed by the user.
waoutnum In: Sets the item selected by default in the listbox part of the combobox, which is copied into the editbox part;
Out: Returns the item selected by the user, or the highest possible index + 1 if the user typed something.

Description

This command shows a combobox in a wizard-style dialog on the screen. A combobox is a combination of an editbox and a listbox; the user can type items, or select items from the list.

Screenshot of a dialog with a combobox

The listbox of the combobox can be filled in two ways: by setting wainput or wafile. wainput contains a list of items, separated by the list separator character. wafile is the name of a file in which each line is added as an item to the list. If you set both, wafile gets preference and the contents of wainput are not used.

You can initialise the combobox in two ways: either set waoutnum to a zero-based index in the list, or set waoutput to an item to appear in the editbox. If you do both, the latter wins.

To retrieve the selection the user made you have to set the name of the batch file before displaying the dialog, and call that batch file afterwards:

    set wabat=%TEMP%\wabat.bat
    start /w wizapp CB
    ...
    call %wabat%

You can then examine the value of waoutput and waoutnum. waoutput contains an item from wainput, or the text that the user typed; waoutnum contains a zero-based index in the list, or the highest possible index + 1 if the user typed something that is not in the list. Note: If you do not initialise the combobox, and the user presses Next without doing anything else, waoutput will be empty, and waoutnum will be the highest possible index + 1.

-CL -- Checklist

Syntax

wizapp CL

Variables used

watitle Sets the title of the dialog box.
wasig Sets the bottom-left signature text of the dialog
watext Sets the text of the dialog box.
wabmp Sets the sidebar picture of the dialog box.
waico Sets the icon for wizard-style dialogs
wainput Sets the labels of the checkboxes. Only the first 10 items are used.
wafile Alternatively sets the labels of the checkboxes. Only the first 10 items are used.
wabat Sets the batch file that is used to return selection information.
waoutput In: Sets the items checked by default in the checkboxes;
Out: Returns the items checked by the user.
waoutnum In: Sets the items checked by default in the checkboxes;
Out: Returns the items checked by the user.

Description

This command shows a set of maximum ten checkboxes in a wizard-style dialog on the screen. The user can check zero or more items in the set.

Screenshot of a dialog with a checklist

The labels of the checkboxes can be set in two ways: by setting wainput or wafile. wainput contains a list of labels, separated by the list separator character. wafile is the name of a file in which each line is added as a label to the list. If you set both, wafile gets preference and the contents of wainput are not used.

You can initialise the checklist in two ways: either set waoutnum to a list of zero-based indices in wainput, or set waoutput to a list of items from wainput. All items appearing in any of those lists will be checked.

To retrieve the selection the user made you have to set the name of the batch file before displaying the dialog, and call that batch file afterwards:

    set wabat=%TEMP%\wabat.bat
    start /w wizapp CL
    ...
    call %wabat%

You can then examine the value of waoutput and waoutnum. waoutput contains a set of items from wainput; waoutnum contains a set of zero-based indices in the list. Here's a possible way to extract items from the list:

    for %%c in (0 1 2 3 4 5 6 7 8 9) do set chk%%c=
    for %%c in (%waoutnum%) do set chk%%c=1
    if "%chk0"=="1" echo Item 0 was checked
    if "%chk1"=="1" echo Item 1 was checked
    ...
    if "%chk9"=="1" echo Item 9 was checked

You can never have more than 10 checkboxes. If you have more items to choose from, you can use a multiple selection listbox instead.

-EB -- Editbox

Syntax

wizapp EB

Variables used

watitle Sets the title of the dialog box.
wasig Sets the bottom-left signature text of the dialog
watext Sets the text of the dialog box.
wabmp Sets the sidebar picture of the dialog box.
waico Sets the icon for wizard-style dialogs
wabat Sets the batch file that is used to return selection information.
waoutput In: Sets the initial (default) value filled in in the editbox;
Out: Returns the text typed by the user.

Description

This command shows an editbox in a wizard-style dialog on the screen. The user can type a text in the edit box.

Screenshot of a dialog with an editbox

You can initialise the editbox by setting waoutput beforehand.

To retrieve the text the user typed you have to set the name of the batch file before displaying the dialog, and call that batch file afterwards:

    set wabat=%TEMP%\wabat.bat
    start /w wizapp EB
    ...
    call %wabat%

waoutput then contains the text typed by the user.

-FB -- Filebrowser

Syntax

wizapp FB FILE wizapp FB DIR

Variables used

watitle Sets the title of the dialog box.
wasig Sets the bottom-left signature text of the dialog
watext Sets the text of the dialog box.
wabmp Sets the sidebar picture of the dialog box.
waico Sets the icon for wizard-style dialogs
wabat Sets the batch file that is used to return selection information.
waoutput In: Sets the initial (default) value for the editbox;
Out: Returns the file or directory selected by the user.

Options

FILE Show a file open dialog when the user presses the Browse button.
DIR Show a browse folder dialog when the user presses the Browse button.

Description

This command shows an editbox with a Browse button next to it in a wizard-style dialog on the screen.

Screenshot of a dialog with a filebrowser

When the user presses the Browse button, a file open dialog or a browse folder dialog is shown. Which dialog is shown depends on the option used. If the option is FILE, an open file dialog is shown:

Screenshot of a file open dialog

If the DIR option is used, a folder browser is shown.

Screenshot of a folder browse dialog

When the user chooses a file or directory, it is filled in in the editbox.

You can initialise the editbox of the filebrowser by setting waoutput beforehand.

To retrieve the selection the user made you have to set the name of the batch file before displaying the dialog, and call that batch file afterwards:

    set wabat=%TEMP%\wabat.bat
    start /w wizapp FB
    ...
    call %wabat%

You can then examine the value of waoutput.

Note that waoutput does not necessarily contain a valid file name, as it is also possible that the user typed something into the editbox without using the Browse button. In the section Advanced batch techniques some ways are explained to determine whether a filename or a directory name is valid.

-FT -- Filetext

Syntax

wizapp FT

Variables used

watitle Sets the title of the dialog box.
wasig Sets the bottom-left signature text of the dialog
watext Sets the text of the dialog box.
wafile Sets the contents of the filebox.
wainput Alternatively sets the contents of the filebox.
wabmp Sets the sidebar picture of the dialog box.
waico Sets the icon for wizard-style dialogs

Description

This command shows a textbox in a wizard-style dialog on the screen. The textbox has a scrollbar on the right side, and contains the contents of the file specified in wafile.

If you have only little text, you can set wainput instead of wafile; then wainput is displayed. The End-of-line character can be used to specify line breaks in wainput.

Screenshot of a dialog with a textfile

This command can be used e.g. to display a license text.

-LB -- Listbox

Syntax

wizapp LB SINGLE wizapp LB MULTIPLE

Variables used

watitle Sets the title of the dialog box.
wasig Sets the bottom-left signature text of the dialog
watext Sets the text of the dialog box.
wabmp Sets the sidebar picture of the dialog box.
waico Sets the icon for wizard-style dialogs
wainput Sets the contents of the listbox.
wafile Alternatively sets the contents of the listbox.
wabat Sets the batch file that is used to return selection information.
waoutput In: Sets the items selected by default in the listbox;
Out: Returns the items selected by the user.
waoutnum In: Sets the items selected by default in the listbox;
Out: Returns the items selected by the user.

Options

SINGLE Show a single-selection listbox, i.e. a listbox in which the user can select exactly 1 item.
MULTIPLE Show a multiple-selection listbox; the user can select zero or more items.

Description

This command shows a listbox in a wizard-style dialog on the screen. You can use a listbox if you have too many items for checkboxes or radiobuttons. A single selection listbox always has one item selected, and the user can move the selection.

Screenshot of a dialog with a single-selection listbox

In a multiple-selection listbox the user can use the Shift-key while clicking to select a range of items; the Control-key while clicking to add an item to the selection; or drag with the mouse to select a range of items.

Screenshot of a dialog with a multiple-selection listbox

The contents of the listbox can be set in two ways: by setting wainput or wafile. wainput contains a list of items, separated by the list separator character. wafile is the name of a file in which each line is added as an item to the list. If you set both, wafile gets preference and the contents of wainput are not used.

You can initialise the listbox in two ways: either set waoutnum to a list of zero-based indices in the list, or set waoutput to a list of listitems. All items appearing in any of those lists will be selected. In a single-selection listbox, only one item should be selected; if you accidently specify more, only the last item will be selected.

To retrieve the selection the user made you have to set the name of the batch file before displaying the dialog, and call that batch file afterwards:

    set wabat=%TEMP%\wabat.bat
    start /w wizapp LB
    ...
    call %wabat%

You can then examine the value of waoutput and waoutnum. waoutput contains a list of items from wainput; waoutnum contains a list of zero-based indices in the list. Here's a possible way to extract items from the list:

    for %%s in (0 1 2 3 4 5 6 7 8 9) do set sel%%s=
    for %%s in (%waoutnum%) do set sel%%s=1
    if "%sel0"=="1" echo Item 0 was selected
    if "%sel1"=="1" echo Item 1 was selected
    ...
    if "%sel9"=="1" echo Item 9 was selected

This example works for a listbox with 10 items, although listbox can contain an arbitrary number of items.

If you have less than 10 items, you can use radiobuttons instead of a single selection listbox, or a checklist instead of a multiple selection listbox.

-MB -- Messagebox

Syntax

wizapp MB INFORMATION wizapp MB EXCLAMATION wizapp MB STOP wizapp MB QUESTION

Variables used

watitle Sets the title of the message box
watext Sets the text of the message box

Options

INFORMATION Use the information icon for the message box (a white icon with a blue 'i' in it), and an OK button.
EXCLAMATION Use the exclamation icon for the message box (a yellow triangle with an exclamation mark in it), and an OK button.
STOP Use the stop icon for the message box (a red circle with a cross in it), and an OK button.
QUESTION Use the question icon for the message box (a white icon with a question mark in it), and an OK and a Cancel button.

Description

This command shows a simple message box on the screen, with one of the standard Windows message box icons. The first three options (INFORMATION, EXCLAMATION and STOP) result in a message box with only one button, labeled 'OK'.

Screenshot of an information messagebox  Screenshot of an exclamation messagebox  Screenshot of a stop messagebox 

The QUESTION option gives a dialog box with two buttons, an OK button and a Cancel button.

Screenshot of a question messagebox

You can examine the errorlevel returned to determine which button was pressed.

The labels of the buttons cannot be changed. They will be 'OK' and 'Cancel' in whatever language the version of Windows is that runs on your machine.

-RB -- Radiobuttons

Syntax

wizapp RB

Variables used

watitle Sets the title of the dialog box.
wasig Sets the bottom-left signature text of the dialog
watext Sets the text of the dialog box.
wabmp Sets the sidebar picture of the dialog box.
waico Sets the icon for wizard-style dialogs
wainput Sets the labels for the radiobuttons. Only the first 10 items are used.
wafile Alternatively sets the labels for the radiobuttons. Only the first 10 items are used.
wabat Sets the batch file that is used to return selection information.
waoutput In: Sets the radiobutton selected by default;
Out: Returns the radiobutton selected by the user.
waoutnum In: Sets the radiobutton selected by default;
Out: Returns the radiobutton selected by the user.

Description

This command shows a set of maximum ten radiobuttons in a wizard-style dialog on the screen. A set of radiobuttons always has one item selected.

Screenshot of a dialog with a set of radiobuttons

The labels of the radiobuttons can be set in two ways: by setting wainput or wafile. wainput contains a list of labels, separated by the list separator character. wafile is the name of a file in which each line is added as a label to the buttons. If you set both, wafile gets preference and the contents of wainput are not used.

You can initialise the radiobuttons in two ways: either set waoutnum to a zero-based index in wainput, or set waoutput to an item from wainput. Only one item should be selected; if you accidently specify more, only the last item will be selected.

To retrieve the selection the user made you have to set the name of the batch file before displaying the dialog, and call that batch file afterwards:

    set wabat=%TEMP%\wabat.bat
    start /w wizapp RB
    ...
    call %wabat%

You can then examine the value of waoutput and waoutnum. waoutput contains the item selected from wainput; waoutnum contains a zero-based index in the list.

You can never have more than 10 radio buttons. If you have more items to choose from, you can use a single selection listbox instead.

-TB -- Textbox

Syntax

wizapp TB

Variables used

watitle Sets the title of the dialog box.
wasig Sets the bottom-left signature text of the dialog
watext Sets the text of the dialog box.
wabmp Sets the sidebar picture of the dialog box.
waico Sets the icon for wizard-style dialogs

Description

This command shows a wizard-style dialog on the screen containing only static text. The text can be as large as the dialog.

Screenshot of a dialog with only text

This command can be used for a welcome text in a wizard.


Dion Nicolaas
dionnicolaas@users.sourceforge.net

The Wizard's Apprentice's Home
http://wizapp.sf.net