Docs: Expand and update the QML Camera example documentation

Added images, code snippets, and restructured the documentation to
talk about the changes since the documentation was initially
created.

Fixes: QTBUG-113572
Change-Id: I20d09c6a468404ed6f2a8aaabd695d8a92160d62
Reviewed-by: Rami Potinkara <rami.potinkara@qt.io>
Reviewed-by: Mats Honkamaa <mats.honkamaa@qt.io>
(cherry picked from commit 24422051dfacaa8036ba45ad23f449922540296b)
Reviewed-by: Qt Cherry-pick Bot <cherrypick_bot@qt-project.org>

7 files changed, 135 insertions, 17 deletions

diff --git a/examples/multimedia/declarative-camera/PhotoCaptureControls.qml b/examples/multimedia/declarative-camera/PhotoCaptureControls.qml
index 6d9ec1052..d5da02d33 100644
--- a/examples/multimedia/declarative-camera/PhotoCaptureControls.qml
+++ b/examples/multimedia/declarative-camera/PhotoCaptureControls.qml
@@ -109,6 +109,7 @@ FocusScope {
     }
 
     ZoomControl {
+        id: zoomControl
         x : 0
         y : captureControls.state === "MobilePortrait" ? -buttonPaneShadow.height : 0
         width : 100
@@ -116,7 +117,7 @@ FocusScope {
 
         currentZoom: camera.zoomFactor
         maximumZoom: camera.maximumZoomFactor
-        onZoomTo: camera.zoomFactor = value
+        onZoomTo: camera.zoomFactor = target
     }
 
     states: [
diff --git a/examples/multimedia/declarative-camera/VideoCaptureControls.qml b/examples/multimedia/declarative-camera/VideoCaptureControls.qml
index 8db725e92..fac3a55ca 100644
--- a/examples/multimedia/declarative-camera/VideoCaptureControls.qml
+++ b/examples/multimedia/declarative-camera/VideoCaptureControls.qml
@@ -91,14 +91,14 @@ FocusScope {
     }
 
     ZoomControl {
-        x : 0
+        x : 10
         y : captureControls.state === "MobilePortrait" ? -buttonPaneShadow.height : 0
         width : 100
-        height: parent.height
+        height: 500
 
         currentZoom: captureSession.camera.zoomFactor
         maximumZoom: captureSession.camera.maximumZoomFactor
-        onZoomTo: captureSession.camera.zoomFactor = value
+        onZoomTo: captureSession.camera.zoomFactor = target
     }
 
     states: [
diff --git a/examples/multimedia/declarative-camera/doc/images/CaptureControls.png b/examples/multimedia/declarative-camera/doc/images/CaptureControls.png
new file mode 100644
index 000000000..8c24d8030
--- /dev/null
+++ b/examples/multimedia/declarative-camera/doc/images/CaptureControls.png
diff --git a/examples/multimedia/declarative-camera/doc/images/VideoCaptureControls.png b/examples/multimedia/declarative-camera/doc/images/VideoCaptureControls.png
new file mode 100644
index 000000000..c35be7beb
--- /dev/null
+++ b/examples/multimedia/declarative-camera/doc/images/VideoCaptureControls.png
diff --git a/examples/multimedia/declarative-camera/doc/images/ZoomControl.png b/examples/multimedia/declarative-camera/doc/images/ZoomControl.png
new file mode 100644
index 000000000..d628e60f1
--- /dev/null
+++ b/examples/multimedia/declarative-camera/doc/images/ZoomControl.png
diff --git a/examples/multimedia/declarative-camera/doc/images/qml-camera.png b/examples/multimedia/declarative-camera/doc/images/qml-camera.png
index 0cd61f0a0..4b710670d 100644
--- a/examples/multimedia/declarative-camera/doc/images/qml-camera.png
+++ b/examples/multimedia/declarative-camera/doc/images/qml-camera.png
diff --git a/examples/multimedia/declarative-camera/doc/src/declarative-camera.qdoc b/examples/multimedia/declarative-camera/doc/src/declarative-camera.qdoc
index fcd37bbc9..205df5f79 100644
--- a/examples/multimedia/declarative-camera/doc/src/declarative-camera.qdoc
+++ b/examples/multimedia/declarative-camera/doc/src/declarative-camera.qdoc
@@ -3,29 +3,146 @@
 
 /*!
 \example declarative-camera
-\title QML Camera Example
+\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.
+\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 in this example supports the user interface. Custom types
+that support the requirements have been implemented using existing Qt Quick
+controls.
+
+\section1 Using screen orientation to select layout
+
+In \c declarative-camera.qml we handle detecting the orientation we're in and
+select the appropriate layout while also catering for the limitations of small
+screen mobile devices like so:
+
+\quotefromfile declarative-camera/declarative-camera.qml
+\skipto Rectangle {
+\printto states: [
+
+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:
+
+\printto CaptureSession {
+
+\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
+\printto Column {
+
+Here we implement the \c flashModeControl switch, which also directly controls
+the Camera device.
+
+\printuntil cameraDevice.flashMode = Camera.FlashOff;
+
+Torch control is implemented in a similar way.
+
 
-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}.
 
-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.
 
 */