Magnum::Ui::UserInterface class
#include <Magnum/Ui/UserInterface.h>

Default user interface.

DPI awareness

There are three separate concepts for DPI-aware UI rendering:

  • UI size — size of the user interface to which all widgets are positioned
  • Window size — size of the window to which all input events are related
  • Framebuffer size — size of the framebuffer the UI is being rendered to

Depending on the platform and use case, each of these three values can be different. For example, a game menu screen can have the UI size the same regardless of window size. Or on Retina macOS you can have different window and framebuffer size and the UI size might be related to window size but independent on the framebuffer size.

When using for example Platform::Sdl2Application or other *Application implementations, you usually have three values at your disposal — windowSize(), framebufferSize() and dpiScaling(). If you want the UI to have the same layout and just scale on bigger window sizes, pass a fixed value to the UI size:

Ui::UserInterface ui({800, 600}, windowSize(), framebufferSize());

If you want the UI to get more room with larger window sizes and behave properly with different DPI scaling values, pass a ratio of window size and DPI scaling to the UI size:

Ui::UserInterface ui(Vector2{windowSize()}/dpiScaling(),
    windowSize(), framebufferSize());

Finally, to gracefully deal with extremely small or extremely large windows, you can apply Math::clamp() on top with some defined bounds. Windows outside of the reasonable size range will then get a scaled version of the UI at boundary size:

Ui::UserInterface ui(Math::clamp({640.0f, 360.0f}, {1920.0f, 1080.0f},
    Vector2{windowSize()}/dpiScaling()), windowSize(), framebufferSize());

Font plugins

Unless you pass your own font instance via UserInterface(const Vector2&, const Vector2i&, Text::AbstractFont&, Text::GlyphCache&, const StyleConfiguration&), the constructor expects that it can load some "TrueTypeFont" plugin. The plugin should be either in a system directory or be linked and correctly imported statically. If the plugin cannot be loaded, the application exits. See Loading and using plugins for more information.

Base classes

template<class ... Layers>
class BasicUserInterface<Implementation::QuadLayer, Implementation::QuadLayer, Implementation::TextLayer>
Base for user interfaces.

Constructors, destructors, conversion operators

UserInterface(const Vector2& size, const Vector2i& windowSize, const Vector2i& framebufferSize, const std::string& extraGlyphs = {}) explicit
Constructor.
UserInterface(const Vector2& size, const Vector2i& windowSize, const std::string& extraGlyphs = {}) explicit
UserInterface(const Vector2& size, const Vector2i& windowSize, const Vector2i& framebufferSize, const StyleConfiguration& styleConfiguration, const std::string& extraGlyphs = {}) explicit
Construct the user interface with a custom style.
UserInterface(const Vector2& size, const Vector2i& windowSize, const StyleConfiguration& styleConfiguration, const std::string& extraGlyphs = {}) explicit
UserInterface(PluginManager::Manager<Text::AbstractFont>& fontManager, const Vector2& size, const Vector2i& windowSize, const Vector2i& framebufferSize, const std::string& extraGlyphs = {}) explicit
Construct using a external font plugin manager.
UserInterface(PluginManager::Manager<Text::AbstractFont>& fontManager, const Vector2& size, const Vector2i& windowSize, const Vector2i& framebufferSize, const StyleConfiguration& styleConfiguration, const std::string& extraGlyphs = {}) explicit
Construct the user interface with a custom style.
UserInterface(PluginManager::Manager<Text::AbstractFont>& fontManager, const Vector2& size, const Vector2i& windowSize, const StyleConfiguration& styleConfiguration, const std::string& extraGlyphs = {}) explicit
UserInterface(const Vector2& size, const Vector2i& windowSize, const Vector2i& framebufferSize, Text::AbstractFont& font, Text::GlyphCache& glyphCache, const StyleConfiguration& styleConfiguration) explicit
Construct the user interface with custom style and font.
UserInterface(const Vector2& size, const Vector2i& windowSize, Text::AbstractFont& font, Text::GlyphCache& glyphCache, const StyleConfiguration& styleConfiguration) explicit

Public functions

auto activePlane() -> Plane*
Active plane.
auto activePlane() const -> const Plane*
auto styleConfiguration() const -> const StyleConfiguration&
Used style configuration.
void setStyleConfiguration(const StyleConfiguration& configuration)
Set style configuration.
void relayout(const Vector2& size, const Vector2i& windowSize, const Vector2i& framebufferSize)
Relayout the user interface.
auto font() -> Text::AbstractFont&
Font used for the interface.
auto font() const -> const Text::AbstractFont&
auto glyphCache() -> Text::GlyphCache&
Glyph cache used for the interface.
auto glyphCache() const -> const Text::GlyphCache&
auto focusedInputWidget() -> Input*
Currently focused input widget.
void draw()
Draw the user interface.
auto inputWidgetFocused() -> Signal
Input widget was focused.
auto inputWidgetBlurred() -> Signal
Input widget was blurred.

Function documentation

Magnum::Ui::UserInterface::UserInterface(const Vector2& size, const Vector2i& windowSize, const Vector2i& framebufferSize, const std::string& extraGlyphs = {}) explicit

Constructor.

Parameters
size Size of the user interface to which all widgets are positioned
windowSize Size of the window to which all input events are related
framebufferSize Size of the window framebuffer. On some platforms with HiDPI screens may be different from window size.
extraGlyphs Extra characters to add to glyph cache

Uses defaultStyleConfiguration() and a builtin font with pre-populated glyph cache.

Magnum::Ui::UserInterface::UserInterface(const Vector2& size, const Vector2i& windowSize, const std::string& extraGlyphs = {}) explicit

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

