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 | |
31 | QT_BEGIN_HEADER |
32 | QT_BEGIN_NAMESPACE |
33 | |
34 | #ifndef QT_NO_PHONON_EFFECT |
35 | |
36 | namespace Phonon |
37 | { |
38 | |
39 | class Effect; |
40 | class 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 | */ |
49 | class 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 | |
220 | uint PHONON_EXPORT qHash(const Phonon::EffectParameter ¶m); |
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 |
227 | inline uint qHash(const Phonon::EffectParameter ¶m) { return Phonon::qHash(param); } //krazy:exclude=inline |
228 | #endif |
229 | Q_DECLARE_OPERATORS_FOR_FLAGS(Phonon::EffectParameter::Hints) |
230 | |
231 | #endif //QT_NO_PHONON_EFFECT |
232 | |
233 | QT_END_NAMESPACE |
234 | QT_END_HEADER |
235 | |
236 | #endif // PHONON_EFFECTPARAMETER_H |
237 | // vim: sw=4 ts=4 tw=80 |
238 | |