public/documentation/better-listview/data/chapter-collections.html

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xmlns:xlink="http://www.w3.org/1999/xlink">
<head>
<meta content="text/html; charset=utf-8" http-equiv="Content-Type">
<title>Collections</title>
<link href="style.css" rel="stylesheet" type="text/css">
<link href="prettify.css" type="text/css" rel="stylesheet">
<script type="text/javascript" src="prettify.js"></script><script type="text/javascript" src="lang-vb.js"></script><link href="../resources/main.css" media="screen" rel="stylesheet" type="text/css">
</head>
<body onload="prettyPrint()"><div class="placing">
<br><table class="navigation"><tr>
<td class="navigation-previous"><a href="chapter-checkboxes.html"><strong>
                « Check Boxes</strong></a></td>
<td class="navigation-index"><a href="../../../quick-start-guide/better-listview/index.html"><strong>Index</strong></a></td>
<td class="navigation-next"><a href="chapter-columns.html"><strong>Columns »
              </strong></a></td>
</tr></table>
<br><h1>Collections</h1>
<div class="banner">
  <a href="../../../blog/page/6/index.html"><img src="../resources/overview.gif" alt="Better ListView" class="ss"></a>
  <div class="inside">
    <div class="text">Better ListView: Ultimate .NET ListView replacement control for WinForms (C#, VB.NET)</div>
    <span class="dbtn-c dbtn-hilight"><span class="dbtn-w"><a href="../../../betterlistview.exe" class="dbtn">Download</a></span></span>
    <span class="dbtn-c"><span class="dbtn-w"><a href="../../../blog/page/6/index.html" class="dbtn">More Info</a></span></span>
  </div>
</div>
  

  

  <p>Better ListView contains several types collections of its elements
  (columns, items, sub-items, groups). These can be accessed via
  properties:</p>

  <ul>
<li>
      <p><span class="code">Columns</span></p>
    </li>
<li>
      <p><span class="code">Items</span></p>
    </li>
<li>
      <p><span class="code">Groups</span></p>
    </li>
<li>
      <p><span class="code">BetterListViewItem.SubItems</span></p>
    </li>
<li>
      <p><span class="code">BetterListViewItem.ChildItems</span></p>
    </li>
</ul>
<p>Each of these collections are of type
  <span class="code">BetterListViewElementCollection&lt;TItem&gt;</span> where
  <span class="code">TItem</span> is collection element type. All these collection also
  implement <span class="code">IList&lt;TItem&gt;</span>,
  <span class="code">ICollection&lt;TItem&gt;</span> and their nongeneric
  companions.</p>

  <p>They also implement extra functionality through
  <span class="code">IExtendedList&lt;TItem&gt;</span>:</p>

  <ul style="list-style:none">
<li>
<span class="code">AddRange</span><ul style="list-style:none"><li>
        <p>add set of items</p>
      </li></ul>
</li>
<li>
<span class="code">RemoveRange</span><ul style="list-style:none"><li>
        <p>remove subset of items</p>
      </li></ul>
</li>
</ul>
<p>These collections are bound to Better ListView, so any modification to
  these collection will be projected into control state.</p>

  <p>When the collection is created by user code, e.g.:</p>

  <p><strong>C#</strong></p>
<pre class="prettyprint"><code class="lang-cs">var myItems = new BetterListViewItemCollection();</code></pre>

  <p><strong>Visual Basic</strong></p>
<pre class="prettyprint"><code class="lang-vb">Dim myItems = New BetterListViewItemCollection()</code></pre>

  <p>then the collection is not bound to the control and its state is
  independent on the control's state.</p>

  <p>All the collections are both binary and XML serializable.</p>

  <h2>Adding Elements</h2>
    

    <p>Specific collections provide several overrides for easy addition of
    items, for example:</p>

    <p><strong>C#</strong></p>
<pre class="prettyprint"><code class="lang-cs">myItems.Add("New Item");</code></pre>

    <p><strong>Visual Basic</strong></p>
<pre class="prettyprint"><code class="lang-vb">myItems.Add("New Item")</code></pre>

    <p>Adds new item with text 'New Item' in the collection.</p>

    <p>All Better ListView collections support adding arbitrary objects,
    for example:</p>

    <p><strong>C#</strong></p>
<pre class="prettyprint"><code class="lang-cs">var person = new Person("Mark Bradley", 13, Gender.Male);

myItems.Add(person);</code></pre>

    <p><strong>Visual Basic</strong></p>
<pre class="prettyprint"><code class="lang-vb">Dim person = New Person("Mark Bradley", 13, Gender.Male)

myItems.Add(person)</code></pre>

    <p>This will create a new BetterListViewItem with Text property
    obtained from converting the <span class="code">Person</span> object. The type can
    either provide custom <span class="code">TypeConverter</span>, or default
    <span class="code">TypeConverter</span> (for primive types) or <span class="code">ToString</span>
    method is used for conversion.</p>

    <p>Multiple custom items can be added either:</p>

    <p><strong>C#</strong></p>
<pre class="prettyprint"><code class="lang-cs">myItems.AddRange(new object[] { person1, person2, "New Person" });</code></pre>

    <p><strong>Visual Basic</strong></p>
<pre class="prettyprint"><code class="lang-vb">myItems.AddRange(New Object() {person1, person2, "New Person"})</code></pre>
  

  <h2>Custom Type Conversion</h2>
    

    <p>You can add arbitrary objects to any Better ListView collection. Of
    course, the objects have to be converted to collection's item type (e.g.
    <span class="code">BetterListViewItem</span>). If no additional code is provided, the
    Better ListView will create new item and fill it with text using
    <span class="code">Object.ToString()</span> method. You can specify this text by
    providing <span class="code">ToString()</span> method override. Here is a simple
    <span class="code">Person</span> type providing custom <span class="code">ToString()</span>
    method:</p>

    <p><strong>C#</strong></p>
<pre class="prettyprint"><code class="lang-cs">class Person
{
    public string Name;
    public int Age;

    public override string ToString()
    {
        return Name;
    }
}</code></pre>

    <p><strong>Visual Basic</strong></p>
<pre class="prettyprint"><code class="lang-vb">Class Person
    
    Public Name As String
    Public Age As Integer

    Public Overrides Function ToString() As String
        Return Name
    End Function
    
End Class</code></pre>

    <p>If you want more control over the conversion, you can provide a
    custom <span class="code">TypeConverter</span>. The following sample code shows
    implementation of <span class="code">PersonConverter</span> class that allows
    conversion from <span class="code">Person</span> type to
    <span class="code">BetterListViewItem</span> type:</p>

    <p><strong>C#</strong></p>
<pre class="prettyprint"><code class="lang-cs">class PersonConverter : TypeConverter
{
    public override bool CanConvertTo(ITypeDescriptorContext context, Type destinationType)
    {
        if (destinationType == typeof(BetterListViewItem))
        {
            return true;
        }

        return base.CanConvertTo(context, destinationType);
    }

    public override object ConvertTo(ITypeDescriptorContext context, CultureInfo culture, object value, Type destinationType)
    {
        if (destinationType == typeof(BetterListViewItem))
        {
            Person person = (Person)value;

            // convert Person instance to BetterListViewItem instance
            return new BetterListViewItem(new string[] { person.Name, person.Age.ToString() });
        }

        return base.ConvertTo(context, culture, value, destinationType);
    }
}</code></pre>

    <p><strong>Visual Basic</strong></p>
<pre class="prettyprint"><code class="lang-vb">Class PersonConverter
    Inherits TypeConverter
    Public Overrides Function CanConvertTo(context As ITypeDescriptorContext, destinationType As Type) As Boolean
        If destinationType = GetType(BetterListViewItem) Then
            Return True
        End If

        Return MyBase.CanConvertTo(context, destinationType)
    End Function

    Public Overrides Function ConvertTo(context As ITypeDescriptorContext, culture As CultureInfo, value As Object, destinationType As Type) As Object
        If destinationType = GetType(BetterListViewItem) Then
            Dim person As Person = DirectCast(value, Person)

            ' convert Person instance to BetterListViewItem instance
            Return New BetterListViewItem(New String() {person.Name, person.Age.ToString()})
        End If

        Return MyBase.ConvertTo(context, culture, value, destinationType)
    End Function
End Class</code></pre>

    <p>Once you have the converter implemented, simply mark your custom
    type with <span class="code">TypeConverterAttribute</span> and Better ListView will
    make use of the converter instead of just <span class="code">ToString()</span>
    method:</p>

    <p><strong>C#</strong></p>
<pre class="prettyprint"><code class="lang-cs">[TypeConverter(typeof(PersonConverter))]
class Person
{
    public string Name;
    public int Age;

    public override string ToString()
    {
        return Name;
    }
}</code></pre>

    <p><strong>Visual Basic</strong></p>
<pre class="prettyprint"><code class="lang-vb">&lt;TypeConverter(GetType(PersonConverter))&gt; _
Class Person
    Public Name As String
    Public Age As Integer

    Public Overrides Function ToString() As String
        Return Name
    End Function
End Class</code></pre>

    <p>Note that <span class="code">TypeConverter</span> is primarily used by Better
    ListView for conversion to collection's native type or to
    <span class="code">String</span>. If the <span class="code">TypeConverter</span> does not support
    conversion to <span class="code">String</span>, the <span class="code">Object.ToString()</span>
    method is used instead.</p>

    <p>Finally, you can add such <span class="code">Person</span> objects to Better
    ListView item collection and they will get converted automatically:</p>

    <p><strong>C#</strong></p>
<pre class="prettyprint"><code class="lang-cs">Person person = new Person();

person.Name = "Jack Black";
person.Age = 38;

listView.Items.Add(person);</code></pre>

    <p><strong>Visual Basic</strong></p>
<pre class="prettyprint"><code class="lang-vb">Dim person As New Person()

person.Name = "Jack Black"
person.Age = 38

listView.Items.Add(person)</code></pre>

    <p>Other item additon methods like Insert, <span class="code">AddRange</span> or
    <span class="code">InsertRange</span> can be used as well.</p>
  
<br><div class="banner">
  <a href="../../../blog/page/6/index.html"><img src="../resources/overview.gif" alt="Better ListView" class="ss"></a>
  <div class="inside">
    <div class="text">Better ListView: Ultimate .NET ListView replacement control for WinForms (C#, VB.NET)</div>
    <span class="dbtn-c dbtn-hilight"><span class="dbtn-w"><a href="../../../betterlistview.exe" class="dbtn">Download</a></span></span>
    <span class="dbtn-c"><span class="dbtn-w"><a href="../../../blog/page/6/index.html" class="dbtn">More Info</a></span></span>
  </div>
</div>
<table class="navigation"><tr>
<td class="navigation-previous"><a href="chapter-checkboxes.html"><strong>
                « Check Boxes</strong></a></td>
<td class="navigation-index"><a href="../../../quick-start-guide/better-listview/index.html"><strong>Index</strong></a></td>
<td class="navigation-next"><a href="chapter-columns.html"><strong>Columns »
              </strong></a></td>
</tr></table>
<br><table class="footer"><tr>
<td class="footer-title">Better ListView Documentation
                </td>
<td class="footer-copyright">
              Copyright © 2010-2012  <a href="../../../index.html" target="_blank">ComponentOwl.com</a>
</td>
</tr></table>
</div></body>
</html>