508 lines
19 KiB
HTML
508 lines
19 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>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-sub-items.html"><strong>
|
||
« Sub-items</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-tooltips.html"><strong>Tooltips »
|
||
</strong></a></td>
|
||
</tr></table>
|
||
<br><h1>Text Formatting</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>Text formatting consists of text alignment, trimming, font and color.
|
||
It can be adjusted on column headers, groups, items and sub-items.</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>&</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="../../../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-sub-items.html"><strong>
|
||
« Sub-items</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-tooltips.html"><strong>Tooltips »
|
||
</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>
|