Magnum::Ui::TextLayer class new in Git master
#include <Magnum/Ui/TextLayer.h>

Text layer.

Draws text laid out using the Text library. You'll most likely instantiate the class through TextLayerGL, which contains a concrete OpenGL implementation.

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 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
Text custom base color.
auto color(LayerDataHandle handle) const -> Color4
Text custom base color assuming it belongs to this layer.
void setColor(DataHandle handle, const Color4& color)
Set text custom base color.
void setColor(LayerDataHandle handle, const Color4& color)
Set text custom base color assuming it belongs to this layer.
auto padding(DataHandle handle) const -> Vector4
Text custom padding.
auto padding(LayerDataHandle handle) const -> Vector4
Text custom padding assuming it belongs to this layer.
void setPadding(DataHandle handle, const Vector4& padding)
Set text custom padding.
void setPadding(LayerDataHandle handle, const Vector4& padding)
Set text custom padding assuming it belongs to this layer.
void setPadding(DataHandle handle, Float padding)
Set text custom padding with all edges having the same value.
void setPadding(LayerDataHandle handle, Float padding)
Set text custom padding with all edges having the same value assuming it belongs to this layer.

Function documentation

Shared& Magnum::Ui::TextLayer::shared()

Shared state used by this layer.

Reference to the instance passed to TextLayerGL::TextLayerGL(LayerHandle, Shared&).

const Shared& Magnum::Ui::TextLayer::shared() const

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

TextLayer& Magnum::Ui::TextLayer::assignAnimator(TextLayerStyleAnimator& animator)

Assign a style animator to this layer.

Returns Reference to self (for method chaining)

Expects that Shared::dynamicStyleCount() is non-zero and that given animator wasn't passed to assignAnimator() on any layer yet. On the other hand, it's possible to associate multiple different animators with the same layer.

TextLayerStyleAnimator* Magnum::Ui::TextLayer::defaultStyleAnimator() const

Default style animator for this layer.

If a style animator haven't been set, returns nullptr. If not nullptr, the returned animator is guaranteed to be assigned to this layer, i.e. that BaseLayerStyleAnimator::layer() is equal to handle().

TextLayer& Magnum::Ui::TextLayer::setDefaultStyleAnimator(TextLayerStyleAnimator* animator)

Set a default style animator for this layer.

Returns Reference to self (for method chaining)

Makes animator used in style transitions in response to events. Expects that animator is either nullptr or is already assigned to this layer, i.e. that assignAnimator() was called on this layer with animator before. Calling this function again with a different animator or with nullptr replaces the previous one.

Containers::ArrayView<const TextLayerStyleUniform> Magnum::Ui::TextLayer::dynamicStyleUniforms() const

Dynamic style uniforms.

Size of the returned view is at least Shared::dynamicStyleCount(). These uniforms are used by style indices greater than or equal to Shared::styleCount(). If Shared::hasEditingStyles() is true, size of the returned view is three times Shared::dynamicStyleCount() and the extra elements are referenced by dynamicStyleSelectionStyleTextUniform(UnsignedInt) const.

Int Magnum::Ui::TextLayer::dynamicStyleSelectionStyle(UnsignedInt id) const

Dynamic style selection style ID.

Expects that the id is less than Shared::dynamicStyleCount(). If given dynamic style has no associated selection style, returns -1, otherwise the returned index is a constant calculated from id and points to the dynamicEditingStyleUniforms() and dynamicEditingStylePaddings() arrays. Use dynamicStyleSelectionStyleTextUniform(UnsignedInt) const to retrieve ID of the uniform override applied to selected text.

Int Magnum::Ui::TextLayer::dynamicStyleSelectionStyleTextUniform(UnsignedInt) const

Dynamic style selection style text uniform IDs.

Expects that the id is less than Shared::dynamicStyleCount(). If given dynamic style has no associated selection style, returns -1, otherwise the returned index is a constant calculated based on id and points to the dynamicStyleUniforms() array.

