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
Getting Started Tutorial (VST 2.x)

This tutorial should give you a brief overview on how to get started using VSTGUI.

- VST Integration
- Adding views and controls
- Getting notification of control changes
  Note: If you are new to VST in general, consider using the VST3 SDK so that you can use Inline UI Editing for VST3 (WYSIWYG). The VST3 SDK includes a wrapper so that the VST3 plug-in can be used in hosts which only supports VST2.

# VST Integration

To add a user interface to a VST Plug-In with VSTGUI is quite simple.

Create a new class which inherits from AEffGUIEditor. Overwrite AEffGUIEditor::open and AEffGUIEditor::close.

class MyEditor : public AEffGUIEditor
{
public:
MyEditor (void* ptr) : AEffGUIEditor (ptr) {}
bool open (void* ptr);
void close ();
};

In MyEditor::open you create the CFrame.

bool MyEditor::open (void* ptr)
{
CRect frameSize (0, 0, 300, 300);
frame = new CFrame (frameSize, ptr, this);
return true;
}

In MyEditor::close you need to delete the CFrame

void MyEditor::close ()
{
delete frame;
frame = 0;
}

Now you just need to set the editor of your VST Plug-In to a new instance of MyEditor.

// somewhere in the constructor of your VST Plug-In
setEditor (new MyEditor (this));

So you have your own editor for a VST Plug-In. Now you need to add controls to it.

# Adding views and controls

- Loading images
- Creating views and adding them to the frame
- Creating a knob control

## Loading images

Most controls provided with VSTGUI use images. So you need to know how to load and use images in VSTGUI. To load an image, you just need to use the CBitmap class.

CBitmap* bitmap = new CBitmap ("MyBitmap.png");

The image "MyBitmap.png" must be defined in the .rc file on Windows like this :

MyBitmap.png DATA DISCARDABLE "MyBitmap.png"

On Mac OS X the image must be inside the Resources folder of the vst bundle.

## Creating views and adding them to the frame

Now that we have loaded an image, we want this image to be shown in our editor. The simplest way is to use the CView class, which is the base of all view and control classes.

CView* myView = new CView (CRect (0, 0, bitmap->getWidth (), bitmap->getHeight ()));
myView->setBackground (bitmap);

To actually get this shown, we need to add this view to the CFrame object created earlier.

frame->addView (myView);

So after we have setup all views we can get rid of our image as all views will remember the image by its own.

bitmap->forget ();

Now lets see how this looks as a complete example :

bool MyEditor::open (void* ptr)
{
CRect frameSize (0, 0, 300, 300);
frame = new CFrame (frameSize, ptr, this);
CBitmap* bitmap = new CBitmap ("MyBitmap.png");
CView* myView = new CView (CRect (0, 0, bitmap->getWidth (), bitmap->getHeight ()));
myView->setBackground (bitmap);
frame->addView (myView);
bitmap->forget ();
return true;
}

To only have an image shown in our editor is a little bit lame. We want to have some controls the user can interact with.

## Creating a knob control

VSTGUI provides some basic controls you can use. As an example we use the CKnob control. The CKnob control takes two images, the background and the handle. The background as its name suggest is always drawn as the background of this control, while the handle is drawn at the position of the value of this control. See VSTGUI::CKnob for more info.

Now lets see how to create such a knob:

CKnob* knob = new CKnob (r, 0, 0, background, handle, CPoint (0, 0));

As you can see there are some parameters set to zero. Ignore them for a moment. I will talk about it later. If you add this knob to the frame and test the interface you will see that if you press the mouse button over this control and move the mouse, the handle of the knob is also moving. Great, we have something to play with in the editor.

The complete example :

bool MyEditor::open (void* ptr)
{
CRect frameSize (0, 0, 300, 300);
frame = new CFrame (frameSize, ptr, this);
CBitmap* background = new CBitmap ("KnobBackground.png");
CBitmap* handle = new CBitmap ("KnobHandle.png");
CRect r (0, 0, background->getWidth (), background->getHeight ());
CKnob* knob = new CKnob (r, 0, 0, background, handle, CPoint (0, 0));
background->forget ();
handle->forget ();
frame->addView (knob);
return true;
}

# Getting notification of control changes

So now we have a knob in our editor. We'd like to know when the user uses this control.

## The CControlListener

This is done with the CControlListener interface. Every control in VSTGUI can have one listener. When the value of the control has changed the listener is notified.

First we need a CControlListener. The easiest way is to inherit our editor not only from AEffGUIEditor but also from CControlListener :

class MyEditor : public AEffGUIEditor, public CControlListener
{
public:
MyEditor (void* ptr) : AEffGUIEditor (ptr) {}
// from AEffGUIEditor
bool open (void* ptr);
void close ();
// from CControlListener
void valueChanged (CControl* pControl);
};

Now we can use our editor as the listener parameter in the CKnob constructor.

CKnob* knob = new CKnob (r, this, 0, background, handle, CPoint (0, 0));

We only need to implement the valueChanged method and we know when the user twiddles our knob.

void MyEditor::valueChanged (CControl* pControl)
{
// pControl is our knob in this example
}

## Control identification

With one control it's fairly easy to know which control was used by the user. If there are more controls in our editor, to know which control was used is done by the tag of the control. So if we add two knobs to the frame we gave them different tags :

CKnob* knob1 = new CKnob (r, this, 0, background, handle, CPoint (0, 0));
CKnob* knob2 = new CKnob (r, this, 1, background, handle, CPoint (0, 0));

Now in our valueChanged method we can differentiate between the controls :

void MyEditor::valueChanged (CControl* pControl)
{
int32_t tag = pControl->getTag ();
if (tag == 0)
{
// the first knob
}
else if (tag == 1)
{
// the second knob
}
}

For a complete example have a look at the tutorial project included with VSTGUI.