diff options
author | Kavindra Palaraja <kpalaraja@luxoft.com> | 2019-02-15 16:51:39 +0100 |
---|---|---|
committer | Kavindra Palaraja <kpalaraja@luxoft.com> | 2019-03-15 11:52:20 +0000 |
commit | 402894eac28760f63864c59d07abd7a35321a5c3 (patch) | |
tree | 8a99c7c9642d1a3c5f3e3a086de4f46465fadf9d | |
parent | c0eabe1bb8da128a1d4eca73cbb6704882c6ff1b (diff) |
[docs] Review QmlLive documentation
* Starting with the index and the concepts topics
Task-number: AUTOSUITE-780
Change-Id: I556b89fcae9956ffaded0592ab7a1e1dabcde2ee
Reviewed-by: Svetlana Abramenkova <sabramenkova@luxoft.com>
-rw-r--r-- | doc/concepts.qdoc | 157 | ||||
-rw-r--r-- | doc/index.qdoc | 44 | ||||
-rw-r--r-- | doc/installation.qdoc | 47 | ||||
-rw-r--r-- | doc/ipc-group.qdoc | 11 | ||||
-rw-r--r-- | doc/qmllive-group.qdoc | 4 |
5 files changed, 125 insertions, 138 deletions
diff --git a/doc/concepts.qdoc b/doc/concepts.qdoc index 26d79c6..099ce44 100644 --- a/doc/concepts.qdoc +++ b/doc/concepts.qdoc @@ -35,63 +35,73 @@ \page qmllive-concepts.html \title Concepts +The following are some concepts that are helpful to understand QmlLive. + +\list + \li \l{Live Reloading} + \li \l{Local Sessions} + \li \l{Display, Screens, Panels, Components, Fragments} + \li \l{Remote Sessions} + \li \l{UXSheets} +\endlist + \section1 Live Reloading -During a typical user interface design phase, designers create many graphical -documents describing the desired user interface. Transferring such graphical -visions into a running source code is difficult and time consuming. +In a typical User Interface (UI) design phase, designers create many graphical +files describing their ideal UI. Transferring these graphical visions into +source code that runs, is a challenging and time consuming task. \image workbench.png -Not only is it a tedious process, it often comes with great compromises on both -sides. The designer's vision is often not fully replicable with the underlying -technology. So it takes many iterations to come to an optimal solution. - -A lot of time-consuming editing is needed to finally reach a compromise that -satisfies the designer's vision and how it is realized in code. Each iteration -is a small step towards the desired user experience goal. Qt, with the Qt Quick -technology, already shortens the gap between vision and product by introducing -a more design oriented language (QML). However, there is still room for -improvement, which is why QmlLive was created. - -QmlLive is managed by a central bench watching your project workspace. A change -on a file inside the workspace is automatically detected and immediately -reflected onto one or more local rendering areas or to connected remote -clients. A team can develop a user interface very quickly and precisely on a PC and -simultaneously display it on one or several local and/or remote clients. The -clients can run on any desktop or networked embedded device that -supports Qt5 and QmlLive. +This task also involves compromises between the designers and the developers. +Sometimes, the designer's vision cannot be replicated fully with the underlying +technology. Consequently, this task requires many iterations before there is +an optimal solution. + +There is a lot of time consuming editing work needed, to reach a compromise +that satisfies the designer's vision and how the developer realizes it in code. +Each iteration is a small step towards the desired user experience goal. Qt, +with the Qt Quick technology, already shortens the gap between vision and +product via QML, a more design oriented language. QmlLive aims to close this +gap. + +QmlLive is managed by a central Bench that watches your project workspace. A +change in a file inside the workspace is automatically detected and immediately +reflected onto one or more local rendering areas, or to connected remote +clients. A team can develop a UI quickly and precisely on a machine and +simultaneously display it on one or more local and/or remote clients. These +clients can run on any desktop or networked embedded device that supports Qt5 +and QmlLive. \image concept.png \section1 Local Sessions For a local session you only need the QmlLive Bench. It contains all of the -required components in an easy-to-use interface. You type and save, we show -you the outcome on your PC in a fraction of a second. This is ideally suited -for a multi-monitor setup where you see your code on one display and the -live results of your changes on the other display. Seamless user interface -creation is the target, where you see every change immediately. This -is great for sketching out a scene or getting the last touch on animation -behavior. It also encourages you to think in terms of components; instead of -developing a whole scene, you can break apart the scene into smaller parts -or components. You can work on these small components and see how they look -standalone or embedded into a larger scene. +required components in an easy-to-use interface. As you type and save, the +output is displayed on your machine in a fraction of a second. Local sessions +are best suited for a multi-monitor setup where you see your code on one +display and the live results of your changes on another display. This +use case is ideal for sketching out a scene or putting final touches to +animation behavior. Local sessions also encourage you to think in terms of +elements; instead of developing a whole scene, you can break the scene into +smaller elements. As you work on these small elements, you can see how they +look standalone or embedded into a larger scene. \image client.png -\section1 Remote Sessions - \e{putting delight on your devices} +\section1 Remote Sessions -A scene rendered on a PC display will rarely look the same as on the target -display for the embedded device. There are subtle changes in the color -appearance, pixel density, font rendering and proportions. So it is vital to -ensure that a user experience designed on a PC looks just as brilliant on the -embedded device. In the past this was always cumbersome and required that you -manually copy the code to the device and restart the application. With QmlLive -Bench and QmlLive Runtime you simply connect to the device, propagate your -workspace and from then on all changes are reflected on the device display. Of course, -you can also connect more devices, or devices with different sizes. +A scene rendered on a machine's display rarely looks the same as on the target +display for an embedded device. There are subtle changes in the color +appearance, pixel density, font rendering, and proportions. So it is vital to +ensure that a user experience designed on a machine looks just as good on the +embedded device. In the past, this used to be a cumbersome process, requiring +that you copy the code to the embedded device and restart the application. With +QmlLive Bench and QmlLive Runtime you connect to the device, propagate your +workspace, and from there on all changes are reflected on the device's display. +You can always connect more devices, or devices with different sizes. \image runtime.png @@ -111,44 +121,43 @@ you can also connect more devices, or devices with different sizes. +- Fragment \endcode -To better structure a user interface, we normally assume a hierarchy of user -interface elements. For simplicity we name them \e display, \e screen, \e panel, -\e component, and \e fragment. They form a hierarchy from large chunks of user -interfaces to the smaller entities and internals of the user interface. The -main benefit is that it allows us to share a common vocabulary with the customers -and ensures the design is aligned with the shared definition of user interface -elements. - -We define the user interface as a root element called the display. The display -contains a collection of screens or panels, where each screen covers the entire -physical display. A screen consists of several panels providing the visual structure -defined by the design team. Each panel itself consists of a set of components, which -are reusable user interface elements. These components contain fragments, which are -user interface elements, an internal structure which is not exposed to the user -interface developer. - -Designing a user interface requires an understanding of the initial display layout +To better structure a UI, we \assume a hierarchy of UI elements. For simplicity +we name them \e display, \e screen, \e panel, \e component, and \e fragment. +These elements form a hierarchy from large UI elements to the smaller entities +and internals. The main benefit of this hierarchy, is that it allows us to +share a common vocabulary with our customers and ensures the design is always +aligned with this shared definition. + +These elements are defined as follows: + +\list + \li display - The root element that contains a collection of screens or + panels, where each screen covers the entire physical display. + \li screen - Consists of several panels that provide the visual structure + as defined by the design team. + \li panel - Each panel consists of a set of components. + \li components - Reusable UI elements that contain fragments. + \li fragments - An internal structure UI element, not exposed to the + UI developer. +\endlist + +Designing a UI requires an understanding of the initial display layout and its screen navigation structure, and of the structure of individual screens and their panels. It is also required to define a common set of components to be used inside the panels. The fragments are implementation-specific. -\section1 UX Sheets - \e{visual component testing} - - -UXSheet gives guidance on how to successfully develop user interface components with -the QmlLive live-preview technology. +\section1 UXSheets Over time, developing applications in QML can become complex, especially if -there is no clear concept for (isolated) components. Exactly the same is true -for designing user interfaces. For a successful translation of the designer's -vision into a programmer's code, the vision needs to be broken down into smaller -user interface elements (i.e. screen, panel, components and so on). Each user -interface element needs to be validated on its own and translated into source code. - -Now, to better compare this vision with what a programmer understands, a -graphics sheet can be directly implemented with Qt Quick as a series of -standalone documents collectively called a UXSheet. These sheets act as the -interface between designer and programmer. The screen below shows how a sample -sheet could look. +it is not clear how elements are isolated; this is also true for designing UIs. +To translate the designer's vision into a developer's code, the vision needs +to be broken into UI elements like screen, panel, components, and so on. Then, +these elements need to be further validated on their own; before being translated +into source code. + +To connect this vision to a developer's workflow, you can implement a graphics +sheet directly with Qt Quick, as a series of standalone documents, collectively +called a UXSheet. These sheets act as interfaces between the designer and the +developer. The screen below shows how a sample sheet could look. */ diff --git a/doc/index.qdoc b/doc/index.qdoc index 64265ce..f0c268a 100644 --- a/doc/index.qdoc +++ b/doc/index.qdoc @@ -33,58 +33,34 @@ /*! \page qmllive-index.html -\keyword QmlLive Reference Documentation \indexpage \title Qt QmlLive \section1 Overview -Qt QmlLive is a local and remote Qt Quick live reloading system. It allows you to -change your QML user interface source code and view the result in almost -realtime. +Qt QmlLive is a local and remote Qt Quick live reloading system. It allows you +to change your QML user interface source code and view the result in realtime. \image workbench.png -Often in user interface development you need to edit the placement or -animations of the user interface to provide the exact user experience -envisioned by the design team. This process of \e{try-and-error} is tedious with a -classical \e{edit-save-run-exit} cycle. With QmlLive this cycle is way more -effective. The scene is automatically reloaded when a document change is -detected. - -\quotation - -A live reloading system opens a complete new world of possibilities and makes -your work so much more delightful. - -\endquotation +Often in User Interface (UI) development you need to edit the placement or +animations to provide the user experience the design team envisions. This +process of try-and-error is tedious with the classic \e{edit-save-run-exit} +cycle. QmlLive makes this cycle more effective: the scene reloads automatically +when a file changes. \section1 Contents -The content of the documentation: - \list \li \l{Installation} - How to install QmlLive from the source code \li \l{Usage} - How to use the different parts - \li \l{Concepts} - General overview of the system - \li \l{qmllive-reference}{Reference} - The API reference to build your custom render scene + \li \l{Concepts} - A general overview of the system + \li \l{qmllive-examples}{Examples} - Try out QmlLive + \li The API reference to build your custom render scene: \list \li \l{qmllive}{QmlLive} - The QmlLive library API \li \l{ipc}{IPC} - The internal IPC API \endlist - - \li \l{qmllive-examples}{Examples} - Try out QmlLive \endlist */ - -/*! - * \page qmllive-reference - * \title API Reference - * - * - * \list - * \li \l{qmllive}{QmlLive} - * \li \l{ipc}{IPC} - * \endlist - */ diff --git a/doc/installation.qdoc b/doc/installation.qdoc index 96b2d90..bf351a7 100644 --- a/doc/installation.qdoc +++ b/doc/installation.qdoc @@ -35,7 +35,7 @@ \page qmllive-installation.html \title Installation -\section1 Dependencies +\section1 Prerequisites \list \li Windows, Linux or macOS @@ -49,18 +49,19 @@ $ make \endcode -QmlLive Bench can be started directly from build directory by executing -\c{./bin/qmllivebench}. Optionally it can be installed with +To start QmlLive Bench directly from the build directory, run +\c{./bin/qmllivebench}. Optionally, you can also install QmlLive Bench with +the following command: \code $ make install \endcode -\section1 Building for device +\section1 Build for Device -\e{Note: Only needed when you want to have live reloading enabled on the -target.} +If you want to have live reloading enabled on the target device, use the +following command: \code # using qmake from cross compiler toolchain @@ -68,29 +69,29 @@ target.} $ make \endcode -You need to cross-compile QmlLive and copy the \c{./bin/qmlliveruntime} binary onto the -target. +You need to cross-compile QmlLive and copy the \c{./bin/qmlliveruntime} binary +onto the target. -Optionally it can be packaged with the help of +Optionally, you can package QmlLive with the following command: \code $ make install INSTALL_ROOT=... \endcode -\section1 Building documentation +\section1 Build Documentation \code $ qmake CONFIG+=force_independent $ make docs \endcode -The documentation will be available at \tt{doc/qmllive/index.html}. +The documentation is available at: \tt{doc/qmllive/index.html}. -\section1 Build options reference +\section1 Build Options -The following values can be added to qmake \c CONFIG variable: +The following options can be added to the qmake \c CONFIG variable: \table \header @@ -115,30 +116,30 @@ The following values can be added to qmake \c CONFIG variable: \row \li static-link-runtime - \li Produce a single-binary QmlLive Runtime executable. Without this option - enabled QmlLive Runtime executable requires the \c libqmllive dynamic - library to be copied to the target. + \li Produce a single QmlLive Runtime executable binary. If this option is disabled, + QmlLive Runtime executable requires that the \c libqmllive dynamic library to + be copied to the target. \endtable The following custom qmake variables are recognized: \table \header - \li Variable + \li Custom Variable \li Description \row \li PREFIX - \li Installation prefix. Defaults to \c{$$[QT_INSTALL_PREFIX]}. + \li Installation prefix; defaults to \c{$$[QT_INSTALL_PREFIX]}. \row \li EXAMPLES_PREFIX - \li Installation prefix for examples. Defaults to - \c{$$[QT_INSTALL_EXAMPLES]/qmllive}. + \li Installation prefix for examples; defaults to + \c{$$[QT_INSTALL_EXAMPLES]/qmllive/examples}. \row \li QMLLIVE_VERSION_EXTRA - \li Distribution specific version description (spaces allowed). + \li Distribution specific version description; white spaces are allowed. \row \li QMLLIVE_REVISION @@ -146,8 +147,8 @@ The following custom qmake variables are recognized: \row \li QMLLIVE_SETTINGS_VARIANT - \li Overrides \c QCoreApplication::organizationName which is used to determine - application specific \c QSettings storage. + \li Overrides \c QCoreApplication::organizationName, which is used to determine + application-specific \c QSettings storage. \endtable diff --git a/doc/ipc-group.qdoc b/doc/ipc-group.qdoc index 7c9363f..8714c20 100644 --- a/doc/ipc-group.qdoc +++ b/doc/ipc-group.qdoc @@ -34,11 +34,12 @@ /*! \module ipc - \title IPC Related Classes - \brief A simple IPC solution for calling method on remote objects. + \title IPC related classes + \brief A simple IPC solution to call methods on remote objects. - The IPC is based on the idea to have a server with individual connections - to clients and a client. The server is waiting for method calls from the - client and the client allows to send methods with additional data. + The Inter-Process Communication (IPC) is based on the idea to have a server + with individual connections to clients and a client. The server waits for + method calls from the client and the client lets you send methods with + additional data. */ diff --git a/doc/qmllive-group.qdoc b/doc/qmllive-group.qdoc index 1692595..9fad76b 100644 --- a/doc/qmllive-group.qdoc +++ b/doc/qmllive-group.qdoc @@ -35,8 +35,8 @@ \module qmllive \title QmlLive Module - \brief Classes for watching a workspace and for local and remote reloading - of Qt Quick user interfaces. + \brief Classes for watching a workspace, as well as for local and remote + reloading of Qt Quick User Interfaces. The QmlLive module allows a developer to quickly create his own instance of a QmlLive workbench or a QmlLive runtime. |