Magnum::Ui::TextLayer class new in Git master

#include <Magnum/Ui/TextLayer.h>

Setting up a text layer instance

If you create a UserInterfaceGL with a style and don't exclude StyleFeature::TextLayer, an implicit instance of the TextLayerGL subclass, configured for use with builtin widgets, is already provided and available through UserInterface::textLayer().

For a custom layer, you first need to instantiate TextLayer::Shared, which contains a glyph cache, font instances, GPU shaders and style definitions. It's constructed from a glyph cache reference and a configuration instance. In case of the TextLayerGL implementation the cache is Text::GlyphCacheArrayGL. Assuming monochrome fonts, construct it with a single-channel pixel format and a size large enough to fit pre-rendered glyphs of all fonts you'll need:

Text::GlyphCacheArrayGL glyphCache{PixelFormat::R8Unorm, {256, 256, 4}};

The glyph cache is expected to be alive for the whole shared instance lifetime, alternatively you can use the TextLayerGL::Shared::Shared(Text::GlyphCacheArrayGL&&, const Configuration&) constructor to move its ownership to the shared instance. For the TextLayer::Shared::Configuration, at the very least you have to specify how many distinct visual styles you intend to use, which is for example the number 3 in the following snippet:

Ui::TextLayerGL::Shared textLayerShared{glyphCache,
    Ui::TextLayer::Shared::Configuration{3}
};

The shared instance, in this case a concrete TextLayerGL::Shared subclass for the OpenGL implementation of this layer, is then passed to the layer constructor alongside a fresh AbstractUserInterface::createLayer() handle, and is expected to stay alive for the whole layer lifetime. The shared instance can be used by multiple layers, for example if the application wants to have a dedicated layer for very dynamic UI content, or if it combines visual options that have to be hardcoded in particular TextLayer::Shared instances. To make the layer available as the implicit UserInterface::textLayer(), pass it to UserInterfaceGL::setTextLayerInstance():

ui.setTextLayerInstance(
    Containers::pointer<Ui::TextLayerGL>(ui.createLayer(), textLayerShared));

Otherwise, if you want to set up a custom base layer that's independent of the one exposed through UserInterface::textLayer(), possibly for completely custom widgets, pass the newly created layer to AbstractUserInterface::setLayerInstance() instead:

Ui::TextLayer& textLayer = ui.setLayerInstance(
    Containers::pointer<Ui::TextLayerGL>(ui.createLayer(), textLayerShared));

Afterwards, in order to be able to draw the layer, at least one font has to be added, and a style referencing the fonts has to be set. Text::AbstractFont instances, commonly loaded using a plugin manager, are added with TextLayerGL::Shared::addFont(), together with specifying size in UI coordinates at which a text using them should be rendered. The function then returns a FontHandle, which is subsequently used to reference the font from styles. As with the glyph cache, the font instance is expected to be alive for the whole shared instance lifetime, or you can use TextLayerGL::Shared::addFont(Containers::Pointer<Text::AbstractFont>&&, Float) to move the loaded plugin ownership to the shared instance. Note that you're still responsible for keeping the plugin manager instance around even in that case.

PluginManager::Manager<Text::AbstractFont> fontManager;

Containers::Pointer<Text::AbstractFont> font16 =
    fontManager.loadAndInstantiate("TrueTypeFont");
if(!font16 ||
   !font16->openFile("font.ttf", 16.0f) ||
   !font16->fillGlyphCache(glyphCache, "abcdefghijklmnopqrstuvwxyz"
                                       "ABCDEFGHIJKLMNOPQRSTUVWXYZ"
                                       "0123456789?!:;,. "))
    Fatal{} << "Uh oh";

Containers::Pointer<Text::AbstractFont> font12 =
    fontManager.loadAndInstantiate("TrueTypeFont");
if(!font12 ||
   !font12->openFile("font.ttf", 12.0f) ||
   !font12->fillGlyphCache(glyphCache, "abcdefghijklmnopqrstuvwxyz"
                                       "ABCDEFGHIJKLMNOPQRSTUVWXYZ"
                                       "0123456789?!:;,. "))
    Fatal{} << "Oh no";

Ui::FontHandle font16Handle = textLayerShared.addFont(*font16, font16->size());
Ui::FontHandle font12Handle = textLayerShared.addFont(*font12, font12->size());

Assuming the UI size matches the framebuffer size, a good default is to use the same size in Text::AbstractFont::openFile() / openData() and TextLayerGL::Shared::addFont(), like in the snippet above. See the Text crispness and DPI awareness section below for additional considerations.

Finally, a style referencing the fonts has to be set with TextLayer::Shared::setStyle(). At the very least you're expected to pass a TextLayerCommonStyleUniform containing properties common to all styles, an array of TextLayerStyleUniform matching the style count in the TextLayer::Shared::Configuration, and a FontHandle and Text::Alignment alignment that given style should use. Default-constructed instances will result in white text, you can then use method chaining to update only the properties you're interested in; zero-initialized Text::Alignment value is equivalent to Text::Alignment::LineLeft. In the following snippet, style 0 uses the first, larger font and style defaults, style 1 is the first font again but with a blue color, and style 2 is the smaller font centered:

textLayerShared.setStyle(Ui::TextLayerCommonStyleUniform{}, {
    Ui::TextLayerStyleUniform{},    /* Style 0, default */
    Ui::TextLayerStyleUniform{}     /* Style 1 */
        .setColor(0x2f83cc_rgbf),
    Ui::TextLayerStyleUniform{}     /* Style 2 */
}, {
    font16Handle,                   /* Font for style 0 */
    font16Handle,                   /* Font for style 1 */
    font12Handle                    /* Font for style 2 */
}, {
    Text::Alignment{},              /* Alignment for style 0 */
    Text::Alignment{},              /* Alignment for style 1 */
    Text::Alignment::MiddleCenter   /* Alignment for style 2 */
}, {}, {}, {}, {}, {}, {});

With this, assuming AbstractUserInterface::draw() is called in an appropriate place, the layer is ready to use. All style options are described in detail further below.

Creating texts

A text is created by calling create() with desired style index, the actual UTF-8 string to render, a TextProperties instance with optional data-specific shaping and layout settings, and a NodeHandle the data should be attached to. In this case it picks the style 1 from above, which makes the text blue:

Ui::NodeHandle node = ui.createNode(…);

textLayer.create(1, "hello!", {}, node);

As with all other data, they're implicitly tied to lifetime of the node they're attached to. You can remember the Ui::DataHandle returned by create() to modify the data later, attach() to a different node or remove() it.

Style, shaping and layout options

Text color

