WPF Text Blog : WPF 4.0

WPF Text Measurement Units

text — Fri, 11 Dec 2009 23:48:00 GMT

The WPF text team has seen some people get confused about what units WPF uses when measuring text. Samer, a developer on the WPF text team, and I have created this post to try and shed some light on this subject. The first part of this post is very straight forward, whereas the end will only be useful for those of you who are extensively using WPF text APIs.

General Units

WPF supports multiple units for text measurement. The units that can be used are “px” (device independent pixels), “in" (inches), "cm" (centimeters), "pt" (points). If you do not specify the unit of measurement, WPF defaults to px.

<TextBlock FontSize="24">Hello World</TextBlock>

To force WPF to use a different unit of measurement, just append the unit abbreviation to the FontSize.

<TextBlock FontSize="24pt">Hello World</TextBlock>

Device Independent Pixels & Physical Pixels

In accordance with WPF’s resolution independence, the framework measures objects in device independent pixels. These device independent pixels can have different sizes than physical pixels.

1 device independent pixel = 1/96 inch.

1 physical pixel = 1/DPI (dependent on the system DPI)

Default system settings usually choose a DPI of 96 so these two types of pixels come out to be the same size. If this is not the case, it is easy to convert between the two types of pixels.

physical pixels = DPI/96 * device independent pixels

device independent pixels = 96/DPI * physical pixels

Notice that as the DPI increases, so does the number of physical pixels which compose one device independent pixel. Hence, objects that have their sizes specified in device independent pixels get larger as the system DPI increases.

Points

A point (pt) is also a common unit of measurement for fonts.

1pt = 1/72 inches

Converting between points and device independent pixels is also easy.

pt = 72/96 device independent pixels

device independent pixels = 96/72 pt

Remember objects which are measured in device independent pixels get larger as system DPI increases? This is true for text. Since there is a constant ratio between point sizes/device independent pixels, if the point size of text is held constant while the system DPI is increased, the size of the rendered text will grow.

Uses For Font Units

Aside from knowing how to correctly set FontSize, the above knowledge could be helpful in understanding the values that WPF text APIs, such as FormattedText or TextFormatter, use and return for the different text measurements. The metrics returned from these APIs are in device independent pixel (eg. some properties of GlyphTypeface including Baseline, CapsHeight, XHeight). When interacting with these APIs make sure that you convert to device independent pixels from whatever unit your font is measured in, or visa versa.

- Samer and Chipalo

Custom Dictionaries

text — Fri, 02 Oct 2009 23:33:00 GMT

Most current editors provide built in spell checking which validates user input. Spell checkers can be found in anything from word processors, to email clients, and even web browsers. Depending on the scenario, these spell checking utilities vary in complexity. Simple spell checkers compare the input against a default dictionary and then highlight mismatches. More complex spell checkers allow dynamic modification of the dictionary.

WPF includes a spell checker, but currently it only uses the OS provided dictionary for input validation. It lacks the functionality to allow the default dictionaries to be augmented with custom dictionaries provided by an application. This has been a major issue for apps which target specific industries with specialized lingo. Those apps are plagued by misspelling notifications.

A chat client is a classic example of an application that displays specialized words. In such an application, web slang such as lol, brb, or ttyl is frequently used. While these acronyms are not official words in English, in the context of a chat client these are not misspelled words.

This problem has been fixed in WPF 4.0. The ability to augment spelling support, via an application provided custom dictionary, has been added to the framework.

Custom Dictionaries API

The property CustomDictionaries has been added to the SpellCheck class.

· CustomDictionaries - This is a read-only dependency property which is an IList of URIs. Each URI points to a custom dictionary to be used for spell checking. If spell checking is disabled, SpellCheck.IsEnabled == false, no spell checking will occur, even if a custom dictionary is provided.

Custom Dictionary Format

Custom dictionaries are simple text files with single words on each line. Each line represents a legitimate word which should not be marked as misspelled.

