BTB Wizard Implementation Guide

The Wizard engine in BTB Script provides a structured way to create multi-step graphical, interactive user interfaces within the script, as opposed to simple script prompts. It handles navigation ("Next", "Back", "Cancel") automatically and supports interactive controls, validation, and conditional branching.

---

1. High-Level Syntax

A wizard is defined using a WIZARD...ENDWIZARD block. Inside, the interface is divided into Pages using the *FORM tag.

WIZARD "Wizard Title", [Height], [Width], [AlwaysOnTop]
  ' Page 1 definition
  *FORM
    Name=page1
    Caption=Step 1: Introduction
    Desc=Welcome to the setup.
  *EDIT
    Name=entName
    Caption=Enter your name
    Required=1

  ' Page 2 definition
  *FORM
    Name=page2
    Caption=Step 2: Choices
    Desc=Select your preferences.
  *CHECK
    Name=chkAgree
    Caption=I agree to the terms
    Value=0

ENDWIZARD

Editing Wizards with Wizard Editor

If you are working inside the built-in editor, you can edit wizard layouts visually instead of rewriting the full block by hand.

1. Place the text cursor on the WIZARD keyword in your script.
2. Right-click and select Wizard Editor.
3. The editor automatically highlights the full WIZARD...ENDWIZARD block and opens the visual wizard designer.
4. Make your page layout and property changes in the visual editor, then save.
5. When you save, the Wizard Editor writes the updated wizard code back into the highlighted block.

Wizard Parameters

• Title: The window title bar text.
• Height: Window height in pixels (optional).
• Width: Window width in pixels (optional, use -1 for default).
• AlwaysOnTop: True or False.

---

2. Page Definition (*FORM)

Each page starts with *FORM and includes several properties:

• Name: A unique identifier for the page (used for branching/skipping).
• Caption: The bold title displayed at the top of the white content area.
• Desc: A secondary description line below the caption. (Use Desc1, Desc2 for additional lines).
• Required: If set to 1 on a form, the user must interact with at least one control before proceeding.
• Terminal: An optional *END tag can be used to explicitly mark the end of a page's control list.

---

3. Available Controls

Wizards support a wide variety of specialized controls. Every control must have a Name and a Caption.

Text & Input

Control	Description	Keys
*EDIT	Standard text box.	Password=1 (masked), Value=... (default)
*PASSWORD	Masked input, often prompts for confirmation.	Name, Caption
*LABEL	Displays static text or links.	Supports $ControlName$ and https://...
*DATE	Date picker control.	Value=mm/dd/yyyy

Selections

Control	Description	Keys
*COMBO	Dropdown box.	Selections=val1,val2, Editable=0/1
*LIST	List box.	CheckBox=1 (checklist), Height=px
*RADIO	Circular selection buttons.	Name, Caption, Value=1 (checked)
*CHECK	Individual checkbox.	Value=0/1

File System

Control	Description	Keys
*DIR	Directory picker with "..." button.	Name, Caption
*FILE	File picker with "..." button.	`Filters=Text

Specialized

Control	Description	Keys
*ENLIST	Enhanced list with + / - buttons.	AttachTo=ControlName, Sorted=1
*BUTTON	Custom button inside the page.	SkipTo=PageName

---

4. Conditional Branching

BTB Wizards support dynamic flows where the "Next" button leads to different pages based on user input.

Using *SKIPTO

Used to jump to a page based on a control's value.

*COMBO
  Name=cmbChoice
  Selections=PageA,PageB
*SKIPTO
  Name=cmbChoice
  Value=fr$cmbChoice$  ' If user selects PageA, jumps to frPageA

Using *COND

Allows mapping specific values to target pages.

*RADIO
  Name=rdPath
  Caption=Option 1
  Value=1
*COND
  Name=rdPath
  Caption=1
  Value=frPage1  ' If rdPath is 1, go to frPage1

---

5. Working with Results

After ENDWIZARD, the script continues, and you can retrieve the user's answers.

WIZARDVAR("ControlName")

Returns the content of the control (text in an edit box, selected item in a combo, or 1/0 for a checkbox).

name = WIZARDVAR("edFirstName")
IF WIZARDVAR("chWakeUp") = "1" THEN
   ' User checked the box
ENDIF

Variable Template Substitution

You can use $ControlName$ anywhere in Page Captions or Labels to display values the user entered on previous pages.

*LABEL
  Caption=Hello, $edFirstName$! Welcome to step 2.

---

6. Example: User Information Wizard

(Matches the provided runtime visual)

WIZARD "Easy Wizard", 500, -1, True
*Form
  Name=frUserInfo
  Caption=User Information
  Desc=Please enter information about yourself
*Edit
  Name=edFirstName
  Caption=First Name *
  Required=1
*Edit
  Name=edLastName
  Caption=Last Name *
  Required=1
*Combo
  Name=coAgeRange
  Caption=Age Range
  Selections=Under 18, Age 18 to 21, Age 21 and Over
ENDWIZARD