Coming into this investigation, we knew we would have some hard challenges to overcome like ClickOnce performance. As we looked harder at these problems, we realized that the complexity that they were introducing would add a notable burden onto customers (E.g NGEN app local packages). In the light of these findings, we decided that the better solution was to work to improve system-wide WPF instead. At the same time, we want to bring some of the benefits of the app local approach, like quick turnaround of fixes and the ability for customers to privately test these changes into the system-wide version of the framework as well.

First, we want to assure you that we are still committed to continuously servicing the platform, providing important fixes and improvements, and evolving the tooling based on customer feedback. We are exploring ways for partners and the community to provide us with more direct feedback, and participate more easily in testing and validation of fixes and features as they are prepared. This would allow customers to review these changes in a non-production environment for feedback purposes. The following are the improvements that have been delivered as a part of .NET 4.6.1 release.

Performance Improvements

Touch stack performance has been improved with coalescing support added to touch events such that current position is reported after a UI thread delay similar to mouse pointer movements.  Additionally, RichTextBox typing no longer hogs up the Render thread during fast input and you will be able to notice a much smoother experience in this scenario.

DX Integration [Open Source]

One of the highest voted ideas on our UserVoice was to add to WPF the ability to work with DX11 Content in D3DImage easily. We have been able to deliver on that through our WPF DirectX Extensions project hosted here in GitHub. Granted, this still requires a native dll for you author your DirectX visualizations but it enables you to easily integrate it with our custom D3DImage class in the project.

Currently, we have support for Dx10 and Dx11 and in future will extend it to DX11 on 12 and DX 12. If you are curious about what optimizations DX12 gives you, take a look at the article here. The nuget package release is a preview release at this time and we would love to get more feedback from the community on the quality and features before we release a stable version.

WPF Samples [Open Source]

There are a large number of samples available for WPF in MSDN. Unfortunately, there are not easily browsable, targets .NET 3.5 and requires you to individually download each sample to take a look at the content. We have vastly simplified this process by hosting all the samples on GitHub. This is a work in progress and we have moved over 200+ samples (retargeted to 4.5.2) to the repo already. If you see a sample missing from the list, do let us know by raising an issue here.

Spell Checking Improvements

The spell checker in WPF has been updated on Windows 8.1 and above to leverage OS support for spell checking additional languages.  There is no change in functionality on Vista SP2, Windows 7 and Windows 8. The following languages are available to be spell-checked, which includes the languages available for spelling checking in previous versions of .NET Framework (English, German, French, and Spanish).

The above list is subject to changes, and is included here for informational purposes only – this list should not be treated as a guarantee for support of spell-checking on these languages. The list of spell-checkers supported by the underlying OS platform can vary over time – additional languages could be added, and existing languages might go out of support – and WPF’s capabilities would correspondingly change as well.

As in the previous versions of .NET, the language for a TextBox control or a RichTextBox block is detected by looking at the following information in the order listed below:

1. xml:lang is used, if specified.
2. Current input language
3. Current thread culture

Additional support for per-user custom dictionaries

With the 4.6.1 RC we have added support for WPF to recognize custom dictionaries registered globally. This capability is available in addition to the ability to register them per-control. Also, custom dictionaries in the previous versions of WPF had no affordance for Excluded Words and AutoCorrect lists. On Windows 8.1 and Windows 10, these scenarios are now enabled through the use of files that can be placed under %AppData%\Microsoft\Spelling\<language tag>.

• The files should have extensions: .dic (Added words), .exc (Excluded words) or .acl (AutoCorrect).
• The files should be UTF-16 LE plaintext that starts with the appropriate Byte Order Mark (BOM).
• Each line should consist of a word (in the Added and Excluded word lists), or an autocorrect pair with the words separated by a vertical bar (“|”) (in the AutoCorrect word list).
• These files are considered read-only and are not modified by the system.
• Note: These new file-formats are not directly supported by the WPF spell checking API’s, and the custom dictionaries supplied to WPF in applications should continue to use .lex files.

Also, see KB3088234 for important additional details.

Per-Monitor DPI Support

Today, WPF applications are system-DPI aware – this means that the applications are scaled by the OS to appropriately depending on the DPI of the monitor on which the application is being rendered. This can result in loss of sharpness, blurry text etc. Application developers have to write additional native code to enable per-monitor DPI awareness in WPF applications.

Given the recent proliferation of high-DPI and hybrid-DPI environments in the ecosystem,  we’re working on a way to enable, out of the box, per-monitor DPI awareness in WPF applications. If you are interested in trying out a preview version of this support, please complete the following survey (available until November 6^th). We will be reaching out in the next couple of weeks to those who have signed up and provide invites for downloading the installers from Connect.

Additionally, we are continuing to execute on our previously communicated investment areas and are actively listening to customer feedback. Please send us your feedback through replies to this post, email, Connect bugs and User Voice requests.

Author: Harikrishna Menon, Senior Program manager, Visual Studio Client Tools Team Hari is a Program Manager with Microsoft, and works on the Xaml Experiences Team in Visual Studio. He has been with Microsoft for over 6 years, and has shipped multiple versions of Visual Studio working on a variety of XAML tooling experiences spanning different XAML platforms like WPF, Windows Phone and Windows Store.

If you do a quick search with WPF as the search query of GitHub, you get over 6K results. That shows the incredible community support WPF has been blessed with over the years. We wanted to take this opportunity to call out some of popular and upcoming open source projects from the community, to give them the due recognition they deserve. This by no means an exhaustive list, but features projects and authors that our team has been in touch with over time and they have consistently given us a lot of great feedback over the years. If you feel a particular project has been overlooked, do let us know in the comments and we will look into featuring it in a future update to the blog.

Material Design in XAML Toolkit

Created by James Willock, this is an awesome example of the community adapting non-Windows design concepts to fun useful themes for the platform. It already has 8k downloads, and did I mention? It works amazingly well with Dragablz and Mahapps (check the sample app in the repo). Excited, want to try it out? Check out the Get Started guide here.

[WPF Team]: What inspired you to build this?

[James]: As an enterprise developer with a love of UI I feel that desktop apps often fall behind mobile and web in the looks department, but XAML has all the tools you need to build great UIs so I gave Material Design a shot.  As soon as the first few templates were in place I knew the results were pretty good, and the early response from the community was encouraging so I pushed on to make a comprehensive library. 

Mahapps.metro

With over 300K downloads, this is super popular toolkit for creating metro-style WPF applications. Lots of goodness out-of-the box. Created by Paul Jenkins; Jake Ginnivan; Brendan Forster (shiftkey); Alex Mitchell (Amrykid); Dennis Daume (flagbug); Jan Karger (punker76) this enables WPF developers to add a metro flair to their app with very little effort. For more information, see here. If you are interested in contributing to the project, head to the GitHub repo. Some apps that are using this:-Espera, Simple Music Player , myEcho, Papercut, Carnac, Markdown Edit, ChocolateyGUI. 

[WPF Team]: What inspired you to contribute to this?

[Jan]: MahApps.Metro is a project that Paul Jenkins started back in 2011 as a simple way to bring a Metro-style user interface into your WPF application. I started in 2012 with my first PR to fix an issue for MahApps. After some more PRs I was added to the core team. MahApps is not only for metro-styled apps it's also possible to use it with 3rd party styling libs such Material Design in XAML & WPF, for C# & VB.Net. 

Universal WPF

Simply put, it is a set of WPF Controls ported from Windows Universal control concepts (RelativePanel, SplitView etc..). Created by Morten Nielsen this is a work in progress and he is looking for community support to build this out and make it awesome. This super exciting work and we hope the community is contributing and make it a great addition to the WPF ecosystem. Give it a try at the repo here.

[WPF Team]: What inspired you build this?

[Morten]: I love building controls - it's probably my favorite part of developing. I also love the new RelativePanel control in Universal app - it allows you to create some nicely aligned set of controls and at the same time significantly reducing the size of your UI tree to achieve that layout. But it was missing from WPF which could get a lot of benefit from reducing the number of UI elements required in many some advanced layouts. At the same time, Custom Panel controls are quite challenging and a great way to really understand the layout system of XAML - the Measure and Arrange steps in particular, and the complexity of the RelativePanel simply sounded like a fun challenge. After publishing it requires for more controls came, so I'm currently working on the SplitView. Also the new Adaptive Triggers really makes SplitView and Relative Panel 'tick', so this is also something I'm working on adding as a future enhancement. So the bottom line as to why: Just some plain ol' fun :-)

Some highlights of this new release include:

User interface tailored for XAML design: Blend’s new user interface makes it easier to design your XAML apps by giving more space to the panes you use the most, including the properties and objects and timeline panes. In doing so, Blend provides you with a more pleasant and productive XAML design experience.

Roslyn powered XAML IntelliSense: We created a new XAML language service to provide you with faster and better XAML IntelliSense. The new XAML language service is provided in both VS and Blend.

UI tools for XAML debugging: Blend now includes tools for inspecting XAML at runtime. These tools enable you to inspect the visual tree of your running app and the properties of any element in the tree to make it easier to debug your XAML. To learn more about this feature, please read Dante’s Introducing the UI debugging tools for XAML post.

Design in Blend / Edit in VS: To continue supporting the simultaneous XAML design and code editing experience between Blend and VS, they now include the “Design in Blend” and “Edit in Visual Studio” commands available through context menus in the solution explorer pane.

Accessibility: As part of Microsoft’s ongoing effort towards creating accessible software, the Blend designer panes are now fully keyboard and screen reader accessible. Whether you use accessible technologies or are a power user who likes to use the keyboard to accomplish tasks faster, please try these new features and tell us what you think. Furthermore, we are actively working towards also making Blend high-contrast accessible.

Try the new Blend for Visual Studio 2015 today by installing Visual Studio 2015 RC. A number of improvements are motivated by your feedback. Thank you for sharing these suggestions with us! We are looking forward to hearing from you on how we can continue to improve Blend for Visual Studio. As always, please post your suggestions on UserVoice, and report any bugs you find on our Connect site.

Kino Aguilar, Program Manager, Visual Studio Client Tools Team Kino is a Program Manager in the XAML Experiences Team. He joined Microsoft in 2013, and since then has helped ship tools for creating XAML apps. He is the PM owner of Blend for Visual Studio 2015.

Since the very earliest days of WPF/XAML development, there has always been a need to inspect the visual tree. Early Pre-Alpha builds of Blend had a debug command which would dump the entire visual tree to a text file so developers could look through it for anomalies. We had internal tools for inspecting visual trees and the properties of those elements and debugging capabilities of this type have been a frequent ask for years.  For Visual Studio 2015, we wanted to take a look at the needs that developers, both internal and external, faced and look at the tools we’ve made to create the optimal runtime inspection tools that we could. Information on how to use the UI debugging tools can be found here, but if you’re interested in how we made it happen, please read on.

