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 | |
34 | namespace Phonon |
35 | { |
36 | |
37 | class Effect; |
38 | class 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 | */ |
47 | class 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 | |
218 | Q_DECLARE_OPERATORS_FOR_FLAGS(EffectParameter::Hints) |
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 | |
230 | #endif //QT_NO_PHONON_EFFECT |
231 | |
232 | |
233 | #endif // PHONON_EFFECTPARAMETER_H |
234 | // vim: sw=4 ts=4 tw=80 |
235 | |