BTB Dialog Implementation Guide

The Dialog engine allows you to create fully customized windows with precise control over layout, fonts, and interactivity within a BTB script. Unlike Wizards (which are multi-page), Dialogs are single-page layouts where every control's position and size are specified in pixels.

---

1. High-Level Syntax

A basic dialog is initiated using the DIALOG...ENDDIALOG block. BTB scripts often inject variables into the layout using the |variable| template syntax.

DIALOG ["Title"], ["Font"], [Width], [Height], [AlwaysOnTop]
  *FORM
    Dimension=X, Y, Width, Height
    Caption=Dialog Title
    ...
  *BUTTON
    Name=btnOk
    Caption=OK
    Dimension=300, 250, 75, 25
    OnClicked=MySub()
ENDDIALOG

Editing Dialogs with Dialog Editor

If you are working inside the built-in editor, you do not need to hand-edit the entire dialog block every time.

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

Dialog Opening Parameters

• Title: Title bar text (overridden by Caption in *FORM).
• Font: Default typeface and size.
• AlwaysOnTop: True or False.

---

2. Page Setup (*FORM)

Every dialog requires a *FORM section (usually the first block) to define the window itself:

• Dimension: Left, Top, Width, Height in pixels.
• PPI: Pixels Per Inch (default is 96).
• Font: Typeface, Size, [Style (B, I, U, S)], and Color.
• Color: Background color (standard Windows constants like clBtnFace).
• TimeOut: Optional seconds to automatically close the dialog.

---

3. Reference of Controls

Every control requires a Name, Dimension, and Caption (or Value).

Basic Inputs

Control	Main Properties	Notes
*EDIT	Value, MaxLength, ReadOnly, Password	Standard single-line input.
*MEMO	Value, WordWrap, TextAlign, ReadOnly	Multi-line text area.
*LABEL	Caption, WordWrap, TextAlign	Supports URL strings for clickable links.

Selection Controls

Control	Main Properties	Notes
*COMBO	Selections, Value, DropDownCount	Dropdown selection. Selections separated by `nl`.
*LIST	Selections, Value	Scrollable list of items.
*RADIO	Caption, <Value>	Circular choice button.
*CHECK	Caption, <Value>	Standard 1/0 checkbox.

Visuals & Action

Control	Main Properties	Notes
*BUTTON	Caption, Default, OnClicked	Triggers a subroutine when pressed.
*IMAGE	FileName, Value	Displays a JPG or BMP icon.

---

4. Templating and Data Retrieval

Template Injection

You can pre-fill a dialog with script variables using |variable|.

lName = "John Doe"
DIALOG
*FORM
  ...
*EDIT
  Name=edName
  Value=|lName|
ENDDIALOG

Retrieving Answers

After the dialog closes (if the user clicked OK/Yes), use DIALOGVAR to get values:

userName = DIALOGVAR("edName")
choice = DIALOGVAR("Check2") ' "1" or "0"

---

5. Event Handling (OnClicked)

You can handle interactions while the dialog is open by mapping subroutines to buttons.

*BUTTON
  Name=btnRefresh
  Caption=Sync Now
  OnClicked=EvtRefresh()
ENDDIALOG

SUB EvtRefresh
  PRINT "Refreshing data..."
  SETDLGVAR("Edit6", "New Data Value")
ENDSUB

• DIALOGVAR("Name"): Read a control's value.
• SETDLGVAR("Name", Value): Update a control's property/value dynamically.

---

Example: Comprehensive Sample

(This matches the provided runtime visual)

' Pre-fill data
lComboData = "Test1" + nl + "Test2" + nl + "Test3"
lComboValue = "Test2"
lMemoValue = "This is the Memo Value." + nl + "Line #1"

DIALOG
*FORM
  Dimension=100, 100, 454, 350
  PPI=96
  Font=Segoe UI, 10
  Caption=Dialog
*IMAGE
  Name=Image9
  Dimension=16, 8, 36, 36
  FileName="C:\images\info_icon.jpg"
*BUTTON
  Name=Button4
  Dimension=324, 8, 110, 32
  Caption=Button Label
*CHECK
  Name=Check2
  Dimension=16, 64, 200, 20
  Caption=Test Check
*RADIO
  Name=Radio10
  Dimension=224, 40, 200, 20
  Font=Segoe UI, 10, BI, clBlack
  Caption=Radio10
*COMBO
  Name=Combo3
  Dimension=20, 88, 408, 25
  Caption=|lComboData|
  Value=|lComboValue|
*LABEL
  Name=Label6
  Dimension=20, 120, 200, 20
  Caption=https://www.chalardservices.com
*EDIT
  Name=Edit6
  Dimension=20, 180, 408, 25
  Value=This is the Edit Value
ENDDIALOG