1 | /* This file is part of the KDE project |
2 | Copyright (C) 2006-2007 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_OBJECTDESCRIPTION_H |
24 | #define PHONON_OBJECTDESCRIPTION_H |
25 | |
26 | #include "phonon_export.h" |
27 | |
28 | #include <QtCore/QExplicitlySharedDataPointer> |
29 | #include <QtCore/QtDebug> |
30 | #include <QtCore/QList> |
31 | #include <QtCore/QSharedData> |
32 | #include <QtCore/QString> |
33 | #include <QtCore/QVariant> |
34 | |
35 | QT_BEGIN_HEADER |
36 | QT_BEGIN_NAMESPACE |
37 | |
38 | namespace Phonon |
39 | { |
40 | class ObjectDescriptionPrivate; |
41 | |
42 | /** |
43 | * Defines the type of information that is contained in a ObjectDescription |
44 | * object. |
45 | * |
46 | * \ingroup Backend |
47 | */ |
48 | enum ObjectDescriptionType |
49 | { |
50 | /** |
51 | * Audio output devices. This can be soundcards (with different drivers), soundservers or |
52 | * other virtual outputs like playback on a different computer on the |
53 | * network. |
54 | * |
55 | * For Hardware devices the backend should use libkaudiodevicelist |
56 | * (AudioDevice and AudioDeviceEnumerator) which will list removable |
57 | * devices even when they are unplugged and provide a unique identifier |
58 | * that can make backends use the same identifiers. |
59 | */ |
60 | AudioOutputDeviceType, |
61 | |
62 | /** |
63 | * Lists all processing effects the backend supports. |
64 | */ |
65 | EffectType, |
66 | AudioChannelType, |
67 | SubtitleType, |
68 | |
69 | /** |
70 | * Audio capture devices. This can be soundcards (with different drivers), soundservers or |
71 | * other virtual inputs like capture on a different computer on the |
72 | * network. |
73 | * |
74 | * For Hardware devices the backend should use libkaudiodevicelist |
75 | * (AudioDevice and AudioDeviceEnumerator) which will list removable |
76 | * devices even when they are unplugged and provide a unique identifier |
77 | * that can make backends use the same identifiers. |
78 | */ |
79 | AudioCaptureDeviceType |
80 | |
81 | //VideoOutputDeviceType, |
82 | //VideoCaptureDeviceType, |
83 | //AudioCodecType, |
84 | //VideoCodecType, |
85 | //ContainerFormatType, |
86 | //VisualizationType, |
87 | }; |
88 | |
89 | /** \internal |
90 | * \class ObjectDescriptionData objectdescription.h Phonon/ObjectDescription |
91 | * \brief Data class for objects describing devices or features of the backend. |
92 | * |
93 | * \author Matthias Kretz <kretz@kde.org> |
94 | * \see BackendCapabilities |
95 | */ |
96 | class PHONON_EXPORT ObjectDescriptionData : public QSharedData //krazy:exclude=dpointer (it's protected, which should be fine for this type of class) |
97 | { |
98 | public: |
99 | /** |
100 | * Returns \c true if this ObjectDescription describes the same |
101 | * as \p otherDescription; otherwise returns \c false. |
102 | */ |
103 | bool operator==(const ObjectDescriptionData &otherDescription) const; |
104 | |
105 | /** |
106 | * Returns the name of the capture source. |
107 | * |
108 | * \return A string that should be presented to the user to |
109 | * choose the capture source. |
110 | */ |
111 | QString name() const; |
112 | |
113 | /** |
114 | * Returns a description of the capture source. This text should |
115 | * make clear what sound source this is, which is sometimes hard |
116 | * to describe or understand from just the name. |
117 | * |
118 | * \return A string describing the capture source. |
119 | */ |
120 | QString description() const; |
121 | |
122 | /** |
123 | * Returns a named property. |
124 | * |
125 | * If the property is not set an invalid value is returned. |
126 | * |
127 | * \see propertyNames() |
128 | */ |
129 | QVariant property(const char *name) const; |
130 | |
131 | /** |
132 | * Returns all names that return valid data when property() is called. |
133 | * |
134 | * \see property() |
135 | */ |
136 | QList<QByteArray> propertyNames() const; |
137 | |
138 | /** |
139 | * Returns \c true if the Tuple is valid (index != -1); otherwise returns |
140 | * \c false. |
141 | */ |
142 | bool isValid() const; |
143 | |
144 | /** |
145 | * A unique identifier for this device/. Used internally |
146 | * to distinguish between the devices/. |
147 | * |
148 | * \return An integer that uniquely identifies every device/ |
149 | */ |
150 | int index() const; |
151 | |
152 | static ObjectDescriptionData *fromIndex(ObjectDescriptionType type, int index); |
153 | |
154 | ~ObjectDescriptionData(); |
155 | |
156 | ObjectDescriptionData(ObjectDescriptionPrivate * = 0); |
157 | ObjectDescriptionData(int index, const QHash<QByteArray, QVariant> &properties); |
158 | |
159 | protected: |
160 | ObjectDescriptionPrivate *const d; |
161 | |
162 | private: |
163 | ObjectDescriptionData &operator=(const ObjectDescriptionData &rhs); |
164 | }; |
165 | |
166 | template<ObjectDescriptionType T> class ObjectDescriptionModel; |
167 | |
168 | /** \class ObjectDescription objectdescription.h Phonon/ObjectDescription |
169 | * \short Provides a tuple of enduser visible name and description. |
170 | * |
171 | * Some parts give the enduser choices, e.g. what source to capture audio from. |
172 | * These choices are described by the name and description methods of this class |
173 | * and identified with the id method. Subclasses then define additional |
174 | * information like which audio and video choices belong together. |
175 | * |
176 | * \ingroup Frontend |
177 | * \author Matthias Kretz <kretz@kde.org> |
178 | */ |
179 | template<ObjectDescriptionType T> |
180 | class ObjectDescription |
181 | { |
182 | public: |
183 | /** |
184 | * Returns a new description object that describes the |
185 | * device/effect/codec/... with the given \p index. |
186 | */ |
187 | static inline ObjectDescription<T> fromIndex(int index) { //krazy:exclude=inline |
188 | return ObjectDescription<T>(QExplicitlySharedDataPointer<ObjectDescriptionData>(ObjectDescriptionData::fromIndex(T, index))); |
189 | } |
190 | |
191 | /** |
192 | * Returns \c true if this ObjectDescription describes the same |
193 | * as \p otherDescription; otherwise returns \c false. |
194 | */ |
195 | inline bool operator==(const ObjectDescription &otherDescription) const { //krazy:exclude=inline |
196 | return *d == *otherDescription.d; |
197 | } |
198 | |
199 | /** |
200 | * Returns \c false if this ObjectDescription describes the same |
201 | * as \p otherDescription; otherwise returns \c true. |
202 | */ |
203 | inline bool operator!=(const ObjectDescription &otherDescription) const { //krazy:exclude=inline |
204 | return !operator==(otherDescription); |
205 | } |
206 | |
207 | /** |
208 | * Returns the name of the capture source. |
209 | * |
210 | * \return A string that should be presented to the user to |
211 | * choose the capture source. |
212 | */ |
213 | inline QString name() const { return d->name(); } //krazy:exclude=inline |
214 | |
215 | /** |
216 | * Returns a description of the capture source. This text should |
217 | * make clear what sound source this is, which is sometimes hard |
218 | * to describe or understand from just the name. |
219 | * |
220 | * \return A string describing the capture source. |
221 | */ |
222 | inline QString description() const { return d->description(); } //krazy:exclude=inline |
223 | |
224 | /** |
225 | * Returns a named property. |
226 | * |
227 | * If the property is not set an invalid value is returned. |
228 | * |
229 | * \see propertyNames() |
230 | */ |
231 | inline QVariant property(const char *name) const { return d->property(name); } //krazy:exclude=inline |
232 | |
233 | /** |
234 | * Returns all names that return valid data when property() is called. |
235 | * |
236 | * \see property() |
237 | */ |
238 | inline QList<QByteArray> propertyNames() const { return d->propertyNames(); } //krazy:exclude=inline |
239 | |
240 | /** |
241 | * Returns \c true if the Tuple is valid (index != -1); otherwise returns |
242 | * \c false. |
243 | */ |
244 | inline bool isValid() const { return d->isValid(); } //krazy:exclude=inline |
245 | |
246 | /** |
247 | * A unique identifier for this device/. Used internally |
248 | * to distinguish between the devices/. |
249 | * |
250 | * \return An integer that uniquely identifies every device/ |
251 | */ |
252 | inline int index() const { return d->index(); } //krazy:exclude=inline |
253 | |
254 | ObjectDescription() : d(new ObjectDescriptionData(0)) {} |
255 | ObjectDescription(int index, const QHash<QByteArray, QVariant> &properties) : d(new ObjectDescriptionData(index, properties)) {} |
256 | |
257 | protected: |
258 | friend class ObjectDescriptionModel<T>; |
259 | ObjectDescription(const QExplicitlySharedDataPointer<ObjectDescriptionData> &dd) : d(dd) {} |
260 | QExplicitlySharedDataPointer<ObjectDescriptionData> d; |
261 | }; |
262 | |
263 | template<ObjectDescriptionType T> |
264 | inline QDebug operator<<(QDebug s, const ObjectDescription<T> &o) //krazy:exclude=inline |
265 | { |
266 | return s << o.name(); |
267 | } |
268 | |
269 | /** |
270 | * \ingroup BackendInformation |
271 | */ |
272 | typedef ObjectDescription<AudioOutputDeviceType> AudioOutputDevice; |
273 | /** |
274 | * \ingroup BackendInformation |
275 | */ |
276 | #ifndef QT_NO_PHONON_AUDIOCAPTURE |
277 | typedef ObjectDescription<AudioCaptureDeviceType> AudioCaptureDevice; |
278 | #endif //QT_NO_PHONON_AUDIOCAPTURE |
279 | /** |
280 | * \ingroup BackendInformation |
281 | */ |
282 | //typedef ObjectDescription<VideoOutputDeviceType> VideoOutputDevice; |
283 | /** |
284 | * \ingroup BackendInformation |
285 | */ |
286 | //typedef ObjectDescription<VideoCaptureDeviceType> VideoCaptureDevice; |
287 | /** |
288 | * \ingroup BackendInformation |
289 | */ |
290 | #ifndef QT_NO_PHONON_EFFECT |
291 | typedef ObjectDescription<EffectType> EffectDescription; |
292 | #endif //QT_NO_PHONON_EFFECT |
293 | |
294 | /** |
295 | * \ingroup BackendInformation |
296 | */ |
297 | //typedef ObjectDescription<AudioCodecType> AudioCodecDescription; |
298 | /** |
299 | * \ingroup BackendInformation |
300 | */ |
301 | //typedef ObjectDescription<VideoCodecType> VideoCodecDescription; |
302 | /** |
303 | * \ingroup BackendInformation |
304 | */ |
305 | //typedef ObjectDescription<ContainerFormatType> ContainerFormatDescription; |
306 | /** |
307 | * \ingroup BackendInformation |
308 | */ |
309 | //typedef ObjectDescription<VisualizationType> VisualizationDescription; |
310 | #ifndef QT_NO_PHONON_MEDIACONTROLLER |
311 | typedef ObjectDescription<AudioChannelType> AudioChannelDescription; |
312 | typedef ObjectDescription<SubtitleType> SubtitleDescription; |
313 | #endif //QT_NO_PHONON_MEDIACONTROLLER |
314 | |
315 | } //namespace Phonon |
316 | |
317 | QT_END_NAMESPACE |
318 | |
319 | Q_DECLARE_METATYPE(Phonon::AudioOutputDevice) |
320 | Q_DECLARE_METATYPE(QList<Phonon::AudioOutputDevice>) |
321 | |
322 | #ifndef QT_NO_PHONON_AUDIOCAPTURE |
323 | Q_DECLARE_METATYPE(Phonon::AudioCaptureDevice) |
324 | Q_DECLARE_METATYPE(QList<Phonon::AudioCaptureDevice>) |
325 | #endif //QT_NO_PHONON_AUDIOCAPTURE |
326 | |
327 | #ifndef QT_NO_PHONON_EFFECT |
328 | Q_DECLARE_METATYPE(QList<Phonon::EffectDescription>) |
329 | Q_DECLARE_METATYPE(Phonon::EffectDescription) |
330 | #endif //QT_NO_PHONON_EFFECT |
331 | |
332 | |
333 | #ifndef QT_NO_PHONON_MEDIACONTROLLER |
334 | Q_DECLARE_METATYPE(Phonon::AudioChannelDescription) |
335 | Q_DECLARE_METATYPE(Phonon::SubtitleDescription) |
336 | Q_DECLARE_METATYPE(QList<Phonon::AudioChannelDescription>) |
337 | Q_DECLARE_METATYPE(QList<Phonon::SubtitleDescription>) |
338 | #endif //QT_NO_PHONON_MEDIACONTROLLER |
339 | |
340 | QT_END_HEADER |
341 | |
342 | #endif // PHONON_OBJECTDESCRIPTION_H |
343 | |