diff options
| -rw-r--r-- | doc/concepts.qdoc | 249 | ||||
| -rw-r--r-- | doc/images/client.png | bin | 60531 -> 0 bytes | |||
| -rw-r--r-- | doc/images/concept.png | bin | 68871 -> 42580 bytes | |||
| -rw-r--r-- | doc/images/runtime.png | bin | 193192 -> 215209 bytes | |||
| -rw-r--r-- | doc/images/workbench.png | bin | 335948 -> 153687 bytes | |||
| -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 |
9 files changed, 200 insertions, 155 deletions
diff --git a/doc/concepts.qdoc b/doc/concepts.qdoc index 26d79c6..1013e4c 100644 --- a/doc/concepts.qdoc +++ b/doc/concepts.qdoc @@ -35,120 +35,187 @@ \page qmllive-concepts.html \title Concepts +The following are some concepts that are helpful to understand QmlLive. + +\list + \li \l{Live Reloading} + \li \l{QmlLive Bench vs QmlLive Runtime} + \li \l{Local Sessions} + \li \l{Remote Sessions} + \li \l{Create Your Own QmlLive Runtime} + \li \l{Structure QML Apps For Live Coding} +\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 supports live coding with two essential features: +\list + \li Allows you to distribute source code modifications, removing the need + to redeploy your application to see the effect of your changes. QmlLive monitors + changes in the file system. As soon as you save a file, it is preprocessed as + needed, and the live view is refreshed. + \li Loads a particular QML file with your required component instead of the main + component, so that each component can be worked on independently. +\endlist + +After each code change, QmlLive reloads your project on each connected device, +within seconds. + +\section1 QmlLive Bench vs. QmlLive Runtime + +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. + +For sketching out the scene or working with independent UI elements, the QmlLive +Bench is sufficient; you can see the live preview on your local machine. + +\table + \header + \li QmlLive Feature + \li Description + \row + \li QmlLive Bench + \li A GUI server application that populates workspace + updates to each local or remote client. + \row + \li QmlLive Runtime + \li A client application that listens to workspace updates from the + QmlLive Bench. +\endtable + +If the application being developed should run on any embedded device or +devices with different display resolutions, then you must launch the QmlLive Runtime +on each embedded device. But, you only need to launch the QmlLive Bench on the +developer's machine. + +QmlLive Bench supports the following features: +\list + \li live reload a \c main file, or a selected component + \li watch workspace updates + \li provide a GUI to set a workspace or project settings, configure host connections, + import paths, and so on + \li Publish each file change to all local and remote QmlLive Runtimes on the + embedded devices + \li lets the user select different files to watch, for certain QmlLive Runtime + instances, on different connected devices + \li follows the currently watched file, on the connected devices + \li grabs log messages from all connected QmlLive Runtimes, to enable a more + convenient debugging process + \li lets the user select a file to watch, through the Workspace Navigator + \li controls connections to all of the devices +\endlist + +QmlLive Runtime supports the following features: +\list + \li live reload a \c main file, or a selected component + \li listens workspace updates from the QmlLive Bench +\endlist \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. - -\image client.png - - -\section1 Remote Sessions - \e{putting delight on your devices} - -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. +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. + +\section1 Remote Sessions + +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 -\section1 Display, Screens, Panels, Components, Fragments +\section1 Create Your Own QmlLive Runtime + +Some projects include custom C++ or native code. Those languages require a +compilation step and cannot be reloaded directly with QmlLive reloading. For +such case you can develop you own QmlLive Runtime based on the QmlLive library. +For more details see \l{Custom Runtime}. + +\section1 Structure QML Apps For Live Coding + +Over time, developing applications in QML can become complex, especially if +it's 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 \e display, \e screen, \e panel, \e component, +and \e fragment. \code +- Display - | - +- Panel - | - +- Screen - | - +- Panel - | - +- Component - | - +- Fragment + | + +- Panel + | + +- Screen + | + +- Panel + | + +- Component + | + +- 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 +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. -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. - -*/ diff --git a/doc/images/client.png b/doc/images/client.png Binary files differdeleted file mode 100644 index 1192b0f..0000000 --- a/doc/images/client.png +++ /dev/null diff --git a/doc/images/concept.png b/doc/images/concept.png Binary files differindex dec994d..936a900 100644 --- a/doc/images/concept.png +++ b/doc/images/concept.png diff --git a/doc/images/runtime.png b/doc/images/runtime.png Binary files differindex 41804af..3aa98f1 100644 --- a/doc/images/runtime.png +++ b/doc/images/runtime.png diff --git a/doc/images/workbench.png b/doc/images/workbench.png Binary files differindex 9c4ec78..be9455c 100644 --- a/doc/images/workbench.png +++ b/doc/images/workbench.png 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. |
