contract_editor_session.hpp

Go to the documentation of this file.

#pragma once
 
// One editor opened through the editor-host contract (editor_host.hpp), held
// by a format adapter on the host's behalf.
//
// Every plug-in format turns its own editor callbacks (VST3 IPlugView, CLAP
// clap_plugin_gui, an AU Cocoa view) into the same handful of contract calls.
// This session owns what those adapters share, so each one is a thin mapping:
//
// - the editor itself, built from the processor's EditorFactory in the editor
//   role, with an EditorContext whose resize and host-action requests go to
//   hooks the adapter supplies;
// - one StateStoreParamPort over the adapter's store, so edits reach the host
//   through the adapter's existing gesture path, and closing this editor never
//   ends a gesture another editor holds;
// - attachment: `detach()` releases every gesture this session holds before
//   the editor detaches. When the adapter or its processor goes away,
//   `close_for_owner()` (the host's window still exists) releases them,
//   detaches the editor and destroys it, and `invalidate()` (the window is
//   already gone) releases them, invalidates the editor and destroys it; both
//   run while the processor that owns the editor's factory still exists;
// - the idle tick: while attached, Editor::idle() runs from a cancellable
//   main-thread timer (detail::MainThreadTimer) unless the adapter drives
//   `tick()` itself from a host timer. Once the session detaches, closes,
//   invalidates or is destroyed, no tick runs;
// - size negotiation shared by every format: the current size, a host resize
//   (keeping the scale the editor reports), a new content scale, whether the
//   editor is resizable, and a proposed size adjusted by the editor and clamped
//   to its hints.
//
// Main thread only. View-free: it names no view, canvas or render type, so it
// compiles into pulp-format-core.
 
#include <pulp/format/detail/main_thread_timer.hpp>
#include <pulp/format/editor_host.hpp>
 
#include <atomic>
#include <cstdint>
#include <functional>
#include <memory>
#include <mutex>
#include <vector>
 
namespace pulp::state {
class StateStore;
}
 
namespace pulp::format {
 
class ContractEditorSession;

class ContractSessionRegistry {
  public:
    ContractSessionRegistry() = default;
    ~ContractSessionRegistry();
    ContractSessionRegistry(const ContractSessionRegistry&) = delete;
    ContractSessionRegistry& operator=(const ContractSessionRegistry&) = delete;

    void close_all();
    std::size_t size() const;
 
  private:
    friend class ContractEditorSession;
    mutable std::mutex mutex_;
    std::vector<std::weak_ptr<ContractEditorSession>> sessions_;
};
 
class ContractEditorSession : public std::enable_shared_from_this<ContractEditorSession> {
  public:
    static constexpr int kIdleIntervalMs = 16;

    struct HostHooks {
        std::function<bool(const EditorSize&)> request_resize;
        std::function<bool(const HostActionRequest&)> host_action;
    };

    enum class IdleSource : std::uint8_t {
        self_paced,  
        host_driven, 
    };

    static std::unique_ptr<ContractEditorSession> create(Processor& processor,
                                                         state::StateStore& store,
                                                         EditorFactory& factory, HostHooks hooks,
                                                         IdleSource idle = IdleSource::self_paced);
 
    ~ContractEditorSession();
    ContractEditorSession(const ContractEditorSession&) = delete;
    ContractEditorSession& operator=(const ContractEditorSession&) = delete;

    Editor* editor() const {
        return editor_.get();
    }

    StateStoreParamPort* param_port() const {
        return port_.get();
    }
    bool is_attached() const {
        return attached_;
    }

    bool attach(const NativeParent& parent);
    void detach();
    void close_for_owner();
    void invalidate();
    void use_self_paced_idle();
    IdleSource idle_source() const {
        return idle_source_;
    }

    void tick();

    bool register_with(ContractSessionRegistry& registry);
    void disconnect_owner();

    EditorSize size() const;
    ViewSize size_hints() const;
    bool set_size(std::uint32_t width, std::uint32_t height);
    bool set_scale(double scale);
    bool resizable() const;
    bool constrain(std::uint32_t& width, std::uint32_t& height) const;

    KeyDisposition offer_key(const EditorKeyEvent& event);
    void focus_changed(bool focused);
    void visibility_changed(bool visible);
 
  private:
    friend class ContractSessionRegistry;
    class Context;
 
    ContractEditorSession(Processor& processor, state::StateStore& store, HostHooks hooks,
                          IdleSource idle);
    void start_idle();
    void stop_idle();
    void destroy_editor();
 
    IdleSource idle_source_;
    // Declared in dependency order so the editor is destroyed first, then the
    // context it was created with, then the port the context hands out.
    std::unique_ptr<StateStoreParamPort> port_;
    std::unique_ptr<Context> context_;
    std::unique_ptr<Editor> editor_;
    bool attached_ = false;
    detail::MainThreadTimer idle_timer_;
    std::atomic<bool> owner_gone_{false};
};
 
} // namespace pulp::format