A UserDialog is described by a Begin Dialog...End Dialog block. To graphically add a UserDialog place the current selection in the code where you want the dialog and select Insert > UserForm from the Scripting Development Environment.  

The following will display:

Use the controls on the left to add items to design your form.  Hover your mouse over each item to understand what they are for.   When you are done, close the dialog and the code for the form will be inserted into your script. 

To graphically edit a UserDialog place the current selection in a UserDialog block and select Insert > UserForm from the Scripting Development Environment.  The dialog will open to edit the previously created form.   

The following code is an OK and Cancel button.   

Begin Dialog UserDialog 400,203 ' %GRID:10,7,1,1
		OKButton 50,161,90,21
		CancelButton 210,161,90,21
	End Dialog
	Dim dlg As UserDialog
	Dialog dlg

When you have a cancel button, you need to return a value from the dialog to make decisions.  Below is the code changed to handle a cancel button press. 

' Code Module
Sub Main
	
	Begin Dialog UserDialog 400,203 ' %GRID:10,7,1,1
		OKButton 50,161,90,21
		CancelButton 210,161,90,21
	End Dialog
	Dim dlg As UserDialog
	rtn =Dialog(dlg)
	If rtn = 0 Then 'cancel pressed
		End
	End If

After adding a control, double-click to edit properties for each control.  The example below is a text field in a dialog. 

There are options for the dialog itself.  You double click anywhere in the editor not on a control item.   

The Caption field will be the name of the dialog and the Dialog Function name is to reference an the function to do advanced dialog controls.   

The example below shows both fields entered. 

When closing the dialog with the Dialog Function field filled, you will get the prompt below.    You usually would click next and then the shell of the dialog function code will be added.   

With the form looking like below,

the code in the editor will be.  

' Code Module
Sub Main
	Begin Dialog UserDialog 400,203,"My Example Dialog",.examplefunction ' %GRID:10,7,1,1
		Text 30,21,270,28,"AWR Example Text",.Text1
		OKButton 30,105,90,21
		CancelButton 140,105,90,21
	End Dialog
	Dim dlg As UserDialog
	Dialog dlg

End Sub

Rem See DialogFunc help topic for more information.
Private Function examplefunction(DlgItem$, Action%, SuppValue&) As Boolean
	Select Case Action%
	Case 1 ' Dialog box initialization
	Case 2 ' Value changing or button pressed
		Rem examplefunction = True ' Prevent button press from closing the dialog box
	Case 3 ' TextBox or ComboBox text changed
	Case 4 ' Focus changed
	Case 5 ' Idle
		Rem Wait .1 : examplefunction = True ' Continue getting idle actions
	Case 6 ' Function key
	End Select
End Function

Please see Scripting How-To: Adding a Dynamic Dialog for details using the DialogFunc capabilities. 

Initializing Values

How to populate a listbox

When you want user's to pick from a pre-defined list of items, you can use a list box. You must first collect up this list of items and then use this list in the dialog. See the example below.

Sub Main
    Dim fns() As String
    Dim fn As DataFile
'create array of strings for list box values, stored in variable fns
    cnt = 0
    For Each fn In Project.DataFiles
        ReDim Preserve fns(cnt)
        fns(cnt) = fn.Name
        cnt = cnt+1
    Next fn
'create UI
    Begin Dialog UserDialog 400,203 ' %GRID:10,7,1,1
        Text 20,7,290,28,"Choose Data File",.Text1
        DropListBox 20,49,290,35,fns(),.DropListBox1
        OKButton 20,98,300,84
    End Dialog
    Dim dlg As UserDialog
    Dialog dlg
 
'get settings from dialog box
    Set fn = Project.DataFiles(fns(dlg.dropListBox1))
    Debug.Print fn.Name
 
End Sub

• The first chunk of code is collecting up all the data file names in the project into an array of strings. Note that a dictionary is probably a better way to do this for complex structures. This code generates a variable named "fns" that has all the data file names.
• In the UI there is a "DropListBox" item. Notice that in the definition for this object is the variable "fns()". When you first create the dialog from the "user form" there will be a default variable here, you will need to change this to your variable name.
• The last section of code is getting the setting from the dialog.
  • dlg.dropListBox1 will return the index into the string array.
  • fns(dlg.dropListBox1) gets the proper string from the "fns" variable.
  • in this example, we are creating a data file object, so the rest of the line is setting the variable "fn" to be a data file object. The script prints the data file name to show that it did properly get set.

How to define default values for textboxes

When you add a textbox (a box a user can type into), sometimes you want there to be default values set in this box. The code below does this.

 ' Code Module
Sub Main
    Begin Dialog UserDialog 400,203 ' %GRID:10,7,1,1
        Text 10,21,120,21,"Enter Text",.Text1
        TextBox 170,21,130,21,.TextBox1
        OKButton 30,63,330,119
    End Dialog
    Dim dlg As UserDialog
    dlg.TextBox1 = "Default Value" ' default gets set here, has to be at this location of the dialog.
    Dialog dlg
 
    Debug.Print dlg.textbox1
 
End Sub

The key to this is that you assign the value between the "Dim dlg As UserDialog" and the "Dialog dlg" commands that are automatically generated when you create a dialog from the user form.