Adding controls and content (DirectX and C++)
[ This article is for Windows 8.x and Windows Phone 8.x developers writing Windows Runtime apps. If you’re developing for Windows 10, see the latest documentation ]
Just about every app needs controls such as buttons, check boxes, and drop-down lists. Windows Runtime apps using DirectX with C++ can work with the XAML framework to use its control and content APIs, or you can use Direct2D and DirectWrite to develop your own controls for your app.
There are three ways you can create controls and other interactive UI elements in your Windows Runtime app using DirectX:
- DirectX and XAML interop. This is the easiest case overall, where you can either create a DirectX surface for image compositing (SurfaceImageSource and VirtualSurfaceImageSource) inside your XAML framework, or draw a XAML layout on top of your swap chain (SwapChainBackgroundPanel). With either method, you can use the XAML controls provided in the Windows.UI.Xaml* namespaces. For apps that don't use the precise look-and-feel of our Windows Runtime app visual design guidelines, you can take advantage of XAML’s extensibility and styling options to give your app its own unique look and feel.
- Direct2D and DirectWrite. In this case, you draw your controls and content for your app using the Direct2D and DirectWrite APIs, handling all the input events directly. You draw your own app bar and settings, as well. It takes more work to lock down the look-and-feel of a Windows Runtime app than if you use XAML interop, but it's also quite a bit more flexible for apps that require a unique look.
- Direct3D. You can create your controls and content entirely in 3-D, or in conjunction with Direct2D and DirectWrite. Again, you draw your controls and content yourself, and manage their behaviors. This approach is best suited for games that don't use the precise look-and-feel of our Windows Store app visual design guidelines, but instead have unique looks and effects specifically suited to match their content.
Adding controls and content DirectX and XAML
If you're unfamiliar with the design guidelines for Windows Store apps, and want to get the benefit of all the great UI controls and components in the Windows.UI.Xaml namespaces, then start with XAML interop.
DirectX XAML interop requires a little work in setup, but after you've set up the DirectX framework, you can develop your Windows Runtime app using DirectX just like you would any other Windows Runtime app using XAML: you build your interface as a XAML document, and write your interface callback code as a C++ code behind.
There are two different types of DirectX XAML interop scenarios:
- You're writing a C++ Windows Runtime app using XAML, but want to use DirectX to composite an image that your app will display as content or as a control. In this case, you don't have to worry about a swap chain, because the XAML framework handles it for you. Now, you have two choices for the DirectX content or control:
- The image is smaller than or equal to the size of the screen, and will not be panned or zoomed. Use a SurfaceImageSource XAML element, and draw to it using the ISurfaceImageSourceNative interface.
- The image is larger than the screen, or will be panned and zoomed such that portions of it might be occluded. Use a VirtualSurfaceImageSource XAML element, and draw to it using the IVirtualSurfaceImageSourceNative interface.
- You're writing a DirectX app, and want to draw a XAML interface or overlay on top of the rendered content. In this case, you create and manage the swap chain (and any updated) for the rendered DirectX content directly. Use a SwapChainBackgroundPanel XAML element as the parent element in your XAML document (because it's a full screen component, and there can only be one of them), and create any other XAML control and content elements under it. Associate the swap chain for your app with the SwapChainBackgroundPanel XAML element through the ISwapChainBackgroundPanelNative interface.
Use these docs to help you get started with XAML content and controls.
| Topic | Description |
|---|---|
| DirectX and XAML interop | Learn how to use the three different XAML elements used for displaying DirectX content in a Windows Runtime app with XAML. |
| Adding and styling controls (Windows Runtime app using C++, C#, or Visual Basic) | The topics in this section get you started with adding and styling controls. |
| Controls list (Windows Runtime app using C++, C#, or Visual Basic) | An alphabetical list of the common controls for Windows Runtime apps with XAML. |
| Controls by function (Windows Runtime app using C++, C#, or Visual BasicL) | A list of the common controls by function for Windows Runtime apps with XAML. |
| Displaying and editing text (Windows Runtime app using C++, C#, or Visual Basic) | The topics in this section provide info about displaying and editing text. |
| Displaying images, graphics, and thumbnails (Windows Runtime app using C++, C#, or Visual Basic) | The topics in this section get you started with displaying graphics. (Note: XAML primitives, not DirectX graphics.) |
| Adding layout controls (Windows Runtime app using C++, C#, or Visual Basic) | Learn how to create and use layout controls to arrange elements of your app UI. |
This sample demonstrates DirectX XAML interop using SwapChainBackgroundPanel:
Adding controls and content with Direct2D and DirectWrite
If you aren't using XAML with your Windows Runtime app using DirectX, you can create all your content and controls using the Direct2D and DirectWrite APIs. In this case, you must first create a view provider for DirectX, or use one of the templates provided in Microsoft Visual Studio, such as the Direct2D App or Direct3D App templates.
The view provider connects the DirectX swap chain to the CoreWindow for your app. CoreWindow defines all the basic input and system events for your app. You can use them to determine where on the screen a user has pressed or clicked, or if they've pressed a key, or if they've suspended or resumed your app. Handle these input events fired on the CoreWindow by creating callbacks for them and using the data to manage the behaviors of the Direct2D controls and content you create. For example, this is the process for creating your own button control using Direct2D:
- Draw the button as a Direct2D primitive. Draw any text for it using DirectWrite. Present the swap chain, and wait for a PointerPressed event.
- In your callback for the PointerPressed event, use the pixel coordinates provided by the event to determine if the click or press happened within the area of your button. (This is called "hit testing".)
- If it did, dispatch the operation associated with the button. Update the animation for the button to indicate a successful press.
- Draw the updated button and present the swap chain as needed until the animation completes.
Create your controls and content according to the design guidelines for Windows Runtime apps. In most cases, you’ll have to define the control behaviors and draw the controls and content yourself. You can, however, use system-provided controls and dialog boxes like PopupMenu. For a list of system controls that you can use, see the Windows.UI.Xaml.Controls namespace.
Draw your control geometry with Direct2D primitives, and use Direct2D effects for animations. Create and manage text layers for controls and content using the DirectWrite APIs. The same is true for dialog boxes and flyout windows in your app; you provide the look-and-feel for the CoreWindowDialog and CoreWindowFlyout types, respectively.
You must also perform any image composition for dynamic image content yourself.
If you're new to Direct2D and DirectWrite, take a look at these samples for inspiration:
- DirectWrite hit testing sample
- Input: touch hit testing sample
- Direct2D composite effect modes sample
For image content composition, you can also use the Windows Image Composition (WIC) APIs. Check out this code sample for implementation details:
Adding controls and content with Direct3D
If you're developing a game or immersive graphics app, you often create your own controls or 3-D text that match the look and feel of the content in your app. In this case, you can create your controls using Direct3D.
As with Direct2D and DirectWrite content and controls, you use the input events raised on the CoreWindow to determine when interaction has occurred. For Direct3D, you are working with your graphics rendering pipeline directly and are responsible for translating an input event's 2-D screen coordinates to and from the corresponding location in your 3-D viewport and its 2-D projection.
When an input event (such as PointerPressed) is raised, do the following:
- Translate the pixel coordinates of the event from the screen coordinate system to the 3-D scene (world) coordinate system.
- Perform any hit testing to determine the control that the user is intending to interact with.
- Render the animation for selection feedback and present them.
This sample illustrates this process:
You can also create your controls as Direct2D and DirectWrite primitives in a specific Direct2D context, and composite the Direct2D render target with the Direct3D scene in the swap chain. In this case, you'd implement your input controls using the Direct2D hit testing method. Take a look at the following sample to see how this process works.
Related topics
Developing apps (C++ and DirectX)