Add documentation for picture transfer example and minor QML fixes

Change-Id: I8ef9e19de9f48797034fd186dff4b0e096748b1d
Reviewed-by: Fabian Bumberger <fbumberger@rim.com>
Reviewed-by: Alex Blasche <alexander.blasche@digia.com>

17 files changed, 135 insertions, 22 deletions

diff --git a/examples/bluetooth/bluetooth.pro b/examples/bluetooth/bluetooth.pro
index 549bb7c6..e8a6f9a6 100644
--- a/examples/bluetooth/bluetooth.pro
+++ b/examples/bluetooth/bluetooth.pro
@@ -6,4 +6,4 @@ qtHaveModule(widgets) {
                bttennis
 }
 
-qtHaveModule(quick): SUBDIRS += scanner
+qtHaveModule(quick): SUBDIRS += scanner picturetransfer
diff --git a/examples/bluetooth/qmlpicturetransfer/Button.qml b/examples/bluetooth/picturetransfer/Button.qml
index 5ee56d10..eed6a4e9 100644
--- a/examples/bluetooth/qmlpicturetransfer/Button.qml
+++ b/examples/bluetooth/picturetransfer/Button.qml
@@ -38,7 +38,7 @@
 **
 ****************************************************************************/
 
-import QtQuick 2.0
+import QtQuick 2.1
 
 Rectangle {
     property alias text: label.text
diff --git a/examples/bluetooth/qmlpicturetransfer/DeviceDiscovery.qml b/examples/bluetooth/picturetransfer/DeviceDiscovery.qml
index c6629a80..1da77975 100644
--- a/examples/bluetooth/qmlpicturetransfer/DeviceDiscovery.qml
+++ b/examples/bluetooth/picturetransfer/DeviceDiscovery.qml
@@ -1,6 +1,7 @@
 /****************************************************************************
 **
 ** Copyright (C) 2013 BlackBerry Limited. All rights reserved.
+** Copyright (C) 2014 Digia Plc and/or its subsidiary(-ies).
 ** Contact: http://www.qt-project.org/legal
 **
 ** This file is part of the QtBluetooth module of the Qt Toolkit.
@@ -38,8 +39,8 @@
 **
 ****************************************************************************/
 
-import QtQuick 2.0
-import QtBluetooth 5.0
+import QtQuick 2.1
+import QtBluetooth 5.2
 
 Item {
     Rectangle {
@@ -61,7 +62,9 @@ Item {
         }
     }
 
+//! [Discovery-1]
     ListView {
+//! [Discovery-1]
         id: listView
         anchors.left: parent.left
         anchors.right: parent.right
@@ -73,7 +76,7 @@ Item {
         add: Transition {
             NumberAnimation { properties: "x"; from: 1000; duration: 500 }
         }
-
+//! [Discovery-2]
         model: BluetoothDiscoveryModel {
             discoveryMode: BluetoothDiscoveryModel.DeviceDiscovery
         }
@@ -84,4 +87,5 @@ Item {
             onClicked: root.remoteDevice = model.remoteAddress
         }
     }
+//! [Discovery-2]
 }
diff --git a/examples/bluetooth/qmlpicturetransfer/FileSending.qml b/examples/bluetooth/picturetransfer/FileSending.qml
index d59eca50..3a4a282f 100644
--- a/examples/bluetooth/qmlpicturetransfer/FileSending.qml
+++ b/examples/bluetooth/picturetransfer/FileSending.qml
@@ -38,7 +38,7 @@
 **
 ****************************************************************************/
 
-import QtQuick 2.0
+import QtQuick 2.1
 
 Item {
     Button {
diff --git a/examples/bluetooth/qmlpicturetransfer/PictureSelector.qml b/examples/bluetooth/picturetransfer/PictureSelector.qml
index 6cef7c6e..ca81ae44 100644
--- a/examples/bluetooth/qmlpicturetransfer/PictureSelector.qml
+++ b/examples/bluetooth/picturetransfer/PictureSelector.qml
@@ -1,6 +1,7 @@
 /****************************************************************************
 **
 ** Copyright (C) 2013 BlackBerry Limited. All rights reserved.
+** Copyright (C) 2014 Digia Plc and/or its subsidiary(-ies).
 ** Contact: http://www.qt-project.org/legal
 **
 ** This file is part of the QtBluetooth module of the Qt Toolkit.
@@ -38,7 +39,7 @@
 **
 ****************************************************************************/
 
-import QtQuick 2.0
+import QtQuick 2.1
 import Qt.labs.folderlistmodel 1.0
 
 Item {
@@ -76,12 +77,14 @@ Item {
             NumberAnimation { properties: "x"; from: 1000; duration: 500 }
         }
 
+//! [FileSelect-1]
         model: FolderListModel {
             folder: "file://"+SystemPictureFolder
             showDirs: false
         }
 
         delegate: Rectangle {
+//! [FileSelect-1]
             opacity: 0.7
             height: label.height + 130
             width: listView.width + 2
@@ -98,17 +101,22 @@ Item {
                 source: "file://" + model.filePath
             }
 
+//! [FileSelect-2]
             Text {
+//! [FileSelect-2]
                 id: label
                 anchors.verticalCenter: parent.verticalCenter
                 anchors.right: parent.right
                 anchors.margins: 20
                 anchors.left: picture.right
+//! [FileSelect-3]
                 text: model.fileName
+//! [FileSelect-3]
                 font.bold: true
                 font.pointSize: 10
                 color: "white"
                 wrapMode: Text.WordWrap
+//! [FileSelect-4]
             }
             MouseArea {
                 id: mArea
@@ -119,5 +127,6 @@ Item {
                 }
             }
         }
+//! [FileSelect-4]
     }
 }
diff --git a/examples/bluetooth/qmlpicturetransfer/background.png b/examples/bluetooth/picturetransfer/background.png
index c9f80fb5..c9f80fb5 100644
--- a/examples/bluetooth/qmlpicturetransfer/background.png
+++ b/examples/bluetooth/picturetransfer/background.png
diff --git a/examples/bluetooth/qmlpicturetransfer/bttransfer.qml b/examples/bluetooth/picturetransfer/bttransfer.qml
index d6588af2..bdfb47f0 100644
--- a/examples/bluetooth/qmlpicturetransfer/bttransfer.qml
+++ b/examples/bluetooth/picturetransfer/bttransfer.qml
@@ -1,6 +1,7 @@
 /****************************************************************************
 **
 ** Copyright (C) 2013 BlackBerry Limited. All rights reserved.
+** Copyright (C) 2014 Digia Plc and/or its subsidiary(-ies).
 ** Contact: http://www.qt-project.org/legal
 **
 ** This file is part of the QtBluetooth module of the Qt Toolkit.
@@ -38,26 +39,35 @@
 **
 ****************************************************************************/
 
-import QtQuick 2.0
+import QtQuick 2.1
 
+//! [Root-1]
 Image {
     id: root
+//! [Root-1]
     width: 600; height: 800
     fillMode: Image.PreserveAspectCrop
     source: "background.png"
+//! [Root-2]
     property string remoteDevice;
     property string fileName;
+//! [Root-2]
     onRemoteDeviceChanged: {
         loader.source = "PictureSelector.qml"
     }
+
+//! [Root-3]
     onFileNameChanged: {
         fileTransfer.initTransfer(remoteDevice, fileName);
         loader.source = "FileSending.qml"
     }
+//! [Root-3]
 
     Loader {
         id: loader
         anchors.fill: parent
         source: "DeviceDiscovery.qml"
     }
+//! [Root-4]
 }
+//! [Root-4]
diff --git a/examples/bluetooth/picturetransfer/doc/images/opp-example-1.png b/examples/bluetooth/picturetransfer/doc/images/opp-example-1.png
new file mode 100644
index 00000000..0b33bc8a
--- /dev/null
+++ b/examples/bluetooth/picturetransfer/doc/images/opp-example-1.png
diff --git a/examples/bluetooth/picturetransfer/doc/images/opp-example-2.png b/examples/bluetooth/picturetransfer/doc/images/opp-example-2.png
new file mode 100644
index 00000000..d3d325d5
--- /dev/null
+++ b/examples/bluetooth/picturetransfer/doc/images/opp-example-2.png
diff --git a/examples/bluetooth/picturetransfer/doc/images/opp-example-3.png b/examples/bluetooth/picturetransfer/doc/images/opp-example-3.png
new file mode 100644
index 00000000..cef9830c
--- /dev/null
+++ b/examples/bluetooth/picturetransfer/doc/images/opp-example-3.png
diff --git a/examples/bluetooth/picturetransfer/doc/src/picturetransfer.qdoc b/examples/bluetooth/picturetransfer/doc/src/picturetransfer.qdoc
new file mode 100644
index 00000000..fc2ffa32
--- /dev/null
+++ b/examples/bluetooth/picturetransfer/doc/src/picturetransfer.qdoc
@@ -0,0 +1,91 @@
+/****************************************************************************
+**
+** 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 QtBluetooth module.
+**
+** $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 Digia.  For licensing terms and
+** conditions see http://qt.digia.com/licensing.  For further information
+** use the contact form at http://qt.digia.com/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: http://www.gnu.org/copyleft/fdl.html.
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+\example picturetransfer
+\title QML Bluetooth Picture Push Example
+
+The Bluetooth Picture Push example shows how to use the \l QBluetoothTransferManager
+API. The example transfers a local image to a remote device.
+
+On the first user interface page the application scans for remote Bluetooth devices. The user must select
+the appropriate device to continue:
+
+\image opp-example-1.png
+
+The next page presents a list of image files on the device. The files must be located under
+\l QStandardPaths::PictureLocation}:
+
+\image opp-example-2.png
+
+Once the picture was selected the UI shows the progress of the file transfer:
+
+\image opp-example-3.png
+
+\section1 Device Discovery
+
+The device discovery uses the \l BluetoothDiscoveryModel to detect the remote devices. Each discovery is displayed
+as an entry in a list. Once a device was selected the device address is stored in the \c root element. More
+details about the \c root element will follow further below.
+
+\snippet picturetransfer/DeviceDiscovery.qml Discovery-1
+\snippet picturetransfer/DeviceDiscovery.qml Discovery-2
+
+\section1 File Selection
+
+The file is selected with the help of \l FolderListModel. Once again the selected file is stored in the \c root
+element:
+
+\snippet picturetransfer/PictureSelector.qml FileSelect-1
+\snippet picturetransfer/PictureSelector.qml FileSelect-2
+\snippet picturetransfer/PictureSelector.qml FileSelect-3
+\snippet picturetransfer/PictureSelector.qml FileSelect-4
+
+\section1 The root element
+
+The already mentioned \c root element collects the necessary pieces of data for the picture transfer.
+Once the file name has been set it triggers the file transfer:
+
+
+\snippet picturetransfer/bttransfer.qml Root-1
+\snippet picturetransfer/bttransfer.qml Root-2
+\snippet picturetransfer/bttransfer.qml Root-3
+\snippet picturetransfer/bttransfer.qml Root-3
+
+\section1 The File Transfer
+
+The file transfer is implemented in C++:
+
+\snippet picturetransfer/filetransfer.cpp Transfer-1
+
+and exposed to QML via a context property:
+
+\snippet picturetransfer/main.cpp Transfer-2
+
+
+
+*/
diff --git a/examples/bluetooth/qmlpicturetransfer/filetransfer.cpp b/examples/bluetooth/picturetransfer/filetransfer.cpp
index ba8ec47e..7cfd041d 100644
--- a/examples/bluetooth/qmlpicturetransfer/filetransfer.cpp
+++ b/examples/bluetooth/picturetransfer/filetransfer.cpp
@@ -48,7 +48,7 @@ FileTransfer::FileTransfer(QObject *parent) :
 {
 }
 
-
+//! [Transfer-1]
 void FileTransfer::initTransfer(QString address, QString fileName)
 {
     qDebug() << "Begin sharing file: " << address << fileName;
@@ -58,6 +58,7 @@ void FileTransfer::initTransfer(QString address, QString fileName)
     reply = manager.put(request, file);
     connect(reply, SIGNAL(transferProgress(qint64,qint64)), this, SLOT(updateProgress(qint64,qint64)));
 }
+//! [Transfer-1]
 
 void FileTransfer::updateProgress(qint64 transferred, qint64 total)
 {
diff --git a/examples/bluetooth/qmlpicturetransfer/filetransfer.h b/examples/bluetooth/picturetransfer/filetransfer.h
index 1bc9c78d..1bc9c78d 100644
--- a/examples/bluetooth/qmlpicturetransfer/filetransfer.h
+++ b/examples/bluetooth/picturetransfer/filetransfer.h
diff --git a/examples/bluetooth/qmlpicturetransfer/icon.png b/examples/bluetooth/picturetransfer/icon.png
index e378a26d..e378a26d 100644
--- a/examples/bluetooth/qmlpicturetransfer/icon.png
+++ b/examples/bluetooth/picturetransfer/icon.png
diff --git a/examples/bluetooth/qmlpicturetransfer/main.cpp b/examples/bluetooth/picturetransfer/main.cpp
index 3a6ce944..7db3053e 100644
--- a/examples/bluetooth/qmlpicturetransfer/main.cpp
+++ b/examples/bluetooth/picturetransfer/main.cpp
@@ -49,11 +49,14 @@
 int main(int argc, char *argv[])
 {
     QGuiApplication application(argc, argv);
+//! [Transfer-2]
     QQuickView view;
     FileTransfer fileTransfer;
     view.rootContext()->setContextProperty("fileTransfer", QVariant::fromValue(&fileTransfer));
+//! [Transfer-2]
     view.rootContext()->setContextProperty("SystemPictureFolder",
                       QStandardPaths::standardLocations(QStandardPaths::PicturesLocation).first());
+    qDebug() << QStandardPaths::standardLocations(QStandardPaths::PicturesLocation);
 
     view.setSource(QUrl(QLatin1String("qrc:/bttransfer.qml")));
     view.setResizeMode(QQuickView::SizeRootObjectToView);
diff --git a/examples/bluetooth/qmlpicturetransfer/qmltransfer.pro b/examples/bluetooth/picturetransfer/picturetransfer.pro
index da5e1d18..0eee46a2 100644
--- a/examples/bluetooth/qmlpicturetransfer/qmltransfer.pro
+++ b/examples/bluetooth/picturetransfer/picturetransfer.pro
@@ -1,9 +1,7 @@
 QT += quick bluetooth
 
-SOURCES += \
-    main.cpp
 
-TARGET = qml_transfer
+TARGET = qml_picturetransfer
 TEMPLATE = app
 
 RESOURCES += \
@@ -11,20 +9,17 @@ RESOURCES += \
 
 OTHER_FILES += \
     bttransfer.qml \
-    Button.qml
-
-OTHER_FILES += \
-    DeviceDiscovery.qml
-
-OTHER_FILES += \
-    PictureSelector.qml
+    Button.qml \
+    DeviceDiscovery.qml \
+    PictureSelector.qml \
+    FileSending.qml
 
 HEADERS += \
     filetransfer.h
 
 SOURCES += \
-    filetransfer.cpp
+    filetransfer.cpp \
+    main.cpp
+
 
-OTHER_FILES += \
-    FileSending.qml
 
diff --git a/examples/bluetooth/qmlpicturetransfer/qmltransfer.qrc b/examples/bluetooth/picturetransfer/qmltransfer.qrc
index f28e97ea..f28e97ea 100644
--- a/examples/bluetooth/qmlpicturetransfer/qmltransfer.qrc
+++ b/examples/bluetooth/picturetransfer/qmltransfer.qrc