iPlug 2: IEditorDelegate Class Reference
This pure virtual interface delegates communication in both directions between a UI editor and something else (which is usually a plug-in) It is also the class that owns parameter objects (for historical reasons) - although it's not necessary to allocate them. More...
#include <IPlugEditorDelegate.h>
Public Member Functions | |
| IEditorDelegate (int nParams) | |
| IEditorDelegate (const IEditorDelegate &)=delete | |
| IEditorDelegate & | operator= (const IEditorDelegate &)=delete |
| IParam * | AddParam () |
| Adds an IParam to the parameters ptr list Note: This is only used in special circumstances, since most plug-in formats don't support dynamic parameters. More... | |
| void | RemoveParam (int idx) |
| Remove an IParam at a particular index Note: This is only used in special circumstances, since most plug-in formats don't support dynamic parameters. More... | |
| IParam * | GetParam (int paramIdx) |
| Get a pointer to one of the delegate's IParam objects. More... | |
| const IParam * | GetParam (int paramIdx) const |
| Get a const pointer to one of the delegate's IParam objects (for const methods) More... | |
| int | NParams () const |
| virtual void * | OpenWindow (void *pParent) |
| If you are not using IGraphics, you can implement this method to attach to the native parent view e.g. More... | |
| virtual void | CloseWindow () |
| If you are not using IGraphics you can if you need to free resources etc when the window closes. More... | |
| virtual void | OnParentWindowResize (int width, int height) |
| Called by app wrappers when the OS window scaling buttons/resizers are used. More... | |
| virtual void | OnUIOpen () |
| Override this method to do something before the UI is opened. More... | |
| virtual void | OnUIClose () |
| Override this method to do something before the UI is closed. More... | |
| virtual void | OnParamChange (int paramIdx, EParamSource source, int sampleOffset=-1) |
| Override this method to do something to your DSP when a parameter changes. More... | |
| virtual void | OnParamChange (int paramIdx) |
| Another version of the OnParamChange method without an EParamSource, for backwards compatibility / simplicity. More... | |
| virtual void | OnParamChangeUI (int paramIdx, EParamSource source=kUnknown) |
| Override this method to do something when a parameter changes on the main/UI thread Like OnParamChange, OnParamChangeUI will be called when a parameter changes. More... | |
| virtual void | OnParamReset (EParamSource source) |
| Called when parameters have changed to inform the plugin of the changes Override only if you need to handle notifications and updates in a specialist manner (e.g. More... | |
| virtual void | OnMidiMsgUI (const IMidiMsg &msg) |
| Handle incoming MIDI messages sent to the user interface. More... | |
| virtual void | OnSysexMsgUI (const ISysEx &msg) |
| Handle incoming SysEx messages sent to the user interface. More... | |
| virtual bool | OnMessage (int msgTag, int ctrlTag, int dataSize, const void *pData) |
| This could be implemented in either DSP or EDITOR to receive a message from the other one. More... | |
| virtual void | OnRestoreState () |
| This is called by API classes after restoring state and by IPluginBase::RestorePreset(). More... | |
| virtual bool | OnKeyDown (const IKeyPress &key) |
| KeyDown handler, in order to get keystrokes from certain hosts/plugin formats that send key press messages through the plug-in API, rather than the view. More... | |
| virtual bool | OnKeyUp (const IKeyPress &key) |
| KeyDown handler, in order to get keystrokes from certain hosts/plugin formats that send key press messages through the plug-in API rather than the view. More... | |
| void | SendCurrentParamValuesFromDelegate () |
| Loops through all parameters, calling SendParameterValueFromDelegate() with the current value of the parameter This is important when modifying groups of parameters, restoring state and opening the UI, in order to update it with the latest values. More... | |
| virtual void | SendControlValueFromDelegate (int ctrlTag, double normalizedValue) |
| SendControlValueFromDelegate (Abbreviation: SCVFD) WARNING: should not be called on the realtime audio thread. More... | |
| virtual void | SendControlMsgFromDelegate (int ctrlTag, int msgTag, int dataSize=0, const void *pData=nullptr) |
| SendControlMsgFromDelegate (Abbreviation: SCMFD) WARNING: should not be called on the realtime audio thread. More... | |
| virtual void | SendArbitraryMsgFromDelegate (int msgTag, int dataSize=0, const void *pData=nullptr) |
| SendArbitraryMsgFromDelegate (Abbreviation: SAMFD) WARNING: should not be called on the realtime audio thread. More... | |
| virtual void | SendMidiMsgFromDelegate (const IMidiMsg &msg) |
| SendMidiMsgFromDelegate (Abbreviation: SMMFD) WARNING: should not be called on the realtime audio thread. More... | |
| virtual void | SendSysexMsgFromDelegate (const ISysEx &msg) |
| SendSysexMsgFromDelegate (Abbreviation: SSMFD) WARNING: should not be called on the realtime audio thread. More... | |
| virtual void | SendParameterValueFromDelegate (int paramIdx, double value, bool normalized) |
| SendParameterValueFromDelegate (Abbreviation: SPVFD) WARNING: should not be called on the realtime audio thread. More... | |
| virtual void | DirtyParametersFromUI () |
| When modifying a range of parameters in the editor, it can be necessary to broadcast that fact via the host, for instance in a distributed plug-in. More... | |
| virtual void | BeginInformHostOfParamChangeFromUI (int paramIdx)=0 |
| Called by the UI at the beginning of a parameter change gesture, in order to notify the host (via a call in the API class) that the parameter is going to be modified The host may be trying to automate the parameter as well, so it needs to relinquish control when the user is modifying something in the user interface. More... | |
| virtual void | SendParameterValueFromUI (int paramIdx, double normalizedValue) |
| SPVFUI Called by the UI during a parameter change gesture, in order to notify the host of the new value (via a call in the API class) If you override this method you should call the base class implementation to make sure OnParamChangeUI gets triggered. More... | |
| virtual void | EndInformHostOfParamChangeFromUI (int paramIdx)=0 |
| Called by the user interface at the end of a parameter change gesture, in order to notify the host (via a call in the API class) that the parameter is no longer being modified The host may be trying to automate the parameter as well, so it needs to relinquish control when the user is modifying something in the user interface. More... | |
| virtual bool | EditorResizeFromUI (int viewWidth, int viewHeight, bool needsPlatformResize) |
| If the editor changes UI dimensions, e.g. More... | |
| virtual void | SendMidiMsgFromUI (const IMidiMsg &msg) |
| SendMidiMsgFromUI (Abbreviation: SMMFUI) This method should be used when sending a MIDI message from the UI. More... | |
| virtual void | SendSysexMsgFromUI (const ISysEx &msg) |
| SendSysexMsgFromUI (Abbreviation: SSMFUI) If a plug-in can send Sysex data as a result of actions in the user interface, this method can be used. More... | |
| virtual void | SendArbitraryMsgFromUI (int msgTag, int ctrlTag=kNoTag, int dataSize=0, const void *pData=nullptr) |
| SendArbitraryMsgFromUI (Abbreviation: SAMFUI) More... | |
| virtual void | DeferMidiMsg (const IMidiMsg &msg) |
| This method is needed, for remote editors to avoid a feedback loop. More... | |
| virtual void | DeferSysexMsg (const ISysEx &msg) |
| This method is needed, for remote editors to avoid a feedback loop. More... | |
| void | SetEditorSize (int width, int height) |
| void | SetSizeConstraints (int widthLo, int widthHi, int heightLo, int heightHi) |
| Sets the minimum and maximum size constraints for the editor window. More... | |
| int | GetEditorWidth () const |
| int | GetEditorHeight () const |
| int | GetMinWidth () const |
| int | GetMaxWidth () const |
| int | GetMinHeight () const |
| int | GetMaxHeight () const |
| virtual bool | ConstrainEditorResize (int &w, int &h) const |
| Constrain the incoming editor width and height values based on the minimum and maximum. More... | |
| virtual bool | SerializeEditorState (IByteChunk &chunk) const |
| Serializes the editor state (such as scale) into a binary chunk. More... | |
| virtual int | UnserializeEditorState (const IByteChunk &chunk, int startPos) |
| Unserializes editor state (such as scale). More... | |
| virtual void | SetScreenScale (float scale) |
| Can be used by a host API to inform the editor of screen scale changes. More... | |
Friends | |
| class | IPlugAPP |
| class | IPlugAAX |
| class | IPlugVST2 |
| class | IPlugVST3 |
| class | IPlugVST3Controller |
| class | IPlugVST3Processor |
| class | IPlugAU |
| class | IPlugAUv3 |
| class | IPlugWEB |
| class | IPlugWAM |
| class | IPlugAPIBase |
| class | IPluginBase |
This pure virtual interface delegates communication in both directions between a UI editor and something else (which is usually a plug-in) It is also the class that owns parameter objects (for historical reasons) - although it's not necessary to allocate them.
This is the lowest level base class in iPlug 2 that facilitates distributing editor and DSP parts for plug-in formats that need that, but also allowing non-distributed plug-ins to use the same API. In distributed plug-in architectures certain methods will be overridden in order to pipe messages to various places, using whatever mechanism that plug-in format requires. In this case, there are actually two classes that implement the IEditorDelegate interface, but only one which is directly connected to the user interface (IGraphics etc.), the other being connected to a class inheriting IPlugAPIBase that deals with processing audio, see for example IPlugVST3Processor
Note on method names:
- "FromUI" in a method name, means that that method is called by something in the UI i.e. when the user interacts with a control.
- "FromDelegate" in a method name means that method is called from a class that implements the IEditorDelegate interface, which is usually your plug-in base class, but may not be in the case of an isolated editor class, or if you are using IGraphics without IPlug, and your IEditorDelegate is not a plug-in
NOTES: A parameter VALUE is a floating point number linked to an integer parameter index. TODO: Normalised ? A parameter OBJECT (IParam) is an instance of the IParam class as defined in IPlugParameter.h A parameter OBJECT is also referred to as a "param", in method names such as IEditorDelegate::GetParam(int paramIdx) and IControl::GetParam().
Definition at line 48 of file IPlugEditorDelegate.h.
|
inline |
◆ ~IEditorDelegate()
|
inlinevirtual |
◆ AddParam()
|
inline |
Adds an IParam to the parameters ptr list Note: This is only used in special circumstances, since most plug-in formats don't support dynamic parameters.
- Returns
- Ptr to the newly created IParam object
Definition at line 68 of file IPlugEditorDelegate.h.
◆ BeginInformHostOfParamChangeFromUI()
|
pure virtual |
Called by the UI at the beginning of a parameter change gesture, in order to notify the host (via a call in the API class) that the parameter is going to be modified The host may be trying to automate the parameter as well, so it needs to relinquish control when the user is modifying something in the user interface.
- Parameters
-
paramIdx The index of the parameter that is changing value
Referenced by WebViewEditorDelegate::OnMessageFromWebView(), IGraphics::OnMouseDown(), and IVNumberBoxControl::OnMouseDown().
◆ CloseWindow()
|
inlinevirtual |
◆ ConstrainEditorResize()
|
inlinevirtual |
Constrain the incoming editor width and height values based on the minimum and maximum.
- Parameters
-
w the incoming width value to test/set if clipping needed h the incoming height value to test/set if clipping needed
- Returns
trueif the parameters fell withing the permitted range
Definition at line 321 of file IPlugEditorDelegate.h.
References Clip().
Referenced by IGraphics::Resize().
◆ DeferMidiMsg()
|
inlinevirtual |
This method is needed, for remote editors to avoid a feedback loop.
Definition at line 285 of file IPlugEditorDelegate.h.
◆ DeferSysexMsg()
|
inlinevirtual |
This method is needed, for remote editors to avoid a feedback loop.
Definition at line 288 of file IPlugEditorDelegate.h.
◆ DirtyParametersFromUI()
|
inlinevirtual |
When modifying a range of parameters in the editor, it can be necessary to broadcast that fact via the host, for instance in a distributed plug-in.
You can use it if you restore a preset using a custom preset mechanism.
Definition at line 233 of file IPlugEditorDelegate.h.
◆ EditorResizeFromUI()
|
inlinevirtual |
If the editor changes UI dimensions, e.g.
from clicking a button to choose a size or dragging a corner resizer, it needs to call into the plug-in API to resize the window in the plugin returns a bool to indicate whether the DAW or plugin class has resized the host window
Definition at line 262 of file IPlugEditorDelegate.h.
Referenced by IGraphics::Resize(), and IGraphics::SetScreenScale().
◆ EndInformHostOfParamChangeFromUI()
|
pure virtual |
◆ GetEditorHeight()
|
inline |
◆ GetEditorWidth()
|
inline |
◆ GetMaxHeight()
|
inline |
◆ GetMaxWidth()
|
inline |
◆ GetMinHeight()
|
inline |
◆ GetMinWidth()
|
inline |
◆ GetParam() [1/2]
|
inline |
◆ GetParam() [2/2]
|
inline |
Get a const pointer to one of the delegate's IParam objects (for const methods)
- Parameters
-
paramIdx The index of the parameter object to be got
- Returns
- A pointer to the IParam object at paramIdx or nullptr if paramIdx is invalid
Definition at line 83 of file IPlugEditorDelegate.h.
◆ NParams()
|
inline |
◆ OnKeyDown()
|
inlinevirtual |
KeyDown handler, in order to get keystrokes from certain hosts/plugin formats that send key press messages through the plug-in API, rather than the view.
- Parameters
-
key Information about the key that was pressed
- Returns
trueif the key was handled by the plug-in
Reimplemented in IGEditorDelegate, and WebViewEditorDelegate.
Definition at line 157 of file IPlugEditorDelegate.h.
◆ OnKeyUp()
|
inlinevirtual |
KeyDown handler, in order to get keystrokes from certain hosts/plugin formats that send key press messages through the plug-in API rather than the view.
- Parameters
-
key Information about the key that was released
- Returns
trueif the key was handled by the plug-in
Reimplemented in IGEditorDelegate, and WebViewEditorDelegate.
Definition at line 162 of file IPlugEditorDelegate.h.
◆ OnMessage()
|
inlinevirtual |
◆ OnMidiMsgUI()
|
inlinevirtual |
◆ OnParamChange() [1/2]
|
inlinevirtual |
Another version of the OnParamChange method without an EParamSource, for backwards compatibility / simplicity.
WARNING: this method can in some cases be called on the realtime audio thread
Definition at line 118 of file IPlugEditorDelegate.h.
◆ OnParamChange() [2/2]
|
inlinevirtual |
Override this method to do something to your DSP when a parameter changes.
WARNING: this method can in some cases be called on the realtime audio thread
- Parameters
-
paramIdx The index of the parameter that changed source One of the EParamSource options to indicate where the parameter change came from. sampleOffset For sample accurate parameter changes - index into current block
Definition at line 110 of file IPlugEditorDelegate.h.
References OnParamChange().
Referenced by OnParamChange(), and OnParamReset().
◆ OnParamChangeUI()
|
inlinevirtual |
Override this method to do something when a parameter changes on the main/UI thread Like OnParamChange, OnParamChangeUI will be called when a parameter changes.
However, whereas OnParamChange may be called on the audio thread and should be used to update DSP state, OnParamChangeUI is always called on the low-priority thread, should be used to update UI (e.g. for hiding or showing controls). You should not update parameter objects using this method.
- Parameters
-
paramIdx The index of the parameter that changed
Reimplemented in CocoaEditorDelegate.
Definition at line 124 of file IPlugEditorDelegate.h.
Referenced by OnParamReset(), SendParameterValueFromDelegate(), and SendParameterValueFromUI().
◆ OnParamReset()
|
inlinevirtual |
Called when parameters have changed to inform the plugin of the changes Override only if you need to handle notifications and updates in a specialist manner (e.g.
if the ordering of updating parameters has an effect or if you need to avoid multiple settings of linked parameters). This must update both DSP and UI. The default implementation calls OnParamChange() and OnParamChangeUI() for each parameter.
- Parameters
-
source Specifies the source of the parameter changes
Definition at line 129 of file IPlugEditorDelegate.h.
References NParams(), OnParamChange(), and OnParamChangeUI().
◆ OnParentWindowResize()
|
inlinevirtual |
◆ OnRestoreState()
|
inlinevirtual |
This is called by API classes after restoring state and by IPluginBase::RestorePreset().
Typically used to update user interface, where multiple parameter values have changed. If you need to do something when state is restored you can override it If you override this method you should call this parent, or implement the same functionality in order to get controls to update, when state is restored.
Definition at line 152 of file IPlugEditorDelegate.h.
References SendCurrentParamValuesFromDelegate().
◆ OnSysexMsgUI()
|
inlinevirtual |
◆ OnUIClose()
|
inlinevirtual |
◆ OnUIOpen()
|
inlinevirtual |
◆ OpenWindow()
|
inlinevirtual |
◆ RemoveParam()
|
inline |
Remove an IParam at a particular index Note: This is only used in special circumstances, since most plug-in formats don't support dynamic parameters.
- Parameters
-
idx The index of the parameter to remove
Definition at line 73 of file IPlugEditorDelegate.h.
◆ SendArbitraryMsgFromDelegate()
|
inlinevirtual |
SendArbitraryMsgFromDelegate (Abbreviation: SAMFD) WARNING: should not be called on the realtime audio thread.
This method can be used to send opaque data from a class implementing IEditorDelegate to the IEditorDelegate connected to the user interface The message can be handled at the destination via IEditorDelegate::OnMessage()
- Parameters
-
msgTag A unique tag to identify the message dataSize The size in bytes of the data payload pointed to by pData. Note: if this is nonzero, pData must be valid. pData Ptr to the opaque data payload for the message
Reimplemented in WebViewEditorDelegate.
Definition at line 201 of file IPlugEditorDelegate.h.
References OnMessage().
◆ SendArbitraryMsgFromUI()
|
inlinevirtual |
◆ SendControlMsgFromDelegate()
|
inlinevirtual |
◆ SendControlValueFromDelegate()
|
inlinevirtual |
SendControlValueFromDelegate (Abbreviation: SCVFD) WARNING: should not be called on the realtime audio thread.
In IGraphics plug-ins, this method is used to update controls in the user interface from a class implementing IEditorDelegate, when the control is not linked to a parameter. A typical use case would be a meter control. In OnIdle() your plug-in would call this method to update the IControl's value.
- Parameters
-
ctrlTag A tag for the control normalizedValue The normalised value to set the control to. This will modify IControl::mValue;
Reimplemented in IGEditorDelegate, CocoaEditorDelegate, and WebViewEditorDelegate.
Definition at line 182 of file IPlugEditorDelegate.h.
◆ SendCurrentParamValuesFromDelegate()
|
inline |
◆ SendMidiMsgFromDelegate()
|
inlinevirtual |
◆ SendMidiMsgFromUI()
|
inlinevirtual |
◆ SendParameterValueFromDelegate()
|
inlinevirtual |
◆ SendParameterValueFromUI()
|
inlinevirtual |
◆ SendSysexMsgFromDelegate()
|
inlinevirtual |
SendSysexMsgFromDelegate (Abbreviation: SSMFD) WARNING: should not be called on the realtime audio thread.
This method can be used to send SysEx data from the class implementing IEditorDelegate to the user interface The message can be handled at the destination via IEditorDelegate::OnSysexMsgUI()
- Parameters
-
msg an ISysEx Containing the SysEx data to send to the user interface.
Definition at line 215 of file IPlugEditorDelegate.h.
References OnSysexMsgUI().
◆ SendSysexMsgFromUI()
|
inlinevirtual |
SendSysexMsgFromUI (Abbreviation: SSMFUI) If a plug-in can send Sysex data as a result of actions in the user interface, this method can be used.
Unlike SendMidiMsgFromUI, Sysex messages will not be received in IPlugProcessor::ProcessSysex()
- Parameters
-
msg The Sysex message to send.
Definition at line 274 of file IPlugEditorDelegate.h.
◆ SerializeEditorState()
|
inlinevirtual |
Serializes the editor state (such as scale) into a binary chunk.
- Parameters
-
chunk The output chunk to serialize to. Will append data if the chunk has already been started.
- Returns
trueif the serialization was successful
Reimplemented in IGEditorDelegate.
Definition at line 338 of file IPlugEditorDelegate.h.
◆ SetEditorSize()
|
inline |
◆ SetScreenScale()
|
inlinevirtual |
◆ SetSizeConstraints()
|
inline |
Sets the minimum and maximum size constraints for the editor window.
- Parameters
-
widthLo Minimum width widthHi Maximum width heightLo Minimum height heightHi Maximum height
Definition at line 298 of file IPlugEditorDelegate.h.
◆ UnserializeEditorState()
|
inlinevirtual |
Unserializes editor state (such as scale).
- Parameters
-
chunk The incoming chunk where editor data is stored to unserialize startPos The start position in the chunk where parameter values are stored
- Returns
- The new chunk position (endPos)
Reimplemented in IGEditorDelegate.
Definition at line 344 of file IPlugEditorDelegate.h.
◆ IPlugAAX
◆ IPlugAPIBase
◆ IPlugAPP
◆ IPlugAU
◆ IPlugAUv3
◆ IPluginBase
◆ IPlugVST2
◆ IPlugVST3
◆ IPlugVST3Controller
◆ IPlugVST3Processor
◆ IPlugWAM
◆ IPlugWEB
The documentation for this class was generated from the following file: