361 lines
15 KiB
HTML
361 lines
15 KiB
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>Items</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-item-reorder.html"><strong>
|
||
« Item Reordering</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-label-edit.html"><strong>Label Editing »
|
||
</strong></a></td>
|
||
</tr></table>
|
||
<br><h1>Items</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 items can be selected or their check state changed in
|
||
two ways - setting properties on items or using specific collections.</p>
|
||
|
||
<h2>Selecting Items</h2>
|
||
|
||
|
||
<p>The easy way to select or deselect some item is to set
|
||
<span class="code">BetterListViewItem.Selected</span> property to
|
||
<span class="code">true</span>.</p>
|
||
|
||
<p>When you need to select multiple items, it would be more efficient
|
||
to use one of these collections:</p>
|
||
|
||
<ul>
|
||
<li>
|
||
<p><span class="code">BetterListView.SelectedIndices</span></p>
|
||
</li>
|
||
<li>
|
||
<p><span class="code">BetterListView.SelectedItems</span></p>
|
||
</li>
|
||
</ul>
|
||
<p>These properties have only getter, so to edit selection, simply
|
||
modify the collection. For example, the code to select all items in the
|
||
list would look like this:</p>
|
||
|
||
<p><strong>C#</strong></p>
|
||
<pre class="prettyprint"><code class="lang-cs">listView.SelectedItems.Set(listView.Items);</code></pre>
|
||
|
||
<p><strong>Visual Basic</strong></p>
|
||
<pre class="prettyprint"><code class="lang-vb">ListView.SelectedItems.Set(listView.Items)</code></pre>
|
||
|
||
<p>In addition to standard collection operations
|
||
(<strong><em>add</em></strong>, <strong><em>remove</em></strong>,
|
||
<strong><em>clear</em></strong>...) the collections provide a <span class="code">Set</span>
|
||
method allowing to change selection from one set of items to
|
||
another.</p>
|
||
|
||
<p>Note that when you use <span class="code">SelectedIndices</span>, you obtain and
|
||
can set only indices of top-level items, while <span class="code">SelectedItems</span>
|
||
allows you to set selections for hierarchical items as well.</p>
|
||
|
||
<p>If you are accustomed to use <strong><em><a href="chapter-data.html">Data Binding</a></em></strong>, the following
|
||
properties provide you the means for selecting items via addressing
|
||
objects they represent:</p>
|
||
|
||
<ul>
|
||
<li>
|
||
<p><span class="code">BetterListView.SelectedValue</span></p>
|
||
</li>
|
||
<li>
|
||
<p><span class="code">BetterListView.SelectedValues</span></p>
|
||
</li>
|
||
</ul>
|
||
<h2>Checking Items</h2>
|
||
|
||
|
||
<p>To change check state of some item, set
|
||
<span class="code">BetterListViewItem.Checked</span> or
|
||
<span class="code">BetterListViewItem.CheckState</span> property. The
|
||
<span class="code">CheckState</span> property allows you to set indeterminate state of
|
||
items (supported if <span class="code">BetterListView.CheckBoxes</span> property is set
|
||
to <span class="code">ThreeState</span>), while <span class="code">Checked</span> is just for
|
||
checked/unchecked state.</p>
|
||
|
||
<p>When you need to check multiple items, it would be more efficient to
|
||
use one of these collections:</p>
|
||
|
||
<ul>
|
||
<li>
|
||
<p><span class="code">BetterListView.SelectedIndices</span></p>
|
||
</li>
|
||
<li>
|
||
<p><span class="code">BetterListView.SelectedItems</span></p>
|
||
</li>
|
||
</ul>
|
||
<p>These properties have only getter, so to edit selection, simply
|
||
modify the collection. For example, the code to un-check all items in the
|
||
list would look like this:</p>
|
||
|
||
<p><strong>C#</strong></p>
|
||
<pre class="prettyprint"><code class="lang-cs">listView.CheckedItems.Clear();</code></pre>
|
||
|
||
<p><strong>Visual Basic</strong></p>
|
||
<pre class="prettyprint"><code class="lang-vb">ListView.CheckedItems.Clear()</code></pre>
|
||
|
||
<p>In addition to standard collection operations
|
||
(<strong><em>add</em></strong>, <strong><em>remove</em></strong>,
|
||
<strong><em>clear</em></strong>...) the collections provide a <span class="code">Set</span>
|
||
method allowing to change selection from one set of items to
|
||
another.</p>
|
||
|
||
<p>Note that when you use <span class="code">CheckedIndices</span>, you obtain and
|
||
can set only indices of top-level items, while <span class="code">CheckedItems</span>
|
||
allows you to set selections for hierarchical items as well.</p>
|
||
|
||
<br><hr>
|
||
<p class="note">The <span class="code">CheckedItems</span> and <span class="code">CheckedIndices</span>
|
||
collections do not contain items in indeterminate check state.</p>
|
||
<hr>
|
||
<br><h2>Detecting selection and check state changes</h2>
|
||
|
||
|
||
<p>Better ListView provides several events to detect when selection or
|
||
check state of items change:</p>
|
||
|
||
<ul style="list-style:none">
|
||
<li>
|
||
<span class="code">CheckedItemsChanged</span><ul style="list-style:none"><li>
|
||
<p>Raised when value of <span class="code">CheckedItems</span> property has
|
||
changed. It is raised once every time check state of items changes,
|
||
even when multiple items are checked in one operation.</p>
|
||
</li></ul>
|
||
</li>
|
||
<li>
|
||
<span class="code">ItemCheck</span><ul style="list-style:none"><li>
|
||
<p>Raised when item check state is about to change. You can
|
||
cancel the check operation in the event handler. If multiple items
|
||
change its check state, this event is raised multiple times.</p>
|
||
</li></ul>
|
||
</li>
|
||
<li>
|
||
<span class="code">ItemChecked</span><ul style="list-style:none"><li>
|
||
<p>Raised after an item has been checked. If multiple items
|
||
change its check state, this event is raised multiple times.</p>
|
||
</li></ul>
|
||
</li>
|
||
<li>
|
||
<span class="code">ItemSelectionChanged</span><ul style="list-style:none"><li>
|
||
<p>Raised for every item whose <span class="code">Selected</span> property has
|
||
changed. If multiple items has been selected and de-selected, this
|
||
event will be raised multiple times.</p>
|
||
</li></ul>
|
||
</li>
|
||
<li>
|
||
<span class="code">SelectedIndexChanged</span><ul style="list-style:none"><li>
|
||
<p>Raised when index of the focused selected item has been
|
||
changed. This event is useful when only single item can be selected
|
||
(i.e. <span class="code">MultiSelect</span> is set to <span class="code">false</span>).</p>
|
||
</li></ul>
|
||
</li>
|
||
<li>
|
||
<span class="code">SelectedItemsChanged</span><ul style="list-style:none"><li>
|
||
<p>Raised when value of <span class="code">SelectedItems</span> property has
|
||
changed. It is raised once every time selection changes, even when
|
||
multiple items are selected in one operation (e.g. Shift+click on
|
||
some item).</p>
|
||
</li></ul>
|
||
</li>
|
||
</ul>
|
||
<p>It should be noted that selection is tied with Better ListView,
|
||
rather than with individual items. So if you move item from one ListView
|
||
to another, the selection state of the item is <strong><em>not</em></strong>
|
||
preserved.</p>
|
||
|
||
<p>On the other hand, check state is a property of each item. If you
|
||
move item from one ListView to another, check state of the item is
|
||
preserved.</p>
|
||
|
||
<p>When you need to determine how the check state has been changed, use
|
||
the <span class="code">CheckStateChangeMode</span> property of ItemCheck,
|
||
<span class="code">ItemCheck</span> or <span class="code">CheckedItemsChanged</span> event data. It
|
||
can have one of three values (the fourth value of enumeration is not
|
||
used):</p>
|
||
|
||
<ul style="list-style:none">
|
||
<li>
|
||
<span class="code">Keyboard</span><ul style="list-style:none"><li>
|
||
<p>Check state changed by keyboard.</p>
|
||
</li></ul>
|
||
</li>
|
||
<li>
|
||
<span class="code">Mouse</span><ul style="list-style:none"><li>
|
||
<p>Check state changed by mouse.</p>
|
||
</li></ul>
|
||
</li>
|
||
<li>
|
||
<span class="code">UserCode</span><ul style="list-style:none"><li>
|
||
<p>Check state change from user code.</p>
|
||
</li></ul>
|
||
</li>
|
||
<li>
|
||
<span class="code">Undefined</span><ul style="list-style:none"><li>
|
||
<p>Check state change not defined. Not used in event data.</p>
|
||
</li></ul>
|
||
</li>
|
||
</ul>
|
||
<h2>Check If Any Item Is Selected</h2>
|
||
|
||
|
||
<p>To check if there is any item selected, use
|
||
<span class="code">IsAnythingSelected</span> boolean property.</p>
|
||
|
||
<p>You can also test whether <span class="code">SelectedItems.Count</span> or
|
||
<span class="code">SelectedIndcies.Count</span> is equal to zero, but the above
|
||
property provides potentially faster response.</p>
|
||
|
||
|
||
<h2>Hiding and Preserving Selections</h2>
|
||
|
||
|
||
<p>By default, when Better ListView loses focus, selections on items
|
||
disappears.</p>
|
||
|
||
<p>To preserve display of item selection, set
|
||
<span class="code">HideSelection</span> property to <span class="code">false</span>. This will cause
|
||
selections on unfocused control to be displayed in disabled state.</p>
|
||
|
||
<p>If you need to draw selection always highlighted, use the
|
||
<span class="code">HideSelectionMode</span> property, which is more thorough than
|
||
<span class="code">HideSelection</span>. The following images show unfocused Better
|
||
ListView with <span class="code">HideSelectionMode</span> property set to
|
||
<span class="code">Hide</span>, <span class="code">Disable</span> and
|
||
<span class="code">KeepSelection</span>:</p>
|
||
|
||
<p class="images"><img src="items-hide.png"><img src="items-disable.png"><img src="items-keep.png"></p>
|
||
|
||
|
||
<h2>Non-selectable Items</h2>
|
||
|
||
|
||
<p>Every item can is selectable by default. When
|
||
<span class="code">BetterListViewItem.Selectable</span> property is set to
|
||
<span class="code">false</span>, the item can no longer be selected by keyboard or
|
||
mouse. These items can still be selected from user code (e.g. calling
|
||
<span class="code">SelectedItems.Add</span>).</p>
|
||
|
||
<p>The following images show that non-selectable items can be used as
|
||
separators (with owner drawing) and simply as disabled items - the
|
||
non-selectable items can still be expanded/collapsed if contain
|
||
children:</p>
|
||
|
||
<p class="images"><img src="items-nonselectable1.png"><img src="items-nonselectable2.png"></p>
|
||
|
||
|
||
<h2>Circular Selection</h2>
|
||
|
||
|
||
<p>Sometimes it is pleasant to connect the first and the last item so
|
||
that the focus and selection can move from the last item to the first one
|
||
and vice versa.</p>
|
||
|
||
<p>This behavior can be turned by setting
|
||
<span class="code">CircularSelection</span> property to <span class="code">true</span>.</p>
|
||
|
||
<p>The following image shows how selection moves when circular
|
||
selection is active and the user is pressing down arrow:</p>
|
||
|
||
<p class="images"><img src="items-circular.png"></p>
|
||
|
||
|
||
<h2>
|
||
<a name="combined-items" id="combined-items"></a>Combined Items</h2>
|
||
|
||
|
||
<p>Parent and child items can be selected separately, by default. You
|
||
can combine parent and child items to behave just like a single item by
|
||
setting <span class="code">BetterListViewItem.AllowSelectChildItems</span> to
|
||
<span class="code">false</span>.</p>
|
||
|
||
<p>Even when combined, child items can use individual check boxes and
|
||
can be detected with a hit test (see <strong><em><a href="chapter-hit-test.html">Hit Test</a></em></strong> for more
|
||
information).</p>
|
||
|
||
<p>The following screenshots show combined items in action:</p>
|
||
|
||
<p class="images"><img src="items-combineditems1.png"><img src="items-combineditems2.png"></p>
|
||
|
||
<p>To determine which item is actually the "selectable parent" one, use
|
||
a <span class="code">BetterListViewItem.SelectableItem</span> property. The child items
|
||
provide reference to parent item with <span class="code">AllowSelectChildItems</span>
|
||
property set to <span class="code">false</span> in the
|
||
<span class="code">BetterListViewItem.SelectableItem</span> property.</p>
|
||
|
||
|
||
<h2>
|
||
<a name="hide-items" id="hide-items"></a>Hiding Items</h2>
|
||
|
||
|
||
<p>Items can be hidden by setting
|
||
<span class="code">BetterListViewItem.Visible</span> property to
|
||
<span class="code">false</span>.</p>
|
||
|
||
<p>The hiding affects only display of the item, the item is still
|
||
present in its owner collection.</p>
|
||
|
||
<p>If you hide an item containing child items, the child items will be
|
||
hidden as well.</p>
|
||
|
||
<p>Hiding have the same effect as if the item has been removed from
|
||
<span class="code">Items</span> (or <span class="code">BetterListView.ChildItems</span>,
|
||
respectively) collection, but is still present in the collection.</p>
|
||
|
||
|
||
<h2>Getting Visible Items Only</h2>
|
||
|
||
|
||
<p>Some items may be scrolled out of view or hidden (see <strong><em><a href="chapter-items.html#hide-items">Hiding Items</a></em></strong>). If you need to iterate
|
||
through the visible items only, use the <span class="code">VisibleItems</span>
|
||
property. The property getter returns collection which is re-created
|
||
whenever the visibility of items changes.</p>
|
||
|
||
<p>The collection contains items regardless of hierarchy, so there are
|
||
both parent and child items. If you need only the visible top-level items,
|
||
for example, you need to filter them out using the
|
||
<span class="code">BetterListViewItem.Level</span> property.</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-item-reorder.html"><strong>
|
||
« Item Reordering</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-label-edit.html"><strong>Label Editing »
|
||
</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>
|