path: root/doc/src/plugins/qml-multimedia.qdoc

/****************************************************************************
**
** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies).
** All rights reserved.
** Contact: Nokia Corporation (qt-info@nokia.com)
**
** This file is part of the documentation of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:FDL$
** GNU Free Documentation License
** Alternatively, this file may be used under the terms of the GNU Free
** Documentation License version 1.3 as published by the Free Software
** Foundation and appearing in the file included in the packaging of
** this file.
**
** Other Usage
** Alternatively, this file may be used in accordance with the terms
** and conditions contained in a signed written agreement between you
** and Nokia.
**
**
**
**
** $QT_END_LICENSE$
**
****************************************************************************/

/*!
    \group qml-multimedia
    \title QML Multimedia Plugin
    QML Support for the QtMobility Project Multimedia API.
*/

/*!
    \page qml-multimedia.html

    \title Multimedia QML Plugin

    \brief A QML plugin for the QtMobility Project Multimedia API.


    \section1 Overview

    The Multimedia API in the QtMobility Project gives developers a simplified way to use audio and video playback, and access camera functionality. The Multimedia QML Plugin provides a QML friendly interface to these features.

    \section1 Elements

    \section2 Audio

    The \l Audio element is an easy way to add audio playback to a Qt Quick
    scene. QtMobility provides properties for control, methods (functions) and signals.

    The code extract below shows the creation and use of an audio element.

    \qml

    import Qt 4.7
    import QtMultimediaKit 1.1
    // ...

    Audio {
        id: playMusic
        source: "music.wav"
    }

    MouseArea {
        id: playArea
        anchors.fill: parent
        onPressed:  { playMusic.play() }
    }

    \endqml

    The snippet above shows how the inclusion of \i playMusic enables audio features on the element that contains it. So that when the parent's MouseArea is clicked the \l {Audio::play()}{play()} method of the audio element is run. Other typical audio control methods are available such as \l {Audio::pause}{pause()} and \l {Audio::stop()}{stop()}.

    Much of the getting / setting of \l Audio parameters is done through properties. These include
    \table 70%
        \header
            \o Property
            \o Description
        \row
            \o \l {Audio::source}{source}
            \o The source URL of the media.
        \row
            \o \l {Audio::autoLoad}{autoLoad}
            \o Indicates if loading of media should begin immediately.
        \row
            \o \l{Audio::playing}{playing}
            \o Indicates that the media is playing.
        \row
            \o \l {Audio::paused}{paused}
            \o The media is paused.
        \row
            \o \l{Audio::status}{status}
            \o The status of media loading.
        \row
            \o \l{Audio::duration}{duration}
            \o Amount of time in milliseconds the media will play.
        \row
            \o \l{Audio::position}{position}
            \o Current position in the media in milliseconds of play.
        \row
            \o \l{Audio::volume}{volume}
            \o Audio output volume: from 0.0 (silent) to 1.0 (maximum)
        \row
            \o \l{Audio::muted}{muted}
            \o Indicates audio is muted.
        \row
            \o \l{Audio::bufferProgress}{bufferProgress}
            \o Indicates how full the data buffer is: 0.0 (empty) to 1.0 (full).
        \row
            \o \l{Audio::seekable}{seekable}
            \o Indicates whether the audio position can be changed.
        \row
            \o \l{Audio::playbackRate}{playbackRate}
            \o The rate at which audio is played at as a multiple of the normal rate.
        \row
            \o \l{Audio::error}{error}
            \o An error code for the error state including NoError
        \row
            \o \l{Audio::errorString}{errorString}
            \o A description of the current error condition.
    \endtable

    The set of signals available allow the developer to create custom behavior when the following events occur,

    \table 70%
        \header
            \o Signal
            \o Description
        \row
            \o \l{Audio::onStarted}{onStarted}
            \o Called when playback has been started.
        \row
            \o \l{Audio::onResumed}{onResumed}
            \o Called when playback is resumed from the paused state.
        \row
            \o \l{Audio::onPaused}{onPaused}
            \o Called when playback is paused.
        \row
            \o \l{Audio::onStopped}{onStopped}
            \o Called when playback is stopped.
        \row
            \o \l{Audio::onError}{onError}
            \o Called when the specified error occurs.
    \endtable

    \section2 Camera

    The \l Camera element in the plugin enables still image capture using
    QML. The element has methods for starting and stopping the camera, capturing
    the image, camera settings and many signals indicating critical events.

    The follow code is taken from the \l {QML Camera Example}. This snippet
    shows the setting up of the \l Camera element

    \qml

    Camera {
        id: camera
        x : 0
        y : 0
        width : 640
        height : 480
        focus : visible //to receive focus and capture key events
        //captureResolution : "640x480"

        flashMode: stillControls.flashMode
        whiteBalanceMode: stillControls.whiteBalance
        exposureCompensation: stillControls.exposureCompensation

        onImageCaptured : {
            photoPreview.source = preview
            stillControls.previewAvailable = true
            cameraUI.state = "PhotoPreview"
        }
    }

    \endqml

    Notice that the slot for the \l {Camera::imageCaptured()}{imageCaptured()}
    signal is implemented in \i onImageCaptured. However, this code only
    changes some state information to allow previewing.

    The capture call itself is part of the implementation of the button
    that the user presses to take the image. It uses a call to
    \l {Camera::captureImage()}{captureImage()}:

    \qml

    CameraButton {
        text: "Capture"
        onClicked: camera.captureImage()
    }

    \endqml


    \section2 Video

    Adding video playback, with sound, to a Qt Quick scene is also easy. The process is very similar to that of Audio above, in fact \l {Video} shares many of the property names, methods and signals. Here is the equivalent sample code to implement a video playback element in a scene

    \qml

    Video {
        id: video
        width : 800
        height : 600
        source: "video.avi"

        MouseArea {
            anchors.fill: parent
            onClicked: {
                video.play()
            }
        }

        focus: true
        Keys.onSpacePressed: video.paused = !video.paused
        Keys.onLeftPressed: video.position -= 5000
        Keys.onRightPressed: video.position += 5000
    }

    \endqml

    There are similar features like \l {Video::play()}{play()} with new
    features specific to video.

    In the above sample when the parent of MouseArea is clicked, an area of 800x600 pixels with an id of 'video', the source "video.avi" will play in that area. Notice also that signals for the Keys element have been defined so that a spacebar will toggle the pause button; the left arrow will move the current position in the video to 5 seconds previously; and the right arrow will advance the current position in the video by 5 seconds.

    Most of the differences will obviously be about video control and information. There are many properties associated with the \l {Video} element, most of them deal with meta-data, control of the video media and aspects of presentation.

    \section2 SoundEffect

    The \l SoundEffect element provides a way to play short sound effects, like in video games. Multiple sound effect instances can be played simultaneously.
    You should use the \l Audio element for music playback.

    \qml

    import Qt 4.7
    import QtMultimediaKit 1.1


        SoundEffect {
            id: effect
            source: "test.wav"
        }
        MouseArea {
            id: playArea
            anchors.fill: parent
            onPressed:  { effect.play() }
        }

    \endqml


    In the above sample the sound effect will be played when the MouseArea is clicked.

    For a complete description of this element, see \l SoundEffect

    \section2 Camera

    Adding access to the camera viewfinder, and capturing images is possible by using the  \l Camera element.  You can adjust capture settings
    including white balance, exposure compensation and flash mode, and control zoom.

    \qml
    import Qt 4.7
    import QtMultimediaKit 1.1

    Camera {
        focus : visible // to receive focus and capture key events when visible

        flashMode: Camera.FlashRedEyeReduction
        whiteBalanceMode: Camera.WhiteBalanceFlash
        exposureCompensation: -1.0

        onImageCaptured : {
            photoPreview.source = preview  // Show the preview in an Image element
        }

    }
    \endqml

    For a complete description of this element, see \l Camera, and look at the \l {declarative-camera}{QML Camera Example}.

    \section1 Multimedia QML Elements

    \annotatedlist qml-multimedia
*/