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

Setting up a debug layer instance

A debug layer, either DebugLayer or DebugLayerGL, is constructed using a fresh AbstractUserInterface::createLayer() handle, a combination of DebugLayerSource values that the debug layer should track and a DebugLayerFlag combination describing the actual behavior; and is subsequently passed to AbstractUserInterface::setLayerInstance(). For correct behavior it should be added as the very last layer so it's drawn on top of all other layers and reacts to events first.

ui.setLayerInstance(Containers::pointer<Ui::DebugLayerGL>(
    ui.createLayer(),
    Ui::DebugLayerSource::NodeHierarchy|Ui::DebugLayerSource::NodeDataAttachments,
    Ui::DebugLayerFlag::NodeHighlight));

With this, assuming AbstractUserInterface::draw() is called in an appropriate place, the layer is ready to use. You likely don't need to keep a reference to it as it will track changes in enabled sources without further involvement. In case of the base DebugLayer that doesn't draw, or when inspecting the UI programmatically, calling just AbstractUserInterface::update() (which is otherwise called from draw()) is enough to make it aware of latest state changes.

Node highlight

The setup shown above, in particular with DebugLayerFlag::NodeHighlight together with at least DebugLayerSource::Nodes enabled, makes it possible to highlight any node in the hierarchy and see its details. NodeHierarchy additionally shows info about parent and child nodes and NodeDataAttachments also lists data attachments. Let's say we have a Ui::Button placed somewhere in the UI, reacting to a tap or click:

Ui::NodeHandle button = Ui::button(…, Ui::Icon::Yes, "Accept");

ui.eventLayer().onTapOrClick(button, []{
    …
});

With the DebugLayer set up, clicking on this button with Ctrl right mouse button (or Ctrl pen eraser in case of a pen input) highlights the node, showing a magenta rectangle over, and prints details about it to the console like shown below. Clicking on any other node will highlight that one instead, clicking again on the highlighted node will remove the highlight.

Node {0x9, 0x2}
  Nested at level 1 with 0 direct children
  4 data from 3 layers

debugLayer.setLayerName(ui.eventLayer(), "Event");
debugLayer.setLayerName(ui.baseLayer(), "Base");
debugLayer.setLayerName(ui.textLayer(), "Text");
debugLayer.setNodeName(button, "Accept button");

Node {0x9, 0x2} Accept button
  Nested at level 1 with 0 direct children
  1 data from layer {0x0, 0x1} Base
  2 data from layer {0x1, 0x1} Text
  1 data from layer {0x2, 0x1} Event

Node {0x9, 0x2} Accept button
  Nested at level 1 with 0 direct children
  Data {0x3, 0x2} from layer {0x0, 0x1} Base
    Inactive out style: 1
    Inactive over style: 2
    Pressed out style: 3
    Pressed over style: 4
    Disabled style: 5
  Data {0x6, 0x1} from layer {0x1, 0x1} Text
    Inactive style: 3
    Pressed style: 7
    Disabled style: 11
  Data {0x7, 0x1} from layer {0x1, 0x1} Text
    Inactive style: 4
    Pressed style: 8
    Disabled style: 12
  Data {0x0, 0x1} from layer {0x2, 0x1} Event reacting to tap or click

/* Enable node highlighting with just a touch */
debugLayer
    .addFlags(Ui::DebugLayerFlag::NodeHighlight)
    .setNodeHighlightGesture(Ui::Pointer::Finger, {});

…

/* Disable it again and revert to a safe gesture when not used anymore */
debugLayer
    .clearFlags(Ui::DebugLayerFlag::NodeHighlight)
    .setNodeHighlightGesture(Ui::Pointer::MouseRight, Ui::Modifier::Ctrl);

Ui::Label details{…};

…

debugLayer.setNodeHighlightCallback([&details](Containers::StringView message) {
    details
        .setText(message)
        .setHidden(!message);
});

Making the DebugLayer opt-in

As mentioned above, having the layer always present may have unintended performance implications, and a node highlight can be confusing if triggered accidentally by an unsuspecting user. One possibility is to create it only with a certain startup option, such as is the case with --debug in magnum-ui-gallery.

Another way is to create it with no DebugLayerFlag present, and enable them temporarily only if some debug mode is activated, similarly to what was shown for touch input above. Such setup will however still make it track all enabled DebugLayerSource bits all the time. To avoid this, it's also possible to defer the layer creation and setup to the point when it's actually needed, and then destroy it again after. Note that, as certain options involve iterating the whole node tree, with very complex UIs such on-the-fly setup might cause stalls.

DebugLayer integration for custom layers

To make a custom layer provide detailed info for DebugLayerSource::NodeDataAttachmentDetails, implement an inner type named DebugIntegration containing at least a print() function. In the following snippet, a layer that exposes per-data color has the color printed in the DebugLayerFlag::NodeHighlight output. To make the output fit with the other text, it's expected to be indented and end with a newline:

class ColorLayer: public Ui::AbstractLayer {
    public:
        struct DebugIntegration;

        Color3 color(Ui::LayerDataHandle handle) const;

        …
};

