phonon/objectdescription.h

   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 Library General Public
   6     License version 2 as published by the Free Software Foundation.
   7
   8     This library is distributed in the hope that it will be useful,
   9     but WITHOUT ANY WARRANTY; without even the implied warranty of
  10     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  11     Library General Public License for more details.
  12
  13     You should have received a copy of the GNU Library General Public License
  14     along with this library; see the file COPYING.LIB.  If not, write to
  15     the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
  16     Boston, MA 02110-1301, USA.
  17
  18 */
  19
  20 #ifndef PHONON_OBJECTDESCRIPTION_H
  21 #define PHONON_OBJECTDESCRIPTION_H
  22
  23 #include <QtGlobal>
  24 #include <kdelibs_export.h>
  25 #include <QSharedDataPointer>
  26 #include <QVariant>
  27 #include <QByteArray>
  28 #include <QList>
  29 class QString;
  30
  31 namespace Phonon
  32 {
  33         class ObjectDescriptionPrivate;
  34
  35         enum ObjectDescriptionType
  36         {
  37                 AudioOutputDeviceType,
  38                 AudioCaptureDeviceType,
  39                 VideoOutputDeviceType,
  40                 VideoCaptureDeviceType,
  41                 AudioEffectType,
  42                 VideoEffectType,
  43                 AudioCodecType,
  44                 VideoCodecType,
  45                 ContainerFormatType,
  46                 VisualizationType
  47         };
  48
  49 /**
  50  * \short Provides a tuple of enduser visible name and description.
  51  *
  52  * Some parts give the enduser choices, e.g. what source to capture audio from.
  53  * These choices are described by the name and description methods of this class
  54  * and identified with the id method. Subclasses then define additional
  55  * information like which audio and video choices belong together.
  56  *
  57  * \author Matthias Kretz <kretz@kde.org>
  58  * \see AudioCaptureDevice
  59  * \see VideoCaptureDevice
  60  */
  61 template<ObjectDescriptionType T>
  62 class PHONONCORE_EXPORT ObjectDescription
  63 {
  64         public:
  65                 ObjectDescription( const ObjectDescription<T>& rhs );
  66                 ObjectDescription<T>& operator=( const ObjectDescription<T>& rhs );
  67                 ObjectDescription();
  68                 ~ObjectDescription();
  69
  70                 /**
  71                  * Returns \c true if this ObjectDescription describes the same
  72                  * as \p otherDescription; otherwise returns \c false.
  73                  */
  74                 bool operator==( const ObjectDescription<T>& otherDescription ) const;
  75
  76                 /**
  77                  * Returns the name of the capture source.
  78                  *
  79                  * \return A string that should be presented to the user to
  80                  * choose the capture source.
  81                  */
  82                 const QString& name() const;
  83
  84                 /**
  85                  * Returns a description of the capture source. This text should
  86                  * make clear what sound source this is, which is sometimes hard
  87                  * to describe or understand from just the name.
  88                  *
  89                  * \return A string describing the capture source.
  90                  */
  91                 const QString& description() const;
  92
  93         /**
  94          * Returns a named property.
  95          *
  96          * If the property is not set an invalid value is returned.
  97          *
  98          * \see propertyNames()
  99          */
 100         QVariant property(const char *name) const;
 101
 102         /**
 103          * Returns all names that return valid data when property() is called.
 104          *
 105          * \see property()
 106          */
 107         QList<QByteArray> propertyNames() const;
 108
 109                 /**
 110                  * A unique identifier for this capture source. Used internally
 111                  * to distinguish between the capture sources.
 112                  *
 113                  * \return An integer that uniquely identifies every capture
 114                  * source.
 115                  */
 116                 int index() const;
 117
 118                 /**
 119                  * Returns \c true if the Tuple is valid (index != -1); otherwise returns
 120                  * \c false.
 121                  */
 122                 bool isValid() const;
 123
 124                 /**
 125                  * \internal
 126                  * Returns a new description object that describes the
 127                  * device/effect/codec/...  with the given \p index.
 128                  */
 129                 static ObjectDescription<T> fromIndex( int index );
 130
 131         protected:
 132                 /**
 133                  * \internal
 134                  * Sets the data.
 135                  */
 136         ObjectDescription(int index, const QHash<QByteArray, QVariant>& properties);
 137
 138         private:
 139                 /**
 140                  * \internal
 141                  * The data is implicitly shared.
 142                  */
 143                 QSharedDataPointer<ObjectDescriptionPrivate> d;
 144 };
 145
 146 typedef ObjectDescription<AudioOutputDeviceType> AudioOutputDevice;
 147 typedef ObjectDescription<AudioCaptureDeviceType> AudioCaptureDevice;
 148 typedef ObjectDescription<VideoOutputDeviceType> VideoOutputDevice;
 149 typedef ObjectDescription<VideoCaptureDeviceType> VideoCaptureDevice;
 150 typedef ObjectDescription<AudioEffectType> AudioEffectDescription;
 151 typedef ObjectDescription<VideoEffectType> VideoEffectDescription;
 152 typedef ObjectDescription<AudioCodecType> AudioCodecDescription;
 153 typedef ObjectDescription<VideoCodecType> VideoCodecDescription;
 154 typedef ObjectDescription<ContainerFormatType> ContainerFormatDescription;
 155 typedef ObjectDescription<VisualizationType> VisualizationDescription;
 156
 157 } //namespace Phonon
 158
 159 #endif // PHONON_OBJECTDESCRIPTION_H
 160 // vim: sw=4 ts=4 tw=80