List Box — worked example

A list box shows a scrolling list of items the user can select. Like the combo box, each item can carry a hidden tag — a short key you look up after selection, separate from the visible text.

A listbox of fruit with Cherry selected, showing idx=3 tag=[C] below it.

Verified by execution on KCML 06.00.88 (KClient direct mode).

What it demonstrates

The program

01000 REM test_listbox - single-select listbox with tagged items
    : DIM result, msg$80, tag$10
01010 - DEFFORM ListTest()=\
       {.form,.form$,.Style=0x50c000c4,.Width=300,.Height=200,.Text$="ListBox Test",.Id=1024},\
       {.lblInfo,.static$,.Style=0x50000000,.Left=10,.Top=10,.Width=280,.Height=10,.Text$="Single-click selects, double-click logs DblClick.",.Id=2000,.Font=.SegoeCtl},\
       {.lstFruit,.listbox$,.Style=0x50a10000,.Left=10,.Top=25,.Width=160,.Height=100,.Id=2001,.Font=.SegoeCtl},\
       {.lblPicked,.static$,.Style=0x50000000,.Left=10,.Top=135,.Width=280,.Height=10,.Text$="(nothing picked yet)",.Id=2002,.Font=.SegoeCtl},\
       {.btnClose,.button$,.Style=0x50010001,.Left=210,.Top=155,.Width=80,.Height=14,.Text$="Close",.Id=1,.Font=.SegoeCtl},\
       {.paneStatus,.status$,.Width=300,.Style=0x50000000,.Text$="Ready"},\
       {.SegoeCtl,.dlgfont$,.Name$="Segoe UI",.Size=10}
    :     + DEFEVENT ListTest.Enter()
    :         .lstFruit.Add("Apple","A")
    :         .lstFruit.Add("Banana","B")
    :         .lstFruit.Add("Cherry","C")
    :         .lstFruit.Add("Date","D")
    :         .lstFruit.Add("Elderberry","E")
    :     END EVENT
    :     + DEFEVENT ListTest.lstFruit.Click()
    :         tag$ = RTRIM(.lstFruit.GetTag$(.lstFruit.Index))
    :         .lblPicked.Text$ = $PRINTF("Click idx=%d tag=[%s]", .lstFruit.Index, tag$)
    :     END EVENT
    :     + DEFEVENT ListTest.lstFruit.DblClk()
    :         tag$ = RTRIM(.lstFruit.GetTag$(.lstFruit.Index))
    :         .lblPicked.Text$ = $PRINTF("DblClk idx=%d tag=[%s]", .lstFruit.Index, tag$)
    :     END EVENT
    : FORM END ListTest
01020 result = ListTest.Open()
    : $END

How it works

Tags decouple display from data. .Add("Cherry", "C") shows Cherry but stores the tag C. After a selection, GetTag$(.Index) returns the tag so your code branches on a stable key, not the display text (which may be translated).

1-based indexing. As with the combo box, .Index and GetTag$() are 1-based — the third item (Cherry) reports idx=3. Wrap tag reads in RTRIM() to strip the fixed-length padding.

Click vs DblClk. Click() fires on selection; DblClk() on double-click — commonly used to "open" the selected row. Spell the event DblClk.

See also