VSTGUI 4.10
Graphical User Interface Framework not only for VST plugins
New stuff in VSTGUI 4

Table of Contents

Introduction

Version 4 of VSTGUI is a new milestone release with a restructured code base with the focus of code conformity and easier future enhancements. The result is that code written for any earlier version of VSTGUI is not always compatible. It's recommended to start new projects with version 4 while old projects should stay with version 3.6.

New Stuff

Version 4.14

  • add crosshair mouse cursor (kCursorCrosshair)
  • customizable knob range (see CKnob::setKnobRange)
  • new layouts for CRowColumnView

Version 4.13

  • support embedding platform views (HWND & NSView) as sub views (see CExternalView and ExternalView::IView) and examples in the contrib folder.

Version 4.12.2

  • make it possible to draw only frames in a range for views using multi frame bitmaps.

Version 4.12.1

  • make it possible to use the new multi frame bitmap feature with custom value to frame index mappings by subclassing.

Version 4.12

  • new multi frame bitmap representation that allows to support more frames per bitmap on current hardware by supporting to layout the frames in the bitmap by rows and multiple columns instead of one column as before. See VSTGUI::CMultiFrameBitmap. All included controls are updated to support it, while the old method is deprecated but still supported for now.
  • the image stitcher tool was updated to support the creation of multi row/column frames bitmap

Version 4.11

  • Using DirectComposition on Windows now with support for CLayeredViewContainer
  • Removed 32-bit Carbon support
  • Reworked event handling, please see VSTGUI 4.10 -> VSTGUI 4.11
  • Reworked unit test framework to be able to debug the tests

Version 4.10

  • VSTGUI now needs to be initialized and terminated explicitly. See VSTGUI::init() and VSTGUI::exit().
  • UIDescription files are now written in JSON format and the old XML format is deprecated
  • It's now possible to conditionally remove the XML parser and the expat library from building (set VSTGUI_ENABLE_XML_PARSER to 0)
  • This is the last version not depending on c++17 compiler support.

Version 4.9

  • new control: VSTGUI::CListControl in play with VSTGUI::CStringList
  • custom font support: VSTGUI now supports using fonts embedded in its Bundle/Package at Resources/Fonts. Note that this works on Windows only when building with the Windows 10 SDK and it does also only work on Windows 10. There's no such restriction on macOS or Linux.

Version 4.8

Version 4.7

  • redesigned drag'n drop
  • drags with bitmaps are now supported on Windows
  • standalone library support for Windows 7
  • new ImageStitcher tool
  • the GDI+ draw backend was removed, the Direct2D backend is the replacement

Version 4.6

  • new Control: VSTGUI::KeyboardView
  • cmake cleanup
  • fix static object initialization order
  • fix build warnings/errors depending on macOS SDK use
  • remove warnings

Version 4.5

Version 4.4

  • preview Linux version
  • support for Windows XP, Mac OS X 10.6 and non c++11 mode will be removed with version 4.5

Version 4.3

Note: All current deprecated methods will be removed in the next version. So make sure that your code compiles with VSTGUI_ENABLE_DEPRECATED_METHODS=0

Version 4.2

  • iOS Support with Multi Touch handling. See iOS support notes
  • support drawing an icon on a VSTGUI::CTextButton
  • VSTGUI::CGradientView
  • VSTGUI::CDataBrowser now supports multi row selections
  • support compiling in c++11 mode with clang and visual studio
  • VSTGUI_OVERRIDE_VMETHOD is now used throughout the vstgui sources to indicate methods which are expecting to override a virtual method of its base classes. (c++11 only)

Version 4.1

Version 4.0

Changes for existing VSTGUI code

VSTGUI 4.13 -> VSTGUI 4.14

  • In CParamDisplay::drawPlatformText(..) the string argument changed from IPlatformString to UTF8Text

VSTGUI 4.12 -> VSTGUI 4.13

  • the context argument of IFontPainter has changed to use the new platform graphics device context

VSTGUI 4.11 -> VSTGUI 4.12

  • The CMultiFrameBitmap change deprecated the VSTGUI::IMultiBitmapControl class. If you use it, update your uses and use a VSTGUI::CMultiFrameBitmap instead.
  • If you compile with VSTGUI_ENABLE_DEPRECATED_METHODS=0 you need to update your multi frame bitmaps to use VSTGUI::CMultiFrameBitmap.
  • In 4.12.2 the following constructors have lost their offset parameter:
    • CKickButton
    • CAnimKnob
    • CMovieBitmap
    • CMovieButton
    • CSwitchBase
    • CVerticalSwitch
    • CHorizontalSwitch
    • CRockerSwitch

VSTGUI 4.10 -> VSTGUI 4.11

Changes due to event handling rework:

  • IKeyboardHook changed its methods. If you inherit from it, you need to adopt to the new methods or use OldKeyboardHookAdapter
  • IMouseObserver changed a few of its methods. If you inherit from it, you need to adopt to the new methods or use OldMouseObserverAdapter
  • CViewContainer::onWheel is now marked final, you cannot inherit this method, please override the new CView::onMouseWheelEvent instead if you need to handle mouse wheel events in a custom view container
  • DragEventData has changed it's modifiers type from CButtonState to Modifiers
  • CView::hitTest uses an Event now instead of a CButtonState (the method with a CButtonState still works but is deprecated)
  • CControl::checkDefaultValue(CButtonState) was removed and replaced by a generic method which uses the static function CControl::CheckDefaultValueEventFunc to reset a control to its default value

CView has the following new methods:

  • dispatchEvent
  • onMouseDownEvent
  • onMouseMoveEvent
  • onMouseUpEvent
  • onMouseCancelEvent
  • onMouseEnterEvent
  • onMouseExitEvent
  • onMouseWheelEvent
  • onZoomGestureEvent
  • onKeyboardEvent

