C# Class BrightIdeasSoftware.VirtualObjectListView

A virtual object list view operates in virtual mode, that is, it only gets model objects for a row when it is needed. This gives it the ability to handle very large numbers of rows with minimal resources.

A listview is not a great user interface for a large number of items. But if you've ever wanted to have a list with 10 million items, go ahead, knock yourself out.

Virtual lists can never iterate their contents. That would defeat the whole purpose.

Animated GIFs should not be used in virtual lists. Animated GIFs require some state information to be stored for each animation, but virtual lists specifically do not keep any state information. In any case, you really do not want to keep state information for 10 million animations!

Although it isn't documented, .NET virtual lists cannot have checkboxes. This class codes around this limitation, but you must use the functions provided by ObjectListView: CheckedObjects, CheckObject(), UncheckObject() and their friends. If you use the normal check box properties (CheckedItems or CheckedIndicies), they will throw an exception, since the list is in virtual mode, and .NET "knows" it can't handle checkboxes in virtual mode.

Due to the limits of the underlying Windows control, virtual lists do not trigger ItemCheck/ItemChecked events. Use a CheckStatePutter instead.

To enable grouping, you must provide an implmentation of IVirtualGroups interface, via the GroupingStrategy property.

Similarly, to enable filtering on the list, your VirtualListDataSource must also implement the IFilterableDataSource interface.

Inheritance: ObjectListView

Show file Open project: soywiz/cspspemu Class Usage Examples

Private Properties

Property	Type	Description

Public Methods

Method	Description
AddObjects ( ICollection modelObjects ) : void	Add the given collection of model objects to this control. The added objects will appear in their correct sort position, if sorting is active. Otherwise, they will appear at the end of the list. No check is performed to see if any of the objects are already in the ListView. Null objects are silently ignored.
BuildList ( bool shouldPreserveSelection ) : void	Rebuild the list with its current contents. Invalidate any cached information when we rebuild the list.
ClearCachedInfo ( ) : void	Clear any cached info this list may have been using
ClearObjects ( ) : void	Remove all items from this list
EnsureNthGroupVisible ( int groupIndex ) : void	Scroll the listview so that the given group is at the top. If the group is already visible, the list will still be scrolled to move the group to the top, if that is possible. This only works when the list is showing groups (obviously).
GetDisplayOrderOfItemIndex ( int itemIndex ) : int	Return the position of the given itemIndex in the list as it currently shown to the user. If the control is not grouped, the display order is the same as the sorted list order. But if the list is grouped, the display order is different.
GetItemCount ( ) : int	Return the number of items in the list
GetLastItemInDisplayOrder ( ) : BrightIdeasSoftware.OLVListItem	Return the last item in the order they are shown to the user. If the control is not grouped, the display order is the same as the sorted list order. But if the list is grouped, the display order is different.
GetModelObject ( int index ) : object	Return the model object at the given index
GetNextItem ( BrightIdeasSoftware.OLVListItem itemToFind ) : BrightIdeasSoftware.OLVListItem	Return the ListViewItem that appears immediately after the given item. If the given item is null, the first item in the list will be returned. Return null if the given item is the last item.
GetNthItemInDisplayOrder ( int n ) : BrightIdeasSoftware.OLVListItem	Return the n'th item (0-based) in the order they are shown to the user. If the control is not grouped, the display order is the same as the sorted list order. But if the list is grouped, the display order is different.
GetPreviousItem ( BrightIdeasSoftware.OLVListItem itemToFind ) : BrightIdeasSoftware.OLVListItem	Return the ListViewItem that appears immediately before the given item. If the given item is null, the last item in the list will be returned. Return null if the given item is the first item.
IndexOf ( Object modelObject ) : int	Find the given model object within the listview and return its index
MakeListViewItem ( int itemIndex ) : BrightIdeasSoftware.OLVListItem	Create a OLVListItem for given row index
ModelToItem ( object modelObject ) : BrightIdeasSoftware.OLVListItem	Return the OLVListItem that displays the given model object This method has O(n) performance.
RefreshItem ( BrightIdeasSoftware.OLVListItem olvi ) : void	Refresh the given item in the list
RefreshObjects ( IList modelObjects ) : void	Update the rows that are showing the given objects This method does not resort the items.
RefreshSelectedObjects ( ) : void	Update the rows that are selected This method does not resort or regroup the view.
RemoveObjects ( ICollection modelObjects ) : void	Remove all of the given objects from the control Nulls and model objects that are not in the ListView are silently ignored. Due to problems in the underlying ListView, if you remove all the objects from the control using this method and the list scroll vertically when you do so, then when you subsequenially add more objects to the control, the vertical scroll bar will become confused and the control will draw one or more blank lines at the top of the list.
SelectObject ( object modelObject, bool setFocus ) : void	Select the row that is displaying the given model object. All other rows are deselected.
SelectObjects ( IList modelObjects ) : void	Select the rows that is displaying any of the given model object. All other rows are deselected. This method has O(n) performance where n is the number of model objects passed. Do not use this to select all the rows in the list -- use SelectAll() for that.
SetObjects ( IEnumerable collection, bool preserveState ) : void	Set the collection of objects that this control will show.
UpdateVirtualListSize ( ) : void	Change the size of the virtual list so that it matches its data source
VirtualObjectListView ( ) : System	Create a VirtualObjectListView

Protected Methods

Method	Description
CreateGroups ( IEnumerable groups ) : void	Do the work of creating groups for this control
DisableVirtualGroups ( ) : void	Do the plumbing to disable groups on a virtual list
EnableVirtualGroups ( ) : void	Do the plumbing to enable groups on a virtual list
FindMatchInRange ( string text, int first, int last, OLVColumn column ) : int	Find the first row in the given range of rows that prefix matches the string value of the given column.
GetCheckState ( object modelObject ) : CheckState?	Get the checkedness of an object from the model. Returning null means the model does know and the value from the control will be used.
HandleCacheVirtualItems ( object sender, System.Windows.Forms.CacheVirtualItemsEventArgs e ) : void	Handle the CacheVirtualItems event
HandleRetrieveVirtualItem ( object sender, System.Windows.Forms.RetrieveVirtualItemEventArgs e ) : void	Handle a RetrieveVirtualItem
HandleSearchForVirtualItem ( object sender, System.Windows.Forms.SearchForVirtualItemEventArgs e ) : void	Handle the SearchForVirtualList event, which is called when the user types into a virtual list
MakeGroups ( BrightIdeasSoftware.GroupingParameters parms ) : IList	Make a list of groups that should be shown according to the given parameters
PostProcessRows ( ) : void	On virtual lists, this cannot work.
PutCheckState ( object modelObject, CheckState state ) : CheckState	Record the change of checkstate for the given object in the model. This does not update the UI -- only the model
SetVirtualListSize ( int newSize ) : void	Change the size of the list
TakeOwnershipOfObjects ( ) : void	Take ownership of the 'objects' collection. This separates our collection from the source. This method separates the 'objects' instance variable from its source, so that any AddObject/RemoveObject calls will modify our collection and not the original colleciton. VirtualObjectListViews always own their collections, so this is a no-op.
UpdateFiltering ( ) : void	Change the state of the control to reflect changes in filtering

Method Details

AddObjects() public method

Add the given collection of model objects to this control.

The added objects will appear in their correct sort position, if sorting is active. Otherwise, they will appear at the end of the list.

No check is performed to see if any of the objects are already in the ListView.

Null objects are silently ignored.

public AddObjects ( ICollection modelObjects ) : void
modelObjects	ICollection	A collection of model objects
return	void

BuildList() public method

Rebuild the list with its current contents.

Invalidate any cached information when we rebuild the list.

public BuildList ( bool shouldPreserveSelection ) : void
shouldPreserveSelection	bool
return	void

ClearCachedInfo() public method

Clear any cached info this list may have been using

public ClearCachedInfo ( ) : void
return	void

ClearObjects() public method

Remove all items from this list

public ClearObjects ( ) : void
return	void

CreateGroups() protected method

Do the work of creating groups for this control

protected CreateGroups ( IEnumerable groups ) : void
groups	IEnumerable
return	void

