307 lines
12 KiB
HTML
307 lines
12 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>Using the Control</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="../../../better-thumbnail-browser/quick-start-guide.html"><strong>
|
||
« Quick Start</strong></a></td>
|
||
<td class="navigation-index"><a href="../../../better-thumbnail-browser/documentation.html"><strong>Index</strong></a></td>
|
||
<td class="navigation-next"><a href="chapter-layout.html"><strong>Layout »
|
||
</strong></a></td>
|
||
</tr></table>
|
||
<br><h1>Using the Control</h1>
|
||
<div class="banner">
|
||
<a href="../../../better-thumbnail-browser.html"><img src="../resources/better-thumbnail-browser-overview.gif" alt="Better Thumbnail Browser" class="ss"></a>
|
||
<div class="inside">
|
||
<div class="text">Better Thumbnail Browser for .NET (C#, VB) - Image thumbnail viewing and loading control</div>
|
||
<span class="dbtn-c dbtn-hilight"><span class="dbtn-w"><a href="../../../betterthumbnailbrowser.exe" class="dbtn">Download</a></span></span>
|
||
<span class="dbtn-c"><span class="dbtn-w"><a href="../../../better-thumbnail-browser.html" class="dbtn">More Info</a></span></span>
|
||
</div>
|
||
</div>
|
||
|
||
|
||
|
||
|
||
<h2>Naming Conventions</h2>
|
||
|
||
|
||
<p>Better Thumbnail Browser inherits from Better ListView, so most
|
||
classes are named with BetterListView- prefix. Class names of Better
|
||
ListView are similar to those of .NET ListView, but with the Better-
|
||
prefix.</p>
|
||
|
||
<p>Better Thumbnail Browser uses its own item type -
|
||
<span class="code">BetterThumbnailBrowserItem</span> (which inherits from
|
||
<span class="code">BetterListViewItem</span>). Please use instances of
|
||
<span class="code">BetterThumbnailBrowserItem</span> instead of
|
||
<span class="code">BetterListViewItem</span> although for example the Items collection
|
||
is of type <span class="code">BetterListViewItemCollection</span>. The
|
||
<span class="code">BetterThumbnailBrowserItem</span> contains extra data that Better
|
||
ThumbnailBrowser needs for item loading.</p>
|
||
|
||
|
||
<h2>Auto-populating Better Thumbnail Browser with Items</h2>
|
||
|
||
|
||
<p>You can populate Better Thumbnail Browser with auto-population in
|
||
case you want to display images from an image folder:</p>
|
||
|
||
<p><strong>C#</strong></p>
|
||
<pre class="prettyprint"><code class="lang-cs">thumbnailBrowser.Path = "c:\\images";</code></pre>
|
||
|
||
<p><strong>Visual Basic</strong></p>
|
||
<pre class="prettyprint"><code class="lang-vb">thumbnailBrowser.Path = "c:\images"</code></pre>
|
||
|
||
<p>This will automatically add items to Better Thumbnail Browser and
|
||
starts loading them using default image loading provider:</p>
|
||
|
||
<p class="images"><img src="using-auto-populate.png"></p>
|
||
|
||
|
||
<h2>Populating Better Thumbnail Browser with Items</h2>
|
||
|
||
|
||
<p>This will look for all files with supported extensions (listed in
|
||
<span class="code">SupportedExtensions</span> property), create items for them and
|
||
starts loading image thumbnails immediately.</p>
|
||
|
||
<p>Filling Better Thumbnail Browser with custom items is the same as in
|
||
.NET ListView or Better ListView, but we use the
|
||
<span class="code">BetterThumbnailBrowserItem</span> instances. The following code
|
||
fills Better Thumbnail Browser with 100 items:</p>
|
||
|
||
<p><strong>C#</strong></p>
|
||
<pre class="prettyprint"><code class="lang-cs">thumbnailBrowser.BeginUpdate();
|
||
|
||
for (int indexItem = 0; indexItem < 100; indexItem++)
|
||
{
|
||
thumbnailBrowser.Items.Add(new BetterThumbnailBrowserItem());
|
||
}
|
||
|
||
thumbnailBrowser.EndUpdate();</code></pre>
|
||
|
||
<p><strong>Visual Basic</strong></p>
|
||
<pre class="prettyprint"><code class="lang-vb">thumbnailBrowser.BeginUpdate()
|
||
|
||
For indexItem As Integer = 1 To 100
|
||
thumbnailBrowser.Items.Add(New BetterThumbnailBrowserItem())
|
||
Next
|
||
|
||
thumbnailBrowser.EndUpdate()</code></pre>
|
||
|
||
<p>If you want these items to have thumbnail of specific images from
|
||
disk, set <span class="code">Path</span> property of each item pointing to an image
|
||
file, then call <span class="code">StartLoading()</span> method and Better
|
||
ThumbnailBrowser will load thumbnail images for you.</p>
|
||
|
||
<p><strong>C#</strong></p>
|
||
<pre class="prettyprint"><code class="lang-cs">thumbnailBrowser.BeginUpdate();
|
||
|
||
foreach (string path in Directory.GetFiles("c:\\images"))
|
||
{
|
||
BetterThumbnailBrowserItem item = new BetterThumbnailBrowserItem();
|
||
|
||
item.Path = path;
|
||
|
||
thumbnailBrowser.Items.Add(item);
|
||
}
|
||
|
||
thumbnailBrowser.EndUpdate();
|
||
thumbnailBrowser.StartLoading();</code></pre>
|
||
|
||
<p><strong>Visual Basic</strong></p>
|
||
<pre class="prettyprint"><code class="lang-vb">thumbnailBrowser.BeginUpdate()
|
||
|
||
For Each path As String In Directory.GetFiles("c:\images")
|
||
|
||
Dim item As New BetterThumbnailBrowserItem()
|
||
|
||
item.Path = path
|
||
|
||
thumbnailBrowser.Items.Add(item)
|
||
|
||
Next
|
||
|
||
thumbnailBrowser.EndUpdate()
|
||
thumbnailBrowser.StartLoading()</code></pre>
|
||
|
||
|
||
<h2>Thumbnail Display Options</h2>
|
||
|
||
|
||
<p>Better Thumbnail Browser provider number of properties for adjusting
|
||
thumbnail sizes, paddings and more:</p>
|
||
|
||
<ul style="list-style:none">
|
||
<li>
|
||
<span class="code">CenterThumbnails</span><ul style="list-style:none"><li>
|
||
<p>Align thumbnails to center horizontally.</p>
|
||
</li></ul>
|
||
</li>
|
||
<li>
|
||
<span class="code">ThumbnailImageBorderColor</span><ul style="list-style:none"><li>
|
||
<p>Border color of thumbnail image border.</p>
|
||
</li></ul>
|
||
</li>
|
||
<li>
|
||
<span class="code">ThumbnailImageBorderThickness</span><ul style="list-style:none"><li>
|
||
<p>Thumbnail image border thickness (in pixels).</p>
|
||
</li></ul>
|
||
</li>
|
||
<li>
|
||
<span class="code">ThubmnailImageBorderType</span><ul style="list-style:none"><li>
|
||
<p>Thumbnail image border style (e.g. single line,
|
||
shadow).</p>
|
||
</li></ul>
|
||
</li>
|
||
<li>
|
||
<span class="code">ThumbnailImagePadding</span><ul style="list-style:none"><li>
|
||
<p>Padding around thumbnail image (in pixels).</p>
|
||
</li></ul>
|
||
</li>
|
||
<li>
|
||
<span class="code">ThumbnailInnerPadding</span><ul style="list-style:none"><li>
|
||
<p>Padding between thumbnail item border and its content (in
|
||
pixels).</p>
|
||
</li></ul>
|
||
</li>
|
||
<li>
|
||
<span class="code">ThumbnailOuterPadding</span><ul style="list-style:none"><li>
|
||
<p>Padding between neighboring thumbnail items (in
|
||
pixels).</p>
|
||
</li></ul>
|
||
</li>
|
||
<li>
|
||
<span class="code">ThumbnailTextLines</span><ul style="list-style:none"><li>
|
||
<p>Maximum number of text lines allowed in item label.</p>
|
||
</li></ul>
|
||
</li>
|
||
<li>
|
||
<span class="code">ThumbnailTextPadding</span><ul style="list-style:none"><li>
|
||
<p>Padding around thumbnail label text (in pixels).</p>
|
||
</li></ul>
|
||
</li>
|
||
</ul>
|
||
<p>For more about adjusting display, see chapter <strong><em><a href="chapter-layout.html">Layout</a></em></strong>.</p>
|
||
|
||
|
||
<h2>Sorting Thumbnails with Multiple Columns</h2>
|
||
|
||
|
||
<p>Column headers can be displayed in <span class="code">Thumbnails</span> view and
|
||
the thumbnail items can be sorted using these columns:</p>
|
||
|
||
<p class="images"><img src="using-sorting.png"></p>
|
||
|
||
<p>To display columns, set <span class="code">ColumnsDisplayMode</span> property to
|
||
<span class="code">BetterListViewColumnHeaderDisplayMode.ShowAlways</span>.</p>
|
||
|
||
<p>To enable sorting by specific columns, also set <span class="code">Style</span>
|
||
property of these columns to
|
||
<span class="code">BetterListViewColumnHeaderStyle.Sortable</span>.</p>
|
||
|
||
<p>Sub-items need to be added to every thumbnail item in order to allow
|
||
sorting with multiple columns. Every item is also a single sub-item, so if
|
||
there are four columns, we need to add three sub-items in every item
|
||
(using <span class="code">BetterThumbnailBrowserItem.SubItems</span> property).</p>
|
||
|
||
<p>By default, the sorting uses <span class="code">Key</span> property of
|
||
item/sub-item. If this is not available, item comparer looks for
|
||
<span class="code">Value</span> property and then the <span class="code">Text</span> property of
|
||
items and sub-items. We can use keys instead of labels by setting
|
||
<span class="code">Key</span> property of every item and sub-item. Unlike
|
||
<span class="code">Text</span> property, the <span class="code">Key</span> can contain any
|
||
<span class="code">IComparable</span> instance (e.g. <span class="code">Items[3].SubItems[2].Key =
|
||
0.5</span>).</p>
|
||
|
||
<p>The sorting behavior can be specified by setting
|
||
<span class="code">BetterListViewColumnHeader.SortMethod property</span>.</p>
|
||
|
||
|
||
<h2>Thumbnail Item Loading and Loading Providers</h2>
|
||
|
||
|
||
<p>Item loading is performed by so called <strong><em>loading
|
||
providers</em></strong>. By default, Better Thumbnail Browser uses its own
|
||
loading provider designed for loading images from files on disk.</p>
|
||
|
||
<p>There can be more than one loading provider specified and you can
|
||
set up your own. The loading providers can be accessed through
|
||
<span class="code">LoadingProviders</span> property. It is a list, whose every element
|
||
is a loading provider. If more that one loading provider is specified,
|
||
then the first provider is used on every item until all items are loaded,
|
||
then second is used and so on. Multiple loading providers allow for <strong><em><a href="chapter-loading.html#multi-pass-loading">Multi-pass
|
||
loading</a></em></strong>.</p>
|
||
|
||
<p>You can control item loading by calling <span class="code">StartLoading()</span>,
|
||
<span class="code">StopLoading()</span> and <span class="code">RestartLoading()</span>
|
||
methods.</p>
|
||
|
||
<p>For more about loading providers, see chapter <strong><em><a href="chapter-loading.html">Loading Thumbnails</a></em></strong>.</p>
|
||
|
||
|
||
<h2>Properly Disposing the Control</h2>
|
||
|
||
|
||
<p>Because Better Thumbnail Browser uses thread synchronization. It is
|
||
necessary to stop item loading before disposing the control. This is done
|
||
automatically if the control is placed <strong><em>directly</em></strong> in a
|
||
form, but if Better Thumbnail Browser is deeper in control hierarchy, it
|
||
cannot detect the owner form closing and you should call
|
||
<span class="code">StopLoading()</span> method in <span class="code">FormClosed</span> event
|
||
handler:</p>
|
||
|
||
<p><strong>C#</strong></p>
|
||
<pre class="prettyprint"><code class="lang-cs">...
|
||
|
||
protected override void OnFormClosed(FormClosedEventArgs e)
|
||
{
|
||
base.OnFormClosed(e);
|
||
this.thumbnailBrowser.StopLoading();
|
||
}
|
||
|
||
...</code></pre>
|
||
|
||
<p><strong>Visual Basic</strong></p>
|
||
<pre class="prettyprint"><code class="lang-vb">...
|
||
|
||
Protected Overrides Sub OnFormClosed(e As FormClosedEventArgs)
|
||
|
||
MyBase.OnFormClosed(e)
|
||
Me.thumbnailBrowser.StopLoading()
|
||
|
||
End Sub
|
||
|
||
...</code></pre>
|
||
|
||
<br><div class="banner">
|
||
<a href="../../../better-thumbnail-browser.html"><img src="../resources/better-thumbnail-browser-overview.gif" alt="Better Thumbnail Browser" class="ss"></a>
|
||
<div class="inside">
|
||
<div class="text">Better Thumbnail Browser for .NET (C#, VB) - Image thumbnail viewing and loading control</div>
|
||
<span class="dbtn-c dbtn-hilight"><span class="dbtn-w"><a href="../../../betterthumbnailbrowser.exe" class="dbtn">Download</a></span></span>
|
||
<span class="dbtn-c"><span class="dbtn-w"><a href="../../../better-thumbnail-browser.html" class="dbtn">More Info</a></span></span>
|
||
</div>
|
||
</div>
|
||
<table class="navigation"><tr>
|
||
<td class="navigation-previous"><a href="../../../better-thumbnail-browser/quick-start-guide.html"><strong>
|
||
« Quick Start</strong></a></td>
|
||
<td class="navigation-index"><a href="../../../better-thumbnail-browser/documentation.html"><strong>Index</strong></a></td>
|
||
<td class="navigation-next"><a href="chapter-layout.html"><strong>Layout »
|
||
</strong></a></td>
|
||
</tr></table>
|
||
<br><table class="footer"><tr>
|
||
<td class="footer-title">Better Thumbnail Browser Documentation
|
||
</td>
|
||
<td class="footer-copyright">
|
||
Copyright © 2010-2012 <a href="../../../index.html" target="_blank">ComponentOwl.com</a>
|
||
</td>
|
||
</tr></table>
|
||
</div></body>
|
||
</html>
|