After examining our internal solutions and the common issues we’ve heard and put together the following list of items we wanted to do:

• The ability to inspect an existing installed app or an ‘in-development’ app at debug time.

• A representation of the visual tree that is always up to date.

• The ability to select elements by selecting them in the running app.

• The ability to locate and select any element in the representation of the visual tree.

• A command to locate a given element in the source XAML.

• A complete list of all properties on any selected element, displayed based on where the property is set (locally, in a Style, etc…).

• The ability to change any property setter at any scope.

• A command to jump to wherever a property setter is defined if it comes from XAML.

• A persistence option to push runtime debugging changes into the XAML.

We created these requirements based on the needs of XAML developers, regardless of their platform or target device of choice. Naturally, the experience would tweak slightly based on these factors. The way a user selects an element for investigation on the desktop is going to be different from selection on a Windows Phone.

What do we need and what is missing?

The first system we need is one that allows us to talk to different apps on different platforms. We started by creating the XamlDiagnosticTap.dll, which is a generic solution that the debugger extension in Visual Studio knows how to communicate with. This assembly is loaded by one of a set of platform specific assemblies. For instance, in a WPF application, WPFXamlDiagnosticTap.dll is injected into the running app and it will pull in the generic XamlDiagnosticTap.dll. It’s obvious that we’ll see other flavors of the platform level tap, like DesktopXamlDiagnosticTap.dll or WPXamlDiagnosticTap.dll.

When we compared our requirement list to the capabilities of WPF, we found that we really only had two shortcomings. WPF didn’t provide a system for listening to changes in the visual tree, and it only stored source information privately in BAML files.

The VisualTreeChanged event

It turns out that all Visual Tree manipulations channel through four or five specific methods. These methods had all the information that we wanted, including the handles to the elements being added or removed. Adding the events here was surprisingly simple. The final implementation fires the events whenever any element is added or removed from any other element.

The API ends up looking like this:

It should be noted that this API is designed as a debugger API. Specifically, when you attempt to register for notifications on the VisualTreeChanged event, the request to register is ignored if the debugger is not currently attached. It’s also worth mentioning that at the time of this writing, this API is still in development, and it’s subject to change.

The GetXamlSourceInfo method

The source code information was a bit trickier. For elements originating from a BAML file, the elements already knew their source information. They knew the source XAML file that declared the elements as well as the Line/Column information to locate the declarations. Unfortunately, the information was private to the element and couldn’t be extracted by the diagnostic tap. Then, unfortunately, elements originating from a XAML file didn’t have their source information at all.

Exposing the already existing file information for BAML elements was easy, but we started some interesting discussions around the XAML elements. BAML is an optional step, and many people don’t even use it. Additionally, while folks are still working on their app, it’s uncommon for people to already be creating BAML files, so in our investigations, most people worked from XAML files until later in the development process. Now, consider what it means to add the source information. For every element, we need to add the file information along with the line/column information. While this isn’t a large amount per element, when you add it all together, it’s a sufficiently significant amount of memory that may obscure other memory issues. We eventually decided that the source information for XAML originating elements would only be available in Debug builds of the user’s apps, and we’d require a launch-time switch to enable it, even for Debug builds.

For DependencyObject elements, it’s trivial to add an additional attached DependencyProperty, and in that property, store the file, line and row information. However, non-DependencyObject elements, like Styles, don’t afford us this luxury. For these, we used the handy ConditionalWeakTable object from the System.Runtime.CompilerServices namespace. Simply put, the ConditionalWeakTable is similar to a dictionary, but with the noted exception that it doesn’t hold references to the objects inside it. This means that if we create a reference to Object A and all other references to A cease to exist, the ConditionalWeakTable deletes the reference to A. This prevents the ConditionalWeakTable from keeping objects alive once the system has released all other references to them.

In effect, an element gets created, we store its source information in the ConditionalWeakTable. If the app deletes the element and abandons all of its references to it, the ConditionalWeakTable automatically removes the source information from itself and the object is ready for Garbage Collection. More information on the ConditionalWeakTable can be found on MSDN.

The API for getting XamlSourceInfo is quite straightforward:

However, in order to use to use the method, two things need to be true first. As discussed above, the SourceInfo is only available for Debug builds of apps. Second, the environment variable ENABLE_XAML_DIAGNOSTICS_SOURCE_INFO will be checked when the app is started. If the variable is set and set to any value except 0 or false, WPF will store the source information for all elements. When launching your app from inside Visual Studio, the debugger extension will automatically set this in the process it will use to launch your app. However, if you’re trying to get source information on another machine, you can manually set the environment variable before launching the Debug build of the app, and you will be able to attach and get source information.

Additionally, like the VisualTreeChanged event, the GetXamlSourceInfo API is subject to change. MSDN will have the latest up to date information when the API is finalized.

Conclusion

The architecture for these tools had to be created in a platform agnostic way, in order to have a consistent experience across platforms. Then, we needed to create a platform dependent wrapper around our generic architecture to handle the various differences between the platforms. Finally, when we looked at the user experience we wanted to deliver, we had to choose between cutting back on the experience or extending the platform. When it came down to it, we simply weren’t satisfied with the experience we’d be delivering to our WPF developers without the platform extensions. The decision to deliver the top-notch experience that we wanted was an easy one to make.

Dante Gagne is a Program Manager with 12 years of experience with XAML. He started as one of the original testers on Expression Blend and brings his passion to XAML developers in Visual Studio. His focus is on the design experience and productivity.

Why use the new profiling tool?

Performance is a critical aspect of any enterprise WPF application. Customers expect applications to load fast, as well as interactions with them to be jitter free and fluid. The Application Timeline tool helps you improve the performance of your WPF applications by providing a semantically-rich, scenario centric view of your applications’ resource consumption. You can analyze the time spent by your application preparing UI frames, servicing network and disk requests, and much more in scenarios like Application Startup and Page Load. This post briefly highlights the features of this tool.

Profiling an application

To profile a WPF application in Visual Studio 2015 CTP 5, open the Performance and Diagnostics hub from the Debug -> Start Diagnostic Tools Without Debugging (ALT+F2) menu. Select the Application Timeline tool and click Start (You can also run the CPU Usage tool alongside the Application Timeline tool). This launches the application in the profiler. Once you exercise the scenario that you’d like to investigate, you can stop the profiling session by clicking on the Stop Collection link, which starts the analysis of the collected performance data.

Now you can investigate the performance report for optimization opportunities.

Inspecting profiling session details

The report shows a chronologically ordered list of interesting events in your application, which directly corresponds to CPU consumption during your application’s execution.

Graphs

Along with the reports, you are also equipped with graphs that detail the UI thread utilization and the Visual throughput (UI and Composition) of your application. These graphs enable you to quickly spot periods of excessive UI thread utilization or low frame rate which might correspond to poor application responsiveness. The UI Thread utilization graph details the time spent by the UI thread in Parsing, Layout, Render, I/O, Application Code and other framework services. Currently, only Disk I/O is computed in I/O. Network I/O support is slated for a future release. The Visual throughput graph details the frame rate of both the UI thread in the application and the Composition thread in the Desktop Window Manager.

After identifying a region of interest, you can further drill down and filter to the events in the selected time range by click-and-dragging the selection on the graphs. You can achieve more fine grained control over the selected time range by using the left/right arrow keys on the ruler handles.

Details View

The details view is where you will be spending most of your time analyzing the report. It shows a detailed view of CPU utilization of your application categorized by the UI Framework subsystem or system component that consumed the CPU. Below is the list of categories and events supported in Visual Studio 2015 CTP 5 for WPF applications. We will continue to enhance this list in the future based on our investigations into real life performance issues and your feedback.

XAML: Layout, Parsing, Render

System: Disk, Network

Other: Garbage Collection

Most of the events occur on the UI thread and are marked as such by the purple bar on the left of the event in the details view. Some of these events have descriptors in their names that enable you to quickly inspect the key property of the event. E.g., the Layout event always shows the number of elements that have taken part in that layout pass. Other events like Disk and Network I/O have hint text that details the total data payload of these requests. This enables you to in many cases co-relate the time consumed by the event to the size of the payload serviced in that time range.

These UI enhancements can be turned off by using the View Settings option in the command bar of the details view.

We also support a variety of filtering options for your convenience that you can access from the Filter option in the command bar. These commands enable you to slice and dice the events in the details view to isolate specific events or regions of interest.

When you find an event of interest, you can drill into it further using the following gestures:

• Selecting the event row will display additional details about it in the detail pane. E.g., selecting a Parsing event will show the full path of the XAML file that was parsed.
• Expanding the event row will display its child events. E.g., expanding a Parsing event will show all Parsing events that was generated as a result of the parent parsing event

By default, the timeline is sorted chronologically. If you want to quickly check out the most expensive events in your session, you can do so by changing the sort type to Duration from Start time.

Some of the key scenarios and optimizations that can be done based on their inspection are given below:

Layout: In large applications, often thousands of elements are shown on the screen at the same time. This might result in a low UI frame rate and correspondingly poor application responsiveness. The Layout event accurately determines the cost of laying out each element (i.e. the time spent in Arrange, Measure, Apply Template, Arrange Override and Measure Override) and builds the visual trees that took part in a Layout pass. You can use this visualization to determine which of your logical trees needs pruning, or to evaluate other deferral mechanisms to optimize your layout pass.

Parsing: This event enables you to identify the total time spent by the UI thread in parsing XAML files and creating objects. It also shows you the dependency chain of all the XAML files that was parsed as a result of the root event. This will enable you to identify unnecessary file parsing and object creation in performance sensitive scenarios and optimize them out.

Disk and Network I/O: Frequent disk access and large network payloads on the UI thread might severely impact application responsiveness. Even if some of these I/O accesses happen on a different thread, it might still impact the perceived responsiveness of the application. These events will detail the total payload and time spent servicing the I/O requests. Currently only network requests serviced through the WININET provider is represented here. Support for other providers will be added in a future release.

Application startup: One of the goals we had laid out while designing the profiler was to make it easy for our customers to quickly identify scenarios of interest in the vast trove of session data that is displayed in the tool. In order to do this, we automatically identify scenarios that we believe are of interest to you and generate semantic events for the same. Application Startup is a semantic event that is created by our tool that measures the interval between application launch by the operating system to the time taken for the application to submit the first frame to the Desktop Window Manager. This measurement in essence captures the startup time of your application. You can choose to filter the session details to this specific scenario by executing the filter to event command in the context menu.

This enables you to quickly identify the events that consume the largest blocks of time in this scenario. In the example above, you can see that Layout event consumes the largest block of time. Optimizing layout here will enable faster application startup.

Frame: If you want to view the total time spent in UI frame creation, you can toggle the Group by Frames option in the command bar. This will group the Layout events and related Render events in a UI thread frame to a semantic Frame event.

Application Code: The Application Timeline tool can be used in conjunction with the CPU Usage tool. This enables you to co-relate excessive App Code execution (observed on the UI Thread utilization graph) to user code that was executed during that time period.

Known limitations

Currently only events from the UI thread of the Main Application Window are shown in the tool. We will be adding support for other UI threads in the application in a near future release of Visual Studio.

Tell us more!

We are interested in knowing more about what you think about our tooling investments in the WPF platform and what you would like to see in the Performance and Diagnostics hub going forward. Please send us your feedback through replies to this post, Connect bugs, User Voice requests, the MSDN diagnostics forum or the Send a Smile button inside Visual Studio.

We have made some key improvements to WPF in this release:

• Transparent child windows
• Multi-image cursor files
• Re-designed Blend experience
• New set of Visual Diagnostics tools
• Timeline tool in the Performance and Diagnostics hub

We have also fixed a number of customer reported issues. The best place to ask us questions or engage with the us is in the comments of the roadmap for the WPF platform blog post.

For those of you unfamiliar with the context of the question, it comes from a Silverlight point of view. The developer would like to see how the WPF WebBrowser handles the interop communication between a WebBrowser Control and WPF acting as the main container for the app. Silverlight handles the communications between the hosted content and the Silverlight control using the WebBrowser.ScriptNotify event..

The WPF WebBrowser control does something a little different. The WPF WebBrowser control uses the ObjectForScripting property. This property requires that the object have its ComVisibleAttribute set to True and you are good to go. Here is an example…

In your Xaml:

<WebBrowser x:Name=”HtmlHost” ObjectForScripting=”HtmlInteropClass” />

In your code:

[System.Runtime.InteropServices.ComVisibleAttribute(True)]

Public Class HtmlInteropClass

{

 Public void MyMethod(string SomeValue)

 {

  ((MainWindow)Application.Current.MainWindow).SomeTextBox.Text = SomeValue;

 }

}

In your JavaScript:

<script type=”text/javaScript”>

 Function wpfAppMethod(inputValue) {

  Window.external.MyMethod(inputValue);

 }

</script>

One thing to note from the sample code above… Any ComVisibleAttribute that is set to True is available for use by window.external. This opens up many more opportunities to create better code that can fit your needs more precisely.

I’ve attached a sample project that will provide a good start. For more reading on the WPF WebBrowser Control, you can start here.

If you have any questions or comments, please let me know. Thanks!

WpfHostingWebOCHostingSL.zip

WPF exposes a swatch of colors that comprise the current Windows system theme.  These are available in the SystemColors class as Colors, Brushes, and corresponding ResourceKeys (for binding with dynamic notification of changes to these colors, e.g. if the user switches Windows themes).  This blog post contains a WPF tool to visually describe what Windows system colors are exposed through WPF and how these SystemColors members change as the Windows theme changes.  Screenshots from the tool are contained in the blog post.

• SystemColors Swatch
• Reference Tables - SystemColors tables for different Windows themes
• What are the Windows system colors?
• SystemColors in WPF
• Overriding SystemColors using ResourceKeys to skin WPF controls

1.   SystemColors Swatch

This graph is intended as a quick reference for control authors.  While creating the default Style and template for a control, pick colors from this table that give the desired look across different OS themes.  Here's a direct link you can bookmark and use as a quick reference.  (Note: Luna is deprecated and is only available on XP)

2.   Reference Tables - SystemColors tables for different Windows themes

• Aero
• Classic
• High Contrast #1
• High Contrast #2
• High Contrast Black
• High Contrast White
• Luna Blue
• Luna Olive Green
• Luna Silver
• Royale

Here's the source for the tool I used to create these tables, and it is also attached to the blog post.  Check it out!

3.   What are the Windows system colors?

Windows uses a set of colors to draw UI elements like highlight borders, text, shadows, control chrome, window frames, etc.  These colors can be retrieved and set using Windows APIs like GetSysColor.  WPF applications expose these colors through managed wrappers as we’ll see in the SystemColors class.

Each Windows theme specifies the system colors differently.  You can tweak the system colors yourself to create your own Windows theme, and WPF is able to pick up the colors the user has set in their theme so that WPF controls render to match the current theme.

To personalize your system colors on Win7, bring up the Appearance and Personalization config either through Desktop or Control Panel: 

Click on “Window Color” to customize the window glass color and other system colors:

Choose “Advanced appearance settings…”:

Here you can configure the different system colors for Windows to use.  The combo box allows you to select a UI element, and the color picker enables you to assign colors and other properties for it: 

If you play around with these settings, you’ll see native Windows applications and WPF applications transform by picking up on the color settings.  For example, if we change the black color for “3D Objects” to purple, then the foreground of certain UI elements picks this up:

In general, don’t worry about specifics here, like which settings affect which controls.  Just be aware that WPF controls bind to many of the colors and other parameters specified here.  (Note: While WPF apps dynamically assume the new system colors when the Windows theme changes, the same cannot be said for tweaking individual system colors.  If you are using a WPF app to calibrate changes to the Windows system colors, you should recycle the app between sets of changes.)

