HOWTO: Select a Listview Item Programmatically

ID: Q131284

The information in this article applies to:

Microsoft Win32 Software Development Kit (SDK)

SUMMARY

Selecting a listview item is not as easy as selecting a list box item was in Windows version 3.1. To select a list box item, an application sends an LB_SETCURSEL or LB_SETSEL to a single- or multiple-selection list box respectively. To select a listview item, an application sends an LVM_SETITEMSTATE message or calls the ListView_SetItemState() macro.

MORE INFORMATION

An application can force a selection of a listview item. You might want the application to do this when a user clicks a column other than the first column of a listview of multiple subitems or columns.

Currently, a listview item is selected only when the user clicks the first column of that item. However, you many want the application to select the item regardless of which column in the listview is clicked.

Windows does not provide a separate message or function to set the current selection in a listview. Instead, it defines item states or LVIS_* values that determine the listview item's appearance and functionality. LVIS_FOCUSED and LVIS_SELECTED in particular are the states that determine a listview item's selection state.

To select a listview item programmatically, an application sets the listview item's state as follows:

   ListView_SetItemState (hWndListView,         // handle to listview
                          iWhichItem,         // index to listview item
                          LVIS_FOCUSED | LVIS_SELECTED, // item state
                          0x000F);                      // mask

Note that the last parameter passed to this macro is a mask specifying which bits are about to change. LVIS_FOCUSED and LVIS_SELECTED are defined in <commctrl.h> as 0x0001 and 0x0002 respectively, so you need to set the last four bits of the mask.

The same principle applies to selecting a treeview item programmatically. The only difference is that an application sends a TVM_SETITEM message or calls the TreeView_SetItem() macro.

Because listviews allow multiple selection by default, you can program an application to select multiple items by simulating a CTRL keydown (or SHIFT keydown event) prior to setting the item state. For example, the following code simulates the pressing of the CTRL key:

   BYTE  pbKeyState [256];

   GetKeyboardState ((LPBYTE)&pbKeyState);
   pbKeyState[VK_CONTROL] |= 0x80;
   SetKeyboardState ((LPBYTE)&pbKeyState);

Note that if an application simulates a keypress, it must also be responsible for releasing it by resetting the appropriate bit. For example, the following code simulates the release of a CTRL key:

   BYTE  pbKeyState [256];

   GetKeyboardState ((LPBYTE)&pbKeyState);
   pbKeyState[VK_CONTROL] = 0;
   SetKeyboardState ((LPBYTE)&pbKeyState);

Similarly, retrieving the currently selected item in a listview control in Windows is not as easy as sending an LB_GETCURSEL message to a listbox control.

For listviews, call the ListView_GetNextItem() function with the LVNI_SELECTED flag specified:

   iCurSel = ListView_GetNextItem (ghwndLV, -1, LVNI_SELECTED);

For treeviews, retrieve the currently selected item by calling the TreeView_GetNextItem() function with the TVGN_CARET flag specified or by calling the TreeView_GetSelection() macro directly:

   iCurSel = TreeView_GetNextItem (ghwndTV, NULL, TVGN_CARET);
      or
   iCurSel = TreeView_GetSelection (ghwndTV);

Additional query words:

Keywords          : kbcode kbCtrl kbListView kbNTOS kbGrpUser kbWinOS95 kbWinOS98 
Issue type        : kbhowto

Last Reviewed: December 26, 1998