qt-creator/doc/qtdesignstudio/src/qtdesignstudio-importing-2d.qdoc

// Copyright (C) 2021 The Qt Company Ltd.
// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only

/*!
    \previouspage studio-importing-designs.html
    \page studio-importing-2d.html
    \nextpage qtquick-fonts.html

    \title Importing 2D Assets

    You can import 2D assets, such as images, fonts, and sound files, to \QDS to
    use them in your projects.

    To import an asset, drag-and-drop the external file containing the asset from,
    for example, File Explorer on Windows, to the \uicontrol {2D},
    \uicontrol Navigator, or \uicontrol {Code} view. Alternatively, select
    \uicontrol Assets > \inlineimage icons/plus.png
    and follow the instructions in the \uicontrol {Asset Import} dialog. You can
    also multiselect several external asset files to drag-and-drop them to
    \QDS simultaneously.

    The imported images will appear in \uicontrol Assets.
    If you initiate the import by dragging the assets to the \uicontrol {2D} view,
    they are also added to your projects as image components, and you can view
    them in the \uicontrol {2D} and \uicontrol Navigator view. If you drag an
    external font file to the \uicontrol {2D} view, it will be added to your
    project as a text component. Other imported assets, such as sound files,
    will only appear in \uicontrol Assets, and you can then
    drag-and-drop them to a suitable view.

    \section1 Importing Designs From Other Design Tools

    \image studio-imported-assets.png "UI imported into Qt Design Studio"

    \QB enables you to export assets and then import them to a \QDS project
    as images and QML files for editing in the \l {2D} view. If you make changes
    to your design in the design tool that you originally used to create it,
    you can merge the changes into existing QML files without overwriting the
    changes you have made in \QDS. For more information, see
    \l {Exporting from Design Tools}.

    \QB exports the designs either as an archive(.qtbridge) or as images with
    a .metadata file. \QDS support both formats.

    The following instructions use an empty project as an example. For more
    information about the options you have, see
    \l {Creating Projects}.

    To import the exported assets to \QDS projects:

    \list 1
        \li Select \uicontrol File > \uicontrol {New Project} >
            \uicontrol General > \uicontrol {Empty}. Add \uicontrol {Details} about
            the project and select \uicontrol Create.
        \li In \uicontrol Projects, double-click \e Screen01.ui.qml to move to
            the Design mode.
        \li Select \uicontrol Assets > \inlineimage icons/plus.png
            .
        \li Select the folder where you exported the assets.
        \li Select \uicontrol {Compressed Metadata (*.qtbridge)}  or
            \uicontrol {Exported Metadata (*.metadata)} in the dropdown menu to
            filter the exported files.
        \li Select a the file to import and then select \uicontrol Open.
        \li Select \uicontrol Details next to the
            \uicontrol {Import Paths} field to display the path where the exported
            assets are imported from.
            \image studio-asset-import.png "Asset Import dialog"
        \li Select \uicontrol Details next to the
            \uicontrol {Export Paths} field to display the paths to
            copy the assets to.
        \li In the \uicontrol QML field, you can change the folder to copy the
            QML files to.
        \li In the \uicontrol Assets field, you can change the folder to copy
            the image files to.
        \li Select the \uicontrol {Create sub directory} check box to import the
            assets in a sub directory inside \uicontrol {Export Paths}.
        \li Deselect the \uicontrol {Import assets} check box if you only want
            to create QML files.
        \li Deselect the \uicontrol {Generate QML} check box if you only
            want to import assets.
        \li Select the \uicontrol {Merge QML} check box if you have imported the
            assets before and want to merge the changes into existing QML files
            instead of overwriting the existing files. See \l {Merging QML Files}.
        \li Select the \uicontrol {Round off coordinates} check box to round off
            the position and dimension values to integers in the generated QML files.
        \li Select the \uicontrol {Save Logs} check box to write the export logs
            to a text file inside the directory selected in \uicontrol QML export path.
        \li Select \uicontrol Import to import the QML files and assets. This
            might take a little while for complex projects.
    \endlist

    The imported assets are displayed in \uicontrol Assets as images.
    The components that you specified in the design tool are displayed in
    \uicontrol Components > \uicontrol {My Components} as well as in the
    \uicontrol Projects view as separate QML files. To use them,
    drag-and-drop them from \uicontrol Components to the \uicontrol {2D} or
    \l Navigator view.

    If asset importer conflicts, warnings, and errors are displayed in the
    \uicontrol {Asset Import} dialog while importing, fix the issues in
    design tool and export the assets again.

    \section2 Merging QML Files
    When you re-import a QML component, the changes done in \QDS are preserved.
    The QML item changes in the existing QML component are copied to the corresponding
    QML item in the new component.

    The following rules are observed while merging QML components.
    \list
        \li While importing, a unique identifier (UUID) is added for each QML item in the
            component. The UUID is used to find the corresponding QML item in the existing
            component.
        \li New item properties in the existing component are added to the corresponding
            item in the new component.
        \li When a QML property is set in both old and new QML item, the property in the
            new item remains unchanged. This rule does not apply to binding properties. In case
            of bindings, changes done in \QDS are preserved.
        \li New child items are added to the corresponding item in the new component.
        \li QML items for which a corresponding QML item is not found in the existing component,
            are added under the root item of the new component.
    \endlist
    \include qtbridge-tutorial-links.qdocinc qtsketchbridge tutorials

*/