Doc: Add Qt Design Studio Manual sources

To build the manual, switch to qtcreator\doc\qtdesignstudiodoc,
run qmake, and then "make docs".

The example documentation does not get built with this change.
We need to decide whether to move the examples or fetch their
docs from the other repository.

Task-number: QDS-1487
Change-Id: Ic0a8c15b226eba8ac90686953568f3deaa000fb0
Reviewed-by: Eike Ziller <eike.ziller@qt.io>
Reviewed-by: Tim Jenssen <tim.jenssen@qt.io>

1 files changed, 258 insertions, 0 deletions

diff --git a/doc/qtdesignstudio/src/qtbridge/qtbridge-ps-using.qdoc b/doc/qtdesignstudio/src/qtbridge/qtbridge-ps-using.qdoc
new file mode 100644
index 0000000000..754a73f635
--- /dev/null
+++ b/doc/qtdesignstudio/src/qtbridge/qtbridge-ps-using.qdoc
@@ -0,0 +1,258 @@
+/****************************************************************************
+**
+** Copyright (C) 2019 The Qt Company Ltd.
+** Contact: https://www.qt.io/licensing/
+**
+** This file is part of the Qt Bridge 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.
+**
+****************************************************************************/
+
+/*!
+    \contentspage {Qt Design Studio Manual}
+    \previouspage qtbridge-ps-setup.html
+    \page qtbridge-ps-using.html
+    \nextpage sketchqtbridge.html
+
+    \title Using \QBPS
+
+    \section1 Organizing Assets
+
+    To get the best results when you use \QBPS to export designs from Adobe
+    Photoshop to \QDS, follow these guidelines when working with Photoshop:
+
+    \list
+        \li Arrange your art into artboards and organize it into groups and
+            layers that are imported into \QDS as separate files, depending
+            on the choices you make when exporting designs.
+        \li Use the Type tool to make sure that all of your text labels
+            are exported to \l Text items.
+        \li Store all assets in vector format to be able to easily rescale them
+            for different screen sizes and resolutions.
+    \endlist
+
+    If you would rather use Adobe Illustrator for creating artwork, you can
+    copy-paste your assets to Adobe Photoshop as \e {smart objects}. You can
+    then double-click the smart objects in Photoshop to open them in Illustrator
+    for editing. Because you use smart objects, all your changes are propagated
+    to all instances of the objects used in your designs in Photoshop.
+
+    To use the fonts that you use in Photoshop also in \QDS, you need to load
+    them to \QDS. \QDS deploys them to devices when you preview the UI. For more
+    information, see \l{Using Custom Fonts}.
+
+    \section2 Using Artboards
+
+    The relationships between the groups and layers on an artboard are preserved
+    when you export designs from Adobe Photoshop and import them into \QDS.
+
+    When you use \QBPS to export your designs, you will determine how you want
+    each group or layer exported: as a \e component or \e child. A component is
+    a single QML file that can contain other assets. A child is a single PNG
+    file that you can use within QML files.
+
+    If you plan to use pieces of your artwork as separate images in the UI,
+    group them on an artboard as separate layers. You can then export the group
+    as a component and each layer within it as a child. The children are
+    imported to \QDS as separate PNG files that you can use as image sources.
+
+    To use the contents of an artboard as a single image in the UI, you can
+    merge the groups and layers when you export them. During import, the
+    contents are flattened into one PNG file. The merge is done in a way that
+    enables you to change the groups and layers in Photoshop or Adobe
+    Illustrator and then export and import the artboard again. This is an easy
+    way to create a reference image of how the final UI should look like, for
+    example.
+
+    Place different parts of the UI, such as menus and pop-ups, on separate
+    artboards to be able to export them as components or children and to
+    import them as QML and PNG files that you can drag and drop to the working
+    area in \QDS Design mode while creating a UI.
+
+    \QDS offers predefined sets of UI controls that you can modify according
+    to your needs. You can export your own controls as QML types, Qt Quick
+    Controls, or Studio Components. The position and dimensions of your control
+    are preserved.
+
+    However, if you want your UI controls, such as check boxes, to look exactly
+    like they do in Photoshop, you have to create the control in an Artboard and
+    use the artboard in the layers where the control instance is to be created.
+    \QB exports the control as a custom QML component that you can program in
+    \QDS.
+
+    \section1 Exporting Assets
+
+    Each artboard is exported automatically as a component. That is, a separate
+    QML file that contains all the artwork on the artboard, except layers that
+    are set to be skipped or exported as child items. You determine how
+    each group or layer in an artboard is exported: as a component or a child
+    item. In addition, you can merge the groups and layers of an artboard
+    into the parent as one item or skip layers completely.
+
+    By default, layers are exported as follows:
+
+    \list
+        \li First level group layers are exported as child items of the
+            artboard.
+        \li Second level group layers are merged to their parent.
+        \li Asset layers are exported as merged.
+        \li Text layers are always exported as child items.
+    \endlist
+
+    \QBPS automatically proposes identifiers (QML ids) for all groups and layers.
+    The ids will be used as filenames in \QDS. You can change the ids, so that
+    you can easily find them in \QDS. Just keep in mind that the ids must be
+    unique and that they must follow some naming conventions.
+
+    You can export assets using the default settings and make all the changes
+    later in \QDS. If you are familiar with the \l{QML Syntax Basics}
+    {QML syntax}, you can modify the settings to tailor the generated QML to
+    a certain degree. For example, you can specify the QML type or Studio
+    component to use for a component or layer. If you have drawn an arc that
+    you mean to animate, you can export it as an Arc Studio component to avoid
+    having to replace the arc image with an Arc component in \QDS. Or you could
+    export a button as a Qt Quick Controls 2 Button type.
+
+    You can specify effects, such as a blur effect, to use for a group or layer.
+
+    The QML types supported by \QDS are listed in the \uicontrol {QML Types}
+    tab in the \uicontrol Library in the Design mode of \QDS. For more
+    information, see \l{Creating Components}.
+
+    You can also specify values for the properties of the QML type or create
+    \l{Property Aliases}{property aliases} to fetch the values from other
+    properties.
+
+    \image qt-bridge.png
+
+    \section2 Specifying Settings for Exporting Assets
+
+    To export your design using \QBPS:
+
+    \list 1
+        \li \QBPS automatically proposes identifiers for all groups and layers
+            that you can change in the \uicontrol {QML ID} field. The ids must
+            be unique, they must begin with a lower-case letter or an
+            underscore, and they can only contain letters, numbers, and
+            underscore characters. For more information, see
+            \l {The id Attribute}.
+        \li In the \uicontrol {Export As} field, select the export type for the
+            group or layer:
+            \list
+                \li \uicontrol Component creates a separate QML file for the
+                    selected artboard, group, or layer that contains all the
+                    artwork in it, except layers that are set to be skipped or
+                    exported as child items.
+                \li \uicontrol Child creates a separate PNG file for each asset
+                    of the selected group or layer, with references to the
+                    images in the component file.
+                \li \uicontrol Merged merges the selected groups and layers into
+                    the parent as one item.
+                \li \uicontrol Skipped completely skips the selected layer.
+            \endlist
+        \li In the \uicontrol {As Artboard} field, select an artboard
+            to reuse. For example, you can use an artboard to define a
+            component, such as a button, and reuse it in other artboards.
+        \li In the \uicontrol {QML Type} field, specify the QML type
+            or Studio component to morph this layer into. The generated
+            component will be of this type. For example, if you drew a
+            rectangle, you can export it as a Rectangle Studio component.
+            You can provide the import statement of the module where the QML
+            type is defined in the \uicontrol {Add Imports} field.
+        \li In the \uicontrol {Add Imports} field, enter additional
+            import statements to have them added to the generated QML file.
+            For example, to use Qt Quick Controls 2.3, you need the import
+            statement \c {QtQuick.Controls 2.3} and to use Qt Studio
+            Components 1.0, you need the import statement
+            \c {QtQuick.Studio.Components 1.0}. You can also import a module
+            as an alias.
+        \li In the \uicontrol {QML Properties} field, specify properties for
+            the QML type. You can add and modify properties in \QDS.
+        \li Select the \uicontrol {Clip Contents} check box to enable clipping
+            in the type generated from the layer. The generated type will clip
+            its own painting, as well as the painting of its children, to its
+            bounding rectangle.
+        \li Select the \uicontrol {Create Alias} check box to export the item
+            generated from this layer as an alias in the parent component.
+        \li Select \uicontrol {Cascade properties} to apply the current set of
+            properties to all the children of the selected layer.
+        \li Select \uicontrol Export to copy your assets to the export path you
+            specified.
+        \li When the exporting is done, select \uicontrol OK.
+    \endlist
+
+    All the assets and metadata are copied to the directory you specified. This
+    might take a little while depending on the complexity of your project.
+
+    You can now create a project in \QDS and import the assets to it, as
+    described in \l {Creating Projects} and \l{Importing Designs}.
+
+    \section1 Sanitizing Documents
+
+    \QBPS enables removing all \QBPS related metadata from the active
+    document. In the \QBPS \uicontrol Settings dialog, select
+    \uicontrol {Sanitize Document} to sanitize the active document.
+    Once the sanitization is successfully done, the document will
+    contain no \QBPS related metadata and the \QBPS layer settings will fall
+    back to the \l{Exporting Assets}{default} values.
+
+    \note The sanitization is done in memory and the document must be saved to
+    keep the sanitized state.
+
+    \image qt-bridge-sanitize.png
+
+    \section1 Extending \QBPS
+    You can change the default behavior of \QBPS with the help of a JSX script. One can write
+    specific functions in the script that are called by \QBPS with useful parameters.
+
+    \section2 Overridable JSX Functions
+    You can define the following functions in the override JSX.
+    \list
+        \li preExport(document)
+            This function is called before the document is exported. The parameter \a document is
+            the PSD Document instance. This function can be used to make temporary changes in
+            the document before export.
+        \li postExport(document)
+            This function is called after the document is exported. The parameter \a document is the
+            PSD Document instance. You can undo the temporary changes done in the function
+            \e preExport(...).
+        \li customDefaultQmlId(name, instance)
+            The function is called for settings the default QML id of the layer. The returned value
+            is used for the QML id. Return \e Falsey to use the auto generated QML id instead.
+            The parameter \a name is the auto generated QML id by the plugin and \a instance is the
+            PSD layer instance.
+    \endlist
+
+    \note Please refer to \l {https://www.adobe.com/devnet/photoshop/scripting.html}
+    {Adobe Photoshop CC Javascript} scripting guide to understand the object model and \e Document
+    and \e Layer instances.
+
+    \image qt-bridge-override.png
+
+    In the \QBPS \uicontrol Settings dialog, select \uicontrol {Override JSX Script} to set the
+    override JSX script.
+
+    For more information, watch a video tutorial and webinar about using \QBPS:
+
+    \list
+        \li \l{https://resources.qt.io/development-topic-ui-design/qtdesignstudio-clustertutorial-partone}
+            {Building an Instrument Cluster for Your Car HMI, Part 1}
+        \li \l{https://www.youtube.com/watch?v=ZzbucmQPU44}
+            {From Photoshop to Prototype with Qt Design Studio}
+    \endlist
+*/