In particular, contrary to the styles specified with Shared::setEditingStyle(), even if a text uniform wasn't passed in setDynamicStyleWithCursorSelection() or setDynamicStyleWithSelection(), the ID still points to a valid uniform index – the uniform data are instead copied over from the base style.

void Magnum::Ui::TextLayer::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.

Parameters
id Dynamic style ID
uniform Style uniform
font Font handle
alignment Alignment
features Font features to use
padding Padding inside the node in order left, top, right, bottom

Expects that the id is less than Shared::dynamicStyleCount(), font is either FontHandle::Null or valid and alignment is not *GlyphBounds as the implementation can only align based on font metrics and cursor position, not actual glyph bounds. Shared::styleCount() plus id is then a style index that can be passed to create(), createGlyph() or setStyle() in order to use this style. Compared to Shared::setStyle() the mapping between dynamic styles and uniforms is implicit. All dynamic styles are initially default-constructed TextLayerStyleUniform instances, FontHandle::Null, Text::Alignment::MiddleCenter with empty feature lists, zero padding vectors and no associated cursor or selection styles.

Calling this function causes LayerState::NeedsCommonDataUpdate to be set to trigger an upload of changed dynamic style uniform data. If padding changed, LayerState::NeedsDataUpdate gets set as well. On the other hand, changing the font, alignment or features doesn't cause LayerState::NeedsDataUpdate to be set — the font, alignment and features get only used in the following call to create(), createGlyph(), setText() or setGlyph().

This function doesn't set any cursor or selection style, meaning they won't be shown at all if using this style for a TextDataFlag::Editable text. Use setDynamicStyleWithCursorSelection(), setDynamicStyleWithCursor() or setDynamicStyleWithSelection() to specify those as well.

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

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

void Magnum::Ui::TextLayer::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.

Parameters
id Dynamic style ID
uniform Style uniform
font Font handle
alignment Alignment
features Font features to use
padding Padding inside the node in order left, top, right, bottom
cursorUniform Style uniform for the editing cursor
cursorPadding Padding around the editing cursor in order left, top, right, bottom
selectionUniform Style uniform for the editing selection
selectionTextUniform Style uniform applied to selected portions of the text or Containers::NullOpt if uniform should be used for the selection as well
selectionPadding Padding around the editing selection in order left, top, right, bottom

Expects that the id is less than Shared::dynamicStyleCount(), Shared::hasEditingStyles() is true, font is either FontHandle::Null or valid and alignment is not *GlyphBounds as the implementation can only align based on font metrics and cursor position, not actual glyph bounds. Shared::styleCount() plus id is then a style index that can be passed to create(), createGlyph() or setStyle() in order to use this style. Compared to Shared::setStyle() the mapping between dynamic styles and uniforms is implicit. All dynamic styles are initially default-constructed TextLayerStyleUniform instances, FontHandle::Null, Text::Alignment::MiddleCenter with empty feature lists, zero padding vectors and no associated cursor or selection styles.

Calling this function causes LayerState::NeedsCommonDataUpdate to be set to trigger an upload of changed dynamic style uniform data. If padding, cursorPadding or selectionPadding changed, LayerState::NeedsDataUpdate gets set as well. On the other hand, changing the font, alignment or features doesn't cause any state flag to be set — the font, alignment and features get only used in the following call to create(), createGlyph(), setText() or setGlyph().

Note that while selectionPadding is merely a way to visually fine-tune the appearance, cursorPadding has to be non-zero horizontally to actually be visible at all.

Use setDynamicStyleWithCursor() if showing selection is not desirable for given style, setDynamicStyleWithSelection() if showing cursor is not desirable and setDynamicStyle() for non-editable styles or editable styles where showing neither cursor nor selection is desirable, for example in widgets that aren't focused.

void Magnum::Ui::TextLayer::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)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

void Magnum::Ui::TextLayer::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.

