Doc: Add Qt-Bridge plugin docs for adobe XD

Task-number: QDS-4615
Change-Id: Ie3c7d814fbf59841f112315cf71553076ec7e0d7
Reviewed-by: Leena Miettinen <riitta-leena.miettinen@qt.io>

14 files changed, 344 insertions, 2 deletions

diff --git a/doc/config/macros.qdocconf b/doc/config/macros.qdocconf
index 22c0c182cc..4ae4dc1617 100644
--- a/doc/config/macros.qdocconf
+++ b/doc/config/macros.qdocconf
@@ -20,6 +20,7 @@ macro.Q3DS              = "Qt 3D Studio"
 macro.QA                = "Qt Assistant"
 macro.QB                = "Qt Bridge"
 macro.QBPS              = "Qt Bridge for Adobe Photoshop"
+macro.QBXD              = "Qt Bridge for Adobe XD"
 macro.QBSK              = "Qt Bridge for Sketch"
 macro.QBF               = "Qt Bridge for Figma"
 macro.QC                = "$IDE_DISPLAY_NAME"
diff --git a/doc/qtdesignstudio/images/qt-bridge-xd-home.png b/doc/qtdesignstudio/images/qt-bridge-xd-home.png
new file mode 100644
index 0000000000..2d4dfa20db
--- /dev/null
+++ b/doc/qtdesignstudio/images/qt-bridge-xd-home.png
diff --git a/doc/qtdesignstudio/images/qt-bridge-xd-menu.png b/doc/qtdesignstudio/images/qt-bridge-xd-menu.png
new file mode 100644
index 0000000000..8345543fb6
--- /dev/null
+++ b/doc/qtdesignstudio/images/qt-bridge-xd-menu.png
diff --git a/doc/qtdesignstudio/images/qt-bridge-xd-settings.png b/doc/qtdesignstudio/images/qt-bridge-xd-settings.png
new file mode 100644
index 0000000000..6c16f50f40
--- /dev/null
+++ b/doc/qtdesignstudio/images/qt-bridge-xd-settings.png
diff --git a/doc/qtdesignstudio/images/qt-bridge-xd-warn.png b/doc/qtdesignstudio/images/qt-bridge-xd-warn.png
new file mode 100644
index 0000000000..18a79320d4
--- /dev/null
+++ b/doc/qtdesignstudio/images/qt-bridge-xd-warn.png
diff --git a/doc/qtdesignstudio/images/qt-bridge-xd.png b/doc/qtdesignstudio/images/qt-bridge-xd.png
new file mode 100644
index 0000000000..c9a0b72676
--- /dev/null
+++ b/doc/qtdesignstudio/images/qt-bridge-xd.png
diff --git a/doc/qtdesignstudio/images/xd-logo.png b/doc/qtdesignstudio/images/xd-logo.png
new file mode 100644
index 0000000000..07a189bc0f
--- /dev/null
+++ b/doc/qtdesignstudio/images/xd-logo.png
diff --git a/doc/qtdesignstudio/src/qtbridge/qtbridge-overview.qdoc b/doc/qtdesignstudio/src/qtbridge/qtbridge-overview.qdoc
index db4800d66a..bc27d5e348 100644
--- a/doc/qtdesignstudio/src/qtbridge/qtbridge-overview.qdoc
+++ b/doc/qtdesignstudio/src/qtbridge/qtbridge-overview.qdoc
@@ -52,11 +52,13 @@
     \row
         \li \inlineimage ai-logo.png
         \li \inlineimage ps-logo.png
+        \li \inlineimage xd-logo.png
         \li \inlineimage sketch-logo.png
         \li \inlineimage figma-logo.png
     \row
         \li \l{Exporting Designs from Adobe Illustrator}{Adobe Illustrator}
         \li \l{Exporting Designs from Adobe Photoshop}{Adobe Photoshop}
+        \li \l{Exporting Designs from Adobe XD}{Adobe XD}
         \li \l{Exporting Designs from Sketch}{Sketch}
         \li \l{Exporting Designs from Figma}{Figma}
     \endtable
