Chapter 19. Interoperability with Non-WPF Technologies

Despite the incredible breadth of Windows Presentation Foundation, it lacks some features that other desktop technologies have. When creating a WPF-based user interface, you might want to exploit such features. For example, WPF still doesn’t include some of the standard controls that Windows Forms has had for over a decade: NumericUpDown, NotifyIcon, and more. Windows Forms also has support for multiple-document interface (MDI) window management, wrappers over additional Win32 dialogs and APIs, and various handy APIs, such as Screen.AllScreens (which returns an array of screens with information about their bounds). Win32 has controls such as an IP Address text box (SysIPAddress32) that have no equivalent in either Windows Forms or WPF. Windows includes many Win32-based user interface pieces that don’t have first-class exposure to WPF, such as task dialogs and a wizard framework. Tons of ActiveX controls exist for the purpose of embedding rich functionality into your own software. And some technologies cover scenarios that are fundamentally different from what WPF is designed to enable, but it would still be nice to leverage such pieces in a WPF application. Some examples are high-performance immediate-mode DirectX rendering and platform-agnostic HTML-based rendering.

Perhaps you’ve already put a lot of effort into developing your own pre-WPF user interfaces or controls. If so, you might want to leverage some of your own work that’s already in place. Maybe you have developed an application in a non-WPF technology with an extremely complicated main surface (for example, a CAD program) and just want to “WPF-ize” the outer edges of the applications with rich menus, toolbars, and so on. Maybe you’ve created a web application with tons of HTML content that you want to enhance but not replace.

In earlier chapters, you’ve seen WPF’s HTML interoperability. Given that HTML can be hosted inside a WPF Frame or WebBrowser and WPF content can be hosted inside HTML (as a XAML Browser Application or a loose XAML page), you can leverage existing HTML content—and any Silverlight, Flash, and other content it contains—alongside new WPF content. Fortunately, WPF’s support for interoperability goes much deeper than that. It’s fairly easy for WPF applications and controls to leverage all kinds of non-WPF content or APIs, such as all the examples in the previous two paragraphs. Some of these scenarios are possible thanks to the features described in this chapter, some are possible thanks to the .NET Framework’s interoperability between managed and unmanaged code, and (in the case of calling miscellaneous Windows Forms APIs from WPF) some are possible simply because the other technology defines managed APIs that just happen to live in non-WPF assemblies.

Figure 19.1 summarizes different desktop user interface technologies and the paths you can take to mix and match them. Win32 is a general bucket that includes any technology that runs on the Windows desktop: MFC, WTL, OpenGL, and so on. Notice that there’s a direct path between WPF and each technology except for Silverlight and ActiveX. In these cases, you must use another technology as an intermediate layer. Silverlight does provide a mechanism for being directly hosted outside of HTML, leveraged by Visual Studio and Blend. It involves using Silverlight’s HostingRenderTargetBitmap class to get a bitmap representation of the Silverlight content then feeding that information into a WPF InteropBitmap or WriteableBitmap. This support is pretty primitive, however, so it is omitted from the figure.

All the blue lines connecting the technologies are discussed in this chapter. The line between Win32 and Windows Forms is enabled by standard .NET Framework interoperability technologies for mixing managed and unmanaged code (and the fact that Windows Forms is based on Win32), and the lines between Win32 and ActiveX/DirectX are somewhat artificial because there are no big barriers separating Win32 and ActiveX or Win32 and DirectX.

This chapter focuses on embedding controls of one type inside applications of another type. It first examines both directions of WPF/Win32 interoperability separately, then both directions of WPF/Windows Forms interoperability separately. WPF/DirectX interoperability is examined in a single section because its seamless mixing can be used to effectively get either direction of interoperability. The chapter ends by examining the options with WPF/ActiveX interoperability. Although the focus is on embedding controls, we’ll look at another important scenario at the end of most sections that isn’t as straightforward as you might imagine: launching heterogeneous dialogs.

Although WPF’s subsystems (layout, animation, and so on) don’t know how to interact directly with HWNDs, WPF defines a FrameworkElement that can host an arbitrary HWND. This FrameworkElement is System.Windows.Interop.HwndHost, and it makes HWND-based controls look and act almost exactly like WPF controls.

To demonstrate the use of HwndHost in a WPF application, let’s look at embedding a custom Win32 control to add webcam functionality to WPF. WPF’s video support doesn’t include anything for interacting with local video capture devices such as a simple webcam. Microsoft’s DirectShow technology has support for this, however, so Win32 interoperability enables you to leverage that webcam support in a WPF application.

LISTING 19.1 Webcam.h—Definition of Some Webcam Win32 APIs

Click here to view code image

The Webcam class is designed to work with a computer’s default video capture device, so it contains a set of simple static methods for controlling this device. It is initialized with a width and height (which can be later retrieved via GetWidth and GetHeight methods). Then, after telling Webcam (via AttachToWindow) what HWND to render itself on, the behavior can be controlled with simple Start, Pause, and Stop methods.

Listing 19.2 contains the implementation of the Webcam class. The complete implementations of Webcam::Initialize and Webcam::Terminate are omitted for brevity, but the entire implementation can be found with this book’s source code (http://informit.com/title/9780672336973).

LISTING 19.2 Webcam.cpp—Implementation of the Webcam APIs

Click here to view code image

The implementation begins with a simple Win32 window procedure, which makes sure to repaint the video whenever a WM_ERASEBKGND message is received. Inside Initialize, a Win32 window class called WebcamClass is defined and registered, and a bunch of DirectShow-specific COM objects are created and initialized. (The Terminate method releases all these COM objects.) AttachToWindow not only tells DirectShow which window to render on, but it sets the size of the video to match the dimensions passed to Initialize. The other methods are simple wrappers for the underlying DirectShow methods.

Listing 19.3 defines a WPF Window—all in C++/CLI—and uses the HwndHost type to integrate the Win32 Webcam control. Because it is using and defining managed data types, it must be compiled with the /clr compiler option.

LISTING 19.3 Window1.h—A WPF Window Using an HwndHost-Derived Class

Click here to view code image

The first thing to notice about Listing 19.3 is that it defines a subclass of HwndHost called MyHwndHost. This is necessary because HwndHost is actually an abstract class. It contains two methods that need to be overridden:

BuildWindowCore—In this method, you must return the HWND to be hosted. This is typically where initialization is done as well. The parent HWND is given to you as a parameter to this method. If you do not return a child HWND whose parent matches the passed-in parameter, WPF throws an InvalidOperationException.

DestroyWindowCore—This method gives you the opportunity to do any cleanup/termination when the HWND is no longer needed.

For both methods, HWNDs are represented as HandleRef types. HandleRef is a lightweight wrapper (in the System.Runtime.InteropServices namespace) that ties the lifetime of the HWND to a managed object. You’ll typically pass this as the managed object when constructing a HandleRef.

Listing 19.3 calls the Win32 CreateWindow API inside BuildWindowCore to create an instance of the WebcamClass window that was registered in Listing 19.2, passing the input HWND as the parent. The HWND returned by CreateWindow is not only returned by BuildWindowCore (inside a HandleRef), but it is also passed to the Webcam::AttachToWindow method so the video is rendered appropriately. Inside DestroyWindowCore, the Win32 DestroyWindow API is called to signify the end of the HWND’s lifespan.

Inside the Window’s constructor, the MyHwndHost is instantiated and added to a DockPanel just like any other FrameworkElement. The Webcam is then initialized, and the video stream is started.

Listing 19.4 contains the final piece needed for the WPF webcam application, which is the main method that creates the Window and runs the Application. It is also compiled with the /clr option. Figure 19.2 shows the running application.

LISTING 19.4 HostingWin32.cpp—The Application’s Entry Point

Click here to view code image

Notice the gray area underneath the video stream in Figure 19.2. The reason this appears is quite simple. The MyHwndHost element is docked to the left side of the DockPanel in Listing 19.3, but the Webcam control is initialized with a fixed size of 640x480.

If the implementation of Webcam::AttachToWindow in Listing 19.2 were changed to discover the size of the HWND, the video could stretch to fill that area. This change is shown in the following code, and Figure 19.3 shows the result:

Click here to view code image

HRESULT Webcam::AttachToWindow(HWND hwnd)
{
  if (!_initialized || !_windowlessControl)
    return E_FAIL;

  _hwnd = hwnd;

  // Position and size the video
  RECT rcDest;
  GetClientRect(hwnd, &rcDest);
  _windowlessControl->SetVideoClippingWindow(hwnd);
  return _windowlessControl->SetVideoPosition(NULL, &rcDest);
}

Although the best solution for a webcam application is probably to give the HwndHost-derived element a fixed (or at least unstretched) size, it’s important to understand that WPF layout applies only to the HwndHost. Within its bounds, you need to play by Win32 rules to get the layout you desire.

Tabbing into the hosted Win32 content

Tabbing out of the hosted Win32 content

Supporting access keys

Figure 19.4 illustrates the contents of a hypothetical WPF Window with two WPF controls surrounding a Win32 control (hosted in HwndHost) with four child Win32 controls. We’ll use this illustration when discussing each of these three features. The numbers represent the expected order of navigation. For the three WPF controls (1, 6, and the HwndHost containing 2–5), the ordering could come implicitly from the way in which they were added to their parent, or it could come from an explicit TabIndex being set for each control. For the four Win32 controls (2–5), the order is defined by application-specific logic.

When the previous WPF element has focus, pressing Tab moves focus to the first item in the Win32 control. In Figure 19.4, this means focus moves from 1 to 2.

When the next WPF element has focus, pressing Shift+Tab moves focus back to the last item in the Win32 control. In Figure 19.4, this means focus moves from 6 to 5.

Both of these actions can be supported fairly easily by overriding HwndHost’s TabInto method, which is called when HwndHost receives focus via Tab or Shift+Tab. In C++/CLI, a typical implementation would look like the following:

Click here to view code image

virtual bool TabInto(TraversalRequest^ request) override
{
  if (request->FocusNavigationDirection == FocusNavigationDirection::Next)
    SetFocus(hwndForFirstWin32Control);
  else
    SetFocus(hwndForLastWin32Control);
  return true;
}

TabInto’s parameter reveals whether the user has just pressed Tab (giving FocusNavigationDirection.Next) or Shift+Tab (giving FocusNavigationDirection.Previous). Therefore, this code uses this information to decide whether to give focus to its first child or last child. It does this using the Win32 SetFocus API. After setting focus to the correct element, it returns true to indicate that it successfully handled the request.

Supporting this direction is a little more complicated than the other direction. That’s because after focus enters Win32 content, WPF no longer has the same kind of control over what’s going on. The application still receives Windows messages that are ultimately passed along to HwndHost, but WPF’s keyboard navigation functionality can’t “see” what’s going on with focus.

Therefore, there is no TabOutOf method to override. Instead, there is a TranslateAccelerator method, which gets called whenever the application receives WM_KEYDOWN or WM_SYSKEYDOWN message from Windows (much like the Win32 API with the same name). Listing 19.5 shows a typical C++/CLI implementation of TranslateAccelerator for the purpose of supporting tabbing out of Win32 content (and tabbing within it).

LISTING 19.5 A Typical C++/CLI Implementation for TranslateAccelerator

Click here to view code image

TranslateAccelerator is passed a reference to a “raw” Windows message (represented as a managed System.Windows.Interop.MSG structure) and a ModifierKeys enumeration that reveals whether the user is pressing Shift, Alt, Control, and/or the Windows key. (This information can also be retrieved using the Win32 GetKeyState API.)

In this listing, the code takes action only if the message is WM_KEYDOWN and if Tab is being pressed (which includes Shift+Tab). After determining whether the user pressed Tab or Shift+Tab using GetKeyState, the code must determine whether it is time to tab out of the control or within the control. Tabbing out should occur if focus is already on the first child control and the user pressed Shift+Tab, or if focus is already on the last child control and the user pressed Tab. In these cases, the implementation calls OnNoMoreTabStops on HwndHost’s KeyboardInputSite property. This is the way to tell WPF that focus should return under its control. OnNoMoreTabStops needs to be passed a FocusNavigationDirection value so it knows which WPF element should get focus (1 or 6 in Figure 19.4). The implementation of TranslateAccelerator must return true if it handles the keyboard event. Otherwise, the event bubbles or tunnels to other elements. One point that Listing 19.5 glosses over is that setting the values of hwndOfPreviousControl and hwndOfNextControl appropriately involves a small amount of application-specific code to determine what the previous/next Win32 control is, based on the HWND that currently has focus.

With such an implementation of TranslateAccelerator and TabInto (from the previous section), a user of the application represented by Figure 19.4 would now be able to navigate all the way from 1 to 6 and back from 6 to 1 by using Tab and Shift+Tab, respectively.

To support access keys, you can override HwndHost’s OnMnemonic method. Like TranslateAccelerator, it is given a raw Windows message and a ModifierKeys enumeration. So you could implement it as follows, if you want to support two access keys, a and b:

Click here to view code image

virtual bool OnMnemonic(MSG% msg, ModifierKeys modifiers) override
{
  // Ensure that we got the expected message
  if (msg.message == WM_SYSCHAR && (modifiers | ModifierKeys.Alt))
  {
    // Convert the IntPtr to a char
    char key = (char)msg.wParam.ToPointer();

    // Only handle the 'a' and 'b' characters
    if (key == 'a')
      return (SetFocus(someHwnd) != NULL);
    else if (key == 'b')
      return (SetFocus(someOtherHwnd) != NULL);
  }
  return false;
}

WPF’s HWND interoperability is bidirectional, so WPF controls can be embedded in Win32 applications much like the way Win32 controls are embedded in WPF applications. In this section, you’ll see how to embed a built-in WPF control—DocumentViewer, the viewer for XPS documents—in a simple Win32 window using a class called HwndSource.

LISTING 19.6 HostingWPF.cpp—Embedding a WPF Control in a Win32 Dialog

Click here to view code image

In this project, a simple dialog is defined via a Win32 resource script (not shown here). The application’s entry point (_tWinMain) simply shows this dialog via the Win32 DialogBox function, specifying DialogFunction as the window procedure that receives the Win32 messages.

Inside DialogFunction, only two messages are processed—WM_INITDIALOG, which creates and embeds the WPF control on initialization, and WM_CLOSE, which terminates the dialog appropriately. Inside the processing of WM_INITDIALOG, an HwndSourceParameters structure is created, and some of its fields are initialized to give the HwndSource an initial size, position, and style. Most important, it is given a parent HWND (which, in this case, is the dialog itself). For Win32 programmers, this type of initialization should look very familiar. It’s mostly the same kind of information that you would pass to the Win32 CreateWindow function.

After HwndSourceParameters is populated, the code only needs to do two simple steps to put the WPF content in place. It instantiates an HwndSource object with the HwndSourceParameters data, and then it sets HwndSource’s RootVisual property (of type System.Windows.Media.Visual) to an appropriate instance. Here, a DocumentViewer is instantiated. Figure 19.5 shows the result.

Although this example uses a built-in WPF control, you can follow the same approach with your own arbitrarily complex WPF content. Just take the top-level element (for example, a Grid or Page) and use HwndSource to expose it to the rest of Win32 as one big HWND.

LISTING 19.7 HostingWPF.cpp—Updating the Size of the WPF Control

Click here to view code image

The most important code in Listing 19.7 is the handling of the WM_SIZE message. It uses the Win32 GetClientRect API to get the current window size, and then it applies it to the HwndSource using the Win32 SetWindowPos API. There are two interesting points about this new implementation:

The HwndSource variable is now “global,” so it can be shared by multiple places in the code. But C++/CLI does not allow a managed variable to be truly global, so the listing uses a common technique of making it a static variable of a managed class.

To operate on the HwndSource with Win32 APIs such as SetWindowPos, you need its HWND. This is exposed via a Handle property of type IntPtr. In C++/CLI, you can call its ToPointer method (which returns a void*) and then cast the result to an HWND.

However, there is an opportunity for much richer integration between Windows Forms and WPF, without delving into the underlying HWND-based plumbing. Sure, they have different rendering engines and different controls. But they both have rich .NET-based object models with similar properties and events, and both have services (such as layout and data binding) that go above and beyond their Win32 common denominator.

Indeed, WPF takes advantage of this opportunity and also has built-in functionality for direct interoperability with Windows Forms. This support is still built on top of the Win32 HWND interoperability described in the preceding two sections, but with many features to make the integration much simpler. The hard work is done for you, so you can communicate more directly between the technologies, usually without needing to write any unmanaged code.

As with Win32 interoperability, WPF defines a pair of classes to cover both directions of communication. The analog to HwndHost is called WindowsFormsHost, and it appears in the System.Windows.Forms.Integration namespace (in the WindowsFormsIntegration.dll assembly).

The first step is to add a reference to System.Windows.Forms.dll and WindowsFormsIntegration.dll to your WPF-based project. After you’ve done this, your Window’s Loaded event is an appropriate place to create and attach a hosted Windows Forms control. For example, consider this simple Window containing a Grid called grid:

Click here to view code image

<Window x:Class="HostingWindowsFormsControl.Window1"
  xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
  xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
  Title="Hosting a Windows Forms Property Grid in WPF"
  Loaded="Window_Loaded">
    <Grid Name="grid"/>
</Window>

The following handler of the Loaded event adds the PropertyGrid to the Grid, using WindowsFormsHost as the intermediate element:

Click here to view code image

private void Window_Loaded(object sender, RoutedEventArgs e)
{
  // Create the host and the PropertyGrid control
  System.Windows.Forms.Integration.WindowsFormsHost host =
    new System.Windows.Forms.Integration.WindowsFormsHost();
  System.Windows.Forms.PropertyGrid propertyGrid =
    new System.Windows.Forms.PropertyGrid();

  // Add the PropertyGrid to the host, and the host to the WPF Grid
  host.Child = propertyGrid;
  grid.Children.Add(host);

  // Set a PropertyGrid-specific property
  propertyGrid.SelectedObject = this;
}

The integration-specific code is as simple as instantiating WindowsFormsHost and setting its Child property to the desired object. WindowsFormsHost’s Child property can be set to any object that derives from System.Windows.Forms.Control.

The last line, which sets PropertyGrid’s SelectedObject property to the instance of the current WPF Window, enables a pretty amazing scenario. PropertyGrid displays the properties of any .NET object, and, in some cases, enables the editing of the object’s values. It does this via .NET reflection. Because WPF objects are .NET objects, PropertyGrid provides a fairly rich way to edit the current Window’s properties on the fly, without writing any extra code. Figure 19.7 shows the previously defined Window in action. When running this application, you can see values change as you resize the Window, you can type in new property values to resize the Window, you can change its background color or border style, and so on.

Notice that the enumeration values for properties such as HorizontalContentAlignment are automatically populated in a drop-down list, thanks to the standard treatment of .NET enums. But Figure 19.7 highlights some additional similarities between Windows Forms and WPF, aside from being .NET-based. Notice that Window’s properties are grouped into categories such as “Behavior,” “Content,” and “Layout.” This comes from CategoryAttribute markings that are used by both Windows Forms and WPF. The type converters that WPF uses are also compatible with Windows Forms, so you can type in “red” as a color, for example, and it gets automatically converted to the hexadecimal ARGB representation (#FFFF0000). Another neat thing about the PropertyGrid used in this manner is that you can see attached properties that could be applied to the object, with the syntax you would expect.

Not all Windows Forms controls work well within XAML, but PropertyGrid works reasonably well. For example, the previous XAML can be replaced with the following XAML:

Click here to view code image

<Window x:Class="HostingWindowsFormsControl.Window1"
  xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
  xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
  xmlns:swf="clr-namespace:System.Windows.Forms;assembly=System.Windows.Forms"
  Title="Hosting a Windows Forms Property Grid in WPF"
  Loaded="Window_Loaded" x:Name="rootWindow">
  <Grid>
    <WindowsFormsHost>
      <swf:PropertyGrid x:Name="propertyGrid"
                        SelectedObject="{x:Reference rootWindow}"/>
    </WindowsFormsHost>
  </Grid>
</Window>

The System.Windows.Forms.Integration .NET namespace is already included as part of WPF’s standard XML namespace, so WindowsFormsHost can be used without any additional work, as long as your project has a reference to WindowsFormsIntegration.dll. And with the System.Windows.Forms .NET namespace given the prefix swf, the PropertyGrid object can be instantiated directly in the XAML file. Notice that the PropertyGrid can be added as a child element to WindowsFormsHost because its Child property is marked as a content property. PropertyGrid’s properties can generally be set in XAML rather than C#. Thanks to x:Reference, SelectedObject can be set to the current Window instance (now named rootWindow), replicating the entire example without any procedural code needed!

To demonstrate the use of ElementHost, we’ll create a simple Windows Forms application that hosts a WPF Expander control. After creating a standard Windows Forms project in Visual Studio, the first step is to add ElementHost to the Toolbox using the Tools, Choose Toolbox Items menu item. This presents the dialog shown in Figure 19.8.

With ElementHost in the Toolbox, you can drag it onto a Windows Forms Form just like any other Windows Forms control. Doing this automatically adds references to the necessary WPF assemblies (PresentationFramework.dll, PresentationCore.dll, and so on). Listing 19.8 shows the main source file for a Windows Forms project whose Form contains an ElementHost called elementHost docked to the left and a Label on the right.

LISTING 19.8 Form1.cs—Embedding a WPF Expander in a Windows Forms Form

Click here to view code image

This code uses the System.Windows.Controls namespace for Expander, which it simply instantiates and initializes inside the Form’s constructor. ElementHost, like WindowsFormsHost, has a simple Child property that can be set to any UIElement. This property must be set in source code rather than in the Windows Forms designer, so here it is set to the Expander instance. Figure 19.9 shows the result. Notice that, by default, the Expander occupies all the space given to the ElementHost.

Taking this example one step further, you can use a combination of ElementHost and WindowsFormsHost to have a Windows Forms control embedded in a WPF control embedded in a Windows Forms application! All you need to do is set the Content of the WPF Expander to a WindowsFormsHost, which can contain an arbitrary Windows Forms control. Listing 19.9 does just that, placing a Windows Forms MonthCalendar inside a WPF Expander, all on the same Windows Forms Form. Figure 19.10 shows the result.

LISTING 19.9 Form1.cs—Using Both Directions of Windows Forms and WPF Integration

Click here to view code image

Starting with WPF 3.5 SP1 (and WPF 3.0 SP2), direct mixing of WPF and DirectX is now possible, no matter which direction you want to achieve interoperability. This feature—an ImageSource called D3DImage—doesn’t make interoperability significantly easier, but it does remove the inability to overlap that is unavoidable in the other interoperability scenarios. This means that you can blend, layer, and transform the two types of content with the same seamlessness that you get with any two WPF elements. The D3DImage functionality is not layered on top of HWND interoperability; it is a distinct and more powerful mechanism.

D3DImage is a container that can host an arbitrary DirectX surface. (Despite the name, this surface can contain 2D as well as 3D content.) Because D3DImage is an ImageSource, it can be used in a number of places, such as an Image, ImageBrush, or ImageDrawing.

For the example that demonstrates D3DImage, we’ll use a slightly different approach than the previous examples. This section’s example uses a simple unmanaged C++ application from the DirectX SDK. (The details of the example are unimportant for this chapter, but the full source code is available with this book’s source code on the website, http://informit.com/title/9780672336973.) This DirectX SDK example will remain completely unmanaged, but it will be turned into a DLL instead of an EXE. Then, a WPF C# application will access the functionality of the DirectX sample by using PInvoke to call three unmanaged APIs that it exposes.

The resulting sample is a hypothetical order form for tigers, where the background is a 3D spinning tiger provided by the DirectX DLL, and the foreground contains a bunch of standard WPF controls directly on top of the spinning tiger. Figure 19.11 shows the result.

Listing 19.10 contains the XAML for this WPF Window. It uses a D3DImage as its background, thanks to ImageBrush. It then places several WPF controls inside the Window at 70% opacity, to help demonstrate the blending of these controls with the DirectX background.

LISTING 19.10 MainWindow.xaml—A WPF Window Control with DirectX Background Content

Click here to view code image

The IsFrontBufferAvailableChanged event on D3DImage is important to handle. Throughout the application’s lifetime, WPF’s DirectX surface might occasionally become unavailable. (This can happen in a number of situations, such as when the user presses Ctrl+Alt+Delete to bring up the Windows lock screen or when the video driver changes.) Therefore, this event can trigger the initialization (or reinitialization) of the custom DirectX content as well as its cleanup, based on the value of D3DImage’s IsFrontBufferAvailable property.

The work of connecting the empty D3DImage to the actual DirectX content happens in the code-behind file, shown in its entirety in Listing 19.11.

LISTING 19.11 MainWindow.xaml.cs—Making D3DImage Work with DirectX Content from an Unmanaged C++ DLL

Click here to view code image

The listing begins by defining three simple PInvoke signatures for the three unmanaged APIs exported from DirectXSample.dll. Although the source code for DirectXSample.dll is not shown here, it is included in this book’s source code. (To build it yourself, you must first download and install a recent DirectX SDK from http://microsoft.com.) Regardless of the actual work done by the DirectX code, the pattern of Initialize, Render, and Cleanup is pretty universal. Initialize requires an HWND, because the underlying DirectX API—creating a Direct3D device—requires an HWND.

Because Initialize needs an HWND, you can’t call it from MainWindow’s constructor (unless you give it an HWND for a different window). Therefore, Window’s OnSourceInitialized method is overridden so initialization can be done from there. At this point, WindowInteropHelper is able to give you a valid HWND for the WPF Window. But rather than duplicate the initialization code from the d3dImage_IsFrontBufferAvailableChanged event handler, the code in OnSourceInitialized just calls it.

Inside d3dImage_IsFrontBufferAvailableChanged, the initialization path calls Initialize with the Window’s HWND, width, and height and gets back a reference to an IDirect3DSurface9 interface pointer disguised as an IntPtr (a common trick to avoid the need to create a managed definition of the interface). This IntPtr can then be passed to D3DImage.SetBackBuffer (while the D3DImage is locked) to associate the content. The unmanaged Render method needs to be called once per frame, so CompositionTarget’s static Rendering event is perfect for this purpose. The cleanup path of d3dImage_IsFrontBufferAvailableChanged—when IsFrontBufferAvailable is false—simply detaches the Rendering event handler and calls the unmanaged Cleanup method so the C++ code has a chance to release its resources.

Finally, the CompositionTarget_Rendering event handler calls the unmanaged Render method (while the D3DImage is locked) and also invalidates the entire area of the D3DImage by calling AddDirtyRect with the dimensions of the D3DImage. WPF composes any dirty regions from the D3DImage with its own internal surface and then renders the result. In some applications, this could be optimized by reducing invalidation to one or more smaller regions. In addition, some applications might not require the DirectX rendering and D3DImage invalidation to happen every frame.

Using Windows Forms as an intermediate layer between ActiveX and WPF might sound suboptimal, but the development experience is just about as pleasant as can be expected. To demonstrate how to embed an ActiveX control in a WPF application, this section uses the Microsoft Terminal Services control that ships with Windows. This control contains basically all the functionality of Remote Desktop, but it is controllable via a few simple APIs.

The first step for using an ActiveX control is to get a managed and Windows Forms–compatible definition of the relevant types. This can be done in two different ways:

Run the ActiveX Importer (AXIMP.EXE) on the ActiveX DLL. This utility is included in the .NET Framework component of the Windows SDK.

In any Windows Forms project in Visual Studio, add the component to the Toolbox using the COM Components tab from the dialog shown by choosing the Tools, Choose Toolbox Items menu item. Then drag the control from the Toolbox onto any Form. This process causes Visual Studio to invoke the ActiveX Importer behind the scenes.

No matter which approach you use, two DLLs are generated. You should add references to these in your WPF-based project (along with System.Windows.Forms.dll and WindowsFormsIntegration.dll). One is an interop assembly that contains “raw” managed definitions of the unmanaged interfaces, classes, enums, and structures defined in the type library contained inside the ActiveX DLL. The other is an assembly that contains a Windows Forms control that corresponds to each ActiveX class. The first DLL is named with the library name from the original type library, and the second DLL is named the same but with an Ax prefix.

For the Microsoft Terminal Services control, the original ActiveX DLL is called mstscax.dll and is found in the Windows system32 directory. (In the Choose Toolbox Items dialog, it shows up as Microsoft Terminal Services Client Control.) Running the ActiveX Importer generates MSTSCLib.dll and AxMSTSCLib.dll.

With the four relevant assemblies added to a project (MSTSCLib.dll, AxMSTSCLib.dll, System.Windows.Forms.dll, and WindowsFormsIntegration.dll), Listings 19.12 and 19.13 contain the XAML and C# code to host the control and get the resulting application shown in Figure 19.12.

LISTING 19.12 Window1.xaml—XAML for the Terminal Services WPF Application

Click here to view code image

LISTING 19.13 Window1.xaml.cs—C# Code for Hosting the Terminal Services ActiveX Control

Click here to view code image

There’s nothing special about the XAML in Listing 19.12; it simply contains a DockPanel with a TextBox and Button for choosing a server and connecting to it. In Listing 19.13, a WindowsFormsHost is added to the DockPanel, and the Windows Forms representation of the ActiveX control is added to the WindowsFormsHost. This control is called AxMsTscAxNotSafeForScripting. (In versions of Windows prior to Windows Vista, it has the somewhat simpler name AxMsTscAx.) The interaction with the complicated-sounding AxMsTscAxNotSafeForScripting control is quite simple. Its Server property can be set to a simple string, and you can connect to the server by calling Connect.

Of course, the instantiation of the WindowsFormsHost and the AxMsTscAxNotSafeForScripting control can be done directly in XAML, replacing the boldface code in Listing 19.13. This is shown in Listing 19.14. You could go a step further and use data binding to replace the first line in connectButton_Click, but you would still need the event handler for calling the Connect method.

LISTING 19.14 Window1.xaml—Updated XAML for the Terminal Services WPF Application

Click here to view code image

The main scenarios discussed in this chapter boil down to five classes. Their names are a bit confusing and inconsistent, so Table 19.1 provides a summary that you can flip back to if you ever forget which class is which.

The benefits of interoperability are broader than the features discussed in this chapter, however. You could completely overhaul an application’s user interface with WPF but hook it up to back-end logic already in place—even if that logic is unmanaged code. This could be done using a number of techniques, such as using C++/CLI, PInvoke, or COM interoperability.

Despite the ease and power of the features described in this chapter, there are still clear benefits to having an all-WPF user interface rather than a hybrid one. For example, in a pure WPF user interface, all the elements can be scaled, styled, and restyled in a similar fashion. They can be seamlessly overlaid on top of each other. Keyboard navigation and focus works naturally without much extra effort. In addition, you don’t have to worry about mixing resolution-independent elements with resolution-dependent elements. A pure WPF user interface also opens the door to being able to run in a partial-trust environment (depending on how you separate your back-end logic)—perhaps even buildable for a Windows Store app as well.

Even complex applications with years of user-interface investment can easily benefit from WPF if they are well factored. For example, I once came across an MFC-based program that showed street maps across the United States. The application used various MFC (therefore GDI-based) primitives to draw each line and shape in the current scene. By swapping in a WPF surface and performing the same drawing actions using the drawing APIs discussed in Chapter 15, “2D Graphics,” the map could be replaced with a WPF version with relatively small code changes. After making the leap to WPF, the application could now easily support features that would have been difficult otherwise: crisp zooming, tilting the map in 3D, and so on.

Therefore, if you have developed a pre-WPF application, there are many ways to improve its look or functionality by using interoperability to incrementally add WPF features. If you’ve developed pre-WPF controls, there’s another nice use of interoperability that doesn’t necessarily involve updating end-user functionality: Simply wrap such controls in a WPF object model so consumers can treat it like a first-class WPF control without having to learn about WPF’s interoperability features. Creating custom controls (whether pure WPF or not) is the topic of the next chapter.