Parameters
id Dynamic style ID
uniform Style uniform
font Font handle
alignment Alignment
features Font features to use
padding Padding inside the node in order left, top, right, bottom
cursorUniform Style uniform for the editing cursor
cursorPadding Padding around the editing cursor in order left, top, right, bottom

Compared to setDynamicStyleWithCursorSelection(UnsignedInt, const TextLayerStyleUniform&, FontHandle, Text::Alignment, Containers::ArrayView<const TextFeatureValue>, const Vector4&, const TextLayerEditingStyleUniform&, const Vector4&, const TextLayerEditingStyleUniform&, const Containers::Optional<TextLayerStyleUniform>&, const Vector4&) this doesn't set any selection style, meaning a TextDataFlag::Editable text will be rendered without the selection visible. Useful for example for dynamic styles of input widgets which show the cursor always but selection only when focused.

void Magnum::Ui::TextLayer::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)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

void Magnum::Ui::TextLayer::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.

Parameters
id Dynamic style ID
uniform Style uniform
font Font handle
alignment Alignment
features Font features to use
padding Padding inside the node in order left, top, right, bottom
selectionUniform Style uniform for the editing selection
selectionTextUniform Style uniform applied to selected portions of the text or Containers::NullOpt if uniform should be used for the selection as well
selectionPadding Padding around the editing selection in order left, top, right, bottom

Compared to setDynamicStyleWithCursorSelection(UnsignedInt, const TextLayerStyleUniform&, FontHandle, Text::Alignment, Containers::ArrayView<const TextFeatureValue>, const Vector4&, const TextLayerEditingStyleUniform&, const Vector4&, const TextLayerEditingStyleUniform&, const Containers::Optional<TextLayerStyleUniform>&, const Vector4&) this doesn't set any cursor style, meaning a TextDataFlag::Editable text will be rendered without the cursor visible. Useful for example for dynamic styles of input widgets which show the selection always but cursor only when focused.

void Magnum::Ui::TextLayer::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)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

DataHandle Magnum::Ui::TextLayer::create(UnsignedInt style, Containers::StringView text, const TextProperties& properties, TextDataFlags flags = {}, NodeHandle node = NodeHandle::Null)

Create a text.

Parameters
style Style index
text Text to render
properties Text properties
flags Flags
node Node to attach to
Returns New data handle

Expects that Shared::setStyle() has been called, style is less than Shared::totalStyleCount() and TextProperties::font() is either FontHandle::Null or valid. Styling is driven from the TextLayerStyleUniform at index style. If TextProperties::font() is not null it's used, otherwise the default FontHandle assigned to given style is used and is expected to not be null. The FontHandle, whether coming from the style or from properties, is expected to have a font instance. Instance-less fonts can be only used to create single glyphs (such as various icons or images) with createGlyph().

If flags contain TextDataFlag::Editable, the text and properties are remembered and subsequently accessible through text() and textProperties(), cursor() position and selection are both set to text size. Currently, for editable text, the properties are expected to have empty TextProperties::features() — only the features supplied by the style are used for editable text.

DataHandle Magnum::Ui::TextLayer::create(UnsignedInt style, Containers::StringView text, const TextProperties& properties, NodeHandle node)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

template<class StyleIndex>
DataHandle Magnum::Ui::TextLayer::create(StyleIndex style, Containers::StringView text, const TextProperties& properties, TextDataFlags flags = {}, NodeHandle node = NodeHandle::Null)

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

Casts style to UnsignedInt and delegates to create(UnsignedInt, Containers::StringView, const TextProperties&, TextDataFlags, NodeHandle).

template<class StyleIndex>
DataHandle Magnum::Ui::TextLayer::create(StyleIndex style, Containers::StringView text, const TextProperties& properties, NodeHandle node)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

DataHandle Magnum::Ui::TextLayer::createGlyph(UnsignedInt style, UnsignedInt glyph, const TextProperties& properties, NodeHandle node = NodeHandle::Null)

Create a single glyph.

