Introduction	Projects	Language	Messages	Functions	Advanced
Overview Examples IDE Compilation Distribution	Project Files DDT Windows Controls Menus Dialogs   Help Files Resources   Templates   Project Shell	Syntax Operators Data Types Variables Scope Declarations   Procedures Flow Control	Windows Messages Callbacks Mouse Keyboard Dialogs Controls Subclassing	Arithmetic Trig   Strings Arrays Date/Time Printing Files Folders Keyboard Mouse Sound System	Error Traps Debugging Objects Graphics Databases API DLLs ASM Threads

ListBox Control
The listbox control provides a simple listing of string and or images. One or more may be selected. Horizontal and vertical scrollbars are available to help view the list. Multiple columns are also supported. Automatic sorting of items is provided.

• Syntax:
  

  Control Add ListBox, hDlg, id&, data$(), x, y, xx, yy, _
                                       style&, extsytle& CALL callback
  

• Source Code Example:
  This short example creates a complete application with a single listbox. When clicked, the listbox responds with a message. This tutorial page discusses most of the statements used, however the DDT, Controls, Messages, and Callback tutorials provide background information that may be helpful in understanding the example.

     #Compile Exe
     Global hDlg As Dword
     Function PBMain() As Long
        Dim MyArray(3) As String
        Array Assign MyArray() = "zero", "one", "two", "three"
        Dialog New Pixels, 0, "ListBox Test",300,300,200,200, _
                                        %WS_SysMenu, 0 To hDlg
        Control Add ListBox, hDlg, 100, MyArray(), 50,50,75,100
        Dialog Show Modal hDlg Call DlgProc
     End Function
  
     CallBack Function DlgProc() As Long
        If Cb.Msg = %WM_Command And Cb.Ctl = 100 And _
                          Cb.CtlMsg = %LBN_SelChange Then
           MsgBox "Selected!"
        End If
     End Function
  

  An additional example of a callback function is provided further down this page.

• Visual Examples:
  And here are a few examples of what you can do with the listbox control in PowerBASIC. Variations on the Control Add ListBox statement were used to create the examples. In some cases, other Control statements were used to modify the results.

  

  The options are pretty basic. A list, including multiple columns, of selectable items is displayed. Vertical and horizontal scrolling are supported. Fonts and colors may be changed.

Arguments
The Control Add statement is used to create all new controls. Here are the statement's arguments and any special significance to the listbox control.

• hDlg
  The dialog handle to which the listbox control is to be added. The value was returned by the DIALOG NEW statement.

• id&
  The id& argument is a control identifier assigned by the programmer. It must be a value of 1-65535. Values of 100+ are suggested, as PowerBASIC pre-assigns identifiers with special meaning. Numeric equates are suggested over the use of literal values.

• data$
  The initial data for the listbox is supplied in a dynamic string array. If data$ is omitted the list will be empty.

• x,y and xx,yy
  The integer x,y and xx,yy dimensions use the same units as the parent dialog. (x,y) is the upper/left coordinates of the control. (xx,yy) is the width/height of the control.

  When the control is aligned to an edge of the dialog using one of the style& options, the x,y and xx,yy values are ignored.

• style& and extstyle&
  The style& and extstyle& arguments (listed below) are optional. If not supplied, default values are used (see the table below). If values are supplied, they completely replace default values (i.e., the entered values are not in addition to the default values).

• CALL
  The "CALL callback" section is optional. If not supplied, the callback function of the parent dialog is used. An example callback function for listbox controls is provided further down this page. The #MESSAGE COMMAND compiler directive can be used to prevent sending %WS_NOTIFY messages to the callback function. By default, both %WS_NOTIFY and %WS_COMMAND messages are sent.

Usage Notes
Some of these comments refer to the ListBox-specific statement in the next section below.

The ListBox is limited to 32,767 items.

Indexing is starts at 1 for all Control and Listbox statements.

Item numbers and returned item numbers are long integers.

To change an item and sort the results, use Delete/Add instead of Set Text.

To add an item and sort the results, use Add instead of Insert.

To change number of columns, send the %lb_setcolumnwidth message to the listbox using the Control Send statement, which assigns the column widths (NOT the number of columns).

    Control Send hdlg, 504, %lb_setcolumnwidth, 50, 0

Using a horizontal scroll bar requires sending %lb_sethorizontalextent with Control Send to the listbox. Then use %ws_hscroll and %lbs_disablenoscroll in style& to make the horizontal scroll visible at all times.

Using %ws_vscroll in style& enables vertical scrollbar if list is too long. Use with %lbs_disablenoscroll in style& to make the vertical scroll visible at all times.

By default, the listbox height resizes to integral multiples of a list item. Use %lbl_nointegralheight in style& to force the listbox to the exact size specified in the Control Add Listbox statement.

ListBox-Specific PowerBASIC Statements
PowerBASIC provides several statements specific to the listbox control. These allow the application to manage the content and display of the control.

ListBox Add	add new item to end of list (sorted if %lbs_sort is used)
	hDlg, id&, item$
ListBox Delete	delete specified item.
	hDlg, id&, item&
ListBox Find	find 1st item in list that starts with search$. starts at item&. pos& is position of matching item (zero if not found). search is case-insensitive.
	hDlg, id&, item&, search$ TO pos&
ListBox Find Exact	find 1st item in list exactly matches search$. starts at item&. pos& is position of matching item (zero if not found). search is case-insensitive.
	hDlg, id&, item&, search$ TO pos&
ListBox Get Count	get number of item in listbox
	hDlg, id& TO count&
ListBox Get SelCount	get number of selected items in listbox
	hDlg, id& TO count&
ListBox Get Select	find 1st selected item. item& is optional. pos& is position of selected item (zero if none selected)
	hDlg, id&, item& TO pos$
ListBox Get State	get selected status of item. status$ is True (-1) or False (0).
	hDlg, id&, item& TO status$
ListBox Get Text	get specified item. if optional item& omitted, currently selected text is returned (single selection list) or text of 1st selected item is returned (multi-selection list)
	hDlg, id&, item& TO item$
ListBox Get User	get optional numeric value associated with item
	hDlg, id&, item& TO value&
ListBox Insert	insert string item, moves all items down. does not resort.
	hDlg, id&, item&, value$
ListBox Reset	delete all items
	hDlg, id&
ListBox Select	select and scroll to item. select all if item& = 0.
	hDlg, id&, item&
ListBox Set Text	change text at item& to value$. does not resort.
	hDlg, id&, item&, value$
ListBox Set User	set optional numeric value associated with item
	hDlg, id& TO value&
ListBox UnSelect	unselect item&. item& is optional. if item& is omitted, or is zero, all items are unselected.
	hDlg, id&, item&

See the Usage section above for information on how to use the values made available by these statements.

Messages, Notifications, Styles, and ExtSstyles
There are four types of named constants in the following table. All are pulled from the MSDN web site.

• Notifications - event notifications a control receives
• Messages - controls may send these
• Styles - affect the visual look of a control
• ExtStyles - additional values that affect the visual look

The first column contains control-specific named constants and the second column contains generic window named constants (listbox controls are windows).

Also, if the PowerBASIC Help file has an entry on the value, it is highlighted in yellow. If the value was noted in PowerBASIC Help as a default value, it is also shown in bold text.

In the values for notifications, descriptions starting with -n and -c refer to events received through the %wm_notify and %wm_command messages. By default, PowerBASIC controls can receive both of these messages.

And here is a short description of many of the named constants corresponding to notifications, styles, and extstyle - particularly those discussed in the PowerBASIC Help topics.

    %lbn_dblclk            -c doubleclick
    %lbn_errspace          -c not enough memory
    %lbn_killfocus         -c keyboard focus lost
    %lbn_selcancel         -c ignore initial user selection
    %lbn_selchange         -c selection about to be changed (arrow or mouse)
    %lbn_setfocus          -c keyboard focus received
    %lbs_disablenoscroll   - show vertical scrollbar (disable if not needed)
    %lbs_extendedsel       - allow multiple selection (SHIFT+mouse)
    %lbs_multicolumn       - multi-column list box. scroll horizontally. 
    %lbs_multiplesel       - allow multiple selection (SHIFT not needed)
    %lbs_nointegralheight  - use exact size (partial display of lines)
    %lbs_nosel             - disallow list box selection (can view)
    %lbs_notify            - send click/dbl-click messages
    %lbs_sort              - automatically sort list
    %lbs_standard          - combination of %_sort/notify/vscroll/border
    %lbs_usetabstops       - expand tabs to tabstop positions
    %wm_chartoitem         - response to wm_char (lbs_wantkeyboardinput style only)
    %wm_ctlcolorlistbox    - before system draws list box
    %wm_deleteitem         - when listbox destroyed or item deleted 
    %wm_vkeytoitem         - response to wm_keydown (lbs_wantkeyboardinput style only)
    %ws_border             - use thin line border
    %ws_ex_clientedge      - apply sunken edge border
    %ws_ex_left            - generic left-aligned properties
    %ws_ex_right           - generic right-aligned properties
    %ws_ex_staticedge      - apply 3D border
    %ws_ex_transparent     - draw controls/windows beneath control first
    %ws_ex_windowedge      - apply raised edge border
    %ws_group              - starts/ends group. use %ws_tabstop style.
    %ws_hscroll            - autodisplay horizontal scroll
    %ws_tabstop            - allows receipt of keyboard focus
    %ws_vscroll            - autodisplay vertical scroll

