Click here to Skip to main content
13,004,774 members (66,495 online)
Click here to Skip to main content
Add your own
alternative version


169 bookmarked
Posted 4 Aug 2004

Using virtual lists

, 4 Aug 2004
Rate this:
Please Sign up or sign in to vote.
This article explains how to work with virtual lists, a very fast list that is useful to show a large number of items.

Sample Image - virtuallist.gif



Let's say you have a large database in your program and you want to show the database to the user. You use a CListCtrl with a couple of columns and fill it with a few thousand, maybe million elements. When you run it, you notice it's a bit (or very) slow. Wouldn't it be great if you didn't need to add all elements to the list, and let the list show them anyway? Does it sound stupid and ridiculous? That's how a virtual list works.

Virtual list

A virtual list is a list that has no data, it only knows how many data items it is supposed to have. But how does it now what data to show? The secret is that the list asks the parent for the information it needs. Assume you have a list with 100 elements, and elements 10-20 are visible. When the list is redrawing, it first asks the parent about element 10. When the parent has answered, the list redraws element 10, and then goes on to the next element.

A virtual list is sending three different messages to the parent. LVN_GETDISPINFO is sent when the list needs information. This is the most important message. The message LVN_ODFINDITEM is sent when the user tries to find an item by writing in the list. LVN_ODCACHEHINT is sent to give you a chance to cache data. You will probably don't care about this message at all.

OK, that's enough fuzzy theory, let's look on some code instead.

Creating a virtual list

Creating a virtual list isn't much harder than creating an ordinary CListCtrl. Add a list control in the resource editor as you usually do. Then check the style "Owner data", and then add a CListCtrl variable for this control. The only difference from an ordinary CListCtrl is the "Owner data" (LVS_OWNERDATA) style.

When you work with a virtual list, you use it mostly in the same way you do with a non-virtual list. Adding columns, selecting items, adding image list and much more works exactly the same way.

Add items to the list

Let's say m_list is the control variable for the list. Normally, you add data to the list like this:

m_list.InsertItem(0, _T("Hello world"));

But in a virtual list, this will not work. Instead, it is up to you to handle the data. Instead of adding, you change the number of elements the list is showing:

//"Add" 100 elements

If you set the item count to 100 or 1,000,000 doesn't matter, the time to run this command will still be practically zero. In a non-virtual list, adding a million elements could take hours.

Handling the LVN_GETDISPINFO message

As I said before, the list is asking the parent for information when it needs it. The list does this by sending a LVN_GETDISPINFO message. This is the most important message to handle when you are dealing with a virtual list. A typical function looks like this:

void CVirtualListDlg::OnGetdispinfoList(NMHDR* pNMHDR, LRESULT* pResult) 

    //Create a pointer to the item
    LV_ITEM* pItem= &(pDispInfo)->item;

    //Which item number?
    int itemid = pItem->iItem;

    //Do the list need text information?
    if (pItem->mask & LVIF_TEXT)
        CString text;

        //Which column?
        if(pItem->iSubItem == 0)
            //Text is name
            text = m_database[itemid].m_name;
        else if (pItem->iSubItem == 1)
            //Text is slogan
            text = m_database[itemid].m_slogan;

        //Copy the text to the LV_ITEM structure
        //Maximum number of characters is in pItem->cchTextMax
        lstrcpyn(pItem->pszText, text, pItem->cchTextMax);

    //Do the list need image information?
    if( pItem->mask & LVIF_IMAGE) 
        //Set which image to use
        //Show check box?
            //To enable check box, we have to enable state mask...
            pItem->mask |= LVIF_STATE;
            pItem->stateMask = LVIS_STATEIMAGEMASK;

                //Turn check box on
                pItem->state = INDEXTOSTATEIMAGEMASK(2);
                //Turn check box off
                pItem->state = INDEXTOSTATEIMAGEMASK(1);

    *pResult = 0;

First, we create a LV_DISPINFO pointer, and then a pointer to the item. In itemid, we save which item we should handle. Then we check the mask in pItem. The mask is telling us what kind of information the list needs. First, we check if text information is needed. If it is, we first figure out which column the text is. The first column is for names, the second for slogans (several columns will be shown in report view, in other views only first column will be used).

