VGUI SectionedListPanel

From Valve Developer Community
Jump to: navigation, search

A SectionedListPanel is a VGUI2 element defined in the vgui_controls library, in the file SectionedListPanel.cpp. SectionedListPanels are available in all source games.

SectionListPanels are useful for creating sectioned groups of information, as a list. These list items are then sortable by the values contained in them, such as a player's name or their score. The standard scoreboard was created using a SectionedListPanel (visible inside of CClientScoreBoardDialog : SectionedListPanel), and thus represents a good example of its capabilities.

Overview

The member m_Items is a CUtlLinkedList class that contains unsorted items, and calling SectionedListPanel::ResortList() traverses through m_Items and sorts m_Items provided you define a sorting function m_pFuncSort passed via AddSection(). The resulting sorted list is then stored in the vector m_SortedItems.

Tip:Look at CClientScoreBoardDialog::StaticPlayerSortFunc for an example of a sorting function.
This screenshot represents valve's default scoreboard which was built using a SectionedListPanel.

Example Usage

Before creating anything, we first need to include the SectionedListPanel header file and use the vgui namespace.

#include <vgui_controls/SectionedListPanel.h>

using namespace vgui;

SectionedListPanels can be created via the C++ keyword new with a simple call to SectionedListPanel.

SectionedListPanel* myPanel = new SectionedListPanel(this, "myPanel");

Remember that you need to provide your own sorting function!


Example Sorting Function

This is taken from CClientScoreBoardDialog, note that the sort function returns true if itemID1 > itemID2. Hence the term static sort.

bool CClientScoreBoardDialog::StaticPlayerSortFunc(vgui::SectionedListPanel *list, int itemID1, int itemID2)
{
	KeyValues *it1 = list->GetItemData(itemID1);
	KeyValues *it2 = list->GetItemData(itemID2);
	Assert(it1 && it2);

	// first compare frags
	int v1 = it1->GetInt("frags");
	int v2 = it2->GetInt("frags");
	if (v1 > v2)
		return true;
	else if (v1 < v2)
		return false;

	// next compare deaths
	v1 = it1->GetInt("deaths");
	v2 = it2->GetInt("deaths");
	if (v1 > v2)
		return false;
	else if (v1 < v2)
		return true;

	// the same, so compare itemID's (as a sentinel value to get deterministic sorts)
	return itemID1 < itemID2;
}

Additional Information

Additional information and examples can be found by simply looking at the scoreboard code, found in ClientScoreBoardDialog.cpp in the game_controls folder.