DWriteTextLayoutCloudFont

topic	languages	products
sample	cpp cppcx	windows windows-uwp

Downloadable fonts (DirectWrite) sample

Shows how to use DirectWrite downloadable fonts, a feature added in Windows 10, together with the DirectWrite text layout API.

Note: This sample is part of a large collection of UWP feature samples. If you are unfamiliar with Git and GitHub, you can download the entire collection as a ZIP file, but be sure to unzip everything to access shared dependencies. For more info on working with the ZIP file, the samples collection, and GitHub, see Get the UWP samples from GitHub. For more samples, see the Samples portal on the Windows Dev Center.

A new capability in DirectWrite for Windows 10 allows an app to format text content using fonts that may not be installed on a device, and for the font to be downloaded on demand from a Microsoft service. DirectWrite now includes low-level APIs for using downloadable fonts. An easy way to leverage the downloadable font mechanism is to use DirectWrite's text layout (IDWriteTextLayout3), which integrates the lower-level APIs and does part of the work for you. When a text layout is created with a Windows font that is not locally installed, the text layout will automatically add requests for the font data to a font download queue. You need to add code that initiates the download and that responds when the download is completed.

Sample project files

The sample is intended to demonstrate how to use the DirectWrite downloadable font mechanism together with DirectWrite's text layout API. The app is comprised of two projects:

• The DWriteTextLayoutCloudFontImplementation project provides the implementation of DirectWrite APIs for text layout and downloadable fonts that are the main focus of this sample. It is implemented as a Windows Runtime Component that wraps around DirectWrite and enables interop with the sample client app. It also uses other DirectX APIs to implement a XAML SurfaceImageSource as a means of displaying the text layout.
• The DWriteTextLayoutCloudFont project provides the sample app shell, implemented using XAML, that functions as a client of the the DirectWrite APIs being demonstrated.

This organization suits the needs of this sample app, utilizing the simplicity of XAML for UI to navigate between scenarios while keeping the native DirectWrite code that's of primary interest separate and easier for you to focus on.

DWriteTextLayoutCloudFontImplementation project

Within the DWriteTextLayoutCloudFontImplementation project, the following files are significant:

• The TextLayout.h/.cpp files wrap the DirectWrite text layout API.
• The FontDownloadListener.h/.cpp files wrap around DirectWrite lower-level APIs for interacting with the font download mechanism, and provide an implementation of the IDWriteFontDownloadListener interface, needed for responding to the download mechanism.
• The FontNameCollector.h/.cpp files wrap additional DirectWrite APIs to determine which fonts are actually used in text layout. They are not needed to use the font download mechanism but provide you more insight, while the sample app is running, into how the text layout and font download mechanisms are interacting.
• The TextLayoutImageSource.h/.cpp files implement a XAML SurfaceImageSource using DirectX APIs for rendering the text layout.

DWriteTextLayoutCloudFont project

Within the DWriteTextLayoutCloudFont project, the following files are significant:

• The Scenario_Document1.*, Scenario_Document2.* and Scenario_Document3.* files each present a DirectWrite text layout using a different downloadable font that gets downloaded, with the layout subsequently being updated.
• The DocumentPresenter.* files provide the higher-level implementation for the three documents (Scenario_Document1, etc.) The DocumentPresenter class creates the text layout and the surface image source used to present it. It also creates the FontDownloadListener that interacts with DirectWrites font download mechanism and initiates the download of remote fonts. It also implements event handlers to update the layout and the surface image source when the remote font has been downloaded, and on other relevant events.
• The Scenario_SampleOverview.* files provide guidance for using the sample app.
• The Scenario_CloudFontOverview.* files provide more information about the downloadable font mechanism.

Other files are boilerplate files used for UWP sample apps.

Other files

The ClearDownloadableFontCache.ps1 file is not part of the sample project itself, but is a PowerShell script that can be used to reset the state of the downloadable font mechanism (clearing cached data) before or after running the sample app. Instructions for using this script are given in the sample app.

Related topics

IDWriteFactory3::GetSystemFontCollection method
IDWriteTextLayout3 interface
IDWriteFontDownloadQueue interface
IDWriteFontDownloadListener interface
Guidelines for fonts

System requirements

Client: Windows 10

Server: Windows Server 2016 Technical Preview

Phone: Windows 10

Build the sample

1. If you download the samples ZIP, be sure to unzip the entire archive, not just the folder with the sample you want to build.
2. Start Microsoft Visual Studio 2017 and select File > Open > Project/Solution.
3. Starting in the folder where you unzipped the samples, go to the Samples subfolder, then the subfolder for this specific sample, then the subfolder for your preferred language (C++, C#, or JavaScript). Double-click the Visual Studio Solution (.sln) file.
4. Press Ctrl+Shift+B, or select Build > Build Solution.

Run the sample

The next steps depend on whether you just want to deploy the sample or you want to both deploy and run it.

Deploying the sample

• Select Build > Deploy Solution.

Deploying and running the sample

• To run the sample with debugging, press F5 or select Debug > Start Debugging. To run the sample without debugging, press Ctrl+F5 or selectDebug > Start Without Debugging.