The first line of this file can specify a language that the custom dictionary should correspond to (e.g. “#LID 1033” means that this custom dictionary applies to US English). If no language is set, the custom dictionary will apply to all default dictionaries.

· #LID 1033 – English

· #LID 3082 - Spanish

· #LID 1031 - German

· #LID 1036 - French

Comments are not supported inside the custom dictionary file.

<Window x:Class="CustomSpellerDictionaries.MainWindow"

xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"

xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"

xmlns:sys1="clr-namespace:System;assembly=system"

Title="Custom Dictionaries Example">

<Grid>

<TextBox Text="Finallly, my name, Chipalo, is not marked as misspelled."

TextOptions.TextFormattingMode="Display">

<SpellCheck.IsEnabled>true</SpellCheck.IsEnabled>

<SpellCheck.CustomDictionaries>

<sys1:Uri>D:\TEMP\dictionary.lex</sys1:Uri>

</SpellCheck.CustomDictionaries>

</TextBox>

</Grid>

</Window>

Contents of D:\TEMP\dictionary.lex

Chipalo

TextBlock created with the above XAML. Notice that spell checking is enabled but “Chipalo” is not marked as misspelled.

Custom Dictionaries Suggested Usage

Custom dictionaries should be used when an application wants a set of words, which are not found in the default dictionary for a language, to not be marked as misspelled. Specifying a langue for a custom dictionary will limit the use of the dictionary to only the denoted language. A custom dictionary which is not marked as language specific will be used for spell checking in all languages which spell checking is supported.

Spelling support in WPF is limited to four languages: English, Spanish, French, and German. Custom dictionaries are designed to augment the default dictionaries for these languages and not to extend spelling support to other languages. Creating a custom dictionary which contains common Russian words, marking the dictionary as a Russian dictionary, and adding it to the SpellCheck object of a TextBox or RichTextbox will not add Russian spelling support. If the first line of a custom dictionary denotes that the dictionary is used for a language which is not supported, that dictionary will be ignored.

- Chipalo

Bindable Run

text — Wed, 02 Sep 2009 01:01:00 GMT

Since the initial release of WPF, Run.Text has been a normal CLR property. This has meant that Run.Text lacks all the benefits of the WPF dependency property system, most notably the ability to be bound. In some cases, one could substitute Runs for TextBlocks, which can be bound to; however this can quickly create text flow problems (see example below). The omission of a bindable Run has given birth to many homebrew solutions (eg. here and here). Feeble workarounds and custom solutions are no longer necessary. In WPF 4.0 we have done the work to back Run.Text with a dependency property.

Bindable Run API

The property Run.Text has been converted to a dependency property. Now Run.Text enjoys all of the benefits of full dependency properties (binding, styling, templating, etc…).

<Window x:Class="TextBlogDWriteDemo.Window1"

xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"

xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"

Title="Window1">

<Window.Resources>

<TextBox x:Key="DataStore1" Text="how text does not

flow correctly"/>

<TextBox x:Key="DataStore2" Text="This is an example

of how text flows correctly when only

using bound Runs"/>

</Window.Resources>

<TextBlock Text="{Binding Source=

{StaticResource DataStore1},

Path=Text}"/>

<Run Text="when using a combination of Runs

and TextBlock"/>

</Paragraph>

<Run Text="{Binding Source={StaticResource

DataStore2}, Path=Text}"/>

</Paragraph>

</FlowDocument>

</Window>

This is a screenshot of the text produced by the above XAML. Notice the spacing issues which are fixed by binding to a Run as opposed to a TextBlock.

Bindable Run Usage

One way data binding is fully supported. A Run can be bound to a data source and the content of the Run will reflect the value of what it is bound to. The bound Run will receive and display any changes that occur in the data source.

Two way data binding is partially supported. If a bound Run is updated via calls to the WPF property system, the data source which the Run is bound to will reflect the changes to the Run. On the other hand, if a bound Run is updated via a RichTextBox or the text object model, the Run will lose its binding.

- Chipalo

Caret Brush

text — Tue, 01 Sep 2009 02:55:00 GMT

WPF provides extensive customizability to app authors, allowing them to change the default look and feel of most controls. One exception to this has been the color of the caret in WPF TextBoxes and RichTextBoxes. Since this functionality was not originally provided, the community has been forced to create complex workarounds. In WPF 4.0, control over the caret color has been exposed in an intuitive and simple to use manner.

Caret Brush API

The property CaretBrush is now available for use on TextBox, RichTextBox, and PasswordBox.

· CaretBrush - The brush assigned to this property will be used to draw the caret.

- Chipalo

Selection Brush

text — Fri, 28 Aug 2009 17:29:00 GMT

The default visual appearance of most objects in WPF can be easily tweaked, if not swapped out for a completely different visual tree. This provides developers far greater power over the visual look of an application than ever before. Facilitating the creation of highly customized apps has become a major adoption point for WPF. Despite WPF’s extensibility, the color of selection in text boxes and document viewers was originally baked into the framework. With the release of WPF 4.0, developers can now control the text selection color in their applications.

Selection Brush API

The properties SelectionBrush and SelectionOpacity are now available for use on TextBox, RichTextBox, FlowDocumentPageViewer, FlowDocumentScrollViewer, FlowDocumentReader and PasswordBox.

· SelectionBrush - The brush assigned to this property will be used to draw the selection overlay for text.

· SelectionOpacity - The opacity for the selection overlay. Note that if this value is set to 1 and the brush being used does not have some transparency specified in the alpha channel, selected text will be obscured by the selection overlay. In general, you don’t worry about setting the SelectionOpacity. It defaults to a value of .6.

TextBox created with the above XAML. Notice that the red selection gets rendered as a pink due to the default value of SelectionOpacity.

SelectionBrush FAIL. The text is obscured by the selection overlay because the SelectionBrush is not transparent and the SelectionOpacity has been set to 1.

Selection Brush Usage

We have added this feature to complement your creativity. SelectionBrush can be used whether you want to completely customize your application or just add a little flair to text selection. When using this feature, remember that SelectionOpacity effects the color of the selection drawn to the screen. If the rendered color of your selection is not the exact color of the SelectionBrush, it is probably due to the interaction of SelectionOpacity and SelectionBrush. If the selection is obscuring you text, remember to tweak SelectionOpacity or give SelectionBrush some transparency.

Below is a slightly more interesting application of SelectionBrush using a GradientBrush.

<TextBox.SelectionBrush>

</LinearGradientBrush>

</TextBox.SelectionBrush>

</TextBox>

- Chipalo

Layout Rounding

text — Thu, 27 Aug 2009 10:41:00 GMT

WPF’s layout engine frequently gives elements sub-pixel positions. Antialiasing algorithms cause these sub-pixel positioned elements to be rendered over multiple physical pixels after filtering. This can result in blurry lines and other non desirable rendering artifacts. Layout rounding has been introduced in WPF 4.0 to allow developers to force the WPF layout system to position elements on pixel boundaries, eliminating many of the negative side effects of sub-pixel positioning.