Parameters
style Style index
glyph Glyph ID to render
properties Text properties
node Node to attach to
Returns New data handle

Expects that Shared::setStyle() has been called, style is less than Shared::totalStyleCount() and TextProperties::font() is either FontHandle::Null or valid. Styling is driven from the TextLayerStyleUniform at index style. If TextProperties::font() is not null it's used, otherwise the default FontHandle assigned to given style is used and is expected to not be null. The glyph is expected to be less than Text::AbstractGlyphCache::fontGlyphCount() for given font.

Compared to create(), the glyph is aligned according to TextProperties::alignment() based on its bounding rectangle coming from the glyph cache, not based on font metrics. If the Text::Alignment is *Start or *End, it's converted to an appropriate *Left or *Right value based on TextProperties::layoutDirection() and shapeDirection(). The TextProperties::script(), language() and features() properties aren't used in any way.

template<class StyleIndex>
DataHandle Magnum::Ui::TextLayer::createGlyph(StyleIndex style, UnsignedInt glyph, const TextProperties& properties, NodeHandle node = NodeHandle::Null)

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

Casts style to UnsignedInt and delegates to createGlyph(UnsignedInt, UnsignedInt, const TextProperties&, NodeHandle).

template<class GlyphIndex>
DataHandle Magnum::Ui::TextLayer::createGlyph(UnsignedInt style, GlyphIndex glyph, const TextProperties& properties, NodeHandle node = NodeHandle::Null)

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

Casts glyph to UnsignedInt and delegates to createGlyph(UnsignedInt, UnsignedInt, const TextProperties&, NodeHandle).

template<class StyleIndex, class GlyphIndex>
DataHandle Magnum::Ui::TextLayer::createGlyph(StyleIndex style, GlyphIndex glyph, const TextProperties& properties, NodeHandle node = NodeHandle::Null)

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

Casts style and glyph to UnsignedInt and delegates to createGlyph(UnsignedInt, UnsignedInt, const TextProperties&, NodeHandle).

void Magnum::Ui::TextLayer::remove(DataHandle handle)

Remove a text.

Delegates to AbstractLayer::remove(DataHandle) and additionally marks the now-unused glyph run for removal in the next update().

void Magnum::Ui::TextLayer::remove(LayerDataHandle handle)

Remove a text assuming it belongs to this layer.

Delegates to AbstractLayer::remove(LayerDataHandle) and additionally marks the now-unused glyph run for removal in the next update().

TextDataFlags Magnum::Ui::TextLayer::flags(DataHandle handle) const

Text flags.

Expects that handle is valid. Note that, to avoid implementation complexity, the flags can be only specified in create() or setText(DataHandle, Containers::StringView, const TextProperties&, TextDataFlags) and cannot be modified independently. Data created with createGlyph() or updated with setGlyph() have the flags always empty.

TextDataFlags Magnum::Ui::TextLayer::flags(LayerDataHandle handle) const

Text flags assuming it belongs to this layer.

Like flags(DataHandle) const but without checking that handle indeed belongs to this layer. See its documentation for more information.

UnsignedInt Magnum::Ui::TextLayer::glyphCount(DataHandle handle) const

Text glyph count.

Expects that handle is valid.

UnsignedInt Magnum::Ui::TextLayer::glyphCount(LayerDataHandle handle) const

Text glyph count assuming it belongs to this layer.

Expects that handle is valid.

Vector2 Magnum::Ui::TextLayer::size(DataHandle handle) const

Size of the laid out text.

Expects that handle is valid. For text laid out with create() or setText() the size is derived from ascent, descent and advances of individual glyphs, not from actual area of the glyphs being drawn, as that may not be known at that time. For createGlyph() or setGlyph() the size is based on the actual glyph size coming out of the glyph cache.

Vector2 Magnum::Ui::TextLayer::size(LayerDataHandle handle) const

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

Like size(DataHandle) const but without checking that handle indeed belongs to this layer. See its documentation for more information.