Which replaces the following old methods:

  • onKeyDown
  • onKeyUp
  • onWheel

The old mouse methods (onMouseDown, onMouseUp, onMouseMoved, etc) are still supported but should be replaced with the new methods in the long run.

VSTGUI 4.9 -> VSTGUI 4.10

VSTGUI 4.8 -> VSTGUI 4.9

  • removed method CView::onWheel (..) where the axis of the event was not included. You have to use the other onWheel method for your custom classes now.
  • new IViewMouseListener interface method IViewMouseListener::viewOnMouseEnabled
  • changed ModalViewSession type name to ModalViewSessionID and its type to an integer type
  • changed the CFrame::beginModalViewSession return value to be an Optional<ModalViewSessionID> for safer use.

VSTGUI 4.7 -> VSTGUI 4.8

  • CCommandMenuItem constructor takes a CCommandMenuItem::Desc argument now. You will get compiler errors when not adopting to this change.
  • removed Message sending for:
    • kMsgMenuItemValidate, kMsgMenuItemSelected -> use ICommandMenuItemTarget
    • kMessageValueChanged, kMessageBeginEdit, kMessageEndEdit -> use IControlListener
    • kMsgTruncatedTextChanged -> use ITextLabelListener
    • kMsgBeforePopup -> use IOptionMenuListener
  • IDependency is deprecated. Please use explicit interfaces for communicating changes.
  • removed "using namespace VSTGUI" from vstgui.h

VSTGUI 4.6 -> VSTGUI 4.7

  • CView::doDrag is deprecated, instead use the asynchronous variant of it : CView::doDrag ;-)
  • CView don't has drop target methods (onDragEnter, onDragLeave, onDragMove and onDrop) anymore. Instead it has a method to return a drop target. See the documentation for IDropTarget on how to use it.
  • the CControlEnum is gone and is moved into the classes where they are used: CParamDisplay/COptionMenu/CTextEdit/CSlider
  • CControl::kMessageTagWillChange and CControl::kMessageTagDidChange is gone, use IControlListener instead
  • COptionMenu::popup has changed behaviour and got a callback function that will be called when the popup is closed. The return of COptionMenu::popup now only indicates if the popup was shown.
  • IDataBrowserDelegate is now a real virtual interface class, use DataBrowserDelegateAdapter instead if you get compile/linker errors.
  • renamed the following interface adapter classes :
    • IViewListenerAdapter -> ViewListenerAdapter
    • IViewContainerListenerAdapter -> ViewContainerListenerAdapter
    • IViewMouseListenerAdapter -> ViewMouseListenerAdapter
    • IGenericStringListDataBrowserSourceSelectionChanged -> GenericStringListDataBrowserSourceSelectionChanged

VSTGUI 4.3 -> VSTGUI 4.5

  • COffscreenContext::create returns a SharedPointer<COffscreenContext> now, not a naked pointer.

VSTGUI 4.2 -> VSTGUI 4.3

VSTGUI 4.1 -> VSTGUI 4.2

  • the class CDragContainer is replaced by IDataPackage. The class CDragContainerHelper is a helper class you can use to quickly get your code up and running again.
  • the class IDataBrowser is renamed to IDataBrowserDelegate and the drag and drop methods have changed
  • CView::getVisibleSize () was renamed to CView::getVisibleViewSize ()

VSTGUI 4.0 -> VSTGUI 4.1

  • the pBackground member of CView is now private. You must replace all read access with getDrawBackground () or getBackground () and all write access with setBackground ()

VSTGUI 3.6 -> VSTGUI 4.0

  • the variable types were changed to use C99 style types (int32_t, etc), you must do this for all your derivated VSTGUI classes too
  • the buttons parameter has changed from long to CButtonState
  • your custom views need to use the new mouse methods
  • COptionMenuScheme is not available anymore
  • VSTGUI::CFileSelector is gone, you have to use VSTGUI::CNewFileSelector
  • VST extensions previously enabled via ENABLE_VST_EXTENSION_IN_VSTGUI is gone without replacement
  • VSTGUI::CBitmap was completely changed and does not use a transparency color anymore, you need to use the alpha channel of a bitmap to get the same results
  • VSTGUI::COffscreenContext is handled completely different. But in most cases you can simply remove all offscreens where you needed them to reduce flicker.
  • On Windows graphics are entirely drawn with GDI+ or Direct2D (when available), GDI is not used anymore
  • The internal string encoding is now always UTF-8
  • The VSTGUI::CCoord type is now always a double
  • on Mac OS X, embedding a CFrame into a non composited carbon window is not supported anymore
  • on Mac OS X, when targeting Mac OS X 10.4 some of the graphics path methods are not implemented.
  • Method signature changes which don't lead to compile errors:
    • CView::setViewSize (CRect& rect, bool invalid = true)
    • CView::hitTest (const CPoint& where, CButtonState& buttons = -1)
    • CView::invalidRect (CRect& rect)
    • CViewContainer::drawBackgroundRect (CDrawContext* pContext, CRect& _updateRect)
    • CViewContainer::addView (CView* pView, CRect& mouseableArea, bool mouseEnabled = true)

HiDPI notes

  • HiDPI is supported on OSX, iOS and Windows (with Direct2D backend)
  • Due to platform differences one need to call frame->setZoom (scaleFactor) on Windows, while on OSX and iOS this is not needed.

iOS support notes

  • VSTGUI supports iOS 7 and later
  • Currently COptionMenu, CScrollView and COpenGLView are not supported
  • Support for a single MultiTouch View is not yet tested and the API may change in the future