qt-creator/doc/qtdesignstudio/src/qtbridge/qtbridge-figma-using.qdoc

/****************************************************************************
**
** Copyright (C) 2020 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-figma-setup.html
    \page qtbridge-figma-using.html
    \nextpage exporting-3d-assets.html

    \title Using \QBF

    \section1 Organizing Assets

    To get the best results when you use \QBF to export designs from Figma
    to \QDS, follow these guidelines when working with Figma:

    \list
        \li Use pages for different purposes, such as \e sketching for trying
            out ideas, \e components for creating UI components, \e assets for
            images that you use in the components, and \e screens for building
            the UI screens using components and assets.
        \li Arrange each page into frames. When you are happy with a design,
            move it from the sketching page to the components page and use it
            in screens. When you export your assets, you can skip all frames
            that you don't want to be part of the final UI, to avoid cluttering
            the \QDS project. The QML code generated in \QDS corresponds to the
            structure of your Figma document.
        \li \QBF supports \e {Figma components}. Each Figma component
            is exported as a \e {QML component}, and each Figma component
            instance is generated as a respective QML component instance
            in the generated QML.
        \li Create components in Figma and export them to \QDS before you
            start making instances of them. In \QDS, add functionality to the
            components, such as button states and then bring them back to Figma
            as assets. If you use functional QML components in Figma, you will
            find it easier to merge new iterations of the design to \QDS and
            continue to build the screens there.
        \li Use descriptive and unique ids to avoid duplicate QML ids after
            exporting assets and \l{Importing 2D Assets}{importing} them to
            \QDS.
    \endlist

    To use the fonts that you use in Figma 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 Using Frames

    The relationships between frames and layers are preserved when you export
    designs from Figma and import them into \QDS.

    A frame can only be exported as a component or skipped. A component will
    be imported as a separate QML file that contains all the artwork on the
    frame, except layers that are set to be skipped or exported as child
    items. The child items can contain graphical assets or text.

    \section1 Exporting Assets

    \image qt-figma-bridge.png

    To export your design using \QBF:

    \list 1
        \li \QBF automatically proposes identifiers for all groups and layers
            that you can change in the \uicontrol {QML ID} field. Use unique and
            descriptive ids to avoid duplicate QML ids when the layer and the
            respective artwork is imported into \QDS.
        \li In the \uicontrol {Export As} field, select the export type for the
            group or layer:
            \list
               \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 selected groups and layers into
                    the parent frame or group as one item.
                \li \uicontrol Skipped completely skips the selected layer.
            \endlist
        \li In the \uicontrol {QML type} field, specify the QML type 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 Rectangle component.
            You can provide the import statement of the module where the QML
            type is defined in the \uicontrol {QML Imports} field.
        \li In the \uicontrol {QML 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 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 {QML properties} field, specify properties for the
            QML type. You can add and modify properties in \QDS.
        \li Select the \uicontrol Alias check box to export the item generated
            from this layer as an alias in the parent component.
        \li Select the \uicontrol Clip 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 Visible check box to determine the visibility
            of the layer.
       \li Select \uicontrol {Export assets and metadata} to export your design.
        \li When the exporting is done, select \uicontrol OK.
    \endlist

    \QBF exports everything into a single archive. Before importing the project
    into \QDS, you have to manually extract the archive. Then you can import the
    \e .metainfo into a project in \QDS, as described in \l{Importing Designs}.
*/