| /* This file is part of the KDE project |
| Copyright (C) 2007 Matthias Kretz <kretz@kde.org> |
| |
| This library is free software; you can redistribute it and/or |
| modify it under the terms of the GNU Lesser General Public |
| License as published by the Free Software Foundation; either |
| version 2.1 of the License, or (at your option) version 3, or any |
| later version accepted by the membership of KDE e.V. (or its |
| successor approved by the membership of KDE e.V.), Nokia Corporation |
| (or its successors, if any) and the KDE Free Qt Foundation, which shall |
| act as a proxy defined in Section 6 of version 3 of the license. |
| |
| This library is distributed in the hope that it will be useful, |
| but WITHOUT ANY WARRANTY; without even the implied warranty of |
| MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU |
| Lesser General Public License for more details. |
| |
| You should have received a copy of the GNU Lesser General Public |
| License along with this library. If not, see <http://www.gnu.org/licenses/>. |
| |
| */ |
| |
| #ifndef PHONON_PATH_H |
| #define PHONON_PATH_H |
| |
| #include "phonon_export.h" |
| #include "objectdescription.h" |
| |
| #include <QtCore/QExplicitlySharedDataPointer> |
| |
| QT_BEGIN_HEADER |
| QT_BEGIN_NAMESPACE |
| |
| template<class T> class QList; |
| |
| namespace Phonon |
| { |
| |
| class PathPrivate; |
| class Effect; |
| class MediaNode; |
| |
| /** \class Path path.h Phonon/Path |
| * \short Connection object providing convenient effect insertion |
| * |
| * \code |
| MediaObject *media = new MediaObject; |
| AudioOutput *output = new AudioOutput(Phonon::MusicCategory); |
| Path path = Phonon::createPath(media, output); |
| Q_ASSERT(path.isValid()); // for this simple case the path should always be |
| //valid - there are unit tests to ensure it |
| // insert an effect |
| QList<EffectDescription> effectList = BackendCapabilities::availableAudioEffects(); |
| if (!effectList.isEmpty()) { |
| Effect *effect = path.insertEffect(effectList.first()); |
| } |
| * \endcode |
| * \ingroup Playback |
| * \ingroup Recording |
| * \author Matthias Kretz <kretz@kde.org> |
| * \author Thierry Bastian <thierry.bastian@trolltech.com> |
| */ |
| class PHONON_EXPORT Path |
| { |
| friend class FactoryPrivate; |
| public: |
| /** |
| * Destroys this reference to the Path. If the path was valid the connection is not broken |
| * as both the source and the sink MediaNodes still keep a reference to the Path. |
| * |
| * \see disconnect |
| */ |
| ~Path(); |
| |
| /** |
| * Creates an invalid path. |
| * |
| * You can still make it a valid path by calling reconnect. To create a path you should use |
| * createPath, though. |
| * |
| * \see createPath |
| * \see isValid |
| */ |
| Path(); |
| |
| /** |
| * Constructs a copy of the given path. |
| * |
| * This constructor is fast thanks to explicit sharing. |
| */ |
| Path(const Path &); |
| |
| /** |
| * Returns whether the path object connects two MediaNodes or not. |
| * |
| * \return \p true when the path connects two MediaNodes |
| * \return \p false when the path is disconnected |
| */ |
| bool isValid() const; |
| //MediaStreamTypes mediaStreamTypes() const; |
| |
| #ifndef QT_NO_PHONON_EFFECT |
| /** |
| * Creates and inserts an effect into the path. |
| * |
| * You may insert effects of the same class as often as you like, |
| * but if you insert the same object, the call will fail. |
| * |
| * \param desc The EffectDescription object for the effect to be inserted. |
| * |
| * \param insertBefore If you already inserted an effect you can |
| * tell with this parameter in which order the data gets |
| * processed. If this is \c 0 the effect is appended at the end of |
| * the processing list. If the effect has not been inserted before |
| * the method will do nothing and return \c false. |
| * |
| * \return Returns a pointer to the effect object if it could be inserted |
| * at the specified position. If \c 0 is returned the effect was not |
| * inserted. |
| * |
| * \see removeEffect |
| * \see effects |
| */ |
| Effect *insertEffect(const EffectDescription &desc, Effect *insertBefore = 0); |
| |
| /** |
| * Inserts an effect into the path. |
| * |
| * You may insert effects of the same class as often as you like, |
| * but if you insert the same object, the call will fail. |
| * |
| * \param newEffect An Effect object. |
| * |
| * \param insertBefore If you already inserted an effect you can |
| * tell with this parameter in which order the data gets |
| * processed. If this is \c 0 the effect is appended at the end of |
| * the processing list. If the effect has not been inserted before |
| * the method will do nothing and return \c false. |
| * |
| * \return Returns whether the effect could be inserted at the |
| * specified position. If \c false is returned the effect was not |
| * inserted. |
| * |
| * \see removeEffect |
| * \see effects |
| */ |
| bool insertEffect(Effect *newEffect, Effect *insertBefore = 0); |
| |
| /** |
| * Removes an effect from the path. |
| * |
| * If the effect gets deleted while it is still connected the effect |
| * will be removed automatically. |
| * |
| * \param effect The effect to be removed. |
| * |
| * \return Returns whether the call was successful. If it returns |
| * \c false the effect could not be found in the path, meaning it |
| * has not been inserted before. |
| * |
| * \see insertEffect |
| * \see effects |
| */ |
| bool removeEffect(Effect *effect); |
| |
| /** |
| * Returns a list of Effect objects that are currently |
| * used as effects. The order in the list determines the order the |
| * signal is sent through the effects. |
| * |
| * \return A list with all current effects. |
| * |
| * \see insertEffect |
| * \see removeEffect |
| */ |
| QList<Effect *> effects() const; |
| #endif //QT_NO_PHONON_EFFECT |
| |
| /** |
| * Tries to change the MediaNodes the path is connected to. |
| * |
| * If reconnect fails the old connection is kept. |
| */ |
| bool reconnect(MediaNode *source, MediaNode *sink); |
| |
| /** |
| * Disconnects the path from the MediaNodes it was connected to. This invalidates the path |
| * (isValid returns \p false then). |
| */ |
| bool disconnect(); |
| |
| /** |
| * Assigns \p p to this Path and returns a reference to this Path. |
| * |
| * This operation is fast thanks to explicit sharing. |
| */ |
| Path &operator=(const Path &p); |
| |
| /** |
| * Returns \p true if this Path is equal to \p p; otherwise returns \p false; |
| */ |
| bool operator==(const Path &p) const; |
| |
| /** |
| * Returns \p true if this Path is not equal to \p p; otherwise returns \p false; |
| */ |
| bool operator!=(const Path &p) const; |
| |
| /** |
| * Returns the source MediaNode used by the path. |
| */ |
| MediaNode *source() const; |
| |
| /** |
| * Returns the sink MediaNode used by the path. |
| */ |
| MediaNode *sink() const; |
| |
| |
| protected: |
| friend class PathPrivate; |
| QExplicitlySharedDataPointer<PathPrivate> d; |
| }; |
| |
| /** |
| * \relates Path |
| * Creates a new Path connecting two MediaNodes. |
| * |
| * The implementation will automatically select the right format and media type. E.g. connecting a |
| * MediaObject and AudioOutput will create a Path object connecting the audio. This might be |
| * represented as PCM or perhaps even AC3 depending on the AudioOutput object. |
| * |
| * \param source The MediaNode to connect an output from |
| * \param sink The MediaNode to connect to. |
| */ |
| PHONON_EXPORT Path createPath(MediaNode *source, MediaNode *sink); |
| |
| } // namespace Phonon |
| |
| QT_END_NAMESPACE |
| QT_END_HEADER |
| |
| #endif // PHONON_PATH_H |