Chris@50
|
1 /* -*- c-basic-offset: 4 indent-tabs-mode: nil -*- vi:set ts=8 sts=4 sw=4: */
|
Chris@50
|
2
|
Chris@50
|
3 /*
|
Chris@52
|
4 Sonic Visualiser
|
Chris@52
|
5 An audio file viewer and annotation editor.
|
Chris@52
|
6 Centre for Digital Music, Queen Mary, University of London.
|
Chris@52
|
7 This file copyright 2006 Chris Cannam.
|
Chris@50
|
8
|
Chris@52
|
9 This program is free software; you can redistribute it and/or
|
Chris@52
|
10 modify it under the terms of the GNU General Public License as
|
Chris@52
|
11 published by the Free Software Foundation; either version 2 of the
|
Chris@52
|
12 License, or (at your option) any later version. See the file
|
Chris@52
|
13 COPYING included with this distribution for more information.
|
Chris@50
|
14 */
|
Chris@50
|
15
|
Chris@50
|
16 #ifndef _PLUGIN_INSTANCE_H_
|
Chris@50
|
17 #define _PLUGIN_INSTANCE_H_
|
Chris@50
|
18
|
Chris@50
|
19 #include <string>
|
Chris@50
|
20 #include <vector>
|
Chris@50
|
21
|
Chris@55
|
22 #include "base/XmlExportable.h"
|
Chris@55
|
23
|
Chris@55
|
24 class QXmlAttributes;
|
Chris@55
|
25
|
Chris@50
|
26 /**
|
Chris@50
|
27 * A base class for plugins with optional configurable parameters,
|
Chris@50
|
28 * programs, etc.
|
Chris@50
|
29 *
|
Chris@50
|
30 * This does not provide the necessary interfaces to instantiate or
|
Chris@50
|
31 * run a plugin -- that depends on the plugin subclass, as different
|
Chris@50
|
32 * plugin types may have quite different operating structures. This
|
Chris@50
|
33 * class just specifies the necessary interface to show editable
|
Chris@50
|
34 * controls for the plugin to the user.
|
Chris@50
|
35 */
|
Chris@50
|
36
|
Chris@55
|
37 class PluginInstance : public XmlExportable
|
Chris@50
|
38 {
|
Chris@50
|
39 public:
|
Chris@50
|
40 /**
|
Chris@50
|
41 * Get the computer-usable name of the plugin. This should be
|
Chris@50
|
42 * reasonably short and contain no whitespace or punctuation
|
Chris@50
|
43 * characters. It may be shown to the user, but it won't be the
|
Chris@50
|
44 * main method for a user to identify a plugin (that will be the
|
Chris@50
|
45 * description, below).
|
Chris@50
|
46 */
|
Chris@50
|
47 virtual std::string getName() const = 0;
|
Chris@50
|
48
|
Chris@50
|
49 /**
|
Chris@50
|
50 * Get a human-readable description of the plugin. This should be
|
Chris@50
|
51 * self-contained, as it may be shown to the user in isolation
|
Chris@50
|
52 * without also showing the plugin's "name".
|
Chris@50
|
53 */
|
Chris@50
|
54 virtual std::string getDescription() const = 0;
|
Chris@50
|
55
|
Chris@50
|
56 /**
|
Chris@50
|
57 * Get the name of the author or vendor of the plugin in
|
Chris@50
|
58 * human-readable form.
|
Chris@50
|
59 */
|
Chris@50
|
60 virtual std::string getMaker() const = 0;
|
Chris@50
|
61
|
Chris@50
|
62 /**
|
Chris@50
|
63 * Get the version number of the plugin.
|
Chris@50
|
64 */
|
Chris@50
|
65 virtual int getPluginVersion() const = 0;
|
Chris@50
|
66
|
Chris@50
|
67 /**
|
Chris@50
|
68 * Get the copyright statement or licensing summary of the plugin.
|
Chris@50
|
69 */
|
Chris@50
|
70 virtual std::string getCopyright() const = 0;
|
Chris@50
|
71
|
Chris@57
|
72 /**
|
Chris@57
|
73 * Get the type of plugin (e.g. DSSI, etc). This is likely to be
|
Chris@57
|
74 * implemented by the immediate subclass, not by actual plugins.
|
Chris@57
|
75 */
|
Chris@57
|
76 virtual std::string getType() const = 0;
|
Chris@57
|
77
|
Chris@50
|
78
|
Chris@50
|
79 struct ParameterDescriptor
|
Chris@50
|
80 {
|
Chris@50
|
81 /**
|
Chris@50
|
82 * The name of the parameter, in computer-usable form. Should
|
Chris@55
|
83 * be reasonably short, and may only contain the characters
|
Chris@55
|
84 * [a-zA-Z0-9_].
|
Chris@50
|
85 */
|
Chris@50
|
86 std::string name;
|
Chris@50
|
87
|
Chris@50
|
88 /**
|
Chris@50
|
89 * The human-readable name of the parameter.
|
Chris@50
|
90 */
|
Chris@50
|
91 std::string description;
|
Chris@50
|
92
|
Chris@50
|
93 /**
|
Chris@50
|
94 * The unit of the parameter, in human-readable form.
|
Chris@50
|
95 */
|
Chris@50
|
96 std::string unit;
|
Chris@50
|
97
|
Chris@50
|
98 /**
|
Chris@50
|
99 * The minimum value of the parameter.
|
Chris@50
|
100 */
|
Chris@50
|
101 float minValue;
|
Chris@50
|
102
|
Chris@50
|
103 /**
|
Chris@50
|
104 * The maximum value of the parameter.
|
Chris@50
|
105 */
|
Chris@50
|
106 float maxValue;
|
Chris@50
|
107
|
Chris@50
|
108 /**
|
Chris@50
|
109 * The default value of the parameter.
|
Chris@50
|
110 */
|
Chris@50
|
111 float defaultValue;
|
Chris@50
|
112
|
Chris@50
|
113 /**
|
Chris@50
|
114 * True if the parameter values are quantized to a particular
|
Chris@50
|
115 * resolution.
|
Chris@50
|
116 */
|
Chris@50
|
117 bool isQuantized;
|
Chris@50
|
118
|
Chris@50
|
119 /**
|
Chris@50
|
120 * Quantization resolution of the parameter values (e.g. 1.0
|
Chris@50
|
121 * if they are all integers). Undefined if isQuantized is
|
Chris@50
|
122 * false.
|
Chris@50
|
123 */
|
Chris@50
|
124 float quantizeStep;
|
Chris@50
|
125 };
|
Chris@50
|
126
|
Chris@50
|
127 typedef std::vector<ParameterDescriptor> ParameterList;
|
Chris@50
|
128
|
Chris@50
|
129 /**
|
Chris@50
|
130 * Get the controllable parameters of this plugin.
|
Chris@50
|
131 */
|
Chris@50
|
132 virtual ParameterList getParameterDescriptors() const {
|
Chris@50
|
133 return ParameterList();
|
Chris@50
|
134 }
|
Chris@50
|
135
|
Chris@50
|
136 /**
|
Chris@50
|
137 * Get the value of a named parameter. The argument is the name
|
Chris@50
|
138 * field from that parameter's descriptor.
|
Chris@50
|
139 */
|
Chris@50
|
140 virtual float getParameter(std::string) const { return 0.0; }
|
Chris@50
|
141
|
Chris@50
|
142 /**
|
Chris@50
|
143 * Set a named parameter. The first argument is the name field
|
Chris@50
|
144 * from that parameter's descriptor.
|
Chris@50
|
145 */
|
Chris@50
|
146 virtual void setParameter(std::string, float) { }
|
Chris@50
|
147
|
Chris@50
|
148
|
Chris@50
|
149 typedef std::vector<std::string> ProgramList;
|
Chris@50
|
150
|
Chris@50
|
151 /**
|
Chris@50
|
152 * Get the program settings available in this plugin.
|
Chris@50
|
153 * The programs must have unique names.
|
Chris@50
|
154 */
|
Chris@50
|
155 virtual ProgramList getPrograms() const { return ProgramList(); }
|
Chris@50
|
156
|
Chris@50
|
157 /**
|
Chris@50
|
158 * Get the current program.
|
Chris@50
|
159 */
|
Chris@50
|
160 virtual std::string getCurrentProgram() const { return ""; }
|
Chris@50
|
161
|
Chris@50
|
162 /**
|
Chris@50
|
163 * Select a program. (If the given program name is not one of the
|
Chris@50
|
164 * available programs, do nothing.)
|
Chris@50
|
165 */
|
Chris@50
|
166 virtual void selectProgram(std::string) { }
|
Chris@55
|
167
|
Chris@55
|
168 /**
|
Chris@55
|
169 * Export plugin settings to XML.
|
Chris@55
|
170 */
|
Chris@55
|
171 virtual QString toXmlString(QString indent = "",
|
Chris@55
|
172 QString extraAttributes = "") const;
|
Chris@55
|
173
|
Chris@55
|
174 /**
|
Chris@55
|
175 * Set the parameters and program of a plugin from a set of XML
|
Chris@55
|
176 * attributes. This is a partial inverse of toXmlString.
|
Chris@55
|
177 */
|
Chris@55
|
178 virtual void setParameters(const QXmlAttributes &);
|
Chris@55
|
179
|
Chris@56
|
180 /**
|
Chris@56
|
181 * Set the parameters and program of a plugin from an XML plugin
|
Chris@56
|
182 * element as returned by toXmlString. This is a partial inverse
|
Chris@56
|
183 * of toXmlString.
|
Chris@56
|
184 */
|
Chris@56
|
185 virtual void setParametersFromXml(QString xml);
|
Chris@56
|
186
|
Chris@55
|
187 protected:
|
Chris@55
|
188 QString stripInvalidParameterNameCharacters(QString) const;
|
Chris@50
|
189 };
|
Chris@50
|
190
|
Chris@50
|
191 #endif
|