From af73d55efffa1dca928038cd4f392eb7def7c7e1 Mon Sep 17 00:00:00 2001 From: Jerome Pasion Date: Wed, 9 Apr 2014 17:02:25 +0200 Subject: Doc: Improved example documentation -added instructions on how to run the example (using \include to insert a section from qtbase/doc/global/) -updated copyright year -removed links to Qt 4 API -rearranged some of the sections -created links from the example pages to Qt Multimedia -fixed QDoc warnings related to the example pages Task-number: QTBUG-33597 Change-Id: Id45ce5cbd40dbfa384abd7260a316f6f6837c186 Reviewed-by: Yoann Lopes Reviewed-by: Sze Howe Koh --- .../audiodevices/doc/src/audiodevices.qdoc | 9 +++--- .../audioengine/doc/src/audioengine.qdoc | 10 +++--- .../multimedia/audioinput/doc/src/audioinput.qdoc | 9 +++--- .../audiooutput/doc/src/audiooutput.qdoc | 9 +++--- .../audiorecorder/doc/src/audiorecorder.qdoc | 12 ++++--- .../doc/src/declarative-camera.qdoc | 37 +++++++--------------- .../doc/src/declarative-radio.qdoc | 10 +++--- examples/multimedia/spectrum/doc/src/spectrum.qdoc | 6 ++-- examples/multimedia/video/doc/src/qmlvideo.qdoc | 11 +++---- examples/multimedia/video/doc/src/qmlvideofx.qdoc | 11 ++++--- .../multimediawidgets/camera/doc/src/camera.qdoc | 8 ++--- .../multimediawidgets/player/doc/src/player.qdoc | 5 +-- .../doc/src/videographicsitem.qdoc | 6 ++-- .../videowidget/doc/src/videowidget.qdoc | 6 ++-- 14 files changed, 73 insertions(+), 76 deletions(-) (limited to 'examples') diff --git a/examples/multimedia/audiodevices/doc/src/audiodevices.qdoc b/examples/multimedia/audiodevices/doc/src/audiodevices.qdoc index d75584485..bdf1590fe 100644 --- a/examples/multimedia/audiodevices/doc/src/audiodevices.qdoc +++ b/examples/multimedia/audiodevices/doc/src/audiodevices.qdoc @@ -1,6 +1,6 @@ /**************************************************************************** ** -** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies). +** Copyright (C) 2014 Digia Plc and/or its subsidiary(-ies). ** Contact: http://www.qt-project.org/legal ** ** This file is part of the documentation of the Qt Toolkit. @@ -29,8 +29,8 @@ \example audiodevices \title Audio Devices Example \ingroup multimedia_examples - \brief The Audio Devices example shows the application of the audio devices APIs - + \brief The Audio Devices example shows the application of the audio devices + APIs. This example shows how to create a simple application to list and test the configuration for the various audio devices available on the device @@ -38,6 +38,5 @@ \image audiodevices.png + \include examples-run.qdocinc */ - - diff --git a/examples/multimedia/audioengine/doc/src/audioengine.qdoc b/examples/multimedia/audioengine/doc/src/audioengine.qdoc index c83247df1..52a377130 100644 --- a/examples/multimedia/audioengine/doc/src/audioengine.qdoc +++ b/examples/multimedia/audioengine/doc/src/audioengine.qdoc @@ -1,6 +1,6 @@ /**************************************************************************** ** -** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies). +** Copyright (C) 2014 Digia Plc and/or its subsidiary(-ies). ** Contact: http://www.qt-project.org/legal ** ** This file is part of the documentation of the Qt Toolkit. @@ -30,10 +30,10 @@ \title AudioEngine Example \ingroup multimedia_examples \brief The Audio Engine example demonstrates 3D sound control using - the QtAudioEngine API. + the Qt Audio Engine API. - \image audioengine.png + The Audio Engine example demonstrates 3D sound control using the + \l{Qt Audio Engine QML Types}{Qt Audio Engine} API. + \include examples-run.qdocinc */ - - diff --git a/examples/multimedia/audioinput/doc/src/audioinput.qdoc b/examples/multimedia/audioinput/doc/src/audioinput.qdoc index 39ef26156..11a513a99 100644 --- a/examples/multimedia/audioinput/doc/src/audioinput.qdoc +++ b/examples/multimedia/audioinput/doc/src/audioinput.qdoc @@ -1,6 +1,6 @@ /**************************************************************************** ** -** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies). +** Copyright (C) 2014 Digia Plc and/or its subsidiary(-ies). ** Contact: http://www.qt-project.org/legal ** ** This file is part of the documentation of the Qt Toolkit. @@ -37,7 +37,8 @@ Qt provides the QAudioInput class to enable audio functionality within a standard application user interface. - This example calculates the maximum linear value of the input audio from the microphone and displays the output. -*/ - + This example calculates the maximum linear value of the input audio from the + microphone and displays the output. + \include examples-run.qdocinc +*/ diff --git a/examples/multimedia/audiooutput/doc/src/audiooutput.qdoc b/examples/multimedia/audiooutput/doc/src/audiooutput.qdoc index bc79e6a5d..60c9d00d4 100644 --- a/examples/multimedia/audiooutput/doc/src/audiooutput.qdoc +++ b/examples/multimedia/audiooutput/doc/src/audiooutput.qdoc @@ -1,6 +1,6 @@ /**************************************************************************** ** -** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies). +** Copyright (C) 2014 Digia Plc and/or its subsidiary(-ies). ** Contact: http://www.qt-project.org/legal ** ** This file is part of the documentation of the Qt Toolkit. @@ -31,13 +31,14 @@ \ingroup multimedia_examples \brief The Audio Output Example show the use of the QAudioOutput API. - The example demonstrates the basic use cases of the QAudioOutput class. + The example demonstrates the basic use cases of the QAudioOutput class from + \l{Qt Multimedia}. \image audiooutput-example.png This example provides a tone generator to supply continuous audio playback. The first button allows pause and resume of the playback, and the second button allows toggling between push and pull modes of operation. -*/ - + \include examples-run.qdocinc +*/ diff --git a/examples/multimedia/audiorecorder/doc/src/audiorecorder.qdoc b/examples/multimedia/audiorecorder/doc/src/audiorecorder.qdoc index 8453ea34e..35f6c0511 100644 --- a/examples/multimedia/audiorecorder/doc/src/audiorecorder.qdoc +++ b/examples/multimedia/audiorecorder/doc/src/audiorecorder.qdoc @@ -1,6 +1,6 @@ /**************************************************************************** ** -** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies). +** Copyright (C) 2014 Digia Plc and/or its subsidiary(-ies). ** Contact: http://www.qt-project.org/legal ** ** This file is part of the documentation of the Qt Toolkit. @@ -34,6 +34,12 @@ It demonstrates the discovery of the supported devices and codecs and the use of recording functions in the QAudioRecorder class. + \image audiorecorder.png + + \include examples-run.qdocinc + + \section1 Displaying the Window and Audio Settings + We display a window for the user to select the appropriate audio input, codec, container, and sample rate. Allow a setting of either quality or bitrate. Finally, the output file can be selected and recording can be @@ -49,7 +55,7 @@ \l{QMultimedia::NormalQuality}, while the bitrates are hardcoded into the list. - \image audiorecorder.png + \section1 Recording Audio To record audio we simply create a QAudioRecorder object. @@ -96,5 +102,3 @@ ui->statusbar->showMessage(tr("Recorded %1 sec").arg(duration / 1000)); \endcode */ - - diff --git a/examples/multimedia/declarative-camera/doc/src/declarative-camera.qdoc b/examples/multimedia/declarative-camera/doc/src/declarative-camera.qdoc index 02e77854c..8c87b1d46 100644 --- a/examples/multimedia/declarative-camera/doc/src/declarative-camera.qdoc +++ b/examples/multimedia/declarative-camera/doc/src/declarative-camera.qdoc @@ -1,6 +1,6 @@ /**************************************************************************** ** -** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies). +** Copyright (C) 2014 Digia Plc and/or its subsidiary(-ies). ** Contact: http://www.qt-project.org/legal ** ** This file is part of the documentation of the Qt Toolkit. @@ -34,35 +34,22 @@ or video. \image qml-camera.png -This example demonstrates how to use the Qt Multimedia QML API to access -camera functions. It shows how to change settings and to capture images. +This example demonstrates how to use the +\l{Qt Multimedia QML Types}{Qt Multimedia QML API} to access camera functions. +It shows how to change settings and to capture images. + +\include examples-run.qdocinc + +\section1 Application Structure Most of the QML code supports the user interface for this application with the camera types being mostly found in \e {declarative-camera.qml} and \e {CaptureControls.qml}. -In \e {declarative-camera.qml} the \l Camera is initialized with an id -of \e {camera}, a photo preview is setup, states are implemented for image -preview or capture and \l CaptureControls is initialized. The initial -\e state is \e PhotoCapture. \l CameraCapture includes a handler, \e onImageCaptured, -for the \l {imageCaptured} signal. The handler sets up the application to process -the preview including a change in the user interface state. The \l PhotoPreview -becomes visible with any key press being picked up by the handler -in PhotoPreview and returning the state to \e PhotoCapture. - -\e CaptureControls, which is implemented in \e {CaptureControls.qml}, +CaptureControls, which is implemented in \e {CaptureControls.qml}, generates a column on the right hand side of the screen which includes control -buttons for \e focus (not initially visible), \e {capture}, \e {flash modes}, -\e {white balance}, \e {exposure compensation}, and if a preview is -available a \e {preview} button. The last button exits from the application. - -When the Capture button is pressed the \e onClicked handler calls -\l {Camera::captureImage()}{captureImage()} - - - - - - +buttons for focus (not initially visible), capture, flash modes, +white balance, exposure compensation, and if a preview is +available, a preview button. The last button exits from the application. */ diff --git a/examples/multimedia/declarative-radio/doc/src/declarative-radio.qdoc b/examples/multimedia/declarative-radio/doc/src/declarative-radio.qdoc index 99c41114a..bb1a5d89f 100644 --- a/examples/multimedia/declarative-radio/doc/src/declarative-radio.qdoc +++ b/examples/multimedia/declarative-radio/doc/src/declarative-radio.qdoc @@ -1,6 +1,6 @@ /**************************************************************************** ** -** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies). +** Copyright (C) 2014 Digia Plc and/or its subsidiary(-ies). ** Contact: http://www.qt-project.org/legal ** ** This file is part of the documentation of the Qt Toolkit. @@ -31,8 +31,8 @@ \brief Demonstrates the radio functionality \ingroup multimedia_examples - This examples uses the Qt Multimedia Radio QML type to list the available - channels on the FM frequency. -*/ - + This examples uses the \l{Qt Multimedia} \l Radio QML type to list the + available channels on the FM frequency. + \include examples-run.qdocinc +*/ diff --git a/examples/multimedia/spectrum/doc/src/spectrum.qdoc b/examples/multimedia/spectrum/doc/src/spectrum.qdoc index 280838956..3c846afdc 100644 --- a/examples/multimedia/spectrum/doc/src/spectrum.qdoc +++ b/examples/multimedia/spectrum/doc/src/spectrum.qdoc @@ -1,6 +1,6 @@ /**************************************************************************** ** -** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies). +** Copyright (C) 2014 Digia Plc and/or its subsidiary(-ies). ** Contact: http://www.qt-project.org/legal ** ** This file is part of the documentation of the Qt Toolkit. @@ -59,6 +59,6 @@ (FFT) of a segment of audio data. An open-source library, \l{http://ldesoras.free.fr/prod.html}{FFTReal}, against which the application is dynamically linked, is used to compute the transform. -*/ - + \include examples-run.qdocinc +*/ diff --git a/examples/multimedia/video/doc/src/qmlvideo.qdoc b/examples/multimedia/video/doc/src/qmlvideo.qdoc index 6d6833497..1e80cd176 100644 --- a/examples/multimedia/video/doc/src/qmlvideo.qdoc +++ b/examples/multimedia/video/doc/src/qmlvideo.qdoc @@ -1,6 +1,6 @@ /**************************************************************************** ** -** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies). +** Copyright (C) 2014 Digia Plc and/or its subsidiary(-ies). ** Contact: http://www.qt-project.org/legal ** ** This file is part of the documentation of the Qt Toolkit. @@ -34,8 +34,6 @@ resize; rotate; change aspect ratio) which can be applied to QML \l{VideoOutput} items. -\section1 Overview - This example demonstrates the various manipulations (move; resize; rotate; change aspect ratio) which can be applied to QML \l{VideoOutput} items. @@ -50,7 +48,9 @@ which moves across the \l{VideoOutput} item. \image qmlvideo-overlay.png -\section1 Application structure +\include examples-run.qdocinc + +\section1 Application Structure The \l{video/qmlvideo/qml/qmlvideo/main.qml} file creates a UI which includes the following items: @@ -127,7 +127,7 @@ instance, the embedded \l{video/qmlvideo/qml/qmlvideo/Content.qml}{Content} item creates either a \l{MediaPlayer} or a \l{Camera} item. -\section1 Calculating and displaying QML painting rate +\section1 Calculating and Displaying QML Painting Rate \input multimedia/doc/src/examples/video-qml-paint-rate.qdocinc @@ -145,4 +145,3 @@ object to a JavaScript function, which will eventually call frequencyItem.notify \printuntil SLOT(qmlFramePainted())); */ - diff --git a/examples/multimedia/video/doc/src/qmlvideofx.qdoc b/examples/multimedia/video/doc/src/qmlvideofx.qdoc index b7bd78ac7..80f087e7f 100644 --- a/examples/multimedia/video/doc/src/qmlvideofx.qdoc +++ b/examples/multimedia/video/doc/src/qmlvideofx.qdoc @@ -1,6 +1,6 @@ /**************************************************************************** ** -** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies). +** Copyright (C) 2014 Digia Plc and/or its subsidiary(-ies). ** Contact: http://www.qt-project.org/legal ** ** This file is part of the documentation of the Qt Toolkit. @@ -34,9 +34,11 @@ can be used to apply postprocessing effects, expressed in \c GLSL, to video and camera viewfinder content. +\include examples-run.qdocinc + \section1 Overview -This example shows how a \l {ShaderEffectItem} can be used to apply +This example shows how a \l {ShaderEffect} can be used to apply postprocessing effects, expressed in GLSL, to QML \l {VideoOutput} items. It also shows how native code can be combined with QML to implement more @@ -73,7 +75,7 @@ for Effect*.qml files in the list above to see the full range. \section1 Application structure Shader effects can be applied to video or viewfinder content using -\l{ShaderEffectItem}, as shown in the following example, which applies +\l{ShaderEffect}, as shown in the following example, which applies a wiggly effect to the content: \code @@ -171,7 +173,7 @@ is based on the \l{ShaderEffect}: \skipto import \printuntil /^\}/ -The interface of the \l Effect allows for derived effects to specify the +The interface of Effect allows for derived effects to specify the number of parameters which they support (and therefore the number of sliders which should be displayed), and whether a vertical dividing line should be drawn between transformed and untransformed image regions. As an example, here is the @@ -219,4 +221,3 @@ object to a JavaScript function, which will eventually call frequencyItem.notify \printuntil SLOT(qmlFramePainted())); */ - diff --git a/examples/multimediawidgets/camera/doc/src/camera.qdoc b/examples/multimediawidgets/camera/doc/src/camera.qdoc index d1a855d4e..5f6683484 100644 --- a/examples/multimediawidgets/camera/doc/src/camera.qdoc +++ b/examples/multimediawidgets/camera/doc/src/camera.qdoc @@ -1,6 +1,6 @@ /**************************************************************************** ** -** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies). +** Copyright (C) 2014 Digia Plc and/or its subsidiary(-ies). ** Contact: http://www.qt-project.org/legal ** ** This file is part of the documentation of the Qt Toolkit. @@ -35,10 +35,12 @@ \brief The Camera Example shows how to use the API to capture a still image or video. -The Camera Example demonstrates how you can use Qt Multimedia to implement +The Camera Example demonstrates how you can use \l{Qt Multimedia} to implement some basic Camera functionality to take still images and record video clips with audio. +\include examples-run.qdocinc + A Camera class is created that will act as our Camera. It has a user interface, control functions, setting values and a means of defining the location where the image or video clip is to be saved. It will also store the image and video @@ -74,5 +76,3 @@ is started with a call to \l {QMediaRecorder::record()}. \image camera-example.png */ - - diff --git a/examples/multimediawidgets/player/doc/src/player.qdoc b/examples/multimediawidgets/player/doc/src/player.qdoc index 2dfb7c3d0..29121dce4 100644 --- a/examples/multimediawidgets/player/doc/src/player.qdoc +++ b/examples/multimediawidgets/player/doc/src/player.qdoc @@ -1,6 +1,6 @@ /**************************************************************************** ** -** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies). +** Copyright (C) 2014 Digia Plc and/or its subsidiary(-ies). ** Contact: http://www.qt-project.org/legal ** ** This file is part of the documentation of the Qt Toolkit. @@ -34,6 +34,8 @@ This example creates a simple multimedia player. We can play audio and or video files using various codecs. + \include examples-run.qdocinc + The example uses a QMediaPlayer object passed into a QVideoWidget to control the video output. To give the application playlist capability we also use a QPlayList object. @@ -93,4 +95,3 @@ \endcode */ - diff --git a/examples/multimediawidgets/videographicsitem/doc/src/videographicsitem.qdoc b/examples/multimediawidgets/videographicsitem/doc/src/videographicsitem.qdoc index 3ccdba5f5..1e392ce8c 100644 --- a/examples/multimediawidgets/videographicsitem/doc/src/videographicsitem.qdoc +++ b/examples/multimediawidgets/videographicsitem/doc/src/videographicsitem.qdoc @@ -1,6 +1,6 @@ /**************************************************************************** ** -** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies). +** Copyright (C) 2014 Digia Plc and/or its subsidiary(-ies). ** Contact: http://www.qt-project.org/legal ** ** This file is part of the documentation of the Qt Toolkit. @@ -32,9 +32,11 @@ \brief This example demonstrates how to stream video on a graphics scene. The Video Graphics Item example shows how to implement a QGraphicsItem that displays video on a - graphics scene using Qt Multimedia's QAbstractVideoSurface. + graphics scene using \l{Qt Multimedia}'s QAbstractVideoSurface. \image video-videographicsitem.png \sa {Video Widget Example} + + \include examples-run.qdocinc */ diff --git a/examples/multimediawidgets/videowidget/doc/src/videowidget.qdoc b/examples/multimediawidgets/videowidget/doc/src/videowidget.qdoc index 805a830bc..6b93a3c19 100644 --- a/examples/multimediawidgets/videowidget/doc/src/videowidget.qdoc +++ b/examples/multimediawidgets/videowidget/doc/src/videowidget.qdoc @@ -1,6 +1,6 @@ /**************************************************************************** ** -** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies). +** Copyright (C) 2014 Digia Plc and/or its subsidiary(-ies). ** Contact: http://www.qt-project.org/legal ** ** This file is part of the documentation of the Qt Toolkit. @@ -32,7 +32,9 @@ \brief This example is a simple video player The Video Widget example denonstrates how to implement a video widget using - Qt Multimedia's QAbstractVideoSurface. + \l{Qt Multimedia}'s QAbstractVideoSurface. \image video-videowidget.png + + \include examples-run.qdocinc */ -- cgit v1.2.3