1 files changed, 143 insertions, 40 deletions
diff --git a/examples/multimedia/declarative-camera/doc/src/declarative-camera.qdoc b/examples/multimedia/declarative-camera/doc/src/declarative-camera.qdoc
index 6aa8e8fa6..c6701a68b 100644
--- a/examples/multimedia/declarative-camera/doc/src/declarative-camera.qdoc
+++ b/examples/multimedia/declarative-camera/doc/src/declarative-camera.qdoc
@@ -1,55 +1,158 @@
-/****************************************************************************
-**
-** Copyright (C) 2015 The Qt Company Ltd.
-** Contact: http://www.qt.io/licensing/
-**
-** This file is part of the documentation of the Qt Toolkit.
-**
-** $QT_BEGIN_LICENSE:FDL$
-** Commercial License Usage
-** Licensees holding valid commercial Qt licenses may use this file in
-** accordance with the commercial license agreement provided with the
-** Software or, alternatively, in accordance with the terms contained in
-** a written agreement between you and The Qt Company. For licensing terms
-** and conditions see https://www.qt.io/terms-conditions. For further
-** information use the contact form at https://www.qt.io/contact-us.
-**
-** GNU Free Documentation License Usage
-** 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. Please review the following information to ensure
-** the GNU Free Documentation License version 1.3 requirements
-** will be met: https://www.gnu.org/licenses/fdl-1.3.html.
-** $QT_END_LICENSE$
-**
-****************************************************************************/
+// Copyright (C) 2015 The Qt Company Ltd.
+// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
 
 /*!
-\example multimedia/declarative-camera
-\title QML Camera Example
+\example declarative-camera
+\title QML Camera Application
 \ingroup multimedia_examples
 \ingroup camera_examples_qml
-\brief  The Camera Example shows how to use the API to capture a still image
-or video.
+\examplecategory {Multimedia}
+\examplecategory {Mobile}
+\brief This Qt Quick based application shows how to use the API to capture a
+still image or video.
 
 \image qml-camera.png
 
 This example demonstrates how to access camera functions via QML.
-It shows how to change settings and to capture images.
+It shows how to change settings and capture images or video.
 
 \include examples-run.qdocinc
 
-\section1 Application Structure
+\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}.
+Most of the QML code in this example supports the user interface. Custom types
+that support the requirements have been implemented using existing Qt Quick
+controls.
 
-CaptureControls, which is implemented in \e {CaptureControls.qml},
-generates a column on the right hand side of the screen which includes control
-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.
+\section1 Using screen orientation to select layout
 
+The orientation and control layout state logic is encapsulated in a separate
+Item, \c controlLayout like so:
+
+\quotefromfile declarative-camera/declarative-camera.qml
+\skipto Item {
+\printuntil /^    }/
+
+The \c stillControls and \c videoControls objects both bind to the \c state
+and \c buttonsWidth properties of this Item, as shown in \c stillControls:
+
+\skipto PhotoCaptureControls
+\printuntil /^    }/
+
+To support debugging, a message about layout state change is logged.
+
+Here is the portrait layout:
+
+\image qml-declarative-portrait.png
+
+You can see the \c state property is initially set as \c PhotoCapture.
+
+Then the \c states themselves are defined like so:
+
+\quotefromfile declarative-camera/declarative-camera.qml
+\skipto states: [
+\printuntil /^    ]/
+
+\section1 Controls for capturing
+
+Controls for capturing are implemented in \c PhotoCaptureControls.qml and
+VideoCaptureControls.qml. They each are based on a \l FocusScope that defines
+common buttons dimensions and margins that are used by the control buttons and
+then declares the buttons.
+
+This generates a column on the right hand side of the screen which includes,
+listed top to bottom, the following controls:
+\div {class="multi-column"}
+    \div {class="doc-column"}
+        \list
+        \li A \c Capture or \c Record button, which initiates capturing.
+        \li A \c{capture properties} button that displays the icon of the current
+        white balance mode selected and when pressed uses a pop-up to displays
+        the following option's icons:
+            \list
+            \li Flash mode (if available)
+            \li White balance modes
+            \li Exposure compensation
+            \endlist
+        \li A \c View button, once something has been captured.
+        \li A button which displays the currently selected capture device and
+        when pressed provides a list of available devices to switch to, using a
+        pop-up.
+        \li A \c{Switch To} button that displays the alternate capture mode
+        (video or photo) depending on the current active selection and switches
+        the mode when pressed.
+        \li A \c Quit button, that exits the application.
+        \endlist
+    \enddiv
+    \div {class="doc-column"}
+        \inlineimage CaptureControls.png
+    \enddiv
+    \div {class="doc-column"}
+        \inlineimage VideoCaptureControls.png
+    \enddiv
+\enddiv
+
+\section1 Image capturing
+
+The button that triggers this is defined in CameraButton.qml:
+but its interaction with the camera is in the controls types, lets look at
+PhotoCaptureControls:
+
+\quotefromfile declarative-camera/PhotoCaptureControls.qml
+\skipto CameraButton {
+\printto CameraPropertyButton {
+
+\section1 Zoom control
+
+\div {class="multi-column"}
+    \div {class="doc-column"}
+    Implemented in \c ZoomControl.qml the ZoomControl type is based on an Item
+    and creates a bar that represents the zoom level, which can also be dragged.
+    It uses an exponential calculation method to determine the zoom factor given
+    the position of the \c grove.
+
+    The bar is only visible if the initialZoom is greater than 1. This means
+    the currently active camera has a zoom function.
+    \enddiv
+    \div {class="doc-column"}
+        \inlineimage ZoomControl.png
+    \enddiv
+\enddiv
+
+\quotefromfile declarative-camera/ZoomControl.qml
+\skipto Item {
+\printuntil font.pixelSize: 18
+
+In PhotoCaptureControls.qml and VideoCaptureControls.qml the signal \c zoomTo
+will set the selected camera's \l{Camera::}{zoomFactor} property to the
+calculated \c target value, as well as updating the ZoomControl bar.
+
+\quotefromfile declarative-camera/VideoCaptureControls.qml
+\skipto ZoomControl {
+\printto FlashControl {
+
+\section1 Flash and torch control
+
+\image FlashControls.png
+
+Defined in \c FlashControl.qml this enables flash mode selection and torch
+functionality to be toggled via a Switch. As with the zoom control, the switches
+are only visible on top of the preview window if the active device supports
+these functions.
+
+Here we check if the functions are supported:
+
+\quotefromfile declarative-camera/FlashControl.qml
+\skipto property Camera cameraDevice
+\printline Camera
+\printline FlashOn
+\printline TorchOn
+
+Here we implement the \c flashModeControl switch, which also directly controls
+the Camera device.
+
+\skipto Switch {
+\printuntil /^        }/
+
+Torch control is implemented in a similar way.
 */