Callback Function
A control can have its own callback function, or use the parent dialog callback function.

A control callback function should return TRUE to indicate it has processed the message. This prevents unnecessarily calling the dialog callback function, which will process the message if no control callback function is available, or if the control callback function returns FALSE.

By default, both %WM_COMMAND and %WM_NOTIFY messages are received. However, if the #MESSAGE COMMAND compiler directive is invoked, the %WM_NOTIFY messages will not be available.

In addition, %lbs_notify must be included in style& to receive the %lbn_dblclk messages.

Here's a sample listbox control callback function.

   CallBack Function cbListBox()
      Select Case CB.MSG
         Case %WM_COMMAND
            Select Case CB.CTLMSG
               Case %lbn_dblclk      'doubleclick
               Case %lbn_errspace    'not enough memory
               Case %lbn_killfocus   'keyboard focus lost
               Case %lbn_selcancel   'ignore initial user selection
               Case %lbn_selchange   'selection about to be changed (arrow or mouse)
               Case %lbn_setfocus    'keyboard focus received
         End Select
      End Select
   End Function

In each Case section, add the statements the application needs to respond to the event. Also, be sure to add "Function=1" as appropriate to indicate that the event was handled by the callback function.

Issues
Help mentions that listboxes can contain images, but no information is provided on how to add the images. There are two samples apps distributed with PowerBASIC but with little explanation.

The %lbs_notify says it affect click and dblclk, but there is no click event listed as available.

I'll update this page as more information becomes available.

CONTROL Statement Syntax
The following table lists the various Control statements (except the ADD statements). Most, but not all, can be used with the listbox control. A one-line description of the statement and then its syntax are presented.

CONTROL DISABLE	disable
	hDlg, id&
CONTROL ENABLE	enable	hDlg, id&
CONTROL GET CHECK	check state	hDlg, id& TO iResult1&
CONTROL GET CLIENT	top/left location	hDlg, id& TO wide&, high&
CONTROL GET LOC	top/left location	hDlg, id& TO x&, y&
CONTROL GET SIZE	width/height	hDlg, id& TO width&, height&
CONTROL GET TEXT	text	hDlg, id& TO txt$
CONTROL GET USER	get user data	hDlg, id&, index& TO retvar&
CONTROL HANDLE	window handle for control id	hDlg, id& TO hCtl&
CONTROL KILL	remove control	hDlg, id&
CONTROL POST	put message in queue (non-blocking)	hDlg, id&, Msg&, wParam&, lParam&
CONTROL REDRAW	schedule redraw of control	hDlg, id&
CONTROL SEND	send message to control, wait for processing	hDlg, id&, Msg&, wParam&, lParam& TO iResult2&
CONTROL SET CHECK	set check for 3state or checkbox	hDlg, id&, checkstate&
CONTROL SET CLIENT	change size to specific client area size	hDlg, id&, wide&, high&
CONTROL SET COLOR	set fg/bg color	hDlg, id&, fgcolor&, bgcolor&
CONTROL SET FOCUS	set focus	hDlg, id&
CONTROL SET FONT	select font for a control	hDlg, id&, fonthandle&
CONTROL SET LOC	relocate control within dialog	hDlg, id&, x&, y&
CONTROL SET OPTION	set check state of option control	hDlg, id&, minid&, maxid&
CONTROL SET SIZE	change control size	hDlg, id&, width&, height&
CONTROL SET TEXT	change control text	hDlg, id&, text$
CONTROL SET USER	set user data	hDlg, id&, index&, uservalue&
CONTROL SHOW STATE	toggle visibility	hDlg, id&, showstate& TO iResult3&

If you have any suggestions or corrections, please let me know.