source/includes/vst3sdk/pluginterfaces/gui/iplugview.h

   1 //-----------------------------------------------------------------------------
   2 // Project     : SDK Core
   3 //
   4 // Category    : SDK GUI Interfaces
   5 // Filename    : pluginterfaces/gui/iplugview.h
   6 // Created by  : Steinberg, 12/2007
   7 // Description : Plug-in User Interface
   8 //
   9 //-----------------------------------------------------------------------------
  10 // This file is part of a Steinberg SDK. It is subject to the license terms
  11 // in the LICENSE file found in the top-level directory of this distribution
  12 // and at www.steinberg.net/sdklicenses.
  13 // No part of the SDK, including this file, may be copied, modified, propagated,
  14 // or distributed except according to the terms contained in the LICENSE file.
  15 //-----------------------------------------------------------------------------
  16
  17 #pragma once
  18
  19 #include "pluginterfaces/base/funknown.h"
  20 #include "pluginterfaces/base/typesizecheck.h"
  21
  22 namespace Steinberg {
  23
  24 class IPlugFrame;
  25
  26 //------------------------------------------------------------------------
  27 /*! \defgroup pluginGUI Graphical User Interface
  28 */
  29
  30 //------------------------------------------------------------------------
  31 /**  Graphical rectangle structure. Used with IPlugView.
  32 \ingroup pluginGUI
  33 */
  34 struct ViewRect
  35 {
  36         ViewRect (int32 l = 0, int32 t = 0, int32 r = 0, int32 b = 0)
  37         : left (l), top (t), right (r), bottom (b)
  38         {
  39         }
  40
  41         int32 left;
  42         int32 top;
  43         int32 right;
  44         int32 bottom;
  45
  46         //--- ---------------------------------------------------------------------
  47         int32 getWidth () const { return right - left; }
  48         int32 getHeight () const { return bottom - top; }
  49 };
  50
  51 SMTG_TYPE_SIZE_CHECK (ViewRect, 16, 16, 16, 16)
  52
  53 //------------------------------------------------------------------------
  54 /**  \defgroup platformUIType Platform UI Types
  55 \ingroup pluginGUI
  56 List of Platform UI types for IPlugView. This list is used to match the GUI-System between
  57 the host and a plug-in in case that an OS provides multiple GUI-APIs.
  58 */
  59 /*@{*/
  60 /** The parent parameter in IPlugView::attached() is a HWND handle.
  61  *      You should attach a child window to it. */
  62 const FIDString kPlatformTypeHWND = "HWND"; ///< HWND handle. (Microsoft Windows)
  63
  64 /** The parent parameter in IPlugView::attached() is a WindowRef.
  65  *      You should attach a HIViewRef to the content view of the window. */
  66 const FIDString kPlatformTypeHIView = "HIView"; ///< HIViewRef. (Mac OS X)
  67
  68 /** The parent parameter in IPlugView::attached() is a NSView pointer.
  69  * You should attach a NSView to it. */
  70 const FIDString kPlatformTypeNSView = "NSView"; ///< NSView pointer. (Mac OS X)
  71
  72 /** The parent parameter in IPlugView::attached() is a UIView pointer.
  73  * You should attach an UIView to it. */
  74 const FIDString kPlatformTypeUIView = "UIView"; ///< UIView pointer. (iOS)
  75
  76 /** The parent parameter in IPlugView::attached() is a X11 Window supporting XEmbed.
  77  * You should attach a Window to it that supports the XEmbed extension.
  78  * See https://standards.freedesktop.org/xembed-spec/xembed-spec-latest.html */
  79 const FIDString kPlatformTypeX11EmbedWindowID = "X11EmbedWindowID"; ///< X11 Window ID. (X11)
  80
  81 /*@}*/
  82 //------------------------------------------------------------------------
  83
  84 //------------------------------------------------------------------------
  85 /**  Plug-in definition of a view.
  86 \ingroup pluginGUI vstIPlug vst300
  87 - [plug imp]
  88 - [released: 3.0.0]
  89
  90 \par Sizing of a view
  91 Usually, the size of a plug-in view is fixed. But both the host and the plug-in can cause
  92 a view to be resized:
  93 \n
  94 - \b Host: If IPlugView::canResize () returns kResultTrue the host will set up the window
  95   so that the user can resize it. While the user resizes the window,
  96   IPlugView::checkSizeConstraint () is called, allowing the plug-in to change the size to a valid
  97   a valid supported rectangle size. The host then resizes the window to this rect and has to call IPlugView::onSize ().
  98 \n
  99 \n
 100 - \b Plug-in: The plug-in can call IPlugFrame::resizeView () and cause the host to resize the
 101   window.\n\n
 102   Afterwards, in the same callstack, the host has to call IPlugView::onSize () if a resize is needed (size was changed).
 103   Note that if the host calls IPlugView::getSize () before calling IPlugView::onSize () (if needed),
 104   it will get the current (old) size not the wanted one!!\n
 105   Here the calling sequence:\n
 106     - plug-in->host: IPlugFrame::resizeView (newSize)
 107         - host->plug-in (optional): IPlugView::getSize () returns the currentSize (not the newSize!)
 108         - host->plug-in: if newSize is different from the current size: IPlugView::onSize (newSize)
 109     - host->plug-in (optional): IPlugView::getSize () returns the newSize
 110 \n
 111 <b>Please only resize the platform representation of the view when IPlugView::onSize () is
 112 called.</b>
 113
 114 \par Keyboard handling
 115 The plug-in view receives keyboard events from the host. A view implementation must not handle
 116 keyboard events by the means of platform callbacks, but let the host pass them to the view. The host
 117 depends on a proper return value when IPlugView::onKeyDown is called, otherwise the plug-in view may
 118 cause a malfunction of the host's key command handling.
 119
 120 \see IPlugFrame, \ref platformUIType
 121 */
 122 class IPlugView : public FUnknown
 123 {
 124 public:
 125 //------------------------------------------------------------------------
 126         /** Is Platform UI Type supported
 127             \param type : IDString of \ref platformUIType */
 128         virtual tresult PLUGIN_API isPlatformTypeSupported (FIDString type) = 0;
 129
 130         /** The parent window of the view has been created, the (platform) representation of the view
 131                 should now be created as well.
 132             Note that the parent is owned by the caller and you are not allowed to alter it in any way
 133                 other than adding your own views.
 134             Note that in this call the plug-in could call a IPlugFrame::resizeView ()!
 135             \param parent : platform handle of the parent window or view
 136             \param type : \ref platformUIType which should be created */
 137         virtual tresult PLUGIN_API attached (void* parent, FIDString type) = 0;
 138
 139         /** The parent window of the view is about to be destroyed.
 140             You have to remove all your own views from the parent window or view. */
 141         virtual tresult PLUGIN_API removed () = 0;
 142
 143         /** Handling of mouse wheel. */
 144         virtual tresult PLUGIN_API onWheel (float distance) = 0;
 145
 146         /** Handling of keyboard events : Key Down.
 147             \param key : unicode code of key
 148             \param keyCode : virtual keycode for non ascii keys - see \ref VirtualKeyCodes in keycodes.h
 149             \param modifiers : any combination of modifiers - see \ref KeyModifier in keycodes.h
 150             \return kResultTrue if the key is handled, otherwise kResultFalse. \n
 151                     <b> Please note that kResultTrue must only be returned if the key has really been
 152            handled. </b> Otherwise key command handling of the host might be blocked! */
 153         virtual tresult PLUGIN_API onKeyDown (char16 key, int16 keyCode, int16 modifiers) = 0;
 154
 155         /** Handling of keyboard events : Key Up.
 156             \param key : unicode code of key
 157             \param keyCode : virtual keycode for non ascii keys - see \ref VirtualKeyCodes in keycodes.h
 158             \param modifiers : any combination of KeyModifier - see \ref KeyModifier in keycodes.h
 159             \return kResultTrue if the key is handled, otherwise return kResultFalse. */
 160         virtual tresult PLUGIN_API onKeyUp (char16 key, int16 keyCode, int16 modifiers) = 0;
 161
 162         /** Returns the size of the platform representation of the view. */
 163         virtual tresult PLUGIN_API getSize (ViewRect* size) = 0;
 164
 165         /** Resizes the platform representation of the view to the given rect. Note that if the plug-in
 166          *      requests a resize (IPlugFrame::resizeView ()) onSize has to be called afterward. */
 167         virtual tresult PLUGIN_API onSize (ViewRect* newSize) = 0;
 168
 169         /** Focus changed message. */
 170         virtual tresult PLUGIN_API onFocus (TBool state) = 0;
 171
 172         /** Sets IPlugFrame object to allow the plug-in to inform the host about resizing. */
 173         virtual tresult PLUGIN_API setFrame (IPlugFrame* frame) = 0;
 174
 175         /** Is view sizable by user. */
 176         virtual tresult PLUGIN_API canResize () = 0;
 177
 178         /** On live resize this is called to check if the view can be resized to the given rect, if not
 179          *      adjust the rect to the allowed size. */
 180         virtual tresult PLUGIN_API checkSizeConstraint (ViewRect* rect) = 0;
 181 //------------------------------------------------------------------------
 182         static const FUID iid;
 183 };
 184
 185 DECLARE_CLASS_IID (IPlugView, 0x5BC32507, 0xD06049EA, 0xA6151B52, 0x2B755B29)
 186
 187 //------------------------------------------------------------------------
 188 /** Callback interface passed to IPlugView.
 189 \ingroup pluginGUI vstIHost vst300
 190 - [host imp]
 191 - [released: 3.0.0]
 192 - [mandatory]
 193
 194 Enables a plug-in to resize the view and cause the host to resize the window.
 195 */
 196 class IPlugFrame : public FUnknown
 197 {
 198 public:
 199 //------------------------------------------------------------------------
 200         /** Called to inform the host about the resize of a given view.
 201          *      Afterwards the host has to call IPlugView::onSize (). */
 202         virtual tresult PLUGIN_API resizeView (IPlugView* view, ViewRect* newSize) = 0;
 203 //------------------------------------------------------------------------
 204         static const FUID iid;
 205 };
 206
 207 DECLARE_CLASS_IID (IPlugFrame, 0x367FAF01, 0xAFA94693, 0x8D4DA2A0, 0xED0882A3)
 208
 209 #if SMTG_OS_LINUX
 210 //------------------------------------------------------------------------
 211 namespace Linux {
 212
 213 using TimerInterval = uint64;
 214 using FileDescriptor = int;
 215
 216 //------------------------------------------------------------------------
 217 /** Linux event handler interface
 218 \ingroup pluginGUI vst368
 219 - [plug imp]
 220 - [released: 3.6.8]
 221 \see IRunLoop
 222 */
 223 class IEventHandler : public FUnknown
 224 {
 225 public:
 226         virtual void PLUGIN_API onFDIsSet (FileDescriptor fd) = 0;
 227 //------------------------------------------------------------------------
 228         static const FUID iid;
 229 };
 230 DECLARE_CLASS_IID (IEventHandler, 0x561E65C9, 0x13A0496F, 0x813A2C35, 0x654D7983)
 231
 232 //------------------------------------------------------------------------
 233 /** Linux timer handler interface
 234 \ingroup pluginGUI vst368
 235 - [plug imp]
 236 - [released: 3.6.8]
 237 \see IRunLoop
 238 */
 239 class ITimerHandler : public FUnknown
 240 {
 241 public:
 242         virtual void PLUGIN_API onTimer () = 0;
 243 //------------------------------------------------------------------------
 244         static const FUID iid;
 245 };
 246 DECLARE_CLASS_IID (ITimerHandler, 0x10BDD94F, 0x41424774, 0x821FAD8F, 0xECA72CA9)
 247
 248 //------------------------------------------------------------------------
 249 /** Linux host run loop interface
 250 \ingroup pluginGUI vst368
 251 - [host imp]
 252 - [extends IPlugFrame]
 253 - [released: 3.6.8]
 254
 255 On Linux the host has to provide this interface to the plug-in as there's no global event run loop
 256 defined as on other platforms.
 257
 258 A plug-in can register an event handler for a file descriptor. The host has to call the event
 259 handler when the file descriptor is marked readable.
 260
 261 A plug-in also can register a timer which will be called repeatedly until it is unregistered.
 262 */
 263 class IRunLoop : public FUnknown
 264 {
 265 public:
 266         virtual tresult PLUGIN_API registerEventHandler (IEventHandler* handler, FileDescriptor fd) = 0;
 267         virtual tresult PLUGIN_API unregisterEventHandler (IEventHandler* handler) = 0;
 268
 269         virtual tresult PLUGIN_API registerTimer (ITimerHandler* handler,
 270                                                                                           TimerInterval milliseconds) = 0;
 271         virtual tresult PLUGIN_API unregisterTimer (ITimerHandler* handler) = 0;
 272 //------------------------------------------------------------------------
 273         static const FUID iid;
 274 };
 275 DECLARE_CLASS_IID (IRunLoop, 0x18C35366, 0x97764F1A, 0x9C5B8385, 0x7A871389)
 276
 277 //------------------------------------------------------------------------
 278 } // namespace Linux
 279
 280 #endif
 281
 282 //------------------------------------------------------------------------
 283 } // namespace Steinberg