Collapsible.hpp

Go to the documentation of this file.

#pragma once
 
#include "LayoutCursor.hpp"
#include "MayaFlux/Portal/Forma/Target.hpp"
 
namespace MayaFlux::Core {
class Window;
}
 
namespace MayaFlux::Buffers {
class FormaBuffer;
}
 
namespace MayaFlux::Portal::Forma {
 
class Layer;
class Context;
class Surface;
 
/**
 * @struct Collapsible
 * @brief A collapsible header strip.
 *
 * Before place() is called, the struct carries only configuration.
 * After place(), header_id, open, buf, and cursor_out are populated.
 * This mirrors the Element pattern: configure with setters, register
 * with a single explicit call.
 *
 * @code
 * auto col = Collapsible{}
 *     .initially_open(false)
 *     .closed_color({ 0.2F, 0.2F, 0.2F })
 *     .label("Oscillator")
 *     .place(window, layer, ctx, cursor, x_min, x_max, row_h);
 *
 * col.attach(layer, body_id);
 * @endcode
 */
struct Collapsible {
    // =========================================================================
    // Results - populated by place()
    // =========================================================================
 
    /// @brief Element id of the header strip. Valid after place().
    uint32_t header_id {};
 
    /// @brief Open/closed state. Valid after place(). Write to toggle.
    std::shared_ptr<MappedState<bool>> open;
 
    /// @brief FormaBuffer backing the header geometry. Valid after place().
    FormaTarget buf;
 
    /// @brief Cursor positioned below the header, ready for body elements. Valid after place().
    LayoutCursor cursor_out;
 
    /// @brief NDC region occupied by the header strip. Valid after place().
    Kinesis::AABB2D header_bounds {};
 
    /// @brief Header strip region, satisfying Kinesis::HasBounds.
    [[nodiscard]] Kinesis::AABB2D bounds() const noexcept { return header_bounds; }
 
    // =========================================================================
    // Configuration - set before place()
    // =========================================================================
 
    /// @brief Starting toggle state. Default: true (open).
    bool m_initially_open { true };
 
    /// @brief Background color when closed. Default: glm::vec3(0.25F).
    glm::vec3 m_color_closed { 0.25F };
 
    /// @brief Background color when open. Default: glm::vec3(0.35F).
    glm::vec3 m_color_open { 0.35F };
 
    /// @brief Text label drawn over the header. Empty = color only.
    std::string m_label_text;
 
    /// @brief Label text color. Default opaque white.
    glm::vec4 m_label_color { 1.F, 1.F, 1.F, 1.F };
 
    // =========================================================================
    // Configuration setters
    // =========================================================================
 
    Collapsible& initially_open(bool v)
    {
        m_initially_open = v;
        return *this;
    }
 
    Collapsible& closed_color(glm::vec3 c)
    {
        m_color_closed = c;
        return *this;
    }
 
    Collapsible& open_color(glm::vec3 c)
    {
        m_color_open = c;
        return *this;
    }
 
    /**
     * @brief Draw a text label over the header, background included.
     *
     * When set, place() draws @p text with the current open/closed color
     * as Portal::Text::PressParams::background, and every toggle draws it
     * again with the new color - background and label are one slice, so
     * they can never drift out of sync the way two independent draws could.
     * When empty
     * (default), the header stays a plain color-only quad with no text
     * machinery at all.
     *
     * @p buf passed to place() still needs the "text" additional_textures
     * slot when a label is set, same as Element::with_text.
     */
    Collapsible& label(std::string text)
    {
        m_label_text = std::move(text);
        return *this;
    }
 
    /// @brief Label text color. Only meaningful when label() is non-empty.
    Collapsible& label_color(glm::vec4 c)
    {
        m_label_color = c;
        return *this;
    }
 
    // =========================================================================
    // Placement
    // =========================================================================
 
    /**
     * @brief Register the header element and wire the toggle callback.
     *
     * Advances @p cursor by @p row_h. Populates header_id, open, buf,
     * and cursor_out on this struct.
     *
     * @param buf     Pre-created FormaBuffer sized for this header.
     * @param surface Surface to register the header on.
     * @param cursor  Layout cursor. Advanced by row_h on return.
     * @param x_min   Left edge in NDC.
     * @param x_max   Right edge in NDC.
     * @param row_h   Header strip height in NDC units.
     * @return *this, with results populated.
     */
    MAYAFLUX_API Collapsible& place(
        FormaTarget buf,
        Surface& surface,
        LayoutCursor& cursor,
        float x_min, float x_max, float row_h);
 
    /**
     * @brief Register the header element using the cursor's column extents.
     *
     * Equivalent to the explicit-extent overload with x_min and x_max taken
     * from @p cursor. Use with a column-scoped LayoutCursor so the header
     * spans exactly the column the cursor advances within.
     *
     * @param buf     Pre-created FormaBuffer sized for this header.
     * @param surface Surface to register the header on.
     * @param cursor  Layout cursor. Supplies column extents and is advanced
     *                by @p row_h on return.
     * @param row_h   Header strip height in NDC units.
     * @return *this, with results populated.
     */
    MAYAFLUX_API Collapsible& place(
        FormaTarget buf,
        Surface& surface,
        LayoutCursor& cursor,
        float row_h);
 
    // =========================================================================
    // Post-placement helpers
    // =========================================================================
 
    /**
     * @brief Relate a body element to this collapsible and sync its visibility
     *        to the current open state.
     *
     * This is the only bookkeeping Collapsible does for an attached body -
     * everything else lives in Layer::m_relations, keyed by header_id. That
     * means Portal::Forma::destroy(surface, header_id) tears down every
     * attached body for free, with no Collapsible-specific teardown code.
     *
     * @param layer   Layer the body element lives on.
     * @param body_id Element id returned from layer.add(...).
     */
    MAYAFLUX_API void attach(Layer& layer, uint32_t body_id) const;
};
 
// =============================================================================
// Free function escape hatch
// =============================================================================
 
/**
 * @brief Construct a collapsible header strip.
 *
 * Thin wrapper delegating to Collapsible::place(). Preserved as an escape
 * hatch; existing callsites require no changes. The @p bridge parameter is
 * accepted but ignored - Forma::bridge() is called internally.
 */
[[nodiscard]] MAYAFLUX_API Collapsible make_collapsible(
    FormaTarget buf,
    Surface& surface,
    LayoutCursor& cursor,
    float x_min,
    float x_max,
    float row_h,
    bool initially_open = true,
    glm::vec3 color_closed = glm::vec3(0.25F),
    glm::vec3 color_open = glm::vec3(0.35F),
    std::string label = {});
 
} // namespace MayaFlux::Portal::Forma