1 | /* This file is part of the KDE project |
2 | Copyright (C) 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_PATH_H |
24 | #define PHONON_PATH_H |
25 | |
26 | #include "phonon_export.h" |
27 | #include "objectdescription.h" |
28 | |
29 | #include <QExplicitlySharedDataPointer> |
30 | |
31 | |
32 | template<class T> class QList; |
33 | |
34 | namespace Phonon |
35 | { |
36 | |
37 | class PathPrivate; |
38 | class Effect; |
39 | class MediaNode; |
40 | |
41 | /** \class Path path.h phonon/Path |
42 | * \short Connection object providing convenient effect insertion |
43 | * |
44 | * \code |
45 | MediaObject *media = new MediaObject; |
46 | AudioOutput *output = new AudioOutput(Phonon::MusicCategory); |
47 | Path path = Phonon::createPath(media, output); |
48 | Q_ASSERT(path.isValid()); // for this simple case the path should always be |
49 | //valid - there are unit tests to ensure it |
50 | // insert an effect |
51 | QList<EffectDescription> effectList = BackendCapabilities::availableAudioEffects(); |
52 | if (!effectList.isEmpty()) { |
53 | Effect *effect = path.insertEffect(effectList.first()); |
54 | } |
55 | * \endcode |
56 | * \ingroup Playback |
57 | * \ingroup Recording |
58 | * \author Matthias Kretz <kretz@kde.org> |
59 | * \author Thierry Bastian <thierry.bastian@trolltech.com> |
60 | */ |
61 | class PHONON_EXPORT Path |
62 | { |
63 | friend class FactoryPrivate; |
64 | public: |
65 | /** |
66 | * Destroys this reference to the Path. If the path was valid the connection is not broken |
67 | * as both the source and the sink MediaNodes still keep a reference to the Path. |
68 | * |
69 | * \see disconnect |
70 | */ |
71 | ~Path(); |
72 | |
73 | /** |
74 | * Creates an invalid path. |
75 | * |
76 | * You can still make it a valid path by calling reconnect. To create a path you should use |
77 | * createPath, though. |
78 | * |
79 | * \see createPath |
80 | * \see isValid |
81 | */ |
82 | Path(); |
83 | |
84 | /** |
85 | * Constructs a copy of the given path. |
86 | * |
87 | * This constructor is fast thanks to explicit sharing. |
88 | */ |
89 | Path(const Path &); |
90 | |
91 | /** |
92 | * Returns whether the path object connects two MediaNodes or not. |
93 | * |
94 | * \return \p true when the path connects two MediaNodes |
95 | * \return \p false when the path is disconnected |
96 | */ |
97 | bool isValid() const; |
98 | //MediaStreamTypes mediaStreamTypes() const; |
99 | |
100 | #ifndef QT_NO_PHONON_EFFECT |
101 | /** |
102 | * Creates and inserts an effect into the path. |
103 | * |
104 | * You may insert effects of the same class as often as you like, |
105 | * but if you insert the same object, the call will fail. |
106 | * |
107 | * \param desc The EffectDescription object for the effect to be inserted. |
108 | * |
109 | * \param insertBefore If you already inserted an effect you can |
110 | * tell with this parameter in which order the data gets |
111 | * processed. If this is \c 0 the effect is appended at the end of |
112 | * the processing list. If the effect has not been inserted before |
113 | * the method will do nothing and return \c false. |
114 | * |
115 | * \return Returns a pointer to the effect object if it could be inserted |
116 | * at the specified position. If \c 0 is returned the effect was not |
117 | * inserted. |
118 | * |
119 | * \see removeEffect |
120 | * \see effects |
121 | */ |
122 | Effect *insertEffect(const EffectDescription &desc, Effect *insertBefore = nullptr); |
123 | |
124 | /** |
125 | * Inserts an effect into the path. |
126 | * |
127 | * You may insert effects of the same class as often as you like, |
128 | * but if you insert the same object, the call will fail. |
129 | * |
130 | * \param newEffect An Effect object. |
131 | * |
132 | * \param insertBefore If you already inserted an effect you can |
133 | * tell with this parameter in which order the data gets |
134 | * processed. If this is \c 0 the effect is appended at the end of |
135 | * the processing list. If the effect has not been inserted before |
136 | * the method will do nothing and return \c false. |
137 | * |
138 | * \return Returns whether the effect could be inserted at the |
139 | * specified position. If \c false is returned the effect was not |
140 | * inserted. |
141 | * |
142 | * \see removeEffect |
143 | * \see effects |
144 | */ |
145 | bool insertEffect(Effect *newEffect, Effect *insertBefore = nullptr); |
146 | |
147 | /** |
148 | * Removes an effect from the path. |
149 | * |
150 | * If the effect gets deleted while it is still connected the effect |
151 | * will be removed automatically. |
152 | * |
153 | * \param effect The effect to be removed. |
154 | * |
155 | * \return Returns whether the call was successful. If it returns |
156 | * \c false the effect could not be found in the path, meaning it |
157 | * has not been inserted before. |
158 | * |
159 | * \see insertEffect |
160 | * \see effects |
161 | */ |
162 | bool removeEffect(Effect *effect); |
163 | |
164 | /** |
165 | * Returns a list of Effect objects that are currently |
166 | * used as effects. The order in the list determines the order the |
167 | * signal is sent through the effects. |
168 | * |
169 | * \return A list with all current effects. |
170 | * |
171 | * \see insertEffect |
172 | * \see removeEffect |
173 | */ |
174 | QList<Effect *> effects() const; |
175 | #endif //QT_NO_PHONON_EFFECT |
176 | |
177 | /** |
178 | * Tries to change the MediaNodes the path is connected to. |
179 | * |
180 | * If reconnect fails the old connection is kept. |
181 | */ |
182 | bool reconnect(MediaNode *source, MediaNode *sink); |
183 | |
184 | /** |
185 | * Disconnects the path from the MediaNodes it was connected to. This invalidates the path |
186 | * (isValid returns \p false then). |
187 | */ |
188 | bool disconnect(); |
189 | |
190 | /** |
191 | * Assigns \p p to this Path and returns a reference to this Path. |
192 | * |
193 | * This operation is fast thanks to explicit sharing. |
194 | */ |
195 | Path &operator=(const Path &p); |
196 | |
197 | /** |
198 | * Returns \p true if this Path is equal to \p p; otherwise returns \p false; |
199 | */ |
200 | bool operator==(const Path &p) const; |
201 | |
202 | /** |
203 | * Returns \p true if this Path is not equal to \p p; otherwise returns \p false; |
204 | */ |
205 | bool operator!=(const Path &p) const; |
206 | |
207 | /** |
208 | * Returns the source MediaNode used by the path. |
209 | */ |
210 | MediaNode *source() const; |
211 | |
212 | /** |
213 | * Returns the sink MediaNode used by the path. |
214 | */ |
215 | MediaNode *sink() const; |
216 | |
217 | |
218 | protected: |
219 | friend class PathPrivate; |
220 | QExplicitlySharedDataPointer<PathPrivate> d; |
221 | }; |
222 | |
223 | /** |
224 | * \relates Path |
225 | * Creates a new Path connecting two MediaNodes. |
226 | * |
227 | * The implementation will automatically select the right format and media type. E.g. connecting a |
228 | * MediaObject and AudioOutput will create a Path object connecting the audio. This might be |
229 | * represented as PCM or perhaps even AC3 depending on the AudioOutput object. |
230 | * |
231 | * \param source The MediaNode to connect an output from |
232 | * \param sink The MediaNode to connect to. |
233 | */ |
234 | PHONON_EXPORT Path createPath(MediaNode *source, MediaNode *sink); |
235 | |
236 | } // namespace Phonon |
237 | |
238 | |
239 | #endif // PHONON_PATH_H |
240 | |