Update QML media element documentation.

2 files changed, 628 insertions, 54 deletions

diff --git a/src/multimedia/qml/qmlaudio.cpp b/src/multimedia/qml/qmlaudio.cpp
index f56b6c3..fc340d0 100644
--- a/src/multimedia/qml/qmlaudio.cpp
+++ b/src/multimedia/qml/qmlaudio.cpp
@@ -49,13 +49,19 @@ QML_DEFINE_TYPE(Qt,4,6,Audio,QmlAudio);
 
 /*!
     \qmlclass Audio QmlAudio
-    \brief The Audio element allows you to add audio to a scene.
+    \brief The Audio element allows you to add audio playback to a scene.
+
+    \qml
+    Audio { source: "audio/song.mp3" }
+    \endqml
+
+    \sa Video
 */
 
 /*!
     \internal
     \class QmlAudio
-    \brief The QmlAudio class provides a audio item that you can add to a QmlView.
+    \brief The QmlAudio class provides an audio item that you can add to a QmlView.
 */
 
 void QmlAudio::_q_error(int errorCode, const QString &errorString)
@@ -82,7 +88,9 @@ QmlAudio::~QmlAudio()
 /*!
     \qmlmethod Audio::play()
 
-    Starts playback of the audio.
+    Starts playback of the media.
+
+    Sets the \l playing property to true, and the \l paused property to false.
 */
 
 void QmlAudio::play()
@@ -98,7 +106,9 @@ void QmlAudio::play()
 /*!
     \qmlmethod Audio::pause()
 
-    Pauses playback of the audio.
+    Pauses playback of the media.
+
+    Sets the \l playing and \l paused properties to true.
 */
 
 void QmlAudio::pause()
@@ -114,7 +124,9 @@ void QmlAudio::pause()
 /*!
     \qmlmethod Audio::stop()
 
-    Stops playback of the audio.
+    Stops playback of the media.
+
+    Sets the \l playing and \l paused properties to false.
 */
 
 void QmlAudio::stop()
@@ -130,19 +142,23 @@ void QmlAudio::stop()
 /*!
     \qmlproperty url Audio::source
 
-    This property holds the source URL of the audio.
+    This property holds the source URL of the media.
 */
 
 /*!
     \qmlproperty bool Audio::playing
 
-    This property holds whether the audio is playing.
+    This property holds whether the media is playing.
+
+    Defaults to false, and can be set to true to start playback.
 */
 
 /*!
     \qmlproperty bool Audio::paused
 
-    This property holds whether the audio is paused.
+    This property holds whether the media is paused.
+
+    Defaults to false, and can be set to true to pause playback.
 */
 
 /*!
@@ -172,18 +188,18 @@ void QmlAudio::stop()
 /*!
     \qmlproperty enum Audio::status
 
-    This property holds the status of audio loading. It can be one of:
+    This property holds the status of media loading. It can be one of:
 
     \list
-    \o NoMedia - no audio has been set.
-    \o Loading - the audio is currently being loaded.
-    \o Loaded - the audio has been loaded.
-    \o Buffering - the audio is buffering data.
-    \o Stalled - playback has been interrupted while the audio is buffering data.
-    \o Buffered - the audio has buffered data.
-    \o EndOfMedia - the audio has played to the end.
-    \o InvalidMedia - the audio cannot be played.
-    \o UnknownStatus - the status of the audio is unknown.
+    \o NoMedia - no media has been set.
+    \o Loading - the media is currently being loaded.
+    \o Loaded - the media has been loaded.
+    \o Buffering - the media is buffering data.
+    \o Stalled - playback has been interrupted while the media is buffering data.
+    \o Buffered - the media has buffered data.
+    \o EndOfMedia - the media has played to the end.
+    \o InvalidMedia - the media cannot be played.
+    \o UnknownStatus - the status of the media is unknown.
     \endlist
 */
 
@@ -195,44 +211,46 @@ QmlAudio::Status QmlAudio::status() const
 /*!
     \qmlsignal Audio::onLoaded()
 
-    This handler is called when the video source has been loaded.
+    This handler is called when the media source has been loaded.
 */
 
 /*!
     \qmlsignal Audio::onBuffering()
 
-    This handler is called when the video stream starts buffering.
+    This handler is called when the media  starts buffering.
 */
 
 /*!
     \qmlsignal Audio::onStalled()
 
-    This handler is called when playback has stalled while the video stream buffers.
+    This handler is called when playback has stalled while the media buffers.
 */
 
 /*!
     \qmlsignal Audio::onBuffered()
 
-    This handler is called when the video stream has finished buffering.
+    This handler is called when the media has finished buffering.
 */
 
 /*!
-    \qmlsignal Audio::onEndOfMedia
+    \qmlsignal Audio::onEndOfMedia()
 
-    This handler is called when playback stops because end of the video has been reached.
+    This handler is called when playback stops because end of the media has been reached.
 */
 /*!
     \qmlproperty int Audio::duration
 
-    This property holds the duration of the audio in milliseconds.
+    This property holds the duration of the media in milliseconds.
 
-    If the audio doesn't have a fixed duration (a live stream for example) this will be 0.
+    If the media doesn't have a fixed duration (a live stream for example) this will be 0.
 */
 
 /*!
     \qmlproperty int Audio::position
 
     This property holds the current playback position in milliseconds.
+
+    If the \l seekable property is true, this property can be set to seek to a new position.
 */
 
 /*!
@@ -258,6 +276,8 @@ QmlAudio::Status QmlAudio::status() const
     \qmlproperty bool Audio::seekable
 
     This property holds whether position of the audio can be changed.
+
+    If true; setting a \l position value will cause playback to seek to the new position.
 */
 
 /*!
diff --git a/src/multimedia/qml/qmlgraphicsvideo.cpp b/src/multimedia/qml/qmlgraphicsvideo.cpp
index f6a5eff..236387e 100644
--- a/src/multimedia/qml/qmlgraphicsvideo.cpp
+++ b/src/multimedia/qml/qmlgraphicsvideo.cpp
@@ -73,6 +73,18 @@ void QmlGraphicsVideo::_q_error(int errorCode, const QString &errorString)
     \qmlclass Video QmlGraphicsVideo
     \brief The Video element allows you to add videos to a scene.
     \inherits Item
+
+    \qml
+    Video { source: "video/movie.mpg" }
+    \endqml
+
+    The video item supports untransformed, stretched, and uniformly scaled video presentation.
+    For a description of stretched uniformly scaled presentation, see the \l fillMode property
+    description.
+
+    The video item is only visible when the \l hasVideo property is true and the video is playing.
+
+    \sa Audio
 */
 
 /*!
@@ -112,19 +124,23 @@ QmlGraphicsVideo::~QmlGraphicsVideo()
 /*!
     \qmlproperty url Video::source
 
-    This property holds the source URL of the video.
+    This property holds the source URL of the media.
 */
 
 /*!
     \qmlproperty bool Video::playing
 
-    This property holds whether the video is playing.
+    This property holds whether the media is playing.
+
+    Defaults to false, and can be set to true to start playback.
 */
 
 /*!
     \qmlproperty bool Video::paused
 
-    This property holds whether the video is paused.
+    This property holds whether the media is paused.
+
+    Defaults to false, and can be set to true to pause playback.
 */
 
 /*!
@@ -154,18 +170,18 @@ QmlGraphicsVideo::~QmlGraphicsVideo()
 /*!
     \qmlproperty enum Video::status
 
-    This property holds the status of video loading. It can be one of:
+    This property holds the status of media loading. It can be one of:
 
     \list
-    \o NoMedia - no video has been set.
-    \o Loading - the video is currently being loaded.
-    \o Loaded - the video has been loaded.
-    \o Buffering - the video is buffering data.
-    \o Stalled - playback has been interrupted while the video is buffering data.
-    \o Buffered - the video has buffered data.
-    \o EndOfMedia - the video has played to the end.
-    \o InvalidMedia - the video cannot be played.
-    \o UnknownStatus - the status of the video is unknown.
+    \o NoMedia - no media has been set.
+    \o Loading - the media is currently being loaded.
+    \o Loaded - the media has been loaded.
+    \o Buffering - the media is buffering data.
+    \o Stalled - playback has been interrupted while the media is buffering data.
+    \o Buffered - the media has buffered data.
+    \o EndOfMedia - the media has played to the end.
+    \o InvalidMedia - the media cannot be played.
+    \o UnknownStatus - the status of the media is cannot be determined.
     \endlist
 */
 
@@ -177,39 +193,39 @@ QmlGraphicsVideo::Status QmlGraphicsVideo::status() const
 /*!
     \qmlsignal Video::onLoaded()
 
-    This handler is called when the video source has been loaded.
+    This handler is called when the media source has been loaded.
 */
 
 /*!
     \qmlsignal Video::onBuffering()
 
-    This handler is called when the video stream starts buffering.
+    This handler is called when the media starts buffering.
 */
 
 /*!
     \qmlsignal Video::onStalled()
 
-    This handler is called when playback has stalled while the video stream buffers.
+    This handler is called when playback has stalled while the media buffers.
 */
 
 /*!
     \qmlsignal Video::onBuffered()
 
-    This handler is called when the video stream has finished buffering.
+    This handler is called when the media has finished buffering.
 */
 
 /*!
-    \qmlsignal Video::onEndOfMedia
+    \qmlsignal Video::onEndOfMedia()
 
-    This handler is called when playback stops because end of the video has been reached.
+    This handler is called when playback stops because end of the media has been reached.
 */
 
 /*!
     \qmlproperty int Video::duration
 
-    This property holds the duration of the video in milliseconds.
+    This property holds the duration of the media in milliseconds.
 
-    If the video doesn't have a fixed duration (a live stream for example) this will be 0.
+    If the media doesn't have a fixed duration (a live stream for example) this will be 0.
 */
 
 /*!
@@ -231,9 +247,9 @@ QmlGraphicsVideo::Status QmlGraphicsVideo::status() const
 */
 
 /*!
-    \qmlproperty bool Audio::hasAudio
+    \qmlproperty bool Video::hasAudio
 
-    This property holds whether the source contains audio.
+    This property holds whether the media contains audio.
 */
 
 bool QmlGraphicsVideo::hasAudio() const
@@ -244,7 +260,7 @@ bool QmlGraphicsVideo::hasAudio() const
 /*!
     \qmlproperty bool Video::hasVideo
 
-    This property holds whether the source contains video.
+    This property holds whether the media contains video.
 */
 
 bool QmlGraphicsVideo::hasVideo() const
@@ -307,7 +323,7 @@ QmlGraphicsVideo::Error QmlGraphicsVideo::error() const
 */
 
 /*!
-    \qmlproperty enum Video::FillMode
+    \qmlproperty enum Video::fillMode
 
     Set this property to define how the video is scaled to fit the target area.
 
@@ -316,6 +332,8 @@ QmlGraphicsVideo::Error QmlGraphicsVideo::error() const
     \o PreserveAspectFit - the video is scaled uniformly to fit without cropping
     \o PreserveAspectCrop - the video is scaled uniformly to fill, cropping if necessary
     \endlist
+
+    The default fill mode is PreserveAspectFit.
 */
 
 QmlGraphicsVideo::FillMode QmlGraphicsVideo::fillMode() const
@@ -331,7 +349,9 @@ void QmlGraphicsVideo::setFillMode(FillMode mode)
 /*!
     \qmlmethod Video::play()
 
-    Starts playback of the video.
+    Starts playback of the media.
+
+    Sets the \l playing property to true, and the \l paused property to false.
 */
 
 void QmlGraphicsVideo::play()
@@ -347,7 +367,9 @@ void QmlGraphicsVideo::play()
 /*!
     \qmlmethod Video::pause()
 
-    Pauses playback of the video.
+    Pauses playback of the media.
+
+    Sets the \l playing and \l paused properties to true.
 */
 
 void QmlGraphicsVideo::pause()
@@ -363,7 +385,9 @@ void QmlGraphicsVideo::pause()
 /*!
     \qmlmethod Video::stop()
 
-    Stops playback of the video.
+    Stops playback of the media.
+
+    Sets the \l playing and \l paused properties to false.
 */
 
 void QmlGraphicsVideo::stop()
@@ -389,4 +413,534 @@ void QmlGraphicsVideo::geometryChanged(const QRectF &newGeometry, const QRectF &
 
 QT_END_NAMESPACE
 
+// ***************************************
+// Documentation for meta-data properties.
+// ***************************************
+
+/*!
+    \qmlproperty variant Video::title
+
+    This property holds the tile of the media.
+
+    \sa {QtMedia::Title}
+*/
+
+/*!
+    \qmlproperty variant Video::subTitle
+
+    This property holds the sub-title of the media.
+
+    \sa {QtMedia::SubTitle}
+*/
+
+/*!
+    \qmlproperty variant Video::author
+
+    This property holds the author of the media.
+
+    \sa {QtMedia::Author}
+*/
+
+/*!
+    \qmlproperty variant Video::comment
+
+    This property holds a user comment about the media.
+
+    \sa {QtMedia::Comment}
+*/
+
+/*!
+    \qmlproperty variant Video::description
+
+    This property holds a description of the media.
+
+    \sa {QtMedia::Description}
+*/
+
+/*!
+    \qmlproperty variant Video::category
+
+    This property holds the category of the media
+
+    \sa {QtMedia::Category}
+*/
+
+/*!
+    \qmlproperty variant Video::genre
+
+    This property holds the genre of the media.
+
+    \sa {QtMedia::Genre}
+*/
+
+/*!
+    \qmlproperty variant Video::year
+
+    This property holds the year of release of the media.
+
+    \sa {QtMedia::Year}
+*/
+
+/*!
+    \qmlproperty variant Video::date
+
+    This property holds the date of the media.
+
+    \sa {QtMedia::Date}
+*/
+
+/*!
+    \qmlproperty variant Video::userRating
+
+    This property holds a user rating of the media in the range of 0 to 100.
+
+    \sa {QtMedia::UserRating}
+*/
+
+/*!
+    \qmlproperty variant Video::keywords
+
+    This property holds a list of keywords describing the media.
+
+    \sa {QtMedia::Keywords}
+*/
+
+/*!
+    \qmlproperty variant Video::language
+
+    This property holds the language of the media, as an ISO 639-2 code.
+
+    \sa {QtMedia::Language}
+*/
+
+/*!
+    \qmlproperty variant Video::publisher
+
+    This property holds the publisher of the media.
+
+    \sa {QtMedia::Publisher}
+*/
+
+/*!
+    \qmlproperty variant Video::copyright
+
+    This property holds the media's copyright notice.
+
+    \sa {QtMedia::Copyright}
+*/
+
+/*!
+    \qmlproperty variant Video::parentalRating
+
+    This property holds the parental rating of the media.
+
+    \sa {QtMedia::ParentalRating}
+*/
+
+/*!
+    \qmlproperty variant Video::ratingOrganisation
+
+    This property holds the name of the rating organisation responsible for the
+    parental rating of the media.
+
+    \sa {QtMedia::RatingOrganisation}
+*/
+
+/*!
+    \qmlproperty variant Video::size
+
+    This property property holds the size of the media in bytes.
+
+    \sa {QtMedia::Size}
+*/
+
+/*!
+    \qmlproperty variant Video::mediaType
+
+    This property holds the type of the media.
+
+    \sa {QtMedia::MediaType}
+*/
+
+/*!
+    \qmlproperty variant Video::audioBitRate
+
+    This property holds the bit rate of the media's audio stream ni bits per
+    second.
+
+    \sa {QtMedia::AudioBitRate}
+*/
+
+/*!
+    \qmlproperty variant Video::audioCodec
+
+    This property holds the encoding of the media audio stream.
+
+    \sa {QtMedia::AudioCodec}
+*/
+
+/*!
+    \qmlproperty variant Video::averageLevel
+
+    This property holds the average volume level of the media.
+
+    \sa {QtMedia::AverageLevel}
+*/
+
+/*!
+    \qmlproperty variant Video::channelCount
+
+    This property holds the number of channels in the media's audio stream.
+
+    \sa {QtMedia::ChannelCount}
+*/
+
+/*!
+    \qmlproperty variant Video::peakValue
+
+    This property holds the peak volume of media's audio stream.
+
+    \sa {QtMedia::PeakValue}
+*/
+
+/*!
+    \qmlproperty variant Video::sampleRate
+
+    This property holds the sample rate of the media's audio stream in hertz.
+
+    \sa {QtMedia::SampleRate}
+*/
+
+/*!
+    \qmlproperty variant Video::albumTitle
+
+    This property holds the title of the album the media belongs to.
+
+    \sa {QtMedia::AlbumTitle}
+*/
+
+/*!
+    \qmlproperty variant Video::albumArtist
+
+    This property holds the name of the principal artist of the album the media
+    belongs to.
+
+    \sa {QtMedia::AlbumArtist}
+*/
+
+/*!
+    \qmlproperty variant Video::contributingArtist
+
+    This property holds the names of artists contributing to the media.
+
+    \sa {QtMedia::ContributingArtist}
+*/
+
+/*!
+    \qmlproperty variant Video::composer
+
+    This property holds the composer of the media.
+
+    \sa {QtMedia::Composer}
+*/
+
+/*!
+    \qmlproperty variant Video::conductor
+
+    This property holds the conductor of the media.
+
+    \sa {QtMedia::Conductor}
+*/
+
+/*!
+    \qmlproperty variant Video::lyrics
+
+    This property holds the lyrics to the media.
+
+    \sa {QtMedia::Lyrics}
+*/
+
+/*!
+    \qmlproperty variant Video::mood
+
+    This property holds the mood of the media.
+
+    \sa {QtMedia::Mood}
+*/
+
+/*!
+    \qmlproperty variant Video::trackNumber
+
+    This property holds the track number of the media.
+
+    \sa {QtMedia::TrackNumber}
+*/
+
+/*!
+    \qmlproperty variant Video::trackCount
+
+    This property holds the number of track on the album containing the media.
+
+    \sa {QtMedia::TrackNumber}
+*/
+
+/*!
+    \qmlproperty variant Video::coverArtUrlSmall
+
+    This property holds the URL of a small cover art image.
+
+    \sa {QtMedia::CoverArtUrlSmall}
+*/
+
+/*!
+    \qmlproperty variant Video::coverArtUrlLarge
+
+    This property holds the URL of a large cover art image.
+
+    \sa {QtMedia::CoverArtUrlLarge}
+*/
+
+/*!
+    \qmlproperty variant Video::resolution
+
+    This property holds the dimension of an image or video.
+
+    \sa {QtMedia::Resolution}
+*/
+
+/*!
+    \qmlproperty variant Video::pixelAspectRatio
+
+    This property holds the pixel aspect ratio of an image or video.
+
+    \sa {QtMedia::PixelAspectRatio}
+*/
+
+/*!
+    \qmlproperty variant Video::videoFrameRate
+
+    This property holds the frame rate of the media's video stream.
+
+    \sa {QtMedia::VideoFrameRate}
+*/
+
+/*!
+    \qmlproperty variant Video::videoBitRate
+
+    This property holds the bit rate of the media's video stream in bits per
+    second.
+
+    \sa {QtMedia::VideoBitRate}
+*/
+
+/*!
+    \qmlproperty variant Video::videoCodec
+
+    This property holds the encoding of the media's video stream.
+
+    \sa {QtMedia::VideoCodec}
+*/
+
+/*!
+    \qmlproperty variant Video::posterUrl
+
+    This property holds the URL of a poster image.
+
+    \sa {QtMedia::PosterUrl}
+*/
+
+/*!
+    \qmlproperty variant Video::chapterNumber
+
+    This property holds the chapter number of the media.
+
+    \sa {QtMedia::ChapterNumber}
+*/
+
+/*!
+    \qmlproperty variant Video::director
+
+    This property holds the director of the media.
+
+    \sa {QtMedia::Director}
+*/
+
+/*!
+    \qmlproperty variant Video::leadPerformer
+
+    This property holds the lead performer in the media.
+
+    \sa {QtMedia::LeadPerformer}
+*/
+
+/*!
+    \qmlproperty variant Video::writer
+
+    This property holds the writer of the media.
+
+    \sa {QtMedia::Writer}
+*/
+
+// The remaining properties are related to photos, and are technically
+// available but will certainly never have values.
+#ifndef Q_QDOC
+
+/*!
+    \qmlproperty variant Video::cameraManufacturer
+
+    \sa {QtMedia::CameraManufacturer}
+*/
+
+/*!
+    \qmlproperty variant Video::cameraModel
+
+    \sa {QtMedia::CameraModel}
+*/
+
+/*!
+    \qmlproperty variant Video::event
+
+    \sa {QtMedia::Event}
+*/
+
+/*!
+    \qmlproperty variant Video::subject
+
+    \sa {QtMedia::Subject}
+*/
+
+/*!
+    \qmlproperty variant Video::orientation
+
+    \sa {QtMedia::Orientation}
+*/
+
+/*!
+    \qmlproperty variant Video::exposureTime
+
+    \sa {QtMedia::ExposureTime}
+*/
+
+/*!
+    \qmlproperty variant Video::fNumber
+
+    \sa {QtMedia::FNumber}
+*/
+
+/*!
+    \qmlproperty variant Video::exposureProgram
+
+    \sa {QtMedia::ExposureProgram}
+*/
+
+/*!
+    \qmlproperty variant Video::isoSpeedRatings
+
+    \sa {QtMedia::ISOSpeedRatings}
+*/
+
+/*!
+    \qmlproperty variant Video::exposureBiasValue
+
+    \sa {QtMedia::ExposureBiasValue}
+*/
+
+/*!
+    \qmlproperty variant Video::dateTimeDigitized
+
+    \sa {QtMedia::DateTimeDigitized}
+*/
+
+/*!
+    \qmlproperty variant Video::subjectDistance
+
+    \sa {QtMedia::SubjectDistance}
+*/
+
+/*!
+    \qmlproperty variant Video::meteringMode
+
+    \sa {QtMedia::MeteringMode}
+*/
+
+/*!
+    \qmlproperty variant Video::lightSource
+
+    \sa {QtMedia::LightSource}
+*/
+
+/*!
+    \qmlproperty variant Video::flash
+
+    \sa {QtMedia::Flash}
+*/
+
+/*!
+    \qmlproperty variant Video::focalLength
+
+    \sa {QtMedia::FocalLength}
+*/
+
+/*!
+    \qmlproperty variant Video::exposureMode
+
+    \sa {QtMedia::ExposureMode}
+*/
+
+/*!
+    \qmlproperty variant Video::whiteBalance
+
+    \sa {QtMedia::WhiteBalance}
+*/
+
+/*!
+    \qmlproperty variant Video::DigitalZoomRatio
+
+    \sa {QtMedia::DigitalZoomRatio}
+*/
+
+/*!
+    \qmlproperty variant Video::focalLengthIn35mmFilm
+
+    \sa {QtMedia::FocalLengthIn35mmFile}
+*/
+
+/*!
+    \qmlproperty variant Video::sceneCaptureType
+
+    \sa {QtMedia::SceneCaptureType}
+*/
+
+/*!
+    \qmlproperty variant Video::gainControl
+
+    \sa {QtMedia::GainControl}
+*/
+
+/*!
+    \qmlproperty variant Video::contrast
+
+    \sa {QtMedia::contrast}
+*/
+
+/*!
+    \qmlproperty variant Video::saturation
+
+    \sa {QtMedia::Saturation}
+*/
+
+/*!
+    \qmlproperty variant Video::sharpness
+
+    \sa {QtMedia::Sharpness}
+*/
+
+/*!
+    \qmlproperty variant Video::deviceSettingDescription
+
+    \sa {QtMedia::DeviceSettingDescription}
+*/
+
+#endif
+
 #include "moc_qmlgraphicsvideo_p.cpp"