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