The color supplied with TextLayerStyleUniform::setColor() as shown above is additionally multiplied by a data-specific color set with setColor(). The main use case, like with BaseLayer, is to allow for example custom label coloring where it would be impractical to dynamically update style data based on what's being shown. The color is further multiplied by a per-node opacity coming from AbstractUserInterface::setNodeOpacity(), which can be used for various fade-in / fade-out effects.

textLayerShared.setStyle(…, {
    Ui::TextLayerStyleUniform{}, /* 0 */
    Ui::TextLayerStyleUniform{}  /* 1 */
        .setColor(0x2f83cc_rgbf)
}, {…}, {…}, {}, {}, {}, {}, {}, {});

…

Ui::NodeHandle blue = …;
textLayer.create(1, "hello!", {}, blue);

Ui::NodeHandle colored = …;
Ui::DataHandle coloredData = textLayer.create(0, "HEY", {}, colored);
textLayer.setColor(coloredData, 0x3bd267_rgbf);

Ui::NodeHandle fadedBlue = …;
textLayer.create(1, "shh", {}, fadedBlue);
ui.setNodeOpacity(fadedBlue, 0.25f);

At the moment, there's no possibility to assign different color to individual glyphs or text ranges.

Alignment and padding inside the node

Text::Alignment::MiddleCenter passed to TextLayer::Shared::setStyle() aligns vertical and horizontal glyph bounds, defined by font ascent, descent, line advance and glyph advance, to vertical and horizontal center of given node. Text::Alignment::TopLeft and other alignment values then align a particular edge or baseline of the text to node edges and corners. With those, it's often desirable to specify also a padding inside the node with the last argument to TextLayer::Shared::setStyle(), so e.g. a text inside a text box has some spacing around without having to put it inside a slightly smaller child node. Similarly as with padding in BaseLayer, it's one value for each of four node edges, but often a single value for all is enough:

textLayerShared.setStyle(…, {…}, {…}, {
    Text::Alignment::TopLeft
}, {}, {}, {}, {}, {}, {
    Vector4{8.0f}
});

If needed, style-provided alignment can be overriden for particular data with TextProperties::setAlignment() — or by passing a Text::Alignment directly, as it's implicitly convertible to TextProperties — when creating or updating the text. Note that, unlike e.g. LineLayer::setAlignment(), the alignment cannot be changed dynamically for an already shaped text. The reason is that the alignment may offset each line differently and is dependent on shaping direction of the input text, but neither the input text nor line break positions or other properties are remembered by default.

Finally, the padding can be overriden on a per-data basis with setPadding(). This is especially useful when aligning text of a variable width next to other UI elements such as icons, or combining two differently styled pieces of text together. The following snippet shows aligning a text next to a colored hash character using size() to query the actual rendered size, the other element could also be anything from a BaseLayer or a LineLayer which provide the same padding interfaces. Additionally, the space between the two is defined by the style itself and thus doesn't have to be hardcoded in the offset calculation:

textLayerShared.setStyle(…, {
    Ui::TextLayerStyleUniform{} /* 0 */
        .setColor(0xa5c9ea_rgbf),
    Ui::TextLayerStyleUniform{} /* 1 */
        .setColor(0x2f83cc_rgbf)
}, {…}, {
    /* With centered alignment half of the padding value is used for each */
    Text::Alignment::MiddleCenter,
    Text::Alignment::MiddleCenter
}, {}, {}, {}, {}, {}, {
    /* Left, top, right, bottom */
    {0.0f, 0.0f, 2.0f, 0.0f},
    {2.0f, 0.0f, 0.0f, 0.0f}
});

…

Ui::NodeHandle node = …;
Ui::DataHandle hash = textLayer.create(0, "#", {}, node);
Ui::DataHandle text = textLayer.create(1, "whee", {}, node);

/* Left, top, right, bottom. Again, centered alignment makes use of half of the
   padding value for each, keeping the two centered as a group. */
textLayer.setPadding(hash, {0.0f, 0.0f, textLayer.size(text).x(), 0.0f});
textLayer.setPadding(text, {textLayer.size(hash).x(), 0.0f, 0.0f, 0.0f});

Ui::FontHandle greekFontHandle = textLayerShared.addFont(…);

…

Ui::NodeHandle hello = …;
textLayer.create(…, "Γεια!", greekFontHandle, hello);

textLayer.create(…, "Γεια!",
    Ui::TextProperties{}
        .setFont(greekFontHandle)
        .setScript(Text::Script::Greek)
        .setLanguage("el-GR")
        .setShapeDirection(Text::ShapeDirection::LeftToRight),
    hello);

Font feature selection

TextProperties::setFeatures() allows you to configure OpenType typographic features applied when shaping given text. Again, support for these depends on the font plugin used as well as features exposed by a particular font file. At the moment, HarfBuzzFont is the only plugin implementing these, and most of the features are limited to OTF fonts, TTF supports only a small subset such as toggling Text::Feature::Kerning. In the following snippet, the whole text gets Text::Feature::OldstyleFigures enabled, causing certain numbers to reach below the baseline, then an alternative glyph of the a character in Status is picked, and Text::Feature::SmallCapitals is used for the part of the string containing the actual status description:

textLayer.create(…, "Status: 418 I'm a Teapot",
    Ui::TextProperties{}.setFeatures({
         Text::Feature::OldstyleFigures,
        {Text::Feature::CharacterVariants2, 2, 3},
        {Text::Feature::SmallCapitals, 8, ~UnsignedInt{}},
    }), …);

Note that the features will likely need additional glyphs to be pre-filled in the cache. The Text::AbstractFont::fillGlyphCache(AbstractGlyphCache&, const Containers::StridedArrayView1D<const UnsignedInt>&) overload allows you to specify individual glyph IDs, and Text::AbstractFont::glyphForName() allows you to query the IDs by names that you can look up in some font inspection utility. In case of the Source Sans font used here, it could look like this:

font->fillGlyphCache(glyphCache, {
    /* Small capitals */
    font->glyphForName("A.s"),
    font->glyphForName("B.s"),
    font->glyphForName("C.s"),
    font->glyphForName("D.s"),
    …
    /* Oldstyle figures */
    font->glyphForName("one.t"),
    font->glyphForName("two.t"),
    font->glyphForName("three.t"),
    …
    /* Character variant for lowercase a */
    font->glyphForName("a.a")
});

Font features can be also specified as part of the style. For example you may want to have all title labels in small caps, and all numeric fields with Text::Feature::TabularFigures instead of proportional and with Text::Feature::SlashedZero to distinguish a zero from an uppercase O. All used features are supplied as a list in the fifth argument to TextLayer::Shared::setStyle(), and then each style specifies an offset and count into this list in the next two arguments. The same features can be used by multiple ranges, count being 0 means no features are used for given style:

