Tweak the controls documentation.

Also move the qaudioendpointselector control into controls.

Change-Id: Ia21f98a683eb38a9c11c42f6e7901d7d841aae90
Reviewed-by: Peter Yard <peter.yard@nokia.com>
Reviewed-by: Jonas Rabbe <jonas.rabbe@gmail.com>

src/multimedia/controls/controls.pri

@@ -4,6 +4,7 @@ INCLUDEPATH += controls
 PUBLIC_HEADERS += \
     controls/qaudiodecodercontrol.h \
     controls/qaudioencodercontrol.h \
+    controls/qaudioendpointselector.h \
     controls/qcameracapturebufferformatcontrol.h \
     controls/qcameracapturedestinationcontrol.h \
     controls/qcameracontrol.h \
@@ -41,6 +42,7 @@ PRIVATE_HEADERS += \
 
 SOURCES += \
     controls/qaudioencodercontrol.cpp \
+    controls/qaudioendpointselector.cpp \
     controls/qcameracapturebufferformatcontrol.cpp \
     controls/qcameracapturedestinationcontrol.cpp \
     controls/qcameracontrol.cpp \

src/multimedia/controls/qaudiodecodercontrol.cpp

@@ -49,7 +49,7 @@ QT_BEGIN_NAMESPACE
     \class QAudioDecoderControl
     \inmodule QtMultimedia
 
-    \ingroup multimedia
+
     \ingroup multimedia_control
 
     \brief The QAudioDecoderControl class provides access to the audio decoding

src/multimedia/controls/qaudioencodercontrol.cpp

@@ -48,7 +48,7 @@ QT_BEGIN_NAMESPACE
 /*!
     \class QAudioEncoderControl
     \inmodule QtMultimedia
-    \ingroup multimedia
+
     \ingroup multimedia_control
 
     \brief The QAudioEncoderControl class provides access to the settings of a

src/multimedia/controls/qaudioendpointselector.cpp

@@ -0,0 +1,132 @@
+/****************************************************************************
+**
+** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
+** Contact: http://www.qt-project.org/
+**
+** This file is part of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:LGPL$
+** GNU Lesser General Public License Usage
+** This file may be used under the terms of the GNU Lesser General Public
+** License version 2.1 as published by the Free Software Foundation and
+** appearing in the file LICENSE.LGPL included in the packaging of this
+** file. Please review the following information to ensure the GNU Lesser
+** General Public License version 2.1 requirements will be met:
+** http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
+**
+** In addition, as a special exception, Nokia gives you certain additional
+** rights. These rights are described in the Nokia Qt LGPL Exception
+** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
+**
+** GNU General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU General
+** Public License version 3.0 as published by the Free Software Foundation
+** and appearing in the file LICENSE.GPL included in the packaging of this
+** file. Please review the following information to ensure the GNU General
+** Public License version 3.0 requirements will be met:
+** http://www.gnu.org/copyleft/gpl.html.
+**
+** 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$
+**
+****************************************************************************/
+
+#include "qaudioendpointselector.h"
+
+QT_BEGIN_NAMESPACE
+
+/*!
+    \class QAudioEndpointSelector
+
+    \brief The QAudioEndpointSelector class provides an audio endpoint selector media control.
+    \inmodule QtMultimedia
+    \ingroup multimedia_control
+
+    The QAudioEndpointSelector class provides descriptions of the audio
+    endpoints available on a system and allows one to be selected as the audio
+    of a media service.
+
+    The interface name of QAudioEndpointSelector is \c org.qt-project.qt.audioendpointselector/5.0 as
+    defined in QAudioEndpointSelector_iid.
+
+    \sa QMediaService::requestControl()
+*/
+
+/*!
+    \macro QAudioEndpointSelector_iid
+
+    \c org.qt-project.qt.audioendpointselector/5.0
+
+    Defines the interface name of the QAudioEndpointSelector class.
+
+    \relates QAudioEndpointSelector
+*/
+
+/*!
+    Constructs a new audio endpoint selector with the given \a parent.
+*/
+QAudioEndpointSelector::QAudioEndpointSelector(QObject *parent)
+    :QMediaControl(parent)
+{
+}
+
+/*!
+    Destroys an audio endpoint selector.
+*/
+QAudioEndpointSelector::~QAudioEndpointSelector()
+{
+}
+
+/*!
+    \fn QList<QString> QAudioEndpointSelector::availableEndpoints() const
+
+    Returns a list of the names of the available audio endpoints.
+*/
+
+/*!
+    \fn QString QAudioEndpointSelector::endpointDescription(const QString& name) const
+
+    Returns the description of the endpoint \a name.
+*/
+
+/*!
+    \fn QString QAudioEndpointSelector::defaultEndpoint() const
+
+    Returns the name of the default audio endpoint.
+*/
+
+/*!
+    \fn QString QAudioEndpointSelector::activeEndpoint() const
+
+    Returns the name of the currently selected audio endpoint.
+*/
+
+/*!
+    \fn QAudioEndpointSelector::setActiveEndpoint(const QString& name)
+
+    Set the active audio endpoint to \a name.
+*/
+
+/*!
+    \fn QAudioEndpointSelector::activeEndpointChanged(const QString& name)
+
+    Signals that the audio endpoint has changed to \a name.
+*/
+
+/*!
+    \fn QAudioEndpointSelector::availableEndpointsChanged()
+
+    Signals that list of available endpoints has changed.
+*/
+
+#include "moc_qaudioendpointselector.cpp"
+QT_END_NAMESPACE
+