Containers::Pair<UnsignedInt, UnsignedInt> Magnum::Ui::TextLayer::cursor(DataHandle handle) const

Cursor and selection position in an editable text.

Expects that handle is valid and the text was created or set with TextDataFlag::Editable present. Both values are guaranteed to be always within bounds of a corresponding text(DataHandle) const. The first value is cursor position, the second value denotes the other end of the selection. If both are the same, there's no selection.

Containers::Pair<UnsignedInt, UnsignedInt> Magnum::Ui::TextLayer::cursor(LayerDataHandle handle) const

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

Like cursor(DataHandle) const but without checking that handle indeed belongs to this layer. See its documentation for more information.

void Magnum::Ui::TextLayer::setCursor(DataHandle handle, UnsignedInt position, UnsignedInt selection)

Set cursor position and selection in an editable text.

Low-level interface for cursor positioning. See updateText() for a low-level interface to perform text modifications together with cursor positioning, use editText() to perform higher-level operations with UTF-8 and text directionality awareness.

Expects that handle is valid and the text was created or set with TextDataFlag::Editable enabled. Both the position and selection is expected to be less or equal to text() size. The distance between the two is what's selected — if selection is less than position, the selection is before the cursor, if position is less than selection, the selection is after the cursor. If they're the same, there's no selection. No UTF-8 sequence boundary adjustment is done for either of the two, i.e. it's possible to move the cursor or selection inside a multi-byte UTF-8 sequence.

Calling this function causes LayerState::NeedsDataUpdate to be set, unless the operation performed is a no-op, which is when both removeSize and insertText size are both 0 and cursor is equal to cursor().

void Magnum::Ui::TextLayer::setCursor(DataHandle handle, UnsignedInt position)

Set cursor position in an editable text.

Same as calling setCursor(DataHandle, UnsignedInt, UnsignedInt) with position passed to both position and selection, i.e. with nothing selected.

void Magnum::Ui::TextLayer::setCursor(LayerDataHandle handle, UnsignedInt position, UnsignedInt selection)

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

Like setCursor(DataHandle, UnsignedInt, UnsignedInt) but without checking that handle indeed belongs to this layer. See its documentation for more information.

void Magnum::Ui::TextLayer::setCursor(LayerDataHandle handle, UnsignedInt position)

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

Same as calling setCursor(LayerDataHandle, UnsignedInt, UnsignedInt) with position passed to both position and selection, i.e. with nothing selected.

TextProperties Magnum::Ui::TextLayer::textProperties(DataHandle handle) const

Properties used for shaping an editable text.

Expects that handle is valid and the text was created with TextDataFlag::Editable set. Returns content of TextProperties passed in previous create() or setText() call for handle, except for TextProperties::font() that is picked from the style if it was passed as FontHandle::Null.

TextProperties Magnum::Ui::TextLayer::textProperties(LayerDataHandle handle) const

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

Like textProperties(DataHandle) const but without checking that handle indeed belongs to this layer. See its documentation for more information.

Containers::StringView Magnum::Ui::TextLayer::text(DataHandle handle) const

Contents of an editable text.

Expects that handle is valid and the text was created or set with TextDataFlag::Editable present. The returned view is only valid until the next create(), setText() or update() call and is never Containers::StringViewFlag::NullTerminated.

Containers::StringView Magnum::Ui::TextLayer::text(LayerDataHandle handle) const

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

Like text(DataHandle) const but without checking that handle indeed belongs to this layer. See its documentation for more information.

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

Set text.

Expects that handle is valid and TextProperties::font() is either FontHandle::Null or valid. If not null, the TextProperties::font() is used, otherwise the default FontHandle assigned to style() is used and expected to not be null. Note that it's not possible to change the font alone with setStyle(), it only can be done when setting the text. The FontHandle, whether coming from the style or from properties, is expected to have a font instance. Instance-less fonts can be only used to set single glyphs (such as various icons or images) with setGlyph().

