McBasic™Get McBasic™ ↗
Build 881
Hands-on tutorial · Layout & Forms

Wait for a modal result

Open a modal Form asynchronously and handle its lifetime.

2 Form / control designs2 complete BASIC filesGuided sample project

Modal interaction blocks the user from working with the owner, not the application’s event loop. Await the modal operation from an Async handler. QueryUnload remains a separate decision and must not leave the caller waiting for a dialog that cannot finish.

Step 1Prepare a safe practice project#

Extract the archive into a new writable folder, separate from your own application. Open ModalDialog.mcproj in McBasic™. Keep every declared source, layout, resource and migration file together.

To reconstruct it yourself, create a DesktopApp project and add the files declared below. In the complete project, follow these steps as a guided rebuild: replace each named source file once and Check after all its procedures are present.

Exact project configuration
ModalDialog.mcproj
{
  "schemaVersion": 1,
  "projectId": "4a5bc501-3496-4e8d-bbd6-5446cde70811",
  "name": "ModalDialog",
  "kind": "DesktopApp",
  "language": {
    "dialect": "McBasic1",
    "requireExplicit": true,
    "compare": "Binary",
    "defaultArrayBase": 0
  },
  "application": {
    "bundleIdentifier": "com.mcbasic.samples.modaldialog",
    "version": "0.1.0",
    "buildNumber": "1",
    "startupFormId": "modal-main",
    "shutdownMode": "OnStartupFormClosed"
  },
  "forms": [
    {
      "id": "modal-main",
      "typeName": "frmMain",
      "layout": "Forms/frmMain.form.json",
      "code": "Forms/frmMain.bas"
    },
    {
      "id": "modal-details",
      "typeName": "frmDetails",
      "layout": "Forms/frmDetails.form.json",
      "code": "Forms/frmDetails.bas"
    }
  ],
  "modules": [],
  "classes": [],
  "tests": [],
  "references": [],
  "resources": [],
  "targets": [
    "osx-arm64"
  ],
  "capabilities": []
}

Step 2Build the Form and set its properties#

frmMain

Select the Form first and set its properties. Add containers before their children. These are initial Designer values, not statements to paste into a procedure.

Form propertyValue
Caption"McBasic modal dialog"
Width440
Height230
TypeNameParent
CommandButtoncmdOpenForm
LabellblStatusForm
cmdOpen · exact Inspector values
PropertyValue
Left24
Top30
Width170
Height36
Caption"Open modal dialog"
TabIndex0
Anchor edgesLeft, Top
lblStatus · exact Inspector values
PropertyValue
Left24
Top92
Width380
Height36
Caption"Ready"
Anchor edgesLeft, Top

frmDetails

Select the Form first and set its properties. Add containers before their children. These are initial Designer values, not statements to paste into a procedure.

Form propertyValue
Caption"Owned details"
Width380
Height220
TypeNameParent
LabellblStateForm
CommandButtoncmdCloseForm
lblState · exact Inspector values
PropertyValue
Left24
Top28
Width320
Height36
Caption"Modal active"
Anchor edgesLeft, Top
cmdClose · exact Inspector values
PropertyValue
Left24
Top92
Width160
Height36
Caption"Close dialog"
TabIndex0
Anchor edgesLeft, Top

Step 3Connect the events explicitly#

frmMain

ObjectEventProcedureParameters
cmdOpenClickcmdOpen_ClickClick()

frmDetails

ObjectEventProcedureParameters
cmdCloseClickcmdClose_ClickClick()
FormInitializeForm_Initialize()
FormQueryUnloadForm_QueryUnload(ByRef Cancel As Integer, ByVal UnloadMode As Integer)

Step 4Enter the complete behavior#

Open the named source file. Enter declarations first, then every procedure. Expand a procedure for its full body, or copy the complete file. Helpers are required: do not stop after entering the first Click handler.

Forms/frmMain.bas

Enter these declarations at file scope, before the procedures.

Forms/frmMain.bas · declarations
Option Explicit

' The last dialog stays referenced after it unloads.
Private details As frmDetails
Private Async Sub cmdOpen_Click()

Enter the complete action, including its input checks and calls to helper procedures.

