From a0188acf80824e26632b8e008c22a4d2074d909a Mon Sep 17 00:00:00 2001 From: Andrew O'Doherty Date: Thu, 1 Feb 2018 12:46:32 +0100 Subject: 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 --- examples/nfc/annotatedurl/annotatedurl.cpp | 4 +- examples/nfc/annotatedurl/annotatedurl.h | 2 + .../nfc/annotatedurl/doc/images/annotatedurl.png | Bin 34705 -> 7345 bytes .../nfc/annotatedurl/doc/images/annotatedurl2.png | Bin 0 -> 7685 bytes .../nfc/annotatedurl/doc/src/annotatedurl.qdoc | 48 +++++++++- examples/nfc/corkboard/doc/src/corkboard.qdoc | 101 ++++++++++++++++++++- examples/nfc/corkboard/main.cpp | 2 + 7 files changed, 147 insertions(+), 10 deletions(-) create mode 100644 examples/nfc/annotatedurl/doc/images/annotatedurl2.png (limited to 'examples') 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) QT_FORWARD_DECLARE_CLASS(QNearFieldManager) QT_FORWARD_DECLARE_CLASS(QNearFieldTarget) +//! [0] class AnnotatedUrl : public QObject { Q_OBJECT @@ -79,5 +80,6 @@ public slots: private: QNearFieldManager *manager; }; +//! [0] #endif // ANNOTATEDURL_H diff --git a/examples/nfc/annotatedurl/doc/images/annotatedurl.png b/examples/nfc/annotatedurl/doc/images/annotatedurl.png index b6cf8637..01130ecd 100644 Binary files a/examples/nfc/annotatedurl/doc/images/annotatedurl.png and b/examples/nfc/annotatedurl/doc/images/annotatedurl.png 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 Binary files /dev/null and b/examples/nfc/annotatedurl/doc/images/annotatedurl2.png 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 +TextField. + +\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 #include +//! [0] int main(int argc, char *argv[]) { QGuiApplication application(argc, argv); @@ -62,3 +63,4 @@ int main(int argc, char *argv[]) view.show(); return application.exec(); } +//! [0] -- cgit v1.2.3