textLayerShared.setStyle(…, {
    Ui::TextLayerStyleUniform{} /* title */
        .setColor(0xdcdcdc_rgbf),
    Ui::TextLayerStyleUniform{} /* main title */
        .setColor(0xa5c9ea_rgbf),
    Ui::TextLayerStyleUniform{} /* numeric fields */
        .setColor(0xdcdcdc_rgbf),
    Ui::TextLayerStyleUniform{} /* general text */
        .setColor(0xdcdcdc_rgbf)
}, {…}, {…}, {
    Text::Feature::SmallCapitals,  /* 0 */
    Text::Feature::TabularFigures, /* 1 */
    Text::Feature::SlashedZero,    /* 2 */
}, {
    0, /* title */
    0, /* main title */
    1, /* numeric fields */
    0, /* general text */
}, {
    1, /* title uses feature 0 */
    1, /* main title uses feature 0 as well */
    2, /* numeric fields use feature 1 and 2 */
    0  /* general text uses no features */
}, {}, {}, {});

Text crispness and DPI awareness

With Text::GlyphCacheArrayGL, if the UI size differs from the actual framebuffer size, which is often the case on HiDPI systems and other scenarios described in AbstractUserInterface DPI awareness docs, using the same font size in both Text::AbstractFont::openFile() / openData() and TextLayerGL::Shared::addFont() will result in blurry text. Additionally, because glyphs are often placed at subpixel locations, it's often better to supersample the font at twice the size it's used in for crisper edges even if no HiDPI interface scaling is involved. Thus, the size at which the font is opened and at which the glyph cache is filled should be multiplied by a factor compared to the size the font is used in the UI:

/* Supersample 2x in addition to DPI scaling */
Float scale = 2.0f*(Vector2{ui.framebufferSize()}/ui.size()).max();

font->openFile("font.ttf", 16.0f);
…
Ui::FontHandle fontHandle = textLayerShared.addFont(*font, font->size()*scale);

Fonts added with TextLayerGL::Shared::addInstancelessFont() should then use the scale directly.

Distance field rendering

With Text::GlyphCacheArrayGL that's used above, drawing a particularly sized text involves first populating the cache with a font rasterized at a size matching physical screen pixels. This gives the font plugin an opportunity to align glyph outlines in a way that best suits given size. While it's possible to pass the same Text::AbstractFont instance to TextLayer::Shared::addFont() multiple times with different sizes, the result will likely be either blurry or jaggy.

Having a dedicated font for every size becomes impractical if the application needs to use many font sizes, if it needs to scale the text dynamically or if advanced effects such as thinning, thickening or outline are needed. For such cases, it's possible to use Text::DistanceFieldGlyphCacheArrayGL instead. Compared to the regular glyph cache it requires three input parameters, size of the source image, size of the resulting glyph cache image and a radius for the distance field creation. Their relation and effect on output quality and memory use is described in detail in TextureTools::DistanceFieldGL docs. In short, the ratio between the input and output image size is usually four or eight times, and the size of the font should match the larger size. So, for example, if a {256, 256} Text::GlyphCacheGL would be filled with a 16 pt font, a {1024, 1024} source image for the distance field should use a 64 pt font. The radius should then be chosen so it's at least one or two pixels in the scaled-down result, so in this case at least 4:

Text::DistanceFieldGlyphCacheArrayGL glyphCache{{1024, 1024, 4}, {256, 256}, 20};

Ui::TextLayerGL::Shared textLayerShared{glyphCache,
    Ui::TextLayer::Shared::Configuration{3}
};

The glyph cache is expected to be alive for the whole shared instance lifetime, or you can again use the TextLayerGL::Shared::Shared(Text::DistanceFieldGlyphCacheArrayGL&&, const Configuration&) constructor to move the glyph cache ownership to the shared instance. Afterwards, you can add the same font instance more than once with different sizes. The sizes no longer need to match the size at which the font was opened and rasterized, but rather should be a concrete size at which it's meant to be drawn in the UI:

Containers::Pointer<Text::AbstractFont> font =
    fontManager.loadAndInstantiate("TrueTypeFont");
font->openFile("font.ttf", 64.0f);
font->fillGlyphCache(glyphCache, "abcdefghijklmnopqrstuvwxyz"
                                 "ABCDEFGHIJKLMNOPQRSTUVWXYZ"
                                 "0123456789?!:;,. ");

Ui::FontHandle font8Handle = textLayerShared.addFont(*font, 8.0f);
Ui::FontHandle font16Handle = textLayerShared.addFont(*font, 16.0f);
Ui::FontHandle font12Handle = textLayerShared.addFont(*font, 12.0f);

Edge smoothness

With Text::GlyphCacheArrayGL, the rendered text has edges antialiased already by the rasterizer of a particular font plugin. With distance field rendering you have full control over how the edges look. Similarly to BaseLayer and LineLayer, the edges are aliased by default and with TextLayerCommonStyleUniform::setSmoothness() you set up a smoothness radius in framebuffer pixels. It's not in UI units in order to ensure crisp look everywhere without having to specifically deal with HiDPI displays. Additionally, for effects like shadow or glow, TextLayerStyleUniform::setSmoothness() can override the smoothness per style, and this value is in UI units instead of pixels. The desired usage is that the common smoothness gets tuned for BaseLayer, LineLayer and any distance-field-enabled text layer to a value that makes sense for the UI in general, and the per-style smoothness is then used for text elements that need a fuzzy appearance. Of the two values coming from the style, the larger one — when both are converted to the same units — gets used.

textLayerShared.setStyle(
    Ui::TextLayerCommonStyleUniform{}
        .setSmoothness(1.0f),
    {Ui::TextLayerStyleUniform{}    /* 0 */
        .setColor(0x2f83cc_rgbf),
     Ui::TextLayerStyleUniform{}    /* 1 */
        .setColor(0xa5c9ea_rgbf),
     Ui::TextLayerStyleUniform{}    /* 2 */
        .setColor(0xdcdcdc_rgbf)
        .setSmoothness(4.0f)},
    {font8Handle,                   /* Font for style 0 */
     font16Handle,                  /* Font for style 1 */
     font12Handle},                 /* Font for style 2 */
    {…}, {}, {}, {}, {}, {}, {});

…

Ui::NodeHandle small = …;
Ui::NodeHandle big = …;
Ui::NodeHandle smooth = …;
textLayer.create(0, "small", {}, small);
textLayer.create(1, "big", {}, big);
textLayer.create(2, "smooth", {}, smooth);