Forms/frmMain.bas · cmdOpen_Click
Private Async Sub cmdOpen_Click()
    Set details = New frmDetails
    lblStatus.Caption = "Opening modal"
    Await details.ShowDialogAsync(Me)
    If details.Accepted Then
        lblStatus.Caption = "Modal closed: " & details.ResultText
    Else
        lblStatus.Caption = "Modal closed"
    End If
End Sub
Copy the complete Forms/frmMain.bas file

Replace the file once; do not append duplicate procedures.

Forms/frmMain.bas
Option Explicit

' The last dialog stays referenced after it unloads.
Private details As frmDetails

Private Async Sub cmdOpen_Click()
    Set details = New frmDetails
    lblStatus.Caption = "Opening modal"
    Await details.ShowDialogAsync(Me)
    If details.Accepted Then
        lblStatus.Caption = "Modal closed: " & details.ResultText
    Else
        lblStatus.Caption = "Modal closed"
    End If
End Sub

Forms/frmDetails.bas

Enter these declarations at file scope, before the procedures.

Forms/frmDetails.bas · declarations
Option Explicit

' Public variables keep their values after the dialog unloads, so the
' owner can read them once Await ShowDialogAsync returns.
Public Accepted As Boolean
Public ResultText As String

Private CancelNextClose As Boolean
Private Sub Form_Initialize()

Initialize state before enabling dependent actions. Keep the shared declarations and startup dependencies with this procedure.

Forms/frmDetails.bas · Form_Initialize
Private Sub Form_Initialize()
    CancelNextClose = True
End Sub
Public Function Describe() As String

Enter this helper in the named source file, outside every other procedure. Its callers are included in the same project.

Forms/frmDetails.bas · Describe
Public Function Describe() As String
    Describe = lblState.Caption
End Function
Private Sub Form_QueryUnload(ByRef Cancel As Integer, ByVal UnloadMode As Integer)

This is the lifetime boundary. Preserve the cancellation signature where present and release resources owned by this Form.

Forms/frmDetails.bas · Form_QueryUnload
Private Sub Form_QueryUnload(ByRef Cancel As Integer, ByVal UnloadMode As Integer)
    If CancelNextClose Then
        Cancel = 1
        CancelNextClose = False
        lblState.Caption = "Close cancelled"
    End If
End Sub
Private Sub cmdClose_Click()

Enter the complete action, including its input checks and calls to helper procedures.

Forms/frmDetails.bas · cmdClose_Click
Private Sub cmdClose_Click()
    Accepted = True
    ResultText = "details saved"
    Unload Me
End Sub
Copy the complete Forms/frmDetails.bas file

Replace the file once; do not append duplicate procedures.

Forms/frmDetails.bas
Option Explicit

' Public variables keep their values after the dialog unloads, so the
' owner can read them once Await ShowDialogAsync returns.
Public Accepted As Boolean
Public ResultText As String

Private CancelNextClose As Boolean

Private Sub Form_Initialize()
    CancelNextClose = True
End Sub

' A Public procedure may use controls, so it needs a loaded dialog.
Public Function Describe() As String
    Describe = lblState.Caption
End Function

Private Sub Form_QueryUnload(ByRef Cancel As Integer, ByVal UnloadMode As Integer)
    If CancelNextClose Then
        Cancel = 1
        CancelNextClose = False
        lblState.Caption = "Close cancelled"
    End If
End Sub

Private Sub cmdClose_Click()
    Accepted = True
    ResultText = "details saved"
    Unload Me
End Sub

Step 5Keep resources and storage reproducible#

No external resource or migration files are declared. Any inline migration, seed data or local JSON is present in the code above. Runtime application data and private preferences are not included in the archive.

Step 6Check, run and test the result#

Save all files and run Check. Resolve diagnostics before Run. Developer CLI users can work from the extracted folder:

Developer CLI
mcbasic check ModalDialog.mcproj
mcbasic run ModalDialog.mcproj

Acceptance checklist

  • Open the dialog and confirm the owner cannot be edited.
  • Close the dialog and verify the caller resumes.
  • Open it again to check a fresh lifecycle.

Step 7Make one change and repeat the tests#

Return a public result property and read it only after the modal operation finishes.

Save a working Git checkpoint first. Change one behavior, Check again and repeat the acceptance checklist. Compare with the downloaded solution if a regression appears.

Source baseline 20f4bfed6b · Build manifest