Getting Started
Introduction
Sample Programs
IDEs
History
Advice
Mini-Tutorial
Tutorials
Code Snippets

Resources
Web Sites
More Tutorials
Forums
Vendors/Tools
Books
Magazines
Newsletters
NewsGroups
User Groups
Talk Shows
Blogs

Controls
Overview
Button
Check3State
Checkbox
ComboBox
Frame
Graphic
Image
ImageX
ImgButton
ImgButtonX
Label
Line
ListBox
ListView
Option
Progress Bar
Scrollbar
StatusBar
TAB
TextBox
Toolbar
TreeView

GBIC >> PowerBASIC >> Tutorials >> Controls >> ListView Control

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.

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
  • 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/Delete
       
       Insert Column, Insert Item, 
       Fit Content, Fit Header 
      
      • Find
       Find, Find Exact, Reset, Select,
       Unselect, Sort, Visible
      
      • Get Properties
       Column, Count, Header, Mode, Selcount, 
       Select, State, StyleXX, Text, User
      
      • Set Properties  
       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 DISABLEdisable
      hDlg, id&
      CONTROL ENABLEenable hDlg, id&
      CONTROL GET CHECKcheck state hDlg, id& TO iResult1&
      CONTROL GET CLIENTtop/left location hDlg, id& TO wide&, high&
      CONTROL GET LOCtop/left location hDlg, id& TO x&, y&
      CONTROL GET SIZEwidth/height hDlg, id& TO width&, height&
      CONTROL GET TEXTtext hDlg, id& TO txt$
      CONTROL GET USERget user data hDlg, id&, index& TO retvar&
      CONTROL HANDLE window handle for control id hDlg, id& TO hCtl&
      CONTROL KILLremove control hDlg, id&
      CONTROL POSTput message in queue (non-blocking) hDlg, id&, Msg&, wParam&, lParam&
      CONTROL REDRAWschedule redraw of control hDlg, id&
      CONTROL SENDsend message to control, wait for processing hDlg, id&, Msg&, wParam&, lParam& TO iResult2&
      CONTROL SET CHECKset check for 3state or checkbox hDlg, id&, checkstate&
      CONTROL SET CLIENTchange size to specific client area size hDlg, id&, wide&, high&
      CONTROL SET COLORset fg/bg color hDlg, id&, fgcolor&, bgcolor&
      CONTROL SET FOCUSset focus hDlg, id&
      CONTROL SET FONTselect font for a control hDlg, id&, fonthandle&
      CONTROL SET LOCrelocate control within dialog hDlg, id&, x&, y&
      CONTROL SET OPTIONset check state of option control hDlg, id&, minid&, maxid&
      CONTROL SET SIZEchange control size hDlg, id&, width&, height&
      CONTROL SET TEXTchange control text hDlg, id&, text$
      CONTROL SET USERset 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.