1 //----------------------------------------------------------------------------- 2 // LICENSE 3 // (c) 2007-2018, Steinberg Media Technologies GmbH, All Rights Reserved 4 // (c) 2018, Guillaume Piolat (contact@auburnsounds.com) 5 //----------------------------------------------------------------------------- 6 // 7 // This Software Development Kit is licensed under the terms of the General 8 // Public License (GPL) Version 3. 9 // 10 // This source is part of the "Auburn Sounds (Guillaume Piolat) extension to the 11 // Steinberg VST 3 Plug-in SDK". 12 // 13 // Details of that license can be found at: www.gnu.org/licenses/gpl-3.0.html 14 // 15 // Dual-licence: 16 // 17 // The "Auburn Sounds (Guillaume Piolat) extension to the Steinberg VST 3 Plug-in 18 // SDK", hereby referred to as DPLUG:VST3, is a language translation of the VST3 19 // SDK suitable for usage in Dplug. Any Licensee of a currently valid Steinberg 20 // VST 3 Plug-In SDK Licensing Agreement (version 2.2.4 or ulterior, hereby referred 21 // to as the AGREEMENT), is granted by Auburn Sounds (Guillaume Piolat) a non-exclusive, 22 // worldwide, nontransferable license during the term the AGREEMENT to use parts 23 // of DPLUG:VST3 not covered by the AGREEMENT, as if they were originally 24 // inside the Licensed Software Developer Kit mentionned in the AGREEMENT. 25 // Under this licence all conditions that apply to the Licensed Software Developer 26 // Kit also apply to DPLUG:VST3. 27 // 28 //----------------------------------------------------------------------------- 29 module dplug.vst3.iplugview; 30 31 version(VST3): 32 33 import dplug.vst3.ftypes; 34 35 struct ViewRect 36 { 37 nothrow: 38 @nogc: 39 int left = 0; 40 int top = 0; 41 int right = 0; 42 int bottom = 0; 43 44 int getWidth () const 45 { 46 return right - left; 47 } 48 49 int getHeight () const 50 { 51 return bottom - top; 52 } 53 } 54 55 static assert(ViewRect.sizeof == 16); 56 57 /** \defgroup platformUIType Platform UI Types 58 \ingroup pluginGUI 59 List of Platform UI types for IPlugView. This list is used to match the GUI-System between 60 the host and a Plug-in in case that an OS provides multiple GUI-APIs. 61 */ 62 /** The parent parameter in IPlugView::attached() is a HWND handle. 63 * You should attach a child window to it. */ 64 static immutable kPlatformTypeHWND = "HWND"; ///< HWND handle. (Microsoft Windows) 65 66 /** The parent parameter in IPlugView::attached() is a WindowRef. 67 * You should attach a HIViewRef to the content view of the window. */ 68 static immutable kPlatformTypeHIView = "HIView"; ///< HIViewRef. (Mac OS X) 69 70 /** The parent parameter in IPlugView::attached() is a NSView pointer. 71 * You should attach a NSView to it. */ 72 static immutable kPlatformTypeNSView = "NSView"; ///< NSView pointer. (Mac OS X) 73 74 /** The parent parameter in IPlugView::attached() is a UIView pointer. 75 * You should attach an UIView to it. */ 76 static immutable kPlatformTypeUIView = "UIView"; ///< UIView pointer. (iOS) 77 78 /** The parent parameter in IPlugView::attached() is a X11 Window supporting XEmbed. 79 * You should attach a Window to it that supports the XEmbed extension. */ 80 static immutable kPlatformTypeX11EmbedWindowID = "X11EmbedWindowID"; ///< X11 Window ID. (X11) 81 82 /** Plug-in definition of a view. 83 \ingroup pluginGUI vstIPlug vst300 84 - [plug imp] 85 - [released: 3.0.0] 86 87 \par Sizing of a view 88 Usually the size of a Plug-in view is fixed. But both the host and the Plug-in can cause 89 a view to be resized: 90 \n 91 - <b> Host </b> : If IPlugView::canResize () returns kResultTrue the host will setup the window 92 so that the user can resize it. While the user resizes the window 93 IPlugView::checkSizeConstraint () is called, allowing the Plug-in to change the size to a valid 94 rect. The host then resizes the window to this rect and has to call IPlugView::onSize (). 95 \n 96 \n 97 - <b> Plug-in </b> : The Plug-in can call IPlugFrame::resizeView () and cause the host to resize the 98 window. 99 Afterwards in the same callstack the host has to call IPlugView::onSize () if a resize is needed (size was changed). 100 Note that if the host calls IPlugView::getSize () before calling IPlugView::onSize () (if needed), 101 it will get the current (old) size not the wanted one!! 102 Here the calling sequence: 103 * plug-in->host: IPlugFrame::resizeView (newSize) 104 * host->plug-in (optional): IPlugView::getSize () returns the currentSize (not the newSize)! 105 * host->plug-in: if newSize is different from the current size: IPlugView::onSize (newSize) 106 * host->plug-in (optional): IPlugView::getSize () returns the newSize 107 \n 108 <b>Please only resize the platform representation of the view when IPlugView::onSize () is 109 called.</b> 110 111 \par Keyboard handling 112 The Plug-in view receives keyboard events from the host. A view implementation must not handle 113 keyboard events by the means of platform callbacks, but let the host pass them to the view. The host 114 depends on a proper return value when IPlugView::onKeyDown is called, otherwise the Plug-in view may 115 cause a malfunction of the host's key command handling! 116 117 \see IPlugFrame, \ref platformUIType 118 */ 119 interface IPlugView : FUnknown 120 { 121 public: 122 nothrow: 123 @nogc: 124 /** Is Platform UI Type supported 125 \param type : IDString of \ref platformUIType */ 126 tresult isPlatformTypeSupported (FIDString type); 127 128 /** The parent window of the view has been created, the (platform) representation of the view 129 should now be created as well. 130 Note that the parent is owned by the caller and you are not allowed to alter it in any way 131 other than adding your own views. 132 Note that in this call the Plug-in could call a IPlugFrame::resizeView ()! 133 \param parent : platform handle of the parent window or view 134 \param type : \ref platformUIType which should be created */ 135 tresult attached (void* parent, FIDString type); 136 137 /** The parent window of the view is about to be destroyed. 138 You have to remove all your own views from the parent window or view. */ 139 tresult removed (); 140 141 /** Handling of mouse wheel. */ 142 tresult onWheel (float distance); 143 144 /** Handling of keyboard events : Key Down. 145 \param key : unicode code of key 146 \param keyCode : virtual keycode for non ascii keys - see \ref VirtualKeyCodes in keycodes.h 147 \param modifiers : any combination of modifiers - see \ref KeyModifier in keycodes.h 148 \return kResultTrue if the key is handled, otherwise kResultFalse. \n 149 <b> Please note that kResultTrue must only be returned if the key has really been 150 handled. </b> Otherwise key command handling of the host might be blocked! */ 151 tresult onKeyDown (char16 key, int16 keyCode, int16 modifiers); 152 153 /** Handling of keyboard events : Key Up. 154 \param key : unicode code of key 155 \param keyCode : virtual keycode for non ascii keys - see \ref VirtualKeyCodes in keycodes.h 156 \param modifiers : any combination of KeyModifier - see \ref KeyModifier in keycodes.h 157 \return kResultTrue if the key is handled, otherwise return kResultFalse. */ 158 tresult onKeyUp (char16 key, int16 keyCode, int16 modifiers); 159 160 /** Returns the size of the platform representation of the view. */ 161 tresult getSize (ViewRect* size); 162 163 /** Resizes the platform representation of the view to the given rect. Note that if the Plug-in 164 * requests a resize (IPlugFrame::resizeView ()) onSize has to be called afterward. */ 165 tresult onSize (ViewRect* newSize); 166 167 /** Focus changed message. */ 168 tresult onFocus (TBool state); 169 170 /** Sets IPlugFrame object to allow the Plug-in to inform the host about resizing. */ 171 tresult setFrame (IPlugFrame frame); 172 173 /** Is view sizable by user. */ 174 tresult canResize (); 175 176 /** On live resize this is called to check if the view can be resized to the given rect, if not 177 * adjust the rect to the allowed size. */ 178 tresult checkSizeConstraint (ViewRect* rect); 179 180 immutable __gshared TUID iid = INLINE_UID(0x5BC32507, 0xD06049EA, 0xA6151B52, 0x2B755B29); 181 } 182 183 /** Callback interface passed to IPlugView. 184 \ingroup pluginGUI vstIHost vst300 185 - [host imp] 186 - [released: 3.0.0] 187 188 Enables a Plug-in to resize the view and cause the host to resize the window. 189 */ 190 interface IPlugFrame : FUnknown 191 { 192 public: 193 nothrow: 194 @nogc: 195 /** Called to inform the host about the resize of a given view. 196 * Afterwards the host has to call IPlugView::onSize (). */ 197 tresult resizeView (IPlugView view, ViewRect* newSize); 198 199 immutable __gshared TUID iid = INLINE_UID(0x367FAF01, 0xAFA94693, 0x8D4DA2A0, 0xED0882A3); 200 }