VSTGUI 4.5 Graphical User Interface Framework not only for VST plugins

- Main Page
- Related Pages
- Modules
- Namespaces
- Classes

All Classes Namespaces Functions Variables Typedefs Enumerations Enumerator Friends Groups Pages
Inline UI Editing for VST3 (WYSIWYG)

- Introduction
- Setup
- Building and editing
  - VSTGUI Inspector
  - Context Menu
- Parameter Binding
- Creating Custom Views
- Sub-Controllers
- Templates
- Misc

# Introduction

VSTGUI now supports easy and fast UI creation for VST3 plug-ins.

It will automatically support the following VST3 features (only if you have met the requirements for Parameter Binding):

- IParameterFinder (find parameter under mouse)
- IContextMenu (show host context menu on right click for an automatable parameter) [VST3.5 SDK required]

Note that you need at least VST SDK 3.1, any earlier version will not work.

# Setup

- Add the following files to your project (in addition to the other vstgui files, see Setup)
  - plugin-bindings/vst3editor.cpp
  - Windows only: vstgui_uidescription_win32.cpp
  - Mac OS X only: vstgui_uidescription_mac.mm
- Add VSTGUI_LIVE_EDITING=1 to your preprocessor definitions (only for your debug builds)
- Modify your VST Edit Controller class to add the createView(..) method :
  IPlugView* PLUGIN_API MyEditController::createView (FIDString name)
  {
  if (strcmp (name, ViewType::kEditor) == 0)
  {
  return new VSTGUI::VST3Editor (this, "view", "myEditor.uidesc");
  }
  return 0;
  }
- Create an empty myEditor.uidesc file and save it somewhere in your project file hierarchy
- On Windows add a line to your .rc file :

      myEditor.uidesc DATA "realtive/path/to/myEditor.uidesc"

- On Mac OS X add the myEditor.uidesc file to your Xcode project and make sure that it is copied to the Resources folder of the vst3 bundle

# Building and editing

Now you can build your project, start any VST3 host and open an instance of your plugin.

If you open the editor of your plug-in you will initially see a black editor.

To start editing the user interface you need to make a right click on your editor and choose the "Enable Editing" menu item. When you do this the VSTGUI Inspector window will open and you can start editing.

If you are done with it, make sure to use the "Save..." command in the Context Menu to save the changes to the myEditor.uidesc. Then you can choose the "Disable Editing" command to test your user interface.

## VSTGUI Inspector

The VSTGUI Inspector is used for defining Bitmaps, Colors, Fonts and Tags and to edit view attributes.

On the top of the window are 5 tabs:

- Attributes Tab
- Bitmaps Tab
- Colors Tab
- Fonts Tab
- Tags Tab

## Attributes Tab

This tab contains the attributes of the view or views currently selected in your editor. The shown attributes depend on the selected view. If you have multiple views selected only those attributes are shown which are valid for all views. If the values of the attributes differ between the views they are shown in a different color.

## Bitmaps Tab

In this tab you define your bitmaps.

- the name column describes the name you use in the view attributes.
- the bitmap column describes the name in your resources.
- the NinePartsOffset is used for bitmaps which will use the VSTGUI::CNinePartTiledBitmap class to draw a tiled bitmap. The value needs to be 4 integers describing the left, top, right, bottom offsets separated by commas.

## Colors Tab

In this tab you define your colors.

- the name column describes the name you use in the view attributes.
- the color column describes the color value. If you click on it, a color chooser window will open and you can change the color. You can switch to any other tab while the color chooser is open and you can still change the color.

There are predefined colors whose names start with a '~'. You cannot change any of them.

## Fonts Tab

In this tab you define your fonts.

- the name column describes the name you use in the view attributes.
- the font column describes the font. If you click on it, a font chooser window will open and you can change the font. You can switch to any other tab while the font chooser is open and you can still change the font.

There are predefined fonts whose names start with a '~'. You cannot change any of them.

## Tags Tab

In this tab you define your tags.

- the name column describes the name you use in the view attributes.
- the tag column describes the tags used in VSTGUI::CControl. See also Parameter Binding.

## Context Menu

Here is a brief description of the items in the context menu :