4.   SystemColors in WPF

WPF exposes Windows system colors through the SystemColors class as static Color, Brush, and ResourceKey properties.  That is, for each unique system color exposed by WPF, there is a corresponding Color, ResourceKey for the Color, SolidColorBrush, and ResourceKey for the SolidColorBrush.  If you don’t care about dynamic change notification, then in your XAML you can bind to the Brush directly:

  <Button Background="{x:Static SystemColors.DesktopBrush}" .../>

However, control authors using SystemColors will likely want to bind to the resource keys instead so that they receive dynamic change notification.  For example, if you are retemplating Button but wanted to basically match the look of a Windows button, you could bind a template element’s Background to SystemColors.ControlBrushKey using a DynamicResource reference:

  <ControlTemplate TargetType="Button">

    <Grid ...>

      <Border Background="{DynamicResource {x:Static SystemColors.ControlBrushKey}}" ...>

        <ContentPresenter />

      </Border>

    </Grid>

  </ControlTemplate>

By using the correct SystemColor (use the chart at the beginning of this blog post) in a control’s template, the control will appear more natural under the different Windows themes (and even under many custom themes).  That way, instead of having to craft different templates for the different Windows themes to pick up theme-specific color settings, you achieve a theme-specific look automatically.

5.   Overriding SystemColors using ResourceKeys to skin WPF controls

We’ve mentioned that stock WPF controls bind to certain SystemColors in their templates to achieve a look that matches up nicely with the current Windows theme.  In some cases you may want to change the way these stock controls look without having to retemplate them.  Styles can get you pretty far and allow you to set properties like Background, BorderBrush, BorderThickness, Margin, Padding, Foreground, etc.  Beyond that, you can use Triggers in Styles to set these properties differently for different control states.  However, some developers have gone the route of overriding SystemColors to achieve the desired look for these elements.

To override the system-supplied ControlDark color, for example, create a SolidColorBrush whose key is SystemColors.ControlDarkKey and place it in the target control’s ResourceDictionary (or a ResourceDictionary walked by that control during resource resolution).

Here we should state that a control requiring you to go down this road is poorly designed (including parts of the WPF stock controls).  Styles should be sufficient for basic reskinning and colorization.  We don’t advise using this practice, and we are studying this problem so that we may provide a better mechanism.

Further reading on this from Szymon Kobalczyk's blog:

http://geekswithblogs.net/kobush/archive/2007/03/25/109753.aspx

The sample code for this tool is attached.  Happy skinning!

SystemColorsSwatch.zip

Why RibbonWindow reports dimensions inconsistently for .NET 3.5

RibbonWindow derives from Window.  In .NET 3.5, there was an assumption that dimensions would be consistent for all native window instances of a given native style.  This was fine for normal WPF Windows but is invalid for windows like RibbonWindow that use WindowChrome because these windows do not have the same margins between the client and non-client RECTs:

Due to this assumption, RibbonWindow.Left/Height/Width/Height get reported incorrectly and have side effects when set programmatically:

In this screenshot, ActualWidth/ActualHeight/EffectiveLeft/EffectiveTop show the correct dimensions of the RibbonWindow.  Width/Height/Left/Top are reported incorrectly.  So where do these deltas in value come from?  Simple: they are the differences between the client RECT and the window RECT for a normal native window of a given native style (the gray shaded area in the first picture).

These exact dimensions can be determined from SystemParamaters2.WindowNonClientFrameThickness.  In the screen capture, we are running under the “Classic” theme, which reports the Thickness 5, 29, 5, 5 (left, top, right, bottom) for WindowNonClientFrameThickness.  RibbonWindow.Width is reported 10 pixels too large because it assumes it should add the system default 5 pixels for the left non-client edge and 5 pixels for the right non-client edge, when in reality RibbonWindow’s non-client frame has Thickness 0,0,0,0.  If you look at the other dimensions here and then at SystemParameters2.WindowNonClientFrameThickness for the system defaults, it makes sense why these dimension parameters are reported the way they are for RibbonWindow on .NET 3.5.

.NET 4.0 calls GetWindowRect for the real HWND instead of some system default, and thus reports and sets Height/Width/Left/Top correctly.

Getting the effective RibbonWindow dimensions 

For RibbonWindow on .NET 3.5, use ActualWidth and ActualHeight to read the width and height values of the RibbonWindow.  These values come from UIElement.RenderSize, so RibbonWindow’s abnormal lack of non-client frame does not matter.

For reading left and top values, calculate the EffectiveLeft and EffectiveTop values.  These were shipped as APIs in Ribbon RTM (July 2010), but have been removed from the Ribbon October 2010 update based on feedback.  We want folks to eventually move to .NET 4.0 and beyond to take advantage of fixes for issues like this.  For those still targeting .NET 3.5, it only takes a few lines of code to add EffectiveLeft and EffectiveTop properties to your window class.  The attached sample project contains code for this, but in essence you just need to add WindowNonClientFrameThickness.Left to RibbonWindow.Left and add WindowNonClientFrameThickness.Top to RibbonWindow.Top when reporting Left and Top dimensions, respectively.

Setting RibbonWindow dimensions programmatically 