DisableVirtualGroups() protected method

Do the plumbing to disable groups on a virtual list

protected DisableVirtualGroups ( ) : void
return	void

EnableVirtualGroups() protected method

Do the plumbing to enable groups on a virtual list

protected EnableVirtualGroups ( ) : void
return	void

EnsureNthGroupVisible() public method

Scroll the listview so that the given group is at the top.

If the group is already visible, the list will still be scrolled to move the group to the top, if that is possible.

This only works when the list is showing groups (obviously).

public EnsureNthGroupVisible ( int groupIndex ) : void
groupIndex	int	The index of the group to be revealed
return	void

FindMatchInRange() protected method

Find the first row in the given range of rows that prefix matches the string value of the given column.

protected FindMatchInRange ( string text, int first, int last, OLVColumn column ) : int
text	string
first	int
last	int
column	OLVColumn
return	int

GetCheckState() protected method

Get the checkedness of an object from the model. Returning null means the model does know and the value from the control will be used.

protected GetCheckState ( object modelObject ) : CheckState?
modelObject	object
return	CheckState?

GetDisplayOrderOfItemIndex() public method

Return the position of the given itemIndex in the list as it currently shown to the user. If the control is not grouped, the display order is the same as the sorted list order. But if the list is grouped, the display order is different.

public GetDisplayOrderOfItemIndex ( int itemIndex ) : int
itemIndex	int
return	int

GetItemCount() public method

Return the number of items in the list

public GetItemCount ( ) : int
return	int

GetLastItemInDisplayOrder() public method

Return the last item in the order they are shown to the user. If the control is not grouped, the display order is the same as the sorted list order. But if the list is grouped, the display order is different.

public GetLastItemInDisplayOrder ( ) : BrightIdeasSoftware.OLVListItem
return	BrightIdeasSoftware.OLVListItem

GetModelObject() public method

Return the model object at the given index

public GetModelObject ( int index ) : object
index	int	Index of the model object to be returned
return	object

GetNextItem() public method

Return the ListViewItem that appears immediately after the given item. If the given item is null, the first item in the list will be returned. Return null if the given item is the last item.

public GetNextItem ( BrightIdeasSoftware.OLVListItem itemToFind ) : BrightIdeasSoftware.OLVListItem
itemToFind	BrightIdeasSoftware.OLVListItem	The item that is before the item that is returned, or null
return	BrightIdeasSoftware.OLVListItem

GetNthItemInDisplayOrder() public method

Return the n'th item (0-based) in the order they are shown to the user. If the control is not grouped, the display order is the same as the sorted list order. But if the list is grouped, the display order is different.

public GetNthItemInDisplayOrder ( int n ) : BrightIdeasSoftware.OLVListItem
n	int
return	BrightIdeasSoftware.OLVListItem

GetPreviousItem() public method

Return the ListViewItem that appears immediately before the given item. If the given item is null, the last item in the list will be returned. Return null if the given item is the first item.

public GetPreviousItem ( BrightIdeasSoftware.OLVListItem itemToFind ) : BrightIdeasSoftware.OLVListItem
itemToFind	BrightIdeasSoftware.OLVListItem	The item that is before the item that is returned
return	BrightIdeasSoftware.OLVListItem

HandleCacheVirtualItems() protected method

Handle the CacheVirtualItems event

protected HandleCacheVirtualItems ( object sender, System.Windows.Forms.CacheVirtualItemsEventArgs e ) : void
sender	object
e	System.Windows.Forms.CacheVirtualItemsEventArgs
return	void

HandleRetrieveVirtualItem() protected method

Handle a RetrieveVirtualItem

protected HandleRetrieveVirtualItem ( object sender, System.Windows.Forms.RetrieveVirtualItemEventArgs e ) : void
sender	object
e	System.Windows.Forms.RetrieveVirtualItemEventArgs
return	void

HandleSearchForVirtualItem() protected method

Handle the SearchForVirtualList event, which is called when the user types into a virtual list

protected HandleSearchForVirtualItem ( object sender, System.Windows.Forms.SearchForVirtualItemEventArgs e ) : void
sender	object
e	System.Windows.Forms.SearchForVirtualItemEventArgs
return	void

