TListView

Windows ListView common control with icons, details, groups, and tile views

Fonte: source/classes/tlistvie.prg  |  Parent: TControl

Overview

TListView wraps the Windows SysListView32 common control. Unlike TXBrowse (which is designed for database record browsing), TListView is designed for displaying lists of items with icons -- similar to Windows Explorer's file listing. It supports five view modes, item grouping, image lists, and item selection.

Architecture

graph TD TControl --> TListView TListView --> IL_NORMAL["oImageList
(Normal Icons)"] TListView --> IL_SMALL["oImageList
(Small Icons)"] TListView --> GROUPS["aGroups[]
Item Groups"] TListView --> ITEMS["aItems[]
List Items"] subgraph "View Modes" ICON["LV_VIEW_ICON
Large icons"] DETAILS["LV_VIEW_DETAILS
Column details"] SMALL["LV_VIEW_SMALLICON
Small icons"] LIST["LV_VIEW_LIST
Simple list"] TILE["LV_VIEW_TILE
Tile layout"] end TListView --> ICON TListView --> DETAILS TListView --> SMALL TListView --> LIST TListView --> TILE style TListView fill:#1c2129,stroke:#58a6ff,stroke-width:2px,color:#e6edf3 style DETAILS fill:#1c2129,stroke:#3fb950,stroke-width:1px,color:#e6edf3

View Modes

ConstantValueDescription
LV_VIEW_ICON0Large icon view -- items displayed as large icons with label below
LV_VIEW_DETAILS1Details/report view -- items in rows with multiple columns
LV_VIEW_SMALLICON2Small icon view -- items as small icons arranged freely
LV_VIEW_LIST3List view -- items as small icons in a vertical list
LV_VIEW_TILE4Tile view -- items displayed as tiles with icon and multi-line text

Key Properties

PropertyTypeDescription
aPromptsArrayArray of text labels for the initial items
aItemsArrayRuntime array of all inserted items (maintained internally)
aGroupsArrayArray of group definitions for group view
nOptionNumericCurrently selected item index (1-based)
nGroupsNumericNumber of groups inserted (auto-incremented)
bActionBlockCode block executed on item activation (double-click/Enter)
bClickBlockCode block executed on single click

Key Methods

MethodDescription
New( nTop, nLeft, aPrompts, bAction, oWnd, nClrFore, nClrBack, lPixel, lDesign, nWidth, nHeight, cMsg )Constructor. Creates the ListView at the given position.
ReDefine( nId, oWnd, bAction )Redefine from a dialog resource.
InsertItem( nImageIndex, cText, nGroup )Insert a new item with an image index, label, and optional group assignment.
InsertGroup( cText )Insert a new group header with the given label.
DelItem( nItem )Delete the item at 1-based index nItem.
GetItem( nItem )Retrieve item data at the given index.
FindItem( cText )Search for an item by its text label.
SetItemSelect( nItem )Programmatically select an item.
SetStyle( nStyle )Change the view mode (pass one of the LV_VIEW_* constants).
SetImageList( oImageList, nType )Assign an image list. nType: LVSIL_NORMAL (0), LVSIL_SMALL (1), LVSIL_STATE (2).
SetIconSpacing( x, y )Set the spacing between icons in icon view.
SetHotItem( nItem )Set the hot-tracked item.
EnableGroupView()Enable group view mode so group headers are visible.

Command Syntax

@ nRow, nCol LISTVIEW oLvw ;
   [ OF oWnd ] ;
   [ PROMPTS cItem1, cItem2, cItem3 ] ;
   [ ON CHANGE bAction ] ;
   [ SIZE nWidth, nHeight ] ;
   [ PIXEL ] ;
   [ COLOR nClrFore, nClrBack ] ;
   [ MESSAGE cMsg ]

REDEFINE LISTVIEW oLvw ;
   ID nId ;
   [ OF oWnd ] ;
   [ ON CHANGE bAction ]

ListView Lifecycle

sequenceDiagram participant App participant LV as TListView participant Win as SysListView32 App->>LV: @ row,col LISTVIEW oLvw PROMPTS ... LV->>Win: Create("SysListView32") LV->>Win: InsertGroup("default") loop For each prompt LV->>Win: InsertItem(n, cText) end App->>LV: SetImageList(oImgList, LVSIL_NORMAL) LV->>Win: SendMessage(LVM_SETIMAGELIST) App->>LV: InsertGroup("Category A") LV->>Win: LVInsertGroup() App->>LV: InsertItem(0, "New Item", nGroup) LV->>Win: LVInsertItem() App->>LV: SetStyle(LV_VIEW_DETAILS) LV->>Win: LVSetStyle() Win-->>LV: LVN_ITEMCHANGED LV-->>App: Eval(bAction)

Code Examples

Example 1: Basic ListView with Icons

#include "FiveWin.ch"

FUNCTION TestListView()
   LOCAL oWnd, oLvw, oImgList

   DEFINE WINDOW oWnd TITLE "ListView Demo"

   // Create a 32x32 image list
   oImgList := TImageList():New( 32, 32 )
   oImgList:AddMasked( TBitmap():Define( "FOLDER",, oWnd ), CLR_MAGENTA )
   oImgList:AddMasked( TBitmap():Define( "FILE",,   oWnd ), CLR_MAGENTA )

   @ 0, 0 LISTVIEW oLvw OF oWnd ;
      PROMPTS "Documents", "Pictures", "Music", "Videos" ;
      ON CHANGE { || MsgInfo( "Selected: " + Str( oLvw:nOption ) ) } ;
      SIZE 400, 300 PIXEL

   oLvw:SetImageList( oImgList, 0 )  // LVSIL_NORMAL

   ACTIVATE WINDOW oWnd
RETURN NIL

Example 2: Details View with Groups

#include "FiveWin.ch"

FUNCTION TestListViewGroups()
   LOCAL oWnd, oLvw

   DEFINE WINDOW oWnd TITLE "ListView Groups"

   @ 0, 0 LISTVIEW oLvw OF oWnd SIZE 500, 400 PIXEL ;
      ON CHANGE { || ProcessItem( oLvw:nOption ) }

   // Switch to details view
   oLvw:SetStyle( 1 )   // LV_VIEW_DETAILS

   // Insert groups
   oLvw:InsertGroup( "Contacts" )
   oLvw:InsertGroup( "Suppliers" )

   // Enable group headers
   oLvw:EnableGroupView()

   // Insert items into groups
   oLvw:InsertItem( 0, "John Smith",     0 )  // Group 0 = default
   oLvw:InsertItem( 0, "Jane Doe",       1 )  // Group 1 = Contacts
   oLvw:InsertItem( 0, "Acme Corp",      2 )  // Group 2 = Suppliers
   oLvw:InsertItem( 0, "Widget Inc",     2 )

   ACTIVATE WINDOW oWnd
RETURN NIL

Example 3: Switching View Modes

// Add a combobox to switch view modes
@ 0, 0 COMBOBOX oCbx ITEMS { "Large Icons", "Details", ;
   "Small Icons", "List", "Tiles" } ;
   OF oWnd SIZE 150, 200 PIXEL ;
   ON CHANGE { || oLvw:SetStyle( oCbx:nAt - 1 ) }

Tips

Veja Também