editor_host.hpp File Reference

The editor-host contract: how a host (a format adapter, the standalone app, a test) opens, sizes, feeds and tears down a processor's editor without knowing what UI toolkit draws it. More...

#include <pulp/format/editor_host_kind.hpp>
#include <pulp/format/plugin_descriptor.hpp>
#include <pulp/state/parameter.hpp>
#include <cstddef>
#include <cstdint>
#include <functional>
#include <memory>
#include <optional>
#include <span>
#include <string>
#include <string_view>
#include <unordered_map>
#include <utility>
#include <vector>

Go to the source code of this file.

Classes
class	pulp::format::ParamSubscription
	Owns one ParamPort listener registration. More...
class	pulp::format::ParamPort
	Parameter access for an editor. More...
class	pulp::format::StateStoreParamPort
	The default ParamPort, over a processor's StateStore. More...
struct	pulp::format::VisualChannelInfo
	What a visual channel is. The strings stay valid for the life of the port. More...
struct	pulp::format::VisualEvent
	One occurrence on an events channel. More...
class	pulp::format::VisualPort
	Read access to the values and meters a processor publishes for its UI. More...
struct	pulp::format::NativeParent
	A native window to attach an editor to, owned by the host. More...
struct	pulp::format::EditorSize
	An editor size in logical pixels, with the backing scale factor that maps them to physical pixels (2.0 on a Retina display). More...
struct	pulp::format::EditorKeyEvent
	A key the host offers to the editor before acting on it itself. More...
class	pulp::format::EditorAutomation
	Optional automation surface of an editor, so tooling (the pulp control UI tools, tests) can see and drive any editor whatever draws it. More...
class	pulp::format::Editor
	One editor instance in one native window. More...
struct	pulp::format::HostActionRequest
	One host action and its arguments. More...
class	pulp::format::EditorContext
	What the host gives an editor. More...
class	pulp::format::EditorFactory
	Builds a processor's editors. More...

Namespaces
namespace	pulp
namespace	pulp::state
	SequencerStateChannel is the audio-safe transport for a plugin's structured NON-parameter state: the bulk, observable state a step sequencer / mod-matrix / pattern engine holds outside its automatable parameter set (e.g.
namespace	pulp::format
	What the product grants a device: the quota table indexed by capability tier and live thermal state.

Enumerations
enum class	pulp::format::VisualChannelShape : std::uint8_t { pulp::format::scalar = 0 , pulp::format::meter = 1 , pulp::format::vector = 2 , pulp::format::events = 3 }
	The shape of one visual channel. More...
enum class	pulp::format::EditorRole : std::uint8_t { pulp::format::editor = 0 , pulp::format::inspector = 1 , pulp::format::settings = 2 }
	The UI role an editor plays. A processor may offer several at once. More...
enum class	pulp::format::NativeParentKind : std::uint8_t {   pulp::format::none = 0 , pulp::format::cocoa_view = 1 , pulp::format::uikit_view = 2 , pulp::format::win32_window = 3 ,   pulp::format::x11_window = 4 }
	The kind of native window handle an editor is attached to. More...
enum class	pulp::format::EditorKey : std::uint16_t {   pulp::format::none = 0 , pulp::format::space = 1 , pulp::format::enter = 2 , pulp::format::tab = 3 ,   pulp::format::backspace = 4 , pulp::format::escape = 5 , pulp::format::delete_forward = 6 , pulp::format::left = 7 ,   pulp::format::right = 8 , pulp::format::up = 9 , pulp::format::down = 10 , pulp::format::home = 11 ,   pulp::format::end = 12 , pulp::format::page_up = 13 , pulp::format::page_down = 14 }
	A non-character key. More...
enum	pulp::format::EditorKeyModifier : std::uint8_t { pulp::format::editor_modifier_shift = 1u << 0 , pulp::format::editor_modifier_control = 1u << 1 , pulp::format::editor_modifier_alt = 1u << 2 , pulp::format::editor_modifier_command = 1u << 3 }
	Modifier bits in EditorKeyEvent::modifiers. More...
enum class	pulp::format::KeyDisposition : std::uint8_t { pulp::format::forward = 0 , pulp::format::consumed = 1 }
	The editor's answer to an offered key. More...
enum class	pulp::format::HostAction : std::uint16_t { pulp::format::mark_state_dirty = 0 , pulp::format::parameter_context_menu = 1 , pulp::format::close_editor = 2 }
	Actions an editor can ask its host to take. More...

Detailed Description

The editor-host contract: how a host (a format adapter, the standalone app, a test) opens, sizes, feeds and tears down a processor's editor without knowing what UI toolkit draws it.

The contract is deliberately small and UI-agnostic. It names no view, canvas, render or GPU type, so a processor that ships an editor and one that ships none compile against the same header, and any UI toolkit (a Pulp integration package, or a plug-in's own native code) can implement it.

• EditorFactory builds an Editor for a processor, a host-supplied EditorContext and a role. A processor exposes its factory through Processor::editor_factory(); a processor with no factory has no editor on this path. A plug-in's default editor is wired per plug-in, not by a process-wide registration: pulp_add_plugin(... UI <package>) generates a hook in that plug-in's own binary that returns the UI package's factory, the way a VST3 plug-in supplies its own view from createView(). Several plug-ins in one host process therefore never share or override each other's editor choice.
• Editor is one editor instance in one native window: attach and detach, size negotiation, a main-thread tick, synchronous key offering, an optional automation provider, and host-driven invalidation.
• EditorContext is what the host gives the editor: the parameter port, the visual port, a resize request, host actions, the host kind, and query_extension() for capabilities added later.
• ParamPort is parameter access (info, get, begin, set, end, listeners). StateStoreParamPort is the default implementation, routed through the StateStore gesture path the format adapters already report to the host.
• VisualPort is read access to the lock-free values and meters the audio thread publishes for the UI.

Threading: unless a member says otherwise, every call in this contract runs on the host's main (UI) thread, including construction and destruction of editors. ParamPort::get() and ParamPort::info() may be called from any thread.