This function preserves existing flags() for given handle, use setText(DataHandle, Containers::StringView, const TextProperties&, TextDataFlags) to supply different TextDataFlags for the new text.

If flags() contain TextDataFlag::Editable, the text and properties are remembered and subsequently accessible through text() and textProperties(), cursor() position and selection are both set to text size. Currently, for editable text, the properties are expected to have empty TextProperties::features() — only the features supplied by the style are used for editable text.

Calling this function causes LayerState::NeedsDataUpdate to be set.

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

Set text with different flags.

Like setText(DataHandle, Containers::StringView, const TextProperties&) but supplying different TextDataFlags for the new text instead of preserving existing flags().

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

Set text assuming it belongs to this layer.

Like setText(DataHandle, Containers::StringView, const TextProperties&) but without checking that handle indeed belongs to this layer. See its documentation for more information.

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

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

Like setText(DataHandle, Containers::StringView, const TextProperties&, TextDataFlags) but without checking that handle indeed belongs to this layer. See its documentation for more information.

void Magnum::Ui::TextLayer::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.

Parameters
handle Handle which to update
removeOffset Offset at which to remove
removeSize Count of bytes to remove
insertOffset Offset at which to insert after the removal
insertText Text to insert after the removal
cursor Cursor position to set after the removal and subsequent insert
selection Selection to set after the removal and subsequent insert

Low-level interface for text removal and insertion together with cursor positioning. See setCursor() for just cursor positioning alone, use editText() to perform higher-level operations with UTF-8 and text directionality awareness.

Expects that handle is valid and the text was created or set with TextDataFlag::Editable enabled. The removeOffset together with removeSize is expected to be less or equal to text() size; insertOffset then equal to the text size without removeSize; cursor and selection then to text size without removeSize but with insertText size. The distance between cursor and selection is what's selected — if selection is less than cursor, the selection is before the cursor, if cursor is less than selection, the selection is after the cursor. If they're the same, there's no selection. No UTF-8 sequence boundary adjustment is done for any of these, i.e. it's possible to remove or insert partial multi-byte UTF-8 sequences and position the cursor inside them as well.

Calling this function causes LayerState::NeedsDataUpdate to be set, unless the operation performed is a no-op, which is when both removeSize and insertText size are both 0 and cursor is equal to cursor().

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

Update text and cursor position in an editable text.

Same as calling updateText(DataHandle, UnsignedInt, UnsignedInt, UnsignedInt, Containers::StringView, UnsignedInt, UnsignedInt) with position passed to both position and selection, i.e. with nothing selected.

void Magnum::Ui::TextLayer::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.

Like updateText(DataHandle, UnsignedInt, UnsignedInt, UnsignedInt, Containers::StringView, UnsignedInt, UnsignedInt) but without checking that handle indeed belongs to this layer. See its documentation for more information.

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

Update text and cursor position in an editable text.

Same as calling updateText(DataHandle, UnsignedInt, UnsignedInt, UnsignedInt, Containers::StringView, UnsignedInt, UnsignedInt) with position passed to both position and selection, i.e. with nothing selected.

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

Edit text at current cursor position.

High-level interface for text editing, mapping to usual user interface operations. Delegates to setCursor() or updateText() internally.

Expects that handle is valid, the text was created or set with TextDataFlag::Editable enabled and insert is non-empty only if appropriate edit operation is used. See documentation of the TextEdit enum for detailed behavior of each operation.

Calling this function causes LayerState::NeedsDataUpdate to be set, unless the operation performed is a no-op such as inserting empty text or moving a cursor / deleting a character to the left with the cursor already being on the leftmost side of the text.

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

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

Like editText(DataHandle, TextEdit, Containers::StringView) but without checking that handle indeed belongs to this layer. See its documentation for more information.

void Magnum::Ui::TextLayer::setGlyph(DataHandle handle, UnsignedInt glyph, const TextProperties& properties)

Set a single glyph.

