hosted_editor_attachment.hpp

Go to the documentation of this file.

#pragma once
 
// Hosted-editor → WindowHost attachment.
//
// Native-window embedding uses the canonical contract for embedding a
// platform-native child view inside a Pulp WindowHost via
// WindowHost::attach_native_child_view / set_native_child_view_bounds /
// detach_native_child_view. This header migrates the legacy "void* editor
// handle" hosting path onto that canonical contract.
//
// Before:  a host walked PluginSlot::create_editor_view() -> void* and was
//          responsible for embedding it into whatever native window it owned,
//          with no typed contract for size, resizability, or detach.
//
// After:   a host calls EditorAttachment::create(slot, window) and receives an
//          RAII object that owns the slot's HostedEditor and keeps it attached
//          to the WindowHost for its lifetime. Destroying or releasing the
//          attachment detaches the child view and asks the slot to destroy the
//          editor, in the right order, without the host having to thread the
//          native_handle through any glue code itself.
//
// EditorAttachment is non-copyable, move-constructible. It is null-safe — if
// the slot has no editor or the WindowHost has no factory for native child
// embedding on this platform, create() returns nullptr and the host can fall
// back to a separate top-level window.
//
// Resize: while attached, the attachment OWNS the slot's
// set_editor_resize_request_handler channel — it installs a handler that
// re-bounds the child view at the same origin, and clears it on release. A
// plug-in that asks to resize itself (CLAP gui.request_resize, VST3
// IPlugFrame::resizeView) therefore moves the window's child view, not just the
// slot's private container. An application that wants to observe or veto those
// requests should wrap the attachment rather than install its own handler,
// which the attachment would overwrite.
//
// Lifetime:
//   - Slot: EditorAttachment co-owns the PluginSlot via shared_ptr. The signal
//     graph stores nodes as shared_ptr<PluginSlot>, and a plugin editor
//     routinely outlives the graph node that opened it (the node is removed
//     while its window is still on screen). Sharing ownership means release()
//     can safely call destroy_hosted_editor() even after the graph has dropped
//     its own reference — the slot stays alive until the attachment is gone.
//   - WindowHost: held as a NON-owning pointer. WindowHosts are unique_ptr
//     owned by whatever opened the window and expose no destruction hook, so
//     the caller MUST keep the WindowHost alive until the EditorAttachment is
//     released or destroyed. Destroying the WindowHost first is a use-after-
//     free; release the attachment before tearing its host down.
 
// iOS skip: pulp::host (and therefore plugin_slot.hpp) is not on the include
// path on iOS — iOS bundles never host third-party plugins. Use
// `__has_include` so downstream code can include the header unconditionally
// and key off PULP_VIEW_HAS_HOSTED_EDITOR_ATTACHMENT.
#if defined(__has_include) && __has_include(<pulp/host/plugin_slot.hpp>)
#define PULP_VIEW_HAS_HOSTED_EDITOR_ATTACHMENT 1
 
#include <pulp/host/plugin_slot.hpp>
#include <pulp/view/window_host.hpp>
 
#include <cstdint>
#include <memory>
#include <utility>
 
namespace pulp::view {
 
class EditorAttachment {
  public:
    EditorAttachment(const EditorAttachment&) = delete;
    EditorAttachment& operator=(const EditorAttachment&) = delete;
 
    EditorAttachment(EditorAttachment&& other) noexcept
        : slot_(std::move(other.slot_)), host_(other.host_), editor_(std::move(other.editor_)),
          x_(other.x_), y_(other.y_), width_(other.width_), height_(other.height_),
          attached_(other.attached_) {
        // slot_ was moved-from, so other.slot_ is already empty.
        other.host_ = nullptr;
        other.attached_ = false;
        // The handler the slot holds captures `this`; the moved-from object is
        // about to stop being the owner, so re-point it before anyone can call.
        install_resize_handler();
    }
 
    EditorAttachment& operator=(EditorAttachment&& other) noexcept {
        if (this != &other) {
            release();
            slot_ = std::move(other.slot_);
            host_ = other.host_;
            editor_ = std::move(other.editor_);
            x_ = other.x_;
            y_ = other.y_;
            width_ = other.width_;
            height_ = other.height_;
            attached_ = other.attached_;
            // slot_ was moved-from, so other.slot_ is already empty.
            other.host_ = nullptr;
            other.attached_ = false;
            install_resize_handler();
        }
        return *this;
    }
 
    ~EditorAttachment() {
        release();
    }

    static std::unique_ptr<EditorAttachment> create(std::shared_ptr<host::PluginSlot> slot,
                                                    WindowHost* host, float x = 0.0f,
                                                    float y = 0.0f) {
        if (!slot || !host)
            return nullptr;
        auto editor = slot->create_hosted_editor(host->native_window_handle());
        if (!editor || !editor->native_handle) {
            if (editor)
                slot->destroy_hosted_editor(std::move(editor));
            return nullptr;
        }
        const float w = static_cast<float>(editor->width);
        const float h = static_cast<float>(editor->height);
        const bool ok = host->attach_native_child_view(editor->native_handle, x, y, w, h);
        if (!ok) {
            slot->destroy_hosted_editor(std::move(editor));
            return nullptr;
        }
        // The constructor is private; std::make_unique can't see it. Use new.
        std::unique_ptr<EditorAttachment> attachment(
            new EditorAttachment(std::move(slot), host, std::move(editor), x, y));
        attachment->install_resize_handler();
        return attachment;
    }

    const host::PluginSlot::HostedEditor* editor() const {
        return editor_.get();
    }

    bool is_attached() const {
        return attached_;
    }

    bool set_bounds(float x, float y, float width, float height) {
        if (!attached_ || !host_ || !editor_)
            return false;
        const bool ok =
            host_->set_native_child_view_bounds(editor_->native_handle, x, y, width, height);
        if (ok) {
            x_ = x;
            y_ = y;
            width_ = width;
            height_ = height;
        }
        return ok;
    }

    void release() {
        // The slot outlives this object (it is shared), so a handler capturing
        // `this` must come down before the object does.
        if (slot_)
            slot_->set_editor_resize_request_handler(nullptr);
        if (!attached_) {
            // Even if we never managed to attach, we still own the editor and
            // owe the slot a destroy_hosted_editor() call.
            if (editor_ && slot_) {
                slot_->destroy_hosted_editor(std::move(editor_));
            }
            slot_ = nullptr;
            host_ = nullptr;
            return;
        }
        if (host_ && editor_) {
            host_->detach_native_child_view(editor_->native_handle);
        }
        attached_ = false;
        if (slot_ && editor_) {
            slot_->destroy_hosted_editor(std::move(editor_));
        }
        slot_ = nullptr;
        host_ = nullptr;
    }
 
    float x() const {
        return x_;
    }
    float y() const {
        return y_;
    }
    float width() const {
        return width_;
    }
    float height() const {
        return height_;
    }
 
  private:
    EditorAttachment(std::shared_ptr<host::PluginSlot> slot, WindowHost* host,
                     std::unique_ptr<host::PluginSlot::HostedEditor> editor, float x, float y)
        : slot_(std::move(slot)), host_(host), editor_(std::move(editor)), x_(x), y_(y),
          width_(static_cast<float>(editor_ ? editor_->width : 0)),
          height_(static_cast<float>(editor_ ? editor_->height : 0)), attached_(true) {}

    void install_resize_handler() {
        if (!slot_)
            return;
        slot_->set_editor_resize_request_handler([this](uint32_t width, uint32_t height) {
            return set_bounds(x_, y_, static_cast<float>(width), static_cast<float>(height));
        });
    }
 
    std::shared_ptr<host::PluginSlot> slot_;
    WindowHost* host_ = nullptr;
    std::unique_ptr<host::PluginSlot::HostedEditor> editor_;
    float x_ = 0.0f;
    float y_ = 0.0f;
    float width_ = 0.0f;
    float height_ = 0.0f;
    bool attached_ = false;
};
 
} // namespace pulp::view
 
#else // !__has_include(<pulp/host/plugin_slot.hpp>)
#define PULP_VIEW_HAS_HOSTED_EDITOR_ATTACHMENT 0
#endif