How to use the CCListView extension for Cocos2D-X

There is a very useful class on the Cocos2D-X framework called CCListView. This class allows us to create a scroll of elements easily. The problem is that there are no examples or documentation about how to use this class, so here we go, a small introductory tutorial about using the magic CCListViewClass :-)

First of all, remember that CCListView is an extension, so we need to include it:
#include "extensions/CCListView/CCListView.h"

We will also need to use its namespace:
using namespace cocos2d::extension;

Using the class is not complex, we just need to initialize it, it has several properties and configurations that can be very useful. For instance I do it this way:

CCSize size = CCSize(750, 400);
list = CCListView::create(CCListViewModeVertical);
list->setDelegate(this);
list->setContentSize(size);
list->setAnchorPoint(ccp(0,0));
list->setPosition(ccp(130, 100));
list->setSeparatorStyle(CCListViewCellSeparatorStyleNone);
            
this->addChild(list);

Note that we set several properties that are important:

• The create constructor allows us to set up the scroll vertically or horizontally
• We set the delegate in order to be able to handle several callbacks raised by our CCListView (note that your class must implement the CCListViewDelegate in order to get it to work).
• The content size is quite obvious, is the area that will show the scroll elements, out of that area the scroll elements are not rendered.
• The separator style is useful for debugging purposes (at least for me), but once you are sure about the height of each element, I recommend to remove it.

Then we need to create all the elements:

void FriendsList::CCListView_numberOfCells(CCListView *listView, CCListViewProtrolData *data)
        {
            data->nNumberOfRows = 20;
        }
        
        void FriendsList::CCListView_cellForRow(CCListView *listView, CCListViewProtrolData *data)
        {
            CCSize listItemSize = CCSize(list->getContentSize().width, 80);
            
            CCListViewCell *cell = CCListViewCell::node();
            cell->setOpacity(0);
            cell->setContentSize(listItemSize);
            cell->setSelectionColor(ccc4(255, 255, 255, 50));
            data->cell = cell;

            
            CCLabelTTF *labelCount;
            
            labelCount = CCLabelTTF::create("HEY", "Arial", 16);
            
            labelCount->setPosition(ccp(0, (cell->getContentSize().height * 0) + cell->getContentSize().height / 2));
            labelCount->setAnchorPoint(ccp(0,0.5));
            labelCount->setColor(ccc3(0, 0, 0));

            
            cell->addChild(labelCount);         
        }
        
        void FriendsList::CCListView_didClickCellAtRow(CCListView *listView, CCListViewProtrolData *data)
        {
        
        }
        
        void FriendsList::CCListView_didScrollToRow(CCListView *listView, CCListViewProtrolData *data)
        {
        
        }

Note that in CCListView_numberOfCells we must set the total number of cells of our CCListView, in our example I've forced it to 20.

There is another important method here, the cellForRow, that will allow us to create each row element. In that example I am creating just a label on each row, but we could decide what to put on each row based on the information provided by the parameter data->nRow.

Another interesting detail is the setSetSelectionColor method on the CCListViewCell class, as it name says it will tint the selected row, what is very useful.

I think that this class is very powerful and easy to use, and it can be useful in many situations. I hope this small example helps someone to get started with it :-)

Please feel free to follow me on twitter to discuss more about Cocos2D-X and game development, I always love to do so :-) My twitter account is: @jboschaiguade