struct ColorLayer::DebugIntegration {
    void print(Debug& debug, const ColorLayer& layer,
               Containers::StringView layerName, Ui::LayerDataHandle data) {
        /* Convert to an 8-bit color for brevity */
        Color3ub color8 = Math::pack<Color3ub>(layer.color(data));
        debug << "  Data" << Debug::packed << data
            << "from layer" << Debug::packed << layer.handle()
            << Debug::color(Debug::Color::Yellow) << layerName << Debug::resetColor
            << "with color" << Debug::color << color8 << color8 << Debug::newline;
    }
};

Assuming the concrete layer type is passed to setLayerName(), nothing else needs to be done and the integration gets used automatically. If there's multiple data attached to the same node, the print() gets called for each of them.

ColorLayer& colorLayer = ui.setLayerInstance(…);
…

debugLayer.setLayerName(colorLayer, "Shiny");

Node {0xc, 0x1}
  Nested at level 2 with 0 direct children
  Data {0x4, 0x3} from layer {0x4, 0x1} Shiny with color ▓▓ #2f83cc
  Data {0x7, 0x1} from layer {0x4, 0x1} Shiny with color ██ #3bd267

If the integration needs additional state, a constructor can be implemented, and the instance then passed to DebugLayer::setLayerName(const T&, const Containers::StringView&, const typename T::DebugIntegration&) or setLayerName(..., typename T::DebugIntegration&&):

class ColorLayer::DebugIntegration {
    public:
        /*implicit*/ DebugIntegration(DebugFlags flags = {}): _flags{flags} {}

        void print(Debug& debug, const ColorLayer& layer,
                   Containers::StringView layerName, Ui::LayerDataHandle data);

    private:
        DebugFlags _flags;
};

If additional details can be provided even without supplying additional state, it's recommended to have the class default-constructible as well so at least some functionality can be used even if users aren't aware of the extra options. Additionally, in the above code the constructor isn't made explicit, which allows the debug integration arguments to be passed directly to setLayerName():

/* Default integration setup */
debugLayer.setLayerName(colorLayer, "Shiny");

/* Passing extra arguments */
debugLayer.setLayerName(colorLayer, "Shiny",
    ColorLayer::DebugFlag::PrintColor|ColorLayer::DebugFlag::ColorSwatch);

class ColorLayer: public Ui::AbstractVisualLayer {
    public:
        struct DebugIntegration;

        …
};

struct ColorLayer::DebugIntegration: Ui::AbstractVisualLayer::DebugIntegration {
    void print(Debug& debug, const ColorLayer& layer,
               Containers::StringView layerName, Ui::LayerDataHandle data) {
        Ui::AbstractVisualLayer::DebugIntegration::print(debug, layer, layerName, data);

        …
    }
};

Base classes

class AbstractLayer new in Git master

Base for data layers.

Derived classes

class DebugLayerGL new in Git master

OpenGL implementation of the debug layer.

Public types

class DebugIntegration

Debug layer integration.

Constructors, destructors, conversion operators

DebugLayer(LayerHandle handle, DebugLayerSources sources, DebugLayerFlags flags) explicit

Constructor.

DebugLayer(const DebugLayer&) deleted

Copying is not allowed.

DebugLayer(DebugLayer&&) noexcept

Move constructor.

Public functions

auto operator=(const DebugLayer&) -> DebugLayer& deleted

Copying is not allowed.

auto operator=(DebugLayer&&) -> DebugLayer& noexcept

Move assignment.

auto sources() const -> DebugLayerSources

Tracked data sources.

auto flags() const -> DebugLayerFlags

Behavior flags.

auto setFlags(DebugLayerFlags flags) -> DebugLayer&

Set behavior flags.

auto addFlags(DebugLayerFlags flags) -> DebugLayer&

Add behavior flags.

auto clearFlags(DebugLayerFlags flags) -> DebugLayer&

Clear flags.

auto nodeName(NodeHandle handle) const -> Containers::StringView

Node name.

auto setNodeName(NodeHandle handle, Containers::StringView name) -> DebugLayer&

Set node name.

auto layerName(LayerHandle handle) const -> Containers::StringView

Layer name.

auto setLayerName(const AbstractLayer& layer, Containers::StringView name) -> DebugLayer&

Set layer name.

template<class T>

auto setLayerName(const T& layer, const Containers::StringView& name) -> DebugLayer&

Set name for a layer with DebugIntegration implemented.

template<class T>

auto setLayerName(const T& layer, const Containers::StringView& name, const typename T::DebugIntegration& integration) -> DebugLayer&

Set name for a layer with DebugIntegration implemented.

template<class T>

auto setLayerName(const T& layer, const Containers::StringView& name, typename T::DebugIntegration&& integration) -> DebugLayer&

auto nodeHighlightColor() const -> Color4

Node highlight color.

auto setNodeHighlightColor(const Color4& color) -> DebugLayer&

Set node highlight color.

auto nodeHighlightGesture() const -> Containers::Pair<Pointers, Modifiers>

Node highlight gesture.

auto setNodeHighlightGesture(Pointers pointers, Modifiers modifiers) -> DebugLayer&

Set node highlight gesture.

auto hasNodeHighlightCallback() const -> bool

Whether a node highlight callback is set.

auto setNodeHighlightCallback(Containers::Function<void(Containers::StringView message)>&& callback) -> DebugLayer&

Set node highlight callback.

auto currentHighlightedNode() const -> NodeHandle

Node highlighted by last pointer press.

auto highlightNode(NodeHandle node) -> bool

Highlight a node.

Function documentation