VGUI SectionedListPanel

From Valve Developer Community
Revision as of 09:54, 14 April 2011 by LordNed (talk | contribs) (VGUI2 link + New {{stub}} template + Formatting + Article Flow)
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 creating sectioned groups of information, as a list. These list items are then sortable by the values contained in it, such as by a Player's name, or by their score. The standard scoreboard was created using a SectionedListPanel (visible inside of CClientScoreBoardDialog : SectionedListPanel), and thus represents a good example of SectionedListPanel's capabilities.


The member m_Items is a CutlLinkedList structure 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 ist hen stored in the vector m_ItemSorted.

Tip.png Tip: Look at CClientScoreBoardDialog::StaticPlayerSortFunc for an example of a sorting function.

To do: Is it really a vector?

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.