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:

IUIFactory Provides the XML description and creates the controller object(s)
IPlugController
IGenericPlugController
Provides IParameter objects for each value,
is notified on value changes
IViewFactory Creates Plug-In specific views (-> IPlugView)
Used to combine the XML technology with other GUI Toolkits (e.g. VSTGUI, MFC,...)

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

Inheritance: FUnknown <- IUIFactory <- IUIFactory2
Include File:  iplugui.h

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

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

The host requests the size of the editor, name specifies the context in which the editor will be used (usually "editor").


IEditorFactory::createEditor

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.



Copyright ©2004 Steinberg Media Technologies GmbH. All Rights Reserved.
Last Modified: