WPF Team Blog

How does WPF WebBrowser Control handle window.external.notify()?

2011-05-27T15:55:00Z

Every now and then we get some really good questions that make us think. This was one of those questions. Here was the original Tweet that was sent our way.

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!

SystemColors Reference

2010-12-01T04:21:00Z

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

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:

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:

</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!

Working Around RibbonWindow Dimensions Issues When Targeting .NET 3.5

2010-10-29T21:34:00Z

For those targeting .NET 3.5, you will notice that RibbonWindow’s Height, Width, Left, and Top properties are a little funky and can be misreported. This article explains why RibbonWindow on .NET 3.5 has these issues, how the issues manifest, and how to work around them. .NET 4.0 has no known issues with respect to RibbonWindow dimensions. Window dimensions are a fragile area and trying to fix this at the RibbonWindow level leads to side effects, so our recommendation is to target .NET 4.0 for Ribbon apps or else use the simple workarounds described in this article.

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.

Enabling ClearType for Ribbon Applications

2010-10-29T18:51:00Z

The Ribbon RTM release was built against .NET 3.5, but our October 2010 release of Ribbon includes both .NET 3.5 and .NET 4.0 Ribbon DLLs. With the v4.0 Ribbon, we have enabled ClearType on all of the Ribbon controls using RenderOptions.ClearTypeHint. WPF applications using RibbonWindow must also opt-in to enable ClearType for all content below the Ribbon.

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 ...>

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

</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 ...>

<ribbon:Ribbon .../>

<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:

Render an opaque Background within this ScrollContentPresenter.
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.

Future of the WPF Ribbon

2010-10-21T18:05:00Z

I’m sure many of you are wondering what the future of the WPF Ribbon will look like. The future is hard to predict and there are so many things that can change. But here is a short list of things we will be looking into for the future of the WPF Ribbon.

Virtualization – We are looking at the virtualization pattern for WPF Ribbon as we think it will work well for developers that have many commands they would like to make available to their users.
Improvements on Galleries – We are also investigating improving the galleries we already have in the WPF Ribbon as well as looking at including galleries in the in ribbon and not just in drop down ribbon controls.
And many other improvements suggestions from our customers, so keep the ideas coming.

As to the future of the Ribbon as a control… We are not 100% certain as nothing has been set in stone as of yet. I will say that our current thinking is that WPF Ribbon will follow the same path as the WPF DataGrid control.

The WPF DataGrid was initially released as a standalone control separate from the .NET Framework. After its initial release, the WPF DataGrid was updated a couple of times with bug fixes and improvements to its functionality. Then, with our latest release, the WPF DataGrid was made part of the .NET Framework, where it lives today.

The WPF Ribbon will probably follow the same path. Our initial release of the WPF Ribbon was back in July of this year. We are doing our first update to the WPF Ribbon this month, October. We will provide another update to the WPF Ribbon sometime next year. Then we anticipate making the WPF Ribbon part of the .NET Framework with our next major release.

Thanks!
WPF Ribbon Team

WPF Ribbon October 2010 Update Details

2010-10-21T18:04:00Z

Here is the detailed list of the items that were fixed in the October 2010 update.

Ribbon Split Button is only half-highlighted when users mouse over the button
Ribbon Title is bottom-aligned, should be centered
Ribbon Quick Access Toolbar icons are clipped and top-aligned
Ribbon Contextual Tab header text is getting truncated if too long
Ribbon Gallery Item does not stretch to fit its Parent Panel
Initial enabled state of Ribbon Split Menu Items can be incorrect if they have children
Ribbon Split Menu Item with sub-items is disabled if CanExecute=false
WPF Ribbon Dropdown does not close when CanAddToQuickAccessToolBarDirectly="False" was set at various level within the Ribbon
InvalidOperationException may occur when switching themes and the WPF Ribbon is Minimized
Ribbon Tab Header content may not appear when Ribbon starts out collapsed
RibbonTab.TabHeaderLeft & RibbonTab.TabHeaderRight are incorrect when Ribbon starts out hosted in a Collapsed control
Ribbon Tool Tip: Title and Footer Title gets clipped if the stringis too long
Vertical and horizontal alignments for the standard Ribbon controls should be centered, they were not.
After removing all items from the Quick Access Toolbar, phantom items remain visible
Right clicking on the System icon will not place the Context Menu properly
System Icon, Title and Quick Access Toolbar are not displayed correctly when Ribbon Windows is maximized
A minimized Ribbon will render on top of the window when a Popup is opened.
RibbonWindow.Icon does not pick appropriate small size icon from *.ico Icon file.
IndexOutofRange Exception would pop when removing a Tab from an Observable Collection.
WPF Ribbon can use ClearType when targeting .NET Framework 4.0 control.
WPF Ribbon Control Design-Time experience will work with Visual Studio 2010 Express versions.

If you have any questions or you just want to send us some feedback on the changes we’ve made, let us know.

Thanks!
WPF Ribbon Team

UPDATE: Microsoft Ribbon for WPF October 2010

2010-10-21T18:01:00Z

Here is the October 2010 update for the Microsoft Ribbon for WPF. This update contains the latest product changes and fixes for the WPF Ribbon. You can download the latest ribbon here.

We’ve made a few changes to the WPF Ribbon you might be interested in…

Upon the installation of this latest update to the WPF Ribbon we install 2 copies. One that version that targets .NET Framework 3.5 SP1 and another that targets .NET Framework 4. This allows us to take greater advantage of some of the new features in .NET Framework 4.
Our WPF Ribbon and its samples, which also target .NET Framework 4.0, can also take advantage of ClearType in WPF and provide a better text rendering experience for your WPF applications.
Our WPF Ribbon will now work with Visual Studio 2010 Express versions.

In addition, we have also fixed quite a few bugs reported by the community of WPF Ribbon developers. Here are the highlights:

Stylistic Fixes: We have addressed a few style type changes that our customers have pointed out to us, including but not limited to:
- Ribbon Title is bottom-aligned when it should be centered
- Ribbon Gallery Item does not stretch to fit its Parent Panel
- Ribbon Split Button is only half-highlighted when users mouse over the button
- Ribbon Contextual Tab header text is getting truncated if too long
Rendering Fixes: We have also addressed some issues with rendering of the Ribbon that customers have pointed out to us. Here are the highlights:
- After removing all items from the Quick Access Toolbar, phantom items remain visible
- A minimized Ribbon will render on top of the window when a Popup is opened
- Rendering artifacts observed when Ribbon is used in conjunction with interop components such as WindowsFormsHost
- System Icon, Title and Quick Access Toolbar are not displayed correctly when Ribbon Windows is maximized
- For a more detailed list of the fixes in this update, click here.

Now that we’ve updated the WPF Ribbon, I’m sure that some of you are wondering what is next for the WPF Ribbon. To find out more, click here.

And finally, much of what drove our work for this update was feedback directly from our users, please keep that feedback coming. It is your feedback that will determine our work on the WPF Ribbon.

Thanks,
WPF Ribbon Team

Ribbon Browser Application without the title row

2010-08-20T09:38:00Z

We have received a query about being able to hide the title panel in a Ribbon Browser Application. As always this can be achieved by finding the appropriate element within the Ribbon template and manipulating its Visibility. The attached project demonstrates this approach. Here's the resultant UI.

However please note that with this UI, neither QAT nor Contextual Tab Headers will have a proper home. Also there could be other unknown side effects because this isn't an intentionally supported scenario.

Images in Ribbon Sample

2010-08-17T05:49:00Z

We have received some feedback about the blurriness of the images in the Ribbon sample that was published alongside the Ribbon release. We would like to clarify that the sole purpose of this sample application is to showcase the API capabilities for the Ribbon Control Library. The images involved are purely incidental and were added to demonstrate the overall Ribbon layout. To futher this I would draw your attention to Web Matrix, a web development solution from Microsoft with a publicly available Beta. The UI for this app has been built using the Ribbon Control Library. Here are a few screen shots of this tool. This is more representative of real production apps that can be built using this library.

Web Matrix

Web Matrix - Application Menu

Picking the right resolution for RibbonWindow's Icon

2010-08-16T20:47:00Z

