Update copyright headers
[qt:qt.git] / doc / src / classes / phonon-api.qdoc
1 /*
2     This file is part of the KDE project
3     Copyright (C) 2005-2007 Matthias Kretz <kretz@kde.org>
4     Copyright (C) 2015 The Qt Company Ltd.
5     Contact: http://www.qt.io/licensing/
6
7     This library is free software; you can redistribute it and/or
8     modify it under the terms of the GNU Library General Public
9     License version 2 as published by the Free Software Foundation.
10
11     This library is distributed in the hope that it will be useful,
12     but WITHOUT ANY WARRANTY; without even the implied warranty of
13     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
14     Library General Public License for more details.
15
16     You should have received a copy of the GNU Library General Public License
17     along with this library; see the file COPYING.LIB.  If not, write to
18     the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
19     Boston, MA 02110-1301, USA.
20 */
21
22
23 /*!
24     \enum Phonon::DiscType
25     Enum to identify the media discs supported by MediaObject.
26
27     \value NoDisc
28     No disc was selected. This is only useful as a return value from
29     MediaSource::diskType().
30     \value Cd Identifies Audio CDs.
31     \value Dvd Identifies DVDs (not arbitrary data DVDs, only movie DVDs).
32     \value Vcd Identifies Video CDs.
33
34     \sa MediaSource, MediaObject
35 */
36
37 /*!
38     \enum Phonon::MetaData
39
40     Provided as keys for Phonon::MediaObject::metaData(). The enum
41     values matches strings defined in the Ogg Vorbis specification
42
43     \value ArtistMetaData
44     \value AlbumMetaData
45     \value TitleMetaData
46     \value DateMetaData
47     \value GenreMetaData
48     \value TracknumberMetaData
49     \value DescriptionMetaData
50     \value MusicBrainzDiscIdMetaData
51 */
52
53 /*!
54     \enum Phonon::State
55     \since 4.4
56
57     The state enum describes the different states a media object can
58     take. Several functions of \l{Phonon::}{MediaObject} are
59     asynchronous, so even if a you have requested a state change
60     through a function call, e.g., through
61     \l{Phonon::MediaObject::}{play()}, you cannot be sure that the
62     change has taken place before you receive the
63     \l{Phonon::MediaObject::}{stateChanged()} signal.
64
65     A media object can at any time change into any state, regardless
66     of the state it previously had. \omit In the
67     \l{Phonon::}{MediaObject} class description explains the typical
68     state changes in the life of a media object. \endomit
69
70     \value LoadingState
71     After construction it might take a while before the media object
72     is ready to \l{Phonon::MediaObject::}{play()}. This state is
73     commonly used by backends to initialize the \l{Phonon
74     Overview}{media graph} and loading the source. When
75     the object leaves the loading state, it will enter the
76     StoppedState unless an error occurred or another state is
77     requested through a function call, e.g.,
78     \l{Phonon::}{MediaObject::play()}.
79
80     \value StoppedState
81     In the stopped state, the media object is ready to play its
82     current media source. The current
83     \l{MediaObject::seek()}{position} in the media stream is then 0.
84
85     \value PlayingState
86     The media object is playing back its media source.
87
88     \value BufferingState
89     The Player is waiting for data to be able to start or continue
90     playing. This state is commonly used to wait for media data over a
91     network connection.
92
93     \value PausedState
94     The media player has currently paused its playback, i.e., it
95     stops playing but keeps the current playback position in the
96     stream.
97
98     \value ErrorState
99     When a media object enters the error state a problem with the
100     playback has occurred. The possible errors are grouped into
101     two categories by Phonon::ErrorType, and the type can be
102     queried through \l{Phonon::MediaObject::}{errorType()}. A
103     \l{Phonon::}{FatalError} implies that the playback
104     cannot continue, but one can still try with a new media
105     source. With a \l{Phonon::}{NormalError} it might
106     be possible to continue playback, and a media object may
107     therefore change state from the ErrorState.
108
109     \sa MediaObject
110 */
111
112 /*!
113     \enum Phonon::Category
114
115     Sets the category your program should be listed in in the mixer.
116
117     \value NoCategory
118     Will make use of the default device.
119     \value NotificationCategory
120     If the sounds produced are notifications (ping, beep and such) you
121     should use this category.
122     \value MusicCategory
123     If your application is a music player (like a jukebox or media player
124     playing an audio file).
125     \value VideoCategory
126     If the sound is the audio channel of a video.
127     \value CommunicationCategory
128     If your applications produces sounds from communication with somebody
129     else (VoIP, voice chat).
130     \value GameCategory
131     Sound produced by a computer game should go into this category.
132     \value AccessibilityCategory
133     Sounds produced for accessibility (e.g., Text-To-Speech)
134     \omitvalue LastCategory
135     Holds the largest value of categories.
136     \omitvalue AccessibilityCategory
137
138     A Jukebox will set this to Music, a VoIP program to Communication, a
139     DVD player to video, and so on.
140
141     \note These categories can also become useful for an application that
142     controls the volumes automatically, like turning down the music when a call
143     comes in, or turning down the notifications when the media player knows
144     it's playing classical music.
145 */
146
147 /*!
148     \enum Phonon::ErrorType
149
150     This enum describes the severity when an error has occurred during
151     playback.
152
153     After a media object has entered the \l{Phonon::}{ErrorState}, one
154     can query the type of error from
155     \l{Phonon::}{MediaObject::errorType()}. Note that you should query
156     the error when receiving the
157     \l{Phonon::}{MediaObject::stateChanged()} signal, because the
158     error type will be lost if the media object leaves the error
159     state.    
160
161     \value NoError No error. MediaObject::errorType() returns this if
162     MediaObject::state() != Phonon::ErrorState.
163
164     \value NormalError An error has occurred with the playback of the current
165     source. It might be possible to continue playback, for instance, if only the
166     audio stream in a video cannot be played back. The media object will then
167     leave the error state again.
168
169     \value FatalError. Something important does not work. Your program cannot continue
170     the playback of the current source, but it might be possible to try another.
171
172     \sa MediaObject::errorType()
173 */
174
175 /*!
176     \fn QString Phonon::categoryToString(Category c)
177
178     Returns a (translated) string to show to the user identifying the given
179     Category (\a c).
180 */
181
182 /*!
183     \enum Phonon::ObjectDescriptionType
184     \relates Phonon::ObjectDescription
185
186     This enum defines the type of information that is contained in a
187     \l{Phonon::}{ObjectDescription} object.
188
189     \value AudioOutputDeviceType An audio output device (\l{Phonon::}{AudioOutputDevice}).
190     This can be soundcards (with different drivers),
191     sound servers, or other virtual outputs like playback on a different
192     computer on the network.
193
194     \value EffectType An audio effect (\l{Phonon::}{EffectDescription}).
195     \omitvalue SubtitleType
196     \omitvalue AudioCaptureDeviceType
197     \omitvalue AudioChannelType
198 */
199
200 /*!
201     \typedef Phonon::AudioOutputDevice
202     \relates Phonon::ObjectDescription
203
204     This typedef of \l{Phonon::}{ObjectDescription} describes an audio output
205     device, such as soundcards (with different drivers), sound servers, or other
206     virtual outputs like playback on a different computer on the network.
207
208     \omit
209     For Hardware devices the backend should use libkaudiodevicelist
210     (AudioDevice and AudioDeviceEnumerator) which will list removable
211     devices even when they are unplugged and provide a unique identifier
212     that can make backends use the same identifiers.
213     \endomit
214
215     A list of available devices is given by the backend with
216     Backendcapabilities::availableAudioOutputDevices()
217
218     \snippet doc/src/snippets/phononobjectdescription.cpp 1
219
220 */
221
222 /*!
223     \fn Phonon::phononVersion()
224     \inmodule Phonon
225     \since 4.5
226
227     Returns the Phonon version.
228 */
229
230 /*!
231     \class Phonon::ObjectDescription
232     \inmodule Phonon
233     \inheaderfile Phonon/ObjectDescription
234     \since 4.4
235     \brief The ObjectDescription class provides information about Phonon objects.
236
237     Phonon currently uses this class to describe audio effects and
238     audio output devices - using the typedefs AudioOutputDevice and
239     EffectDescription. The type of an ObjectDescription is also
240     described through the \l{Phonon::}{ObjectDescriptionType} enum.
241     Objects of the same \l{Phonon::ObjectDescriptionType}{type} are
242     uniquely identified by an index().
243
244     The class gives a description() and a name() of the object, both
245     of which are strings appropriate for end users of a Phonon
246     application. You can also check whether the device or effect
247     described is \l{isValid()}{valid}. This does not guarantee that
248     the device or effect functions as expected, but that the
249     ObjectDescription describes an existing device or effect.
250
251     Audio output devices and effect descriptions are used to select
252     the audio output device to be used for playback and to create
253     effects; we show examples of this in the snippet below. The
254     available descriptions can be fetched with
255     \l{Phonon::BackendCapabilities::}{availableAudioOutputDevices()}
256     and \l{Phonon::BackendCapabilities::}{availableAudioEffects()}
257     static functions in the Phonon::BackendCapabilities namespace
258
259     \snippet doc/src/snippets/phononobjectdescription.cpp 0
260
261     Other types of ObjectDescriptions might be possible in the future,
262     e.g., descriptions of audio capture devices, such as microphones.
263
264     \omit Not implemented yet.
265     Need a new paragraph on that some descriptions 'belong
266     together', such as chained audio effects.
267
268     Some parts give the end user choices, e.g. what source to capture
269     audio from. These choices are described by the name and
270     description methods of this class and identified with the id
271     method. Subclasses then define additional information like which
272     audio and video choices belong together.  \endomit
273
274     \sa Phonon::AudioOutputDevice, Phonon::EffectDescription, {Capabilities Example}, {Phonon Module}
275 */
276
277 /*!
278     \fn Phonon::ObjectDescription::ObjectDescription()
279     \brief constructs a new object description.
280     \internal
281 */
282
283 /*!
284     \fn Phonon::ObjectDescription::ObjectDescription (int index, const QHash<QByteArray, QVariant> & properties)
285     \internal
286 */
287
288 /*!
289     \fn Phonon::ObjectDescription::ObjectDescription(const QExplicitlySharedDataPointer<ObjectDescriptionData> &dd)
290     \internal
291 */
292
293 /*!
294     \fn static inline ObjectDescription<T> Phonon::ObjectDescription::fromIndex(int index)
295     \internal
296
297     \omit Currently indices are not unique for all ObjectDescription types, making
298     the behavior of this function undefined. \endomit
299
300     Returns a new description object that describes the
301     device/effect/codec/...  with the given \a index.
302 */
303
304 /*!
305     \fn inline bool Phonon::ObjectDescription::operator==(const ObjectDescription &otherDescription) const
306
307     Returns \c true if this ObjectDescription describes the same
308     object as \a otherDescription; otherwise, returns \c false.
309 */
310
311 /*!
312     \fn inline bool Phonon::ObjectDescription::operator!=(const ObjectDescription &otherDescription) const
313     Returns \c false if this ObjectDescription describes the same
314     as \a otherDescription; otherwise, returns \c true.
315 */
316
317 /*!
318     \fn inline QString Phonon::ObjectDescription::name() const
319
320     Returns a string appropriate for a user to select between
321     object descriptions, e.g., from a QComboBox.
322
323     \sa description()
324 */
325
326 /*!
327     \fn inline QString Phonon::ObjectDescription::description() const
328
329     Returns a more extensive description than the name() function.
330
331     For example, in the case of \l{Phonon::}{AudioOutputDevice}s, this
332     text should make clear which sound source is described; this is
333     sometimes hard to describe or understand from just the name.
334
335     The text is appropriate to present to an end user in for example
336     tool tips of items, with the name()'s as text, in a QComboBox.
337
338 */
339
340 /*!
341     \fn inline QVariant Phonon::ObjectDescription::property(const char *name) const
342
343     Returns the property named \a name. A property can be used for
344     extended information, such as the manufacturer of a sound card. The
345     information will usually be given as text.
346
347     If the property is not set an invalid QVariant is returned.
348
349     Qt's backends do not use properties at the time of this writing.
350
351     \sa propertyNames()
352 */
353
354 /*!
355     \fn inline QList<QByteArray> Phonon::ObjectDescription::propertyNames() const
356
357     Properties can be used for extended information about a
358     ObjectDescription, e.g., a manufacturer of a sound card. The
359     information will usually be given text.
360
361     This function returns all names that return valid data when
362     property() is called.
363
364     Currently, Qt backends do not use properties for their object
365     descriptions.
366
367     \sa property()
368 */
369
370 /*!
371     \fn inline bool Phonon::ObjectDescription::isValid() const
372
373     Returns true if the device or effect described exists.
374
375     An ObjectDescription that is invalid, will also have an
376     index() of -1.
377
378     \sa index()
379 */
380
381 /*!
382     \fn inline int Phonon::ObjectDescription::index() const
383
384     Returns a unique identifier for this ObjectDescription. Used
385     internally to distinguish between the descriptions.
386
387     Notice that the identifiers are only unique to the type of
388     description, e.g., \l{Phonon::}{AudioOutputDevice} or
389     \l{Phonon::}{EffectDescription}.
390 */
391
392 /*!
393     \class Phonon::ObjectDescriptionPrivate
394     \inmodule Phonon
395     \since 4.4
396     \internal
397
398 */
399
400 /*!
401     \class Phonon::StreamInterface
402     \inmodule Phonon
403     \since 4.4
404     \brief Backend interface to handle media streams (AbstractMediaStream).
405     \internal
406 */
407
408 /*!
409     \fn virtual Phonon::StreamInterface::~StreamInterface()
410 */
411
412 /*!
413     \fn virtual void Phonon::StreamInterface::writeData(const QByteArray &data) = 0
414     \internal
415 */
416
417 /*!
418     \fn virtual void Phonon::StreamInterface::endOfData() = 0
419     \internal
420 */
421
422 /*!
423     \fn virtual void Phonon::StreamInterface::setStreamSize(qint64 newSize) = 0
424     \internal
425 */
426
427 /*!
428     \fn virtual void Phonon::StreamInterface::setStreamSeekable(bool s) = 0
429     \internal
430 */
431
432 /*!
433     \fn void Phonon::StreamInterface::connectToSource(const MediaSource &mediaSource)
434     \internal
435 */
436
437 /*!
438     \fn void Phonon::StreamInterface::needData()
439     \internal
440 */
441
442 /*!
443     \fn void Phonon::StreamInterface::enoughData()
444     \internal
445 */
446
447 /*!
448     \fn void Phonon::StreamInterface::seekStream(qint64)
449     \internal
450 */
451
452 /*!
453     \fn void Phonon::StreamInterface::reset()
454     \internal
455 */
456
457 /*!
458     \fn Phonon::StreamInterface::StreamInterface()
459     \internal
460     \omit
461     For subclasses.
462     \endomit
463 */
464
465 /*!
466     \class StreamInterfacePrivate
467     \inmodule Phonon
468     \internal
469 */
470
471 /*!
472     \class Phonon::AbstractVideoOutput
473     \inmodule Phonon
474     \internal
475     \since 4.4
476     \brief The AbstractVideoOutput class is the common base class for all video output classes.
477
478     \sa VideoWidget
479 */
480
481 /*!
482     \namespace Phonon::Experimental
483     \internal
484 */
485
486 /*!
487     \fn Phonon::AbstractVideoOutput::AbstractVideoOutput(AbstractVideoOutputPrivate &d)
488     \internal
489
490     Constructor that is called from derived classes.
491
492     \param parent Standard QObject parent.
493 */
494
495 /*!
496     \class Phonon::AbstractVideoOutputPrivate
497     \inmodule Phonon
498     \internal
499     \since 4.4
500 */
501
502 /*!
503     \class Phonon::VolumeFaderEffect
504     \inmodule Phonon
505     \internal
506     \since 4.4
507
508     This effect differs from gradually changing the output volume in that
509     a dedicated effect can change the volume in the smallest possible
510     steps while every other volume control will make more or less
511     noticeable steps.
512
513     \sa AudioOutput::volume()
514 */
515
516 /*!
517     \property Phonon::VolumeFaderEffect::volume
518
519     This is the current volume of the output as voltage factor.
520     Setting this property changes the volume immediately.
521
522     1.0 means 100%, 0.5 means 50% voltage/25% power, 0.0 means 0%
523
524     \sa volumeDecibel
525 */
526
527 /*!
528     \property Phonon::VolumeFaderEffect::volumeDecibel
529
530     This is the current volume of the output in decibel.
531     Setting this property changes the volume immediately.
532
533     0 dB means no change in volume, -6dB means an attenuation of the
534     voltage to 50% and an attenuation of the power to 25%, -inf dB means
535     silence.
536
537     \sa volume
538 */
539
540 /*!
541     \property Phonon::VolumeFaderEffect::fadeCurve
542
543     This property holds the fade curve to be used for the fadeIn(), fadeOut()
544     and fadeTo() slots.
545
546     Defaults to Fade3Decibel.
547
548     \sa FadeCurve
549 */
550
551 /*!
552     \enum Phonon::VolumeFaderEffect::FadeCurve
553     Determines the curve of the volume change.
554
555     \value Fade3Decibel Crossfade curve/fast fade out.
556     This is the default fade curve.
557     \value Fade6Decibel Linear fade out.
558     \value Fade9Decibel Slow fade out.
559     \value Fade12Decibel A more extreme version of the -9dB fade.
560
561     \bold{Notes:}
562
563     \c Fade3Decibel is often the best fade for a crossfade, as after half
564     of the time the volume reached -3dB. This means that half the
565     possible power (which is proportional to the square of the
566     voltage) is reached. Summed, the maximum power of two audio
567     signals fading with a -3dB curve will always be equal.
568
569     For fading in or out the -3dB curve is too abrupt in the end.
570
571     With a -6dB fade curve, a volume of -6dB is reached after half of
572     the fading time. -6dB is equal to half of the voltage meaning
573     that the voltage multiplier changes linearly from the start
574     of the fade to the end.
575
576     With the \c Fade9Decibel fade, a volume of -9dB is reached after
577     half of the fade time, so the fade is fast in the beginning and
578     slow at the end. This is a good fade for ending music.
579 */
580
581 /*!
582     \fn void Phonon::VolumeFaderEffect::fadeIn(int fadeTime)
583
584     Tells the Fader to change the volume from the current volume to 100%
585     in \a fadeTime milliseconds.
586
587     Short for \c fadeTo(1.0, fadeTime).
588
589     \param fadeTime the fade duration in milliseconds
590
591     \sa fadeTo(), volume
592 */
593
594 /*!
595     \fn void Phonon::VolumeFaderEffect::fadeOut(int fadeTime)
596
597     Tells the Fader to change the volume from the current volume to 0%
598     in \a fadeTime milliseconds.
599     Short for \c fadeTo(0.0, fadeTime).
600
601     \param fadeTime the fade duration in milliseconds
602
603     \sa fadeTo
604 */
605
606 /*!
607     \fn void Phonon::VolumeFaderEffect::fadeTo(float volume, int fadeTime)
608
609     Tells the Fader to change the volume from the current value to
610     \a volume in \a fadeTime milliseconds.
611
612     \sa fadeIn(), fadeOut()
613 */
614
615 /*!
616     \class Phonon::VolumeFaderEffectPrivate
617     \inmodule Phonon
618     \since 4.4
619     \internal
620 */
621
622 /*!
623     \class Phonon::VolumeFaderInterface
624     \inmodule Phonon
625     \since 4.4
626     \internal
627 */
628
629 /*!
630     \fn virtual Phonon::VolumeFaderInterface::~VolumeFaderInterface()
631     \internal
632 */
633
634 /*!
635     \fn virtual float Phonon::VolumeFaderInterface::volume() const
636     \internal
637 */
638
639 /*!
640     \fn virtual void Phonon::VolumeFaderInterface::setVolume(float)
641     \internal
642 */
643
644 /*!
645     \fn virtual Phonon::VolumeFaderEffect::FadeCurve Phonon::VolumeFaderInterface::fadeCurve() const
646     \internal
647 */
648
649 /*!
650     \fn virtual void Phonon::VolumeFaderInterface::setFadeCurve(Phonon::VolumeFaderEffect::FadeCurve)
651     \internal
652 */
653
654 /*!
655     \fn virtual void Phonon::VolumeFaderInterface::fadeTo(float, int)
656     \internal
657 */
658
659 /*!
660     \class Phonon::AbstractMediaStream
661     \inmodule Phonon
662     \internal
663     \since 4.4
664     \brief The AbstractMediaStream class is the base class for custom media data streams.
665     \inheaderfile Phonon/AbstractMediaStream
666
667     This class is subclassed to provide custom data streams for
668     \l{Phonon::}{MediaSource}s.
669
670     The \l{Phonon::}{MediaSource} knows how to handle the most common
671     media sources, such as files and CD. If you need to fetch
672     multimedia from other sources, you can reimplement this class,
673     which can be used by a \l{Phonon::}{MediaSource}.
674
675     When a backend needs more data from the stream, needData() will be
676     called. You must then use writeData() to write the data to the
677     backend. You can either write one time and wait for a new
678     needData() call, or continue to write data until you receive an
679     enoughData() call. When the stream is at its end, call endOfData()
680     instead of writeData().
681
682     Before the custom stream is passed to a \l{Phonon::}{MediaSource},
683     setStreamSize() needs to be called, and also setStreamSeekable()
684     (if the stream is seekable). A good place to do this work is in
685     the constructor. A seekable stream must also reimplement
686     seekStream().
687
688     We show two examples. The first writes data repeatedly until it
689     receives the enoughData() call, while the second only writes once
690     and waits for a new needData() call.
691
692     Example where data is written repeatedly.
693
694     \snippet doc/src/snippets/code/doc_src_phonon-api.cpp 0
695
696     Example where data is written once:
697
698     \snippet doc/src/snippets/code/doc_src_phonon-api.cpp 1
699
700     \sa Phonon::MediaSource, Phonon::MediaObject 
701
702 */
703
704 /*!
705     \fn Phonon::AbstractMediaStream::AbstractMediaStream(QObject *parent = 0)
706     \internal
707
708     Constructs an AbstractMediaStream object with the given \a parent.
709
710 */
711
712 /*!
713     \fn qint64 Phonon::AbstractMediaStream::streamSize() const
714
715     Returns the stream size that was set with setStreamSize().
716
717     A negative value means that the length of the stream cannot be known.
718
719     Defaults to 0.
720
721     \sa setStreamSize()
722 */
723
724 /*!
725     \fn void Phonon::AbstractMediaStream::setStreamSize(qint64 size)
726
727     Sets the \a size of the stream in number of bytes.
728
729     A negative value means that the length of the stream cannot be known.
730
731     Defaults to 0.
732
733     This function has to be called. A backend will not call needData()
734     until the stream size is set.
735
736     \sa streamSize()
737
738 */
739
740 /*!
741     \fn bool Phonon::AbstractMediaStream::streamSeekable() const
742
743     Returns whether your data stream is set as seekable.
744
745     Defaults to \c false.
746
747     \sa setStreamSeekable()
748
749 */
750
751 /*!
752     \fn void Phonon::AbstractMediaStream::setStreamSeekable(bool s)
753
754     Sets whether your data stream is seekable. \a s should be true if
755     the stream is seekable; otherwise false.
756
757     Defaults to \c false.
758
759     If you set this to \c true you have to implement the seekStream()
760     function.
761
762     \sa streamSeekable()
763 */
764
765 /*!
766     \fn void Phonon::AbstractMediaStream::writeData(const QByteArray &data)
767
768     Sends the media \a data to the backend for decoding.
769
770     Use this function to send data to the backend after needData() has
771     been called.
772
773     If your stream is a push stream, data should be written until the
774     enoughData() function is called. For a pull stream, write data
775     once before the call to needData() function returns.
776
777     If the data is depleted, call endOfData() instead of writeData().
778
779     \warning Don't call this function before the first needData() is emitted.
780
781     \sa needData(), endOfData()
782
783 */
784
785 /*!
786     \fn void Phonon::AbstractMediaStream::endOfData()
787
788     Tells the backend that the media data stream is at its end.
789
790     \warning Don't call this function before the first needData() is emitted.
791
792     \sa writeData(), needData()
793 */
794
795 /*!
796     \fn void Phonon::AbstractMediaStream::error(Phonon::ErrorType errorType, const QString &errorString)
797
798     If an I/O error occurs you should call this function to make
799     MediaObject go into ErrorState. \c errorType classifies the error,
800     while \a errorString is a textual description of the error suitable
801     for users of Phonon applications.
802
803     \sa MediaObject::errorType(), MediaObject::errorString()
804 */
805
806 /*!
807     \fn virtual void Phonon::AbstractMediaStream::reset() = 0
808
809     Reimplement this function to reset the stream. Subsequent calls to writeData should start
810     from the first position of the data unless a seek is requested.
811
812     The function is necessary for the case where a non-seekable MediaStream is
813     played more than once. For a seekable stream the implementation can simply call
814     \snippet doc/src/snippets/code/doc_src_phonon-api.cpp 2
815
816     \sa writeData(), needData()
817 */
818
819 /*!
820     \fn virtual void Phonon::AbstractMediaStream::needData() = 0
821
822     Reimplement this function to be notified when the backend needs data.
823
824     When this function is called you should write data to the backend
825     (See writeData()).
826
827     \sa writeData(), endOfData(), enoughData()
828 */
829
830 /*!
831     \fn virtual void Phonon::AbstractMediaStream::enoughData()
832
833     If your stream is a push stream, reimplement this function to be
834     notified when the backend has enough data and your stream object
835     may take a break.
836
837     This method is important for pushing data to the backend in order
838     to not fill the backend buffer unnecessarily.
839
840     \sa needData()
841 */
842
843 /*!
844     \fn virtual void Phonon::AbstractMediaStream::seekStream(qint64 offset)
845
846     Reimplement this function if your stream is seekable.
847
848     When this function is called the next call to writeData has to be at the
849     requested \a offset.
850
851     \warning Do not call the parent implementation.
852
853     \sa setStreamSeekable(), streamSeekable(), needData()
854 */
855
856 /*!
857     \class Phonon::BackendInterface
858     \inmodule Phonon
859     \since 4.4
860     \brief Main Backend class interface
861     \internal
862
863     This interface defines the main factory of the backend. The createObject() function creates all the
864     objects needed by the frontend.
865
866     The objectDescriptionIndexes and objectDescriptionProperties functions return information about
867     available devices, effects and codecs.
868
869     An implementation could look like this:
870     \snippet snippets/phonon/samplebackend/main.cpp snippet
871
872 */
873
874 /*!
875     \fn virtual Phonon::BackendInterface::~BackendInterface()
876     \internal
877
878     Silence gcc's warning.
879 */
880
881 /*!
882     \enum Phonon::BackendInterface::Class
883     \internal
884
885     Classes that the createObject() function has to handle.
886
887     \value MediaObjectClass Request to return a \c MediaObject object.
888     \value VolumeFaderEffectClass Request to return a \c VolumeFaderEffect
889     object.
890     \value AudioOutputClass Request to return an \c AudioOutput object.
891     \value AudioDataOutputClass Request to return an \c AudioDataOutput object.
892     \value VisualizationClass Request to return a \c Visualization object.
893     \value VideoDataOutputClass Request to return a \c VideoDataOutput object.
894     \value EffectClass Request to return a \c Effect object.
895     Takes an additional int that specifies the effect ID.
896     \value VideoWidgetClass Request to return a \c VideoWidget object.
897 */
898
899 /*!
900     \fn virtual QObject *Phonon::BackendInterface::createObject(Class c, QObject *parent, const QList<QVariant> &args = QList<QVariant>()) = 0
901     \internal
902
903     Returns a new instance of the requested class.
904
905     \param c The requested class.
906     \param parent The parent object.
907     \param args Additional arguments (documented in Class).
908 */
909
910
911 /*!
912     \fn virtual QList<int> Phonon::BackendInterface::objectDescriptionIndexes(ObjectDescriptionType type) const = 0
913     \internal
914
915     Returns the unique identifiers for the devices/effects/codecs of the given \a type.
916
917     \param type see ObjectDescriptionType
918 */
919
920 /*!
921     \fn virtual QHash<QByteArray, QVariant> Phonon::BackendInterface::objectDescriptionProperties(ObjectDescriptionType type, int index) const = 0
922     \internal
923
924     Given a unique identifier that was returned from objectDescriptionIndexes this function
925     returns a hash mapping property names to values.
926
927     The property "name" must always be present. All other properties are optional.
928
929     \table
930     \header \o Property \o Description
931     \row \o name \o The name of the device/effect/codec/...
932     \row \o description \o A text explaining what this device/effect/codec/... is/can do
933     \row \o icon \o An icon name (using the freedesktop naming scheme) or a QIcon for this
934     device/effect/codec/...
935     \row \o available \o A bool telling whether the device is present or unplugged.
936     \endtable
937
938     \param type see ObjectDescriptionType
939     \param index The unique identifier that is returned from objectDescriptionIndexes
940 */
941
942 /*!
943     \fn virtual bool Phonon::BackendInterface::startConnectionChange(QSet<QObject *>) = 0;
944     \internal
945
946     When this function is called the nodes given in the parameter list should
947     not lose any signal data when connections are changed.
948 */
949
950 /*!
951     \fn virtual bool Phonon::BackendInterface::connectNodes(QObject *, QObject *) = 0
952     \internal
953
954     Defines a signal connection between the two given nodes.
955 */
956
957 /*!
958     \fn virtual bool Phonon::BackendInterface::disconnectNodes(QObject *, QObject *) = 0
959     \internal
960
961     Cuts a signal connection between the two given nodes.
962 */
963
964 /*!
965     \fn virtual bool Phonon::BackendInterface::endConnectionChange(QSet<QObject *>) = 0
966     \internal
967
968     When this function is called the nodes given in the parameter list may lose
969     signal data when a port is not connected.
970 */
971
972 /*!
973     \fn virtual QStringList Phonon::BackendInterface::availableMimeTypes() const = 0
974     \internal
975
976     Returns all available MIME types.
977 */
978
979 /*!
980     \class Phonon::MediaSource
981     \inmodule Phonon
982     \inheaderfile Phonon/MediaSource
983     \since 4.4
984     \brief The MediaSource class provides multimedia data for media objects.
985
986     The MediaSource class manages a source of multimedia content, such
987     as a music or video file, of which data is given to a
988     \l{Phonon::}{MediaObject}.
989
990     The media source knows how fetch its data from several sources,
991     e.g., from files, a QIODevice, or a CD. The possible source types
992     are described by the \l{MediaSource::}{Type} enum. The type of the
993     source is set by the media source itself, and is dependent on the
994     constructor used to create it. Note that it is possible to provide
995     data from any source by implementing a QIODevice.
996
997     The class has several functions to acquire information about the
998     source it manages, e.g., fileName() and url(). The return from
999     these functions are dependent on the type() of the media source.
1000
1001     Normally, a programmer does not need to be concerned with media
1002     sources. It's constructors are implicit, so one can, for instance,
1003     send an URL or filename directly to the constructors of the
1004     \l{Phonon::}{MediaObject}.
1005
1006     \snippet doc/src/snippets/code/doc_src_phonon-api.cpp 3
1007
1008     A MediaSource object cannot be reused for another multimedia
1009     source. It is possible to play the same source again, and also
1010     stop and start a non-seekable media source, such as a radio
1011     stream, with the same MediaSource object.
1012
1013     \section1 Qt Backends
1014
1015     Currently, Qt's backends support files in local and remote
1016     locations. Support for other sources, such as CD/DVD, are planned
1017     for the future.
1018
1019     \sa MediaObject, {Phonon Module}
1020 */
1021
1022 /*!
1023     \enum Phonon::MediaSource::Type
1024
1025     Identifies the type of media described by the MediaSource object.
1026
1027     \value Invalid The MediaSource object does not describe any valid source.
1028     \value LocalFile The MediaSource object describes a local file.
1029     \value Url The MediaSource object describes an URL, which can be either a
1030     local file or a file on the network.
1031     \value Disc The MediaSource object describes a disc, e.g., a CD.
1032     \value Stream The MediaSource object describes a data stream.
1033                   This is the type used for \l{QIODevice}s. Note
1034                   that a stream opened with a QUrl, will still be of the Url type.
1035     \value Empty The media source doesn't have a source.
1036
1037     \sa MediaSource::type()
1038 */
1039
1040 /*!
1041     \fn Phonon::MediaSource::MediaSource()
1042     \internal
1043
1044     Creates an invalid MediaSource object.
1045
1046     \sa Invalid
1047 */
1048
1049 /*!
1050     \fn Phonon::MediaSource::MediaSource(const QString &fileName)
1051
1052     Creates a MediaSource object for the file specified by \a
1053     fileName.  You can also use this constructor with \l{The Qt
1054     Resource System}{Qt resources}
1055
1056     \omit
1057     \param fileName file name of a local media file or a Qt resource that was compiled in.
1058     \endomit
1059 */
1060
1061 /*!
1062     \fn Phonon::MediaSource::MediaSource(const QUrl &url)
1063
1064     Creates a MediaSource object for a the URL specified by \a url.
1065     
1066     If the multimedia content you would like to play back is on a
1067     remote network location, you should use this constructor; though,
1068     it also possible to specify an URL to a local file.
1069
1070     \sa QUrl
1071 */
1072
1073
1074 /*!
1075     \fn Phonon::MediaSource::MediaSource(Phonon::DiscType discType, const QString &deviceName = QString())
1076
1077     Creates a MediaSource object for the type of disc specified by \a discType in the named
1078     device referred to by \a deviceName.
1079
1080     \note \a deviceName is a platform dependent device name. It can be useful to specify this
1081     if the computer has more than one CD drive. On KDE, it is recommended to use the Solid
1082     hardware discovery framework to retrieve the device name in a portable way.
1083 */
1084
1085 /*!
1086     \fn Phonon::MediaSource::MediaSource(AbstractMediaStream *stream)
1087     \internal
1088     Creates a MediaSource object for a data stream.
1089
1090     Your application can provide the media data by subclassing AbstractMediaStream and
1091     passing a pointer to that object. Phonon will never delete the \a stream.
1092
1093     \param stream The AbstractMediaStream subclass to provide the media data.
1094
1095     \sa setAutoDelete
1096 */
1097
1098 /*!
1099     \fn Phonon::MediaSource::MediaSource(QIODevice *ioDevice)
1100
1101     Creates a MediaSource object for the QIODevice specified by \a ioDevice.
1102
1103     This constructor can be very handy in the combination of
1104     QByteArray and QBuffer.
1105
1106     If you need to fetch multimedia data from a source that is not
1107     supported by MediaSource, you should subclass QIODevice and use
1108     this MediaSource constructor. It is important that you reimplement
1109     QIODevice::isSequential(), as it is used by MediaSource to
1110     determine if the media source is seekable.
1111
1112     \a ioDevice is an arbitrary readable QIODevice subclass. If the device is not opened
1113     MediaSource will open it as QIODevice::ReadOnly.
1114
1115     \note Sequential devices can also be used, but MediaObject::isSeekable() will
1116     return false as a result.
1117
1118     \warning On Windows, we only support \l{QIODevice}s containing the
1119     \c avi, \c mp3, or \c mpg formats. Use the constructor that takes
1120     a file name to open files (the Qt backend does not use a QFile
1121     internally).
1122
1123     \sa setAutoDelete()
1124 */
1125
1126 /*!
1127     \fn Phonon::MediaSource::MediaSource(MediaSourcePrivate &)
1128     \internal
1129 */
1130
1131 /*!
1132     \fn Phonon::MediaSource::~MediaSource()
1133
1134     Destroys the MediaSource object. You should never delete a
1135     MediaSource yourself, the MediaObject will handle this.
1136
1137 */
1138
1139 /*!
1140     \fn Phonon::MediaSource::MediaSource(const MediaSource &other)
1141
1142     Constructs a copy of the \a other media source.
1143
1144     This constructor is fast thanks to explicit sharing.
1145 */
1146
1147 /*!
1148     \fn MediaSource &Phonon::MediaSource::operator=(const MediaSource &other)
1149
1150     Assigns the \a other media source to this media source and returns a
1151     reference to it.
1152
1153     This operation is fast thanks to explicit sharing.
1154 */
1155
1156 /*!
1157     \fn bool Phonon::MediaSource::operator==(const MediaSource &other) const
1158
1159     Returns true if this media source is equal to the \a other media source;
1160     otherwise returns false.
1161 */
1162
1163 /*!
1164     \fn void Phonon::MediaSource::setAutoDelete(bool enable)
1165
1166     If \a enable is true, the media source will take ownership of the
1167     object passed in the \l{Phonon::}{MediaSource}'s constructor
1168     object that was passed in the constructor; otherwise, the
1169     programmer is responsible for deletion of this object.
1170
1171     This setting is false by default. If you enable it, you should
1172     only access the stream or device as long as you keep the media
1173     source object around. As long as you keep the media source
1174     wrapping the stream or device, the object will not get deleted.
1175
1176     \sa autoDelete()
1177 */
1178
1179 /*!
1180     \fn bool Phonon::MediaSource::autoDelete() const
1181
1182     Returns the setting of the auto-delete option. The default is
1183     false.
1184
1185     \sa setAutoDelete()
1186 */
1187
1188 /*!
1189     \fn Type Phonon::MediaSource::type() const
1190
1191     Returns the type of the MediaSource (depends on the constructor
1192     that was used).
1193
1194     \sa Type
1195 */
1196
1197 /*!
1198     \fn QString Phonon::MediaSource::fileName() const
1199
1200     Returns the file name of the MediaSource if type() ==
1201     LocalFile; otherwise, returns QString().
1202
1203     \sa type()
1204 */
1205
1206 /*!
1207     \fn QUrl Phonon::MediaSource::url() const
1208     Returns the URL of the MediaSource if type() == URL or type() == LocalFile;
1209     otherwise returns QUrl().
1210
1211     \sa type()
1212 */
1213
1214 /*!
1215     \fn Phonon::DiscType Phonon::MediaSource::discType() const
1216     Returns the disc type of the MediaSource if type() == Disc; otherwise
1217     returns NoDisc.
1218
1219     \sa type()
1220 */
1221
1222 /*!
1223     \fn QString Phonon::MediaSource::deviceName() const
1224
1225     Returns the device name of the MediaSource if type() == Disc; otherwise
1226     returns QString().
1227
1228     \sa type()
1229 */
1230
1231 /*!
1232     \fn AbstractMediaStream *Phonon::MediaSource::stream() const
1233     \internal
1234     Returns the media stream of the MediaSource if type() == Stream; otherwise
1235     returns 0.
1236     QIODevices are handled as streams, too.
1237 */
1238
1239 /*!
1240     \class Phonon::MediaSourcePrivate
1241     \inmodule Phonon
1242     \since 4.4
1243     \internal
1244 */
1245
1246 /*!
1247     \class Phonon::SeekSlider
1248     \inmodule Phonon
1249     \inheaderfile Phonon/SeekSlider
1250     \since 4.4
1251     \brief The SeekSlider class provides a slider for seeking to positions in media streams.
1252
1253     The SeekSlider connects to a \l{Phonon::}{MediaObject}, and
1254     controls the seek position in the object's media stream.
1255
1256     The slider will connect to the necessary signals to keep track of
1257     the sliders maximum, minimum, and current values. It will also
1258     disable itself for non-seekable streams, and update the media
1259     object when the current value of the slider changes.
1260
1261     Here follows a typical example of SeekSlider usage:
1262
1263     \snippet doc/src/snippets/seekslider.cpp 0
1264
1265     \sa Phonon::VolumeSlider, Phonon::VideoWidget, {Music Player Example}, {Phonon Module}
1266
1267 */
1268
1269 /*!
1270     \property Phonon::SeekSlider::iconVisible
1271     \brief whether the icon next to the slider is visible
1272
1273     By default the icon is visible if the platform provides an icon; else
1274     it's hidden.
1275
1276 */
1277
1278 /*!
1279     \property Phonon::SeekSlider::tracking
1280     \brief whether slider tracking is enabled
1281
1282     If tracking is enabled (the default), the media seeks
1283     while the slider is being dragged. If tracking is
1284     disabled, the media seeks only when the user
1285     releases the slider.
1286 */
1287
1288 /*!
1289     \property Phonon::SeekSlider::pageStep
1290     \brief the page step interval
1291
1292     The larger of two natural steps that a slider provides and
1293     typically corresponds to the user pressing PageUp or PageDown.
1294
1295     Defaults to 5 seconds.
1296 */
1297
1298 /*!
1299     \property Phonon::SeekSlider::singleStep
1300     \brief the single step interval
1301
1302     The smaller of two natural steps that a slider provides and
1303     typically corresponds to the user pressing an arrow key.
1304
1305     Defaults to 0.5 seconds.
1306 */
1307
1308 /*!
1309     \property Phonon::SeekSlider::orientation
1310     \brief the orientation of the slider
1311
1312     The orientation must be Qt::Vertical or Qt::Horizontal (the default).
1313 */
1314
1315 /*!
1316     \property Phonon::SeekSlider::iconSize
1317     \brief the icon size used for the mute button/icon.
1318
1319     The default size is defined by the GUI style.
1320 */
1321
1322 /*!
1323     \fn explicit Phonon::SeekSlider::SeekSlider(QWidget *parent = 0)
1324
1325     Constructs a seek slider widget with the given \a parent.
1326 */
1327
1328 /*!
1329     \fn explicit Phonon::SeekSlider::SeekSlider(MediaObject *media, QWidget *parent = 0)
1330
1331     Constructs a seek slider widget for the specified \a media with the
1332     given \a parent.
1333 */
1334
1335 /*!
1336     \fn Phonon::SeekSlider::~SeekSlider()
1337     Destroys the seek slider.
1338 */
1339
1340 /*!
1341     \fn Phonon::MediaObject *Phonon::SeekSlider::mediaObject() const
1342
1343     Return the media object this SeekSlider controls.
1344 */
1345
1346 /*!
1347     \class Phonon::SeekSliderPrivate
1348     \inmodule Phonon
1349     \since 4.4
1350     \internal
1351 */
1352
1353 /*!
1354     \fn void Phonon::SeekSlider::setMediaObject(MediaObject *media)
1355
1356     Sets the media object to be controlled by this slider to the \a media specified.
1357 */
1358
1359 /*!
1360     \class Phonon::VideoPlayer
1361     \inmodule Phonon
1362     \inheaderfile Phonon/VideoPlayer
1363     \since 4.4
1364     \brief The VideoPlayer widget is used to perform playback of video.
1365
1366     With VideoPlayer you can get results quickly and easily. You can
1367     do the standard playback tasks like play(), pause(), and stop(),
1368     but also set a playback volume and seek - if the media and backend
1369     supports seeking.
1370
1371     VideoPlayer is provided for convenience and removes the need to
1372     create a media graph with a \l{Phonon::}{MediaObject},
1373     \l{Phonon::}{AudioOutput}, and \l{Phonon::}{VideoWidget}. If
1374     you need functionality not supported by the player, you can build
1375     this \l{Building Graphs}{graph} yourself.
1376
1377     Keep in mind that when the VideoPlayer instance is deleted the
1378     playback will stop.
1379
1380     Note also that most of the functions in this class are
1381     asynchronous. For instance, a media source may not play
1382     immediately after you call the play() function.
1383
1384     A play and forget code example:
1385     \snippet doc/src/snippets/code/doc_src_phonon-api.cpp 4
1386
1387     \sa {Phonon Module}, MediaObject
1388 */
1389
1390 /*!
1391     \fn Phonon::VideoPlayer::VideoPlayer(QWidget *parent = 0)
1392     
1393     Constructs a new video widget with a \a parent using
1394     Phonon::VideoCategory as its category.
1395
1396     \param parent The QObject parent.
1397 */
1398
1399 /*!
1400     \fn Phonon::VideoPlayer::VideoPlayer(Phonon::Category category, QWidget *parent = 0)
1401
1402     Constructs a new VideoPlayer instance with the specified \a
1403     parent.
1404
1405     \a category is the category used for the audio output device.
1406 */
1407
1408 /*!
1409     \fn Phonon::VideoPlayer::~VideoPlayer()
1410
1411     On destruction the playback is stopped, also the audio output is
1412     removed so that the desktop mixer will not show the application
1413     anymore. If you need a persistent audio output don't use
1414     VideoPlayer but MediaObject, VideoPath and VideoOutput.
1415 */
1416
1417 /*!
1418     \fn qint64 Phonon::VideoPlayer::totalTime() const
1419
1420     Get the total time (in milliseconds) of the file currently being played.
1421 */
1422
1423 /*!
1424     \fn qint64 Phonon::VideoPlayer::currentTime() const
1425
1426     Get the current time (in milliseconds) of the file currently being played.
1427 */
1428
1429 /*!
1430     \fn float Phonon::VideoPlayer::volume() const
1431
1432     This is the current volume of the output as voltage factor.
1433
1434     1.0 means 100%, 0.5 means 50% voltage/25% power, 0.0 means 0%
1435 */
1436
1437 /*!
1438     \fn bool Phonon::VideoPlayer::isPlaying() const
1439
1440     Returns true if it is currently playing; otherwise returns false if it
1441     is currently stopped or paused
1442 */
1443
1444 /*!
1445     \fn bool Phonon::VideoPlayer::isPaused() const
1446
1447     Returns true if it is currently paused; otherwise returns false if it
1448     is currently playing or stopped.
1449 */
1450
1451 /*!
1452     \fn void Phonon::VideoPlayer::load(const Phonon::MediaSource &source)
1453
1454     Starts pre-loading the media data from the specified \a source and
1455     filling audio buffers in the backend.
1456
1457     When there's already a media playing (or paused) it will be stopped
1458     (the finished signal will not be emitted).
1459
1460     \sa MediaObject::setCurrentSource()
1461 */
1462
1463 /*!
1464     \fn void Phonon::VideoPlayer::play(const Phonon::MediaSource &source)
1465
1466     Plays the media from the given \a source. Starts playback as fast as
1467     possible.
1468     This can take a considerable time depending on the URL and the
1469     backend.
1470
1471     If you need low latency between calling play() and the sound actually
1472     starting to play on your output device you need to use MediaObject
1473     and be able to set the URL before calling play(). Note that
1474     \snippet doc/src/snippets/code/doc_src_phonon-api.cpp 5
1475     doesn't make a difference: the application should be idle between the
1476     load and play calls so that the backend can start preloading the
1477     media and fill audio buffers.
1478 */
1479
1480 /*!
1481     \fn void Phonon::VideoPlayer::play()
1482
1483     Continues playback of paused media. Restarts playback of a stopped
1484     (or newly loaded) media.
1485
1486     \sa MediaObject::play(), play()
1487 */
1488
1489 /*!
1490     \fn void Phonon::VideoPlayer::pause()
1491
1492     Pauses the playback.
1493
1494     \sa MediaObject::pause()
1495 */
1496
1497 /*!
1498     \fn void Phonon::VideoPlayer::stop()
1499
1500     Stops the playback.
1501
1502     \sa MediaObject::stop()
1503 */
1504
1505 /*!
1506     \fn void Phonon::VideoPlayer::seek(qint64 ms)
1507
1508     Seeks to the requested time. Note that the backend is free to
1509     ignore the seek request if the media source isn't seekable; you
1510     can check this by asking the media object of the VideoPlayer.
1511
1512     \snippet doc/src/snippets/videomedia.cpp 0
1513
1514     The \a ms parameter is the time in milliseconds from the start of
1515     the media.
1516
1517     The call is asynchronous, so currentTime() can still be the old
1518     value right after this method was called. If all you need is a
1519     slider that shows the current position and allows the user to
1520     seek, use the class SeekSlider.
1521
1522     \sa MediaObject::seek(), MediaObject::isSeekable(), mediaObject()
1523 */
1524
1525 /*!
1526     \fn void Phonon::VideoPlayer::setVolume(float volume)
1527
1528     Sets the \a volume of the output as voltage factor.
1529
1530     1.0 means 100%, 0.5 means 50% voltage/25% power, 0.0 means 0%
1531 */
1532
1533 /*!
1534     \fn MediaObject *Phonon::VideoPlayer::mediaObject() const
1535
1536     Returns the media object being used by the player.
1537
1538     The media object can be accessed directly instead of using the
1539     \l{VideoPlayer}s convenience functions, e.g., play() and stop().
1540     It is also possible to give the object to other Phonon widgets,
1541     e.g., a \l{Phonon::}{SeekSlider} or a \l{Phonon::}{VolumeSlider}.
1542
1543     \sa Phonon::SeekSlider, Phonon::MediaObject
1544 */
1545
1546 /*!
1547     \fn AudioOutput *Phonon::VideoPlayer::audioOutput() const
1548
1549     Returns the audio output object being used by the player.
1550
1551 */
1552
1553 /*!
1554     \fn VideoWidget *Phonon::VideoPlayer::videoWidget() const
1555
1556     Returns the video widget being used by the player.
1557 */
1558
1559 /*!
1560     \fn void Phonon::VideoPlayer::finished()
1561
1562     This signal is emitted when the playback finished.
1563
1564 */
1565
1566 /*!
1567     \class Phonon::VideoWidgetPrivate
1568     \inmodule Phonon
1569     \since 4.4
1570     \internal
1571 */
1572
1573 /*!
1574     \class Phonon::MediaObject
1575     \inmodule Phonon
1576     \inheaderfile Phonon/MediaObject
1577     \since 4.4
1578     \brief The MediaObject class provides an interface for media playback.
1579
1580     The media object manages a \l{Phonon::}{MediaSource}, which
1581     supplies the media object with multimedia content, e.g., from a
1582     file. A playback in Phonon is always started by calling the
1583     \l{Phonon::MediaObject::}{play()} function.
1584
1585     The state of play (play, pause, stop, seek) is controlled by the
1586     media object, and you can also query the current
1587     \l{Phonon::MediaObject::}{state()}. It keeps track of the playback
1588     position in the media stream, and emits the
1589     \l{Phonon::MediaObject::}{tick()} signal when the current position
1590     in the stream changes.
1591
1592     Notice that most functions of this class are asynchronous, so you
1593     cannot rely on that a state is entered after a function call
1594     before you receive the \l{Phonon::MediaObject::}{stateChanged()}
1595     signal. The description of the \l{Phonon::}{State} enum gives a
1596     description of the different states.
1597
1598     Before play() is called, the media object should be connected to
1599     \l{Sinks}{output nodes}, which outputs the media to the
1600     underlying hardware. The output nodes required are dependent on
1601     the contents of the multimedia file that is played back. Phonon
1602     has currently two output nodes: the \l{Phonon::}{AudioOutput} for
1603     audio content and \l{Phonon::}{VideoWidget} for video content.  If
1604     a \l{Phonon::}{MediaSource} contains both audio and video, both
1605     nodes need to be connected to the media object.
1606
1607     \snippet snippets/phonon.cpp 4
1608     \snippet snippets/phonon.cpp 5 
1609
1610     The media object can queue sources for playback. When it has
1611     finished to play one source, it will start playing the next in the
1612     queue; the new source is then removed from the queue. The
1613     queue can be altered at any time. 
1614
1615     \snippet doc/src/snippets/code/doc_src_phonon-api.cpp 7
1616
1617     You can also make use of the
1618     \l{Phonon::MediaObject::}{aboutToFinish()} signal, which is
1619     guaranteed to be emitted in time for altering the queue.
1620
1621     \snippet doc/src/snippets/code/doc_src_phonon-api.cpp 8
1622
1623     When playback is finishing, i.e., when a media source has been
1624     played to the end and the queue is empty, several signals are
1625     emitted. First, the media object will emit aboutToFinish() -
1626     shortly before the playback has finished - and then finished().
1627     The stateChanged() signal will also be emitted with
1628     \l{Phonon::}{PausedState}, which is the state the media object
1629     takes when the playback is finished. If you wish to enter another
1630     state, you can connect a slot to finished() and set a new state
1631     there.
1632
1633     The media object resolves the meta information, such as title,
1634     artist, and album. The meta data is not resolved immediately after
1635     a new source is provided, but will be resolved before the object
1636     leaves the \l{Phonon::}{LoadingState}. The data is queried by
1637     string keys - which should follow the Ogg Vorbis specification
1638     \l http://xiph.org/vorbis/doc/v-comment.html - or by using the
1639     \l{Phonon::}{MetaData} enum. The data available will depend on the
1640     type and content of the individual media files.  metaDataChanged()
1641     will be emitted when the media object has resolved new meta data.
1642
1643     Errors encountered during playback and loading of media sources
1644     are reported by emitting a state changed signal with
1645     \l{Phonon::}{ErrorState}. The severity of the error can be queried
1646     by the \l{Phonon::}{ErrorType}. With a \l{Phonon::}{NormalError},
1647     it might be possible to continue the playback, for instance, if
1648     only audio playback fails for a media source which also has video.
1649     A \l{Phonon::}{FatalError} indicates that Phonon cannot continue
1650     playback of the current source, but it is possible to try with a
1651     different one. A user readable error message is given by
1652     errorString().
1653
1654     \sa {Symbian Platform Security Requirements}
1655     \sa Phonon::MediaSource, Phonon::AudioOutput, VideoWidget,
1656     {Music Player Example}, {Phonon Overview}, Phonon::VideoPlayer,
1657     Phonon::createPlayer(), {Phonon Module}
1658
1659 */
1660
1661 /*!
1662     \property Phonon::MediaObject::transitionTime
1663     \brief Defines the time between playback of two media sources
1664     in the media queue.
1665
1666     A positive transition time defines a gap of silence between queued
1667     media sources.
1668
1669     A transition time of 0 ms requests gapless playback (i.e., the
1670     next source in the media queue starts immediately after the
1671     playback of the current source finishes).
1672
1673     A negative transition time defines a crossfade between the queued
1674     media sources.
1675
1676     Defaults to 0 (gapless playback).
1677
1678     \warning This feature might not work reliably with every
1679              backend.
1680 */
1681
1682 /*!
1683     \property Phonon::MediaObject::prefinishMark
1684     \brief the time when the prefinishMarkReached signal is emitted before playback ends.
1685
1686     This property specifies the time in milliseconds the
1687     prefinishMarkReached() signal is emitted before the playback
1688     finishes. A value of \c 0 disables the signal. The signal is only
1689     emitted for the last source in the \l{queue()}{media queue}.
1690
1691     Defaults to \c 0 (disabled).
1692
1693     \warning For some media data the total time cannot be determined
1694     accurately, therefore the accuracy of the prefinishMarkReached signal
1695     can be bad sometimes. Still, it is better to use this method than to
1696     look at totalTime() and currentTime() to emulate the behavior
1697     because the backend might have more information available than your
1698     application does through totalTime() and currentTime().
1699
1700     \sa prefinishMarkReached()
1701 */
1702
1703 /*!
1704     \property Phonon::MediaObject::tickInterval
1705     \brief The time interval in milliseconds between two ticks.
1706
1707     The tick() signal is emitted continuously during playback.
1708     The tick interval is the time that elapses between the emission of two tick signals.
1709     If you set the interval to \c 0 the tick signal gets disabled.
1710
1711     The tick() signal can, for instance, be used to update widgets
1712     that show the current position in the playback of a media source.
1713
1714     Defaults to \c 0 (disabled).
1715
1716     \warning The back-end is free to choose a different tick interval close
1717     to what you asked for. This means that the following code \c may fail:
1718     \snippet doc/src/snippets/code/doc_src_phonon-api.cpp 9
1719     On the other hand the following is guaranteed:
1720     \snippet doc/src/snippets/code/doc_src_phonon-api.cpp 10
1721
1722     \sa tick()
1723 */
1724
1725 /*!
1726     \fn Phonon::MediaObject::~MediaObject()
1727
1728     Destroys the MediaObject.
1729 */
1730
1731 /*!
1732     \fn State Phonon::MediaObject::state() const
1733
1734     Returns the current Phonon::State of the object.
1735
1736     \sa Phonon::State, stateChanged()
1737 */
1738
1739 /*!
1740     \fn bool Phonon::MediaObject::hasVideo() const
1741
1742     Check whether the current media source includes a video stream.
1743
1744     \warning This information is not resolved immediately after a
1745     media object gets a new source. Listen to the hasVideoChanged()
1746     signal instead.
1747
1748     \snippet doc/src/snippets/code/doc_src_phonon-api.cpp 11
1749
1750     Returns \c true if the media contains video data; otherwise,
1751     returns  \c false.
1752
1753     \sa hasVideoChanged()
1754 */
1755
1756 /*!
1757     \fn bool Phonon::MediaObject::isSeekable() const
1758
1759     Check whether it is possible to seek, i.e., change the
1760     playback position in the media stream.
1761
1762     \warning This information is not solved immediately after the
1763     media object gets a new media source. The hasVideoChanged() signal
1764     is emitted after this information is available.
1765
1766     \snippet doc/src/snippets/code/doc_src_phonon-api.cpp 12
1767
1768     Returns \c true if the current media may be seeked; otherwise,
1769     returns \c false.
1770
1771     \sa seekableChanged()
1772 */
1773
1774 /*!
1775     \fn QStringList Phonon::MediaObject::metaData(const QString &key) const
1776
1777     Returns the strings associated with the given \a key.
1778
1779     Backends should use the keys specified in the Ogg Vorbis
1780     documentation: \l http://xiph.org/vorbis/doc/v-comment.html
1781
1782     Therefore the following should work with every backend:
1783
1784     Note that meta data is not resolved before the \c
1785     metaDataChanged() signal is emitted.
1786
1787     A typical usage looks like this:
1788
1789     \snippet doc/src/snippets/code/doc_src_phonon-api.cpp 13
1790 */
1791
1792 /*!
1793     \fn QStringList Phonon::MediaObject::metaData(Phonon::MetaData key) const
1794
1795     Returns the strings associated with the given \a key.
1796
1797     Same as above except that the keys are defined in the
1798     Phonon::MetaData enum.
1799
1800     \sa metaDataChanged()
1801 */
1802
1803 /*!
1804     \fn QMultiMap<QString, QString> Phonon::MediaObject::metaData() const
1805
1806     Returns all meta data in a multi map. 
1807
1808     \sa metaDataChanged()
1809 */
1810
1811 /*!
1812     \fn QString Phonon::MediaObject::errorString() const
1813
1814     Returns a human-readable description of the last error that occurred.
1815     The strings given may vary between backends.
1816
1817     The error description can be used to give a message to the user -
1818     and the developer - when the stateChanged() signal is emitted with
1819     \l{Phonon::}{ErrorState}.
1820
1821     \section1 Qt Backends
1822
1823     On Windows, Qt fetches its error messages from the DirectShow
1824     backend.  This usually includes an error number, which can be
1825     looked up in the DirectShow documentation:
1826     \l{http://msdn.microsoft.com/archive/default.asp?url=/archive/en-us/dx81_c/directx_cpp/htm/errorandsuccesscodes.asp}.
1827
1828     On Linux and Mac, the error strings are not fetched directly from
1829     the backend, but are created in the backend.
1830
1831     \sa Phonon::ErrorState, stateChanged()
1832 */
1833
1834 /*!
1835     \fn ErrorType Phonon::MediaObject::errorType() const
1836
1837     Tells your program what to do about the last error that occurred.
1838     Use this function after receiving a stateChanged() signal with
1839     \l{Phonon::}{ErrorState}.
1840
1841     \sa Phonon::ErrorType, Phonon::ErrorState, stateChanged()
1842 */
1843
1844 /*!
1845     \fn MediaSource Phonon::MediaObject::currentSource() const
1846
1847     Returns the current media source, i.e., the media source that is
1848     being played back. The current source is either set with
1849     setCurrentSource() or taken from the media queue() when a media
1850     source has finished playing.
1851
1852     \sa setCurrentSource()
1853 */
1854
1855 /*!
1856     \fn void Phonon::MediaObject::setCurrentSource(const MediaSource &source)
1857
1858     Set the media source the MediaObject should use.
1859
1860     After the media object receives a new source, it will enter the
1861     \l{Phonon::}{LoadingState}. When it is ready to play, it
1862     enters the \l{Phonon::}{StoppedState} unless another state
1863     has been requested, e.g., by calling play().
1864
1865     \a source is the MediaSource object to the media data. You can
1866     just as well use a QUrl or QString (for a local file) here.
1867
1868     We show an example:
1869
1870     \snippet doc/src/snippets/code/doc_src_phonon-api.cpp 14
1871
1872     \sa currentSource(), MediaSource
1873 */
1874
1875 /*!
1876     \fn QList<MediaSource> Phonon::MediaObject::queue() const
1877
1878     Returns the queued media sources.
1879
1880     This does list does not include the current source,
1881     returned by currentSource().
1882
1883     \sa enqueue()
1884 */
1885
1886 /*!
1887     \fn void Phonon::MediaObject::setQueue(const QList<MediaSource> &sources)
1888
1889     Set the \a sources to play when the current source has finished.
1890
1891     This function will overwrite the current queue.
1892
1893     \sa clearQueue(), enqueue()
1894 */
1895
1896 /*!
1897     \fn void Phonon::MediaObject::setQueue(const QList<QUrl> &urls)
1898
1899     Set the \a urls to play when the current media has finished.
1900
1901     This function overwrites the current queue.
1902
1903     \sa clearQueue(), enqueue()
1904 */
1905
1906 /*!
1907     \fn void Phonon::MediaObject::enqueue(const MediaSource &source)
1908
1909     Appends \a source to the queue.
1910
1911     You can use this function to provide the next source after the
1912     aboutToFinish() signal has been emitted.
1913
1914     \sa aboutToFinish(), setQueue(), clearQueue()
1915 */
1916
1917 /*!
1918     \fn void Phonon::MediaObject::enqueue(const QList<MediaSource> &sources)
1919
1920     Appends multiple \a sources to the queue.
1921
1922     \sa setQueue(), clearQueue()
1923 */
1924
1925 /*!
1926     \fn void Phonon::MediaObject::enqueue(const QList<QUrl> &urls)
1927
1928     Appends the URLs in \a urls to the media source queue. 
1929
1930     The function will create \l{MediaSource}s from the \l{QUrl}s, and
1931     append these to the queue.
1932
1933     \sa setQueue(), clearQueue()
1934 */
1935
1936 /*!
1937     \fn void Phonon::MediaObject::clearQueue()
1938
1939     Clears the queue of media sources.
1940
1941     \sa queue(), enqueue()
1942 */
1943
1944 /*!
1945     \fn qint64 Phonon::MediaObject::currentTime() const
1946
1947     Returns the current time (in milliseconds), i.e., position in the
1948     media stream, of the file currently being played.
1949
1950     \sa tick(), totalTime(), remainingTime()
1951 */
1952
1953 /*!
1954     \fn qint64 Phonon::MediaObject::totalTime() const
1955
1956     Get the total time (in milliseconds) of the file currently being played.
1957
1958     Returns the total time in milliseconds.
1959
1960     \warning The total time is not defined before the media object
1961              enters the \l{Phonon::}{LoadingState}.
1962
1963     \sa totalTimeChanged()
1964 */
1965
1966 /*!
1967     \fn qint64 Phonon::MediaObject::remainingTime() const
1968
1969     Get the remaining time (in milliseconds) of the file currently being played.
1970
1971     Returns the remaining time in milliseconds.
1972
1973     \sa totalTime(), currentTime(), totalTimeChanged()
1974 */
1975
1976 /*!
1977     \fn void Phonon::MediaObject::play()
1978
1979     Requests playback of the media data to start.
1980
1981     Playback starts when the stateChanged() signal is emitted with
1982     \l{Phonon::}{PlayingState}.
1983
1984     If the media object is already in a
1985     \l{Phonon::}{PlayingState}, nothing happens.
1986
1987     \sa stop(), pause(), stateChanged()
1988 */
1989
1990 /*!
1991     \fn void Phonon::MediaObject::pause()
1992
1993     Requests playback to pause, and the media object to enter the
1994     \l{Phonon::}{PausedState}. If it was paused already, nothing
1995     changes.
1996
1997     This function is asynchronous and the media might not be paused
1998     immediately.
1999
2000     \sa play(), stop(), stateChanged()
2001 */
2002
2003 /*!
2004     \fn void Phonon::MediaObject::stop()
2005
2006     Requests playback to stop, and the media object to enter the
2007     \l{Phonon::}{StoppedState}. If it was stopped before
2008     nothing changes.
2009
2010     This function is asynchronous and the media might not be
2011     stopped immediately.
2012
2013     \sa play(), pause(), stateChanged()
2014 */
2015
2016 /*!
2017     \fn void Phonon::MediaObject::seek(qint64 time)
2018
2019     Requests a seek to the \a time indicated, specified in milliseconds.
2020
2021     You can only seek if state() is PlayingState, BufferingState or PausedState.
2022
2023     The call is asynchronous, so currentTime can still be the old
2024     value right after this method was called. If all you need is a
2025     slider that shows the current position and allows the user to
2026     seek, use the class SeekSlider.
2027
2028     If the current source of the media object is not seekable, calls
2029     to this functions do nothing.
2030
2031     \sa SeekSlider, tick()
2032 */
2033
2034 /*!
2035     \fn void Phonon::MediaObject::clear()
2036
2037     Stops and removes all playing and enqueued media sources.
2038
2039     \sa setCurrentSource()
2040 */
2041
2042
2043 /*!
2044     \fn void Phonon::MediaObject::stateChanged(Phonon::State newstate, Phonon::State oldstate)
2045
2046     This signal is emitted when the state of the MediaObject has changed.
2047     The \a oldstate and \a newstate parameters indicate the previous
2048     state and current state of the media object.
2049
2050     If you are only interested in the new state of the media object, you can
2051     connect this signal to a slot that accepts only one State argument.
2052 */
2053
2054 /*!
2055     \fn void Phonon::MediaObject::tick(qint64 time)
2056
2057     This signal is emitted in intervals defined by the
2058     \l{tickInterval} property. The current position of the media
2059     object in the stream is given by the \a time parameter. The \a
2060     time is specified in milliseconds.
2061
2062     \sa tickInterval
2063 */
2064
2065 /*!
2066     \fn void Phonon::MediaObject::metaDataChanged()
2067
2068     This signal is emitted when the media object has resolved new meta
2069     data. This will happen before the media object leaves the
2070     \l{Phonon::}{LoadingState} after a new source has been set.
2071
2072     This signal is not emitted when the media object removes the
2073     current data, i.e., when a new source is set or an error has
2074     occurred. If you need to know this, you can listen for the
2075     \l{Phonon::}{ErrorState}, and connect to the
2076     \l{Phonon::MediaObject::}{currentSourceChanged()} signal.
2077
2078     You can get the new meta data with the metaData methods.
2079     
2080     \sa metaData(), currentSourceChanged(), stateChanged(), Phonon::State
2081 */
2082
2083 /*!
2084     \fn void Phonon::MediaObject::seekableChanged(bool isSeekable)
2085
2086     This signal is emitted when the media object's ability to seek in
2087     the media stream changes. \a isSeekable is true if it is possible
2088     to seek(); otherwise, it is false.
2089
2090     Change in the ability to seek in the stream usually happens when
2091     the current source changes or when an error occurs.
2092
2093     \omit Emitted whenever the return value of isSeekable()
2094     changes. \endomit
2095
2096     Normally you'll check isSeekable() after setting a new media
2097     source, and then let this signal tell you when seeking is
2098     possible. That way you don't have to poll isSeekable().
2099 */
2100
2101 /*!
2102     \fn void Phonon::MediaObject::hasVideoChanged(bool hasVideo)
2103
2104     Emitted whenever the return value of hasVideo() changes, i.e.,
2105     the media source being played back contains video.
2106
2107     Normally you'll check hasVideo() first and then let this signal
2108     tell you whether video is available now or not. That way you
2109     don't have to poll hasVideo().
2110
2111     \a hasVideo is true  when the stream contains video and adding a
2112     VideoWidget will show a video, and false if there is no video data
2113     in the stream and adding a VideoWidget will show an empty (black)
2114     VideoWidget.
2115 */
2116
2117 /*!
2118     \fn void Phonon::MediaObject::bufferStatus(int percentFilled)
2119
2120     Provides information about the status of the buffer.
2121
2122     When a MediaObject is in the \l{Phonon::}{BufferingState}, it will
2123     send this signal regularly. \a percentFilled is a number between 0
2124     and 100 telling you how much the buffer is filled.
2125
2126     You can use this signal to show a progress bar to the user when
2127     in BufferingState:
2128
2129     \snippet doc/src/snippets/code/doc_src_phonon-api.cpp 15
2130
2131     Note that the \l{Phonon::}{BufferingState} is commonly used when
2132     waiting for data over a network connection, but this might not be
2133     true for all backends.
2134 */
2135
2136 /*!
2137     \fn void Phonon::MediaObject::finished()
2138
2139     Emitted when the object has finished playback.  It is not emitted
2140     if you call stop(), pause() or load(). It is emitted only when the
2141     current media source has finished playing and the media queue() is
2142     empty, or when a \l{Phonon::FatalError}{fatal error} occurs.
2143
2144     \warning This signal is not emitted when the current source has
2145     finished and there's another source in the queue. It is only
2146     emitted when the queue is empty.
2147
2148     \sa currentSourceChanged(), aboutToFinish(), prefinishMarkReached()
2149 */
2150
2151 /*!
2152     \fn void Phonon::MediaObject::currentSourceChanged(const Phonon::MediaSource &newSource)
2153
2154     Emitted when the MediaObject fetches a new MediaSource from the
2155     queue() and before it enters the \l{Phonon::}{LoadingState} for
2156     the new source. The media object will take a new source from the
2157     queue() when it has finished the playback of the
2158     \l{currentSource()}{current source}.
2159
2160     \a newSource is the source that starts to play at the time the
2161     signal is emitted.
2162 */
2163
2164 /*!
2165     \fn void Phonon::MediaObject::aboutToFinish()
2166
2167     Emitted before the playback of the whole queue ends. When this
2168     signal is emitted you still have time to enqueue() a new
2169     MediaSource, so that playback continues.
2170
2171     If you need a signal to be emitted at a specific time before
2172     playback is finished, you should use the prefinishMarkReached()
2173     signal instead.
2174
2175     \sa enqueue(), prefinishMark, prefinishMarkReached()
2176 */
2177
2178 /*!
2179     \fn void Phonon::MediaObject::prefinishMarkReached(qint32 msecToEnd)
2180
2181     Emitted when there are only \a msecToEnd milliseconds left
2182     of playback.
2183
2184     \warning This signal is not emitted when there is another source
2185     in the queue.  It is only emitted when the queue is empty.
2186
2187     \sa setPrefinishMark(), prefinishMark(), aboutToFinish(), finished()
2188 */
2189
2190 /*!
2191     \fn void Phonon::MediaObject::totalTimeChanged(qint64 newTotalTime)
2192
2193     This signal is emitted as soon as the total time of the media file is
2194     known or has changed. For most non-local media data the total
2195     time of the media can only be known after some time. At that time the
2196     totalTime function can not return useful information. You have
2197     to wait for this signal to know the real total time.
2198
2199     \a newTotalTime is the length of the media file in milliseconds.
2200
2201     \sa totalTime()
2202 */
2203
2204 /*!
2205     \fn MediaObject *Phonon::createPlayer(Phonon::Category category, const MediaSource &source = MediaSource())
2206
2207     Convenience function to create a MediaObject and AudioOutput
2208     connected by a path. The \l{Phonon::}{MediaObject} return will
2209     have \a source set as its current source and the specified \a
2210     category.
2211
2212 */
2213
2214 /*!
2215     \class Phonon::MediaObjectPrivate
2216     \inmodule Phonon
2217     \since 4.4
2218     \internal
2219 */
2220
2221 /*!
2222     \namespace Phonon::BackendCapabilities
2223     \inmodule Phonon
2224     \since 4.4
2225     \brief The BackendCapabilities namespace contains functions to describe the capabilities of the multimedia backend.
2226
2227 */
2228
2229 /*!
2230     \class Phonon::BackendCapabilitiesPrivate
2231     \inmodule Phonon
2232     \since 4.4
2233     \internal
2234 */
2235
2236 /*!
2237     \class Phonon::BackendCapabilities::Notifier
2238     \since 4.4
2239     \inmodule Phonon
2240     \inheaderfile Phonon/BackendCapabilities
2241
2242     Notifications about backend capabilities.
2243 */
2244
2245 /*!
2246     \fn void Phonon::BackendCapabilities::Notifier::capabilitiesChanged()
2247
2248     This signal is emitted if the capabilities have changed. This can
2249     happen if the user has requested a backend change.
2250 */
2251
2252 /*!
2253     \fn void Phonon::BackendCapabilities::Notifier::availableAudioOutputDevicesChanged()
2254
2255     This signal is emitted when audio output devices were plugged or
2256     unplugged.
2257
2258     Check BackendCapabilities::availableAudioOutputDevices to get the
2259     current list of available devices.
2260 */
2261
2262 /*!
2263     \fn Notifier *Phonon::BackendCapabilities::notifier()
2264
2265     Use this function to get a QObject pointer to connect to the capabilitiesChanged signal.
2266
2267     \return a pointer to a QObject.
2268
2269     The capabilitiesChanged signal is emitted if the capabilities have changed. This can
2270     happen if the user has requested a backend change.
2271
2272     To connect to this signal do the following:
2273     \snippet doc/src/snippets/code/doc_src_phonon-api.cpp 16
2274
2275     \sa Notifier::capabilitiesChanged()
2276 */
2277
2278 /*!
2279     \fn QStringList Phonon::BackendCapabilities::availableMimeTypes()
2280
2281     Returns a list of mime types that the Backend can decode.
2282
2283     \sa isMimeTypeAvailable()
2284 */
2285
2286 /*!
2287     \fn bool Phonon::BackendCapabilities::isMimeTypeAvailable(const QString &mimeType)
2288
2289     Often all you want to know is whether one given MIME type can be
2290     decoded by the backend. Use this method in favor of
2291     availableMimeTypes() as it can give you a negative answer without
2292     having a backend loaded.
2293
2294     Returns true if the given \a mimeType is supported by the backend;
2295     otherwise, returns false.
2296
2297     \sa availableMimeTypes()
2298 */
2299
2300 /*!
2301     \fn QList<AudioOutputDevice> Phonon::BackendCapabilities::availableAudioOutputDevices()
2302
2303     Returns the audio output devices the backend supports.
2304
2305     \return A list of AudioOutputDevice objects that give a name and
2306             description for every supported audio output device.
2307 */
2308
2309 /*!
2310     \fn QList<EffectDescription> Phonon::BackendCapabilities::availableAudioEffects()
2311
2312     Returns descriptions for the audio effects the backend supports.
2313
2314     \return A list of AudioEffectDescription objects that give a name and
2315     description for every supported audio effect.
2316 */
2317
2318 /*!
2319     \internal
2320     \class ObjectDescriptionModelData
2321     \internal
2322     \inmodule Phonon
2323     \brief Data class for models for ObjectDescription objects.
2324 */
2325
2326 /*!
2327     \typedef Phonon::EffectDescription
2328     \relates Phonon::ObjectDescription
2329
2330     EffectDescription gives a description of an \l{Processors}{audio
2331     effect}. It is a typedef of the \l{Phonon::}{ObjectDescription}
2332     class. Please see its class description for details.
2333
2334     EffectDescription is used to create audio \l{Phonon::}{Effect}s,
2335     which can be inserted into a media graph, altering an audio
2336     stream.
2337
2338     \sa Phonon::ObjectDescription, {Capabilities Example}, {Media
2339     Player}
2340
2341 */
2342
2343 /*!
2344     \class Phonon::ObjectDescriptionModel
2345     \inmodule Phonon
2346     \internal
2347     \since 4.4
2348     \brief The ObjectDescriptionModel class provides a model from
2349     a list of ObjectDescription objects.
2350
2351     ObjectDescriptionModel is a read only model that supplies a list
2352     using ObjectDescription::name() for the text and
2353     ObjectDescription::description() for the tooltip. If set the properties
2354     "icon" and "available" are used to set the decoration and disable the
2355     item (disabled only visually, you can still select and drag it).
2356
2357     It also provides the methods moveUp() and moveDown() to order the list.
2358     Additionally drag and drop is possible so that
2359     QAbstractItemView::InternalMove can be used.
2360     The resulting order of the ObjectDescription::index() values can then be
2361     retrieved using tupleIndexOrder().
2362
2363     An example use case would be to give the user a QComboBox to select
2364     the output device:
2365     \snippet doc/src/snippets/code/doc_src_phonon-api.cpp 17
2366
2367     And to retrieve the selected AudioOutputDevice:
2368     \snippet doc/src/snippets/code/doc_src_phonon-api.cpp 18
2369
2370 */
2371
2372 /*!
2373     \fn inline int Phonon::ObjectDescriptionModel::rowCount(const QModelIndex &parent = QModelIndex()) const
2374
2375     Returns the number of rows in the model. This value corresponds
2376     to the size of the list passed through setModelData.
2377
2378     \param parent The optional \a parent argument is used in most models to specify
2379     the parent of the rows to be counted. Because this is a list if a
2380     valid parent is specified the result will always be 0.
2381
2382     Reimplemented from QAbstractItemModel.
2383
2384     \sa QAbstractItemModel::rowCount()
2385 */
2386
2387 /*!
2388     \fn inline QVariant Phonon::ObjectDescriptionModel::data(const QModelIndex &index, int role = Qt::DisplayRole) const
2389
2390     Returns data from the item with the given \a index for the specified
2391     \a role.
2392     If the view requests an invalid index, an invalid variant is
2393     returned.
2394
2395     Reimplemented from QAbstractItemModel.
2396
2397     \sa QAbstractItemModel::data(), Qt::ItemDataRole
2398 */
2399
2400 /*!
2401     \fn inline Qt::ItemFlags Phonon::ObjectDescriptionModel::flags(const QModelIndex &index) const
2402     \internal
2403
2404     Reimplemented to show unavailable devices as disabled (but still
2405     selectable). The \a index of the model index for which to return
2406     flags.
2407
2408 */
2409
2410 /*!
2411     \fn inline QList<int> Phonon::ObjectDescriptionModel::tupleIndexOrder() const
2412
2413     Returns a list of indexes in the same order as they are in the
2414     model. The indexes come from the ObjectDescription::index
2415     method.
2416
2417     This is useful to let the user define a list of preference.
2418 */
2419
2420 /*!
2421     \fn inline int Phonon::ObjectDescriptionModel::tupleIndexAtPositionIndex(int positionIndex) const
2422
2423     Returns the ObjectDescription::index for the tuple
2424     at the given position \a positionIndex. For example a
2425     QComboBox will give you the currentIndex as the
2426     position in the list. But to select the according
2427     AudioOutputDevice using AudioOutputDevice::fromIndex
2428     you can use this method.
2429
2430     \param positionIndex The position in the list.
2431 */
2432
2433 /*!
2434     \class Phonon::ObjectDescriptionModelDataPrivate
2435     \inmodule Phonon
2436     \since 4.4
2437     \internal
2438 */
2439
2440 /*!
2441     \fn inline QMimeData *Phonon::ObjectDescriptionModel::mimeData(const QModelIndexList &indexes) const
2442     \internal
2443     
2444     Returns the MIME data that dropMimeData() can use to create new
2445     items.
2446 */
2447
2448 /*!
2449     \fn inline void Phonon::ObjectDescriptionModel::moveUp(const QModelIndex &index)
2450
2451     Moves the item at the given \a index up. In the resulting list
2452     the items at index.row() and index.row() - 1 are swapped.
2453
2454     Connected views are updated automatically.
2455 */
2456
2457 /*!
2458     \fn inline void Phonon::ObjectDescriptionModel::moveDown(const QModelIndex &index)
2459
2460     Moves the item at the given \a index down. In the resulting list
2461     the items at index.row() and index.row() + 1 are swapped.
2462
2463     Connected views are updated automatically.
2464 */
2465
2466 /*!
2467     \fn explicit inline Phonon::ObjectDescriptionModel::ObjectDescriptionModel(QObject *parent = 0)
2468
2469     Constructs a ObjectDescription model with the
2470     given \a parent.
2471 */
2472
2473 /*!
2474     \fn explicit inline Phonon::ObjectDescriptionModel::ObjectDescriptionModel(const QList<ObjectDescription<type> > &data, QObject *parent = 0)
2475
2476     Constructs a ObjectDescription model with the
2477     given \a parent and the given \a data.
2478 */
2479
2480 /*!
2481     \fn inline void Phonon::ObjectDescriptionModel::setModelData(const QList<ObjectDescription<type> > &data)
2482
2483     Sets the model data using the list provided by \a data.
2484
2485     All previous model data is cleared.
2486 */
2487
2488 /*!
2489     \fn inline QList<ObjectDescription<type> > Phonon::ObjectDescriptionModel::modelData() const
2490
2491     Returns the model data.
2492
2493     As the order of the list might have changed this can be different
2494     to what was set using setModelData().
2495 */
2496
2497 /*!
2498     \fn inline ObjectDescription<type> Phonon::ObjectDescriptionModel::modelData(const QModelIndex &index) const
2499
2500     Returns one ObjectDescription of the model data for the given \a index.
2501 */
2502
2503 /*!
2504     \fn inline Qt::DropActions Phonon::ObjectDescriptionModel::supportedDropActions() const
2505
2506     This model supports drag and drop to copy or move
2507     items.
2508 */
2509
2510 /*!
2511     \fn inline bool Phonon::ObjectDescriptionModel::dropMimeData(const QMimeData *data, Qt::DropAction action, int row, int column, const QModelIndex &parent)
2512
2513     Accept drops from other models of the same ObjectDescriptionType.
2514
2515     The \a data is dropped at the given \a row and \a column; you
2516     also receive the \a parent model index.
2517
2518     If a valid \a parent is given the dropped items will be inserted
2519     above that item.
2520 */
2521
2522 /*!
2523     \fn inline bool Phonon::ObjectDescriptionModel::removeRows(int row, int count, const QModelIndex &parent = QModelIndex())
2524
2525     Removes count rows starting with the given row.
2526
2527     If a valid \a parent is given no rows are removed since this is a
2528     list model.
2529
2530     Returns true if the rows were successfully removed; otherwise returns false.
2531 */
2532
2533 /*!
2534     \fn inline QStringList Phonon::ObjectDescriptionModel::mimeTypes() const
2535
2536     Returns a list of supported drag and drop MIME types. Currently
2537     it only supports one type used internally.
2538 */
2539
2540 /*!
2541     \class Phonon::EffectInterface
2542     \inmodule Phonon
2543     \since 4.4
2544     \internal
2545 */
2546
2547 /*!
2548     \class Phonon::Effect
2549     \inmodule Phonon
2550     \inheaderfile Phonon/Effect
2551     \since 4.4
2552     \brief The Effect class is used to transform audio streams.
2553
2554     An effect is a media node which is inserted into a path between a
2555     \l{Phonon::}{MediaObject} and an audio output node, for instance,
2556     an \l{Phonon::}{AudioOutput}. The Effect transforms the media
2557     stream on that path.
2558
2559     Examples may include simple modifiers, such as fading or pitch
2560     shifting, and more complex mathematical transformations. You can
2561     query the backend for available effects with
2562     BackendCapabilities::availableAudioEffects(). Note that the
2563     effects available is dependent on the underlying system
2564     (DirectDraw, GStreamer, or QuickTime).
2565
2566     In order to use an effect, insert it into the path as follows:
2567
2568     \snippet doc/src/snippets/code/doc_src_phonon-api.cpp 19
2569
2570     The effect will immediately begin applying it's transformations on
2571     the path. To stop it, remove the Effect from the path.
2572
2573     To create an effect, you use the \l{Phonon::}{EffectDescription}
2574     class, which you get from
2575     \l{BackendCapabilities::}{availableAudioEffects()}. We give a code
2576     example below.
2577
2578     \snippet doc/src/snippets/audioeffects.cpp 0
2579
2580     An effect can have one or more parameters, which let you alter how
2581     the effect works, for instance, by specifying the depth of a
2582     reverb effect. See the EffectParameter class description for
2583     details.
2584
2585     Phonon also provides EffectWidget, which lets the user modify the
2586     parameters of an effect an the fly; e.g., with combo boxes.
2587
2588     \sa {Phonon Module}, EffectWidget
2589 */
2590
2591 /*!
2592     \fn explicit Phonon::Effect::Effect(const EffectDescription &description, QObject *parent = 0)
2593
2594     Constructs a new effect object with the given \a description and \a parent object.
2595
2596     The EffectDescription object determines the type of the effect.
2597
2598     \sa {Phonon::BackendCapabilities::availableAudioEffects()}
2599 */
2600
2601 /*!
2602     \fn Phonon::Effect::Effect(EffectPrivate &dd, QObject *parent)
2603     \internal
2604 */
2605
2606 /*!
2607     \fn Phonon::Effect::~Effect()
2608     \internal
2609 */
2610
2611 /*!
2612     \fn QVariant Phonon::Effect::parameterValue(const EffectParameter &parameter) const
2613
2614     Returns the value of the given effect \a parameter. You can fetch
2615     the available parameters for an effect with parameters().
2616
2617     \sa setParameterValue(), EffectParameter
2618 */
2619
2620 /*!
2621     \fn void Phonon::Effect::setParameterValue(const EffectParameter &parameter, const QVariant &value)
2622
2623     Sets the given effect \a parameter to the specified \a value.
2624
2625     Parameters for an effect are returned by parameters(). You can
2626     check which QVariant::Type an EffectParameter takes with the
2627     EffectParameter::type() function.
2628
2629     \sa parameterValue(), EffectParameter
2630 */
2631
2632 /*!
2633     \fn EffectDescription Phonon::Effect::description() const;
2634
2635     Returns the description of this effect. This is the same
2636     description that was passed to the constructor. 
2637 */
2638
2639 /*!
2640     \fn QList<EffectParameter> Phonon::Effect::parameters() const;
2641
2642     Returns a list of parameters that this effect provides to control
2643     its behavior.
2644
2645     \sa EffectParameter, EffectWidget
2646 */
2647
2648 /*!
2649     \class Phonon::EffectPrivate
2650     \inmodule Phonon
2651     \since 4.4
2652     \internal
2653 */
2654
2655 /*!
2656     \class Phonon::AudioOutput
2657     \inmodule Phonon
2658     \inheaderfile Phonon/AudioOutput
2659     \since 4.4
2660     \brief The AudioOutput class is used to send data to audio output devices.
2661
2662     The AudioOutput class plays sound over a sound device. The audio
2663     output needs to be connected to a \l{Phonon::}{MediaObject} using
2664     \l{Phonon::}{createPath()}. To start playback, you call
2665     \l{Phonon::MediaObject::}{play()} on the media object.
2666
2667     \snippet snippets/phonon.cpp 2
2668
2669     The class supports changing the volume(). It is also possible to
2670     mute the sound. 
2671
2672     To find out what \l{Phonon::}{AudioOutputDevice}s are available
2673     for AudioOutput, you can call
2674     BackendCapabilities::availableAudioOutputDevices(). A default device is
2675     selected by the backend, but it is possible to set the device to
2676     be used with setOutputDevice(). The outputDeviceChanged() signal
2677     will be emitted if the device changes.
2678
2679     If an error occurs with the playback, for instance, if no valid
2680     output device is found, the media object will receive a
2681     stateChanged() signal with the \l{Phonon::}{ErrorState}.
2682
2683     Note that the default values of properties are dependent on the
2684     backend.
2685
2686     \sa Phonon::VolumeSlider, {Music Player Example}, BackendCapabilities, {Phonon Module}
2687 */
2688
2689 /*!
2690     \property Phonon::AudioOutput::name
2691
2692     This is the name that appears in Mixer applications that control
2693     the volume of this output.
2694
2695 */
2696
2697 /*!
2698     \property Phonon::AudioOutput::volume
2699
2700     This is the current loudness of the output.  \omit The volume is a
2701     real value between 0.0 (minimum) and 1.0 (maximum). The volume
2702     follows the sound device used, with 1.0 being the maximum volume
2703     the device can produce. \endomit
2704
2705     (it is using Stevens' law
2706     to calculate the change in voltage internally).
2707
2708     \sa volumeDecibel
2709 */
2710
2711 /*!
2712     \property Phonon::AudioOutput::volumeDecibel
2713
2714     This is the current volume of the output in decibel.
2715
2716     0 dB means no change in volume, -6dB means an attenuation of the
2717     voltage to 50% and an attenuation of the power to 25%, -inf dB means
2718     silence.
2719
2720     \sa volume
2721 */
2722
2723 /*!
2724     \property Phonon::AudioOutput::outputDevice
2725     This property holds the (hardware) destination for the output.
2726
2727     The default device is determined by the \l{Phonon::}{Category} and the global
2728     configuration for that category. Normally you don't need
2729     to override this setting - letting the user change the global
2730     configuration is the right choice. You can still override the
2731     device though, if you have good reasons to do so.
2732
2733     \sa outputDeviceChanged()
2734 */
2735
2736 /*!
2737     \property Phonon::AudioOutput::muted
2738     This property tells whether the output is muted.
2739
2740     Muting the output has the same effect as calling setVolume(0.0).
2741 */
2742
2743 /*!
2744     \fn explicit Phonon::AudioOutput::AudioOutput(Phonon::Category category, QObject *parent = 0)
2745
2746     Creates a new AudioOutput with the given \a parent that defines
2747     output to a physical device.
2748
2749     The \a category can be used by mixer applications to group volume
2750     controls of applications into categories. That makes it easier for
2751     the user to identify the programs.
2752     The category is also used for the default output device that is
2753     configured centrally. As an example: often users want to have the
2754     audio signal of a VoIP application go to their USB headset while
2755     all other sounds should go to the internal soundcard.
2756
2757     \sa Phonon::categoryToString(), outputDevice
2758 */
2759
2760 /*!
2761     \fn explicit Phonon::AudioOutput::AudioOutput(QObject *parent = 0)
2762
2763     Creates a new AudioOutput that defines output to the system
2764     default device with the \{Phonon::Category::}{NoCategory} category
2765
2766     \sa Phonon::categoryToString(), outputDevice
2767 */
2768
2769 /*!
2770     \fn Phonon::Category Phonon::AudioOutput::category() const
2771
2772     Returns the category of this output.
2773
2774     \sa Phonon::AudioOutput::AudioOutput()
2775 */
2776
2777 /*!
2778     \fn void Phonon::AudioOutput::volumeChanged(qreal newVolume)
2779
2780     This signal is emitted whenever the volume has changed. As the
2781     volume can change without a call to setVolume (calls over dbus)
2782     this is important to keep a widget showing the current volume up
2783     to date.
2784
2785     \a newVolume is the new volume level.
2786
2787     \sa setVolume(), volume()
2788 */
2789
2790 /*!
2791     \fn void Phonon::AudioOutput::mutedChanged(bool muted)
2792
2793     This signal is emitted when the muted property has changed. The \a muted
2794     value passed by the signal indicates the state of the muted property.
2795     As this property can change by IPC (DBus) calls a UI element showing
2796     the muted property should listen to this signal.
2797 */
2798
2799 /*!
2800     \fn void Phonon::AudioOutput::outputDeviceChanged(const Phonon::AudioOutputDevice &newAudioOutputDevice)
2801
2802     This signal is emitted when the (hardware) device for the output
2803     has changed. \a newAudioOutputDevice is the new device.
2804
2805     The change can happen either through setOutputDevice or if the
2806     global configuration for the used category has changed.
2807
2808     \sa outputDevice
2809 */
2810
2811 /*!
2812     \class Phonon::AudioOutputPrivate
2813     \inmodule Phonon
2814     \since 4.4
2815     \internal
2816 */
2817
2818 /*!
2819     \class Phonon::EffectParameter
2820     \inmodule Phonon
2821     \inheaderfile Phonon/EffectParameter
2822     \since 4.4
2823     \brief The EffectParameter class describes one parameter of an effect.
2824
2825     You fetch the parameters of an \l{Phonon::}{Effect} with
2826     \l{Phonon::}{Effect::parameters()}.
2827
2828     \snippet doc/src/snippets/phononeffectparameter.cpp 0
2829
2830     To describe itself, an effect parameter gives a name() and
2831     possibly description() (depending on the backend used). These are
2832     suited to present the effect parameter to the user of a Phonon
2833     application.
2834
2835     Note that effects are created by the backend, and that
2836     their name and descriptions may vary.
2837
2838     The value of an effect parameter is stored in a \l{QVariant},
2839     of which type() is usually \c int or \c double. 
2840
2841     The value is retrieved with \l{Phonon::}{Effect::parameterValue()}
2842     and set with \l{Phonon::Effect::}{setParameterValue()} - both of
2843     which takes the EffectParameter as argument. Note that not all
2844     effect parameters support setting of their value. 
2845
2846     You get the values a parameter can take with possibleValues(); an
2847     empty list is returned if the values are continuous.
2848
2849     A parameter may also specify default(), minimum(), and maximum()
2850     values. Values are returned as \l{QVariant}s. If the parameter
2851     does not have the requested value, an \l{QVariant::Invalid}
2852     invalid QVariant is returned from these functions.
2853
2854     The \l{Phonon::}{EffectWidget} provides a widget with which one
2855     can control the parameters of an \l{Phonon::}{Effect}.
2856
2857     \snippet doc/src/snippets/phononeffectparameter.cpp 1
2858
2859     \sa Effect, EffectWidget, {Capabilities Example}, {Phonon Module}
2860 */
2861
2862 /*!
2863     \fn Phonon::EffectParameter::EffectParameter()
2864     \internal
2865
2866     Creates an invalid effect parameter.
2867 */
2868
2869 /*!
2870     \fn Phonon::EffectParameter::~EffectParameter()
2871
2872     Destroys the effect parameter.
2873 */
2874
2875 /*!
2876     \fn Phonon::EffectParameter::EffectParameter(const EffectParameter &other)
2877
2878     Constructs a copy of the \a other effect parameter.
2879 */
2880
2881 /*!
2882     \fn const QString &Phonon::EffectParameter::name() const
2883
2884     The name of the parameter. Can be used as the label.
2885
2886     \return A label for the parameter.
2887 */
2888
2889 /*!
2890     \fn const QString &Phonon::EffectParameter::description() const
2891
2892     The parameter may come with a description (LADSPA doesn't have a
2893     field for this, so don't expect many effects to provide a
2894     description).
2895
2896     The description can be used for a tooltip or WhatsThis help.
2897
2898     \return A text describing the parameter.
2899 */
2900
2901 /*!
2902     \fn QVariant::Type Phonon::EffectParameter::type() const
2903
2904     Returns the parameter type.
2905
2906     Common types are QVariant::Int, QVariant::Double, QVariant::Bool and QVariant::String. When
2907     QVariant::String is returned you get the possible values from possibleValues.
2908 */
2909
2910 /*!
2911     \fn bool Phonon::EffectParameter::isLogarithmicControl() const
2912
2913     Returns whether the parameter should be
2914     displayed using a logarithmic scale. This is particularly useful for
2915     frequencies and gains.
2916 */
2917
2918 /*!
2919     \fn QVariant Phonon::EffectParameter::minimumValue() const
2920
2921     The minimum value to be used for the control to edit the parameter.
2922
2923     If the returned QVariant is invalid the value is not bounded from
2924     below.
2925 */
2926
2927 /*!
2928     \fn QVariant Phonon::EffectParameter::maximumValue() const
2929
2930     The maximum value to be used for the control to edit the parameter.
2931
2932     If the returned QVariant is invalid the value is not bounded from
2933     above.
2934 */
2935
2936 /*!
2937     \fn QVariant Phonon::EffectParameter::defaultValue() const
2938
2939     The default value.
2940 */
2941
2942 /*!
2943     \fn QVariantList Phonon::EffectParameter::possibleValues() const
2944
2945     The possible values to be used for the control to edit the parameter.
2946
2947     if the value of this parameter is to be picked from predefined values
2948     this returns the list (otherwise it returns an empty QVariantList).
2949 */
2950
2951 /*!
2952     \fn bool Phonon::EffectParameter::operator<(const EffectParameter &rhs) const
2953
2954     \internal
2955     compares the ids of the parameters
2956 */
2957
2958 /*!
2959     \fn bool Phonon::EffectParameter::operator>(const EffectParameter &rhs) const
2960
2961     \internal
2962     compares the ids of the parameters
2963 */
2964
2965 /*!
2966     \fn bool Phonon::EffectParameter::operator==(const EffectParameter &rhs) const
2967
2968     \internal
2969     compares the ids of the parameters
2970 */
2971
2972 /*!
2973     \fn Phonon::EffectParameter &Phonon::EffectParameter::operator=(const EffectParameter &other)
2974
2975     Assigns the \a other effect parameter to this parameter and returns
2976     a reference to this parameter.
2977 */
2978
2979 /*!
2980     \enum Phonon::EffectParameter::Hint
2981
2982     Only for backend developers:
2983
2984     Flags to set the return values of isToggleControl(),
2985     isLogarithmicControl(), isIntegerControl(), isBoundedBelow() and
2986     isBoundedAbove(). The values of the flags correspond to the values
2987     used for LADSPA effects.
2988
2989     \value ToggledHint
2990     If this hint is set it means that
2991     the control has only two states: zero and non-zero
2992     (see isToggleControl()).
2993
2994     \value LogarithmicHint
2995     LADSPA's SAMPLE_RATE hint needs to be translated by the backend
2996     to normal bounds, as the backend knows the sample rate - and the
2997     frontend doesn't (see isLogarithmicControl()).
2998
2999     \value IntegerHint See isIntegerControl().
3000 */
3001
3002 /*!
3003     \fn Phonon::EffectParameter::EffectParameter(int parameterId,
3004         const QString &name, EffectParameter::Hints hints,
3005         const QVariant &defaultValue, const QVariant &min = QVariant(),
3006         const QVariant &max = QVariant(), const QVariantList &values = QVariantList(),
3007         const QString &description = QString())
3008
3009     Only to be used by backend implementations:
3010
3011     Creates a new effect parameter.
3012
3013     \a parameterId This is a number to uniquely identify the
3014     parameter. The id is used for value() and setValue().
3015
3016     \a name is the name/label for this parameter.
3017
3018     \a hints sets the hints for the type of parameter.
3019
3020     \a defaultValue The value that should be used as a default.
3021
3022     \a min is the minimum value allowed for this parameter. You only
3023     need to set this if the BoundedBelowHint is set.
3024
3025     \a max is the maximum value allowed for this parameter. You only
3026     need to set this if the BoundedAboveHint is set.
3027
3028     The \a values parameter is the values that the effect parameter
3029     can take (only applies if non-continuous) 
3030
3031     \a description is a descriptive text for the parameter
3032     (explaining what it controls) to be used as a tooltip or
3033     WhatsThis help.
3034 */
3035
3036 /*!
3037     \fn int Phonon::EffectParameter::id() const
3038
3039     \internal
3040
3041     Returns the parameter's identifier.
3042 */
3043
3044 /*!
3045    \typedef Phonon::AudioOutputInterface
3046    \inmodule Phonon
3047    \internal
3048 */
3049
3050 /*!
3051     \class Phonon::AudioOutputInterface40
3052     \inmodule Phonon
3053     \since 4.4
3054     \internal
3055     \brief Interface for AudioOutput objects
3056
3057 */
3058
3059 /*!
3060     \fn virtual Phonon::AudioOutputInterface40::~AudioOutputInterface40()
3061     \internal
3062 */
3063
3064 /*!
3065     \fn virtual qreal Phonon::AudioOutputInterface40::volume() const = 0
3066     \internal
3067 */
3068
3069 /*!
3070     \fn virtual void Phonon::AudioOutputInterface40::setVolume(qreal) = 0
3071     \internal
3072 */
3073
3074 /*!
3075     \fn virtual int Phonon::AudioOutputInterface40::outputDevice() const = 0
3076     \internal
3077 */
3078
3079 /*!
3080     \fn virtual bool Phonon::AudioOutputInterface40::setOutputDevice(int) = 0
3081     \internal
3082 */
3083
3084 /*!
3085     \class Phonon::Path
3086     \inmodule Phonon
3087     \inheaderfile Phonon/Path
3088     \since 4.4
3089     \brief The Path class describes connections between media nodes.
3090
3091     In a \l{Building Graphs}{media graph}, \l{Phonon::}{MediaNode}s
3092     are connected by Paths. The multimedia travels in streams over
3093     these paths.
3094
3095     You create a path between two media nodes using the static
3096     Phonon::createPath() function, which takes two nodes as arguments.
3097     The first argument will send the media stream to the second.
3098     Please refer to the class description of the individual media
3099     nodes and the Phonon \l{Phonon Overview}{overview} to see which
3100     nodes can be connected to each other.
3101
3102     Paths are also used to insert audio \l{Phonon::}{Effect}s between
3103     two media nodes. The effect will then alter the stream on the
3104     path. Notice that \l{Phonon::}{Effect}s also are media nodes, but
3105     that insertEffect() - instead of Phonon::createPath() - is used to
3106     insert them into the media graph.
3107
3108     The following code example shows how to create a path between two
3109     media nodes and insert an effect on that path.
3110
3111     \snippet doc/src/snippets/code/doc_src_phonon-api.cpp 20
3112
3113     \sa Phonon::MediaNode, Phonon::MediaObject, Phonon::AudioOutput,
3114         Phonon::VideoWidget, {Phonon Module}
3115 */
3116
3117 /*!
3118     \fn Phonon::Path::~Path();
3119
3120     Destroys this reference to the Path. If the path was valid the connection is not broken
3121     as both the source and the sink MediaNodes still keep a reference to the Path.
3122
3123     \sa disconnect()
3124 */
3125
3126 /*!
3127     \fn Phonon::Path::Path();
3128
3129     Creates an invalid path.
3130
3131     You can still make it a valid path by calling reconnect. It is
3132     recommended to use the Phonon::createPath() function to create
3133     paths.
3134
3135     \sa Phonon::createPath(), isValid()
3136 */
3137
3138 /*!
3139     \fn Phonon::Path::Path(const Path &path);
3140
3141     Constructs a copy of the other \a path specified.
3142
3143     This constructor is fast thanks to explicit sharing.
3144 */
3145
3146 /*!
3147     \fn bool Phonon::Path::isValid() const;
3148
3149     A path is considered valid if it is connected to two media nodes,
3150     in which case this function returns true. If it is connected to
3151     one or no media nodes, it is consider invalid, and this function
3152     will then return false.
3153 */
3154
3155 /*!
3156     \fn Effect *Phonon::Path::insertEffect(const EffectDescription &desc, Effect *insertBefore = 0);
3157
3158     Creates and inserts an effect into the path.
3159
3160     You may insert effects of the same class as often as you like,
3161     but if you insert the same object, the call will fail.
3162
3163     \a desc is the EffectDescription object for the effect to be inserted.
3164
3165     If you already inserted an effect you can
3166     tell with \a insertBefore in which order the data gets
3167     processed. If this is \c 0 the effect is appended at the end of
3168     the processing list. If the effect has not been inserted before
3169     the method will do nothing and return \c false.
3170
3171     Returns a pointer to the effect object if it could be inserted
3172     at the specified position. If \c 0 is returned, the effect was not
3173     inserted.
3174
3175     Below is a code example for inserting an effect into a path:
3176
3177     \snippet doc/src/snippets/audioeffects.cpp 0
3178
3179     \sa removeEffect(), effects()
3180 */
3181
3182 /*!
3183     \fn bool Phonon::Path::insertEffect(Effect *effect, Effect *insertBefore = 0);
3184
3185     Inserts the given \a effect into the path before the effect specified by \a insertBefore
3186     and returns true if successful; otherwise returns false.
3187
3188     If \a insertBefore is zero, the effect is appended to the processing list.
3189
3190     You may insert effects of the same class as often as you like, but if you insert
3191     the same object, the call will fail.
3192
3193     \a effect will be inserted right before \a insertBefore. If
3194     \a insertBefore is \c 0, the effect is appended at the end of the
3195     processing list. If the effect has not been inserted before the
3196     method will do nothing and return \c false.
3197
3198     Returns whether the effect could be inserted at the specified
3199     position. If \c false is returned the effect was not inserted.
3200
3201     \sa removeEffect(), effects()
3202 */
3203
3204 /*!
3205     \fn bool Phonon::Path::removeEffect(Effect *effect);
3206
3207     Removes the given \a effect from the path and returns true; otherwise returns false.
3208
3209     Removes an \a effect from the path.
3210
3211     If the effect is deleted while it is still connected, the effect will be removed
3212     automatically.
3213
3214     \omit
3215     \param effect The effect to be removed.
3216
3217     \return Returns whether the call was successful. If it returns
3218     \c false the effect could not be found in the path, meaning it
3219     has not been inserted before.
3220     \endomit
3221
3222     \sa insertEffect(), effects()
3223 */
3224
3225 /*!
3226     \fn QList<Effect *> Phonon::Path::effects() const;
3227
3228     Returns a list of Effect objects that are currently
3229     used as effects. The order in the list determines the order the
3230     signal is sent through the effects.
3231
3232     \return A list with all current effects.
3233
3234     \sa insertEffect(), removeEffect()
3235 */
3236
3237 /*!
3238     \fn bool Phonon::Path::reconnect(MediaNode *source, MediaNode *sink);
3239
3240     Changes the media nodes the path is connected to by connecting the path
3241     to the \a source and \a sink nodes specified. Returns true if successful;
3242     otherwise returns false.
3243
3244     If unsuccessful, the path remains connected to the same nodes as before.
3245
3246     \sa Phonon::createPath(), {Phonon Overview}
3247 */
3248
3249 /*!
3250     \fn bool Phonon::Path::disconnect();
3251
3252     Tries to disconnect the path from the MediaNodes it is connected to, returning
3253     true if successful or false if unsuccessful.
3254
3255     If successful, the path is invalidated: isValid() will returns false.
3256 */
3257
3258 /*!
3259     \fn Path &Phonon::Path::operator=(const Path &p);
3260
3261     Assigns \a p to this Path and returns a reference to this Path.
3262
3263     This operation is fast thanks to explicit sharing.
3264 */
3265
3266 /*!
3267     \fn bool Phonon::Path::operator==(const Path &p) const;
3268
3269     Returns true if this Path is equal to \a p; otherwise returns false;
3270 */
3271
3272 /*!
3273     \fn bool Phonon::Path::operator!=(const Path &p) const;
3274
3275     Returns true if this Path is not equal to \a p; otherwise returns false.
3276 */
3277
3278 /*!
3279     \fn MediaNode *Phonon::Path::source() const;
3280
3281     Returns the source MediaNode used by the path.
3282 */
3283
3284 /*!
3285     \fn MediaNode *Phonon::Path::sink() const;
3286
3287     Returns the sink MediaNode used by the path.
3288 */
3289
3290 /*!
3291     \fn Path Phonon::createPath(MediaNode *source, MediaNode *sink);
3292
3293     \relates Phonon::Path
3294     Creates a new Path connecting the two MediaNodes \a source and \a sink.
3295
3296     The implementation will automatically select the right format and media type. E.g. connecting a
3297     MediaObject and AudioOutput will create a Path object connecting the audio. This might be
3298     represented as PCM or perhaps even AC3 depending on the AudioOutput object.
3299
3300     \param source The MediaNode to connect an output from
3301     \param sink The MediaNode to connect to.
3302 */
3303
3304 /*!
3305     \class Phonon::PathPrivate
3306     \inmodule Phonon
3307     \since 4.4
3308     \internal
3309 */
3310
3311 /*!
3312     \class Phonon::MediaObjectInterface
3313     \inmodule Phonon
3314     \since 4.4
3315     \internal
3316     \brief Backend interface for media sources.
3317
3318     The backend implementation has to provide two signals, that are not defined
3319     in this interface:
3320     \list
3321     \o \target phonon_MediaObjectInterface_stateChanged
3322     void stateChanged(Phonon::State newstate, Phonon::State oldstate)
3323
3324     Emitted when the state of the MediaObject has changed.
3325     In case you're not interested in the old state you can also
3326     connect to a slot that only has one State argument.
3327
3328     \param newstate The state the Player is in now.
3329     \param oldstate The state the Player was in before.
3330
3331     \o \target phonon_MediaObjectInterface_tick
3332     void tick(qint64 time)
3333
3334     This signal gets emitted every tickInterval milliseconds.
3335
3336     \param time The position of the media file in milliseconds.
3337
3338     \sa setTickInterval()
3339     \sa tickInterval()
3340     \endlist
3341
3342     \sa MediaObject
3343 */
3344
3345 /*!
3346     \fn virtual Phonon::MediaObjectInterface::~MediaObjectInterface()
3347     \internal
3348 */
3349
3350 /*!
3351     \fn virtual qint64 Phonon::MediaObjectInterface::remainingTime() const
3352     \internal
3353 */
3354
3355 /*!
3356     \fn virtual qint32 Phonon::MediaObjectInterface::prefinishMark() const = 0
3357     \internal
3358 */
3359
3360 /*!
3361     \fn virtual void Phonon::MediaObjectInterface::setPrefinishMark(qint32) = 0
3362     \internal
3363 */
3364
3365 /*!
3366     \fn virtual qint32 Phonon::MediaObjectInterface::transitionTime() const = 0
3367     \internal
3368 */
3369
3370 /*!
3371     \fn virtual void Phonon::MediaObjectInterface::setTransitionTime(qint32) = 0
3372     \internal
3373 */
3374
3375 /*!
3376     \fn virtual void Phonon::MediaObjectInterface::play() = 0
3377     \internal
3378
3379     Requests the playback to start.
3380
3381     This method is only called if the state transition to PlayingState is possible.
3382
3383     The backend should react immediately
3384     by either going into PlayingState or BufferingState if the
3385     former is not possible.
3386 */
3387
3388 /*!
3389     \fn virtual void Phonon::MediaObjectInterface::pause() = 0
3390     \internal
3391
3392     Requests the playback to pause.
3393
3394     This method is only called if the state transition to PausedState is possible.
3395
3396     The backend should react as fast as possible. Go to PausedState
3397     as soon as playback is paused.
3398 */
3399
3400 /*!
3401     \fn virtual void Phonon::MediaObjectInterface::stop() = 0
3402     \internal
3403
3404     Requests the playback to be stopped.
3405
3406     This method is only called if the state transition to StoppedState is possible.
3407
3408     The backend should react as fast as possible. Go to StoppedState
3409     as soon as playback is stopped.
3410
3411     A subsequent call to play() will start playback at the beginning of
3412     the media.
3413 */
3414
3415 /*!
3416     \fn virtual void Phonon::MediaObjectInterface::seek(qint64 milliseconds) = 0
3417     \internal
3418
3419     Requests the playback to be seeked to the given time.
3420
3421     The backend does not have to finish seeking while in this function
3422     (i.e. the backend does not need to block the thread until the seek is
3423     finished; even worse it might lead to deadlocks when using a
3424     ByteStream which gets its data from the thread this function would
3425     block).
3426
3427     As soon as the seek is done the currentTime() function and
3428     the tick() signal will report it.
3429
3430     \param milliseconds The time where playback should seek to in
3431     milliseconds.
3432 */
3433
3434 /*!
3435     \fn virtual qint32 Phonon::MediaObjectInterface::tickInterval() const = 0
3436     \internal
3437
3438     Return the time interval in milliseconds between two ticks.
3439
3440     Returns the tick interval that it was set to (might not
3441     be the same as you asked for).
3442 */
3443
3444 /*!
3445     \fn virtual void Phonon::MediaObjectInterface::setTickInterval(qint32 interval) = 0
3446     \internal
3447
3448     Change the interval the tick signal is emitted. Set \a interval to 0 to
3449     disable the signal.
3450
3451     \a interval tick interval in milliseconds
3452
3453     Returns the tick interval that it was set to (might not be the same as you
3454     asked for).
3455
3456 */
3457
3458 /*!
3459     \fn virtual bool Phonon::MediaObjectInterface::hasVideo() const = 0
3460     \internal
3461
3462     Check whether the media data includes a video stream.
3463
3464     Returns true if the media contains video data.
3465 */
3466
3467 /*!
3468     \fn virtual bool Phonon::MediaObjectInterface::isSeekable() const = 0
3469     \internal
3470
3471     If the current media may be seeked this function returns true;
3472     otherwise, false.
3473
3474     Returns whether the current media may be seeked.
3475 */
3476
3477 /*!
3478     \fn virtual qint64 Phonon::MediaObjectInterface::currentTime() const = 0
3479     \internal
3480
3481     Get the current time (in milliseconds) of the file currently being played.
3482 */
3483
3484 /*!
3485     \fn virtual Phonon::State Phonon::MediaObjectInterface::state() const = 0
3486     \internal
3487
3488     Get the current state.
3489 */
3490
3491 /*!
3492     \fn virtual QString Phonon::MediaObjectInterface::errorString() const = 0
3493     \internal
3494
3495     A translated string describing the error.
3496 */
3497
3498 /*!
3499     \fn virtual Phonon::ErrorType Phonon::MediaObjectInterface::errorType() const = 0
3500     \internal
3501
3502     Tells your program what to do about the error.
3503
3504     \sa Phonon::ErrorType
3505 */
3506
3507 /*!
3508     \fn virtual qint64 Phonon::MediaObjectInterface::totalTime() const = 0
3509     \internal
3510
3511     Returns the total time of the media in milliseconds.
3512
3513     If the total time is not know return -1. Do not block until it is
3514     known, instead emit the totalTimeChanged signal as soon as the total
3515     time is known or changes.
3516 */
3517
3518 /*!
3519     \fn virtual MediaSource Phonon::MediaObjectInterface::source() const = 0
3520     \internal
3521
3522     Returns the current source.
3523 */
3524
3525 /*!
3526     \fn virtual void Phonon::MediaObjectInterface::setSource(const MediaSource &) = 0
3527     \internal
3528
3529     Sets the current source. When this function is called the MediaObject is
3530     expected to stop all current activity and start loading the new
3531     source (i.e. go into LoadingState).
3532
3533     It is expected that the
3534     backend now starts preloading the media data, filling the audio
3535     and video buffers and making all media meta data available. It
3536     will also trigger the totalTimeChanged signal.
3537
3538     If the backend does not know how to handle the source it needs to
3539     change state to Phonon::ErrorState. Don't bother about handling KIO
3540     URLs. It is enough to handle AbstractMediaStream sources correctly.
3541
3542     \warning Keep the MediaSource object around as long as the backend
3543     uses the AbstractMediaStream returned by the MediaSource. In case
3544     that no other reference to the MediaSource exists and it is set to
3545     MediaSource::autoDelete, the AbstractMediaStream is deleted when the
3546     last MediaSource ref is deleted.
3547 */
3548
3549 /*!
3550     \fn virtual void Phonon::MediaObjectInterface::setNextSource(const MediaSource &source) = 0
3551     \internal
3552
3553     Sets the next source to be used for transitions. When a next source
3554     is set playback should continue with the new source. In that case
3555     finished and prefinishMarkReached are not emitted.
3556
3557     \param source The source to transition to (crossfade/gapless/gap). If
3558     \a source is an invalid MediaSource object then the queue is empty
3559     and the playback should stop normally.
3560
3561     \warning Keep the MediaSource object around as long as the backend
3562     uses the AbstractMediaStream returned by the MediaSource. In case
3563     that no other reference to the MediaSource exists and it is set to
3564     MediaSource::autoDelete, the AbstractMediaStream is deleted when the
3565     last MediaSource ref is deleted.
3566 */
3567
3568 /*!
3569     \class Phonon::EffectWidget effectwidget.h Phonon/EffectWidget
3570     \inmodule Phonon
3571     \inheaderfile Phonon/EffectWidget
3572     \since 4.4
3573     \brief The EffectWidget class provides a widget to control the parameters of an Effect.
3574
3575     The EffectWidget class provides a widget, with which an effects
3576     parameters can be controlled. The widget does not have an API,
3577     and is constructed with the \l{Phonon::}{Effect}, of which
3578     parameters should be controlled.
3579
3580     \snippet doc/src/snippets/audioeffects.cpp 1
3581
3582     The following image shows an example of an effect widget.
3583
3584     \image effectwidget.png
3585
3586     Note that some audio effects do not have parameters, and the
3587     widget will then not \l{QWidget::}{show()} at all.
3588
3589     \sa Effect, BackendCapabilities, EffectDescription, {Phonon Module}
3590 */
3591
3592 /*!
3593     \class Phonon::AbstractAudioOutput
3594     \inmodule Phonon
3595     \internal
3596     \brief Provides a common base class for all audio outputs.
3597
3598     \sa AudioOutput
3599 */
3600
3601 /*!
3602     \fn Phonon::AbstractAudioOutput::~AbstractAudioOutput()
3603     \internal
3604 */
3605
3606 /*!
3607     \class Phonon::AbstractAudioOutputPrivate
3608     \inmodule Phonon
3609     \since 4.4
3610     \internal
3611 */
3612
3613 /*!
3614     \class AudioOutputAdaptor
3615     \inmodule Phonon
3616     \brief Provides an adaptor class for interface org.kde.Phonon.AudioOutput
3617     \internal
3618 */
3619
3620 /*!
3621     \class Phonon::VolumeSlider
3622     \inmodule Phonon
3623     \inheaderfile Phonon/VolumeSlider
3624     \since 4.4
3625     \brief The VolumeSlider widget provides a slider that is used to control the volume of an audio output device.
3626
3627     The slider also displays an icon indicating if the volume of the
3628     \l{Phonon::}{AudioOutput} it is connected to is muted. The icon
3629     can be removed with setMuteVisible().
3630
3631     It is possible to set the \l{maximumVolume}{maximum} value of the
3632     slider. By default, the minimum and maximum values of the slider
3633     are 0.0 (no sound) to 1.0 (the maximum volume the audio output can
3634     produce).
3635
3636     Here follows a code example:
3637
3638     \snippet doc/src/snippets/volumeslider.cpp 0
3639
3640     \omit mention how to change the style of the slider. \endomit
3641
3642     \sa {Phonon Module}
3643 */
3644
3645 /*!
3646     \property Phonon::VolumeSlider::maximumVolume
3647
3648     This property holds the maximum volume that can be set with this slider.
3649
3650     By default the maximum value is 1.0 (100%).
3651 */
3652
3653 /*!
3654     \property Phonon::VolumeSlider::orientation
3655     This property holds the orientation of the slider.
3656
3657     The orientation must be Qt::Vertical (the default) or Qt::Horizontal.
3658 */
3659
3660 /*!
3661     \property Phonon::VolumeSlider::tracking
3662     This property holds whether slider tracking is enabled.
3663
3664     If tracking is enabled (the default), the volume changes
3665     while the slider is being dragged. If tracking is
3666     disabled, the volume changes only when the user
3667     releases the slider.
3668 */
3669
3670 /*!
3671     \property Phonon::VolumeSlider::pageStep
3672     This property holds the page step.
3673
3674     The larger of two natural steps that a slider provides and
3675     typically corresponds to the user pressing PageUp or PageDown.
3676
3677     Defaults to 5 (5% of the voltage).
3678 */
3679
3680 /*!
3681     \property Phonon::VolumeSlider::singleStep
3682     This property holds the single step.
3683
3684     The smaller of two natural steps that a slider provides and
3685     typically corresponds to the user pressing an arrow key.
3686
3687     Defaults to 1 (1% of the voltage).
3688 */
3689
3690 /*!
3691     \property Phonon::VolumeSlider::muteVisible
3692     This property holds whether the mute button/icon next to the slider is visible.
3693
3694     By default the mute button/icon is visible.
3695 */
3696
3697 /*!
3698     \property Phonon::VolumeSlider::iconSize
3699     \brief the icon size used for the mute button/icon.
3700
3701     The default size is defined by the GUI style.
3702 */
3703
3704 /*!
3705     \fn explicit Phonon::VolumeSlider::VolumeSlider(QWidget *parent = 0)
3706     Constructs a new volume slider with the given \a parent.
3707 */
3708
3709 /*!
3710     \fn explicit Phonon::VolumeSlider::VolumeSlider(AudioOutput *output, QWidget *parent = 0)
3711     Constructs a new volume slider with the given \a output object and \a parent.
3712 */
3713
3714 /*!
3715     \fn Phonon::VolumeSlider::~VolumeSlider()
3716 */
3717
3718 /*!
3719     \fn AudioOutput *Phonon::VolumeSlider::audioOutput() const
3720 */
3721
3722 /*!
3723     \fn void Phonon::VolumeSlider::setAudioOutput(Phonon::AudioOutput *output)
3724
3725     Sets the audio output object to be controlled by this slider to the specified
3726     \a output object.
3727 */
3728
3729 /*!
3730     \class Phonon::VolumeSliderPrivate
3731     \inmodule Phonon
3732     \since 4.4
3733     \internal
3734 */
3735
3736 /*!
3737     \class Phonon::MediaController
3738     \inmodule Phonon
3739     \inheaderfile Phonon/MediaController
3740     \since 4.4
3741     \brief The MediaController class controls optional features of a media file/device.
3742
3743     Some media sources have content that the \l{Phonon::}{MediaObject}
3744     does not provide control over, for instance, chapters in a DVD
3745     file. The functionality the media controller offers is
3746     dependent on the type of media source that is played back.
3747     Commonly, the media controller allows you to:
3748
3749     \list
3750         \o Navigate between \bold chapters.
3751         \o Navigate between \bold titles.
3752         \o Select between \bold angles.
3753     \endlist 
3754
3755     The \l{Phonon::MediaController::}{Feature} enum explains these
3756     terms in more detail, and their context in playback of CD and DVD. 
3757
3758     The media controller keeps a \l{Phonon::}{MediaObject}, of which
3759     \l{Phonon::MediaObject::currentSource()}{media source} is played
3760     back. You can still call the media object's functions, e.g.,
3761     \l{Phonon::MediaObject::}{stop()}; this is all handled correctly
3762     by the media controller. You have the option of letting the media
3763     controller play all titles of a source in sequence by setting the
3764     \l{autoplayTitles()}{autoplay titles} option.
3765
3766     To start a playback using a media object, you call