ListScreen

From Pointui

Inherits Screen.

Displays a screen containing a vertically scrollable list of items.

Events

void OnListItemClick(ListItem li, int x, int y)

Triggered when the user clicks on a list item.

void OnListItemRightButtonClick (ListItem li, int x, int y)

Triggered when the user clicks the right hand side icon/button of a “IconText” type ListItem object.

Methods

void AddItem(String typeOfListItem)

void AddItem(String id, String text)

void AddItem(String id, String text, ListItem newItem)

void AddItem(String id, String text, String iconFilename)

void AddItem(String id, String text, String iconFilename, ListItem newItem)

Creates a new list item and adds it to the list. These methods are called for manually adding items to a list screen.

The Attributes collection of the ListItem object created has appropriate attributes created based on the supplied parameters.

If using typeOfListItem it must be one of the following:

• "TwoLine"
• "Image"

void SetData(DataTable sourceForListItems)

void SetData(DataTable sourceForListItems, int itemsToLoadPerFrame)

Instructs the ListScreen where to find the source for it’s list items. If itemsToLoadPerFrame is not supplied then all list items will be created before the screen is displayed, otherwise the specified number of items will be loaded per frame. With smaller lists the load time can be negligible and there is no need to supply itemsToLoadPerFrame. However, for larger lists it is recommended that itemsToLoadPerFrame is supplied to spread the load over time and provide the perception of better responsiveness.

Notice that only a DataTable is provided to SetData, and there is no instruction on what sort of list items to create or how to set their attributes. This is because the ListScreen only manages the navigating through the DataTable, and leaves it up to the InitListItem() method (provided in script) to handle the specifics for each list item. See example.

EXAMPLE

class ScreenRunningApps : ListScreen
{
	//table to hold the list of running applications
	DataTable tbl;
 
	void Load()	
	{
		//get list of running applications
		Process.GetRunningApplications(tbl);
 
		//tell the list screen we want to use this data table as the source for the list items
		SetData(tbl);
	}
 
	//provide an implementation of InitListItem()
	//this is called for each ListItem that is created as the screen 
	//navigates through each row of supplied DataTable
	void InitListItem(ListItem li)
	{
		//set the type of list item
		li.SetType("IconText");
 
		//read the values needed from the DataTable
		int hwnd;
		String title;
		Surface icon;
		tbl.GetValue("HWND", hwnd);
		tbl.GetValue("Title", title);
		tbl.GetValue("Icon", icon);
 
		//set list item attributes required to display the icon and text
		//also, store a unique id (in this case the hwnd) for each list item
		li.Attributes.Add("ID", hwnd);
		li.Attributes.Add("Text", title);
		li.Attributes.Add("Icon", icon);
	}
}

void InitListItem(ListItem li)

If this method has been provided in script then it is called for each list item that is created as the DataTable rows are stepped through. See SetData().

void GetSelectedIndex(int result)

Gets the index of the selected list item (zero based) and copies the value into the result parameter.

void GetSelectedItem(ListItem result)

Gets the selected list item and sets the result parameter to it.

void SetSelectedItemID(String id)

Sets the selected item in the list to the item whose “ID” attribute (in it’s Attributes collection) matches the id parameter supplied.

void Clear()

Clears all items from the list.

bool Done(ListItem selectedItem)

If this method has been provided in script then it is called when the user clicks a soft key with the ID “Done”. This is useful if you need to get access to the selectedItem to retrieve it’s attributes to know which item was selected, and then use that information to perform further actions such as save the user’s selection.

You can return true if you have handled the event and do not want default processing to occur (which includes returning to the previous screen).

ListItem* GetItem(int index)

AVAILABLE SINCE: 2.1 Returns a ListItem pointer to the item at the index specified.