We also check if image information is needed. If it is, we save which image to use in pItem->iImage (this is the number to an image in the image list connected to the list).

If check boxes are visible, we should send information about that when image information is requested. First, we change pItem->mask to tell that we are sending state information. We also change pItem->stateMask to tell what kind of information we are sending. Then we write if check box is on or off.

The mask could also have the flags LVIF_INDENT, LVIF_NORECOMPUTE, LVIF_PARAM, and LVIF_DI_SETITEM. But I have never used any of them, so I guess they aren't important :-).

It isn't harder to handle the LVN_GETDISPINFO message than this. Check boxes are probably the hardest, but you will probably never use any more complicated code than I have done in this example. When you have written this function, your list will almost act like a normal list. However, it might be a good idea to implement the LVN_ODFINDITEM as well.

Handling the LVN_ODFINDITEM message

First, some basic education: start Explorer and go to a folder where you have a lot of files. Press A. What happens? If you have a file or folder that begins with an 'A', that file should now be selected. Press A again. If you have more than one file that begins with an 'A', the second file should be selected. Write "AB". If there is any file that begins with 'AB', that is now selected. This is how every normal list control behaves. Aren't list controls cool? :-).

Let's look on how a list control normally searches:


Anna is selected. When we are writing anything, the list will search down to find the best match. If it reaches the end, it restarts at the top and searches until it is back on the start item (Anna). If "A" is written, Annika should be selected. If "AND" is written, Anders should be selected. If "ANNK" is written, the selection should stay on Anna. If "E" is written, Emma should be selected.

Unfortunately, this doesn't work with virtual lists. A virtual list doesn't try to find any item at all, unless you handle the LVN_ODFINDITEM message. I usually implement the message like this:

void CVirtualListDlg::OnOdfinditemList(NMHDR* pNMHDR, LRESULT* pResult) 
    // pNMHDR has information about the item we should find
    // In pResult we should save which item that should be selected

    /* pFindInfo->iStart is from which item we should search.
       We search to bottom, and then restart at top and will stop
       at pFindInfo->iStart, unless we find an item that match

    // Set the default return value to -1
    // That means we didn't find any match.
    *pResult = -1;

    //Is search NOT based on string?
    if( (pFindInfo->lvfi.flags & LVFI_STRING) == 0 )
        //This will probably never happend...

    //This is the string we search for
    CString searchstr = pFindInfo->lvfi.psz;

    int startPos = pFindInfo->iStart;
    //Is startPos outside the list (happens if last item is selected)
    if(startPos >= m_list.GetItemCount())
        startPos = 0;

    int currentPos=startPos;
    //Let's search...
        //Do this word begins with all characters in searchstr?
        if( _tcsnicmp(m_database[currentPos].m_name, 
                 searchstr, searchstr.GetLength()) == 0)
            //Select this item and stop search.
            *pResult = currentPos;

        //Go to next item

        //Need to restart at top?
        if(currentPos >= m_list.GetItemCount())
            currentPos = 0;

    //Stop if back to start
    }while(currentPos != startPos);        

It may not be obvious how this works at a first look, but if you read it carefully, you will understand. Or, you simply skip this, and copy the code and just do the necessary changes - it's up to you :-). If the list is really large, maybe you need to make a faster version of this function, or don't implement it at all.

pFindInfo->lvfi has information on how you should search (like "Restart at top if bottom is reached" or in which direction). I have never cared about that, if you do, you should read in MSDN to get more information.

Handling the LVN_ODCACHEHINT message

LVN_ODCACHEHINT is sent to give you a chance to cache data. If you are working with a database that is in another computer in some network, maybe this is useful, but I haven't used this message in any of my programs. A function that handles this message will probably look something like this:

void CVirtualListDlg::OnOdcachehintList(NMHDR* pNMHDR, LRESULT* pResult) 

    // ... Cache the data pCacheHint->iFrom to pCacheHint->iTo ...

    *pResult = 0;

This is quite simple as you see. But as usual, simple things don't work :-). According to MSDN, you should override OnChildNotify and add the handler in this function. But I will not dig deeper in this, if you need more information about this, read in MSDN.

Changing an item

What should you do to change the data? This is really simple. You don't change the data in the list, but in the database instead. To redraw the list items, call CListCtrl::RedrawItems.

Check boxes

Check boxes are useful, but they are quite tricky to implement when you are working with a virtual list. In a normal non-virtual list, check boxes are toggled when you click on them or when you press space. But in a virtual list, nothing will happen. So you have to implement these events yourself. We start with a simple toggle-check-box-function:

void CVirtualListDlg::ToggleCheckBox(int item)
    //Change check box
    m_database[item].m_checked = !m_database[item].m_checked;

    //And redraw
    m_list.RedrawItems(item, item);

We will call this function when we want to change an item. The function toggles the check box value (in the database!) and forces the list to redraw the item. Quite simple. Toggling a check box when space is pressed is also quite simple. Add a message handler for the LVN_KEYDOWN message. The function should be something like this:

void CVirtualListDlg::OnKeydownList(NMHDR* pNMHDR, LRESULT* pResult) 

    //If user press space, toggle flag on selected item
    if( pLVKeyDown->wVKey == VK_SPACE )
        //Toggle if some item is selected
        if(m_list.GetSelectionMark() != -1)
            ToggleCheckBox( m_list.GetSelectionMark() );

    *pResult = 0;

We check if space is pressed and if any item is selected before we toggle the check box. To toggle check box when we click on it, we have to do a more complicated function. Add a message handler for the NM_CLICK message. My function looks like this:

void CVirtualListDlg::OnClickList(NMHDR* pNMHDR, LRESULT* pResult) 

    LVHITTESTINFO hitinfo;
    //Copy click point = pNMListView->ptAction;

    //Make the hit test...
    int item = m_list.HitTest(&hitinfo); 

    if(item != -1)
        //We hit one item... did we hit state image (check box)?
        //This test only works if we are in list or report mode.
        if( (hitinfo.flags & LVHT_ONITEMSTATEICON) != 0)
    *pResult = 0;

We are using CListCtrl::HitTest to see if we clicked on an item. If we did, the function returns which item we clicked on. We then use hitinfo.flags to see where we clicked. If the flag LVHT_ONITEMSTATEICON is on, then we know that the user clicked on the check box (state image).

Unfortunately, CListCtrl::HitTest doesn't work as it should if the list view is in "Icon" or "Small icon" mode. In these views, hitinfo.flags & LVHT_ONITEMSTATEICON is always 0. I haven't found a solution to this, if you do, let me now. However, using check boxes in these modes is probably quite unusual, so this is not a big problem.


Unless you are making something very unusual, you will not need to know more information than there is in this article, to use virtual lists. However, there are some minor compatibility issues between a virtual and a non-virtual list. For example, a virtual list can't sort data. But that is quite obvious, isn't it :-)? You find more information about these issues in MSDN.

When should you use a virtual list, and when should you not? For large lists, I personally prefer a virtual list. But a non-virtual list is usually easier to program (message handling is never fun), so for smaller lists, I use the ordinary list.

A very neat thing about virtual lists is that they are very easy to keep synchronized with a database. You just change the database and redraw the list if necessary. So, if you work with a list where the user should change data in the database, a virtual list could be useful even if number of items are low.

Another nice thing is that you sometimes could generate data when necessary. If you want to show row number in one column, that is very easy to do, and it takes practically no memory at all. In a non-virtual list, you would have to add this data on all items.


  • 5 August, 2004 - Initial version.


This article has no explicit license attached to it but may contain usage terms in the article text or the download files themselves. If in doubt please contact the author via the discussion board below.

A list of licenses authors might use can be found here


About the Author

Sweden Sweden
PEK is one of the millions of programmers that sometimes program so hard that he forgets how to sleep (this is especially true when he has more important things to do). He thinks that there are not enough donuts in the world. He likes when his programs works as they should do, but dislikes when his programs is more clever than he is.

You may also be interested in...


Comments and Discussions

GeneralBug with MS Tab Control Pin
Sharpmike13-Jan-06 16:38
memberSharpmike13-Jan-06 16:38 
GeneralRe: Bug with MS Tab Control Pin
PEK14-Jan-06 22:27
memberPEK14-Jan-06 22:27 
GeneralRe: Bug with MS Tab Control Pin
termal17-Apr-07 2:38
membertermal17-Apr-07 2:38 
GeneralRe: Bug with MS Tab Control Pin
Sharpmike20-Apr-07 5:36
memberSharpmike20-Apr-07 5:36 
Questionchange color Pin
ledaker12-Dec-05 14:12
memberledaker12-Dec-05 14:12 
AnswerRe: change color Pin
PEK3-Jan-06 9:10
memberPEK3-Jan-06 9:10 
GeneralHi PEK, is it possible to use virtual list in one Class drived from CListView Pin
chaochao_cz7-Nov-05 21:41
memberchaochao_cz7-Nov-05 21:41 
GeneralRe: Hi PEK, is it possible to use virtual list in one Class drived from CListView Pin
PEK8-Nov-05 7:43
memberPEK8-Nov-05 7:43 
I haven't tested it, but it should be possible. However, using ModifyStyle() isn't enough, LVS_OWNERDATA must be set when the control is created. I think you can solve this by modifying the code when CreateWindow is called, or overriding a message.

This have been done before:
GeneralIt is possible Pin
madkoala2-Jan-06 17:28
membermadkoala2-Jan-06 17:28 
GeneralGreat Article Pin
ddmcr21-Oct-05 5:01
memberddmcr21-Oct-05 5:01 
GeneralRe: Great Article Pin
PEK21-Oct-05 22:26
memberPEK21-Oct-05 22:26 
QuestionHow to implement virtual list control in CListView class?? Pin
chaochao_cz4-Sep-05 16:38
memberchaochao_cz4-Sep-05 16:38 
AnswerOK.I got it.I should use CreateWindow() Pin
chaochao_cz4-Sep-05 17:20
memberchaochao_cz4-Sep-05 17:20 
NewsGreat artical to introduce virtual list control usage! Pin
chaochao_cz4-Sep-05 15:58
memberchaochao_cz4-Sep-05 15:58 
QuestionHow to use it to display dynamic dataset? Pin
Liuhan26-Aug-05 16:44
memberLiuhan26-Aug-05 16:44 
AnswerRe: How to use it to display dynamic dataset? Pin
PEK26-Aug-05 21:26
memberPEK26-Aug-05 21:26 
fasafrah23-Aug-05 22:40
memberfasafrah23-Aug-05 22:40 
PEK24-Aug-05 10:07
memberPEK24-Aug-05 10:07 
chaochao_cz1-Sep-05 15:06
memberchaochao_cz1-Sep-05 15:06 
Cubex15-Aug-07 20:23
memberCubex15-Aug-07 20:23 
fasafrah23-Aug-05 22:36
memberfasafrah23-Aug-05 22:36 
GeneralUsing Groups with Virtual Lists Pin
AndyCheetham16-Aug-05 2:18
memberAndyCheetham16-Aug-05 2:18 
GeneralInsertItem and LPSTR_TEXTCALLBACK Pin
dominicMeier22-Jun-05 4:58
memberdominicMeier22-Jun-05 4:58 
GeneralRe: InsertItem and LPSTR_TEXTCALLBACK Pin
PEK25-Jun-05 1:25
memberPEK25-Jun-05 1:25 
GeneralSomething goes wrong ... Pin
dhammeriz19-Mar-05 12:32
memberdhammeriz19-Mar-05 12:32 

General General    News News    Suggestion Suggestion    Question Question    Bug Bug    Answer Answer    Joke Joke    Praise Praise    Rant Rant    Admin Admin   

Use Ctrl+Left/Right to switch messages, Ctrl+Up/Down to switch threads, Ctrl+Shift+Left/Right to switch pages.

Permalink | Advertise | Privacy | Terms of Use | Mobile
Web02 | 2.8.170627.1 | Last Updated 5 Aug 2004
Article Copyright 2004 by PEK
Everything else Copyright © CodeProject, 1999-2017
Layout: fixed | fluid