McBasic™ 0.7.881 · Build 881 · 7 min read

Hands-on tutorial · Lists & navigation

Build an image-backed item browser

Share ImageList assets between ListView and ImageCombo.

1 Form / control designs1 complete BASIC filesGuided sample project

Download complete project Complete event code

The ImageList is nonvisual: it supplies images to visible controls. Keep image keys and item identities stable. SelectionChanged, ItemClick, ItemDoubleClick and ColumnClick represent different actions, so wire each explicitly instead of routing every interaction through one guessed Click event.

Step 1Prepare a safe practice project#

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

ImageCollections.mcproj

{
  "schemaVersion": 1,
  "projectId": "6fb8ce24-0200-4cfe-9387-9d8ac21b9dd0",
  "name": "ImageCollectionsSample",
  "kind": "DesktopApp",
  "language": {
    "dialect": "McBasic1",
    "requireExplicit": true,
    "compare": "Binary",
    "defaultArrayBase": 0
  },
  "application": {
    "bundleIdentifier": "com.mcbasic.samples.imagecollections",
    "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": [
    {
      "name": "Logo",
      "path": "Resources/logo.png"
    }
  ],
  "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`	`"ListView and ImageCombo — McBasic"`
`Width`	`700`
`Height`	`470`
`MinWidth`	`580`
`MinHeight`	`390`

Type	Name	Parent
ListView	`lvwFiles`	Form
ImageCombo	`icbActions`	Form
Label	`lblStatus`	Form
CommandButton	`cmdClose`	Form
ImageList	`imgImages`	Component tray

lvwFiles · exact Inspector values

Property	Value
`Left`	`24`
`Top`	`24`
`Width`	`652`
`Height`	`300`
`Columns`	`"Name\|300\nSize\|130\nModified\|190"`
`Items`	`"Document=Manual\|document\|2.4 MB\|Today\nExamples=Examples\|folder\|18 items\|Yesterday\nReadme=Read Me\|document\|12 KB\|Monday"`
`ImageList`	`"imgImages"`
`View`	`"Details"`
`MultiSelect`	`True`
`FullRowSelect`	`True`
`GridLines`	`True`
`Sorted`	`True`
`SelectedIndex`	`0`
`AccessibleName`	`"Project files"`
Anchor edges	Left, Top, Right, Bottom

icbActions · exact Inspector values

Property	Value
`Left`	`24`
`Top`	`348`
`Width`	`300`
`Height`	`36`
`Items`	`"Open=Open\|open\nSave=Save\|save\nClose=Close\|close"`
`ImageList`	`"imgImages"`
`DropDownStyle`	`"DropDownList"`
`ImageSize`	`18`
`MaxDropDownItems`	`6`
`Sorted`	`False`
`SelectedIndex`	`0`
Anchor edges	Left, Bottom

lblStatus · exact Inspector values

Property	Value
`Left`	`344`
`Top`	`348`
`Width`	`332`
`Height`	`52`
`Caption`	`"Ready"`
`WordWrap`	`True`
Anchor edges	Left, Right, Bottom

cmdClose · exact Inspector values

Property	Value
`Left`	`556`
`Top`	`410`
`Width`	`120`
`Height`	`34`
`Caption`	`"Close"`
`TabIndex`	`2`
Anchor edges	Right, Bottom

imgImages · exact Inspector values

Property	Value
`Images`	`"document=Logo\nfolder=Logo\nopen=Logo\nsave=Logo\nclose=Logo"`

Step 3Connect the events explicitly#

frmMain

Object	Event	Procedure	Parameters
`lvwFiles`	`SelectionChanged`	`lvwFiles_SelectionChanged`	`SelectionChanged()`
`lvwFiles`	`ItemClick`	`lvwFiles_ItemClick`	`ItemClick(ByVal Index As Integer)`
`lvwFiles`	`ItemDoubleClick`	`lvwFiles_ItemDoubleClick`	`ItemDoubleClick(ByVal Index As Integer)`
`lvwFiles`	`ColumnClick`	`lvwFiles_ColumnClick`	`ColumnClick(ByVal ColumnIndex As Integer)`
`icbActions`	`Change`	`icbActions_Change`	`Change()`
`icbActions`	`DropDown`	`icbActions_DropDown`	`DropDown()`
`icbActions`	`DropDownClosed`	`icbActions_DropDownClosed`	`DropDownClosed()`
`cmdClose`	`Click`	`cmdClose_Click`	`Click()`
Form	`Load`	`Form_Load`	`()`

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 Form_Load()

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

Forms/frmMain.bas · Form_Load

Private Sub Form_Load()
    lvwFiles.Items.Add "Archive|folder|4 items|Today"
    lvwFiles.SelectedIndex = 0
    icbActions.SelectedIndex = 0
    lblStatus.Caption = CStr(lvwFiles.Items.Count) + " files; " + CStr(icbActions.Items.Count) + " actions"
End Sub

Private Sub lvwFiles_SelectionChanged()

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

Forms/frmMain.bas · lvwFiles_SelectionChanged

Private Sub lvwFiles_SelectionChanged()
    lblStatus.Caption = "Selected: " + lvwFiles.SelectedItem
End Sub

Private Sub lvwFiles_ItemClick(ByVal Index As Integer)

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

Forms/frmMain.bas · lvwFiles_ItemClick

Private Sub lvwFiles_ItemClick(ByVal Index As Integer)
    lblStatus.Caption = "Item click: " + CStr(Index)
End Sub

Private Sub lvwFiles_ItemDoubleClick(ByVal Index As Integer)

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

Forms/frmMain.bas · lvwFiles_ItemDoubleClick

Private Sub lvwFiles_ItemDoubleClick(ByVal Index As Integer)
    lblStatus.Caption = "Item double click: " + CStr(Index)
End Sub

Private Sub lvwFiles_ColumnClick(ByVal ColumnIndex As Integer)

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

Forms/frmMain.bas · lvwFiles_ColumnClick

Private Sub lvwFiles_ColumnClick(ByVal ColumnIndex As Integer)
    lblStatus.Caption = "Column: " + CStr(ColumnIndex)
End Sub

Private Sub icbActions_Change()

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

Forms/frmMain.bas · icbActions_Change

Private Sub icbActions_Change()
    lblStatus.Caption = "Action: " + icbActions.Text
End Sub

Private Sub icbActions_DropDown()

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

Forms/frmMain.bas · icbActions_DropDown

Private Sub icbActions_DropDown()
    lblStatus.Caption = "Choose an action"
End Sub

Private Sub icbActions_DropDownClosed()

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

Forms/frmMain.bas · icbActions_DropDownClosed

Private Sub icbActions_DropDownClosed()
    lblStatus.Caption = "Action list closed"
End Sub

Private Sub cmdClose_Click()

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

Forms/frmMain.bas · cmdClose_Click

Private Sub cmdClose_Click()
    Unload Me
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 Form_Load()
    lvwFiles.Items.Add "Archive|folder|4 items|Today"
    lvwFiles.SelectedIndex = 0
    icbActions.SelectedIndex = 0
    lblStatus.Caption = CStr(lvwFiles.Items.Count) + " files; " + CStr(icbActions.Items.Count) + " actions"
End Sub

Private Sub lvwFiles_SelectionChanged()
    lblStatus.Caption = "Selected: " + lvwFiles.SelectedItem
End Sub


Private Sub lvwFiles_ItemClick(ByVal Index As Integer)
    lblStatus.Caption = "Item click: " + CStr(Index)
End Sub

Private Sub lvwFiles_ItemDoubleClick(ByVal Index As Integer)
    lblStatus.Caption = "Item double click: " + CStr(Index)
End Sub

Private Sub lvwFiles_ColumnClick(ByVal ColumnIndex As Integer)
    lblStatus.Caption = "Column: " + CStr(ColumnIndex)
End Sub

Private Sub icbActions_Change()
    lblStatus.Caption = "Action: " + icbActions.Text
End Sub

Private Sub icbActions_DropDown()
    lblStatus.Caption = "Choose an action"
End Sub

Private Sub icbActions_DropDownClosed()
    lblStatus.Caption = "Action list closed"
End Sub

Private Sub cmdClose_Click()
    Unload Me
End Sub

Step 5Keep resources and storage reproducible#

Keep the following files at their declared relative paths. Apply migrations before the first query. Media and report resources must travel with the build.

File	Purpose
`Resources/logo.png`	Bundled asset / license

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 ImageCollections.mcproj
mcbasic run ImageCollections.mcproj

Acceptance checklist

Select a ListView item and inspect selection feedback.
Single-click, double-click and activate a column header; compare the reported events.
Open and close the ImageCombo dropdown and change its value.

Step 7Make one change and repeat the tests#

Add another image-backed item using a declared resource and a new stable image key.

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 an image-backed item browser

Step 1Prepare a safe practice project#

Step 2Build the Form and set its properties#

frmMain

Step 3Connect the events explicitly#

frmMain

Step 4Enter the complete behavior#

Forms/frmMain.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`