GUIs: List Enumeration

Most lists in the game are filled from enumerators.

Overview

Most lists in the game are filled from enumerators which means that the list window usually calls fillFromEnumerator during GUI creation or regularly using a timeline.

Examples of using enumerators for filling lists are:

• Player lists (in vehicle, mission, fireteam menu, scoreboard)
• Missions system mission list on HUD.
• Maps in the admin menu.
• Weapons selection in the limbo menu.

This is the player list shown in the Trojan:

windowDef vPlayerList {
	type list;
	properties {
		float 	fontSize 		= 48;			
		float	flags			= immediate( flags ) | WF_AUTO_SIZE_WIDTH | WF_TRUNCATE_TEXT;
		rect 	rect 			= 24, 50, 590, 350;
		color	backColor		= 0,0,0,0;			
	}
	events {
		onCreate {
			insertColumn( gui.blankWStr, 0, 0 ); // player class icon
			insertColumn( gui.blankWStr, 590, 1 ); // player name
		}	
	}
	timeLine {
		onTime 250 {
			// Fill the list with all the players in the vehicle every 250 milliseconds.
			fillFromEnumerator( "vehiclePlayerList" );
			resetTime( 0 );
		}
	}		
}

List Setup

The GUI should create all the columns that is expected by the enumerator similar to in the example above. Once the column have been created fillFromEnumerator may be called to fill the list. The enumerator will always clear the list before it starts filling it.

The valid enumerator names can be found in the gamecode in idGameLocal::Init:

• demoList - list of netdemos.
• crosshairs - list of all custom crosshairs available.
• keyBindings - list of key bindings for a category.
• vehiclePlayerList - players in a vehicle.
• activeTaskList - Currently selectable/Active tasks.
• fireTeamList - Fireteam menu.
• inventoryList - Weapon items in limbo menu.
• scoreboardList - List of players in the scoreboard.
• playerAdminList - List admin and superuser players.
• userGroupsList - List all user groups.
• serverConfigList - List all the server configs that can be executed.
• videoModeList - All the video modes available.
• campaignList - List maps for a campaign.
• mapList - List all maps.
• weaponSwitchList - Weapon selection when switching weapon in the hud.
• callVoteList - List all votes.
• callVoteListOptions - List all options for the current vote.
• colors - Color picker list.
• spawnLocations - Spawn locations currently available.
• availableMSAA - List available anti-aliasing options.

Item and Column Formatting

The gamecode often inserts one item for each row even when multiple columns is wanted. This is possible since the GUIs support inline material names/text formatting/localized text/item flags, and support for inserting multiple columns with the use of the indentation escape code (\t) to separate between columns:

// Insert a new item, row index -1 means it will insert a new row.
// Add three columns.
newItem = insertItem( toWStr( "First column\tSecond column\tThird column" ), -1, 0 );

There are some differences in the possible formatting that can be added for columns and items which are detailed below.

Material

Materials may be set for list items by using a formatting like this:

"<material = 'materialName'>"

Example from guis/common/stats/class.include:

index = insertItem( toWStr( "<material = 'stats_separator'>" ), -1, 0 );

Text Formatting

Text alignment flags for an item or column may be set like this where alignment flags are comma separated:

"<align = flags>"

Valid text align flags are:

• right
• left
• center
• top
• bottom
• vcenter

An example from guis/game/limbo/tabpages/campaign_info.include:

insertColumn( toWStr( "<align = right>" ), 20, 1 ); // number of players

Will align the text to the right for all items in this column.

Localized Text

Localized text may be specified for a list item or column by using a formatting like this:

"<loc = 'localizedTextName'>"

For example inserting an item like this from the stats gui (in guis/common/stats/achievements.include):

index = insertItem( toWStr( "<loc = 'guis/mainmenu/clan'>" ), 1, 0 );

Will insert an item in column 1 with the localized text guis/mainmenu/clan

Flags

Row

Valid item flags:

• customDraw - Items with this flag will call onDrawItem before the gamecode does default drawing for the item.

Column

Valid column flags:

• customDraw - Columns with this flag will call onDrawColumn for the column header before the gamecode does default drawing for the header.
• numeric - Sort the column by converting the item text to numbers.
• noSort - Do not allowing sorting in this column.
• dataSort - Sort by the integer values of the item data.

Forecolor

Set the forecolor for an item or column:

<fore = 1, 1, 1, 1>

or

<fore = 1 1 1 1>

Example (in guis/game/scoreboard/scoreboard.include):

insertColumn( toWStr( "<loc = 'guis/game/scoreboard/fireteam'><fore =" + COLOR_YELLOW_TEXT + ">" ),	40, SC_FIRETEAM );

Backcolor

Set the backcolor for an item or column:

<back = 1, 1, 1, 1>

or

<back = 1 1 1 1>