pulp::state::Binding Class Reference

Reactive binding between a UI widget and a StateStore parameter. More...

#include <binding.hpp>

Public Types
using	ChangeCallback = std::function<void(float new_value)>
	Callback type for change notifications.

Public Member Functions
	Binding ()=default
	Binding (StateStore &store, ParamID param_id)
	Bind to a specific parameter in a store.
float	get () const
	Read the parameter's current value.
void	set (float value)
	Write a new value. Fires change callbacks if the value actually changed.
float	get_normalized () const
	Read the parameter's value mapped to [0, 1].
void	set_normalized (float normalized)
	Write from a normalized [0, 1] value. Fires change callbacks if changed.
void	begin_gesture ()
	Notify the host that a user gesture (e.g., mouse drag) has begun.
void	end_gesture ()
	Notify the host that the current gesture has ended.
void	set_from_background (float value)
	Perform a complete parameter gesture (begin → set → end) from ANY thread — the thread-safe entry point for background writers such as a MIDI-learn engine driving a mapped parameter from a timer thread.
void	set_edit_history (state::EditHistory *h)
	Attach an EditHistory for undo support. Optional — null by default.
state::EditHistory *	edit_history () const
const ParamInfo *	info () const
	Get the immutable metadata for the bound parameter.
ParamID	id () const
	The ID of the bound parameter.
void	on_change (ChangeCallback callback)
	Register a callback that fires when the value changes via set() or poll().
bool	poll ()
	Check whether the parameter was changed externally (e.g., host automation).
void	reset ()
	Reset the parameter to its default value and fire change callbacks.
bool	is_bound () const
	True if this Binding is associated with a StateStore.

Detailed Description

Reactive binding between a UI widget and a StateStore parameter.

Binding wraps a single parameter with value access, gesture tracking, and change notification. The typical usage in a UI widget:

Binding gain_binding(store, kGainParamID);
gain_binding.on_change([&](float v) { knob.repaint(); });
 
// On mouse drag:
gain_binding.begin_gesture();
gain_binding.set_normalized(knob_position);
gain_binding.end_gesture();
 
// On timer tick (detect host automation):
gain_binding.poll();

Note

Thread safety: get/set/get_normalized/set_normalized go through StateStore's atomics and are safe to call from any thread; change callbacks fire on the thread that calls set() or poll(). The GESTURE entry points (begin_gesture/end_gesture) and the EditHistory they drive are main-thread only — they forward to the host's undo-grouping calls (VST3 beginEdit / AU parameter-change gesture / CLAP gesture events) and mutate this Binding's non-atomic gesture state. A background writer (e.g. a MIDI-learn engine on a timer thread) must NOT call them directly; use set_from_background(), which marshals a full begin→set→end gesture onto the host main thread.

Member Typedef Documentation

ChangeCallback

using pulp::state::Binding::ChangeCallback = std::function<void(float new_value)>

Callback type for change notifications.

Constructor & Destructor Documentation

Binding() [1/2]

pulp::state::Binding::Binding ( )

default

Binding() [2/2]

pulp::state::Binding::Binding ( StateStore & store, ParamID param_id )

inline

Bind to a specific parameter in a store.

Parameters

store	The StateStore that owns the parameter.
param_id	ID of the parameter to bind.

Member Function Documentation

begin_gesture()

void pulp::state::Binding::begin_gesture ( )

inline

Notify the host that a user gesture (e.g., mouse drag) has begun.

Call before a series of set()/set_normalized() calls so the host groups them into one undo step. Captures the value for undo.

edit_history()

state::EditHistory * pulp::state::Binding::edit_history ( ) const

inline

end_gesture()

void pulp::state::Binding::end_gesture ( )

inline

Notify the host that the current gesture has ended.

If an EditHistory is attached, pushes an undo action for the value change.

get()

float pulp::state::Binding::get ( ) const

inline

Read the parameter's current value.

get_normalized()

float pulp::state::Binding::get_normalized ( ) const

inline

Read the parameter's value mapped to [0, 1].

id()

ParamID pulp::state::Binding::id ( ) const

inline

The ID of the bound parameter.

info()

const ParamInfo * pulp::state::Binding::info ( ) const

inline

Get the immutable metadata for the bound parameter.

Returns

Pointer to ParamInfo, or nullptr if unbound.

is_bound()

bool pulp::state::Binding::is_bound ( ) const

inline

True if this Binding is associated with a StateStore.

on_change()

void pulp::state::Binding::on_change ( ChangeCallback callback )

inline

Register a callback that fires when the value changes via set() or poll().

poll()

bool pulp::state::Binding::poll ( )

inline

Check whether the parameter was changed externally (e.g., host automation).

Call this periodically from the UI thread. Fires change callbacks if the value differs from the last polled value.

Returns

True if the value changed since the last poll.

Note

Soft-deprecated. The canonical pattern is no longer periodic polling: a parameter change should set a dirty flag and the UI should repaint on the next vblank via WindowHost::mark_dirty() — see pulp::render::RenderLoop and WindowHost::mark_dirty(). poll() stays supported for existing callers and for hosts without a vblank-driven loop, but new code should prefer the dirty-flag / next-frame path. It is intentionally NOT marked [[deprecated]] to avoid breaking -Werror builds.

reset()

void pulp::state::Binding::reset ( )

inline

Reset the parameter to its default value and fire change callbacks.

set()

void pulp::state::Binding::set ( float value )

inline

Write a new value. Fires change callbacks if the value actually changed.

set_edit_history()

void pulp::state::Binding::set_edit_history ( state::EditHistory * h )

inline

Attach an EditHistory for undo support. Optional — null by default.

set_from_background()

void pulp::state::Binding::set_from_background ( float value )

inline

Perform a complete parameter gesture (begin → set → end) from ANY thread — the thread-safe entry point for background writers such as a MIDI-learn engine driving a mapped parameter from a timer thread.

The gesture is marshalled onto the host main thread via StateStore::run_gesture_on_main so the host's begin/endEdit undo grouping is issued in order on the correct thread. Only the store and the target value are captured (never this), so this is safe even if the Binding is destroyed before the marshalled task runs. It does NOT push to this Binding's EditHistory: an off-thread automation-style write is not a user undo step, matching how host automation never creates one.

set_normalized()

void pulp::state::Binding::set_normalized ( float normalized )

inline

Write from a normalized [0, 1] value. Fires change callbacks if changed.

---

The documentation for this class was generated from the following file:

• /home/runner/work/pulp/pulp/core/state/include/pulp/state/binding.hpp