McBasic™ 0.7.881 · Build 881 · 7 min read

Hands-on tutorial · Input & events

Build a keyboard-friendly dialog

Make Return, Escape and Tab part of the design, not an afterthought.

2 Form / control designs2 complete BASIC filesGuided sample project

Download complete project Complete event code

The default command is the action the user expects from Return. A cancel command is a separate escape route. Disabled actions must stay disabled even when activated from the keyboard. Check the tab order within each parent container, not just the visual position of the controls.

Step 1Prepare a safe practice project#

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

KeyboardEntry.mcproj

{
  "schemaVersion": 1,
  "projectId": "c8cd8266-066f-4525-97d5-e3fac8535173",
  "name": "KeyboardEntry",
  "kind": "DesktopApp",
  "language": {
    "dialect": "McBasic1",
    "requireExplicit": true,
    "compare": "Binary",
    "defaultArrayBase": 0
  },
  "application": {
    "bundleIdentifier": "com.mcbasic.keyboardentry",
    "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"
    },
    {
      "id": "5f8d8352-befb-4809-ad1f-906f8b106616",
      "typeName": "frmEntry",
      "layout": "Forms/frmEntry.form.json",
      "code": "Forms/frmEntry.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 property	Value
`Caption`	`"KeyboardEntry"`
`Height`	`240`
`Width`	`640`

Type	Name	Parent
CommandButton	`cmdOpen`	Form
Label	`lblLabel1`	Form

cmdOpen · exact Inspector values

Property	Value
`Caption`	`"Open customer"`
`Enabled`	`True`
`Height`	`32`
`Left`	`24`
`TabIndex`	`0`
`Top`	`32`
`Visible`	`True`
`Width`	`180`
Anchor edges	Left, Top

lblLabel1 · exact Inspector values

Property	Value
`Caption`	`"Enter saves a valid name. Escape closes the entry window."`
`Enabled`	`True`
`Height`	`56`
`Left`	`24`
`TabIndex`	`1`
`Top`	`88`
`Visible`	`True`
`Width`	`560`
Anchor edges	Left, Top

frmEntry

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 property	Value
`Caption`	`"Keyboard customer"`
`Height`	`360`
`Width`	`640`

Type	Name	Parent
TextBox	`txtName`	Form
Label	`lblStatus`	Form
TextBox	`txtNotes`	Form
CommandButton	`cmdSave`	Form
CommandButton	`cmdCancel`	Form
CheckBox	`chkSaveEnabled`	Form

txtName · exact Inspector values

Property	Value
`Enabled`	`True`
`Height`	`32`
`Left`	`24`
`MultiLine`	`False`
`ReadOnly`	`False`
`TabIndex`	`0`
`Text`	`"New customer"`
`Top`	`32`
`Visible`	`True`
`Width`	`520`
`WordWrap`	`False`
Anchor edges	Left, Top

lblStatus · exact Inspector values

Property	Value
`Caption`	`"Enter a name, then press Return."`
`Enabled`	`True`
`Height`	`32`
`Left`	`24`
`TabIndex`	`1`
`Top`	`80`
`Visible`	`True`
`Width`	`560`
Anchor edges	Left, Top

txtNotes · exact Inspector values

Property	Value
`Enabled`	`True`
`Height`	`80`
`Left`	`24`
`MultiLine`	`True`
`ReadOnly`	`False`
`TabIndex`	`1`
`Text`	`""`
`Top`	`128`
`Visible`	`True`
`Width`	`520`
`WordWrap`	`False`
Anchor edges	Left, Top

cmdSave · exact Inspector values

Property	Value
`Caption`	`"Save customer"`
`Enabled`	`True`
`Height`	`32`
`Left`	`24`
`TabIndex`	`2`
`Top`	`248`
`Visible`	`True`
`Width`	`160`
Anchor edges	Left, Top

cmdCancel · exact Inspector values

Property	Value
`Caption`	`"Cancel"`
`Enabled`	`True`
`Height`	`32`
`Left`	`208`
`TabIndex`	`3`
`Top`	`248`
`Visible`	`True`
`Width`	`160`
Anchor edges	Left, Top

chkSaveEnabled · exact Inspector values

Property	Value
`Caption`	`"Enable Save shortcut"`
`Checked`	`True`
`Enabled`	`True`
`Height`	`32`
`Left`	`24`
`TabIndex`	`4`
`Top`	`304`
`Visible`	`True`
`Width`	`400`
Anchor edges	Left, Top

Step 3Connect the events explicitly#

frmMain

Object	Event	Procedure	Parameters
`cmdOpen`	`Click`	`cmdOpen_Click`	`Click()`

frmEntry

Object	Event	Procedure	Parameters
`txtName`	`Change`	`txtName_Change`	`Change()`
`cmdSave`	`Click`	`cmdSave_Click`	`Click()`
`cmdCancel`	`Click`	`cmdCancel_Click`	`Click()`
`chkSaveEnabled`	`Change`	`chkSaveEnabled_Change`	`Change()`

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

Private Sub cmdOpen_Click()

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

Forms/frmMain.bas · cmdOpen_Click

Private Sub cmdOpen_Click()
    Dim entry As frmEntry
    Set entry = New frmEntry
    entry.Show
End Sub

Copy the complete Forms/frmMain.bas file

Replace the file once; do not append duplicate procedures.

Forms/frmMain.bas

Option Explicit

Private Sub cmdOpen_Click()
    Dim entry As frmEntry
    Set entry = New frmEntry
    entry.Show
End Sub

`Forms/frmEntry.bas`

Enter these declarations at file scope, before the procedures.

Forms/frmEntry.bas · declarations

Option Explicit
Private saveCount As Long

Private Sub cmdSave_Click()

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

Forms/frmEntry.bas · cmdSave_Click

Private Sub cmdSave_Click()
    saveCount = saveCount + 1
    Debug.Print "save:" & saveCount
    If Trim(txtName.Text) = "" Then
        lblStatus.Caption = "Enter a customer name."
        txtName.SetFocus
        txtName.SelectAll
        Exit Sub
    End If
    If txtName.Text = "New customer" Then
        lblStatus.Caption = "Replace the sample name."
        txtName.SetFocus
        txtName.SelectAll
        Exit Sub
    End If
    lblStatus.Caption = "Saved " & Trim(txtName.Text)
End Sub

Private Sub cmdCancel_Click()

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

Forms/frmEntry.bas · cmdCancel_Click

Private Sub cmdCancel_Click()
    Debug.Print "cancel"
    Unload Me
End Sub

Private Sub chkSaveEnabled_Change()

Read the current value or selection and update its dependent interface. The binding above determines which object calls this handler.

Forms/frmEntry.bas · chkSaveEnabled_Change

Private Sub chkSaveEnabled_Change()
    cmdSave.Enabled = chkSaveEnabled.Checked
End Sub

Private Sub txtName_Change()

Read the current value or selection and update its dependent interface. The binding above determines which object calls this handler.

Forms/frmEntry.bas · txtName_Change

Private Sub txtName_Change()
    lblStatus.Caption = "Ready to save."
End Sub

Copy the complete Forms/frmEntry.bas file

Replace the file once; do not append duplicate procedures.

Forms/frmEntry.bas

Option Explicit
Private saveCount As Long

Private Sub cmdSave_Click()
    saveCount = saveCount + 1
    Debug.Print "save:" & saveCount
    If Trim(txtName.Text) = "" Then
        lblStatus.Caption = "Enter a customer name."
        txtName.SetFocus
        txtName.SelectAll
        Exit Sub
    End If
    If txtName.Text = "New customer" Then
        lblStatus.Caption = "Replace the sample name."
        txtName.SetFocus
        txtName.SelectAll
        Exit Sub
    End If
    lblStatus.Caption = "Saved " & Trim(txtName.Text)
End Sub

Private Sub cmdCancel_Click()
    Debug.Print "cancel"
    Unload Me
End Sub

Private Sub chkSaveEnabled_Change()
    cmdSave.Enabled = chkSaveEnabled.Checked
End Sub

Private Sub txtName_Change()
    lblStatus.Caption = "Ready to save."
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 KeyboardEntry.mcproj
mcbasic run KeyboardEntry.mcproj

Acceptance checklist

Open the entry Form and navigate through fields using Tab.
Enter a name and press Return to exercise the default command.
Disable the save action, then press Return: it must not perform a disabled action.
Use Escape to exercise cancellation.

Step 7Make one change and repeat the tests#

Add a multiline note field and confirm Return can enter a new line there without unexpectedly submitting.

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

Build a keyboard-friendly dialog

Step 1Prepare a safe practice project#

Step 2Build the Form and set its properties#

frmMain

frmEntry

Step 3Connect the events explicitly#

frmMain

frmEntry

Step 4Enter the complete behavior#

Forms/frmMain.bas

Forms/frmEntry.bas

Step 5Keep resources and storage reproducible#

Step 6Check, run and test the result#

Acceptance checklist

Step 7Make one change and repeat the tests#

Continue learning#

`Forms/frmMain.bas`

`Forms/frmEntry.bas`