It has been reported that when using an icon file as RibbonWindow.Icon, the icon is rendered blurry due to bitmap scaling. The reason for this issue is the inherent behavior of WPF Image element to simply display the first decoded bitmap frame within an icon file instead of picking the best match in terms of resolution. This behavior isn't really manifested unless you use the RibbonWindow. This is because when using a RibbonWindow WPF Image element is rendering the Application icon whereas for a regular WPF Window it is the OS that renders the icon and picks the right resolution. Attached is a workaround app that demonstrates how to manually decode the icon file and pick an image of the right resolution to be rendered as the Application Icon.

        public override void OnApplyTemplate()
        {
            base.OnApplyTemplate();

            Image icon = GetTemplateChild("PART_Icon") as Image;
            if (icon != null)
            {
                Size smallIconSize = SystemParameters2.Current.SmallIconSize;

                BitmapDecoder decoder = BitmapDecoder.Create(new Uri(Icon.ToString()), BitmapCreateOptions.None, BitmapCacheOption.OnLoad);
                foreach (BitmapFrame frame in decoder.Frames)
                {
                    if (frame.Width == smallIconSize.Width &&
                        frame.Height == smallIconSize.Height)
                    {
                        icon.Source = frame;
                        break;
                    }
                }
            }
        }

Please notice that the Application icon shows a red tint (which is the 16x16 icon), whereas the icon in the taskbar shows the yellow tint (which is the 32x32 icon).

Visual improvements for RibbonQuickAccessToolBar

2010-08-15T06:52:00Z

Here are couple of scenarios that can be improved.

The contents of the QuickAccessToolBar show far too low within the title area of the window.
It is preferable that the left and right separators for a RibbonQuickAccessToolBar not show if this ToolBar is empty.

Find attached a workaround app for the two cases outlined above.

The first scenario is mitigated by introducing some negative margin to position the contents of the QuickAccessToolBar higher within the title bar.
The second scenario is mitigated by toggling the visiblity of the separators based upon the RibbonQuickAccessToolBar.HasItems property.

WPF ZoomableCanvas with a million items (from Kael Rowan)

2010-08-12T14:01:43Z

Kael Rowan just posted "ZoomableApplication2: A million items", a post that should be very helpful to some WPF Application developers. We've definitely seen many applcations built that have a designer like surface (zoomable, pannable) with many boxes + lines. ZoomableCanvas shows some techniques to virtualize the data items and the uielements when they are not showing. Kael's series of posts about ZoomableCanvas has been a great build up from nothing, to a ZoomableCanvas component, to using the ZoomableCanvas for a million items.

Please go try out the app running in his post's page, and learn if it would be useful for your application.

Thanks Kael!

Preview: WPF 4 Unleashed - Why WPF, and What About Silverlight

2010-08-09T15:29:00Z

Hey WPFers, WPF4 Unleashed has been, well, unleashed! Get a preview of Chapter 1 @ http://bit.ly/cwGYbY. Enjoy!

My name is Ted Hu, a Senior Program Manager for the WPF Team. I love hearing from customers - please let me know what you think!

SystemMenu does not show correctly when Ribbon application is run against .Net 4.0.

2010-08-06T07:23:05Z

It has been reported that when using a Ribbon hosted in a RibbonWindow in an application targeting .Net 4.0, the SystemMenu does not show in the correct location. See screenshot below.

Please note that this bug does not exist when targetting .Net 3.5. The workaround to this problem is in the attached sample. The essence of the workaround is to override the execution of ShowSystemMenuCommand.

How do I add Galleries to my Ribbon?

2010-08-04T11:38:00Z

RibbonGallery is a new metaphor introduced as part of the Ribbon UI. It is a control that visualizes a list of RibbonGalleryItems that are grouped into RibbonGalleryCategories. RibbonGallery is typically used to visualize a set of related choices that are best expressed visually. Using the Ribbon Controls Library the RibbonGallery can be hosted within any of the following controls.

§ RibbonSplitMenuItem

§ RibbonApplicationMenuItem

§ RibbonApplicationSplitMenuItem

Apart from being hosted in a drop-down control such as the ones listed above, the other popular use is as a standalone InRibbonGallery control. This control is not supported in the current release of Ribbon Controls Library, but will likely be supported in the future. The Styles Group in Microsoft Word has an InRibbonGallery and a Change Styles RibbonMenuButton hosting a variety of other Galleries. The attached sample demonstrates an implementation of this Group.

