Guide structured text input

Step 1Prepare a safe practice project#

Extract the archive into a new writable folder, separate from your own application. Open MaskedTextBox.mcbproj 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.

{
  "schemaVersion": 1,
  "projectId": "a3e919e2-9e0d-4e0f-a372-4c3cfa7d2013",
  "name": "MaskedTextBoxSample",
  "kind": "DesktopApp",
  "ai": {
    "storeChatsInProject": false
  },
  "language": {
    "dialect": "McBasic1",
    "requireExplicit": true,
    "compare": "Binary",
    "defaultArrayBase": 0
  },
  "application": {
    "bundleIdentifier": "com.mcbasic.samples.maskedtextbox",
    "version": "0.1.0",
    "buildNumber": "1",
    "startupFormId": "form-main",
    "shutdownMode": "OnStartupFormClosed"
  },
  "forms": [
    {
      "id": "form-main",
      "typeName": "frmMain",
      "layout": "Forms/frmMain.form.json",
      "code": "Forms/frmMain.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.

Step 3Connect the events explicitly#

frmMain

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.

Option Explicit

Private Sub Form_Load()
    mtxPhone.Mask = "000-000-0000"
    mtxPhone.PromptChar = "_"
    mtxPhone.ReadOnly = False
    mtxPhone.Text = "555-010-0199"
    lblStatus.Caption = "Phone: " & mtxPhone.Text
End Sub

Private Sub mtxPhone_Change()
    lblStatus.Caption = "Phone: " & mtxPhone.Text
End Sub

Private Sub mtxPhone_InvalidInput()
    lblStatus.Caption = "Use the format 000-000-0000."
End Sub

Private Sub cmdClose_Click()
    Unload Me
End Sub

Option Explicit

Private Sub Form_Load()
    mtxPhone.Mask = "000-000-0000"
    mtxPhone.PromptChar = "_"
    mtxPhone.ReadOnly = False
    mtxPhone.Text = "555-010-0199"
    lblStatus.Caption = "Phone: " & mtxPhone.Text
End Sub

Private Sub mtxPhone_Change()
    lblStatus.Caption = "Phone: " & mtxPhone.Text
End Sub

Private Sub mtxPhone_InvalidInput()
    lblStatus.Caption = "Use the format 000-000-0000."
End Sub

Private Sub cmdClose_Click()
    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:

mcbasic check MaskedTextBox.mcbproj
mcbasic run MaskedTextBox.mcbproj

Acceptance checklist

• Enter characters that fit the configured phone mask.
• Try a letter in a numeric position and inspect the invalid-input feedback.
• Leave a partial value and check IsValid before treating it as complete.

Step 7Make one change and repeat the tests#

Add a save button that refuses incomplete text and returns focus to the masked field.

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.