1/* This file is part of the KDE project
2 Copyright (C) 2006 Matthias Kretz <kretz@kde.org>
3
4 This library is free software; you can redistribute it and/or
5 modify it under the terms of the GNU Lesser General Public
6 License as published by the Free Software Foundation; either
7 version 2.1 of the License, or (at your option) version 3, or any
8 later version accepted by the membership of KDE e.V. (or its
9 successor approved by the membership of KDE e.V.), Nokia Corporation
10 (or its successors, if any) and the KDE Free Qt Foundation, which shall
11 act as a proxy defined in Section 6 of version 3 of the license.
12
13 This library is distributed in the hope that it will be useful,
14 but WITHOUT ANY WARRANTY; without even the implied warranty of
15 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
16 Lesser General Public License for more details.
17
18 You should have received a copy of the GNU Lesser General Public
19 License along with this library. If not, see <http://www.gnu.org/licenses/>.
20
21*/
22
23#ifndef PHONON_EFFECTPARAMETER_H
24#define PHONON_EFFECTPARAMETER_H
25
26#include "phonon_export.h"
27
28#include <QExplicitlySharedDataPointer>
29#include <QVariant>
30
31
32#ifndef QT_NO_PHONON_EFFECT
33
34namespace Phonon
35{
36
37class Effect;
38class EffectParameterPrivate;
39
40/** \class EffectParameter effectparameter.h phonon/EffectParameter
41 * \brief This class describes one parameter of an effect.
42 *
43 * \ingroup PhononEffects
44 * \author Matthias Kretz <kretz@kde.org>
45 * \see Effect
46 */
47class PHONON_EXPORT EffectParameter
48{
49 friend class BrightnessControl;
50 public:
51 /**
52 * \internal
53 *
54 * Creates an invalid effect parameter.
55 */
56 EffectParameter();
57
58 /**
59 * The name of the parameter. Can be used as the label.
60 *
61 * \return A label for the parameter.
62 */
63 const QString &name() const;
64
65 /**
66 * The parameter may come with a description (LADSPA doesn't have a
67 * field for this, so don't expect many effects to provide a
68 * description).
69 *
70 * The description can be used for a tooltip or WhatsThis help.
71 *
72 * \return A text describing the parameter.
73 */
74 const QString &description() const;
75
76 /**
77 * Returns the parameter type.
78 *
79 * Common types are QVariant::Int, QVariant::Double, QVariant::Bool and QVariant::String. When
80 * QVariant::String is returned you get the possible values from possibleValues.
81 */
82 QVariant::Type type() const;
83
84 /**
85 * Returns whether the parameter should be
86 * displayed using a logarithmic scale. This is particularly useful for
87 * frequencies and gains.
88 */
89 bool isLogarithmicControl() const;
90
91 /**
92 * The minimum value to be used for the control to edit the parameter.
93 *
94 * If the returned QVariant is invalid the value is not bounded from
95 * below.
96 */
97 QVariant minimumValue() const;
98
99 /**
100 * The maximum value to be used for the control to edit the parameter.
101 *
102 * If the returned QVariant is invalid the value is not bounded from
103 * above.
104 */
105 QVariant maximumValue() const;
106
107 /**
108 * The default value.
109 */
110 QVariant defaultValue() const;
111
112 /**
113 * The possible values to be used for the control to edit the parameter.
114 *
115 * if the value of this parameter is to be picked from predefined values
116 * this returns the list (otherwise it returns an empty QVariantList).
117 */
118 QVariantList possibleValues() const;
119
120 /**
121 * \internal
122 * compares the ids of the parameters
123 */
124 bool operator<(const EffectParameter &rhs) const;
125
126 /**
127 * \internal
128 * compares the ids of the parameters
129 */
130 bool operator>(const EffectParameter &rhs) const;
131
132 /**
133 * \internal
134 * compares the ids of the parameters
135 */
136 bool operator==(const EffectParameter &rhs) const;
137
138 /* dtor, cctor and operator= for forward decl of EffectParameterPrivate */
139 ~EffectParameter();
140 EffectParameter(const EffectParameter &rhs);
141 EffectParameter &operator=(const EffectParameter &rhs);
142
143 /**
144 * Only for backend developers:
145 *
146 * Flags to set the return values of isToggleControl(),
147 * isLogarithmicControl(), isIntegerControl(), isBoundedBelow() and
148 * isBoundedAbove(). The values of the flags correspond to the values
149 * used for LADSPA effects.
150 */
151 enum Hint {
152 /**
153 * If this hint is set it means that
154 * the control has only two states: zero and non-zero.
155 *
156 * \see isToggleControl()
157 */
158 ToggledHint = 0x04,
159
160 /* LADSPA's SAMPLE_RATE hint needs to be translated by the backend
161 * to normal bounds, as the backend knows the sample rate - and the
162 * frontend doesn't */
163
164 /**
165 * \see isLogarithmicControl()
166 */
167 LogarithmicHint = 0x10,
168 /**
169 * \see isIntegerControl
170 */
171 IntegerHint = 0x20
172 };
173 Q_DECLARE_FLAGS(Hints, Hint)
174
175 /**
176 * Only to be used by backend implementations:
177 *
178 * Creates a new effect parameter.
179 *
180 * \param parameterId This is a number to uniquely identify the
181 * parameter. The id is used for value() and setValue().
182 *
183 * \param name The name/label for this parameter.
184 *
185 * \param hints Sets the hints for the type of parameter.
186 *
187 * \param defaultValue The value that should be used as a default.
188 *
189 * \param min The minimum value allowed for this parameter. You only
190 * need to set this if the BoundedBelowHint is set.
191 *
192 * \param max The maximum value allowed for this parameter. You only
193 * need to set this if the BoundedAboveHint is set.
194 *
195 * \param description A descriptive text for the parameter
196 * (explaining what it controls) to be used as a tooltip or
197 * WhatsThis help.
198 */
199 EffectParameter(int parameterId, const QString &name, Hints hints,
200 const QVariant &defaultValue, const QVariant &min = QVariant(),
201 const QVariant &max = QVariant(), const QVariantList &values = QVariantList(),
202 const QString &description = QString());
203
204 /**
205 * \internal
206 *
207 * Returns the parameter's id.
208 */
209 int id() const;
210
211 protected:
212 /**
213 * The data is implicitly shared.
214 */
215 QExplicitlySharedDataPointer<EffectParameterPrivate> d;
216};
217
218Q_DECLARE_OPERATORS_FOR_FLAGS(EffectParameter::Hints)
219
220uint PHONON_EXPORT qHash(const Phonon::EffectParameter &param);
221
222} // namespace Phonon
223
224#if defined(Q_CC_MSVC) && _MSC_VER <= 1300
225//this ensures that code outside Phonon can use the hash function
226//it also a workaround for some compilers
227inline uint qHash(const Phonon::EffectParameter &param) { return Phonon::qHash(param); } //krazy:exclude=inline
228#endif
229
230#endif //QT_NO_PHONON_EFFECT
231
232
233#endif // PHONON_EFFECTPARAMETER_H
234// vim: sw=4 ts=4 tw=80
235

source code of phonon/phonon/effectparameter.h