Notice the use of Galleries within each RibbonMenuItem and the uses of DataTemplates and/or HierarchicalDataTemplates to visualize the two levels in the hierarchy, RibbonGalleryCategory and RibbonGalleryItem. Also note the use of the MaxColumnCount property. The RibbonGallery control supports multi-column layout. The MinColumnCount and MaxColumnCount properties allow an app author to specify the column range and thus when the Popup containing the RibbonGallery is resized, the contents are laid out to match these constraints. When the Popup is opened the Gallery is laid out to its MinColumnCount dimensions. The resizablility of the parent control is specified using the CanUserResizeHorizontally and CanUserResizeVertically properties. And lastly the RibbonGalleryCategory’s HeaderVisibility is configurable. For instance the Style Set Gallery does not show Category Header whereas the Colors and Fonts Galleries do.

How can I add rich ToolTips to my Ribbon controls?

2010-08-04T11:14:00Z

There are six properties on each Ribbon control that enable creation of rich ToolTips such as the one shown below.

The use of any of these six properties causes a RibbonToolTip instance to be created and used as the ToolTip for the Ribbon control. It is always possible to override this behavior by explicitly creating a ToolTip. However note that a RibbonToolTip in addition to providing a rich template also provides the service of correctly positioning iself below the Ribbon instead of the default position next to the mouse cursor. So it is highly recommended to use a RibbonToolTip instance, even if you wanted to create a custom one.

Read next post to learn about adding RibbonGallery to your Ribbon app.

Why should I use a RibbonWindow?

2010-08-04T10:52:00Z

RibbonWindow is a subclass of the regular WPF Window that provides additional services to be able to integrate Ribbon components with the Window Chrome. To demonstrate this use the sample application from the previous post.

Right-click the Format Painter button within the Clipboard Group
Choose Add to QuickAccessToolBar option
Notice that the Button shows in the title row for the Window.

This was made possible by the use of RibbonWindow. Under the covers, RibbonWindow uses the Chrome library to achieve this. However, it isn’t mandatory to use a RibbonWindow to host the Ribbon UI. If a regular WPF Window is used instead all of the same functionality is available barring the integration with the Window Chrome. So the same Ribbon UI would appear as below.

Read next post to learn about rich RibbonToolTips.

Bind my Ribbon UI to my data model

2010-08-04T10:26:00Z

The recommended way to bind the Ribbon UI to a data model is to encapsulate the command and the state associated with each control into a data object that is used as the DataContext for that control. You can then apply an implicit Style to the control that binds individual properties on it to corresponding properties of the data object. Please look at the attached sample that emulates the Clipboard group in Microsoft Word.

The XAML markup for this group ends up being very succinct. Notice that the primary operation here is just to set the DataContext on each control.

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

<ribbon:RibbonTab Header="Home" KeyTip="H" >

<ribbon:RibbonGroup x:Name="Clipboard" DataContext="{x:Static data:WordModel.Clipboard}">

<ribbon:RibbonSplitButton DataContext="{x:Static data:WordModel.Paste}">

<ribbon:RibbonMenuItem DataContext="{x:Static data:WordModel.Paste}" />

<ribbon:RibbonMenuItem DataContext="{x:Static data:WordModel.PasteSpecial}" />

<ribbon:RibbonMenuItem DataContext="{x:Static data:WordModel.PasteAsHyperlink}" />

</ribbon:RibbonSplitButton>

<ribbon:RibbonButton DataContext="{x:Static data:WordModel.Cut}" />

<ribbon:RibbonButton DataContext="{x:Static data:WordModel.Copy}" />

<ribbon:RibbonButton DataContext="{x:Static data:WordModel.FormatPainter}" />

</ribbon:RibbonGroup>

</ribbon:RibbonTab>

</ribbon:Ribbon>

The implicit Styles for these controls are specified in a ResourceDictionary along the ancestor lookup path.

<Grid.Resources>

<Setter Property="ribbon:RibbonControlService.Label"

Value="{Binding Label}" />

<Setter Property="ribbon:RibbonControlService.LargeImageSource"

Value="{Binding LargeImage}" />

<Setter Property="ribbon:RibbonControlService.SmallImageSource"

Value="{Binding SmallImage}" />

<Setter Property="ribbon:RibbonControlService.ToolTipTitle"

Value="{Binding ToolTipTitle}" />

<Setter Property="ribbon:RibbonControlService.ToolTipDescription"

Value="{Binding ToolTipDescription}" />

<Setter Property="ribbon:RibbonControlService.ToolTipImageSource"

Value="{Binding ToolTipImage}" />

<Setter Property="ribbon:RibbonControlService.ToolTipFooterTitle"

