1 //************************************************************************************************
2 //
3 // PreSonus Plug-In Extensions
4 // Written and placed in the PUBLIC DOMAIN by PreSonus Software Ltd.
5 //
6 // Filename    : ipslhostcommands.h
7 // Created by  : PreSonus Software Ltd., 11/2009
8 // Description : Host Command Interface
9 //
10 //************************************************************************************************
11 /*
12 	DISCLAIMER:
13 	The PreSonus Plug-In Extensions are host-specific extensions of existing proprietary technologies,
14 	provided to the community on an AS IS basis. They are not part of any official 3rd party SDK and
15 	PreSonus is not affiliated with the owner of the underlying technology in any way.
16 */
17 //************************************************************************************************
18 
19 #ifndef _ipslhostcommands_h
20 #define _ipslhostcommands_h
21 
22 #include "pluginterfaces/vst/vsttypes.h"
23 #include "pluginterfaces/base/funknown.h"
24 #include "pluginterfaces/base/falignpush.h"
25 
26 namespace Steinberg {
27 class IPlugView; }
28 
29 namespace Presonus {
30 
31 struct ICommandList;
32 
33 //************************************************************************************************
34 // IHostCommandHandler
35 /** Callback interface to access host-specific parameter commands to be integrated
36 	into a context menu inside the plug-in editor. Implemented as extension of
37 	Steinberg::Vst::IComponentHandler.
38 
39 	Please note that the intention of this set of interfaces is not to allow a generic menu
40 	implementation. This is the responsibility of a GUI toolkit. It basically provides
41 	a way to enumerate and execute commands anonymously, i.e. the plug-in does not have to
42 	know the exact sematics of the commands and the host does not break the consistency of
43 	the plug-in GUI.
44 
45 	Usage Example:
46 
47 	IComponentHandler* handler;
48 	FUnknownPtr<IHostCommandHandler> commandHandler (handler);
49 	if(commandHandler)
50 		if(ICommandList* commandList = commandHandler->createParamCommands (kMyParamId))
51 		{
52 			FReleaser commandListReleaser (commandList);
53 			commandHandler->popupCommandMenu (commandList, xPos, yPos);
54 		}
55 */
56 //************************************************************************************************
57 
58 struct IHostCommandHandler: Steinberg::FUnknown
59 {
60 	/**	Create list of currently available host commands for given parameter.
61 		The command list has a short lifecycle, it is recreated whenever
62 		a context menu should appear. The returned pointer can be null, otherwise
63 		it has to be released. */
64 	virtual ICommandList* PLUGIN_API createParamCommands (Steinberg::Vst::ParamID tag) = 0;
65 
66 	/** Helper to popup a command menu at given position.
67 		Coordinates are relative to view or in screen coordintes if view is null.
68 		Can be used for testing purpose, if the plug-in does not have its own context menu implementation
69 		or if it wants to use the look & feel of the host menu. This method is not supposed
70 		to support command lists implemented by the plug-in. */
71 	virtual Steinberg::tresult PLUGIN_API popupCommandMenu (ICommandList* commandList, Steinberg::int32 xPos, Steinberg::int32 yPos, Steinberg::IPlugView* view = 0) = 0;
72 
73 	static const Steinberg::FUID iid;
74 };
75 
76 DECLARE_CLASS_IID (IHostCommandHandler, 0xF92032CD, 0x7A84407C, 0xABE6F863, 0x058EA6C2)
77 
78 //************************************************************************************************
79 // CommandInfo
80 /** Describes a single command. */
81 //************************************************************************************************
82 
83 struct CommandInfo
84 {
85 	Steinberg::Vst::String128 title;	///< command title (possibly localized into active host language)
86 	Steinberg::int32 flags;				///< command flags
87 
88 	enum CommandFlags
89 	{
90 		kCanExecute  = 1<<0,	///< used to display command enabled/disabled
91 		kIsSeparator = 1<<1,	///< not a command, it's a separator
92 		kIsChecked   = 1<<2		///< used to display command with a check mark
93 	};
94 };
95 
96 //************************************************************************************************
97 // ICommandList
98 /** Describes a list of commands. */
99 //************************************************************************************************
100 
101 struct ICommandList: Steinberg::FUnknown
102 {
103 	/** Returns the number of commands. */
104 	virtual Steinberg::int32 PLUGIN_API getCommandCount () = 0;
105 
106 	/** Get command information for a given index. */
107 	virtual Steinberg::tresult PLUGIN_API getCommandInfo (Steinberg::int32 index, CommandInfo& info) = 0;
108 
109 	/** Execute command at given index. */
110 	virtual Steinberg::tresult PLUGIN_API executeCommand (Steinberg::int32 index) = 0;
111 
112 	static const Steinberg::FUID iid;
113 };
114 
115 DECLARE_CLASS_IID (ICommandList, 0xC5A687DB, 0x82F344E9, 0xB378254A, 0x47C4D712)
116 
117 } // namespace Presonus
118 
119 #include "pluginterfaces/base/falignpop.h"
120 
121 #endif // _ipslhostcommands_h
122