Files
componentowl-astro/public/documentation/better-thumbnail-browser/data/chapter-text-formatting.html

549 lines
21 KiB
HTML
Raw 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>Text Formatting</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-loading.html"><strong>
« Loading Thumbnails</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-background-image.html"><strong>Background Image »
</strong></a></td>
</tr></table>
<br><h1>Text Formatting</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>Text formatting consists of text alignment, trimming, font and color.
It can be adjusted on column headers, groups, items and sub-items.</p>
<h2>Formatting File Names</h2>
<p>In case the Better Thumbnail Browser is populated automatically by
files from a folder (specified by setting the <span class="code">Path</span> property),
the file name format can be specified by setting the
<span class="code">FilenameFormatOptions</span> property. It is an enumeration with
following flags:</p>
<ul style="list-style:none">
<li>
<span class="code">None</span><ul style="list-style:none"><li>
<p>No extra formatting applied.</p>
</li></ul>
</li>
<li>
<span class="code">LowerCase</span><ul style="list-style:none"><li>
<p>Convert label to lower case.</p>
</li></ul>
</li>
<li>
<span class="code">UpperCase</span><ul style="list-style:none"><li>
<p>Convert label to upper case.</p>
</li></ul>
</li>
<li>
<span class="code">ShowExtension</span><ul style="list-style:none"><li>
<p>Include file extension.</p>
</li></ul>
</li>
</ul>
<h2>Multi-line Text</h2>
<p>Item labels can have multiple lines and custom line breaks can be
used. The maximum allowed number of text lines is specified by
<span class="code">ThumbnailTextLines</span> property.</p>
<p>For more information about formatting text, see <strong><em><a href="chapter-layout.html#text-layout">Text Layout</a></em></strong>.</p>
<h2>Customized Item/Sub-tem Text</h2>
<p>Items and sub-items display the same string as specified in their
<span class="code">Text</span> property. You can format this text for display without
changing the source string in the <span class="code">Text</span> property.</p>
<p>For example, one may have data bound items with numbers. The item
<span class="code">Text</span> property contains value <strong><em>"35"</em></strong>, but
he wants to display <strong><em>"35 pcs"</em></strong> without altering the
<span class="code">Text</span> property, which would cause modifying the data
source.</p>
<p>The following screenshots show list with and without custom text
formatting:</p>
<p class="images"><img src="text-formatting-format1.png"></p>
<p class="images"><img src="text-formatting-format2.png"></p>
<p>To enable formatting, set the
<span class="code">BetterListViewItem.FormatText</span>
(<span class="code">BetterListViewItem.FormatText</span>) property on the respective
item or sub-item. Then add handler for <span class="code">FormatText</span> event and
use the properties of BetterListViewFormatItemEventArgs:</p>
<ul style="list-style:none">
<li>
<span class="code">Item</span><ul style="list-style:none"><li>
<p>Item which is being formatted.</p>
</li></ul>
</li>
<li>
<span class="code">SubItemIndex</span><ul style="list-style:none"><li>
<p>Index of sub-item which is being formatted. If you have
multiple sub-items in your list, the <span class="code">FormatText</span> event
will be raised several times for each sub-item.</p>
</li></ul>
</li>
<li>
<span class="code">CurrentText</span><ul style="list-style:none"><li>
<p>Original text to be formatted.</p>
</li></ul>
</li>
<li>
<span class="code">NewText</span><ul style="list-style:none"><li>
<p>Formatted text. The property initially contains same value as
<span class="code">CurrentText</span> and can be changed in the
<span class="code">FormatText</span> event handler.</p>
</li></ul>
</li>
</ul>
<p>The formatted text can be retrieved in run-item using the
<span class="code">BetterListViewItem.DisplayText</span>
(<span class="code">BetterListViewSubItem.DisplayText</span>). This property has no
setter because the display text can only be changed via the formatting
event (<span class="code">FormatText</span>).</p>
<p>If you want to re-format the text, call
<span class="code">BetterListViewItem.RefreshDisplayText</span> method. Of course, if
you want to refresh multiple items, it is more convenient to wrap
<span class="code">BetterListViewItem.RefreshDisplayText()</span> calls between
<span class="code">BeginUpdate()</span> and <span class="code">EndUpdate()</span>calls (see <strong><em><a href="chapter-performance.html#beginupdate-endupdate">Performance -
Using BeginUpdate and EndUpdate</a></em></strong>).</p>
<h2>Text Alignment</h2>
<p>Text in column header, item, sub-item and group elements can be
aligned horizontally and vertically. The following images shows different
horizontal alignment of sub-items...</p>
<p class="images"><img src="text-formatting-align1.png"></p>
<p>...and groups:</p>
<p class="images"><img src="text-formatting-align2.png"></p>
<p>Following properties govern horizontal text alignment on different
element types:</p>
<ul>
<li>
<p><span class="code">BetterListViewColumnHeader.AlignHorizontal</span></p>
</li>
<li>
<p><span class="code">BetterListViewGroup.HeaderAlignmentHorizontal</span></p>
</li>
<li>
<p><span class="code">BetterListViewItem.AlignHorizontal</span></p>
</li>
<li>
<p><span class="code">BetterListViewSubItem.AlignHorizontal</span></p>
</li>
</ul>
<p>All of these are of type <span class="code">TextAlignment</span> with values
<span class="code">Left</span>, <span class="code">Center</span>, <span class="code">Right</span> and
<span class="code">Default</span>.</p>
<p>Following properties govern vertical text alignment on different
element types:</p>
<ul>
<li>
<p><span class="code">BetterListViewColumnHeader.AlignVertical</span></p>
</li>
<li>
<p><span class="code">BetterListViewGroup.HeaderAlignmentVertical</span></p>
</li>
<li>
<p><span class="code">BetterListViewItem.AlignVertical</span></p>
</li>
<li>
<p><span class="code">BetterListViewSubItem.AlignVertical</span></p>
</li>
</ul>
<p>All of these are of type <span class="code">TextAlignmentVertical</span> with
values <span class="code">Top</span>, <span class="code">Middle</span>, <span class="code">Bottom</span> and
<span class="code">Default</span>.</p>
<p>The <span class="code">Default</span> value means that the alignment is
determined from the current view default (this default alignment can also
be modified, see <strong><em><a href="chapter-layout.html#default-alignment-trimming">Default Text
Alignment and Trimming</a></em></strong>).</p>
<p>Following image shows different text alignments in the selected
items and group:</p>
<p class="images"><img src="text-formatting-vertical-align.png"></p>
<h2>Text Trimming</h2>
<p>Text trimming is a method of shortening text when it is otherwise
too long to be displayed in text area. There are several trimming
options:</p>
<ul style="list-style:none">
<li>
<span class="code">None</span><ul style="list-style:none"><li>
<p>No triming is applied and the text is just clipped,</p>
</li></ul>
</li>
<li>
<span class="code">Character</span><ul style="list-style:none"><li>
<p>Text is trimmed to the last visible character.</p>
</li></ul>
</li>
<li>
<span class="code">Word</span><ul style="list-style:none"><li>
<p>Text is trimmed to the last visible word.</p>
</li></ul>
</li>
<li>
<span class="code">EllipsisCharacter</span><ul style="list-style:none"><li>
<p>Same as Character, but ellipsis (…) is added at the end of the
text.</p>
</li></ul>
</li>
<li>
<span class="code">EllipsisWord</span><ul style="list-style:none"><li>
<p>Same as Word, but ellipsis (…) is added at the end of the
text.</p>
</li></ul>
</li>
<li>
<span class="code">EllipsisPath</span><ul style="list-style:none"><li>
<p>Trimming for paths, the beginning and end of the path is
retained and the ellipsis (…) is added in the middle of the
text.</p>
</li></ul>
</li>
</ul>
<p>Here is an example of different trimming methods in action:</p>
<p class="images"><img src="text-formatting-trim.png"></p>
<p>Text trimming works also with multi-line text (see <strong><em><a href="chapter-layout.html#text-layout">Text Layout</a></em></strong>), here is
an example of breaking text into a maximum of four lines and then trimming
with ellipsis:</p>
<p class="images"><img src="text-formatting-cheader1.png"><img src="text-formatting-cheader2.png"><img src="text-formatting-cheader3.png"></p>
<p>Following properties on different elements govern text
trimming:</p>
<ul>
<li>
<p><span class="code">BetterListViewColumnHeader.TextTrimming</span></p>
</li>
<li>
<p><span class="code">BetterListViewGroup.TextTrimming</span></p>
</li>
<li>
<p><span class="code">BetterListViewItem.TextTrimming</span></p>
</li>
<li>
<p><span class="code">BetterListViewSubItem.TextTrimming</span></p>
</li>
</ul>
<h2>
<a name="text-wrapping" id="text-wrapping"></a>Text Wrapping</h2>
<p>Text wrapping defines how item (sub-item) text is broken in several
lines with respect to other sub-items. This property can be set only on
items (<span class="code">BetterListViewItem.TextTrimming</span>) and sub-items
(<span class="code">BetterListViewSubitem.TextTrimming</span>) and the property has one
of three values:</p>
<ul style="list-style:none">
<li>Layout<ul style="list-style:none"><li>
<p>Default value. Item (sub-item) text can be split to number of
lines defined by <span class="code">MaximumTextLines</span> property of the
corresponding layout (see <strong><em><a href="chapter-layout.html#text-layout">Text
Layout</a></em></strong>).</p>
</li></ul>
</li>
<li>Space<ul style="list-style:none"><li>
<p>Item (sub-item) text can be split to several lines, but only
up to available space.</p>
</li></ul>
</li>
<li>None<ul style="list-style:none"><li>
<p>Item (sub-item) text cannot be split (single line
only).</p>
</li></ul>
</li>
</ul>
<p>The effect of different text wrapping modes can be seen on the
following screenshot:</p>
<p class="images"><img src="text-formatting-wrap.png"></p>
<p>The sub-item in the first column has <span class="code">TextWrapping</span> set
to <span class="code">Layout</span>, hence the text is split in up to four lines
(<span class="code">MaximumTextLines</span> is <span class="code">4</span> in the sample).</p>
<p>The sub-item in the second column has <span class="code">TextWrapping</span> set
to <span class="code">None</span>, hence the text not wrapped.</p>
<p>The sub-item in the third column has <span class="code">TextWrapping</span> set
to <span class="code">Space</span>, so even though the text can be split to four lines,
it can be split to only available space, which allows for only three
lines. The available space here is governed by the first sub-item.</p>
<h2>Hotkey Prefix</h2>
<p>The hotkey prefix is an underlined character in item/sub-item label.
It is indicated by ampersand (<strong><em>&amp;</em></strong>) character before
the character to be displayed with underline. The following picture show
item with hotkey prefix display turned off and on:</p>
<p class="images"><img src="text-formatting-hotkey.png"></p>
<p>The hotkey prefix can be used for easier navigation in items (e.g.
menu items) with just key presses. The actual implementation of such
behavior is up to user, but Better ListView allows displaying hotkey
prefixes on items and sub-items by setting
<span class="code">BetterListViewItem.HotkeyPrefix</span>
(<span class="code">BetterListViewSubItem.HotkeyPrefix</span>, respectively) to
<span class="code">true</span>.</p>
<h2>Font and Color</h2>
<p>Column header, group, item and sub-item can have its own font and
color:</p>
<p class="images"><img src="text-formatting-fontcolor.png"></p>
<p>Font and colors are controlled with properties <span class="code">Font</span>,
<span class="code">ForeColor</span> and <span class="code">BackColor</span>.</p>
<p>By default, elements does not have a specific font and foreground
color set and there are fallback schemes to obtain these values. The
arrows in the schemes mean <strong><em>if not set, use the following
value</em></strong>.</p>
<p>Column headers:</p>
<ul>
<li>
<p><span class="code">BetterListViewColumnHeader.Font</span>
<span class="code">BetterListView.FontColumns</span>
<span class="code">BetterListView.Font</span></p>
</li>
<li>
<p><span class="code">BetterListViewColumnHeader.ForeColor</span>
<span class="code">BetterListView.ForeColorColumns</span>
<span class="code">BetterListView.ForeColor</span></p>
</li>
</ul>
<p>Groups:</p>
<ul>
<li>
<p><span class="code">BetterListViewGroup.Font</span>
<span class="code">BetterListViewGroup.FontGroups</span>
<span class="code">BetterListViewGroup.DefaultFont</span></p>
</li>
<li>
<p><span class="code">BetterListViewGroup.ForeColor</span>
<span class="code">BetterListViewGroup.ForeColorGroups</span>
<span class="code">BetterListViewGroup.ForeColor</span></p>
</li>
</ul>
<p>Items:</p>
<ul>
<li>
<p><span class="code">BetterListViewItem.Font</span>
<span class="code">BetterListView.FontItems</span>
<span class="code">BetterListView.Font</span></p>
</li>
<li>
<p><span class="code">BetterListViewItem.ForeColor</span>
<span class="code">BetterListView.ForeColorItems</span>
<span class="code">BetterListView.ForeColor</span></p>
</li>
<li>
<p><span class="code">BetterListViewSubItem.Font</span>
<span class="code">BetterListView.FontItems</span>
<span class="code">BetterListView.Font</span></p>
</li>
<li>
<p><span class="code">BetterListViewSubItem.ForeColor</span>
<span class="code">BetterListView.ForeColorItems</span>
<span class="code">BetterListView.ForeColor</span></p>
</li>
</ul>
<br><hr>
<p class="note">Sub-items take into acount
<span class="code">BetterListViewItem.UseItemStyleForSubItems</span>.</p>
<hr>
<br><p>To better understand these schemes, look at the following sample
code:</p>
<p><strong>C#</strong></p>
<pre class="prettyprint"><code class="lang-cs">// all elements will be red
listView.ForeColor = Color.Red;
// ...except for column headers which will be blue
listView.ForeColorColumns = Color.Blue;
// ...except for second column header, which will be green
listView.Columns[1].ForeColor = Color.Green;</code></pre>
<p><strong>Visual Basic</strong></p>
<pre class="prettyprint"><code class="lang-vb">' all elements will be red
listView.ForeColor = Color.Red
' ...except for column headers which will be blue
listView.ForeColorColumns = Color.Blue
' ...except for second column header, which will be green
listView.Columns(1).ForeColor = Color.Green</code></pre>
<p>The result looks like this:</p>
<p class="images"><img src="text-formatting-fallback.png"></p>
<h2>Bold Items</h2>
<p>Items and sub-items can be displayed with strong appearance using
<span class="code">BetterListViewItem.IsBold</span> property
(<span class="code">BetterListViewSubItem.IsBold</span>, respectively):</p>
<p class="images"><img src="text-formatting-isbold.png"></p>
<br><hr>
<p class="note">Sub-items take into acount
<span class="code">BetterListViewItem.UseItemStyleForSubItems</span>.</p>
<hr>
<br><h2>Sample Source Code</h2>
<p><strong>C#</strong></p>
<pre class="prettyprint"><code class="lang-cs">//
// create item with untrimmed text
//
BetterListViewItem itemNoTrim = new BetterListViewItem();
itemNoTrim.Text = "Label of this item does not use any trimming, so it is simply clipped.";
// set no trimming for this item (text will be just clipped)
itemNoTrim.TextTrimming = TextTrimming.None;
//
// create item with word-trimmed text
//
BetterListViewItem itemTrimWord = new BetterListViewItem();
itemTrimWord.Text = "Label of this item is trimmed to the nearest word. Resize the window to see how this works.";
// set trimming to whole words in this item
itemTrimWord.TextTrimming = TextTrimming.EllipsisWord;
this.listView.BeginUpdate();
this.listView.Items.AddRange(
new[]
{
itemNoTrim,
itemTrimWord
});
// resize items in Details view with content to show how the text gets trimmed
// other way would be to add column and see text breaking when resizing the column
this.listView.AutoSizeItemsInDetailsView = true;
this.listView.EndUpdate();</code></pre>
<p><strong>Visual Basic</strong></p>
<pre class="prettyprint"><code class="lang-vb">'
' create item with untrimmed text
'
Dim itemNoTrim As New BetterListViewItem()
itemNoTrim.Text = "Label of this item does not use any trimming, so it is simply clipped."
' set no trimming for this item (text will be just clipped)
itemNoTrim.TextTrimming = TextTrimming.None
'
' create item with word-trimmed text
'
Dim itemTrimWord As New BetterListViewItem()
itemTrimWord.Text =
"Label of this item is trimmed to the nearest word. Resize the window to see how this works."
' set trimming to whole words in this item
itemTrimWord.TextTrimming = TextTrimming.EllipsisWord
ListView.BeginUpdate()
ListView.Items.AddRange (New BetterListViewItem() {itemNoTrim, itemTrimWord})
' resize items in Details view with content to show how the text gets trimmed
' other way would be to add column and see text breaking when resizing the column
ListView.AutoSizeItemsInDetailsView = True
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-loading.html"><strong>
« Loading Thumbnails</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-background-image.html"><strong>Background Image »
</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>