src/multimedia/controls/qaudioendpointselector.h

@@ -0,0 +1,88 @@
+/****************************************************************************
+**
+** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
+** Contact: http://www.qt-project.org/
+**
+** This file is part of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:LGPL$
+** GNU Lesser General Public License Usage
+** This file may be used under the terms of the GNU Lesser General Public
+** License version 2.1 as published by the Free Software Foundation and
+** appearing in the file LICENSE.LGPL included in the packaging of this
+** file. Please review the following information to ensure the GNU Lesser
+** General Public License version 2.1 requirements will be met:
+** http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
+**
+** In addition, as a special exception, Nokia gives you certain additional
+** rights. These rights are described in the Nokia Qt LGPL Exception
+** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
+**
+** GNU General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU General
+** Public License version 3.0 as published by the Free Software Foundation
+** and appearing in the file LICENSE.GPL included in the packaging of this
+** file. Please review the following information to ensure the GNU General
+** Public License version 3.0 requirements will be met:
+** http://www.gnu.org/copyleft/gpl.html.
+**
+** 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$
+**
+****************************************************************************/
+
+#ifndef QAUDIOENDPOINTSELECTOR_H
+#define QAUDIOENDPOINTSELECTOR_H
+
+#include <qaudio.h>
+#include <qmediacontrol.h>
+
+QT_BEGIN_HEADER
+
+QT_BEGIN_NAMESPACE
+
+QT_MODULE(Multimedia)
+
+
+// Class forward declaration required for QDoc bug
+class QString;
+class Q_MULTIMEDIA_EXPORT QAudioEndpointSelector : public QMediaControl
+{
+    Q_OBJECT
+
+public:
+    virtual ~QAudioEndpointSelector();
+
+    virtual QList<QString> availableEndpoints() const = 0;
+    virtual QString endpointDescription(const QString& name) const = 0;
+    virtual QString defaultEndpoint() const = 0;
+    virtual QString activeEndpoint() const = 0;
+
+public Q_SLOTS:
+    virtual void setActiveEndpoint(const QString& name) = 0;
+
+Q_SIGNALS:
+    void activeEndpointChanged(const QString& name);
+    void availableEndpointsChanged();
+
+protected:
+    QAudioEndpointSelector(QObject *parent = 0);
+};
+
+#define QAudioEndpointSelector_iid "org.qt-project.qt.audioendpointselector/5.0"
+Q_MEDIA_DECLARE_CONTROL(QAudioEndpointSelector, QAudioEndpointSelector_iid)
+
+QT_END_NAMESPACE
+
+QT_END_HEADER
+
+
+#endif // QAUDIOENDPOINTSELECTOR_H

