Magnum::Text::HarfBuzzFont class
#include <MagnumPlugins/HarfBuzzFont/HarfBuzzFont.h>

HarfBuzz font plugin.

Improves FreeTypeFont with text shaping capabilities provided by the HarfBuzz library.

This plugin provides the TrueTypeFont and OpenTypeFont plugins.

Usage

This plugin depends on the Text and HarfBuzz libraries and the FreeTypeFont plugin. It is built if MAGNUM_WITH_HARFBUZZFONT is enabled when building Magnum Plugins. To use as a dynamic plugin, load "HarfBuzzFont" via Corrade::PluginManager::Manager.

Additionally, if you're using Magnum as a CMake subproject, bundle the magnum-plugins repository and do the following. Using HarfBuzz itself as a CMake subproject isn't tested at the moment, so you need to provide it as a system dependency and point CMAKE_PREFIX_PATH to its installation dir if necessary.

set(MAGNUM_WITH_HARFBUZZFONT ON CACHE BOOL "" FORCE)
add_subdirectory(magnum-plugins EXCLUDE_FROM_ALL)

# So the dynamically loaded plugin gets built implicitly
add_dependencies(your-app MagnumPlugins::HarfBuzzFont)

To use as a static plugin or as a dependency of another plugin with CMake, request the HarfBuzzFont component of the MagnumPlugins package and link to the MagnumPlugins::HarfBuzzFont target:

find_package(MagnumPlugins REQUIRED HarfBuzzFont)

# ...
target_link_libraries(your-app PRIVATE MagnumPlugins::HarfBuzzFont)

See Downloading and building plugins, Plugin usage with CMake, Loading and using plugins amd File format support for more information.

Behavior and limitations

This plugin implements AbstractShaper::setScript(), setLanguage() and setDirection(). With HarfBuzz 5.2+ all Script values are supported, with older versions the function will return false if given script value is not supported. See documentation of the hb_script_t enum for more information about which scripts are supported on which version.

If AbstractShaper::setScript(), setLanguage() or setDirection() isn't called or it's explicitly set to unspecified values, the library will attempt to guess the properties. Script and direction is guessed from the input text passed to AbstractShaper::shape(), the language HarfBuzz currently detects from system locale. The actual properties used for shaping are then exposed through AbstractShaper::script(), language() and direction().

Reusing an AbstractShaper instance that has the script, language or direction left unspecified will attempt to guess these properties anew for every new shaped text. On the other hand, if a concrete script, language or direction value is set, it stays used for subsequent shaped text.

Typographic features

HarfBuzz enables the following features by default:

Additionally, for ShapeDirection::LeftToRight or ShapeDirection::RightToLeft, HarfBuzz enables the following by default:

Additionally, when HarfBuzz encounters a fraction slash (⁄, U+2044), it looks backward and forward for decimal digits, enables Feature::Numerators on the sequence before the slash, Feature::Denominators on the sequence after the slash and Feature::Fractions on the whole sequence including the slash.

For ShapeDirection::TopToBottom or ShapeDirection::BottomToTop, HarfBuzz enables Feature::VerticalWriting by default.

For Script::Hangul, HarfBuzz disables Feature::ContextualAlternates by default. For Indic scripts and Script::Khmer, HarfBuzz disables Feature::StandardLigatures by default.

Base classes

class FreeTypeFont: FreeType font plugin.

Public static functions

static void initialize(): Initialize the HarfBuzz library.
static void finalize(): Finalize the HarfBuzz library.

Constructors, destructors, conversion operators

HarfBuzzFont() deprecated in Git master explicit: Default constructor.
HarfBuzzFont(PluginManager::AbstractManager& manager, const Containers::StringView& plugin) explicit: Plugin manager constructor.

Function documentation

static void Magnum::Text::HarfBuzzFont::initialize()

Initialize the HarfBuzz library.

Empty in order to avoid FreeTypeFont::initialize() being called again when initializing this plugin.

static void Magnum::Text::HarfBuzzFont::finalize()

Finalize the HarfBuzz library.

Empty in order to avoid FreeTypeFont::finalize() being called again when initializing this plugin.

Magnum::Text::HarfBuzzFont::HarfBuzzFont() explicit

Default constructor.