From 80b04b8248bb09dc6ea20a212359ea6e1b321af2 Mon Sep 17 00:00:00 2001 From: Leena Miettinen Date: Thu, 11 Jun 2020 10:41:24 +0200 Subject: Doc: Describe designing application flows in Design mode Fixes: QDS-1541 Change-Id: I8b4c83f6548414063670303d2d83e7dd5f93d0d8 Reviewed-by: Thomas Hartmann --- doc/qtcreator/src/qtquick/qtquick-components.qdoc | 2 +- doc/qtcreator/src/qtquick/qtquick-uis.qdoc | 14 +- doc/qtdesignstudio/images/icon-event-list.png | Bin 0 -> 239 bytes doc/qtdesignstudio/images/studio-flow-decision.png | Bin 0 -> 40618 bytes .../images/studio-flow-event-list.png | Bin 0 -> 10092 bytes doc/qtdesignstudio/images/studio-flow-view.png | Bin 0 -> 292721 bytes .../src/qtdesignstudio-app-flows.qdoc | 287 +++++++++++++++++++++ doc/qtdesignstudio/src/qtdesignstudio-toc.qdoc | 1 + doc/qtdesignstudio/src/qtdesignstudio.qdoc | 1 + 9 files changed, 303 insertions(+), 2 deletions(-) create mode 100644 doc/qtdesignstudio/images/icon-event-list.png create mode 100644 doc/qtdesignstudio/images/studio-flow-decision.png create mode 100644 doc/qtdesignstudio/images/studio-flow-event-list.png create mode 100644 doc/qtdesignstudio/images/studio-flow-view.png create mode 100644 doc/qtdesignstudio/src/qtdesignstudio-app-flows.qdoc (limited to 'doc') diff --git a/doc/qtcreator/src/qtquick/qtquick-components.qdoc b/doc/qtcreator/src/qtquick/qtquick-components.qdoc index ca4a6e6d89..b601b96a28 100644 --- a/doc/qtcreator/src/qtquick/qtquick-components.qdoc +++ b/doc/qtcreator/src/qtquick/qtquick-components.qdoc @@ -32,7 +32,7 @@ /*! \page quick-components.html \if defined(qtdesignstudio) - \previouspage quick-uis.html + \previouspage studio-app-flows.html \else \previouspage creator-using-qt-quick-designer.html \endif diff --git a/doc/qtcreator/src/qtquick/qtquick-uis.qdoc b/doc/qtcreator/src/qtquick/qtquick-uis.qdoc index e681a32bc0..5a80438259 100644 --- a/doc/qtcreator/src/qtquick/qtquick-uis.qdoc +++ b/doc/qtcreator/src/qtquick/qtquick-uis.qdoc @@ -27,10 +27,11 @@ \page quick-uis.html \if defined(qtdesignstudio) \previouspage quick-converting-ui-projects.html + \nextpage studio-app-flows.html \else \previouspage creator-using-qt-quick-designer.html - \endif \nextpage quick-components.html + \endif \title Creating UIs @@ -58,6 +59,17 @@ \list + \if defined(qtdesignstudio) + \li \l {Designing Application Flows} + + After you export and import your artwork, you can design the + application flow in the form of a \e {schematic diagram} that + shows all significant components of an application UI and their + interconnections by means of symbols. This results in an + interactive prototype that can be clicked through to simulate + the user experience of the application. + \endif + \li \l {Creating Components} In addition to your imported artwork, you can use the Design diff --git a/doc/qtdesignstudio/images/icon-event-list.png b/doc/qtdesignstudio/images/icon-event-list.png new file mode 100644 index 0000000000..b4d2849460 Binary files /dev/null and b/doc/qtdesignstudio/images/icon-event-list.png differ diff --git a/doc/qtdesignstudio/images/studio-flow-decision.png b/doc/qtdesignstudio/images/studio-flow-decision.png new file mode 100644 index 0000000000..47e003544c Binary files /dev/null and b/doc/qtdesignstudio/images/studio-flow-decision.png differ diff --git a/doc/qtdesignstudio/images/studio-flow-event-list.png b/doc/qtdesignstudio/images/studio-flow-event-list.png new file mode 100644 index 0000000000..4a27d30ffc Binary files /dev/null and b/doc/qtdesignstudio/images/studio-flow-event-list.png differ diff --git a/doc/qtdesignstudio/images/studio-flow-view.png b/doc/qtdesignstudio/images/studio-flow-view.png new file mode 100644 index 0000000000..fc32482c3c Binary files /dev/null and b/doc/qtdesignstudio/images/studio-flow-view.png differ diff --git a/doc/qtdesignstudio/src/qtdesignstudio-app-flows.qdoc b/doc/qtdesignstudio/src/qtdesignstudio-app-flows.qdoc new file mode 100644 index 0000000000..0015d7a793 --- /dev/null +++ b/doc/qtdesignstudio/src/qtdesignstudio-app-flows.qdoc @@ -0,0 +1,287 @@ +/**************************************************************************** +** +** Copyright (C) 2020 The Qt Company Ltd. +** Contact: https://www.qt.io/licensing/ +** +** This file is part of the Qt Creator documentation. +** +** Commercial License Usage +** Licensees holding valid commercial Qt licenses may use this file in +** accordance with the commercial license agreement provided with the +** Software or, alternatively, in accordance with the terms contained in +** a written agreement between you and The Qt Company. For licensing terms +** and conditions see https://www.qt.io/terms-conditions. For further +** information use the contact form at https://www.qt.io/contact-us. +** +** GNU Free Documentation License Usage +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of +** this file. Please review the following information to ensure +** the GNU Free Documentation License version 1.3 requirements +** will be met: https://www.gnu.org/licenses/fdl-1.3.html. +** +****************************************************************************/ + +/*! + \page studio-app-flows.html + \previouspage quick-uis.html + \nextpage quick-components.html + + \title Designing Application Flows + + After you \l {Exporting Artwork from Design Tools}{export} your artwork from + your favorite design tool and \l{Importing Designs}{import} it to \QDS, you + can design the application flow in the form of a \e {schematic diagram} that + shows all significant components of an application UI and their + interconnections by means of symbols. This results in an interactive + prototype that can be clicked through to simulate the user experience of + the application. The QML code is created in the background and can be used + as the base of the production version of the application. + + \image studio-flow-view.png "Application flow in Form Editor" + + In \QDS, a \e {flow view} represents a schematic diagram. It consists of + \e {flow items} that represent the screens in the UI and \e {transition + lines} that connect them, thus illustrating the possible user pathways + through the UI. You use \e {action areas} as starting points for transition + lines. You can attach effects to transition lines, such as fade or push, + to determine what users see when one screen changes into another. + + You can use \e {flow decisions} to set up alternative pathways between + screens in the UI. For example, if user input determines which screen + should open next, you can test the different scenarios in the prototype + by having a dialog pop up, where you can select which screen to show next. + + Especially on mobile and embedded platforms, the application might need to + react to external events from the platform, such as notifications or other + applications requiring the users' attention. You can use \e {flow wildcards} + to determine the priority of screens by whitelisting or blacklisting them. + + \section1 Creating Flows + + You can add a flow view to an existing project or create a new project + for it, as described in \l {Creating Projects}. To create the flow + view, select \uicontrol File > \uicontrol {New File or Project} > + \uicontrol {Files and Classes} > \uicontrol {Qt Quick Files} > + \uicontrol {Flow View} and follow the instructions of the wizard. + + You only need to select the \uicontrol {Use event simulator} check box if + you want to add an event simulator to the flow view. + + The flow view properties enable you to adjust the appearance of all + the items in the flow: action areas, transition lines, decisions, and + wildcards. You can change the global settings for all items by editing + flow view properties, or you can select an individual action area or + transition line and change the appearance of just that item, including + the color, line thickness, dotted or solid lines, and even the curve of + the connections. This enables you to add extra semantics to the design + of the flow diagram itself. + + \section1 Adding Flow Items + + If you imported your screen designs from a design tool as individual + components (\e {.ui.qml} files), you can use them as content for flow + items. If you are building your UI from scratch in \QDS, you must first + create the screens as you would any QML components. For more information, + see \l {Creating Components}. The flow items that you attach the components + to are listed under \uicontrol {My QML Components}. + + To add flow items: + + \list 1 + \li Import your UI screens from a design tool or create them in + \uicontrol {Form Editor} and save each screen as a separate + QML component. + \li Select \uicontrol File > \uicontrol {New File or Project} > + \uicontrol {Files and Classes} > \uicontrol {Qt Quick Files} > + \uicontrol {Flow Item} and follow the instructions of the wizard + to create flow items for each screen in the UI. + \li Drag a screen from \uicontrol Library > + \uicontrol {My QML Components} to each flow item in + \uicontrol {Form Editor} or \uicontrol Navigator. + \li In \uicontrol Properties, edit the properties globally for all + flow items, action areas, or transition lines in the flow view. + \endlist + + To include another flow view into a flow view, select the \e {.ui.qml} file + that specifies the flow view in the \uicontrol {Loader source} field in + \uicontrol Properties. + + You can now drag the flow items from \uicontrol Library > + \uicontrol {My QML Components} to the flow view in \uicontrol {Form Editor} + or \uicontrol Navigator. When you have all the screens in place, you can + add action areas to them to create transitions between them. + + \section1 Adding Action Areas and Transitions + + \e {Action areas} can act as clickable areas that initiate transitions + between screens or they can create connections to any signal from any + component in a flow item. For example, you could connect an action + to the \c onPressed signal of a button in your screen. + + Typically, a screen can be connected to several other screens in the flow, + with two-way connections. To avoid clutter, you can set an action area as + \e {go back}, instead of adding explicit transition lines to and from + every potentially connected screen. When the \uicontrol {Go back} option is + enabled, the transition will always take the user back to the previous + screen. + + To create action areas: + + \list 1 + \li Right-click the flow item in \uicontrol {Form Editor} and select + \uicontrol {Flow} > \uicontrol {Create Flow Action} in the context + menu. + \li Drag the action area to the screen control that you want to connect + to the other screen. For example, to a button that opens another + screen when clicked. + \li Double-click the action area and drag the transition line to the + flow item you want to connect to. + \li In \uicontrol Properties, modify the properties of the action area + and transition line. + \endlist + + To preview the flow, select the \inlineimage live_preview.png + (\uicontrol {Show Live Preview}) button on the \uicontrol {Form Editor} + toolbar or press \key {Alt+P}. + + \section1 Applying Effects to Transitions + + You can apply effects, such as fade, move, or push to transitions. A fade + effect makes the first screen appear to fade out, while the next screen + fades in. A move effect makes the second screen appear to move in over the + first screen, while the push effect appears to make a screen push out the + previous one. You can also design and use custom effects. + + The transition direction determines the direction the new screen appears + from: left, right, top, bottom. You can set the duration of the effect and + \l{Editing Easing Curves}{attach an easing curve} to the effect. + + To add effects: + + \list 1 + \li Select a transition line in \uicontrol {Form Editor}. + \li In the context menu, select \uicontrol {Flow} > + \uicontrol {Assign Flow Effects}, and then select the effect + to apply. + \li In \uicontrol Properties, modify the properties of the effect. + \endlist + + To edit effect properties, select a transition, and then select + \uicontrol {Flow} > \uicontrol {Select Effect} in the context menu. + + \section1 Simulating Events + + While transition lines are useful for prototyping, in production you need to + use the real signals from UI screens to control the flow of the application. + For this purpose, you can use action areas in a more advanced way, by + having them listen to signals from screens or the controls in them and + by connecting these to the flow view. You can use keyboard shortcuts to + simulate these events when you preview the UI. + + When you use the wizard to create a \uicontrol {Flow View} item, select the + \uicontrol {Use event simulator} check box to add an event simulator to the + flow view. + + You can create an event list where you assign keyboard shortcuts to events, + and then use context-menu commands to attach the events to action areas or + transition lines. + + To create an event list: + + \list 1 + \li In \uicontrol Navigator, select the \uicontrol EventListSimulator + type, and then select the \uicontrol Active check box in + \uicontrol Properties to activate the event simulator. + \li Select the \inlineimage icon-event-list.png + (\uicontrol {Show Event List}) button on the Design mode toolbar, + or press \key {Alt+E}. + \image studio-flow-event-list.png "Event List Dialog" + \li Select \inlineimage plus.png + to add a keyboard shortcut for triggering an event to the list. + \li In the \uicontrol Id field, enter an identifier for the event. + \li In the \uicontrol Shortcut field, press the keyboard key that will + trigger the event, and then select \uicontrol R to record the + keyboard shortcut. The key identifier appears in the field. + \li In the \uicontrol Description field, describe the keyboard shortcut. + \endlist + + You can now assign the events to the action areas in the flow to use the + keyboard shortcuts to trigger events when you preview the UI. + + To assign events to actions: + + \list 1 + \li In \uicontrol Navigator, select an action area or transition line. + \li In the context menu, select \uicontrol {Flow} > + \uicontrol {Event List} > \uicontrol {Assign Events to Actions}. + \li Select an event in the list, and then select \uicontrol Accept. + \li Press \key {Alt+P} to preview the UI. + \li Double-click events in the event list or use the keyboard shortcuts + to trigger events. + \endlist + + \section1 Simulating Conditions + + Part of any complex UI is the conditional logic it uses to present its + state to users or to collect and process data from various sources. Data + can be produced by user interaction from a variety of inputs, such as + buttons and controls, sensor readings from arrays of equipment, or general + values received from backend or service APIs. + + The \uicontrol {Flow Decision} type simulates conditions by displaying a + list of options you can choose from when you preview the flow. This enables + you to prototype complex interactions before you have access to the physical + controls, backend, or sensor data that will be required for the production + version. + + To simulate conditions: + + \list 1 + \li Select the screen where you want the application to start in + \uicontrol Navigator or \uicontrol {Form Editor}, and then select + \uicontrol {Flow} > \uicontrol {Add Start} in the context menu. + \li Create an action area for the component that will trigger the + condition and connect it to the flow decision. + \li Drag a \uicontrol {Flow Decision} QML type from \uicontrol Library + to a flow view in \uicontrol Navigator or \uicontrol {Form Editor}. + \li Select \uicontrol Connect in the context menu to create connections + to the screens that will open depending on whether the condition is + met. + \li In \uicontrol Properties, \uicontrol Title field, enter a title for + the selection dialog that opens when the condition is triggered. + \li Select a transition line and add a descriptive text in the + \uicontrol {Question} field to represent a choice in the selection + dialog. + \li Press \key {Alt+P} to preview the UI. + \endlist + + When you preview the UI, you can click the action areas to display a dialog + that you can use to select which condition is met and see the results. + + \image studio-flow-decision.png + + \section1 Reacting to External Events + + On mobile and embedded platforms, applications are usually integrated into + the platform, and therefore screens might pop-up from anywhere or at any + time, based on a conditional event. For example, push notifications + appear on mobile devices and incoming call screens on a car's HMI. + + You can use the \uicontrol {Flow Wildcard} type to model this type of + screens in your flow, using real or simulated signals and conditions. You + can whitelist or blacklist wildcard events to prioritize them and stop some + screens from appearing on others. For example, you could block the incoming + call screen from appearing on a warning screen for the engine, if you + consider the warning more important. + + To use wildcards: + + \list 1 + \li Drag a \uicontrol {Flow Wildcard} QML type from \uicontrol Library + to a flow view in \uicontrol Navigator or \uicontrol {Form Editor}. + \li In \uicontrol Properties, add screens to the white and black list + for the screen. + \endlist +*/ diff --git a/doc/qtdesignstudio/src/qtdesignstudio-toc.qdoc b/doc/qtdesignstudio/src/qtdesignstudio-toc.qdoc index 0c20610a1d..0d2de98a0f 100644 --- a/doc/qtdesignstudio/src/qtdesignstudio-toc.qdoc +++ b/doc/qtdesignstudio/src/qtdesignstudio-toc.qdoc @@ -69,6 +69,7 @@ \endlist \li \l{Creating UIs} \list + \li \l{Designing Application Flows} \li \l{Creating Components} \list \li \l{Editing 2D Content} diff --git a/doc/qtdesignstudio/src/qtdesignstudio.qdoc b/doc/qtdesignstudio/src/qtdesignstudio.qdoc index 5425477f9e..4ad8ecb22f 100644 --- a/doc/qtdesignstudio/src/qtdesignstudio.qdoc +++ b/doc/qtdesignstudio/src/qtdesignstudio.qdoc @@ -57,6 +57,7 @@ \endlist \li \b {\l{Creating UIs}} \list + \li \l{Designing Application Flows} \li \l{Creating Components} \li \l{Managing Item Hierarchy} \li \l{Specifying Item Properties} -- cgit v1.2.3