IndexOf() public method

Find the given model object within the listview and return its index

public IndexOf ( Object modelObject ) : int
modelObject	Object	The model object to be found
return	int

MakeGroups() protected method

Make a list of groups that should be shown according to the given parameters

protected MakeGroups ( BrightIdeasSoftware.GroupingParameters parms ) : IList
parms	BrightIdeasSoftware.GroupingParameters
return	IList

MakeListViewItem() public method

Create a OLVListItem for given row index

public MakeListViewItem ( int itemIndex ) : BrightIdeasSoftware.OLVListItem
itemIndex	int	The index of the row that is needed
return	BrightIdeasSoftware.OLVListItem

ModelToItem() public method

Return the OLVListItem that displays the given model object

This method has O(n) performance.

public ModelToItem ( object modelObject ) : BrightIdeasSoftware.OLVListItem
modelObject	object	The modelObject whose item is to be found
return	BrightIdeasSoftware.OLVListItem

PostProcessRows() protected method

On virtual lists, this cannot work.

protected PostProcessRows ( ) : void
return	void

PutCheckState() protected method

Record the change of checkstate for the given object in the model. This does not update the UI -- only the model

protected PutCheckState ( object modelObject, CheckState state ) : CheckState
modelObject	object
state	CheckState
return	CheckState

RefreshItem() public method

Refresh the given item in the list

public RefreshItem ( BrightIdeasSoftware.OLVListItem olvi ) : void
olvi	BrightIdeasSoftware.OLVListItem	The item to refresh
return	void

RefreshObjects() public method

Update the rows that are showing the given objects

This method does not resort the items.

public RefreshObjects ( IList modelObjects ) : void
modelObjects	IList
return	void

RefreshSelectedObjects() public method

Update the rows that are selected

This method does not resort or regroup the view.

public RefreshSelectedObjects ( ) : void
return	void

RemoveObjects() public method

Remove all of the given objects from the control

Nulls and model objects that are not in the ListView are silently ignored.

Due to problems in the underlying ListView, if you remove all the objects from the control using this method and the list scroll vertically when you do so, then when you subsequenially add more objects to the control, the vertical scroll bar will become confused and the control will draw one or more blank lines at the top of the list.

public RemoveObjects ( ICollection modelObjects ) : void
modelObjects	ICollection	Collection of objects to be removed
return	void

SelectObject() public method

Select the row that is displaying the given model object. All other rows are deselected.

public SelectObject ( object modelObject, bool setFocus ) : void
modelObject	object	Model object to select
setFocus	bool	Should the object be focused as well?
return	void

SelectObjects() public method

Select the rows that is displaying any of the given model object. All other rows are deselected.

This method has O(n) performance where n is the number of model objects passed. Do not use this to select all the rows in the list -- use SelectAll() for that.

public SelectObjects ( IList modelObjects ) : void
modelObjects	IList	A collection of model objects
return	void

SetObjects() public method

Set the collection of objects that this control will show.

public SetObjects ( IEnumerable collection, bool preserveState ) : void
collection	IEnumerable
preserveState	bool	Should the state of the list be preserved as far as is possible.
return	void

SetVirtualListSize() protected method

Change the size of the list

protected SetVirtualListSize ( int newSize ) : void
newSize	int
return	void

TakeOwnershipOfObjects() protected method

Take ownership of the 'objects' collection. This separates our collection from the source.

This method separates the 'objects' instance variable from its source, so that any AddObject/RemoveObject calls will modify our collection and not the original colleciton.

VirtualObjectListViews always own their collections, so this is a no-op.

protected TakeOwnershipOfObjects ( ) : void
return	void

UpdateFiltering() protected method

Change the state of the control to reflect changes in filtering

protected UpdateFiltering ( ) : void
return	void

UpdateVirtualListSize() public method

Change the size of the virtual list so that it matches its data source

public UpdateVirtualListSize ( ) : void
return	void

VirtualObjectListView() public method

Create a VirtualObjectListView

public VirtualObjectListView ( ) : System
return	System