src/multimedia/controls/qcameracapturebufferformatcontrol.cpp

@@ -51,7 +51,7 @@ QT_BEGIN_NAMESPACE
     The format is of type QVideoFrame::PixelFormat.
 
     \inmodule QtMultimedia
-    \ingroup multimedia
+
     \ingroup multimedia_control
 
     The interface name of QCameraCaptureBufferFormatControl is \c org.qt-project.qt.cameracapturebufferformatcontrol/5.0 as

src/multimedia/controls/qcameracapturedestinationcontrol.cpp

@@ -52,7 +52,7 @@ QT_BEGIN_NAMESPACE
     Depending on backend capabilities capture to file, buffer or both can be supported.
 
     \inmodule QtMultimedia
-    \ingroup multimedia
+
     \ingroup multimedia_control
 
     The interface name of QCameraCaptureDestinationControl is \c org.qt-project.qt.cameracapturedestinationcontrol/5.0 as

src/multimedia/controls/qcameracontrol.cpp

@@ -53,7 +53,7 @@ QT_BEGIN_NAMESPACE
     classes that control still cameras or video cameras.
 
     \inmodule QtMultimedia
-    \ingroup multimedia
+
     \ingroup multimedia_control
 
     This service is provided by a QMediaService object via

src/multimedia/controls/qcameraexposurecontrol.cpp

@@ -50,7 +50,7 @@ QT_BEGIN_NAMESPACE
     \brief The QCameraExposureControl class allows controlling camera exposure parameters.
 
     \inmodule QtMultimedia
-    \ingroup multimedia
+
     \ingroup multimedia_control
 
     The QCameraExposure class is the usual method of adjusting exposure related parameters

src/multimedia/controls/qcamerafeedbackcontrol.cpp

@@ -50,7 +50,7 @@
     \brief The QCameraFeedbackControl class allows controlling feedback (sounds etc) during camera operation
 
     \inmodule QtMultimedia
-    \ingroup multimedia
+
     \ingroup multimedia_control
     \since 5.0
 

src/multimedia/controls/qcameraflashcontrol.cpp

@@ -51,7 +51,7 @@ QT_BEGIN_NAMESPACE
 
     \inmodule QtMultimedia
 
-    \ingroup multimedia
+
     \ingroup multimedia_control
 
     You can set the type of flash effect used when an image is captured, and test to see

src/multimedia/controls/qcamerafocuscontrol.cpp

@@ -53,7 +53,7 @@ QT_BEGIN_NAMESPACE
 
     \inmodule QtMultimedia
 
-    \ingroup multimedia
+
     \ingroup multimedia_control
 
     The interface name of QCameraFocusControl is \c org.qt-project.qt.camerafocuscontrol/5.0 as

src/multimedia/controls/qcameraimagecapturecontrol.cpp

@@ -52,7 +52,7 @@ QT_BEGIN_NAMESPACE
 
     \inmodule QtMultimedia
 
-    \ingroup multimedia
+
     \ingroup multimedia_control
 
     The interface name of QCameraImageCaptureControl is \c org.qt-project.qt.cameraimagecapturecontrol/5.0 as

src/multimedia/controls/qcameraimageprocessingcontrol.cpp

@@ -60,7 +60,7 @@ namespace
     \class QCameraImageProcessingControl
     \inmodule QtMultimedia
 
-    \ingroup multimedia
+
     \ingroup multimedia_control
 
 

src/multimedia/controls/qcameralockscontrol.cpp

@@ -54,7 +54,7 @@ QT_BEGIN_NAMESPACE
 
     \inmodule QtMultimedia
 
-    \ingroup multimedia
+
     \ingroup multimedia_control
 
     This service is provided by a QMediaService object via

src/multimedia/controls/qcameraviewfindersettingscontrol.cpp

@@ -48,7 +48,7 @@ QT_BEGIN_NAMESPACE
     \class QCameraViewfinderSettingsControl
     \inmodule QtMultimedia
 
-    \ingroup multimedia
+
     \ingroup multimedia_control
 
 

src/multimedia/controls/qcamerazoomcontrol.cpp

@@ -53,7 +53,7 @@ QT_BEGIN_NAMESPACE
 
     \inmodule QtMultimedia
 
-    \ingroup multimedia
+
     \ingroup multimedia_control
 
     The interface name of QCameraZoomControl is \c org.qt-project.qt.camerazoomcontrol/5.0 as

src/multimedia/controls/qimageencodercontrol.cpp

@@ -49,7 +49,7 @@ QT_BEGIN_NAMESPACE
 
     \inmodule QtMultimedia
 
-    \ingroup multimedia
+
     \ingroup multimedia_control
 
     \brief The QImageEncoderControl class provides access to the settings of a media service that

src/multimedia/controls/qmediaaudioprobecontrol.cpp

@@ -48,7 +48,7 @@ QT_BEGIN_NAMESPACE
     \class QMediaAudioProbeControl
     \inmodule QtMultimedia
 
-    \ingroup multimedia
+
     \ingroup multimedia_control
 
     \brief The QMediaAudioProbeControl class allows control over probing audio data in media objects.

src/multimedia/controls/qmediaavailabilitycontrol.cpp

@@ -51,7 +51,7 @@ QT_BEGIN_NAMESPACE
 
     \inmodule QtMultimedia
 
-    \ingroup multimedia
+
     \ingroup multimedia_control
 
     An instance of QMediaObject (or its derived classes) can report any changes

src/multimedia/controls/qmediacontainercontrol.cpp

@@ -51,7 +51,7 @@ QT_BEGIN_NAMESPACE
 
     \inmodule QtMultimedia
 
-    \ingroup multimedia
+
     \ingroup multimedia_control
 
     If a QMediaService supports writing encoded data it will implement

src/multimedia/controls/qmediagaplessplaybackcontrol.cpp

@@ -46,7 +46,7 @@
     \class QMediaGaplessPlaybackControl
     \inmodule QtMultimedia
 
-    \ingroup multimedia
+
     \ingroup multimedia_control
 
     \brief The QMediaGaplessPlaybackControl class provides access to the gapless playback

src/multimedia/controls/qmedianetworkaccesscontrol.cpp

@@ -48,7 +48,7 @@ QT_BEGIN_NAMESPACE
     \brief The QMediaNetworkAccessControl class allows the setting of the Network Access Point for media related activities.
     \inmodule QtMultimedia
 
-    \ingroup multimedia
+
     \ingroup multimedia_control
 
     The functionality provided by this control allows the

src/multimedia/controls/qmediaplayercontrol.cpp

@@ -50,7 +50,7 @@ QT_BEGIN_NAMESPACE
     \class QMediaPlayerControl
     \inmodule QtMultimedia
 
-    \ingroup multimedia
+
     \ingroup multimedia_control
 
 

src/multimedia/controls/qmediaplaylistcontrol.cpp

@@ -51,7 +51,7 @@ QT_BEGIN_NAMESPACE
 
     \inmodule QtMultimedia
 
-    \ingroup multimedia
+
     \ingroup multimedia_control
 
 

src/multimedia/controls/qmediaplaylistsourcecontrol.cpp

@@ -51,7 +51,7 @@ QT_BEGIN_NAMESPACE
 
     \inmodule QtMultimedia
 