Expects that handle is valid and TextProperties::font() is either FontHandle::Null or valid. If not null, the TextProperties::font() is used, otherwise the default FontHandle assigned to style() is used and expected to not be null. Note that it's not possible to change the font alone with setStyle(), it only can be done when setting the glyph. The glyph is expected to be less than Text::AbstractGlyphCache::fontGlyphCount() for given font.

Compared to setText(), the glyph is aligned according to TextProperties::alignment() based on its bounding rectangle coming from the glyph cache, not based on font metrics. The TextProperties::script(), language(), shapeDirection(), layoutDirection() and features() properties aren't used in any way; flags() get reset to empty. Note that it's also possible to change a handle that previously contained a text to a single glyph and vice versa — the internal representation of both is the same.

Calling this function causes LayerState::NeedsDataUpdate to be set.

template<class GlyphIndex>
void Magnum::Ui::TextLayer::setGlyph(DataHandle handle, GlyphIndex glyph, const TextProperties& properties)

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

Casts glyph to UnsignedInt and delegates to setGlyph(DataHandle, UnsignedInt, const TextProperties&).

void Magnum::Ui::TextLayer::setGlyph(LayerDataHandle handle, UnsignedInt glyph, const TextProperties& properties)

Set a single glyph assuming it belongs to this layer.

Like setGlyph(DataHandle, UnsignedInt, const TextProperties&) but without checking that handle indeed belongs to this layer. See its documentation for more information.

template<class GlyphIndex>
void Magnum::Ui::TextLayer::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.

Casts glyph to UnsignedInt and delegates to setGlyph(LayerDataHandle, UnsignedInt, const TextProperties&).

Color4 Magnum::Ui::TextLayer::color(DataHandle handle) const

Text custom base color.

Expects that handle is valid.

Color4 Magnum::Ui::TextLayer::color(LayerDataHandle handle) const

Text custom base color assuming it belongs to this layer.

Expects that handle is valid.

void Magnum::Ui::TextLayer::setColor(DataHandle handle, const Color4& color)

Set text custom base color.

Expects that handle is valid. TextLayerStyleUniform::color is multiplied with color. Applies to style override for selected text as well, but not to TextLayerEditingStyleUniform::backgroundColor for cursor and selection rectangles. By default, the custom color is 0xffffffff_srgbaf, i.e. not affecting the style in any way.

Calling this function causes LayerState::NeedsDataUpdate to be set.

void Magnum::Ui::TextLayer::setColor(LayerDataHandle handle, const Color4& color)

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

Like setColor(DataHandle, const Color4&) but without checking that handle indeed belongs to this layer. See its documentation for more information.

Vector4 Magnum::Ui::TextLayer::padding(DataHandle handle) const

Text custom padding.

In order left, top. right, bottom. Expects that handle is valid.

Vector4 Magnum::Ui::TextLayer::padding(LayerDataHandle handle) const

Text custom padding assuming it belongs to this layer.

In order left, top. right, bottom. Expects that handle is valid.

void Magnum::Ui::TextLayer::setPadding(DataHandle handle, const Vector4& padding)

Set text custom padding.

Expects that handle is valid. The padding is in order left, top, right, bottom and is added to the per-style padding values specified in Shared::setStyle().

Calling this function causes LayerState::NeedsDataUpdate to be set.

void Magnum::Ui::TextLayer::setPadding(LayerDataHandle handle, const Vector4& padding)

Set text custom padding assuming it belongs to this layer.

Like setPadding(DataHandle, const Vector4&) but without checking that handle indeed belongs to this layer. See its documentation for more information.

void Magnum::Ui::TextLayer::setPadding(DataHandle handle, Float padding)

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

Expects that handle is valid. The padding is added to the per-style padding values specified in Shared::setStyle().

Calling this function causes LayerState::NeedsDataUpdate to be set.

void Magnum::Ui::TextLayer::setPadding(LayerDataHandle handle, Float padding)

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

Like setPadding(DataHandle, Float) but without checking that handle indeed belongs to this layer. See its documentation for more information.