Note that the smoothness is not depending on the size at which the text is actually drawn, it's always in pixels or UI units.

Edge offset and outline

TextLayerStyleUniform::setOutlineWidth() and setOutlineColor() set properties of the outline. For consistentcy with vector drawing elsewhere, the outline is centered on the edge, so e.g. a two-pixel outline would extend one pixel inside the glyph and one pixel outside. With TextLayerStyleUniform::setEdgeOffset() you can adjust the edge position to make the glyphs thicker or thinner, and a combination of these two allows you to adjust whether the outline will grow from the center, outside or inside:

textLayerShared.setStyle(…, {
    Ui::TextLayerStyleUniform{}    /* 0 */
        .setColor(0xdcdcdc_rgbf)
        .setOutlineColor(0x2f83cc_rgbf)
        .setOutlineWidth(1.25f)
        .setEdgeOffset(0.625f),
    Ui::TextLayerStyleUniform{}    /* 1 */
        .setColor(0x2f83cc_rgbf)
        .setEdgeOffset(0.75f)
}, {…}, {…}, {}, {}, {}, {}, {}, {});

…

Ui::NodeHandle edgy = …;
Ui::NodeHandle bulky = …;
textLayer.create(0, "edgy.", {}, edgy);
textLayer.create(1, "bulky?!", {}, bulky);

The range how far an outline together with edge offset can go is clamped to the radius used when constructing the Text::DistanceFieldGlyphCacheArrayGL. From the snippet above, a radius of 20, together with the font being scaled down from 64.0f, means the edge can extend at most five pixels for font16Handle or two and half for font8Handle. If you don't need that much, you can reduce the radius, which also means the glyphs will occupy less space and the distance field processing takes less time.

Similarly as with the smoothness, the outline width and offset doesn't depend on size of the font actually used in given style. Consistently with BaseLayer outline drawing the outline color isn't affected by setColor().

Rendering single glyphs

With createGlyph() you can render a single glyph specified with its ID. This is useful mainly with icon fonts, where you can for example use Text::AbstractFont::glyphForName() at runtime if the font has named glyphs:

textLayer.createGlyph(…, font->glyphForName("coffee"), {}, node);

Or you can maintain an enum with name-to-glyph-ID mapping. Similarly to style IDs, createGlyph() accepts both plain integers and enums for a glyph ID:

enum class IconFont: UnsignedInt {
    …
    Coffee = 2249, /* queried from the font in an offline step */
};

textLayer.createGlyph(…, IconFont::Coffee, {}, node);

It's however also possible to insert your own image data into the glyph cache and reference them with this function. Assuming a list of images imported for example from a set of PNGs, call Text::AbstractGlyphCache::addFont() to add a new font ID, copy the image contents to places in the cache reserved using TextureTools::AtlasLandfill::add(), make the glyph cache aware of the new icons with Text::AbstractGlyphCache::addGlyph(), and at the end upload the updated part of the glyph cache to the GPU texture using Text::AbstractGlyphCache::flushImage().

Containers::Array<Trade::ImageData2D> icons = …; /* or Image, ImageView, etc. */
UnsignedInt iconFontId = textLayerShared.glyphCache().addFont(icons.size());

Containers::Array<Vector3i> offsets{NoInit, icons.size()};
Containers::Optional<Range3Di> flushRange = textLayerShared.glyphCache().atlas()
    .add(stridedArrayView(icons).slice(&Trade::ImageData2D::size), offsets);
CORRADE_INTERNAL_ASSERT(flushRange);
Containers::StridedArrayView3D<Color4ub> dst =
    textLayerShared.glyphCache().image().pixels<Color4ub>();
for(std::size_t i = 0; i != icons.size(); ++i) {
    Containers::StridedArrayView3D<const Color4ub> src = icons[i].pixels<Color4ub>();
    Utility::copy(src, dst.sliceSize(
        {std::size_t(offsets[i].z()),
         std::size_t(offsets[i].y()),
         std::size_t(offsets[i].x())}, src.size()));
    textLayerShared.glyphCache().addGlyph(iconFontId, i, {},
        offsets[i].z(), Range2Di::fromSize(offsets[i].xy(), icons[i].size()));
}

textLayerShared.glyphCache().flushImage(*flushRange);

Finally create a FontHandle for the new set of glyphs using TextLayer::Shared::addInstancelessFont(). Compared to TextLayer::Shared::addFont() it takes a scale instead of size. Assuming the UI size matches the framebuffer size, use 1.0f if you want to draw the icons in their original pixel size. the Text crispness and DPI awareness section below for additional considerations. The font handle can then be referenced from the style or passed directly to createGlyph().

Ui::FontHandle iconFontHandle = textLayerShared.addInstancelessFont(iconFontId, 1.0f);

…

/* Create a glyph from containing icon at offset 3 in the `icons` array above */
textLayer.createGlyph(…, 3, iconFontHandle, …);

See Text::AbstractGlyphCache and TextureTools::AtlasLandfill for detailed information about how the cache and atlas packing works internally. If you use Text::DistanceFieldGlyphCacheArrayGL, you don't need to do anything extra as the distance field conversion will be performed by the flushImage() call on the fly.

Updating text data

Any created text or single glyph can be subsequently updated with setText() and setGlyph(). These functions take the same arguments and behave the same as create() and createGlyph(). Internally there's no distinction between a text and a single glyph, so a text can be safely changed to just a glyph and vice versa.

Arbitrary text and glyph transformation

By constructing the layer with TextLayerFlag::Transformable, the text data can be arbitrarily translated, rotated and scaled, replacing the padding functionality. While this feature works with the regular glyph cache as well, it's mainly intended for use with distance field rendering which ensures the transformation doesn't cause any visual artifacts.

Ui::TextLayerGL& textLayer = ui.setLayerInstance(
    Containers::pointer<Ui::TextLayerGL>(ui.createLayer(), textLayerShared,
                                         Ui::TextLayerFlag::Transformable));

For a more involved example, the following code will draw an analog clock with hands drawn as rotated glyphs. First, the hand is imported from an inline SVG with one of the SVG importer plugins such as the LunaSvgImporter. It'll result in a 32x256 image that's — as documented — in PixelFormat::RGBA8Unorm, but is just black and white:

PluginManager::Manager<Trade::AbstractImporter> importerManager;
Containers::Pointer<Trade::AbstractImporter> importer =
    importerManager.loadAndInstantiate("SvgImporter");
