Phonon

objectdescription.h
1/*
2 Copyright (C) 2006-2007 Matthias Kretz <kretz@kde.org>
3 Copyright (C) 2011 Harald Sitter <sitter@kde.org>
4
5 This library is free software; you can redistribute it and/or
6 modify it under the terms of the GNU Lesser General Public
7 License as published by the Free Software Foundation; either
8 version 2.1 of the License, or (at your option) version 3, or any
9 later version accepted by the membership of KDE e.V. (or its
10 successor approved by the membership of KDE e.V.), Nokia Corporation
11 (or its successors, if any) and the KDE Free Qt Foundation, which shall
12 act as a proxy defined in Section 6 of version 3 of the license.
13
14 This library is distributed in the hope that it will be useful,
15 but WITHOUT ANY WARRANTY; without even the implied warranty of
16 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
17 Lesser General Public License for more details.
18
19 You should have received a copy of the GNU Lesser General Public
20 License along with this library. If not, see <http://www.gnu.org/licenses/>.
21*/
22
23#ifndef PHONON_OBJECTDESCRIPTION_H
24#define PHONON_OBJECTDESCRIPTION_H
25
26#include "phonon_export.h"
27
28#include <QExplicitlySharedDataPointer>
29#include <QtDebug>
30#include <QList>
31#include <QSharedData>
32#include <QString>
33#include <QVariant>
34
35
36namespace Phonon
37{
38 class ObjectDescriptionPrivate;
39
40 /**
41 * Defines the type of information that is contained in a ObjectDescription
42 * object.
43 *
44 * \ingroup Backend
45 */
46 enum ObjectDescriptionType : unsigned
47 {
48 /**
49 * Audio output devices. This can be soundcards (with different drivers), soundservers or
50 * other virtual outputs like playback on a different computer on the
51 * network.
52 *
53 * For Hardware devices the backend should use libkaudiodevicelist
54 * (AudioDevice and AudioDeviceEnumerator) which will list removable
55 * devices even when they are unplugged and provide a unique identifier
56 * that can make backends use the same identifiers.
57 */
58 AudioOutputDeviceType,
59
60 /**
61 * Lists all processing effects the backend supports.
62 */
63 EffectType,
64 AudioChannelType,
65 SubtitleType,
66
67 /**
68 * Audio capture devices. This can be soundcards (with different drivers), soundservers or
69 * other virtual inputs like capture on a different computer on the
70 * network.
71 *
72 * For Hardware devices the backend should use libkaudiodevicelist
73 * (AudioDevice and AudioDeviceEnumerator) which will list removable
74 * devices even when they are unplugged and provide a unique identifier
75 * that can make backends use the same identifiers.
76 */
77 AudioCaptureDeviceType,
78
79 /**
80 * Video capture devices. Includes webcams.
81 */
82 VideoCaptureDeviceType
83
84 //VideoOutputDeviceType,
85 //AudioCodecType,
86 //VideoCodecType,
87 //ContainerFormatType,
88 //VisualizationType,
89 };
90
91/** \internal
92 * \class ObjectDescriptionData objectdescription.h phonon/ObjectDescription
93 * \brief Data class for objects describing devices or features of the backend.
94 *
95 * \author Matthias Kretz <kretz@kde.org>
96 * \see BackendCapabilities
97 */
98class PHONON_EXPORT ObjectDescriptionData : public QSharedData //krazy:exclude=dpointer (it's protected, which should be fine for this type of class)
99{
100 public:
101 /**
102 * Returns \c true if this ObjectDescription describes the same
103 * as \p otherDescription; otherwise returns \c false.
104 */
105 bool operator==(const ObjectDescriptionData &otherDescription) const;
106
107 /**
108 * Returns the name of the capture source.
109 *
110 * \return A string that should be presented to the user to
111 * choose the capture source.
112 */
113 QString name() const;
114
115 /**
116 * Returns a description of the capture source. This text should
117 * make clear what sound source this is, which is sometimes hard
118 * to describe or understand from just the name.
119 *
120 * \return A string describing the capture source.
121 */
122 QString description() const;
123
124 /**
125 * Returns a named property.
126 *
127 * If the property is not set an invalid value is returned.
128 *
129 * \see propertyNames()
130 */
131 QVariant property(const char *name) const;
132
133 /**
134 * Returns all names that return valid data when property() is called.
135 *
136 * \see property()
137 */
138 QList<QByteArray> propertyNames() const;
139
140 /**
141 * Returns \c true if the Tuple is valid (index != -1); otherwise returns
142 * \c false.
143 */
144 bool isValid() const;
145
146 /**
147 * A unique identifier for this device/. Used internally
148 * to distinguish between the devices/.
149 *
150 * \return An integer that uniquely identifies every device/
151 */
152 int index() const;
153
154 static ObjectDescriptionData *fromIndex(ObjectDescriptionType type, int index);
155
157
158 ObjectDescriptionData(ObjectDescriptionPrivate * = nullptr);
159 ObjectDescriptionData(int index, const QHash<QByteArray, QVariant> &properties);
160
161 protected:
162 ObjectDescriptionPrivate *const d;
163
164 private:
165 ObjectDescriptionData &operator=(const ObjectDescriptionData &rhs);
166};
167
168template<ObjectDescriptionType T> class ObjectDescriptionModel;
169
170/** \class ObjectDescription objectdescription.h phonon/ObjectDescription
171 * \short Provides a tuple of enduser visible name and description.
172 *
173 * Some parts give the enduser choices, e.g. what source to capture audio from.
174 * These choices are described by the name and description methods of this class
175 * and identified with the id method. Subclasses then define additional
176 * information like which audio and video choices belong together.
177 *
178 * \ingroup Frontend
179 * \author Matthias Kretz <kretz@kde.org>
180 */
181template<ObjectDescriptionType T>
183{
184 public:
185 /**
186 * Returns a new description object that describes the
187 * device/effect/codec/... with the given \p index.
188 */
189 static inline ObjectDescription<T> fromIndex(int index) { //krazy:exclude=inline
190 return ObjectDescription<T>(QExplicitlySharedDataPointer<ObjectDescriptionData>(ObjectDescriptionData::fromIndex(T, index)));
191 }
192
193 /**
194 * Returns \c true if this ObjectDescription describes the same
195 * as \p otherDescription; otherwise returns \c false.
196 */
197 inline bool operator==(const ObjectDescription &otherDescription) const { //krazy:exclude=inline
198 return *d == *otherDescription.d;
199 }
200
201 /**
202 * Returns \c false if this ObjectDescription describes the same
203 * as \p otherDescription; otherwise returns \c true.
204 */
205 inline bool operator!=(const ObjectDescription &otherDescription) const { //krazy:exclude=inline
206 return !operator==(otherDescription);
207 }
208
209 /**
210 * Returns the name of the capture source.
211 *
212 * \return A string that should be presented to the user to
213 * choose the capture source.
214 */
215 inline QString name() const { return d->name(); } //krazy:exclude=inline
216
217 /**
218 * Returns a description of the capture source. This text should
219 * make clear what sound source this is, which is sometimes hard
220 * to describe or understand from just the name.
221 *
222 * \return A string describing the capture source.
223 */
224 inline QString description() const { return d->description(); } //krazy:exclude=inline
225
226 /**
227 * Returns a named property.
228 *
229 * If the property is not set an invalid value is returned.
230 *
231 * \see propertyNames()
232 */
233 inline QVariant property(const char *name) const { return d->property(name); } //krazy:exclude=inline
234
235 /**
236 * Returns all names that return valid data when property() is called.
237 *
238 * \see property()
239 */
240 inline QList<QByteArray> propertyNames() const { return d->propertyNames(); } //krazy:exclude=inline
241
242 /**
243 * Returns \c true if the Tuple is valid (index != -1); otherwise returns
244 * \c false.
245 */
246 inline bool isValid() const { return d->isValid(); } //krazy:exclude=inline
247
248 /**
249 * A unique identifier for this device/. Used internally
250 * to distinguish between the devices/.
251 *
252 * \return An integer that uniquely identifies every device/
253 */
254 inline int index() const { return d->index(); } //krazy:exclude=inline
255
256 ObjectDescription() : d(new ObjectDescriptionData(nullptr)) {}
257 ObjectDescription(int index, const QHash<QByteArray, QVariant> &properties) : d(new ObjectDescriptionData(index, properties)) {}
258
259 protected:
260 friend class ObjectDescriptionModel<T>;
261 ObjectDescription(const QExplicitlySharedDataPointer<ObjectDescriptionData> &dd) : d(dd) {}
263};
264
265template<ObjectDescriptionType T>
266QDebug operator<<(QDebug dbg, const ObjectDescription<T> &d)
267{
268 dbg.nospace() << "\n{\n";
269 dbg.nospace() << " index: " << d.index() << "\n";
270 const QList<QByteArray> propertyNames = d.propertyNames();
271 for (const QByteArray &propertyName : propertyNames) {
272 dbg.nospace() << " " << propertyName << ": " <<
273 d.property(propertyName.constData()).toString() << "\n";
274 }
275 dbg.nospace() << "}\n";
276
277 return dbg.space();
278}
279
280/**
281 * \ingroup BackendInformation
282 */
283typedef ObjectDescription<AudioOutputDeviceType> AudioOutputDevice;
284/**
285 * \ingroup BackendInformation
286 */
287#ifndef PHONON_NO_AUDIOCAPTURE
288typedef ObjectDescription<AudioCaptureDeviceType> AudioCaptureDevice;
289#endif //PHONON_NO_AUDIOCAPTURE
290/**
291 * \ingroup BackendInformation
292 */
293//typedef ObjectDescription<VideoOutputDeviceType> VideoOutputDevice;
294/**
295 * \ingroup BackendInformation
296 */
297#ifndef PHONON_NO_VIDEOCAPTURE
298typedef ObjectDescription<VideoCaptureDeviceType> VideoCaptureDevice;
299#endif
300/**
301 * \ingroup BackendInformation
302 */
303#ifndef QT_NO_PHONON_EFFECT
304typedef ObjectDescription<EffectType> EffectDescription;
305#endif //QT_NO_PHONON_EFFECT
306
307/**
308 * \ingroup BackendInformation
309 */
310//typedef ObjectDescription<AudioCodecType> AudioCodecDescription;
311/**
312 * \ingroup BackendInformation
313 */
314//typedef ObjectDescription<VideoCodecType> VideoCodecDescription;
315/**
316 * \ingroup BackendInformation
317 */
318//typedef ObjectDescription<ContainerFormatType> ContainerFormatDescription;
319/**
320 * \ingroup BackendInformation
321 */
322//typedef ObjectDescription<VisualizationType> VisualizationDescription;
323#ifndef QT_NO_PHONON_MEDIACONTROLLER
324typedef ObjectDescription<AudioChannelType> AudioChannelDescription;
325typedef ObjectDescription<SubtitleType> SubtitleDescription;
326#endif //QT_NO_PHONON_MEDIACONTROLLER
327
328/**
329 * \short Information about how to access a device
330 * \ingroup BackendInformation
331 *
332 * To access a device, one needs the driver name (alsa, oss, pulse for example),
333 * and the device name (dependent on the driver name). This type is a pair of a
334 * driver and a device name.
335 *
336 * \see DeviceAccessList
337 */
338typedef QPair<QByteArray, QString> DeviceAccess;
339
340/**
341 * \short Information about methods for accessing a device
342 * \ingroup BackendInformation
343 *
344 * It is used by the platform plugin or the backend to provide information about how
345 * to access a certain device. To access a device, one needs the driver name (alsa, oss,
346 * pulse for example), and the device name (dependent on the driver name). This type
347 * is essentially a list of pairs of driver and device names.
348 *
349 * It can be put in an ObjectDescriptionData property list.
350 *
351 * \see DeviceAccess
352 * \see AudioCaptureDevice
353 */
354typedef QList<DeviceAccess> DeviceAccessList;
355
356#if QT_VERSION < QT_VERSION_CHECK(6, 0, 0)
357void PHONON_EXPORT_DEPRECATED registerMetaTypes();
358#endif
359
360} //namespace Phonon
361
362Q_DECLARE_METATYPE(Phonon::AudioOutputDevice)
363Q_DECLARE_METATYPE(QList<Phonon::AudioOutputDevice>)
364
365#ifndef PHONON_NO_AUDIOCAPTURE
366Q_DECLARE_METATYPE(Phonon::AudioCaptureDevice)
367Q_DECLARE_METATYPE(QList<Phonon::AudioCaptureDevice>)
368#endif //PHONON_NO_AUDIOCAPTURE
369
370#ifndef PHONON_NO_VIDEOCAPTURE
371Q_DECLARE_METATYPE(Phonon::VideoCaptureDevice)
372Q_DECLARE_METATYPE(QList<Phonon::VideoCaptureDevice>)
373#endif //PHONON_NO_VIDEOCAPTURE
374
375#ifndef QT_NO_PHONON_EFFECT
376Q_DECLARE_METATYPE(QList<Phonon::EffectDescription>)
377Q_DECLARE_METATYPE(Phonon::EffectDescription)
378#endif //QT_NO_PHONON_EFFECT
379
380
381#ifndef QT_NO_PHONON_MEDIACONTROLLER
382Q_DECLARE_METATYPE(Phonon::AudioChannelDescription)
383Q_DECLARE_METATYPE(Phonon::SubtitleDescription)
385Q_DECLARE_METATYPE(QList<Phonon::SubtitleDescription>)
386#endif //QT_NO_PHONON_MEDIACONTROLLER
387
388Q_DECLARE_METATYPE(Phonon::DeviceAccess)
389Q_DECLARE_METATYPE(Phonon::DeviceAccessList)
390
391
392
393#endif // PHONON_OBJECTDESCRIPTION_H
Data class for objects describing devices or features of the backend.
The ObjectDescriptionModel class provides a model from a list of ObjectDescription objects.
Provides a tuple of enduser visible name and description.
bool operator==(const ObjectDescription &otherDescription) const
Returns true if this ObjectDescription describes the same as otherDescription; otherwise returns fals...
QList< QByteArray > propertyNames() const
Returns all names that return valid data when property() is called.
static ObjectDescription< T > fromIndex(int index)
Returns a new description object that describes the device/effect/codec/... with the given index.
QVariant property(const char *name) const
Returns a named property.
bool isValid() const
Returns true if the Tuple is valid (index != -1); otherwise returns false.
QString description() const
Returns a description of the capture source.
int index() const
A unique identifier for this device/.
bool operator!=(const ObjectDescription &otherDescription) const
Returns false if this ObjectDescription describes the same as otherDescription; otherwise returns tru...
QString name() const
Returns the name of the capture source.
KTEXTEDITOR_EXPORT QDebug operator<<(QDebug s, const MovingCursor &cursor)
QDebug & nospace()
QDebug & space()
QString toString(T &&object)
This file is part of the KDE documentation.
Documentation copyright © 1996-2024 The KDE developers.
Generated on Fri May 24 2024 11:53:28 by doxygen 1.10.0 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.