source/includes/vst3sdk/pluginterfaces/vst/ivstcontextmenu.h

   1 //------------------------------------------------------------------------
   2 // Project     : VST SDK
   3 //
   4 // Category    : Interfaces
   5 // Filename    : pluginterfaces/vst/ivstcontextmenu.h
   6 // Created by  : Steinberg, 10/2010
   7 // Description : VST Context Menu Interfaces
   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/vst/vsttypes.h"
  21
  22 //------------------------------------------------------------------------
  23 #include "pluginterfaces/base/falignpush.h"
  24 //------------------------------------------------------------------------
  25
  26 namespace Steinberg {
  27 class IPlugView;
  28
  29 namespace Vst {
  30 class IContextMenu;
  31
  32 //------------------------------------------------------------------------
  33 /** Extended host callback interface Vst::IComponentHandler3 for an edit controller.
  34 \ingroup vstIHost vst350
  35 - [host imp]
  36 - [extends IComponentHandler]
  37 - [released: 3.5.0]
  38 - [optional]
  39
  40 A plug-in can ask the host to create a context menu for a given exported parameter ID or a generic context menu.\n
  41
  42 The host may pre-fill this context menu with specific items regarding the parameter ID like "Show automation for parameter",
  43 "MIDI learn" etc...\n
  44
  45 The plug-in can use the context menu in two ways :
  46 - add its own items to the menu via the IContextMenu interface and call IContextMenu::popup(..) to create the pop-up. See the \ref IContextMenuExample.
  47 - extract the host menu items and add them to a context menu created by the plug-in.
  48
  49 \b Note: You can and should use this even if you do not add your own items to the menu as this is considered to be a big user value.
  50
  51 \sa IContextMenu
  52 \sa IContextMenuTarget
  53
  54 \section IContextMenuExample Examples
  55 - For example, Cubase adds its owned entries in the context menu opened with right-click on an exported parameter when the plug-in uses createContextMenu.
  56 \image html "contextmenuexample.png"
  57 \n
  58 - Adding plug-in specific items to the context menu:
  59
  60 \code{.cpp}
  61 //------------------------------------------------------------------------
  62 class PluginContextMenuTarget : public IContextMenuTarget, public FObject
  63 {
  64 public:
  65         PluginContextMenuTarget () {}
  66
  67         virtual tresult PLUGIN_API executeMenuItem (int32 tag)
  68         {
  69                 // this will be called if the user has executed one of the menu items of the plug-in.
  70                 // It will not be called for items of the host.
  71                 switch (tag)
  72                 {
  73                         case 1: break;
  74                         case 2: break;
  75                 }
  76                 return kResultTrue;
  77         }
  78
  79         OBJ_METHODS(PluginContextMenuTarget, FObject)
  80         DEFINE_INTERFACES
  81                 DEF_INTERFACE (IContextMenuTarget)
  82         END_DEFINE_INTERFACES (FObject)
  83         REFCOUNT_METHODS(FObject)
  84 };
  85
  86 // The following is the code to create the context menu
  87 void popupContextMenu (IComponentHandler* componentHandler, IPlugView* view, const ParamID* paramID, UCoord x, UCoord y)
  88 {
  89         if (componentHandler == 0 || view == 0)
  90                 return;
  91         FUnknownPtr<IComponentHandler3> handler (componentHandler);
  92         if (handler == 0)
  93                 return;
  94         IContextMenu* menu = handler->createContextMenu (view, paramID);
  95         if (menu)
  96         {
  97                 // here you can add your entries (optional)
  98                 PluginContextMenuTarget* target = new PluginContextMenuTarget ();
  99
 100                 IContextMenu::Item item = {0};
 101                 UString128 ("My Item 1").copyTo (item.name, 128);
 102                 item.tag = 1;
 103                 menu->addItem (item, target);
 104
 105                 UString128 ("My Item 2").copyTo (item.name, 128);
 106                 item.tag = 2;
 107                 menu->addItem (item, target);
 108                 target->release ();
 109                 //--end of adding new entries
 110
 111                 // here the the context menu will be pop-up (and it waits a user interaction)
 112                 menu->popup (x, y);
 113                 menu->release ();
 114         }
 115 }
 116 \endcode
 117 */
 118 class IComponentHandler3 : public FUnknown
 119 {
 120 public:
 121         /** Creates a host context menu for a plug-in:
 122                 - If paramID is zero, the host may create a generic context menu.
 123                 - The IPlugView object must be valid.
 124                 - The return IContextMenu object needs to be released afterwards by the plug-in.
 125         */
 126         virtual IContextMenu* PLUGIN_API createContextMenu (IPlugView* plugView, const ParamID* paramID) = 0;
 127         //------------------------------------------------------------------------
 128         static const FUID iid;
 129 };
 130
 131 DECLARE_CLASS_IID (IComponentHandler3, 0x69F11617, 0xD26B400D, 0xA4B6B964, 0x7B6EBBAB)
 132
 133 //------------------------------------------------------------------------
 134 /** Context Menu Item Target interface: Vst::IContextMenuTarget
 135 \ingroup vstIHost vstIPlug vst350
 136 - [host imp]
 137 - [plug imp]
 138 - [released: 3.5.0]
 139 - [optional]
 140
 141 A receiver of a menu item should implement this interface, which will be called after the user has selected
 142 this menu item.
 143
 144 \see IComponentHandler3 for more information.
 145 */
 146 class IContextMenuTarget : public FUnknown
 147 {
 148 public:
 149         /** Called when an menu item was executed. */
 150         virtual tresult PLUGIN_API executeMenuItem (int32 tag) = 0;
 151         //------------------------------------------------------------------------
 152         static const FUID iid;
 153 };
 154
 155 DECLARE_CLASS_IID (IContextMenuTarget, 0x3CDF2E75, 0x85D34144, 0xBF86D36B, 0xD7C4894D)
 156
 157 //------------------------------------------------------------------------
 158 /** IContextMenuItem is an entry element of the context menu. */
 159 struct IContextMenuItem
 160 {
 161         String128 name;                                                                 ///< Name of the item
 162         int32 tag;                                                                              ///< Identifier tag of the item
 163         int32 flags;                                                                    ///< Flags of the item
 164
 165         enum Flags {
 166                 kIsSeparator    = 1 << 0,                                       ///< Item is a separator
 167                 kIsDisabled             = 1 << 1,                                       ///< Item is disabled
 168                 kIsChecked              = 1 << 2,                                       ///< Item is checked
 169                 kIsGroupStart   = 1 << 3 | kIsDisabled,         ///< Item is a group start (like sub folder)
 170                 kIsGroupEnd             = 1 << 4 | kIsSeparator,        ///< Item is a group end
 171         };
 172 };
 173 //------------------------------------------------------------------------
 174 /** Context Menu interface: Vst::IContextMenu
 175 \ingroup vstIHost vst350
 176 - [host imp]
 177 - [create with IComponentHandler3::createContextMenu(..)]
 178 - [released: 3.5.0]
 179 - [optional]
 180
 181 A context menu is composed of Item (entry). A Item is defined by a name, a tag, a flag
 182 and a associated target (called when this item will be selected/executed).
 183 With IContextMenu the plug-in can retrieve a Item, add a Item, remove a Item and pop-up the menu.
 184
 185 \see IComponentHandler3 for more information.
 186 */
 187 class IContextMenu : public FUnknown
 188 {
 189 public:
 190         typedef IContextMenuItem Item;
 191
 192         /** Gets the number of menu items. */
 193         virtual int32 PLUGIN_API getItemCount () = 0;
 194
 195         /** Gets a menu item and its target (target could be not assigned). */
 196         virtual tresult PLUGIN_API getItem (int32 index, Item& item /*out*/, IContextMenuTarget** target /*out*/) = 0;
 197
 198         /** Adds a menu item and its target. */
 199         virtual tresult PLUGIN_API addItem (const Item& item, IContextMenuTarget* target) = 0;
 200
 201         /** Removes a menu item. */
 202         virtual tresult PLUGIN_API removeItem (const Item& item, IContextMenuTarget* target) = 0;
 203
 204         /** Pop-ups the menu. Coordinates are relative to the top-left position of the plug-ins view. */
 205         virtual tresult PLUGIN_API popup (UCoord x, UCoord y) = 0;
 206
 207         //------------------------------------------------------------------------
 208         static const FUID iid;
 209 };
 210
 211 DECLARE_CLASS_IID (IContextMenu, 0x2E93C863, 0x0C9C4588, 0x97DBECF5, 0xAD17817D)
 212
 213 //------------------------------------------------------------------------
 214 } // namespace Vst
 215 } // namespace Steinberg
 216
 217 //------------------------------------------------------------------------
 218 #include "pluginterfaces/base/falignpop.h"
 219 //------------------------------------------------------------------------