diff --git a/doc/qtdesignstudio/src/qtbridge/qtbridge-ps-using.qdoc b/doc/qtdesignstudio/src/qtbridge/qtbridge-ps-using.qdoc
index f335cd7370..87a9904cc8 100644
--- a/doc/qtdesignstudio/src/qtbridge/qtbridge-ps-using.qdoc
+++ b/doc/qtdesignstudio/src/qtbridge/qtbridge-ps-using.qdoc
@@ -26,7 +26,7 @@
 /*!
     \previouspage qtbridge-ps-setup.html
     \page qtbridge-ps-using.html
-    \nextpage sketchqtbridge.html
+    \nextpage xdqtbridge.html
 
     \title Using \QBPS
 
diff --git a/doc/qtdesignstudio/src/qtbridge/qtbridge-sketch-overview.qdoc b/doc/qtdesignstudio/src/qtbridge/qtbridge-sketch-overview.qdoc
index 4f626c1af0..6de2217da4 100644
--- a/doc/qtdesignstudio/src/qtbridge/qtbridge-sketch-overview.qdoc
+++ b/doc/qtdesignstudio/src/qtbridge/qtbridge-sketch-overview.qdoc
@@ -26,7 +26,7 @@
 // Note: The \page value is hard-coded as a link in Qt Bridge for Sketch.
 
 /*!
-    \previouspage qtbridge-ps-using.html
+    \previouspage qtbridge-xd-using.html
     \page sketchqtbridge.html
     \nextpage qtbridge-sketch-setup.html
 
diff --git a/doc/qtdesignstudio/src/qtbridge/qtbridge-xd-overview.qdoc b/doc/qtdesignstudio/src/qtbridge/qtbridge-xd-overview.qdoc
new file mode 100644
index 0000000000..236fc6649e
--- /dev/null
+++ b/doc/qtdesignstudio/src/qtbridge/qtbridge-xd-overview.qdoc
@@ -0,0 +1,58 @@
+/****************************************************************************
+**
+** Copyright (C) 2021 The Qt Company Ltd.
+** Contact: https://www.qt.io/licensing/
+**
+** This file is part of the Qt Design Studio 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.
+**
+****************************************************************************/
+
+// Note: The \page value is hard-coded as a link in Qt Bridge for Adobe XD.
+
+/*!
+    \previouspage qtbridge-ps-using.html
+    \page xdqtbridge.html
+    \nextpage qtbridge-xd-setup.html
+
+    \title Exporting Designs from Adobe XD
+
+    \note This is a \e {Technical Preview} release of the \QBXD. Some design
+    elements might not be exported and imported into \QDS as expected.
+
+    You can use \QBXD to export designs from Adobe XD to \e {.qtbridge}
+    format that you can \l{Importing 2D Assets}{import} to projects in \QDS.
+
+    \image qt-bridge-xd.png
+
+    The following topics describe setting up and using \QBXD:
+
+    \list
+
+        \li \l{Setting Up Qt Bridge for Adobe XD}
+
+            You must install and set up the \QBXD export plugin before you can use
+            it to export designs.
+
+        \li \l{Using Qt Bridge for Adobe XD}
+
+            To get the best results when you use \QB to export designs from
+            Adobe XD, you should follow the guidelines for working with
+            Adobe XD and organizing your assets.
+    \endlist
+*/
diff --git a/doc/qtdesignstudio/src/qtbridge/qtbridge-xd-setup.qdoc b/doc/qtdesignstudio/src/qtbridge/qtbridge-xd-setup.qdoc
new file mode 100644
index 0000000000..8ecead5647
--- /dev/null
+++ b/doc/qtdesignstudio/src/qtbridge/qtbridge-xd-setup.qdoc
@@ -0,0 +1,57 @@
+/****************************************************************************
+**
+** Copyright (C) 2021 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.
+**
+****************************************************************************/
+
+/*!
+    \previouspage xdqtbridge.html
+    \page qtbridge-xd-setup.html
+    \nextpage qtbridge-xd-using.html
+
+    \title Setting Up \QBXD
+
+    You can purchase a \QBXD license from the \l{https://marketplace.qt.io/}
+    {Qt Marketplace}, and then use the Qt Installer to have the \QBXD
+    plugin package copied to the following path in your Qt installation
+    folder:
+
+    \list
+        \li On Windows:
+            \c {Tools\QtDesignStudio\xd_bridge\qtbridge.xdx}
+        \li On \macos:
+            \c {QtDesignStudio/xd_bridge/qtbridge.xdx}.
+    \endlist
+
+    \note Install Adobe XD before installing the plugin.
+
+    To install the \QBXD plugin to Adobe XD, double-click \c qtbridge.xdx in the
+    \c xd_bridge folder in the installation directory of \QDS. Adobe XD will
+    automatically install \QBXD.
+
+    \note Since the plugin is not distributed through Adobe's marketplace, during
+    the installation Adobe XD might warn about the third-party developer.
+
+    \image qt-bridge-xd-warn.png
+
+    You can launch the plugin from \uicontrol Plugins > \uicontrol {\QB}.
+*/
diff --git a/doc/qtdesignstudio/src/qtbridge/qtbridge-xd-using.qdoc b/doc/qtdesignstudio/src/qtbridge/qtbridge-xd-using.qdoc
new file mode 100644
index 0000000000..2988954af9
--- /dev/null
+++ b/doc/qtdesignstudio/src/qtbridge/qtbridge-xd-using.qdoc
@@ -0,0 +1,219 @@
+/****************************************************************************
+**
+** Copyright (C) 2021 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.
+**
+****************************************************************************/
+
+/*!
+    \previouspage qtbridge-xd-setup.html
+    \page qtbridge-xd-using.html
+    \nextpage sketchqtbridge.html
+
+    \title Using \QBXD
+
+    \section1 Organizing Assets
+
+    To get the best results when you use \QBXD to export designs from Adobe XD
+    to \QDS, follow these guidelines when working with Adobe XD:
+
+    \list
+        \li Arrange your design into \e artboards and organize it into groups and
+            layers that are imported into \QDS as separate files.
+        \li Use descriptive and unique IDs to avoid duplicate asset names and IDs
+            in the generated UI.
+    \endlist
+
+
+    To use the fonts that you use in Adobe XD also in \QDS, you need to import
+    them to \QDS as assets. \QDS deploys them to devices when you preview the
+    UI. For more information, see \l{Using Custom Fonts}.
+
+
+    \section2 Supported Design Elements
+
+    You can export the following parts of your design using \QBXD:
+    \list
+        \li Artboard
+        \li Group
+        \li Shapes (Rectangle, Ellipse, Polygon, Line, Pen)
+        \li Text
+    \endlist
+
+    The following design elements might not be exported as expected.
+    \list
+        \li Components
+        \li Prototype
+        \li Repeat Grid
+    \endlist
+
+
+    \section2 Using Artboards
+
+    The hierarchical relationships between artboards and layers are preserved
+    when you export designs from Adobe XD and import them into \QDS. The
+    relationships are the basis of how the Items are organized in the generated
+    code in \QDS.
+
+    An artboard can only be exported as a component or skipped. A component will
+    be imported as a separate file that contains the artwork and text on the
+    artboard.
+
+    \section2 Annotate Layers for Export
+
+    With \QBXD, layers can be annotated to hint how each layer or group must be
+    exported. \uicontrol The {Home} panel displays and allows layer annotation for
+    export:
+
+    \image qt-bridge-xd-home.png
+
+    \list 1
+        \li \QBXD automatically proposes identifiers for all groups and layers
+            that you can change in the \uicontrol {ID} field. Use unique and
+            descriptive IDs to avoid duplicate IDs when the layer and the
+            respective artwork is imported into \QDS. Even though the importer
+            in \QDS is capable of fixing duplicate IDs, doing so will generate
+            warnings. It is recommend that you should manually check all the
+            IDs to make them unique and descriptive.
+
+        \li In the \uicontrol {Export As} field, select the export type for the
+            group or layer:
+            \list
+                \li \uicontrol Component exports the layer as a separate UI file
+                    that contains all the exportable artwork and text in it. Only
+                    Artboards can be exported as components.
+                \li \uicontrol Child exports each asset of the selected group
+                    or layer a separate PNG file, with references
+                    to the images in the component file.
+                \li \uicontrol Merged merges the rendition of the selected groups
+                    and layers into the rendition of parent artboard or group as
+                    one item.
+                \li \uicontrol Skipped completely skips the selected layer.
+            \endlist
+        \li In the \uicontrol {Component} field, specify the component or
+            \l {Shapes}{Qt Quick Studio Component} to morph this
+            layer into. The component that is generated during import will be
+            of this type. For example, if you drew a rectangle, you can export
+            it as a \l {basic-rectangle}{Rectangle} component.
+            You can provide the import statement of the module where the
+            component is defined in the \uicontrol {Imports} field.
+            \note The implicit properties except position and size are not
+            applied when the \uicontrol {Component} is defined. For example, all text
+            properties will be ignored if \uicontrol {Component} is defined
+            for a text layer, but explicit properties defined in the \uicontrol
+            {Properties} field will be applied.
+        \li In the \uicontrol {Imports} field, enter additional import statements
+            to have them added to the generated code file. For example, to use
+            Qt Quick Controls 2.3, you need the import statement
+            \c {QtQuick.Controls 2.3} and to use Qt Quick 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 {Properties} field, specify properties for the
+            component. You can add and modify properties in \QDS.
+        \li Select the \uicontrol Clip check box to enable clipping in the
+            component generated from the layer. The generated component will clip
+            its own painting, as well as the painting of its children, to its
+            bounding rectangle.
+        \li Select the \uicontrol Visible check box to determine the visibility
+            of the layer in the generated UI in \QDS.
+        \li Select \uicontrol Export to export the document into a .qtbridge
+            archive.
+    \endlist
+
+
+    \section2 Export Defaults
+
+    \QBXD assigns the following defaults to the layers:
+
+    By default:
+    \list
+        \li Artboards are exported as \e components.
+        \li Immediate children of an Artboard and Text layers are exported as
+            \e child.
+        \li Any layer not falling under the aforementioned criteria is exported
+            as \e merged.
+        \li Images are exported as PNGs by default with no Hi-DPI images.
+        \li \uicontrol Visible is set to \c true.
+    \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 \QBXD Settings
+
+    Select \uicontrol Settings to change the export settings.
+
+    \image qt-bridge-xd-menu.png
+
+    \image qt-bridge-xd-settings.png
+
+
+    \list 1
+        \li Select \uicontrol {Reset All} to remove all of the \QB data
+            stored in the document. Use \uicontrol {Edit} > \uicontrol {Undo}
+            to restore the data if you accidentally removed it.
+        \li You can export images into PNG, JPG or SVG format. In the section
+            \uicontrol {Export Formats}, select the image format to
+            export.
+        \li Depending on the image format selected for export, the
+            \uicontrol {Format Options} allows fine tuning the exported
+            image.
+            \list
+                \li Select \uicontrol {Hi-DPI Assets} to generate Hi-DPI
+                    images alongside normal scale images. Being a vector format,
+                    this option is not available for SVG format.
+                \li Select \uicontrol {SVG Minify} to minify the SVG.
+                \li Select \uicontrol {JPG Quality} to specify the JPG
+                    compression quality in the range [1, 100].
+            \endlist
+    \endlist
+
+    \section1 Suggestions and Tips
+
+    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 code to
+    a certain degree. For example, you can specify the component or
+    \l {Shapes}{Qt Quick 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 \l Arc 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
+    \l Button component.
+
+    \list
+        \li Name the layers in exactly the same way as your IDs, to be able to
+            find artwork later, especially as the export files can grow very
+            large and complicated as they approach the level of a complete UI
+            project.
+        \li Make sure to skip all artboards that you don't want to be part of
+            the final UI to avoid cluttering the \QDS project. You can select
+            multiple artboards on a page and then select \uicontrol Skip in \QBXD
+            to skip them.
+        \li Store all assets in the scalable vector graphics (SVG) format to be
+            able to easily rescale them for different screen sizes and resolutions.
+            You can export assets into JPG, PNG, or SVG format and select options
+            for optimizing them during the export.
+    \endlist
+
+*/
diff --git a/doc/qtdesignstudio/src/qtdesignstudio-toc.qdoc b/doc/qtdesignstudio/src/qtdesignstudio-toc.qdoc
index 12bae906f4..f917223dfc 100644
--- a/doc/qtdesignstudio/src/qtdesignstudio-toc.qdoc
+++ b/doc/qtdesignstudio/src/qtdesignstudio-toc.qdoc
@@ -153,6 +153,11 @@
                                     \li \l{Setting Up Qt Bridge for Adobe Photoshop}
                                     \li \l{Using Qt Bridge for Adobe Photoshop}
                                 \endlist
+                            \li \l{Exporting Designs from Adobe XD}
+                                \list
+                                    \li \l{Setting Up Qt Bridge for Adobe XD}
+                                    \li \l{Using Qt Bridge for Adobe XD}
+                                \endlist
                             \li \l{Exporting Designs from Sketch}
                                 \list
                                     \li \l{Setting Up Qt Bridge for Sketch}