Virtual List Controls

Home | Overview | Sample

A virtual list control is a list view control that has the LVS_OWNERDATA style. This style enables the control to support an item count up to a DWORD (the default item count only extends to an int). However, the biggest advantage provided by this style is the ability to only have a subset of data items in memory at any one time. This allows the virtual list view control to lend itself for use with large databases of information, where specific methods of accessing data are already in place.

Note In addition to providing virtual list functionality in CListCtrl, MFC also provides the same functionality in the CListView class.

There are some compatibility issues you should be aware of when developing virtual list controls. For more information, see Compatibility issues: styles, states, and messages in the Platform SDK.

Handling the LVN_GETDISPINFO Notification

Virtual list controls maintains very little item information. Except for the item selection and focus information, all item information is managed by the owner of the control. Information is requested by the framework via a LVN_GETDISPINFO notification message. To provide the requested information, the owner of the virtual list control (or the control itself) must handle this notification. This can easily be done using ClassWizard. The resultant code should look something like the following example (where CMyListCtrl is the virtual list control object and the control is handling the notification):

BEGIN_MESSAGE_MAP(CMyListCtrl, CListCtrl)
   //{{AFX_MSG_MAP(CMyListCtrl)
   ON_NOTIFY_REFLECT(LVN_GETDISPINFO, OnGetdispinfo)
   //}}AFX_MSG_MAP
END_MESSAGE_MAP()

In the handler for the LVN_GETDISPINFO notification message, you must check to see what type of information is being requested. The possible values are:

LVIF_TEXT The pszText member must be filled in.
LVIF_IMAGE The iImage member must be filled in.
LVIF_INDENT The iIndent member must be filled in.
LVIF_PARAM The lParam member must be filled in.
LVIF_STATE The state member must be filled in.

You should then supply whatever information is requested back to the framework.

The following example (taken from the body of the notification handler for the list control object) demonstrates one possible method by supplying information for the text buffers and image of an item:

LV_DISPINFO* pDispInfo = (LV_DISPINFO*)pNMHDR;
LV_ITEM* pItem= &(pDispInfo)->item;

int iItemIndx= pItem->iItem;

if (pItem->mask & LVIF_TEXT) //valid text buffer?
{
    switch(pItem->iSubItem){
        case 0: //fill in main text
            lstrcpy(pItem->pszText, 
                m_Items[iItemIndx].m_strItemText);
            break;
        case 1: //fill in sub item 1 text
            lstrcpy(pItem->pszText,
                m_Items[iItemIndx].m_strSubItem1Text);
            break;
        case 2: //fill in sub item 2 text
            lstrcpy(pItem->pszText,
                m_Items[iItemIndx].m_strSubItem2Text);
            break;
    }
}

if pItem->mask & LVIF_IMAGE) //valid image?
        pItem->iImage= 
            m_Items[iItemIndx].m_iImageIndex;

Caching and Virtual List Controls

Because this type of list control is intended for large data sets, it is recommended that you cache requested item data to improve retrieval performance. The framework provides a cache-hinting mechanism to assist in optimizing the cache by sending an LVN_ODCACHEHINT notification message. However, you must use a slightly different method to handle this notification. Using ClassWizard, override the OnChildNotify function of your list control object. In the case of this example, CMyListCtrl.

Inside the body of the handler, check for the LVN_ODCACHEHINT message and, if found, prepare your cache.

The following example (taken from the body of the OnChildNotify function) performs this check and calls the PrepCache member function of the CMyListCtrl class.

NMLVCACHEHINT* pcachehint=NULL;

if (message == WM_NOTIFY)
    {
        NMHDR* phdr = (NMHDR*)lParam;

        switch(phdr->code)
        {
        case LVN_ODCACHEHINT:
            pcachehint= (NMLVCACHEHINT*) phdr;
// Load the cache with the recommended range.
            PrepCache(pcachehint->iFrom, pcachehint->iTo);
            break;
        default:
            return CListCtrl::OnChildNotify(message, wParam, lParam, pLResult);
        }
        return FALSE;
    }
    else
        return CListCtrl::OnChildNotify(message, wParam, lParam, pLResult);

Notice that the notification is passed on to the base class (CListCtrl) if the message type is not LVN_ODCACHEHINT. For more information on preparing and maintaining a cache, see Cache Management in the Platform SDK.

Finding Specific Items

The LVN_ODFINDITEM notification message is sent by the virtual list control when a particular list control item needs to be found. The notification message is sent when the list view control receives quick key access or when it receives an LVM_FINDITEM message. Search information is sent in the form of an LVFINDINFO structure, which is a member of the NMLVFINDITEM structure. Handle this message by overriding the OnChildNotify function of your list control object and inside the body of the handler, check for the LVN_ODFINDITEM message. If found, perform the appropriate action.

You should be prepared to search for an item that matches the information given by the list view control. You should return the index of the item if successful, or -1 if no matching item is found.