if(!importer || !importer->openData(R"(
<svg version="1.1" viewBox="0 0 32 256" xmlns="http://www.w3.org/2000/svg">
  <rect width="32" height="256"/>
  <path d="m16 0-4 16-12 224 16 16 16-16-12-224z" fill="#fff"/>
</svg>
)"))
    Fatal{} << "Uh oh";

Containers::Optional<Trade::ImageData2D> needle = importer->image2D(0);

Afterwards, similarly to the glyph cache packing code above, the image is added to the glyph cache. Just the red channel is copied because the distance field glyph cache is single-channel, and the Text::AbstractGlyphCache::flushImage() call will process it to a distance field. Then a Ui::FontHandle with this single image as glyph 0 is added, which gets referenced later. The {-16, 16} offset moves the glyph origin to the desired rotation center. The scale passed to TextLayer::Shared::addInstancelessFont() is chosen so the 256-pixel-high input image has the right size for the desired size of the clock in the UI.

Vector3i offset[1];
Containers::Optional<Range3Di> flushRange = textLayer.shared().glyphCache()
    .atlas().add({needle->size()}, offset);
CORRADE_INTERNAL_ASSERT(flushRange);
Containers::StridedArrayView3D<const UnsignedByte> src =
    needle->pixels<Color4ub>().slice(&Color4ub::r); /* just the red channel */
Containers::StridedArrayView3D<UnsignedByte> dst =
    textLayer.shared().glyphCache().image().pixels<UnsignedByte>();
Utility::copy(src, dst.sliceSize(
    {std::size_t(offset->z()),
     std::size_t(offset->y()),
     std::size_t(offset->x())}, src.size()));
textLayer.shared().glyphCache().flushImage(*flushRange);

UnsignedInt needleFontId = textLayer.shared().glyphCache().addFont(1);
textLayer.shared().glyphCache().addGlyph(needleFontId, 0,
    {-16, -16}, offset->z(), Range2Di::fromSize(offset->xy(), needle->size()));
Ui::FontHandle needleFont = textLayer.shared().addInstancelessFont(needleFontId, …);

Finally, assuming style has a regular font associated, 12-, 3-, 6- and 9-hour marks are added using various Text::Alignment values. Two other nodes, added as children in order to make the hands appear above the numbers, with the needleFont glyph 0 from above, then show a time of 10:11. The default hand rotation is at the 12-hour mark, first child is the scaled-down hand showing hours, and second, again above hours, is then minutes:

Ui::NodeHandle clock = …;
textLayer.create(style, "12", Text::Alignment::TopCenter, clock);
textLayer.create(style, "3", Text::Alignment::MiddleRight, clock);
textLayer.create(style, "6", Text::Alignment::BottomCenter, clock);
textLayer.create(style, "9", Text::Alignment::MiddleLeft, clock);

Ui::NodeHandle hours = ui.createNode(clock, {}, ui.nodeSize(clock));
Ui::DataHandle hoursData = textLayer.createGlyph(style, 0, needleFont, hours);
textLayer.rotate(hoursData, 360.0_degf*(10.0f + 11.0f/60.0f)/12.0f);
textLayer.scale(hoursData, 0.75f);

Ui::NodeHandle minutes = ui.createNode(hours, {}, ui.nodeSize(hours));
Ui::DataHandle minutesData = textLayer.createGlyph(style, 0, needleFont, minutes);
textLayer.rotate(minutesData, 360.0_degf*11.0f/60.0f);

Dynamic styles

Like with BaseLayer dynamic styles, the TextLayer::Shared::setStyle() API is meant to be used to supply data for static styles, and dynamic styles, requested with TextLayer::Shared::Configuration::setDynamicStyleCount() and specified via setDynamicStyle(), used for style data that change very often:

Ui::TextLayerGL::Shared textLayerShared{glyphCache,
    Ui::TextLayerGL::Shared::Configuration{…}
        .setDynamicStyleCount(10)
};
Ui::TextLayerGL& textLayer = ui.setLayerInstance(
    Containers::pointer<Ui::TextLayerGL>(ui.createLayer(), textLayerShared));

…

UnsignedInt dynamicStyleId = …; /* anything less than the dynamic style count */
textLayer.setDynamicStyle(dynamicStyleId, …);

Ui::NodeHandle node = …;
textLayer.create(textLayer.shared().styleCount() + dynamicStyleId,
    …, node);

The main use case for dynamic styles is animations, which is for the text layer implemented in the TextLayerStyleAnimator class. Again note that if you intend to directly use dynamic styles along with the animator, you should use allocateDynamicStyle() and recycleDynamicStyle() to prevent the animator from stealing dynamic styles you use elsewhere:

/* Attempt to allocate a dynamic style ID, if available */
Containers::Optional<UnsignedInt> dynamicStyleId = textLayer.allocateDynamicStyle();
if(!dynamicStyleId) {
    …
}

/* Populate it, use */
textLayer.setDynamicStyle(*dynamicStyleId, …);
…

/* Once not used anymore, recycle the ID again */
textLayer.recycleDynamicStyle(*dynamicStyleId);

Style transition based on input events

Like with BaseLayer, it's possible to configure TextLayer to perform automatic style transitions based on input events, such as highlighting on hover or press. See the BaseLayer documentation for style transition for a detailed example, the interfaces are the same between the two.

Editable text

By default, the text layer shapes the input text into glyphs, throwing away the input text and all its properties like language or direction, and remembering just which glyphs to render at which positions. As majority of text in user interfaces is non-editable and often only set, never queried back, there's no need to implicitly store such info.

To make editable text, first a style describing how cursor and selection looks like needs to be configured. As both the cursor and the selection are rectangular shapes, there's a single editing style definition, and then it's specified which of them are used for cursors and which for selection. By default there are no editing styles and their desired count has to be specified via TextLayer::Shared::Configuration::setEditingStyleCount(), in this example we'll have just two, used by three regular styles:

Ui::TextLayerGL::Shared textLayerShared{glyphCache,
    Ui::TextLayer::Shared::Configuration{3}
        .setEditingStyleCount(2)
};

Style data is then supplied with TextLayer::Shared::setEditingStyle(). Similarly to regular styles, there can be multiple editing styles, and they consist of a TextLayerCommonEditingStyleUniform, containing properties common to all editing styles, an array of TextLayerEditingStyleUniform, matching the style count specified in the configuration. Default-constructed instances will result in white rectangles, you can then use method chaining to update only the properties you're interested in. Finally, there is a list of padding values, which define how far from the actual glyph bounds the selection or cursor expands. In case of cursors in particular, with no padding specified they'd have a zero width and thus be invisible. The following snippet defines an azure style 0 for a cursor, expanding one UI unit on each side from the cursor position, and a blue selection style 1, tightly wrapping the glyph rectangle:

textLayerShared.setEditingStyle(Ui::TextLayerCommonEditingStyleUniform{}, {
    Ui::TextLayerEditingStyleUniform{}  /* 0 */
        .setBackgroundColor(0xa5c9ea_rgbf),
    Ui::TextLayerEditingStyleUniform{}  /* 1 */
        .setBackgroundColor(0x2f83cc_rgbf),
}, {}, {
    /* Begin, top, end, bottom */
    {1.0f, 0.0f, 1.0f, 0.0f},           /* 0 */
    {}                                  /* 1 */
});

After that, the editing styles need to be referenced from the regular styles. This is done with the eighth and ninth argument to TextLayer::Shared::setStyle(), which are are cursor and selection style indices, respectively, or -1 if given style shouldn't have a cursor / selection style assigned. If either of those arguments is left empty, it's the same as if it'd have -1 for all styles. Here style 0 is a regular non-editing style, 1 is a style with both a cursor and selection style, and 2 has just a selection, for example if a certain label is meant to be just selectable but not directly editable:

textLayerShared.setStyle(…, {
    Ui::TextLayerStyleUniform{} /* 0 */
        …,
    Ui::TextLayerStyleUniform{} /* 1 */
        …,
    Ui::TextLayerStyleUniform{} /* 2 */
        …,
}, {…}, {…}, {}, {}, {}, {
    -1, /* Style 0 uses no cursor style */
    0,  /* Style 1 uses editing style 0 for cursor */
    -1  /* Style 2 uses no cursor style */
}, {
    -1, /* Style 0 uses no selection style */
    1,  /* Style 1 uses editing style 1 for selection */
    1   /* Style 2 uses editing style 1 for selection */
}, {});

With the editing style set up, an editable text can be made by passing TextDataFlag::Editable to either create() or setText() Initially it will have no selection and the cursor at the end, you can then use setCursor() to specify the byte position where the cursor and selection should be:

Ui::NodeHandle node = …;
Ui::DataHandle text = textLayer.create(…, "Hello world!", {},
    Ui::TextDataFlag::Editable, node);
textLayer.setCursor(text, 7, 4); /* Selecting "o w" with cursor at byte 7 */

Contents of an editable text are then subsequently queryable with text(). The updateText() function can perform incremental updates in addition to cursor movement and the editText() API is for higher-level operations with UTF-8 and text directionality awareness. This function is also what is called on actual key and text input events, described in Reacting to focus, pointer and keyboard input events below.

Cursor and selection color, selection text style

Apart from the selection / cursor rectangle color, set with TextLayerEditingStyleUniform::setBackgroundColor(), it's possible to override style of the text under selection using the third argument to TextLayer::Shared::setEditingStyle(). Compared to above, the following snippet adds a style number 3, which is then referenced from the selection editing style, and which makes the selected text darker:

textLayerShared.setStyle(…, {
    Ui::TextLayerStyleUniform{} /* 0 */
        …,
    Ui::TextLayerStyleUniform{} /* 1 */
        …,
    Ui::TextLayerStyleUniform{} /* 2 */
        …,
    Ui::TextLayerStyleUniform{} /* 3 */
        .setColor(0x2f363f_rgbf),
}, …);

textLayerShared.setEditingStyle(…, {…}, {
    -1, /* (Cursor) style 0 doesn't override any style for text selection */
    3   /* (Selection) style 1 uses style 3 for text selection */
}, {…});

Note that only the TextLayerCommonStyleUniform is used from the style override, not font, alignment or other properties.

Cursor and selection rectangle padding

Padding used in the snippets above was only horizontal, but vertical padding can be used for example to achieve better optical alignment of both the text itself and the selection rectangle inside an edit box, or to make a cursor stand out more. Horizontal padding also doesn't necessarily have to be symmetrical. For the cursor it's often desirable to have it shifted towards the typing direction. Here it's still two units wide, but is shifted to the right for Text::ShapeDirection::LeftToRight text, and to the left for RightToLeft text:

textLayerShared.setEditingStyle(…, {…}, {}, {
    /* Begin, top, end, bottom */
    {0.0f, 0.0f, 2.0f, 0.0f},          /* (Cursor) style 0 */
    {1.0f, -1.0f, 1.0f, -1.0f}         /* (Selection) style 1 */
});

Rounded corners and edge smoothness

TextLayerEditingStyleUniform::setCornerRadius() allows you to make the cursor and selection rectangle corners rounded. The edges are aliased by default, use TextLayerCommonEditingStyleUniform::setSmoothness() to smoothen them out. The radius is in framebuffer pixels, same as with BaseLayer edge smoothness.

textLayerShared.setEditingStyle(…, {
    Ui::TextLayerEditingStyleUniform{}  /* (Cursor) style 0 */
        .setBackgroundColor(0xa5c9ea_rgbf)
        .setCornerRadius(1.0f),
    Ui::TextLayerEditingStyleUniform{}  /* (Selection) style 1 */
        .setBackgroundColor(0x2f83cc_rgbf)
        .setCornerRadius(2.0f),
}, {…}, {…});

Ui::NodeHandle node = ui.createNode(…, Ui::NodeFlag::Focusable);
Ui::DataHandle text = textLayer.create(…, Ui::TextDataFlag::Editable, node);

Ui::NodeHandle keyboard = ui.createNode(…, Ui::NodeFlag::NoBlur);

Ui::NodeHandle keyQ = ui.createNode(keyboard, …);
eventLayer.onPress(keyQ, [&ui]{
    Ui::TextInputEvent event{{}, "q"};
    ui.textInputEvent(event);
});
Ui::NodeHandle keyW = ui.createNode(keyboard, …);
eventLayer.onPress(keyW, [&ui]{
    Ui::TextInputEvent event{{}, "w"};
    ui.textInputEvent(event);
});
…
Ui::NodeHandle keyBackspace = ui.createNode(keyboard, …);
eventLayer.onPress(keyBackspace, [&ui]{
    Ui::KeyEvent event{{}, Ui::Key::Backspace, {}};
    ui.keyPressEvent(event);
});
…

Base classes

class AbstractVisualLayer new in Git master

Base for visual data layers.

Derived classes

class TextLayerGL new in Git master

OpenGL implementation of the text layer.

Public types

class Shared

Shared state for the text layer.

Public functions

auto shared() -> Shared&

Shared state used by this layer.

auto shared() const -> const Shared&

auto flags() const -> TextLayerFlags

Layer flags.

auto assignAnimator(TextLayerStyleAnimator& animator) -> TextLayer&

Assign a style animator to this layer.

auto defaultStyleAnimator() const -> TextLayerStyleAnimator*

Default style animator for this layer.

auto setDefaultStyleAnimator(TextLayerStyleAnimator* animator) -> TextLayer&

Set a default style animator for this layer.

auto dynamicStyleUniforms() const -> Containers::ArrayView<const TextLayerStyleUniform>

Dynamic style uniforms.

auto dynamicStyleFonts() const -> Containers::StridedArrayView1D<const FontHandle>

Dynamic style fonts.

auto dynamicStyleAlignments() const -> Containers::StridedArrayView1D<const Text::Alignment>

Dynamic style alignments.

auto dynamicStyleFeatures(UnsignedInt id) const -> Containers::ArrayView<const TextFeatureValue>

Dynamic style font features.

auto dynamicStyleCursorStyles() const -> Containers::BitArrayView

Which dynamic style have associated cursor styles.

auto dynamicStyleCursorStyle(UnsignedInt id) const -> Int

Dynamic style cursor style ID.

auto dynamicStyleSelectionStyles() const -> Containers::BitArrayView

Which dynamic style have associated selection styles.

auto dynamicStyleSelectionStyle(UnsignedInt id) const -> Int

Dynamic style selection style ID.

auto dynamicStyleSelectionStyleTextUniform(UnsignedInt) const -> Int

Dynamic style selection style text uniform IDs.

auto dynamicStylePaddings() const -> Containers::StridedArrayView1D<const Vector4>

Dynamic style paddings.

auto dynamicEditingStyleUniforms() const -> Containers::ArrayView<const TextLayerEditingStyleUniform>

Dynamic editing style uniforms.

auto dynamicEditingStylePaddings() const -> Containers::StridedArrayView1D<const Vector4>

Dynamic editing style paddings.

void setDynamicStyle(UnsignedInt id, const TextLayerStyleUniform& uniform, FontHandle font, Text::Alignment alignment, Containers::ArrayView<const TextFeatureValue> features, const Vector4& padding)

Set a dynamic style for text only.

void setDynamicStyle(UnsignedInt id, const TextLayerStyleUniform& uniform, FontHandle font, Text::Alignment alignment, std::initializer_list<TextFeatureValue> features, const Vector4& padding)

void setDynamicStyleWithCursorSelection(UnsignedInt id, const TextLayerStyleUniform& uniform, FontHandle font, Text::Alignment alignment, Containers::ArrayView<const TextFeatureValue> features, const Vector4& padding, const TextLayerEditingStyleUniform& cursorUniform, const Vector4& cursorPadding, const TextLayerEditingStyleUniform& selectionUniform, const Containers::Optional<TextLayerStyleUniform>& selectionTextUniform, const Vector4& selectionPadding)

Set a dynamic style for text, cursor and selection.

void setDynamicStyleWithCursorSelection(UnsignedInt id, const TextLayerStyleUniform& uniform, FontHandle font, Text::Alignment alignment, std::initializer_list<TextFeatureValue> features, const Vector4& padding, const TextLayerEditingStyleUniform& cursorUniform, const Vector4& cursorPadding, const TextLayerEditingStyleUniform& selectionUniform, const Containers::Optional<TextLayerStyleUniform>& selectionTextUniform, const Vector4& selectionPadding)

void setDynamicStyleWithCursor(UnsignedInt id, const TextLayerStyleUniform& uniform, FontHandle font, Text::Alignment alignment, Containers::ArrayView<const TextFeatureValue> features, const Vector4& padding, const TextLayerEditingStyleUniform& cursorUniform, const Vector4& cursorPadding)

Set a dynamic style for text and cursor only.

void setDynamicStyleWithCursor(UnsignedInt id, const TextLayerStyleUniform& uniform, FontHandle font, Text::Alignment alignment, std::initializer_list<TextFeatureValue> features, const Vector4& padding, const TextLayerEditingStyleUniform& cursorUniform, const Vector4& cursorPadding)

void setDynamicStyleWithSelection(UnsignedInt id, const TextLayerStyleUniform& uniform, FontHandle font, Text::Alignment alignment, Containers::ArrayView<const TextFeatureValue> features, const Vector4& padding, const TextLayerEditingStyleUniform& selectionUniform, const Containers::Optional<TextLayerStyleUniform>& selectionTextUniform, const Vector4& selectionPadding)

Set a dynamic style for text and selection only.

void setDynamicStyleWithSelection(UnsignedInt id, const TextLayerStyleUniform& uniform, FontHandle font, Text::Alignment alignment, std::initializer_list<TextFeatureValue> features, const Vector4& padding, const TextLayerEditingStyleUniform& selectionUniform, const Containers::Optional<TextLayerStyleUniform>& selectionTextUniform, const Vector4& selectionPadding)

auto create(UnsignedInt style, Containers::StringView text, const TextProperties& properties, TextDataFlags flags = {}, NodeHandle node = NodeHandle::Null) -> DataHandle

Create a text.

auto create(UnsignedInt style, Containers::StringView text, const TextProperties& properties, NodeHandle node) -> DataHandle

template<class StyleIndex>

auto create(StyleIndex style, Containers::StringView text, const TextProperties& properties, TextDataFlags flags = {}, NodeHandle node = NodeHandle::Null) -> DataHandle

Create a text with a style index in a concrete enum type.

template<class StyleIndex>

auto create(StyleIndex style, Containers::StringView text, const TextProperties& properties, NodeHandle node) -> DataHandle

auto createGlyph(UnsignedInt style, UnsignedInt glyph, const TextProperties& properties, NodeHandle node = NodeHandle::Null) -> DataHandle

Create a single glyph.

template<class StyleIndex>

auto createGlyph(StyleIndex style, UnsignedInt glyph, const TextProperties& properties, NodeHandle node = NodeHandle::Null) -> DataHandle

Create a single glyph with a style index in a concrete enum type.

template<class GlyphIndex>

auto createGlyph(UnsignedInt style, GlyphIndex glyph, const TextProperties& properties, NodeHandle node = NodeHandle::Null) -> DataHandle

Create a single glyph with a glyph ID in a concrete enum type.

template<class StyleIndex, class GlyphIndex>

auto createGlyph(StyleIndex style, GlyphIndex glyph, const TextProperties& properties, NodeHandle node = NodeHandle::Null) -> DataHandle

Create a single glyph with a style index and glyph ID in a concrete enum type.

void remove(DataHandle handle)

Remove a text.

void remove(LayerDataHandle handle)

Remove a text assuming it belongs to this layer.

auto flags(DataHandle handle) const -> TextDataFlags

Text flags.

auto flags(LayerDataHandle handle) const -> TextDataFlags

Text flags assuming it belongs to this layer.

auto glyphCount(DataHandle handle) const -> UnsignedInt

Text glyph count.

auto glyphCount(LayerDataHandle handle) const -> UnsignedInt

Text glyph count assuming it belongs to this layer.

auto size(DataHandle handle) const -> Vector2

Size of the laid out text.

auto size(LayerDataHandle handle) const -> Vector2

Size of the laid out text assuming it belongs to this layer.

auto cursor(DataHandle handle) const -> Containers::Pair<UnsignedInt, UnsignedInt>

Cursor and selection position in an editable text.

auto cursor(LayerDataHandle handle) const -> Containers::Pair<UnsignedInt, UnsignedInt>

Cursor and selection position in an editable text assuming it belongs to this layer.

void setCursor(DataHandle handle, UnsignedInt position, UnsignedInt selection)

Set cursor position and selection in an editable text.

void setCursor(DataHandle handle, UnsignedInt position)

Set cursor position in an editable text.

void setCursor(LayerDataHandle handle, UnsignedInt position, UnsignedInt selection)

Set cursor position and selection in an editable text assuming it belongs to this layer.

void setCursor(LayerDataHandle handle, UnsignedInt position)

Set cursor position in an editable text assuming it belongs to this layer.

auto textProperties(DataHandle handle) const -> TextProperties

Properties used for shaping an editable text.

auto textProperties(LayerDataHandle handle) const -> TextProperties

Properties used for shaping an editable text assuming it belongs to this layer.

auto text(DataHandle handle) const -> Containers::StringView

Contents of an editable text.

auto text(LayerDataHandle handle) const -> Containers::StringView

Contents of an editable text assuming it belongs to this layer.

void setText(DataHandle handle, Containers::StringView text, const TextProperties& properties)

Set text.

void setText(DataHandle handle, Containers::StringView text, const TextProperties& properties, TextDataFlags flags)

Set text with different flags.

void setText(LayerDataHandle handle, Containers::StringView text, const TextProperties& properties)

Set text assuming it belongs to this layer.

void setText(LayerDataHandle handle, Containers::StringView text, const TextProperties& properties, TextDataFlags flags)

Set text with different flags assuming it belongs to this layer.

void updateText(DataHandle handle, UnsignedInt removeOffset, UnsignedInt removeSize, UnsignedInt insertOffset, Containers::StringView insertText, UnsignedInt cursor, UnsignedInt selection)

Update text, cursor position and selection in an editable text.

void updateText(DataHandle handle, UnsignedInt removeOffset, UnsignedInt removeSize, UnsignedInt insertOffset, Containers::StringView insertText, UnsignedInt cursor)

Update text and cursor position in an editable text.

void updateText(LayerDataHandle handle, UnsignedInt removeOffset, UnsignedInt removeSize, UnsignedInt insertOffset, Containers::StringView insertText, UnsignedInt cursor, UnsignedInt selection)

Update text, cursor position and selection in an editable text assuming it belongs to this layer.

void updateText(LayerDataHandle handle, UnsignedInt removeOffset, UnsignedInt removeSize, UnsignedInt insertOffset, Containers::StringView insertText, UnsignedInt cursor)

Update text and cursor position in an editable text.

void editText(DataHandle handle, TextEdit edit, Containers::StringView insert)

Edit text at current cursor position.

void editText(LayerDataHandle handle, TextEdit edit, Containers::StringView insert)

Edit text at current cursor position assuming it belongs to this layer.

void setGlyph(DataHandle handle, UnsignedInt glyph, const TextProperties& properties)

Set a single glyph.

template<class GlyphIndex>

void setGlyph(DataHandle handle, GlyphIndex glyph, const TextProperties& properties)

Set a single glyph with a glyph ID in a concrete enum type.

void setGlyph(LayerDataHandle handle, UnsignedInt glyph, const TextProperties& properties)

Set a single glyph assuming it belongs to this layer.

template<class GlyphIndex>

void setGlyph(LayerDataHandle handle, GlyphIndex glyph, const TextProperties& properties)

Set a single glyph with a glyph ID in a concrete enum type assuming it belongs to this layer.

auto color(DataHandle handle) const -> Color4

Custom text base color.

auto color(LayerDataHandle handle) const -> Color4

Custom text base color assuming it belongs to this layer.

void setColor(DataHandle handle, const Color4& color)

Set custom text base color.

void setColor(LayerDataHandle handle, const Color4& color)

Set custom text base color assuming it belongs to this layer.

auto padding(DataHandle handle) const -> Vector4

Custom text padding.

auto padding(LayerDataHandle handle) const -> Vector4

Custom text padding assuming it belongs to this layer.

void setPadding(DataHandle handle, const Vector4& padding)

Set custom text padding.

void setPadding(LayerDataHandle handle, const Vector4& padding)

Set custom text padding assuming it belongs to this layer.

void setPadding(DataHandle handle, Float padding)

Set custom text padding with all edges having the same value.

void setPadding(LayerDataHandle handle, Float padding)

Set custom text padding with all edges having the same value assuming it belongs to this layer.

auto transformation(DataHandle handle) const -> Containers::Pair<Vector2, Complex>

Custom text transformation.

auto transformation(LayerDataHandle handle) const -> Containers::Pair<Vector2, Complex>

Custom text transformation.

void setTransformation(DataHandle handle, const Vector2& translation, const Complex& rotation, Float scaling)

Set custom text transformation.

void setTransformation(LayerDataHandle handle, const Vector2& translation, const Complex& rotation, Float scaling)

Set custom text transformation.

void setTransformation(DataHandle handle, const Vector2& translation, Rad rotation, Float scaling)

Set custom text transformation.

void setTransformation(LayerDataHandle handle, const Vector2& translation, Rad rotation, Float scaling)

Set custom text transformation.

void translate(DataHandle handle, const Vector2& translation)

Add to custom text translation.

void translate(LayerDataHandle handle, const Vector2& translation)

Add to custom text translation.

void rotate(DataHandle handle, const Complex& rotation)

Add to custom text rotation.

void rotate(LayerDataHandle handle, const Complex& rotation)

Add to custom text rotation.

void rotate(DataHandle handle, Rad rotation)

Add to custom text rotation.

void rotate(LayerDataHandle handle, Rad rotation)

Add to custom text rotation.

void scale(DataHandle handle, Float scaling)

Update custom text scaling.

void scale(LayerDataHandle handle, Float scaling)

Update custom text scaling.

Function documentation