Plug-In GUI
Plug-In GUI using XML
All recent Steinberg host applications provide the possibility to create a graphical editor
for a Plug-In via an XML description. I.e. the Plug-In is asked for a buffer with XML code
and a controller object and the host creates the corresponding control elements (buttons, sliders, menus, etc.).
The controller has to provide parameter objects for each value "behind" a visible control.
It receives notifications when the user manipulates the value. Setting the value via a parameter object
updates the corresponding control.
All interfaces involved in this mechanism can be found in iplugui.h:
The documentation of the XML tags used to describe a graphical user interface can be found in a separate document.
Plug-In GUI using VSTGUI
Steinberg provides a free cross-platform User Interface Kit for VST Plug-Ins, called VSTGUI.
A special version of the library is available which can be used in combination with the
VST Module Architecture.
If you want to use your own GUI Toolkit (e.g. MFC or Win32 controls) you
have to implement the IViewFactory or IEditorFactory interface and your own IPlugView.
Download VSTGUI
IUIFactory
Inheritance: FUnknown <- IUIFactory
Include File: iplugui.h
The interface IUIFactory signals the ability of a Plug-In to provide XML code for its
editor (or inspector view, etc.).
Methods:
IUIFactory::createController
Create a controller object, name describes the context in which the controller will be used (e.g.
"editor", "inspector",...). On return, c should point
to the newly created controller object. It will be released by the host when it is no longer needed.
Remarks:
Please note that the IUIFactory reference may be released BEFORE the controller is released.
In most cases it is sufficient to implement IUIFactory and IPlugController
in the same object. In this case you could implement IUIFactory::createController with a simple
queryInterface.
IUIFactory::getViewDescription
tresult PLUGIN_API getViewDescription (
char* name,
char* templateName,
char* xml,
long* bufferSize)
This method provides the XML code describing the Plug-In editor or inspector.
Parameters:
name |
Context string for the requested XML code (e.g. "editor", "inspector",...) |
templateName |
If the pointer is valid, the Plug-In has to copy the name of the XML template
to be created. The maximum length is 128 Bytes.
|
xml |
If the pointer is valid, the Plug-In has to copy the XML code to the buffer.
The host determines the required memory amount first (see remarks).
|
bufferSize |
If the pointer is valid, set this to the required memory amount for the XML code.
|
Remarks:
IUIFactory::getViewDescription may be called several times, with some of the pointers set to NULL e.g.
to determine the required memory amount for the XML code (see host example below).
IUIFactory* factory; // a valid factory reference
char templateName[128];
long xmlSize;
if(factory->getViewDescription ("editor", templateName, 0, &xmlSize) == kResultOk)
{
char* xml = new char[xmlSize];
if(factory->getViewDescription ("editor", 0, xml, 0) == kResultOk)
{
// create the editor...
}
delete [] xml;
}
IUIFactory2
IUIFactory2 provides access to resources inside the Plug-In which then can be used inside
the User Interface XML description (e.g. button bitmaps, ...).
Methods:
IUIFactory2::getResource
tresult PLUGIN_API getResource (
const char* path,
char* buffer,
long* bufferSize)
Copies the requested resource to a buffer.
Parameters:
path |
Resource path, as described in the XML code
e.g. <bitmap name="bitmap1" path="path_for_getResource"/>
|
buffer |
If the pointer is valid, the Plug-In has to copy the resource to the buffer.
The host determines the required memory amount first (see remarks).
|
bufferSize |
If the pointer is valid, set this to the required memory amount for the resource.
|
Remarks:
IUIFactory2::getResource may be called several times, with some of the pointers set to NULL e.g.
to determine the required memory amount for the resource.
Typical resources are images in the following formats: Windows Bitmap (BMP), PNG, JPEG, Photoshop (PSD),...
Windows: If the resources are located directly in the DLL, please make sure to include images
as raw resources (RCDATA, NOT as BITMAP)!!!
IViewFactory
Inheritance: FUnknown <- IViewFactory
Include File: iplugui.h
This interface allows Plug-Ins to mix their own views with controls, created by the host application.
It has to be implemented in the controller object,
NOT in the UI factory object!
Methods:
IViewFactory::createView
Create a Plug-In specific view.
Parameters:
name |
View name, as described in the XML template code |
rect |
View bounding rectangle, as described in the XML template code |
view |
On return, view has to point to the newly created view object.
It will be released by the host when no longer needed.
|
Remarks:
Example of XML code and the corresponding IViewFactory::createView call:
XML code:
<view name="MyCustomView" size="0,0,500,300"/>
Function call:
IViewFactory* viewFactory; // a valid view factory reference
ViewRect rect (0, 0, 500, 300);
IPlugView* view;
if(viewFactory->createView ("MyCustomView", &rect, &view) == kResultOk)
{
...
view->release ();
}
IViewFactory::testCondition
tresult PLUGIN_API testCondition (const char* condition)
Test a condition described in XML code.
Remarks:
Example of a condition and the corresponding IViewFactory::testCondition calls:
XML code:
<variant condition="mono AND NOT stereo"/>
...
</variant>
Function calls:
IViewFactory* viewFactory; // a valid view factory reference
if(viewFactory->testCondition ("mono") && !viewFactory->testCondition ("stereo"))
{
// condition is true
}
IPlugView
Inheritance: FUnknown <- IPlugView
Include File: iplugui.h
IPlugView represents a Plug-In specific view. It is created by
IViewFactory::createView or
IEditorFactory::createEditor.
Methods:
IPlugView::attached
tresult PLUGIN_API attached (void* parent)
The view was attached to a parent window.
The parent datatype is platform-dependent: On Windows it is a HWND, on MAC it is a WindowRef.
Remarks:
Windows : You have to create a child window here which receives mouse and painting messages.
Mac OS X : You have to attach a HIView to the parent window.
IPlugView::removed
tresult PLUGIN_API removed ()
The view was removed from its parent window.
Remarks:
Windows: You have to destroy the child window here.
IPlugView::idle
tresult PLUGIN_API idle ()
Host gives some idle time to the Plug-In view.
Remarks:
This method is called periodically, it can be used e.g. to do deferred updates, ...
IPlugView::onWheel
tresult PLUGIN_API onWheel (float distance)
Receive a mouse wheel event, distance is positive or negative to indicate the scroll direction.
IPlugView::onKey
tresult PLUGIN_API onKey (char asciiKey, long keyMsg, long modifiers)
Receive a key event; keyMsg and modifier values are defined in plugkeycodes.h.
IPlugView::onSize
tresult PLUGIN_API onSize ( ViewRect* newSize)
The view was moved or sized. This happens if the parent window is moved or resized and some of the
auto-size styles were specified in the XML code of this view.
Remarks:
Windows: You should resize the child window here.
IEditorFactory
Inheritance: FUnknown <- IEditorFactory
Include File: iplugui.h
IEditorFactory allows to build a Plug-In editor completely based on a another GUI toolkit
(e.g. VSTGUI, MFC, Win32, etc.), without using the XML features described above.
Methods:
IEditorFactory::getEditorSize
tresult PLUGIN_API getEditorSize (const char* name, ViewRect* rect)
The host requests the size of the editor, name specifies the context in which the editor will be used (usually "editor").
IEditorFactory::createEditor
tresult PLUGIN_API createEditor (const char* name, ViewRect* rect, IPlugView** editor)
Create the Plug-In editor.
Parameters:
name |
context string, usually "editor" |
rect |
size of the editor to be created.
The host will pass the size queried via IEditorFactory::getEditorSize
back to this method.
|
editor |
On return, editor has to point to the newly created editor object.
It will be released by the host when no longer needed.
|
Last Modified:
|