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 <QtCore/QExplicitlySharedDataPointer>
29#include <QtCore/QVariant>
30
31QT_BEGIN_HEADER
32QT_BEGIN_NAMESPACE
33
34#ifndef QT_NO_PHONON_EFFECT
35
36namespace Phonon
37{
38
39class Effect;
40class EffectParameterPrivate;
41
42/** \class EffectParameter effectparameter.h Phonon/EffectParameter
43 * \brief This class describes one parameter of an effect.
44 *
45 * \ingroup PhononEffects
46 * \author Matthias Kretz <kretz@kde.org>
47 * \see Effect
48 */
49class PHONON_EXPORT EffectParameter
50{
51 friend class BrightnessControl;
52 public:
53 /**
54 * \internal
55 *
56 * Creates an invalid effect parameter.
57 */
58 EffectParameter();
59
60 /**
61 * The name of the parameter. Can be used as the label.
62 *
63 * \return A label for the parameter.
64 */
65 const QString &name() const;
66
67 /**
68 * The parameter may come with a description (LADSPA doesn't have a
69 * field for this, so don't expect many effects to provide a
70 * description).
71 *
72 * The description can be used for a tooltip or WhatsThis help.
73 *
74 * \return A text describing the parameter.
75 */
76 const QString &description() const;
77
78 /**
79 * Returns the parameter type.
80 *
81 * Common types are QVariant::Int, QVariant::Double, QVariant::Bool and QVariant::String. When
82 * QVariant::String is returned you get the possible values from possibleValues.
83 */
84 QVariant::Type type() const;
85
86 /**
87 * Returns whether the parameter should be
88 * displayed using a logarithmic scale. This is particularly useful for
89 * frequencies and gains.
90 */
91 bool isLogarithmicControl() const;
92
93 /**
94 * The minimum value to be used for the control to edit the parameter.
95 *
96 * If the returned QVariant is invalid the value is not bounded from
97 * below.
98 */
99 QVariant minimumValue() const;
100
101 /**
102 * The maximum value to be used for the control to edit the parameter.
103 *
104 * If the returned QVariant is invalid the value is not bounded from
105 * above.
106 */
107 QVariant maximumValue() const;
108
109 /**
110 * The default value.
111 */
112 QVariant defaultValue() const;
113
114 /**
115 * The possible values to be used for the control to edit the parameter.
116 *
117 * if the value of this parameter is to be picked from predefined values
118 * this returns the list (otherwise it returns an empty QVariantList).
119 */
120 QVariantList possibleValues() const;
121
122 /**
123 * \internal
124 * compares the ids of the parameters
125 */
126 bool operator<(const EffectParameter &rhs) const;
127
128 /**
129 * \internal
130 * compares the ids of the parameters
131 */
132 bool operator>(const EffectParameter &rhs) const;
133
134 /**
135 * \internal
136 * compares the ids of the parameters
137 */
138 bool operator==(const EffectParameter &rhs) const;
139
140 /* dtor, cctor and operator= for forward decl of EffectParameterPrivate */
141 ~EffectParameter();
142 EffectParameter(const EffectParameter &rhs);
143 EffectParameter &operator=(const EffectParameter &rhs);
144
145 /**
146 * Only for backend developers:
147 *
148 * Flags to set the return values of isToggleControl(),
149 * isLogarithmicControl(), isIntegerControl(), isBoundedBelow() and
150 * isBoundedAbove(). The values of the flags correspond to the values
151 * used for LADSPA effects.
152 */
153 enum Hint {
154 /**
155 * If this hint is set it means that
156 * the the control has only two states: zero and non-zero.
157 *
158 * \see isToggleControl()
159 */
160 ToggledHint = 0x04,
161
162 /* LADSPA's SAMPLE_RATE hint needs to be translated by the backend
163 * to normal bounds, as the backend knows the sample rate - and the
164 * frontend doesn't */
165
166 /**
167 * \see isLogarithmicControl()
168 */
169 LogarithmicHint = 0x10,
170 /**
171 * \see isIntegerControl
172 */
173 IntegerHint = 0x20
174 };
175 Q_DECLARE_FLAGS(Hints, Hint)
176
177 /**
178 * Only to be used by backend implementations:
179 *
180 * Creates a new effect parameter.
181 *
182 * \param parameterId This is a number to uniquely identify the
183 * parameter. The id is used for value() and setValue().
184 *
185 * \param name The name/label for this parameter.
186 *
187 * \param hints Sets the hints for the type of parameter.
188 *
189 * \param defaultValue The value that should be used as a default.
190 *
191 * \param min The minimum value allowed for this parameter. You only
192 * need to set this if the BoundedBelowHint is set.
193 *
194 * \param max The maximum value allowed for this parameter. You only
195 * need to set this if the BoundedAboveHint is set.
196 *
197 * \param description A descriptive text for the parameter
198 * (explaining what it controls) to be used as a tooltip or
199 * WhatsThis help.
200 */
201 EffectParameter(int parameterId, const QString &name, Hints hints,
202 const QVariant &defaultValue, const QVariant &min = QVariant(),
203 const QVariant &max = QVariant(), const QVariantList &values = QVariantList(),
204 const QString &description = QString());
205
206 /**
207 * \internal
208 *
209 * Returns the parameter's id.
210 */
211 int id() const;
212
213 protected:
214 /**
215 * The data is implicitly shared.
216 */
217 QExplicitlySharedDataPointer<EffectParameterPrivate> d;
218};
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
229Q_DECLARE_OPERATORS_FOR_FLAGS(Phonon::EffectParameter::Hints)
230
231#endif //QT_NO_PHONON_EFFECT
232
233QT_END_NAMESPACE
234QT_END_HEADER
235
236#endif // PHONON_EFFECTPARAMETER_H
237// vim: sw=4 ts=4 tw=80
238