To effectively set RibbonWindow dimensions, we need to use interop.  If you try to set dimension properties directly then you will see weird side effects.  For example, setting RibbonWindow.Width will make RibbonWindow.Height grow programmatically on .NET 3.5.  As another manifestation, setting RibbonWindow.Left will shrink RibbonWindow.Top by a few pixels.  Here again, the degree of transformation comes from SystemParameters2.WindowNonClientFrameThickness due to assumptions about the non-client frame.

It’s actually quite easy to work around this, but we need to use a few lines of interop.  SetWindowPos is the Win32 function we need to programmatically set both position and size of our RibbonWindow.  When setting width or height, first set the properties directly and then call SetWindowPos with the resultant values:

    // set height to 400

    this.Height = 400;

    IntPtr hwnd = new WindowInteropHelper(this).Handle;

    NativeMethods.SetWindowPos(hwnd, IntPtr.Zero, (int)this.EffectiveLeft, (int)this.EffectiveTop, (int)this.Width, (int)this.Height, SWP.NOZORDER | SWP.NOACTIVATE);

When setting left or top, just call SetWindowPos directly:

    // set left to 300

    IntPtr hwnd = new WindowInteropHelper(this).Handle;

    NativeMethods.SetWindowPos(hwnd, IntPtr.Zero, 300, (int)this.EffectiveTop, (int)Width, (int)Height, SWP.NOZORDER | SWP.NOACTIVATE);

Note that with these changes, RibbonWindow.Width and .Height are reported the same as .ActualWidth and .ActualHeight.  This code (and some test code to drive it) is contained in the attached sample project.

RibbonWindowDimensionWorkarounds.zip

This article describes ClearType technology and requirements and then specifies how a WPF Ribbon application enables ClearType.  We refer to RibbonWindow and Ribbon applications specifically, but similar steps to enable ClearType apply for any WPF app that uses WindowChrome.

• I.                    What is ClearType and where is it available?
• II.                  Why is it necessary to opt in to ClearType when using RibbonWindow in Aero theme?
• III.                How WPF Ribbon achieves ClearType
• IV.                Example: Enable ClearType for body text of RibbonWindow
• V.                  IRTs and ClearTypeHint
• VI.                Determining if text is rendering as ClearType
• VII.              Conditional Compilation of ClearType for .NET 4.0
• VIII.            Sample Code & Related Links

I.                    What is ClearType and where is it available?

ClearType is a subpixel anti-aliasing technique for improving text smoothness.  Wikipedia has a nice overview of the technology here.  WPF supports ClearType and extends ClearType in .NET 4 by allowing app developers to electively use ClearType on surfaces that are otherwise considered transparent and hence inappropriate for ClearType.  Read more about WPF support for ClearType here.

ClearType support in WPF has a couple requirements:

• Opaque surface
  • ClearType is incompatible with alpha blending, so text cannot render as ClearType on top of a transparent background.  In .NET 4.0, ClearTypeHint allows developers to enable ClearType where it is otherwise disabled, though this could make text worse or cause rendering issues when used over a non-opaque background.
• OS support
  • ClearType is available on all Windows OS’s where WPF runs, starting with Windows XP.  However, ClearType is only enabled by default on Vista & later.  So, Windows XP users must go through Control Panel to enable ClearType.  More information is available in this white paper on WPF text clarity.

 Here is some text rendering as ClearType (shown at 800% magnification):

Notice the red and the blue hues.  These indicate the text is rendering on subpixel boundaries.  Rendering this text on subpixel boundaries gives 3x higher horizontal resolution than rendering on pixel boundaries, although there is a chromatic cost – some color is introduced to create the smoothing effect.  This snapshot was taken at 800% magnification, and when I zoom out to normal resolution the red and blue hues are unnoticeable and you see smooth text.   

II.                  Why is it necessary to opt in to ClearType when using RibbonWindow in Aero theme?

Normal WPF 4.0 Window will support ClearType by default, so you get it for free.  However, if you are using RibbonWindow, you need to opt in using the RenderOptions.ClearTypeHint attached property (System.Windows.Media namespace, PresentationCore.dll).  This is necessary because RibbonWindow extends glass into the client area using DwmExtendFrameIntoClientArea.  (RibbonWindow claims the entire native window as client area so that it can draw the Quick Access Toolbar in what is normally non-client area.  Therefore, RibbonWindow must extend glass into the client area to attain the appearance of a normal Aero window.)

It is only necessary for RibbonWindow apps to set RenderOptions.ClearTypeHint for their Aero themes, but setting ClearTypeHint.Enabled for all themes shouldn’t hurt. 

III.                How WPF Ribbon achieves ClearType

All of the WPF Ribbon controls render as ClearType as long as they are rendering against solid backgrounds (most controls are).  Examine this screenshot:

Notice how the “Home” RibbonTab is rendering as ClearType with warm and cold hues, while the RibbonTitlePanel’s text is using grayscale anti-aliasing.  This screenshot was taken on Win7 Aero, and the RibbonTitlePanel renders directly on glass, so it doesn’t support ClearType.  The grayscale text is choppier, while ClearType offers a general improvement in text clarity.  The text sharpening provided by ClearType is a cumulative effect, so the improvement in clarity becomes more evident at the document/app level.

The “Home” tab has ClearType “because the v4.0 Template for RibbonTabHeader sets RenderOptions.ClearTypeHint=“Enabled” on its “InnerBorder” element.  Other Ribbon controls set ClearTypeHint in their templates also, and the Ribbon sample apps (e.g. RibbonWindowSample.exe) set ClearTypeHint similarly in their XAML.

