mostly_harmless::gui::WebviewEditor Class Reference

An opinionated subclass of WebviewBase, providing default impls for bidirectional comms. More...

#include <mostlyharmless_WebviewEditor.h>

Inheritance diagram for mostly_harmless::gui::WebviewEditor:

Public Member Functions
	WebviewEditor (core::ISharedState *sharedState, std::uint32_t initialWidth, std::uint32_t initialHeight, Colour backgroundColour)
	~WebviewEditor () noexcept override=default
void	initialise () override
void	onParamEvent (events::ProcToGuiParamEvent event) override
virtual void	sendEvent (events::WebEvent &&event) noexcept
Public Member Functions inherited from mostly_harmless::gui::WebviewBase
	WebviewBase (std::uint32_t initialWidth, std::uint32_t initialHeight, Colour backgroundColour)
	~WebviewBase () noexcept override
void	setOptions (Options &&options) noexcept
void	destroy () override
void	setSize (std::uint32_t width, std::uint32_t height) override
void	getSize (std::uint32_t *width, std::uint32_t *height) override
void	setParent (void *parentHandle) override
void	show () override
void	hide () override
Public Member Functions inherited from mostly_harmless::core::IEditor
virtual	~IEditor () noexcept=default

Protected Member Functions
virtual choc::value::Value	beginParamChangeGestureCallback (const choc::value::ValueView &args)
virtual choc::value::Value	paramChangeGestureCallback (const choc::value::ValueView &args)
virtual choc::value::Value	endParamChangeGestureCallback (const choc::value::ValueView &args)

Protected Attributes
core::ISharedState *	m_sharedState { nullptr }
Protected Attributes inherited from mostly_harmless::gui::WebviewBase
choc::ui::WebView *	m_internalWebview { nullptr }

Detailed Description

An opinionated subclass of WebviewBase, providing default impls for bidirectional comms.

Where WebviewBase handles lower level things like window creation / management, this class handles slightly higher level details - namely, an event system, and param updates.

To use it, you'll probably want to still subclass it, but the boilerplate will be fairly minimal. See WebviewBase for more fine grained details.

The default implementation establishes bindings to 3 javascript functions, pertaining to parameter updates. These are: beginParamGesture(), setParamValue(), and endParamGesture().
Each of these functions take an object as an arg, expected to be formatted as json containing the paramId to affect, and the value to set. For example:

const args = {
    paramId: 0,
    value: 0.8
};

beginParamGesture is expected to be called when a slider first begins being dragged, setParamValue while it is being changed, and endParamValue once the user stops dragging. These functions are bound to internal native functions (which you can override if you like), beginParamChangeGestureCallback(), paramChangeGestureCallback(), and endParamChangeGestureCallback(). These functions are actually promises, which we don't really leverage here, aside from to report errors in the case of an arg-parsing failure. The default implementation will attempt to parse the args (and assert fail if it failed), and then enqueue the param changes to the guiToProcQueue, for the host and audio side to pick up.

The structure of an event in the default implementation is:

event = new CustomEvent("the event's id", {
    detail: {
         the event's content
    }
});
window.dispatchEvent(event);

So to respond to this, you can register an event listener:

let callback = (ev) => {
     // your code here, details are accessible through ev.detail
};
addEventListener("the event's id", callback);
// to unsubscribe (do this for cleanup!)
removeEventListener("the event's id", callback);

This function is called by the default implementation of onParamEvent(). The event is structured as:

CustomEvent("param", {
    detail: {
        "paramId": "the param id",
        "value": the param's value
    }
});

for example,

let callback = (ev) => {
    const paramId = ev.detail.paramId;
    const value = parseFloat(ev.detail.value);
    // .... do something with this data....
};
addEventListener("param", callback);

Constructor & Destructor Documentation

WebviewEditor()

mostly_harmless::gui::WebviewEditor::WebviewEditor	(	core::ISharedState *	sharedState,
		std::uint32_t	initialWidth,
		std::uint32_t	initialHeight,
		Colour	backgroundColour )

Parameters

initialWidth	The initial width for the webview.
initialHeight	The initial height for the webview.
backgroundColour	The colour to paint the actual window beneath the webview.

~WebviewEditor()

mostly_harmless::gui::WebviewEditor::~WebviewEditor ( )

overridedefaultnoexcept

Default destructor.

Member Function Documentation

beginParamChangeGestureCallback()

virtual choc::value::Value mostly_harmless::gui::WebviewEditor::beginParamChangeGestureCallback ( const choc::value::ValueView & args )

protectedvirtual

Called internally by any javascript side calls to beginParamGesture(). Informs the host/audio thread that a change gesture has started.

Parameters

context	The editor context.
args	The args provided by the frontend.

Returns

An empty value if everything went well, the exception message if parsing the args failed.

endParamChangeGestureCallback()

virtual choc::value::Value mostly_harmless::gui::WebviewEditor::endParamChangeGestureCallback ( const choc::value::ValueView & args )

protectedvirtual

Called internally by any javascript side calls to 'endParamGesture()`. Informs the host/audio thread that a change gesture has ended.

Parameters

context	The editor context.
args	The args provided by the frontend.

Returns

An empty value if everything went well, the exception message if parsing the args failed.

initialise()

void mostly_harmless::gui::WebviewEditor::initialise ( )

overridevirtual

Called immediately after the gui has been created - use this to perform any post-creation initialisation.

Reimplemented from mostly_harmless::gui::WebviewBase.

onParamEvent()

void mostly_harmless::gui::WebviewEditor::onParamEvent ( events::ProcToGuiParamEvent event )

overridevirtual

Called when the host sends a param update, to inform the gui that a change has occurred.
Actually gets invoked from a timer thread, on the message thread.
This is still virtual, and can be overridden as you like, but the default implementation will call sendEvent() with a WebEvent constructed from the event passed from the param queue - see sendEvent() for more details.

Parameters

event

An event specifying

Implements mostly_harmless::gui::WebviewBase.

paramChangeGestureCallback()

virtual choc::value::Value mostly_harmless::gui::WebviewEditor::paramChangeGestureCallback ( const choc::value::ValueView & args )

protectedvirtual

Called internally by any javascript side calls to 'setParamValue()`. Informs the host/audio thread that an adjustment was made, as part of a change gesture.

Parameters

context	The editor context.
args	The args provided by the frontend.

Returns

An empty value if everything went well, the exception message if parsing the args failed.

sendEvent()

virtual void mostly_harmless::gui::WebviewEditor::sendEvent ( events::WebEvent && event )

virtualnoexcept

Sends a javascript event to the internal webview.
You're also totally free to overload this if you don't like the default impl - see events::WebEvent for details about the WebEvent structure.

Parameters

event

An rvalue ref to the event to dispatch - you can create arbitrary custom types of event.

Member Data Documentation

m_sharedState

core::ISharedState* mostly_harmless::gui::WebviewEditor::m_sharedState { nullptr }

protected

---

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

• /home/runner/work/mostly-harmless/mostly-harmless/include/mostly_harmless/gui/mostlyharmless_WebviewEditor.h