Implementing On Item Click / Double Click for TListView

ListView.OnItemClick / OnItemDblClick

TListView Item OnClick / OnDoubleClick
TListView Item OnClick / OnDoubleClick.

Delphi's TListView control displays a list of items in columns with column headers and sub-items, or vertically or horizontally, with small or large icons.

As do most Delphi controls, the TListView exposes the OnClick and OnDblClick (OnDoubleClick) events.

Unfortunately, if you need to know what item was clicked or double clicked you cannot simply handle the OnClick / OnDblClick events to get the clicked item.

The OnClick (OnDblClick) event for the TListView is fired whenever the user clicks the control - that is whenever the "click" occurs somewhere inside the client area of the control.

The user can click inside the list view, BUT "miss" any of the items. What's more, since list view can change its display depending on the ViewStyle property, the user might have clicked on an item, on an item caption, on an item icon, "nowhere", on an item state icon, etc.

Note: the ViewStyle property determines how items are displayed in the list view: the items can be displayed as a set of movable icons, or as columns of text.

ListView.On Item Click & ListView.On Item Double Click

To be able to locate the clicked (if there is one) item when the OnClick event for the list view is fired, you need to determine what elements of the list view lie under the point specified by the X and Y parameters - that is the location of the mouse at the moment of "click".

The TListiew's GetHitTestInfoAt function returns information about the specified point in the list view’s client area.

To make sure the item was clicked (or double clicked) you need to call the GetHitTestInfoAt and react only if the click event occurred on an actual item.

Here's an example implementation of the ListView1's OnDblClick event:

 //handles ListView1's On Double Click
 procedure TForm.ListView1DblClick(Sender: TObject) ;
   hts : THitTests;
   ht : THitTest;
   sht : string;
   ListViewCursosPos : TPoint;
   selectedItem : TListItem;
   //position of the mouse cursor related to ListView
   ListViewCursosPos := ListView1.ScreenToClient(Mouse.CursorPos) ;
   //double click where?
   hts := ListView1.GetHitTestInfoAt(ListViewCursosPos.X, ListViewCursosPos.Y) ;
   //"debug" hit test
   Caption := '';
   for ht in hts do
     sht := GetEnumName(TypeInfo(THitTest), Integer(ht)) ;
     Caption := Format('%s %s | ',[Caption, sht]) ;
   //locate the double-clicked item
   if hts <= [htOnIcon, htOnItem, htOnLabel, htOnStateIcon] then
     selectedItem := ListView1.Selected;
     //do something with the double clicked item!
     Caption := Format('DblClcked : %s',[selectedItem.Caption]) ;

In the OnDblClick (or OnClick) event handler, read the GetHitTestInfoAt function by providing it with the location of the mouse "inside" the control. To get the loction of the mouse related to the list view, the ScreenToClient function is used to convert a point (mouse X and Y) in screen coordinates to local, or client area, coordinates.

The GetHitTestInfoAt return a value of THitTests type. The THitTests is a set of THitTest enumerated values.

The THitTest enumeration values, with their description, are:

  • htAbove - above the client area.
  • htBelow - below the client area.
  • htNowhere - inside the control, but not on an item.
  • htOnItem - on an item, its text, or its bitmap.
  • htOnButton - on a button.
  • htOnIcon - on an icon.
  • htOnIndent - on the indented area of an item.
  • htOnLabel - on a label.
  • htOnRight - on the right side of an item.
  • htOnStateIcon - on a state icon or bitmap associated with an item.
  • htToLeft - to the left of the client area.
  • htToRight - to the right of the client area.

If the result of the call to GetHitTestInfoAt is a subset (Delphi sets!) of [htOnIcon, htOnItem, htOnLabel, htOnStateIcon] you can be sure the user clicked on the item (or on its icon / state icon).

Finally, if the above is true, read the Selected property of the list view, it returns the first selected item (if multiple can be selected) in the list view.

Do something with the clicked / double clicked / selected item ...

e sure to download the full source code to explore the code and learn by adopting it :)