Value="{Binding ToolTipFooterTitle}" />

<Setter Property="ribbon:RibbonControlService.ToolTipFooterDescription"

Value="{Binding ToolTipFooterDescription}" />

<Setter Property="ribbon:RibbonControlService.ToolTipFooterImageSource"

Value="{Binding ToolTipFooterImage}" />

...

</Style>

<Style TargetType="{x:Type ribbon:RibbonButton}"

BasedOn="{StaticResource RibbonControlStyle}">

</Style>

<Style TargetType="{x:Type ribbon:RibbonToggleButton}"

BasedOn="{StaticResource RibbonControlStyle}">

</Style>

...

</Grid.Resources>

</Grid>

This pattern of factoring the visuals and the data helps maintain clean lines of separation between the View and the Model. It also helps scenarios such as moving tasks back and forth between the RibbonQuickAccessToolBar and the main Ribbon, where the same data is visualized multiple different places.

Read next post for learn what using a RibbonWindow buys you.

Add more content to my Simple Ribbon Application

2010-08-04T09:45:00Z

To add more content to the Simple Ribbon Application that we created in the previous post, you can drag-drop variety of elements from the VS toolbox onto the Ribbon.

Drag RibbonGroup to the Home Tab and name it Group2.
Drag three RibbonCheckBox controls to Group2 and set the SmallImageSource property on each using the property inspector.

The resultant XAML is as follows.

<Grid.Resources>

<Setter Property="ribbon:RibbonControlService.Label"

Value="{Binding Label}" />

<Setter Property="ribbon:RibbonControlService.LargeImageSource"

Value="{Binding LargeImage}" />

<Setter Property="ribbon:RibbonControlService.SmallImageSource"

Value="{Binding SmallImage}" />

<Setter Property="ribbon:RibbonControlService.ToolTipTitle"

Value="{Binding ToolTipTitle}" />

<Setter Property="ribbon:RibbonControlService.ToolTipDescription"

Value="{Binding ToolTipDescription}" />

<Setter Property="ribbon:RibbonControlService.ToolTipImageSource"

Value="{Binding ToolTipImage}" />

<Setter Property="ribbon:RibbonControlService.ToolTipFooterTitle"

Value="{Binding ToolTipFooterTitle}" />

<Setter Property="ribbon:RibbonControlService.ToolTipFooterDescription"

Value="{Binding ToolTipFooterDescription}" />

<Setter Property="ribbon:RibbonControlService.ToolTipFooterImageSource"

Value="{Binding ToolTipFooterImage}" />

...

</Style>

<Style TargetType="{x:Type ribbon:RibbonButton}"

BasedOn="{StaticResource RibbonControlStyle}">

</Style>

<Style TargetType="{x:Type ribbon:RibbonToggleButton}"

BasedOn="{StaticResource RibbonControlStyle}">

</Style>

...

</Grid.Resources>

</Grid>

As you may have already noted, the main Ribbon control is similar to a TabControl and contains RibbonTabs, which contain RibbonGroups, which in turn contain a variety of different Ribbon controls. (This is not an exhaustive list.)

It is important to note that there are primarily three properties that constitute the content model for these controls.

These three properties enable a control to exist in a variety of different size variants. The three popular size variants are

Large

LargeImageSource and Label are visible

Medium

SmallImageSource and Label are visible

Small

Only the SmallImageSource is visible

These size variants for each control are pertinent to the resizing behavior of the Ribbon.

Read next post to learn to bind your Ribbon UI to a data model.

Building a Simple Ribbon Application in WPF

2010-08-03T17:16:00Z

The simplest way to get started is to use the WPF Ribbon Application project template.

Install VS 2010
Install Microsoft Ribbon for WPF
Launch VS 2010
Add New Project – WPF Ribbon Application

If you are not able to run VS 2010 then use the following steps.

Install Microsoft Ribbon for WPF
Launch the attached project using VS 2008
Fixup the references to RibbonControlsLibrary.dll and Microsoft.Windows.Shell.dll to point to their install location under the program files path.
Build and run the project

Read next post to learn to add more content to this simple Ribbon application.

Introducing Microsoft Ribbon for WPF

2010-08-03T13:27:00Z

They say that a picture speaks a thousand words. So here are some to whet your appetite. Read next post to get started using the WPF Ribbon. Pete Brown's blog post about the WPF Ribbon makes an interesting read as well.

WPF Ribbon Application VS 2010 Project Template

WPF Ribbon Application Blend 4 Project Template

Simple WPF Ribbon Application UI built using the Project Template

WPF Ribbon Window Item Template

WPF Ribbon elements in the VS Toolbox

Edit Ribbon element properties in VS Property Editor

Office Word like UI using WPF Ribbon

Office Word like UI in a WPF Browser Application

RibbonApplicationMenu in a WPF Ribbon

RibbonQuickAccessToolbar in a WPF Ribbon

RibbonContextualTabGroups in a WPF Ribbon

RibbonMenuButtons containing RibbonMenuItems

RibbonMenuItem containing RibbonGallery and RibbonMenuItems

RibbonSplitButton containing RibbonGallery and RibbonMenuItems

RibbonComboBox containing a RibbonGallery and previewing changes

RibbonGallery with filtering

RibbonGallery with hover zoom

RibbonGallery with resizing

RibbonTabs with scrolling

RibbonGroups with scrolling

Minimized Ribbon

Collapsed Ribbon

Rich RibbonToolTips

KeyTips

WPF Ribbon under High Contrast settings

WPF Ribbon under Right-to-Left settings

Colorized WPF Ribbon

WPF Ribbon UI Automation Tree

Read next post to get started using the WPF Ribbon.

Microsoft XAML Toolkit CTP - July 2010

2010-07-28T22:12:32Z

We have just released the Second CTP of the XAML Tool Kit.

There is still some work to do before the XAML Toolkit is at full release quality, so this is still labeled as a CTP. However, we are confident that it is stable, usable, and suitable for the majority of usage scenarios and can be used, at your discretion, in production apps (in accordance with the updated licensing terms).
There have been lots of issues fixed and improvements to the XAML Toolkit since the November 2009 CTP and we intend to further improve it from customer feedback on this release. We invite you to try it out and let us know what you think!

The XAML Toolkit bits are available here.

Overview

Features of the XAML Toolkit

XamlDom – A XAML DOM that is LINQ friendly. Enables easy static analysis.
XAML FxCop integration – You can run FxCop rules that analyze your XAML against rules.
XAML FxCop rule authoring - A BaseXamlRule implementation that allows you to write custom FxCop rules that target XAML. We’re also shipping a couple of simple ones including a ValidationRule that will validate your XAML.
SilverlightSchemaContext – A XamlSchemaContext that allows System.Xaml to parse Silverlight XAML for tools use.

What’s New in the XAML Toolkit CTP – July 2010

The UISchemaContext has been removed.
The SilverlightSchemaContext now supports Silverlight Version 3.0, 4.0 and Phone 7.
A SilverlightAssemblyHelper static class has been added to help with loading the correct Silverlight schema version.
License terms permit usage in live operating environments (with some restrictions) and distribution of the toolkit binaries. Please see the Microsoft XAML Toolkit License Terms for full details.

Microsoft XAML Toolkit CTP – July 2010: FxCop Integration

2010-07-28T22:11:14Z

This post describes the FxCop Integration feature of the XAML Toolkit CTP – July 2010, announced here and downloadable here. It borrows heavily from Mike Shim’s earlier post on XAML FxCop.

The tool kit’s integration with FxCop has been tested against FxCop version 1.36 but that version of FxCop is a .Net 3 application and must be configured to run in .Net 4 in order to use the XAML FxCop rules.

To configure FxCop 1.36 to run on .Net 4.0 you need to add the following XML to your FxCop.exe.config file:

   1: <startup>

   2:   <supportedRuntime version="v4.0.30319"/>

   3: </startup>

Alternately, the toolkit provides a replacement FxCop.exe.config.

Using FxCop

Start FxCop and add the XAML rules.

Go to the folder where you installed the XAML Toolkit (typically C:\Program Files\Microsoft XAML Toolkit\) and add Microsoft.Xaml.Tools.FxCop.dll

You should see all the XAML rules added to the Rules section.

Go back to “Project” –> “Add Targets” and add your Silverlight or WPF or Workflow assemblies that have XAML resources.

Prompts for Dependent Assemblies

Silverlight - You should no longer get a popup asking you to find System.Windows.dll when you run the rules (with “Analyze”). When loading Silverlight targets you will be still be prompted to supply the path to the correct mscorlib.dll for your version of Silverlight. The path to the Silverlight mscorlib.dll should be in the reference assemblies of the Silverlight Visual Studio project used to build the target assembly. Typically found at: C:\Program Files\Reference Assemblies\Microsoft\Framework\Silverlight.