IV.                Example: Enable ClearType for body text of RibbonWindow

While Ribbon is fully ClearType-enabled, an app using Ribbon must opt-in to ClearType for the Aero theme.  To achieve this, we simply make sure RenderOptions.ClearTypeHint=“Enabled” is set wherever text is hosted.  Examine the following XAML:

<ribbon:RibbonWindow ...>

    <Grid x:Name="LayoutRoot" ...>

        <ribbon:Ribbon x:Name="Ribbon" ... />

        <Border Grid.Row="1">

            <StackPanel>

                <TextBlock Text="ClearType ENABLED." RenderOptions.ClearTypeHint="Enabled"/>

                <TextBlock Text="ClearType OFF."/>

            </StackPanel>

        </Border>

    </Grid>

</ribbon:RibbonWindow>

Running this on Win7 Aero produces the following text rendering:

Notice ClearType rendering in the top TextBlock, which opts in to ClearType.  Besides the chromatic differences, from this screenshot it’s not immediately obvious what improvements ClearType brings to the table.  Bear in mind that ClearType rendering creates an accumulative effect to improve general text crispness.

Generally one should set RenderOptions.ClearTypeHint=“Enabled” at some root element, since the setting propagates down the visual tree unless another IRT (Intermediate Render Target, see next section) gets in the way.  For example:

<ribbon:RibbonWindow ...> 

    <Grid ...>

        <ribbon:Ribbon .../>

        <Border Grid.Row="1" RenderOptions.ClearTypeHint="Enabled">

            <StackPanel>

                <TextBlock>My app</TextBlock>

                <Button Width="Auto" HorizontalAlignment="Left">body has</Button>

                <Label>ClearType!</Label>

            </StackPanel>

        </Border>

    </Grid>

</ribbon:RibbonWindow>

Notice that we set ClearTypeHint=“Enabled” on the Border element below the Ribbon rather than on the parent Grid that contains everything.  This was deliberate – the Ribbon’s quick access toolbar and title draw over the transparent glass at the top of the window, and setting ClearTypeHint=“Enabled” for text over transparent backgrounds may cause rendering issues.

V.                  IRTs and ClearTypeHint

IRT stands for Intermediate Render Target.  An IRT is a common WPF graphics term used to refer to a surface that a tree of WPF visuals render to.  Every separate visual tree (e.g. contents of a Popup in WPF) renders to a separate IRT. In addition, applying a Clip/Opacity to a Visual causes a new IRT to be generated.

ClearTypeHint, when set, propagates to the subtree under that Visual that renders to the same IRT.  If a descendant node in this subtree has a Clip applied to it or causes a new IRT to be created for another reason, it no longer honors the ClearTypeHint settings.  These settings will need to be redefined on a Visual within the scope of this new IRT.  A common instance where this behavior manifests is in the case of a ScrollContentPresenter of a ScrollViewer.  A ScrollContentPresenter inherently clips the contents that are beyond the viewport.  By doing so, it causes its contents to be rendered to a separate IRT.

Now consider a RichTextBox hosted in the content pane of a RibbonWindow.  A RichTextBox’s built-in template uses a ScrollViewer that contains a ScrollContentPresenter.  Thus to turn on ClearType for text rendered within this ScrollContentPresenter, we must do two things:

1. Render an opaque Background within this ScrollContentPresenter.
2. Set ClearTypeHint=“Enabled” within the scope of this ScrollContentPresenter.

The attached sample code demonstrates such usage.  Similar techniques have been implemented in the RibbonControlsLibrary to enable ClearType for the various subcomponents within the Ribbon.  For further reference, Lester Lobo’s blog discusses IRTs and when to use ClearTypeHint in WPF.

VI.                Determining if text is rendering as ClearType

As seen in this article’s screenshots, text rendering as ClearType has red and blue hues since glyphs cut across subpixel boundaries.  It can be difficult to verify ClearType rendering at normal resolution, so we use a magnification technique to zoom in.  Windows ships with a magnifier accessibility tool we can launch from the Start Menu:

When you magnify 800%-1000%, you can readily see the ClearType effect.  The magnifier’s Full screen mode works great on Aero but isn’t available on other themes, so I often use MSPaint to magnify screenshots on non-Aero themes.

VII.              Conditional Compilation of ClearType for .NET 4.0

ClearType is only available in .NET 4.0, but some WPF apps and custom controls may want to support both .NET 3.5 and 4.0, lighting up with ClearType on .NET 4.0.  To support both platforms from a single codebase, some conditional compilation is required.

Ribbon itself requires conditional compilation.  The Microsoft Ribbon for WPF Source and Samples MSI includes a perl script that pushes XAML files for the Ribbon sample apps through the C preprocessor to create separate 3.5 and 4.0 XAML.  The 4.0 XAML has ClearTypeHint specified in several control templates, and #ifdef directives in the XAML direct the conditional compilation. 

VIII.            Sample Code & Related Links

Sample Code for this article is attached.

• Microsoft Ribbon for WPF – Download the WPF team’s Ribbon release, a managed Ribbon implementation.
  • Downloading the Ribbon MSI is necessary to run this article's samples.  You can also download the Ribbon Source & Samples MSI from here.

RibbonClearTypeSamples.zip