XAML Hosting API sample
The XAML Hosting API sample is a win32 desktop app that demonstrates assorted scenarios using the UWP XAML hosting API (also called XAML islands).
- Windows desktop app that uses the XAML hosting API and c++ /WinRT to demonstrate usage of XAML controls within a win32 context. The scenarios demonstrated are:
- Using the Windows Ink UWP feature within a desktop app
- Playing select video files with the UWP Media Player Element control
- Handling XAML and native windows events/messages
- Demonstrates basic XAML data binding
Note: In Window 10 October 2018 Update, the UWP XAML hosting API is available as a developer preview. Although we encourage you to try out this API in your own prototype code now, we do not recommend that you use it in production code at this time. This API, and the sample, will continue to mature and stabilize in future Windows releases.
- Visual Studio 2017
- C++ /WinRT Visual Studio Extension (VSIX)
- Windows 10 SDK version 1809 (build 17763)
- Windows 10 October 2018 Update (version 1809, build 17763)
Note: This example was tested only in the 1809 build. There is no warranty that it works on the 19H1 insider builds. For example, we tested it on the Windows 10 18305 Insider build, and it worked after adding the maxversiontested property in the app manifest, but there were issues with the Reveal effects. As a workaround, the transparency effects were disabled in the OS Settings meanwhile the Product Feature team is finishing the work.
This sample is a "gallery style" project that incorporates Universal Windows Platform (UWP) controls into a Win32 Desktop app. Currently the following controls are used:
- Windows Ink Canvas and Ink Toolbar
- Media Player Element
- Navigation View
The presentation is module-based, and you can click through each of the XAML UI supported scenarios via the Navigation View control. The latter is a hosted XAML UI element that wraps all HWND/XAML content to provide a UWP functional, and themed, navigation experience. The below diagram illustrates the parent and child HWND layout, and the hosted XAML UI.
- The HWND parent/child hierarchy in the sample.
- The parent HWND (hwndParent) contains two child windows. The first, hwndSelection, holds the child hwndSelectionXamlIsland, which hosts the XAML Navigation View control.
- The second child of hwndParent, hwndDetail, is not bound to the Navigation View content property and the window is overlayed onto the HWND Detail Pane region depicted in the second callout. This HWND contains windows for Win32 controls as well as a window for containing XAML UI controls.
Code at a glance
If you're just interested in code snippets for certain areas, and don't want to browse or run the full sample, check out the following functions. The code for this project is located in Main.cpp.
- WindowInit - Defines and registers WNDCLASS structs for windows, creates the windows including the window for hosting the XAML Navigation View control, and displays the navigation UI.
- CreateSelectionMenu - This function returns a XAML grid UI element that contains the navigation view control. This XAML is hosted in hwndSelectionXamlIsland. The function also registers handlers for three events:
- NavigationView.Loaded - This handler sets the default Navigation View item and lays out the child windows of hwndDetail that overlay the HWND Detail Pane region.
- NavigationView.SelectionChanged - This handler determines the items selected in the Navigation View and loads the appropriate Win32 and XAML UI module in the detail window.
- Frame.SizeChanged - This handler responds to hwndParent size changes and updates the detail windows appropriately.
- CreateInkCanvas - Creates the InkCanvas and InkToolbar controls. Creates and returns a XAML UI element that it hosted in hwndDetailXamlIsland.
- CreateMediaPlayer - Creates the UWP MediaPlayerElement control. Creates and returns a XAML UI element that it hosted in hwndDetailXamlIsland.
- LoadModule - Sets the appropriate XAML for hosting based on Navigation View selection.
- The Media Player Element control cannot be maximized to full screen in the Media Player module at this time. The control will disappear if this is done and you'll need to click out of the module and back to restore the view.
This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit https://cla.microsoft.com.
When you submit a pull request, a CLA-bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., label, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA.