Improve knxeditor example documentationv5.12.0-beta3v5.12.0-beta2

Change-Id: Ie93e3407a34d0fc1652b5906ab42c502b52fb741
Reviewed-by: Karsten Heimrich <karsten.heimrich@qt.io>

4 files changed, 224 insertions, 5 deletions

diff --git a/examples/knx/doc/images/editor-devman.jpg b/examples/knx/doc/images/editor-devman.jpg
new file mode 100644
index 0000000..2dd426c
--- /dev/null
+++ b/examples/knx/doc/images/editor-devman.jpg
diff --git a/examples/knx/doc/images/editor-main.png b/examples/knx/doc/images/editor-main.png
new file mode 100644
index 0000000..8093371
--- /dev/null
+++ b/examples/knx/doc/images/editor-main.png
diff --git a/examples/knx/doc/images/tunnel-tab.jpg b/examples/knx/doc/images/tunnel-tab.jpg
new file mode 100644
index 0000000..76bb769
--- /dev/null
+++ b/examples/knx/doc/images/tunnel-tab.jpg
diff --git a/examples/knx/doc/knxeditor.qdoc b/examples/knx/doc/knxeditor.qdoc
index 11e2906..f72d4e1 100644
--- a/examples/knx/doc/knxeditor.qdoc
+++ b/examples/knx/doc/knxeditor.qdoc
@@ -29,12 +29,231 @@
     \example knxeditor
     \title KNX Editor Example
     \ingroup qtknx-examples
-    \brief A simple KNX client.
 
-    \e {KNX Editor} shows how to discover a KNX netIP server, configure a
-    connection, and construct a frame.
+    \brief A KNX client for handling KNX local device management and
+    tunneling.
 
-    The output shows the traffic moving over the connection between the client
-    and the server.
+    \image editor-main.png "KNX editor"
 
+    The KNX Editor user interface contains a \uicontrol Communication group,
+    tabs for different KNX functionalities, and an \uicontrol Output panel.
+
+    To get started, users select one of the network interfaces on their
+    machine in the \uicontrol {Local IP Address} field, and then select
+    \uicontrol Scan to find any neighbouring KNX routers.
+
+    Once the client discovers KNX routers, information about them is displayed
+    in the \uicontrol Output panel. Users must select a router to enable the
+    tab views.
+
+    In the \uicontrol {Local Device Management} tab, users can customize
+    the KNX frame and some parameters. They can choose the local management
+    service type request to send and attach data values to it. The request
+    is sent after the users select \uicontrol Connect. The received response
+    is displayed in the tab. The following image shows an M_PropRead.req
+    request that was sent and the response that was received.
+
+    \image editor-devman.jpg "local device management tab"
+
+    The \uicontrol Tunneling tab allows establishing a KNXnet/IP tunnel
+    connection to a KNX router. The tunnel is established by selecting
+    \uicontrol Connect. It is then possible to send data link layer service
+    requests and customize the parameters contained in the requests. The
+    following image shows an example of sending an L_Data.req request.
+
+    \image tunnel-tab.jpg
+
+    The \uicontrol {Tunneling Features} tab requires a KNX router that supports
+    tunneling version 2. It allows accessing information such as the device
+    descriptor of the host device and other properties. It is an extension
+    that enables users to access the required management information over their
+    authorized tunneling connection only.
+
+    The \uicontrol Output panel shows the traffic moving over the connection
+    between the client and the server.
+
+    The application consists of four classes:
+
+    \list
+        \li \c MainWindow is a \l QMainWindow that renders the general layout of
+            the application.
+        \li \c LocalDeviceManagement is a \l QWidget connected to the
+            \uicontrol {Local Device Management} tab.
+        \li \c Tunneling is a \l QWidget asociated with the
+            \uicontrol Tunneling tab.
+        \li \c TunnelingFeatures is a \l QWidget linked to the
+            \uicontrol {Tunneling Features} tab.
+    \endlist
+
+    Each of the above classes stores a reference to the class definition
+    generated by \c qmake for every designer UI file. Through that reference,
+    the above classes can interact with the graphical components of the
+    application.
+
+    \section1 Main Window Class Definition and Implementation
+
+    \quotefromfile knxeditor/mainwindow.h
+    \skipto class MainWindow :
+    \printuntil /^\}/
+
+    The \c MainWindow class uses a \l QKnxNetIpServerDiscoveryAgent instance
+    that allows discovering KNXnet/IP servers by sending a search request
+    in the network that the client is connected to. It also saves an
+    instance of QKnxNetIpServerInfo for storing information about the
+    current KNXnet/IP server (router) selected by the user.
+
+    The \c QKnxNetIpServerDiscoveryAgent is initiated when the \uicontrol Scan
+    button is clicked. Here is the code snippet doing it:
+
+    \quotefromfile knxeditor/mainwindow.cpp
+    \skipto MainWindow::MainWindow
+    \printuntil {
+    \dots
+    \skipto QPushButton::clicked
+    \printuntil );
+    \dots
+
+    There are signal handlers installed for every signal emitted by the
+    discovery agent. Here is an example of one of the setups capturing the
+    \l QKnxNetIpServerDiscoveryAgent::deviceDiscovered signal emitted when
+    a server is found:
+
+    \quotefromfile knxeditor/mainwindow.cpp
+    \skipto MainWindow::MainWindow
+    \printuntil {
+    \dots
+    \skipto QKnxNetIpServerDiscoveryAgent::deviceDiscovered
+    \printuntil );
+    \dots
+
+    In this last example, when \l
+    QKnxNetIpServerDiscoveryAgent::deviceDiscovered is triggered, the
+    function \c MainWindow::showServerAndServices() is called. It displays
+    information about the routers in the \uicontrol Output panel.
+
+    At this point, users can select one of the available routers to establish
+    a connection, and send the different types of frames using the different
+    features available in the tabs:
+
+    \quotefromfile knxeditor/mainwindow.cpp
+    \skipto MainWindow::MainWindow
+    \printuntil {
+    \dots
+    \skipto QKnxNetIpServerDiscoveryAgent::finished
+    \printuntil });
+    \dots
+    \skipto /^\}/
+    \printuntil /^\}/
+    \skipto void MainWindow::newServerSelected
+    \printuntil auto info
+    \dots
+    \skipto info.endpoint
+    \printuntil /^\}/
+
+    The \c MainWindow::newServerSelected method saves the selected server in
+    the \c MainWindow instance.
+
+    \section1 Local Device Management Class Definition and Implementation
+
+    \quotefromfile knxeditor/localdevicemanagement.h
+    \skipto class LocalDeviceManagement :
+    \printuntil /^\}/
+
+    Local device management uses an instance of \l QKnxNetIpDeviceManagement
+    for the opening and handling of a device management connection to a
+    KNXnet/IP router. The tunnel is created when the \uicontrol Connect button
+    is clicked.
+
+    \quotefromfile knxeditor/localdevicemanagement.cpp
+    \skipto LocalDeviceManagement::LocalDeviceManagement
+    \printuntil {
+    \dots
+    \skipto QPushButton::clicked
+    \printuntil });
+    \dots
+    \skipto /^\}/
+    \printuntil /^\}/
+
+    The \l QKnxNetIpDeviceManagement instance is instructed to connect
+    to the server host that was previously selected.
+
+    Once the \l QKnxNetIpDeviceManagement::connected signal is triggered, the
+    \uicontrol {Send Request} button gets enabled and the client can begin
+    sending customized device management service requests. The code snippet
+    below shows the handler set up for the \c clicked signal of the
+    \uicontrol {Send Request} button (\c deviceManagementSendRequest):
+
+    \quotefromfile knxeditor/localdevicemanagement.cpp
+    \skipto LocalDeviceManagement::LocalDeviceManagement
+    \printuntil {
+    \dots
+    \skipto QKnxNetIpDeviceManagement::connected
+    \printuntil     });
+    \dots
+    \skipto deviceManagementSendRequest, &QPushButton::clicked
+    \printuntil     });
+    \dots
+    \skipto /^\}/
+    \printuntil /^\}/
+
+
+    \section1 Tunneling Class Definition and Implementation
+
+    \quotefromfile knxeditor/tunneling.h
+    \skipto class Tunneling :
+    \printuntil /^\}/
+
+    The \c Tunneling class holds a \l QKnxNetIpTunnel that enables the opening
+    and handling of a KNXnet/IP client connection to a KNXnet/IP server. Once
+    the class is instantiated, the client establishes the connection when the
+    \uicontrol Connect button is clicked:
+
+    \quotefromfile knxeditor/tunneling.cpp
+    \skipto Tunneling::Tunneling
+    \printuntil {
+    \dots
+    \skipto QPushButton::clicked
+    \printuntil     });
+    \dots
+    \skipto /^\}/
+    \printuntil /^\}/
+
+    The received KNX frames are decoded and handled here:
+
+    \quotefromfile knxeditor/tunneling.cpp
+    \skipto Tunneling::Tunneling
+    \printuntil {
+    \dots
+    \skipto QKnxNetIpTunnel::frameReceived
+    \printuntil     });
+    \dots
+    \skipto /^\}/
+    \printuntil /^\}/
+
+    \section1 TunnelingFeatures Class Definition and Implementation
+
+    \quotefromfile knxeditor/tunnelingfeatures.h
+    \skipto class TunnelingFeatures :
+    \printuntil /^\}/
+
+    Similarly to the \c Tunneling class, the \c TunnelingFeatures class uses a
+    \l QKnxNetIpTunnel for opening and handling a KNXnet/IP client connection.
+    However, it makes use of some  additional methods for sending the tunneling
+    feature version 2 frames: \l QKnxNetIpTunnel::sendTunnelingFeatureGet and
+    \l QKnxNetIpTunnel::sendTunnelingFeatureSet. Here is the handler for
+    the \c clicked singal of the \uicontrol {Send Message} button
+    (\c tunnelingSend):
+
+    \quotefromfile knxeditor/tunnelingfeatures.cpp
+    \skipto tunnelingSend, &QPushButton::clicked
+    \printuntil     });
+
+    \section1 The Main Function
+
+    The KNX editor \c main() function does not have any special handling. It
+    looks like the main function for any Qt app:
+
+    \quotefromfile knxeditor/main.cpp
+    \skipto #include
+    \printuntil /^\}/
 */