WPF – You will get prompted for the path to PresentationFramework.dll when Analyzing WPF XAML assemblies. Again, the best answer is the path found in the project file of solution that created the assembly, typically found at: C:\Program Files\Reference Assemblies\Microsoft\Framework\.NETFramework\v4.0.

64bit – Remember, on 64 bit machines the above paths are modified to: C:\Program Files (x86)\Reference Assemblies.

Analyze

If everything goes smoothly, you can now press “Analyze” and you see the rules run. And there will be some output like:

You should be able to do similar things for adding your own custom rules to FxCop as well.

Microsoft XAML Toolkit CTP – July 2010: XAML DOM

2010-07-28T22:04:02Z

This post describes the XAML DOM feature of the XAML Toolkit CTP – July 2010, announced here and downloadable here. It borrows heavily from Mike Shim’s post announcing the first CTP.

Here’s a simple example of reading a XAML document and writing out all the types used:

   1: XamlDomObject rootObject = XamlDomServices.Load("Window1.xaml");

2:

   3: foreach (XamlDomObject domObject in rootObject.DescendantsAndSelf())

   4: {

   5:   Console.WriteLine(domObject.Type);

   6: }

By calling XamlDomServices.Load, we get a XamlDomObject for the root object in the XAML document. From there, we can call DescendantsAndSelf (similar to XML XElement) on the root object which returns an IEnumerable<XamlDomObject>.

Here’s another example. Imagine you want to set Background on every Control in your document that doesn’t already have one:

   1: XamlDomObject rootObject = XamlDomServices.Load("Window1.xaml");

   2: foreach (XamlDomObject objectNode in

   3:         from control in rootObject.DescendantsAndSelf(typeof(Control))

   4:         where !control.HasMember("Background")

   5:         select control)

   6: {

   7:   objectNode.SetMemberValue("Background", "Red");

   8: }

   9: XamlDomServices.Save(rootObject, "NewFile.xaml");

The call to DescendantsAndSelf this time is passed typeof(Control). This will limit it to return only things that are assignable to Control. We are leveraging LINQ to easily restrict the returned XamlDomObjects to only the ones without a “Background” member. We then set the background property to Red with SetMemberValue("Background", "Red"). Finally, we call XamlDomServices.Save to save the file back out to XAML. This is a pretty simple example of a transformation but we can do much more complex transformations with our XamlDom.

Microsoft XAML Toolkit CTP – July 2010: FxCop Rule Authoring

2010-07-28T22:00:54Z

The XAML toolkit, announced here and downloadable here, provides a number of FxCop rules for analyzing your XAML. This post describes how the XAML Toolkit also helps you write FxCop rules.

Writing an FxCop Rule

There are resources on the net describing how to write an FxCop rule. You can read the original MSDN article here or a newer posting on the FxCop team blog here. The difference here is that the XAML Toolkit has already sub-classed the BaseIntrospectionRule with the BaseXamlRule.

BaseXamlRule implements the Check(Resource resource) method. This method will:

Find the XAML/BAML resource
Determine the resource’s type (Silverlight, WPF, other),
Load the proper Schema Context
Load the XAML or BAML content into a XAML DOM
Calls a new abstract method CheckXaml()

   1: public abstract void CheckXaml(XamlDomObject rootObjectNode,

   2:                                XamlSchemaContext schemaContext,

   3:                                string resourceName);

To implement a XAML FxCop rule you implement the CheckXaml() method, and not the Check() method.

Restricting rules

Not all XAML rules apply to all flavors of XAML. For example you might write a rule that should only run with Silverlight XAML. For this purpose the BaseXamlRule has a virtual method IsRuleValidForXamlFlavor().

   1: internal virtual bool IsRuleValidForXamlFlavor(ResourceType xamlFlavor)

   2: {

   3:     return true;

   4: }

The values of ResourceType are:

   1: internal enum ResourceType

   2: {

   3:     SimpleXAML,

   4:     Workflow,

   5:     WPF,

   6:     Silverlight

   7: }

You don’t need to implement this method in every XAML rule. The base implementation returns “true”. But if you need to exclude your rule from some flavors of XAML you can do it here.