path: root/examples
diff options
authorAndrew O'Doherty <>2018-02-01 12:46:32 +0100
committerAndrew O'Doherty <>2018-03-05 14:37:54 +0000
commita0188acf80824e26632b8e008c22a4d2074d909a (patch)
treeaee0c462a35451ea0c555d4f69362442223eb28a /examples
parent3d93b58fcc36f556a90613750a3150d56379b2a4 (diff)
Revamp Qt NFC examples: documentation update
Update the documentation of annotatedurl and corkboard examples Task-number: QTBUG-60644 Change-Id: Ide980dd2573e443bc54553cd2916ac6b209da2c9 Reviewed-by: Alex Blasche <>
Diffstat (limited to 'examples')
-rw-r--r--examples/nfc/annotatedurl/doc/images/annotatedurl.pngbin34705 -> 7345 bytes
-rw-r--r--examples/nfc/annotatedurl/doc/images/annotatedurl2.pngbin0 -> 7685 bytes
7 files changed, 147 insertions, 10 deletions
diff --git a/examples/nfc/annotatedurl/annotatedurl.cpp b/examples/nfc/annotatedurl/annotatedurl.cpp
index 5c4a0527..0e6b58fa 100644
--- a/examples/nfc/annotatedurl/annotatedurl.cpp
+++ b/examples/nfc/annotatedurl/annotatedurl.cpp
@@ -168,12 +168,12 @@ void AnnotatedUrl::handleMessage(const QNdefMessage &message, QNearFieldTarget *
QNdefNfcUriRecord uriRecord(record);
url = uriRecord.uri();
-//! [handleMessage 3]
} else if (record.typeNameFormat() == QNdefRecord::Mime &&
record.type().startsWith("image/")) {
pixmap = QPixmap::fromImage(QImage::fromData(record.payload()));
-//! [handleMessage 4]
+//! [handleMessage 3]
+//! [handleMessage 4]
emit annotatedUrl(url, title, pixmap);
diff --git a/examples/nfc/annotatedurl/annotatedurl.h b/examples/nfc/annotatedurl/annotatedurl.h
index e62b9d08..204bed5f 100644
--- a/examples/nfc/annotatedurl/annotatedurl.h
+++ b/examples/nfc/annotatedurl/annotatedurl.h
@@ -60,6 +60,7 @@ QT_FORWARD_DECLARE_CLASS(QPixmap)
+//! [0]
class AnnotatedUrl : public QObject
@@ -79,5 +80,6 @@ public slots:
QNearFieldManager *manager;
+//! [0]
diff --git a/examples/nfc/annotatedurl/doc/images/annotatedurl.png b/examples/nfc/annotatedurl/doc/images/annotatedurl.png
index b6cf8637..01130ecd 100644
--- a/examples/nfc/annotatedurl/doc/images/annotatedurl.png
+++ b/examples/nfc/annotatedurl/doc/images/annotatedurl.png
Binary files differ
diff --git a/examples/nfc/annotatedurl/doc/images/annotatedurl2.png b/examples/nfc/annotatedurl/doc/images/annotatedurl2.png
new file mode 100644
index 00000000..2ea6f12f
--- /dev/null
+++ b/examples/nfc/annotatedurl/doc/images/annotatedurl2.png
Binary files differ
diff --git a/examples/nfc/annotatedurl/doc/src/annotatedurl.qdoc b/examples/nfc/annotatedurl/doc/src/annotatedurl.qdoc
index 0ea57a7c..7fda040f 100644
--- a/examples/nfc/annotatedurl/doc/src/annotatedurl.qdoc
+++ b/examples/nfc/annotatedurl/doc/src/annotatedurl.qdoc
@@ -30,13 +30,53 @@
\title Annotated URL Example
\brief An example showing reading from formatted NFC Data Exchange Format (NDEF) messages.
-The Annotated URL example displays the contents of specifically formatted NFC
-Data Exchange Format (NDEF) messages read from an NFC Tag. The NDEF message
-should contain a URI record, an optional \c image/* MIME record, and one or more
-localized Text records.
+The Annotated URL example displays the contents of specifically
+formatted NFC Data Exchange Format (NDEF) messages read from an NFC
+Tag. The NDEF message should contain a URI record, an optional \c
+image/* MIME record, and one or more localized Text records.
+This is the initial state of the example:
\image annotatedurl.png
+In this example the NFC Tag used contains a text record. The UI
+gets updated accordingly to:
+\image annotatedurl2.png
+\section1 AnnotatedUrl Class Definition
+The \c AnnotatedUrl class wraps the \c QNearFieldManager, the class
+providing the NFC Tag detection functionality. NDEF messages are read
+by the QNearFieldManager and forwarded to a handler contained in the
+\c AnnotatedUrl class. After parsing the NDEF message the class emits
+the signal AnnotatedUrl::annotatedUrl(const QUrl &url, const QString
+&title, const QPixmap &pixmap). The UI reacts to the signal displaying
+the contents of the NDEF message.
+\snippet annotatedurl/annotatedurl.h 0
+\section1 AnnotatedUrl Handler Implementation
+NFC messages read by the \c QNearFieldManager are forwarded to
+AnnotatedUrl::handleMessage. The callback signature details can be
+read in \l{QNearFieldManager::registerNdefMessageHandler}.
+\snippet annotatedurl/annotatedurl.cpp handleMessage 1
+Because NFC messages are composed of several NDEF records, looping
+through all of the records allows the extraction of the 3 parameters
+to be displayed in the UI: the Uri, the Title and the Pixmap:
+\snippet annotatedurl/annotatedurl.cpp handleMessage 2
+\snippet annotatedurl/annotatedurl.cpp handleMessage 3
+Finally after having extracted the parameters of the NFC message the
+corresponding signal is emitted so that the UI can handle it.
+\snippet annotatedurl/annotatedurl.cpp handleMessage 4
\include examples-run.qdocinc
\sa {Qt NFC}
diff --git a/examples/nfc/corkboard/doc/src/corkboard.qdoc b/examples/nfc/corkboard/doc/src/corkboard.qdoc
index 29ad8eac..ac21187b 100644
--- a/examples/nfc/corkboard/doc/src/corkboard.qdoc
+++ b/examples/nfc/corkboard/doc/src/corkboard.qdoc
@@ -30,13 +30,106 @@
\title QML CorkBoard Example
\brief A QML example about displaying NFC Data Exchange Format (NDEF) messages.
-The QML CorkBoard example displays the contents of NDEF messages read from an
-NFC Tag. Each newly detected NDEF message is added to the corkboard and can be
-dragged into an arbitrary position on the board. The corkboard has a \e Personal
-and \e Work space. The workspace can be changed by sliding left or right.
+The QML corkboard example displays the contents of NDEF messages read
+from an NFC Tag. Each newly detected NDEF message is added to the
+corkboard and can be dragged into an arbitrary position on the
+board. The corkboard has a \e Personal and \e Work space. The
+workspace can be changed by sliding left or right.
\image corkboard.png
+\section1 Implementation details
+In the corkboard example, we use the following .qml files:
+ \list
+ \li corkboards.qml
+ \li Mode.qml
+ \endlist
+The main.cpp holds the application logic to load the main view stored
+in the corkboards.qml file.
+\snippet corkboard/main.cpp 0
+\section1 corkboards.qml details
+There are two basic QML components in this file:
+ \list
+ \li NearField
+ \li ListView
+ \endlist
+The first time the NearField QML type is instantiated, the
+Component.onCompleted handler will start the NFC polling process. The
+\l [Qml] {NearField} {onMessageRecordsChanged} handler parses NFC
+Messages that are detected by the NearField component and builds up a
+data model that is passed into the ListView. Additionally, every time the
+NearField manager stops the polling process, the onPollingChanged
+handler restarts it.
+\quotefromfile corkboard/corkboards.qml
+\skipto NearField
+\printuntil onMessageRecordsChanged
+\dots 8
+\skipuntil }
+\skipto onPollingChanged
+\printuntil onPollingChanged
+\dots 8
+\skipuntil }
+\skipto Component
+\printuntil Component
+\dots 8
+\skipuntil }
+\printline }
+\skipto ListModel
+\printto ListModel
+The ListView component takes a ListModel as parameter (built from the
+NFC records). The view of each of the items of the model is defined by
+the Mode component (its implementation details can be found in the
+file Mode.qml). The data model consists of a list of corkboards. Each
+corkboard can display multiple NFC text message records.
+\quotefromfile corkboard/corkboards.qml
+\skipto ListView
+\printuntil id
+\dots 8
+\skipto model
+\printuntil model
+\dots 8
+\skipto delegate
+\printuntil delegate
+\skipto }
+\printline }
+\section1 Mode.qml details
+A corkboard title is displayed for each of the items that form part
+of the data model:
+\quotefromfile corkboard/Mode.qml
+\skipto Text
+\printuntil }
+\printuntil }
+Every text record that was read from an NFC message, is represented by
+a sticky note with its own position on the display. Initially the
+position is set randomly. The text on the sticky note is set on a
+\quotefromfile corkboard/Mode.qml
+\skipto Repeater
+\printuntil y:
+\skipto Item
+\dots 16
+\printuntil sticky
+\dots 20
+\skipto TextEdit
+\printuntil noteText
+\dots 24
+\skipto }
+\printuntil }
+\dots 20
\include examples-run.qdocinc
\sa {Qt NFC}
diff --git a/examples/nfc/corkboard/main.cpp b/examples/nfc/corkboard/main.cpp
index 99673c80..74fad72f 100644
--- a/examples/nfc/corkboard/main.cpp
+++ b/examples/nfc/corkboard/main.cpp
@@ -53,6 +53,7 @@
#include <QtQml/QQmlEngine>
#include <QtQuick/QQuickView>
+//! [0]
int main(int argc, char *argv[])
QGuiApplication application(argc, argv);
@@ -62,3 +63,4 @@ int main(int argc, char *argv[]);
return application.exec();
+//! [0]