Table of Contents

Class PluginUIController<TModel>

Namespace
PluginUI.NPlug
Assembly
PluginUI.NPlug.dll

Base edit controller for plug-ins with a PluginUI editor: implements IParameterEditSink on top of NPlug's concurrent edit support, creates the view on Windows only, sends the notes played on the editor to the processor, receives the processor's shared state and provides MIDI learn.

public abstract class PluginUIController<TModel> : AudioController<TModel>, IAudioConnectionPoint, IAudioControllerExtended, IAudioControllerUnitInfo, IAudioControllerMidiMapping, IParameterEditSink, IAudioControllerMidiLearn, IAudioController, IAudioPluginComponent, IAudioPluginObject where TModel : AudioProcessorModel, new()

Type Parameters

TModel

Parameter model shared with the processor.

Inheritance
AudioPluginComponent
AudioController<TModel>
PluginUIController<TModel>
Implements
IAudioConnectionPoint
IAudioControllerExtended
IAudioControllerUnitInfo
IAudioControllerMidiMapping
IAudioControllerMidiLearn
IAudioController
IAudioPluginComponent
IAudioPluginObject
Inherited Members
AudioController<TModel>.Initialize(AudioHostApplication)
AudioController<TModel>.RestoreComponentState(PortableBinaryReader)
AudioController<TModel>.TrySetKnobMode(AudioControllerKnobModes)
AudioController<TModel>.SetMidiCCMapping(AudioMidiControllerNumber, AudioParameter)
AudioController<TModel>.IsEditingParameter(AudioParameter)
AudioController<TModel>.BeginGroupEditParameters()
AudioController<TModel>.EndGroupEditParameters()
AudioController<TModel>.BeginEditParameter(AudioParameter)
AudioController<TModel>.EndEditParameter(AudioParameter)
AudioController<TModel>.EndEditParameter()
AudioController<TModel>.RestartComponent(AudioRestartFlags)
AudioController<TModel>.ClearMapBusToUnit()
AudioController<TModel>.Model
AudioController<TModel>.Handler
AudioController<TModel>.MapMidiCCToAudioParameter
AudioController<TModel>.EditedParameter
AudioController<TModel>.EditedParameterCount
AudioController<TModel>.SelectedUnit
AudioPluginComponent.Terminate()
AudioPluginComponent.Host
AudioPluginComponent.ConnectionPoint

Examples

public sealed class MyController : PluginUIController<MyModel>
{
    protected override PluginEditorView CreateEditor() => new MyEditor(this);
}

Remarks

MIDI learn (MidiLearn, offered when IsMidiLearnEnabled is set): the controller implements VST3 IMidiLearn and IMidiMapping; learned assignments are saved with the controller state by SaveState(PortableBinaryWriter) and read back by RestoreState(PortableBinaryReader). Derived classes that store their own controller data call the base method first.

Override OnMessage(AudioMessage) or OnConnect(IAudioConnectionPoint) only with a call to the base method.

Constructors

PluginUIController()

Creates the controller.

protected PluginUIController()

Properties

IsMidiLearnEnabled

When true, the editor's context menus offer MIDI learn. Default false: enable it for plug-ins with an event input (instruments, MIDI-controlled effects), since hosts send MIDI controllers only to those. Learned assignments apply whatever this setting.

public bool IsMidiLearnEnabled { get; set; }

Property Value

bool

MidiLearn

