jarvis/componentowl-astro
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
componentowl-astro/public/documentation/better-thumbnail-browser/data/chapter-layout.html

601 lines
25 KiB
HTML
Raw Permalink Blame History

This file contains invisible Unicode characters
This file contains invisible Unicode characters that are indistinguishable to humans but may be processed differently by a computer. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
<!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>Layout</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-using.html"><strong>
« Using the Control</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-loading.html"><strong>Loading Thumbnails »
</strong></a></td>
</tr></table>
<br><h1>Layout</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>
<p>Better ListView consists of three visual parts: <strong><em>column
headers</em></strong>, <strong><em>items</em></strong>
(<strong><em>sub-items</em></strong>) and <strong><em>groups</em></strong>. Each of
these has its corresponding <span class="code">BetterListViewLayout</span> instance that
defines how to measure and position elements in these parts. Furthermore,
every view has its layout, because it behaves differently, can contain
images of different size, etc. The layout instances can be accessed through
these properties:</p>
<ul>
<li>
<p><span class="code">LayoutColumns</span></p>
</li>
<li>
<p><span class="code">LayoutGroupsCurrent</span> (<strong><em>depends on current
view</em></strong>)</p>
</li>
<li>
<p><span class="code">LayoutItemsCurrent</span> (<strong><em>depends on current
view</em></strong>)</p>
</li>
</ul>
<p>There are also properties for specific views, so you can address
layout properties of other than current view:</p>
<ul>
<li>
<p><span class="code">LayoutGroupsHorizontal</span></p>
</li>
<li>
<p><span class="code">LayoutGroupsVertical</span></p>
</li>
<li>
<p><span class="code">LayoutItemsDetails</span> (<strong><em>used when columns are
not present in Details view</em></strong>)</p>
</li>
<li>
<p><span class="code">LayoutItemsDetailsColumns</span></p>
</li>
<li>
<p><span class="code">LayoutItemsLargeIcon</span></p>
</li>
<li>
<p><span class="code">LayoutItemsList</span></p>
</li>
<li>
<p><span class="code">LayoutItemsSmallIcon</span></p>
</li>
<li>
<p><span class="code">LayoutItemsThumbnails</span></p>
</li>
<li>
<p><span class="code">LayoutItemsTile</span></p>
</li>
</ul>
<p>All the layout properties properties always reference the same
instance of <span class="code">BetterListViewLayout</span> except for
<span class="code">LayoutGroupsCurrent</span> and <span class="code">LayoutItemsCurrent</span> which
depend on current view. There are also two layouts for
<strong><em>Details</em></strong> view. This is because Better ListView uses
different layout for items in <strong><em>Details</em></strong> view with and
without columns (regular .NET ListView supports <strong><em>Details</em></strong>
view, but only when columns are visible).</p>
<p>These layout contain properties defining sizes and paddings of all the
elements and element parts. These properties are descibed below in their
contexts.</p>
<h2>Thumbnail Size</h2>
<p>Current thumbnail image size can be changed using
<span class="code">ThumbnailSize</span> property. The value is a space reserved for
thumbnail image, although the image can be larger or smaller than
<span class="code">ThumbnailSize</span>. When the image is larger, it is resized
proportionally to fit in size defined by <span class="code">ThumbnailSize</span>. When
the image is smaller, it is centered within area of reserved space.</p>
<h2>ThumbnailSizeChanged Event</h2>
<p>When value of <span class="code">ThumbnailSize</span> property is changed,
either from code or by the user, a <span class="code">ThumbnailSizeChanged</span>
event is raised. The even contains data about current view, current
thumbnail size and the new thumbnail size.</p>
<h2>Mousewheel Thumbnail Resizing</h2>
<p>Better Thumbnail Browser supports resizing thumbnails by using
<strong><em>Control</em></strong> key + mouse wheel.</p>
<p>The same resizing effect can be achieved by calling
<span class="code">ZoomIn()</span> and <span class="code">ZoomOut()</span> methods. Both methods
return boolean value, which is false if further zooming is not
possible.</p>
<p>You can specify allowed thumbnail sizes using the
<span class="code">ThumbnailSizesMouseWheel</span> property. It is simply a list of
<span class="code">System.Drawing.Size</span> instances sorted from smaller to
larger.</p>
<p>When <strong><em>Control+MouseWheel</em></strong> combination is used,
or when <span class="code">ZoomIn()</span> or <span class="code">ZoomOut()</span> method is used,
a nearest size from the <span class="code">ThumbnailSizesMouseWheel</span> list is
chosed and then next or previous item from the list is used as a new
thubmnail size.</p>
<h2>Centering Thumbnails</h2>
<p>Thumbnails are horzontally centered by default, but can be brought
to the left side by setting <span class="code">CenterThumbnails</span> property to
<span class="code">false</span>:</p>
<p class="images"><img src="layout-thumbnails-center1.jpg"></p>
<p class="images"><img src="layout-thumbnails-center2.jpg"></p>
<h2>Spacing Between Thumbnails</h2>
<p>Spacing between thumbnails can be controlled by
<span class="code">ThumbnailOuterPadding</span> property, which is of type
<span class="code">System.Drawing.Size</span> (you can set horizontal and vertical
padding separately):</p>
<p class="images"><img src="layout-thumbnails-spacing.jpg"></p>
<h2>Image Borders</h2>
<p>There are three properties for controlling thumbnail image
borders:</p>
<ul style="list-style:none">
<li>
<span class="code">ThumbnailImageBorderColor</span><ul style="list-style:none"><li>
<p>A color of the border, be it a line or shadow.</p>
</li></ul>
</li>
<li>
<span class="code">ThumbnailImageBorderThickness</span><ul style="list-style:none"><li>
<p>Thickness of the border, in pixels. It applies for shadow size
as well. The border size is limited by
<span class="code">ThumbnailInnerPadding</span> value, so if you want very thick
borders, remember to set this property to larger value.</p>
</li></ul>
</li>
<li>
<span class="code">ThumbnailImageBorderType</span><ul style="list-style:none"><li>
<p>Style of image border - there are several options.</p>
</li></ul>
</li>
</ul>
<p class="images"><img src="layout-thumbnails-border.jpg"></p>
<h2>Internal Paddings</h2>
<p>There are several additional properties for controlling paddings
around content of each thumbnail. Each is of type
<span class="code">System.Windows.Forms.Padding</span>, so that the padding is defined
for every side separately (top, bottom, left, right):</p>
<ul style="list-style:none">
<li>
<span class="code">ThumbnailImagePadding</span><ul style="list-style:none"><li>
<p>Padding around thumbnail image. This make space for possible
image border or shadow.</p>
</li></ul>
</li>
<li>
<span class="code">ThumbnailInnerPadding</span><ul style="list-style:none"><li>
<p>Padding between thumbnail image boundary and its
content.</p>
</li></ul>
</li>
<li>
<span class="code">ThumbnailTextPadding</span><ul style="list-style:none"><li>
<p>Padding around thumbnail item label.</p>
</li></ul>
</li>
</ul>
<h2>Custom Item Height</h2>
<p>Item height can be customized with
<span class="code">BetterListViewItem.CustomHeight</span> property. The default value
is <span class="code">0</span>, which means that the custom height if effectively not
used.</p>
<p>Every item has some minimum height determined by its font, image and
number of text lines. The <span class="code">CustomHeight</span> value will take effect
whenever it is larger than the minimum height.</p>
<p>The following image shows items with different heights:</p>
<p class="images"><img src="layout-customheight.png"></p>
<p>The property works for <strong><em>Details</em></strong> view
only.</p>
<h2>
<a name="text-layout" id="text-layout"></a>Text Layout</h2>
<p>The only common property for all layouts is
<span class="code">TextPadding</span>, which is the spacing around text area.</p>
<p>There is no property for settings text size, because it depends on
text in each element. There is, however, some control over text height. It
is different for column header, group, and item layout.</p>
<p>Column header and group layouts share a property called
<span class="code">MinimumTextHeight</span>. This is a minimum allowed height of the
text area. When the actual text height is smaller than this value, the
text area will have <span class="code">MinimumTextHeight</span> pixels in vertical
dimension and the text will be centered vertically in it.</p>
<p>Column header and item layouts have an extra property called
<span class="code">MaximumTextLines</span> which allows displaying multi-line text.
When its value is greater than <span class="code">1</span>, the text is first broken
into multiple lines up to the specified value. Text trimming is used when
there is no remaining lines left:</p>
<p class="images"><img src="layout-multiline1.png"></p>
<p>In this example, <span class="code">MaximumTextLines</span> property was set to
<span class="code">3</span> for both column headers and items:</p>
<p><strong>C#</strong></p>
<pre class="prettyprint"><code class="lang-cs">listView.LayoutColumnHeaders.MaximumTextLines = listView.LayoutItemsCurrent.MaximumTextLines = 3;</code></pre>
<p><strong>Visual Basic</strong></p>
<pre class="prettyprint"><code class="lang-vb">ListView.LayoutColumnHeaders.MaximumTextLines = ListView.LayoutItemsCurrent.MaximumTextLines = 3</code></pre>
<p>When the column width is too small to maintain given text, even then
the text is trimmed:</p>
<p class="images"><img src="layout-multiline2.png"></p>
<p>Maximum allowed number of text lines can also be specified on each
sub-item individually by setting
<span class="code">BetterListViewSubItem.MaximumTextLines</span>.</p>
<h2>Default Image Alignment</h2>
<p>Every view defined default image alignment. For example, image in
<strong><em>Details</em></strong> view is usually aligned on the left side of
text. You can set the <span class="code">DefaultImageAlignmentHorizontal</span> and
<span class="code">DefaultImageAlignmentVertical</span> properties of the item layout.
Group and column header layout also support these properties.</p>
<p>For example, setting
LayoutGroupsCurrent.DefaultImageAlignmentHoriozontal to
<span class="code">BetterListViewImageAlignmentHorizontal.AfterTextCenter</span>
results in the following image alignment on all the groups:</p>
<p class="images"><img src="layout-image-align.png"></p>
<p>It is possible to change image alignment on every item, sub-item,
column header and group separately.</p>
<h2>
<a name="default-alignment-trimming" id="default-alignment-trimming"></a>Default Text Alignment
and Trimming</h2>
<p>Every view defines default text alignment and trimming. For example,
text in <strong><em>Details</em></strong> view is usually aligned on left,
while in <strong><em>LargeIcon</em></strong> view is centered. You can set the
<span class="code">DefaultTextAlignmentHorizontal</span>,
<span class="code">DefaultTextAlignmentVertical</span> and
<span class="code">DefaultTextTrimming</span> properties of the item layout.</p>
<p>These properties are used on item when the item has
<span class="code">AlignHorizontal</span> property set to
<span class="code">TextAlignmentHorizontal.Default</span>, <span class="code">AlignVertical</span>
property to <span class="code">TextAlignmentVertical.Default</span> and
<span class="code">TextTrimming</span> property to
<span class="code">TextTrimming.Undefined</span>.</p>
<p>Text alignment and trimming can be set on each element individually
(see <strong><em><a href="chapter-text-formatting.html">Text
Formatting</a></em></strong>).</p>
<h2>Image Layout</h2>
<p>Better ListView can display images of arbitrary sizes (not only
predefined ones) in all views and always keeps aspect ratios of the
images.</p>
<p>Images are downscaled, if needed, but never upscaled (they are
rather centered in the larger bounding box).</p>
<p>Image layout options affect a bounding box, in which images are
aligned. It is also possible to set up image paddings and borders of
different styles and sizes.</p>
<p>Image layout can be adjusted on all Better ListView layouts through
the corresponding properties described below.</p>
<h2>Image Size</h2>
<p>Column and group layouts contain <span class="code">ImageSize</span> property to
manually adjust area for placing images.</p>
<p>Item layouts contain also <span class="code">SubImageSizes</span> property which
is array of <span class="code">BetterListViewImageSize</span> objects. The collection
should contain at leat one <span class="code">BetterListViewImageSize</span> instance
(returned by <span class="code">ImageSize</span> property). When the collection
contains more tnat one entry, item and sub-items can have different image
area sizes.</p>
<p>The <span class="code">BetterListViewImageSize</span> instance holds minimum and
maximum allowed image size for the corresponding item/sub-item. Better
ListView will always fit images within these boundaries.</p>
<p>You can set specific image size for some layout:</p>
<p><strong>C#</strong></p>
<pre class="prettyprint"><code class="lang-cs">listView.LayoutItemsLargeIcon.ImageSizes = new[] { new BetterListViewImageSize(new Size(97, 34)) };</code></pre>
<p><strong>Visual Basic</strong></p>
<pre class="prettyprint"><code class="lang-vb">ListView.LayoutItemsLargeIcon.ImageSizes = New BetterListViewImageSizeSize() {New BetterListViewImageSizeSize(New Size(97, 34))}</code></pre>
<p>We set bounding box for images in the <span class="code">LargeIcon</span>
view.</p>
<p>The following images show how Better ListView fits larger images
into such bounding box (displayed in gray):</p>
<p class="images"><img src="layout-image-large-source.png"><img src="layout-image-large-target.png"></p>
<p>Smaller images are just centered:</p>
<p class="images"><img src="layout-image-small-source.png"><img src="layout-image-small-target.png"></p>
<h2>Minimum Text Size</h2>
<p>It is possible to customize minimum text area size.</p>
<p>Every item has text area size determined by minimum size and actual
text size. The minimum size is cointrolled by
<span class="code">BetterListViewLayout.EmptyTextSize</span> property. We can set
<span class="code">EmptyTextSize</span> to desired minimal size of text:</p>
<p><strong>C#</strong></p>
<pre class="prettyprint"><code class="lang-cs">listView.LayoutItemsCurrent.AutoSizeText = true;
listView.LayoutItemsCurrent.EmptyTextSize = new Size(8, 8);</code></pre>
<p><strong>Visual Basic</strong></p>
<pre class="prettyprint"><code class="lang-vb">listView.LayoutItemsCurrent.AutoSizeText = False
listView.LayoutItemsCurrent.EmptyTextSize = New Size(8, 8)</code></pre>
<p>The sample code sets <span class="code">EmptyTextSize</span> to (8,8). This is
the minimum allowed text area size.</p>
<p>The following image shows automatic sizing of the text when minimum
text size is set to small value, so that child items (with smaller font)
are allowed to be smaller:</p>
<p class="images"><img src="layout-text-autosize.png"></p>
<h2>Image Border</h2>
<p>Image is an element part and as such it has some padding around it.
This is just empty space around the image to keep it in distance from
other elements. This padding can be adjusted via
<span class="code">BetterListViewLayoutItems.ImagePadding</span> property of the
corresponding layout.</p>
<p>There are also two other properties available in item layouts, which
allows setting painted frame around the image. These are:</p>
<ul>
<li>
<p><span class="code">ImageBorderColor</span></p>
</li>
<li>
<p><span class="code">ImageBorderType</span></p>
</li>
<li>
<p><span class="code">ImageBorderThickness</span> (in
<strong><em>pixels</em></strong>)</p>
</li>
</ul>
<p>For example, setting:</p>
<p><strong>C#</strong></p>
<pre class="prettyprint"><code class="lang-cs">listView.LayoutItemsCurrent.ImageBorderType = ImageBorderType.SingleOffset;
listView.LayoutItemsCurrent.ImageBorderThickness = 2;</code></pre>
<p><strong>Visual Basic</strong></p>
<pre class="prettyprint"><code class="lang-vb">ListView.LayoutItemsCurrent.ImageBorderType = ImageBorderType.SingleOffset
ListView.LayoutItemsCurrent.ImageBorderThickness = 2</code></pre>
<p>Yields this kind of image border:</p>
<p class="images"><img src="layout-thumbnails.png"></p>
<h2>Column Headers Properties</h2>
<p>These properties are specific to column headers layout:</p>
<ul>
<li>
<p><span class="code">BetterListViewLayoutColumnHeaders.BorderSize</span></p>
</li>
<li>
<p><span class="code">BetterListViewLayoutColumnHeaders.SortGlyphPadding</span></p>
</li>
</ul>
<p><span class="code">BorderSize</span> defines extent of boundary at the right end
of each column header. When mouse cursor hovers over this boundary, the
column header can be resized.</p>
<p><span class="code">SortGlyphPadding</span> is the spacing around sort glyph,
which is displayed when the column header is sorted. It is displayed as an
arrow pointing upwards or downwards (dependind on sort order). When visual
style can be used, this glyph is located in the top part of column header.
It is located in the right part, otherwise.</p>
<h2>Group Properties</h2>
<p>There is only one property specific to group layout, which is
<span class="code">BetterListViewLayoutGroups.MinimumSize</span>. This is a minimum
allowed size of a group. For vertically oriented groups, only height
dimension is taken into account.</p>
<p>Layout of vertically oriented groups supports also
<span class="code">BetterListViewLayoutGroupsVertical.ExpandButtonPadding</span>
property. This is a spacing around group expand button.</p>
<h2>Common Properties</h2>
<p>All the layouts share following properties:</p>
<ul>
<li>
<p><span class="code">BetterListViewLayout.ElementInnerPadding</span></p>
</li>
<li>
<p><span class="code">BetterListViewLayout.ElementOuterPadding</span></p>
</li>
<li>
<p><span class="code">BetterListViewLayout.LayoutPadding</span></p>
</li>
</ul>
<p>Each element has inner padding specified by
<span class="code">ElementInnerPadding</span>, which is a distance between element
boundary and its content. These is also outer padding specified by
<span class="code">ElementOuterPadding</span>, which is a distance between
elements.</p>
<p>Whole layout has also a padding specified by
<span class="code">LayoutPadding</span>. This is a distance between elements and its
containing area (control or group).</p>
<p>Following image shows different areas with and without
paddings:</p>
<p class="images"><img src="layout-padding.png"></p>
<h2>Centering Items in LargeIcon and Thumbnails View</h2>
<p>Earch row of items in LargeIcon and Thumbnails view can be aligned
either to the left or to center of the client area. This can be done using
Center property of the corresponding layout (LayoutItemsLargeIcon.Center
or LayoutItemsThumbnails.Center). The following images show how items are
aligned when the Center property is set to true and false:</p>
<p class="images"><img src="layout-center1.png"><img src="layout-center2.png"></p>
<h2>Sample Source Code</h2>
<p>The following sample shows setting up Better ListView to display
multi-line items in <strong><em>Details</em></strong> view stretched to width
of a client area (because there are no columns added):</p>
<p><strong>C#</strong></p>
<pre class="prettyprint"><code class="lang-cs">this.listView.BeginUpdate();
this.listView.Items.AddRange(
new[]
{
"Item label can be split in several lines defined by MaximumTextLines property of layout class corresponding to current View.",
"All text trimming methods also works with multi-line items. When some items cannot be split to more lines, trimming with additional ellipsis can be used."
});
// resize items in Details view with content to show how the text breaks
// other way would be to add column and see text breaking when resizing the column
this.listView.AutoSizeItemsInDetailsView = true;
// enable multi-line items by settings maximum allowed text lines to a number larger than 1
this.listView.LayoutItemsDetails.MaximumTextLines = 4; //NOTE: we can also use LayoutItemsCurrent for the view currently set
this.listView.EndUpdate();</code></pre>
<p><strong>Visual Basic</strong></p>
<pre class="prettyprint"><code class="lang-vb">ListView.Items.AddRange (
New String() { _
"Item label can be split in several lines defined by MaximumTextLines property of layout class corresponding to current View.",
"All text trimming methods also works with multi-line items. When some items cannot be split to more lines, trimming with additional ellipsis can be used."
})
' resize items in Details view with content to show how the text breaks
' other way would be to add column and see text breaking when resizing the column
ListView.AutoSizeItemsInDetailsView = True
' enable multi-line items by settings maximum allowed text lines to a number larger than 1
ListView.LayoutItemsDetails.MaximumTextLines = 4
'NOTE: we can also use LayoutItemsCurrent for the view currently set
ListView.EndUpdate()</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="chapter-using.html"><strong>
« Using the Control</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-loading.html"><strong>Loading Thumbnails »
</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>
Reference in New Issue View Git Blame Copy Permalink