-    \ingroup multimedia
+
     \ingroup multimedia_control
 
 

src/multimedia/controls/qmediarecordercontrol.cpp

@@ -48,7 +48,7 @@ QT_BEGIN_NAMESPACE
     \class QMediaRecorderControl
     \inmodule QtMultimedia
 
-    \ingroup multimedia
+
     \ingroup multimedia_control
 
     \brief The QMediaRecorderControl class provides access to the recording

src/multimedia/controls/qmediastreamscontrol.cpp

@@ -60,7 +60,7 @@ namespace
     \class QMediaStreamsControl
     \inmodule QtMultimedia
 
-    \ingroup multimedia
+
     \ingroup multimedia_control
 
     \brief The QMediaStreamsControl class provides a media stream selection control.

src/multimedia/controls/qmediavideoprobecontrol.cpp

@@ -48,7 +48,7 @@ QT_BEGIN_NAMESPACE
     \class QMediaVideoProbeControl
     \inmodule QtMultimedia
 
-    \ingroup multimedia
+
     \ingroup multimedia_control
 
     \brief The QMediaVideoProbeControl class allows control over probing video frames in media objects.

src/multimedia/controls/qmetadatareadercontrol.cpp

@@ -49,7 +49,7 @@ QT_BEGIN_NAMESPACE
     \class QMetaDataReaderControl
     \inmodule QtMultimedia
 
-    \ingroup multimedia
+
     \ingroup multimedia_control
 
 

src/multimedia/controls/qmetadatawritercontrol.cpp

@@ -49,7 +49,7 @@ QT_BEGIN_NAMESPACE
     \class QMetaDataWriterControl
     \inmodule QtMultimedia
 
-    \ingroup multimedia
+
     \ingroup multimedia_control
 
 

src/multimedia/controls/qradiodatacontrol.cpp

@@ -50,7 +50,7 @@ QT_BEGIN_NAMESPACE
     \class QRadioDataControl
     \inmodule QtMultimedia
 
-    \ingroup multimedia
+
     \ingroup multimedia_control
 
 

src/multimedia/controls/qradiotunercontrol.cpp

@@ -50,7 +50,7 @@ QT_BEGIN_NAMESPACE
     \class QRadioTunerControl
     \inmodule QtMultimedia
 
-    \ingroup multimedia
+
     \ingroup multimedia_control
 
 

src/multimedia/controls/qvideodevicecontrol.cpp

@@ -49,7 +49,7 @@ QT_BEGIN_NAMESPACE
     \brief The QVideoDeviceControl class provides an video device selector media control.
     \inmodule QtMultimedia
 
-    \ingroup multimedia
+
     \ingroup multimedia_control
 
     The QVideoDeviceControl class provides descriptions of the video devices

src/multimedia/controls/qvideoencodercontrol.cpp

@@ -50,7 +50,7 @@ QT_BEGIN_NAMESPACE
 
     \inmodule QtMultimedia
 
-    \ingroup multimedia
+
     \ingroup multimedia_control
 
     \brief The QVideoEncoderControl class provides access to the settings

src/multimedia/controls/qvideorenderercontrol.cpp

@@ -49,8 +49,9 @@ QT_BEGIN_NAMESPACE
     \class QVideoRendererControl
 
     \inmodule QtMultimedia
+    \brief The QVideoRendererControl class provides a media control for rendering video to a QAbstractVideoSurface.
+
 
-    \ingroup multimedia
     \ingroup multimedia_control
 
     Using the surface() property of QVideoRendererControl a

src/multimedia/controls/qvideowindowcontrol.cpp

@@ -47,7 +47,7 @@ QT_BEGIN_NAMESPACE
     \class QVideoWindowControl
 
     \inmodule QtMultimedia
-    \ingroup multimedia
+
     \ingroup multimedia_control
     \brief The QVideoWindowControl class provides a media control for rendering video to a window.