Equivalent to UserInterface(const Vector2&, const Vector2i&, const Vector2i&, const std::string&) with both windowSize and framebufferSize set to the same value. In order to have crisp rendering on HiDPI screens, it's advised to set those two values separately.

Magnum::Ui::UserInterface::UserInterface(const Vector2& size, const Vector2i& windowSize, const Vector2i& framebufferSize, const StyleConfiguration& styleConfiguration, const std::string& extraGlyphs = {}) explicit

Construct the user interface with a custom style.

Parameters
size Size of the user interface to which all widgets are positioned
windowSize Size of the window to which all input events are related
framebufferSize Size of the window framebuffer. On some platforms with HiDPI screens may be different from window size.
styleConfiguration Style configuration to use
extraGlyphs Extra characters to add to glyph cache

Uses a builtin font with pre-populated glyph cache.

Magnum::Ui::UserInterface::UserInterface(const Vector2& size, const Vector2i& windowSize, const StyleConfiguration& styleConfiguration, const std::string& extraGlyphs = {}) explicit

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

Equivalent to UserInterface(const Vector2&, const Vector2i&, const Vector2i&, const StyleConfiguration&, const std::string&) with both windowSize and framebufferSize set to the same value. In order to have crisp rendering on HiDPI screens, it's advised to set those two values separately.

Magnum::Ui::UserInterface::UserInterface(PluginManager::Manager<Text::AbstractFont>& fontManager, const Vector2& size, const Vector2i& windowSize, const Vector2i& framebufferSize, const std::string& extraGlyphs = {}) explicit

Construct using a external font plugin manager.

Parameters
fontManager Font plugin manager
size Size of the user interface to which all widgets are positioned
windowSize Size of the window to which all input events are related
framebufferSize Size of the window framebuffer. On some platforms with HiDPI screens may be different from window size.
extraGlyphs Extra characters to add to glyph cache

Uses defaultStyleConfiguration() and a builtin font with pre-populated glyph cache, loaded from fontManager.

Magnum::Ui::UserInterface::UserInterface(PluginManager::Manager<Text::AbstractFont>& fontManager, const Vector2& size, const Vector2i& windowSize, const Vector2i& framebufferSize, const StyleConfiguration& styleConfiguration, const std::string& extraGlyphs = {}) explicit

Construct the user interface with a custom style.

Parameters
fontManager Font plugin manager
size Size of the user interface to which all widgets are positioned
windowSize Size of the window to which all input events are related
framebufferSize Size of the window framebuffer. On some platforms with HiDPI screens may be different from window size.
styleConfiguration Style configuration to use
extraGlyphs Extra characters to add to glyph cache

Uses a builtin font with pre-populated glyph cache, loaded from fontManager.

Magnum::Ui::UserInterface::UserInterface(PluginManager::Manager<Text::AbstractFont>& fontManager, const Vector2& size, const Vector2i& windowSize, const StyleConfiguration& styleConfiguration, const std::string& extraGlyphs = {}) explicit

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

Equivalent to UserInterface(PluginManager::Manager<Text::AbstractFont>&, const Vector2&, const Vector2i&, const Vector2i&, const StyleConfiguration&, const std::string&) with both windowSize and framebufferSize set to the same value. In order to have crisp rendering on HiDPI screens, it's advised to set those two values separately.

Magnum::Ui::UserInterface::UserInterface(const Vector2& size, const Vector2i& windowSize, const Vector2i& framebufferSize, Text::AbstractFont& font, Text::GlyphCache& glyphCache, const StyleConfiguration& styleConfiguration) explicit

Construct the user interface with custom style and font.

Parameters
size Size of the user interface to which all widgets are positioned
windowSize Size of the window to which all input events are related
framebufferSize Size of the window framebuffer. On some platforms with HiDPI screens may be different from window size.
font Font to use
glyphCache Populated glyph cache to use
styleConfiguration Style configuration to use

The font and glyphCache is expected to be kept in scope for the whole user interface lifetime.

Magnum::Ui::UserInterface::UserInterface(const Vector2& size, const Vector2i& windowSize, Text::AbstractFont& font, Text::GlyphCache& glyphCache, const StyleConfiguration& styleConfiguration) explicit

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

Equivalent to UserInterface(const Vector2&, const Vector2i&, const Vector2i&, Text::AbstractFont&, Text::GlyphCache&, const StyleConfiguration&) with both windowSize and framebufferSize set to the same value. In order to have crisp rendering on HiDPI screens, it's advised to set those two values separately.

const Plane* Magnum::Ui::UserInterface::activePlane() const

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::UserInterface::setStyleConfiguration(const StyleConfiguration& configuration)

Set style configuration.

Note that everything set prior to this call will have undefined contents after calling this function. Reset the contents and fill the interface again.

void Magnum::Ui::UserInterface::relayout(const Vector2& size, const Vector2i& windowSize, const Vector2i& framebufferSize)

Relayout the user interface.

Adapts the internal state for a new size / window size.

const Text::AbstractFont& Magnum::Ui::UserInterface::font() const

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

const Text::GlyphCache& Magnum::Ui::UserInterface::glyphCache() const

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

Input* Magnum::Ui::UserInterface::focusedInputWidget()

Currently focused input widget.

Input widget that should receive text input from the application. Returns nullptr if there is no active text input widget.

Signal Magnum::Ui::UserInterface::inputWidgetFocused()

Input widget was focused.

Text input from the application should be started upon signaling this. Currently active input widget is available in focusedInputWidget().

Signal Magnum::Ui::UserInterface::inputWidgetBlurred()

Input widget was blurred.

Text input from the application should be started upon signaling this. Currently active input widget is available in focusedInputWidget().