Two common situations where negative side effects display themselves are grid and image rendering. Many times grids are created using “star sizing,” resulting in all rows having proportional sizes (The same technique can be used for columns. For simplicity's sake, I will just refer to rows in this post). If the space being divided into rows is not a multiple of the smallest row, each row will have a fractional size. When this occurs, the content of each row will be antialiased at row boundaries. An example of this is below. The effect of the antialiasing creates the banding effect.

<Grid.RowDefinitions>

</Grid.RowDefinitions>

</Grid>

XAML for a grid that uses “star sizing” to measure row height. Each row will have a height of 33.33… since the total space for all rows is 100, and this space must be divided equally between three rows.

The grid rendered from the above XAML and zoomed to 200%. Since the only contents of each row are a dark blue Rectangles, one could reasonably expect a solid dark blue window. Without layout rounding, seams will be rendered at the row boundaries. These are artifacts from antialiasing.

Image clarity can also be improved by layout rounding. Bitmap images contain color information for individual pixels.

A bitmap image of a smiley face. Each red square represents one image pixel.

If an image is not placed on whole pixel boundaries, the color of one physical pixel has contributions from multiple image pixels. This results in a blurry rendered image.

The bitmap image from above is placed at (1.5, 1.5). This results in the color of each physical pixel (black) depending on the color of 4 image pixels (red).

Below are a couple examples of the effect that sub-pixel image positioning can have on the clarity of an image.

The left image is the original. The right image is rendered on sup-pixel boundaries

Layout Rounding API

The attached property UseLayoutRounding has been introduced to allow layout rounding functionality to be toggled on or off.

This property can either be True or False. The value of this property is inherited by an element’s children.

· True – This element will use layout rounding

· False (default) – This element will not use layout rounding

Code snipit of this property in action

<Grid.RowDefinitions>

</Grid.RowDefinitions>

</Grid>

The grid rendered from the above XAML and zoomed to 200%. Notice that setting UseLayoutRounding=”True” resolved the banding issue in the image above.

UseLayoutRounding Usage

Layout rounding should be used in UI scenarios where the exact location of objects can be sacrificed for overall appearance of the application. Since rounding of layout parameters occurs when using this feature, precise element placement is lost. A few of the effects layout rounding can have on exact layout are…

· width and or height of elements may grow or shrink by at most1 pixel

· placement of an object can move by at most 1 pixel

· centered elements can be vertically or horizontally off center by at most1 pixel

If your app has an unexpectedly blurry image or icon, fuzzy lines or borders that should be crisp, or grid banding try using layout rounding.

-Chipalo

New WPF 4.0 Features

text — Wed, 24 Jun 2009 20:35:00 GMT

WPF 4.0 Beta1 was released last month. While many exciting features were included in Beat1, there was no work targeting text, flow, or layout. This will all be reversed with WPF Beat2. Below is a brief overview for each of the features included in Beta2 which target text, flow, or layout. I will make subsequent posts giving more detail about each feature, including API details. For now, I just want to let everyone know that great features are coming!

Text clarity improvements

In previous versions of WPF, all text is formatted without specifically accounting for pixel boundaries. This approach provides uniform scalability and ensures that glyph outlines adhere to font specifications. Unfortunately, small text appears blurry when it is rendered across pixel boundaries, and this has affected our customers. In the past, we have only been able to say “we are working on a fix.” Now I can tell you that this is solved in WPF4.0!

As of Beta2, WPF provides developers with the ability to control how text is both formatted and rendered. Text can now be formatted to either strictly adhere to font specifications or fall on pixel boundaries. This new option allows text to be rendered more clearly at the slight expense of glyph shape and position.

The option to set the rendering mode for text (eg, aliased, grayscale, ClearType) is also conveniently exposed. In most situations ClearType is an obvious win; however ClearType can degrade the user experience on CRTs and for people whose eyes are color sensitive. In the past, WPF forced all apps to use ClearType. Now, developers can choose between two additional rendering modes.

A Bindable Run

The inability to bind Run.Text has forced many people to create home brew solutions. In WPF4.0, Run.Text has been converted to a Dependency Property. Run.Text now enjoys most of the benefits that come with this change, such as the ability to be bound, styled, and templated.

One-way binding is fully supported. Unfortunately, we did not have time to implement full support for two-way binding. This scenario is supported if a run is only modified through the property system, but not when the run is modified via a RichTextBox or the text object model.

LayoutRounding

WPF’s layout engine frequently causes subpixel rendering along element boundaries. This can lead to both rendering artifacts and blurry rendering, as antialiasing causes subpixel rendered elements to be displayed over multiple actual pixels. A classic example of this problem is small icons which get blurred because the icon images are placed on subpixel boundaries. Enabling LayoutRounding forces the WPF layout engine to place elements on whole pixel boundaries, thus removing most of the rendering artifacts caused by this problem.

Caret and Selection Brush

The default visual appearance of most objects in WPF can be easily tweaked or completely changed. This provides developers far greater power over the visual look of an application than ever before. Facilitating the creation of highly customized apps has become a major adoption point for WPF. Despite WPF’s extensibility, the color of text selection and carets in text boxes and document viewers remains baked into the framework. WPF now exposes properties to control the brushes used to paint text selection and carets.

-Chipalo