PowerBASIC Information Center Tutorials
These tutorials were written to help you get a quick, but thorough, understanding of PowerBASIC -
the scope of the language as well as it's specific capabilities.
 ListView Control
The listview control displays information in a tabular form - rows and columns.
Four ways to view the data are provided - small icon, icon, report, list.
- Syntax:
Control Add ListView, hDlg, id&, txt$, x, y, xx, yy, _
style&, extsytle& CALL callback
ListView Insert Column hDlg, id&, col&, StrExpr, width&, format&
ListView Insert Item hDlg, id&, row&, image&, StrExpr
Note that the Control Add ListView statement simply creates an empty listview. The
ListView Insert Column statement must be used to create columns, then a ListView
Insert Item must be used to create rows.
Note also that an imagelist is required if images are to be included on
the listview. Imagelists are discussed further down the page.
- Source Code Example:
This short example creates a complete application with a single listview,
with two columns and two rows. Icons are included in the first column.
When the column headers are clicked, the listview 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
#Include "commctrl.inc"
#Resource "pb-test.pbr"
Global hDlg As Dword 'main dialog handle
Global hLst1 As Dword, hLst2 As Dword, hLst3 As Dword
Function PBMain() As Long
Dialog New Pixels, 0, "ListView Test",300,300,245,95, _
%WS_SysMenu, 0 To hDlg
'create control
Control Add ListView, hDlg, 100, "", 10,10,175,75 '225
'create SMALL imagelist w,h,depth,size
ImageList New Icon 16,16,32,3 To hLst1
ImageList Add Icon hLst1, "x"
ImageList Add Icon hLst1, "y"
'create LARGE imagelist w,h,depth,size
ImageList New Icon 48,48,32,3 To hLst2
ImageList Add Icon hLst2, "xx"
ImageList Add Icon hLst2, "yy"
'create STATUS imagelist w,h,depth,size
ImageList New Icon 16,16,32,2 To hLst3
ImageList Add Icon hLst3, "check"
ImageList Add Icon hLst3, "blank"
'attach imagelist
ListView Set ImageList hdlg, 100, hLst1, %lvsil_small
ListView Set ImageList hdlg, 100, hLst2, %lvsil_normal
ListView Set ImageList hdlg, 100, hLst3, %lvsil_state
'columns hdlg, id&, col, "test", width, format
ListView Insert Column hDlg, 100, 1, "test1", 75, 0
ListView Insert Column hDlg, 100, 2, "test2", 75, 0
'rows hdlg, id&, row, image, "text"
ListView Insert Item hdlg, 100, 1, 1, "one" 'row 1, col1
ListView Insert Item hdlg, 100, 2, 2, "two" 'row 2, col1
'items hdlg, id&, row, col, "text"
ListView Set Text hdlg, 100, 1,2, "12" 'row1 col2
ListView Set Text hdlg, 100, 2,2, "22" 'row2 col2
ListView Set Mode hdlg, 100, 1 '0-icon 1-report 2-small 3-list
Dialog Show Modal hDlg Call DlgProc
End Function
CallBack Function DlgProc() As Long
If Cb.Msg = %WM_Notify And Cb.NmId = 100 And _
Cb.NmCode = %LVN_ColumnClick Then
MsgBox "Selected!"
End If
End Function
In this example, the listview images are stored in a resource file,
available from here.
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 listview control in PowerBASIC.
Variations on the Control Add ListView statement were used to create the examples.
In some cases, other Control statements were used to modify the results.
Icon Mode
| Report Mode
| |
| Small Icon Mode
| List
|
There are a wide variety of options - display format, sorting, font, icons, text,
multiple columns, scrolling, and more.
Report Modes
As shown in the examples above, the ListView control provides four different ways of
viewing information. The different modes are:
- Icon
Items (small icons and text, as available) are displayed left to right, wrapped as necessary.
- Report
Items (small icons and text, as available) are displayed top to bottom, one item
per line. Multiple columns, containing sub-items, are allowed. Column header text
can be displayed in buttons used to sort the control by that column.
- Small Icon
Items (small icons and text, as available) are displayed left to right, wrapped as necessary.
- List
Items (small icons and text, as available) are displayed top to bottom, one item
per line.
Arguments
The Control Add statement is used to create all new controls. Here are the
statement's arguments and any special significance to the listview control.
- hDlg
The dialog handle to which the listview 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.
- txt$
An ampersand can also be included in txt$, such as "&Stop", to specify a hot key Alt-S.
The listview control does not display the txt$ value, so it is usually set to "". However, any entered txt$ value can be accessed using the GET/SET TEXT statements. This provides the application with a control-specific property that can used for any purpose the programmer
chooses.
- 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
listview 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 ListView-specific statement in the
next section below.
The ListView is limited to 32,767 items.
Indexing is starts at 1 for all Control and listview statements.
The value format& describes the format and justification of the text: 0=left, 1=right, 2=center. Column 1 is always left-justified,
ListView-Specific PowerBASIC Statements
PowerBASIC provides several statements specific to the
listview control. These allow the application to manage
the content and display of the control.
Here's a summary of the ListView statements, categorized
by the capability they provide.
|
|
Insert Column, Insert Item,
Fit Content, Fit Header
|
|
|
Find, Find Exact, Reset, Select,
Unselect, Sort, Visible
|
|
|
Column, Count, Header, Mode, Selcount,
Select, State, StyleXX, Text, User
|
|
|
Column, Header, Image, Image2, ImageList,
Mode, Overlay, StyleXX, Text, User
|
And here's a description and syntax for each of the LISTVIEW
statements, along with some additional usage information.
| ListView Delete Column
| Delete specified column
| | hDlg, id&, col&
| | 
| | ListView Delete item
| Delete specified row
| | hDlg, id&, row&
| |
| | ListView Find
| Search 1st column for item beginning with StrExpr
| | hDlg, id&, row&, StrExpr TO datav&
| |
| | ListView Find Exact
| Search 1st column for item matching StrExpr (not case-sensitive)
| | hDlg, id&, row&, StrExpr TO datav&
| |
| | ListView Fit Content
| Adjust column width to fit largest item
| | hDlg, id&, col&
| |
| | ListView Fit Header
| Adjust column header to fit column header text (if last columns, fills width)
| | hDlg, id&, col&
| |
| | ListView Get Column
| Get width of specified column
| | hDlg, id&, col& TO datav&
| |
| | ListView Get Count
| Get number of rows
| | hDlg, id& TO datav$
| |
| | ListView Get Header
| Get header text
| | hDlg, id&, col& TO datav$
| |
| | ListView Get Mode
| Get display mode 0-icon, 1-report, 2-small icon, 3-list
| | hDlg, id& TO datav$
| |
| | ListView Get SelCount
| Get number of primary items currently selected
| | hDlg, id& TO datav$
| |
| | ListView Get Select
| Get next selected primary item (row number)
| | hDlg, id&, row& TO datav$
| |
| | ListView Get State
| Get state (-1 if selected, otherwise 0)
| | hDlg, id&, row&, col& TO datav$
| |
| | ListView Get StyleXX
| Get unique style value (set Set StyleXX below)
| | hDlg, id& TO datav$
| |
| | ListView Get Text
| Get string at specified row/col
| | hDlg, id&, row&, col& TO txtv$
| |
| | ListView Get User
| Get long integer value associated with specified row
| | hDlg, id&, row& TO datav$
| |
| | ListView Insert Column
| Adds new column at specified position
| | hDlg, id&, col&, StrExpr, width&, format&
| |
| | ListView Insert Item
| Add new row at specified position, with justification (col 1 always left-justified)
| | hDlg, id&, row&, image&, StrExpr
| |
| | ListView Reset
| Remove all items (retain columns count and column headers)
| | hDlg, id&
| |
| | ListView Select
| Select items at row/col. ListView scrolls to ensure visibility.
| | hDlg, id& row&, col&
| |
| | ListView Set Column
| Set width of specified column
| | hDlg, id&, col&, NumExpr
| |
| | ListView Set Header
| Set header text
| | hDlg, id&, col&, StrExpr
| |
| | ListView Set Image
| Set image to display next to item text string
| | hDlg, id&, row&, NumExpr
| |
| | ListView Set Image2
| Set secondary image, displayed to left of primary image
| | hDlg, id&, row&, NumExpr
| |
| | ListView Set ImageList
| Attached normal, small, or status imagelists
| | hDlg, id&, hList, NumExpr
| |
| | ListView Mode
| Set mode 0-icon, 1-report, 2-small icon, 3-list
| | hDlg, id&, NumExpr
| |
| | ListView Overlay
| Display image over specified row image
| | hDlg, id&, row&, NumExpr
| |
| | ListView StyleXX
| Apply style attributes unique to ListView control
| | hDlg, id&, NumExpr
| |
| | ListView Text
|
| | hDlg, id&, row&, col&, StrExpr
| |
| | ListView User
|
| | hDlg, id&, row&, NumExpr
| |
| | ListView Sort
|
| | hDlg, id&, col&, options
| |
| | ListView UnSelect
|
| | hDlg, id&, row&, col&
| |
| | ListView Visible
|
| | hDlg, id&, row&
| |
|
The ListView-specific styleXX values are:
- %lvs_ex_gridlines
| grid lines in report mode
| - %lvs_ex_subitemimages
| display icons with sub-items in report mode
| - %lvs_ex_checkboxes
| displays checkboxes next to items
| - %lvs_ex_trackselect
| hot track selection
| - %lvs_ex_headerdragdrop
| drag columns to reorder
| - %lvs_ex_fullrowselect
| highlights full row on selection
| - %lvs_ex_oneclickactivate
| single-click notification
| - %lvs_ex_twoclickactivate
| double-click notification
| - %lvs_ex_flatsb
| flat scroll bars
| - %lvs_ex_regional
| displays icons and text
| - %lvs_ex_infotip
| display infotips
| - %lvs_ex_underlinehot
| underline hot item text
| - %lvs_ex_underlinecold
| underline non-hot item text
| - %lvs_ex_multiworkareas
| delayed auto-arrange
| - %lvs_ex_labeltip
| unfolds partly hidden labels
| - %lvs_ex_borderselect
| selection by border, not highlighting
| - %lvs_ex_doublebuffer
| flicker reduction
| - %lvs_ex_hidelabels
| hide labels in icon/small icon modes
| - %lvs_ex_singlerow
| display a single row
| - %lvs_ex_snaptogrid
| icons snap to grid
| - %lvs_ex_simpleselect
| top right overlay rendering
| | | | | | | | | | | | | | | | | | | | | |
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 table below does not include the StyleXX values listed above
in the discussion on ListView-specific statements.
The first column contains control-specific named constants and the
second column contains generic window named constants (listview 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.
%lvs_alignleft - left align list
%lvs_aligntop - align with top
%lvs_autoarrange - icons are auto-arranged
%lvs_editlabels - allow text edit
%lvs_icon - set icon view
%lvs_list - set list view
%lvs_nocolumnheader - use no column headers in report view
%lvs_nolabelwrap - do not wrap
%lvs_noscroll - do not display scrollbars
%lvs_nosortheader - no column sort. flat view.
%lvs_ownerdata - specifies virtual listview control
%lvs_ownerdrawfixed - owner window can paint items in report view
%lvs_report - report view, left align 1st column, headers
%lvs_shareimagelists - imagelist remains if listview destroyed
%lvs_showselalways - show selection if focus is lost
%lvs_singlesel - allow select of only one item
%lvs_smallicon - small icon view
%lvs_sortascending - sort indexes in ascending order
%lvs_sortdescending - sort indexes in descending order
%ws_disabled - initially disabled (no user input)
%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_tabstop - allows receipt of keyboard focus
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.
Here's a sample listview control callback function.
CallBack Function cbListView()
Select Case CB.MSG
Case %WM_COMMAND
Select Case CB.CTLMSG
Case %lvn_columnclick
Case %lvn_deleteitem
Case %lvn_endlabeledit
Case %lvn_insertitem
Case %lvn_itemactivate
Case %lvn_itemchanged
Case %lvn_itemchanging
Case %lvn_keydown
Case %nm_click
Case %nm_dblclk
Case %nm_killfocus
Case %nm_rclick
Case %nm_rdblclk
Case %nm_return
Case %nm_setfocus
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 listview 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.
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 listview 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.
|
