Manage Script-Specific Theme Fonts in C++

Overview

A presentation theme can select different font families for different writing systems. This allows multilingual text that still uses theme fonts to follow one coordinated font scheme while using suitable fonts for Cyrillic, Arabic, Japanese, Georgian, Thaana, and other scripts.

The theme’s IFontScheme contains a major font collection, typically used for headings, and a minor font collection, typically used for body text. In addition to their Latin and East Asian font properties, both collections expose mappings from writing-system tags to font family names through the IFonts interface.

This article shows how to inspect and modify those mappings in the presentation’s master theme and verify that the changes survive a save-and-reload cycle.

Understand Script Tags

The script font methods use four-letter BCP 47 script subtags to identify writing systems. Common values include:

Script tag Writing system
Cyrl Cyrillic
Arab Arabic
Hans Simplified Chinese
Jpan Japanese
Geor Georgian
Thaa Thaana

These mappings belong to the theme font scheme, not to individual text portions. A presentation may define different mappings for the major and minor collections, and it may omit mappings for some scripts.

Access and Inspect Script Font Mappings

Use Presentation::get_MasterTheme to access the presentation-level theme. The FontScheme::get_Major and FontScheme::get_Minor methods return the two IFonts collections.

Call Fonts::GetScriptFontMap to retrieve all mappings from a collection. To look up one writing system, call Fonts::GetScriptFont with its script tag. GetScriptFont returns a null string when that collection does not define the requested mapping.

Modify Mappings and Verify Persistence

Use Fonts::SetScriptFont to create a mapping or replace its current font family. Use Fonts::RemoveScriptFont to remove a mapping.

The following end-to-end example reads all existing major and minor mappings, looks up the Japanese major font, changes the Cyrillic major font, removes the Thaana minor mapping, saves the presentation, and reopens it to verify both changes. To make the removal step independent of the initial theme, the example first creates a Thaana mapping only when one is not already defined.

#include <DOM/IFonts.h>
#include <DOM/Presentation.h>
#include <DOM/Theme/IFontScheme.h>
#include <DOM/Theme/IMasterTheme.h>
#include <Export/SaveFormat.h>
#include <system/collections/idictionary.h>
#include <system/console.h>
#include <system/string.h>

using namespace Aspose::Slides;
using namespace Aspose::Slides::Export;
using namespace System;

auto presentation = MakeObject<Presentation>();
auto fontScheme = presentation->get_MasterTheme()->get_FontScheme();
auto majorFonts = fontScheme->get_Major();
auto minorFonts = fontScheme->get_Minor();

Console::WriteLine(u"Existing major mappings:");
for (auto&& mapping : majorFonts->GetScriptFontMap())
{
    Console::WriteLine(u"  {0}: {1}", mapping.get_Key(), mapping.get_Value());
}

Console::WriteLine(u"Existing minor mappings:");
for (auto&& mapping : minorFonts->GetScriptFontMap())
{
    Console::WriteLine(u"  {0}: {1}", mapping.get_Key(), mapping.get_Value());
}

auto japaneseFont = majorFonts->GetScriptFont(u"Jpan");
if (japaneseFont.IsNull())
{
    Console::WriteLine(u"No major Japanese font is defined.");
}
else
{
    Console::WriteLine(u"Major Japanese font: {0}", japaneseFont);
}

majorFonts->SetScriptFont(u"Cyrl", u"Arial");

if (minorFonts->GetScriptFont(u"Thaa").IsNull())
{
    minorFonts->SetScriptFont(u"Thaa", u"Arial");
}

minorFonts->RemoveScriptFont(u"Thaa");
presentation->Save(u"script-font-mappings.pptx", SaveFormat::Pptx);

auto savedPresentation = MakeObject<Presentation>(u"script-font-mappings.pptx");
auto savedFontScheme = savedPresentation->get_MasterTheme()->get_FontScheme();
auto savedMajorFonts = savedFontScheme->get_Major();
auto savedMinorFonts = savedFontScheme->get_Minor();
auto savedCyrillicFont = savedMajorFonts->GetScriptFont(u"Cyrl");
auto savedThaanaFont = savedMinorFonts->GetScriptFont(u"Thaa");

if (savedCyrillicFont == u"Arial")
{
    Console::WriteLine(u"The Cyrillic mapping was preserved.");
}
else
{
    Console::WriteLine(u"The Cyrillic mapping was not preserved.");
}

if (savedThaanaFont.IsNull())
{
    Console::WriteLine(u"The Thaana mapping removal was preserved.");
}
else
{
    Console::WriteLine(u"The Thaana mapping still exists.");
}

The verification uses the same null-string behavior as an ordinary lookup: after the removal is saved, GetScriptFont(u"Thaa") returns a null string for the minor collection.

Distinguish Theme Mappings from Other Font Settings

Script-specific theme mappings participate in font selection, but they solve a different problem from direct text formatting, substitution, and fallback:

Mechanism Purpose Effect of changing a theme mapping
Script-specific theme font mapping Selects a major or minor theme font for a writing system. Text that still uses the corresponding theme font can resolve to the new mapped family.
Font assigned explicitly to a text portion Fixes the requested font family on that portion instead of relying on the theme. The portion may remain unchanged because its direct formatting overrides the theme choice.
Font substitution Replaces a requested font when that font is unavailable or when a substitution rule applies. It acts after a font has been requested; it does not redefine the theme’s script mapping.
Font fallback Supplies glyphs that the selected font does not contain, often for specific Unicode ranges. It fills missing glyph coverage; it does not change the stored theme mapping.

For more information about the last two mechanisms, see Font Substitution and Fallback Fonts.

Changing a mapping in Presentation::get_MasterTheme affects only content whose effective formatting still depends on that theme. Text can instead inherit a theme override from a master, layout, or slide, or use an explicitly assigned font. Inspect those levels when the visible result does not follow the presentation-level mapping.

Make Mapped Fonts Available and Validate the Result

A script mapping stores a font family name; it does not install or load the corresponding font file. For consistent rendering and export, every mapped font must be installed in the environment or supplied to Aspose.Slides through a custom source such as FontsLoader::LoadExternalFonts or LoadOptions::set_DocumentLevelFontSources. See Custom Fonts for the available loading options.

Verifying the saved mapping confirms only that the theme definition was preserved. It does not prove that the font is available, contains all required glyphs, or produces the intended layout. Render representative text for every required writing system to an image or PDF and inspect the output. This catches missing fonts, incomplete glyph coverage, fallback behavior, and layout changes before the presentation is distributed. See Convert PowerPoint Presentations for rendering and export examples.

FAQ

What does GetScriptFont return when a script is not mapped?

Fonts::GetScriptFont returns a null string when the requested script mapping is not defined in that major or minor font collection.

Does SetScriptFont add a second mapping when the script already exists?

No. Fonts::SetScriptFont creates the mapping when it is missing and replaces the mapped font family when the same script tag is already present.

Why did changing a theme mapping not change some text?

The text may have an explicitly assigned font, inherit a different theme through an override, or be affected by substitution or fallback during rendering. A presentation-level script mapping controls only text whose effective formatting still refers to that theme font collection.

Is saving and reopening enough to validate multilingual output?

No. Reopening verifies persistence of the theme data. Also render representative text from each required writing system to confirm that the mapped fonts are available and contain the necessary glyphs.

Manage Presentation Themes in C++ Manage Presentation Backgrounds in C++