- Undo : Undo last action
- Redo : Redo last undo action
- Size To Fit : Size views to fit according to its attributes (calls CView::sizeToFit() internally).
- Unembed Views : If you have a container view selected, it will move all children out of it and delete it.
- Delete : Delete all selected views.
- Insert Subview : Insert the view chosen in the submenu at the current mouse location. If a container view is selected it is placed into it, otherwise it uses the deepest container view found under the mouse.
- Embed Into : Insert the selected views into the container view chosen in the submenu.
- Insert Template : Insert the template chosen in the submenu at the current mouse location. If a container view is selected it is placed into it, otherwise it uses the deepest container view found under the mouse. See Templates.
- Transform View Type : Transform the selected view into the view chosen in the submenu.
- Grid : Set the grid option.
- Save... : Save the xml file to disk.
- Show Hierarchy Browser : Show the view hierarchy browser.
- Template Settings... : Open the template settings dialog.
- Change Template : Change the editor to another template.
- Add New Template : Create a new template and show it.
- Sync Parameter Tags : Sync the parameter ids of the VST Edit Controller with the tags. This is not undoable.
- Disable Editing : Disable editing. This also erases the undo stack.

# Parameter Binding

If you've used the Parameter class provided by the VST3 SDK, you will get automatic parameter bindings between the controls of your editor and the parameters in your VST Edit Controller.

The only thing you need to do is to declare the ids of the parameters as tags in the VSTGUI Inspector (or use the 'Sync Parameter Tags' command in the Context Menu) and set the tags of your controls to these ids. After you've done this your VST Edit Controller will receive the beginEdit(..)/performEdit(..)/endEdit(..) calls when the user changes the controls and if the host automates the parameter the control will also reflect these changes.

As an addition you can modify your VST Edit Controller to return specific parameter objects in the getParameterObject(int32 paramID) method for UI only needs, which are not parameters of your VST audio processor. This way you can store view settings like the tab which is open when the user closes the editor so that you can restore it when the user opens the editor again. You can look at the sources of the included 'uidescription test' project how this works.

# Creating Custom Views

If you need to create custom views, you can implement the VSTGUI::VST3EditorDelegate interface in your edit controller class. The createCustomView method will be called if you set the 'custom-view-name' attribute in one of the views.

Another way to use your own views is to register them at runtime with the UIViewFactory. This method requires more work but has the advantage that the view will be listed like the built-in views and changing attributes work on the fly. See VSTGUI::IViewCreator.

# Sub-Controllers

Sub-Controllers are useful if you need finer control of your views. You can define Sub-Controllers for views with the 'sub-controller' attribute. Sub-Controllers will be created via the VSTGUI::VST3EditorDelegate interface. When they are created they are owned by the VSTGUI::VST3Editor object.

The VSTGUI::DelegationController is a helper class if you don't want to control every aspect of the views by forwarding every call to its parent controller. You only overwrite the methods you need in your inherited class.

If you want to be notified about value changes for controls in your sub-controller but don't want to loose the Parameter Binding you can add your sub-controller as dependent of the control:

class MyController : public DelegationController, public CBaseObject
{
public:
MyController (IController* baseController) : DelegationController (baseController), controlView (0) {}
~MyController ()
{
if (controlView)
{
controlView->removeDependent (this);
controlView->forget ();
}
}
CView* verifyView (CView* view, const UIAttributes& attributes, IUIDescription* description)
{
CControl* control = dynamic_cast<CControl*> (view);
if (control && control->getTag () == 20)
{
controlView = control;
controlView->addDependent (this);
controlView->remember ();
}
return controller->verifyView (view, attributes, description);
}
CMessageResult notify (CBaseObject* sender, IdStringPtr message)
{
if (sender == controlView)
{
if (message == CControl::kMessageValueChanged)
{
// do something
}
return kMessageNotified;
}
return kMessageUnknown;
}
protected:
CControl* controlView;
};

# Templates

Templates are root views where you can group controls in logical entities. You can embed Templates into other Templates. Some views like the VSTGUI::UIViewSwitchContainer shows different Templates depending on a control value.

# Misc

- For your deployment versions make sure to set the VSTGUI_LIVE_EDITING definition to zero.