MIDI learn service (assign MIDI controllers to parameters from the editor's context menu).

public NPlugMidiLearn MidiLearn { get; }

Property Value

NPlugMidiLearn

SharedState

Object shared by the processor (CreateSharedState()), or null until the components are connected (or if the processor shares nothing).

public object? SharedState { get; }

Property Value

object

Methods

CreateEditor()

Creates the editor view (called on Windows 10 1809+ only).

protected abstract PluginEditorView? CreateEditor()

Returns

PluginEditorView

CreateView()

Create a view for this controller. This is called by NPlug.IAudioController.CreateView().

protected override IAudioPluginView? CreateView()

Returns

IAudioPluginView

OnConnect(IAudioConnectionPoint)

Called when this component is connected to another component.

protected override void OnConnect(IAudioConnectionPoint connectionPoint)

Parameters

connectionPoint IAudioConnectionPoint

OnDisconnect(IAudioConnectionPoint)

Called when this component is disconnected from another component.

protected override void OnDisconnect(IAudioConnectionPoint connectionPoint)

Parameters

connectionPoint IAudioConnectionPoint

OnLiveMidiControllerInput(int, short, AudioMidiControllerNumber)

Live MIDI controller reported by the host (VST3 IMidiLearn, UI thread).

protected virtual bool OnLiveMidiControllerInput(int busIndex, short channel, AudioMidiControllerNumber midiCC)

Parameters

busIndex int

Event input bus.

channel short

MIDI channel, 0-based.

midiCC AudioMidiControllerNumber

Controller number.

Returns

bool

true if a learn completed.

OnMessage(AudioMessage)

Called when this component receives a message from another component.

protected override void OnMessage(AudioMessage message)

Parameters

message AudioMessage

The message. The sender owns it: it is valid during this call only and must not be disposed.

OnParameterValueChanged(AudioParameter, bool)

This method is called whenever a parameter value is changed in the model. It will replicate the change to the host via the NPlug.AudioController<TAudioControllerModel>.Handler.

protected override void OnParameterValueChanged(AudioParameter parameter, bool parameterValueChangedFromHost)

Parameters

parameter AudioParameter

The audio parameter that changed.

parameterValueChangedFromHost bool

true if the value was changed by the host.

Remarks

Without a host connection (tests, snapshots, standalone use) changes are kept in the model only.

Exceptions

InvalidOperationException

RestoreState(PortableBinaryReader)

This method is called by the host when restoring the state of this controller (different from the audio processor component state).

protected override void RestoreState(PortableBinaryReader reader)

Parameters

reader PortableBinaryReader

The reader stream to restore specific controller data.

Remarks

Reads the learned MIDI assignments; overrides call this first, then read their own data.

SaveState(PortableBinaryWriter)

This method is called by the host when saving the state of this controller (different from the audio processor component state).

protected override void SaveState(PortableBinaryWriter writer)

Parameters

writer PortableBinaryWriter

The writer stream to store specific controller data.

Remarks

Writes the learned MIDI assignments; overrides call this first, then write their own data.

SendNote(UINoteEvent)

Sends a note played on the editor to the processor (UI thread).

public bool SendNote(UINoteEvent note)

Parameters

note UINoteEvent

The note event.

Returns

bool

false if the processor is not connected.

TryGetMidiControllerAssignment(int, int, AudioMidiControllerNumber, out AudioParameterId)

Gets an (preferred) associated NPlug.AudioParameterId for a given Input Event Bus index, channel and MIDI Controller.

protected override bool TryGetMidiControllerAssignment(int busIndex, int channel, AudioMidiControllerNumber midiControllerNumber, out AudioParameterId id)

Parameters

busIndex int

The index of the bus.

channel int

The index of the channel.

midiControllerNumber AudioMidiControllerNumber

The MIDI CC number.

id AudioParameterId

The output parameter id.

Returns

bool

true if the midiControllerNumber is associated with a parameter; false otherwise.

Remarks

Learned assignments first, then the fixed mappings declared with SetMidiCCMapping.

TryGetSharedState<T>(out T?)

Typed access to SharedState.

public bool TryGetSharedState<T>(out T? state) where T : class

Parameters

state T

The shared object.

Returns

bool

true if the processor shares an object of this type.

Type Parameters

T

Type of the shared object.

Events

SharedStateChanged

Raised on the UI thread when SharedState becomes available.

public event Action? SharedStateChanged

Event Type

Action
Edit this page