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

/*!
    \previouspage qtbridge-figma-setup.html
    \page qtbridge-figma-using.html
    \nextpage qtbridge-figma-template.html

    \title Using \QBF

    \section1 Organizing designs

    To get the best results during export and import, 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 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 {\QDS component}, and each Figma component
            instance is generated as a respective component instance in the
            component files generated when you \l{Importing 2D Assets}{import}
            the design into \QDS.
        \li Create components with instances in Figma and export them to \QDS.
            \QDS friendly Figma components make it easier to create, for example, button states,
            connections, animations, and transitions.
        \li \QBF does not support exporting changes in component instances.
            If you make changes to component instances in Figma, you must
            detach the instances before exporting them. Similarly, if your
            Figma components contain nested components, Figma allows you to
            hot swap the nested instance inside the component instance.
            However, \QBF doesn't support this so you get the original
            component unless you detach the component instance before
            exporting it.
        \li Use descriptive and unique IDs to avoid duplicate IDs after
            exporting designs and importing them to \QDS.
    \endlist

    To use the fonts that you use in Figma also in \QDS, you need to add
    them to \QDS as assets. \QDS deploys them to devices when you preview the
    UI. For more information, see \l{Using custom fonts}.

    \section2 Items you can export

    You can export the following parts of your design using \QBF:
    \list
        \li Images
        \li Vector images
        \li Layers
            \list
                \li Text layers
                \li Shape layers
            \endlist
        \li Components
        \li Component instances
        \li Frames
        \li Groups
    \endlist

    \section2 Using frames

    Frames are exported as components of the \l Rectangle type by default.
    However, if you have applied effects to the frames that \QBF cannot
    handle, such as gradient fill colors or a mixed radius, the frames are
    exported as images.

    \section2 Using variables
    With \QDS 4.6, variables are exported as a QML module named \e DesignSystem. A QML singleton
    is created for each collection. Modes of the collection are exported as theme objects.
    A collection has a \e currentTheme property, updating the property changes the active theme.

    When a variable is bound to a property of a layer, the \e DesignSystem module import
    is added to the generated code and the property binding is created accordingly.

    To export variables, select \uicontrol {Export Variables} from \l{Settings}.
    
    \note Remote variables are not supported. Setting the active mode on the page or
    layer does not affect the generated code.

    \section2 Using variants
    Figma variants are exported as a component with states. All variants
    inside a \e component-set are merged together and the differences across
    the variants are translated into states.

    For an optimal output, follow these guidelines:
    \list
        \li \QBF panel is disabled for variants. Before adding
            a variant to a component, the \QBF settings for the component
            should be complete.
        \li Do not change the layer names across the variants. The \l ID  of
            a layer is derived from the layer name which in turn is used
            to identify the property differences for the state generation, so
            it is essential to keep the layer names same across variants.
        \li Adding and removing layers across the variants is fine and
            encouraged to create the variant differences.
    \endlist

    \section1 Exporting designs

    \image qt-figma-bridge.png "Qt Bridge for Figma"

    To export your design using \QBF:

    \list 1
        \li Specify settings for exporting each group and layer.
        \li Select \uicontrol Export to export your design.
        \li When the exporting is done, select \uicontrol OK.
    \endlist

    \QBF exports everything into a .qtbridge archive. You can import the archive
    into a project in \QDS, as described in \l{Importing 2D Assets}.

    \section1 Export settings

    You can specify export settings in the \uicontrol Home tab and in the
    \uicontrol Settings tab.

    \section2 Home

    You can specify settings for exporting each group and layer.

    \table
    \header
        \li Name
        \li Purpose
    \row
        \li \uicontrol ID
        \li \QBF automatically derives identifiers for all groups and layers
            from layer name.
            You can change them in this field. Use unique and descriptive IDs
            to avoid duplicate IDs when the layer and the respective artwork
            are imported into \QDS.
            \note Once the ID is edited, the automatic assignment of ID from
            layer name stops for this layer. Use \imagefigmabindingreset
            button next to \uicontrol ID to reset the ID back to automatic assignment.
    \row
        \li \uicontrol {Export as}
        \li Determines how to export the group or layer:
            \list
               \li \uicontrol Child exports each asset of the selected group
                    or layer as a separate component file. Images are exported
                    as separate files nested in \l{Images}{Image} components.
                    You select the image file format in \uicontrol Settings >
                    \uicontrol {Asset settings}.

                    Figma rectangles are exported as \l{basic-rectangle}
                    {Rectangle} components. Figma vectors are exported as
                    \l{SVG Path Item} components from the \l{Shapes}
                    {Qt Quick Studio Components} module.
                \li \uicontrol Merged merges the selected groups and layers
                    into one component.
                \li \uicontrol Skipped completely skips the selected layer.
            \endlist
            \note Use \imagefigmabindingreset button next to
            \uicontrol {Export as} to reset to default value.
    \row
        \li \uicontrol {Custom Component Type}
        \li Determines the \l{Component Types}{component type} to morph this
            layer into. The component that is generated during import will be
            of this type. For example, if you drew a button, you can export
            it as a \l Button component from the Qt Quick Controls module.
            You can provide the import statement of the
            \l{Adding and Removing Modules}{module} where the component
            is defined in the \uicontrol {Imports} field.
    \row
        \li \uicontrol Properties
        \li Sets values of properties for the component. You can add properties
            and modify their values in \QDS.
    \row
        \li \uicontrol Imports
        \li If you want to make additional components available in the component
            file, you can enter the import statements of the modules that
            contain the components in this field. For example, to use components
            from version 2.3 of the Qt Quick Controls module, you need the
            import statement \c {QtQuick.Controls 2.3} and to use version 1.0
            Qt Quick Studio Components, you need the import statement
            \c {QtQuick.Studio.Components 1.0}. You can add components from all
            the available modules in \QDS later. You can also import a module as
            an \e alias.
    \row
        \li \uicontrol {Properties}
        \li Specify new properties or assign values to the existing properties of
            the component. You can also add and modify properties in \QDS.
            The following are a few examples of the properties:
            \code
            property int counter: 5
            property string label: "ok"
            antialiasing : true
            width: parent.width / 2
            \endcode
            To remove a property, write a "dash" (-) followed by the "property name".
            For example:
            \code
            - width
            \endcode
            will remove the property \e width from the generated code.
    \row
        \li \uicontrol {Snippet}
        \li Specify component to be added as child under this component.
            Following example adds a Connection component:
            \code
            Connections {
                target: myItem
                onVisibleChanged: console.log(original_Text.visible)
            }
            \endcode
            \note The code must have a scope of a component (such as Item, MouseArea,
            Connections) with a valid syntax for \l {UI files}.
            \note Add respective imports for your snippet in \uicontrol {Imports}.
    \row
        \li \uicontrol Alias
        \li Exports the component generated from this layer as an alias in the
            parent component.
    \row
        \li \uicontrol {Start Screen}
        \li Sets the component to be the starting component in \QDS project.
    \endtable

    \section2 Settings

    \image {qt-figma-bridge-settings.png} {The Qt Bridge for Figma settings window in Figma.}

    You can export assets in the selected format (JPG, PNG, or SVG).

    By default, vectors are exported as \l{SVG Path Item} components from the
    Qt Quick Studio Components module. This might not work for layers that have
    particular effects applied to them. In that case, the layers are exported
    as images.

    Because MCUs only support simple images, disable the
    \uicontrol {Export as shapes} check box when designing for MCUs.

    The following table describes the options you have. You can combine options as necessary.

    \table
    \header
        \li Name
        \li Purpose
    \row
        \li \uicontrol {Export target}
        \li Determines whether to create code for Qt or \l{\QMCU}. \QMCU supports a subset
        of QML components and their properties. For more information, see \l{Differences
        between \QUL Controls and Qt Quick Controls} and \l{\QMCU Known Issues or Limitations}.
    \row
        \li \uicontrol {Asset settings}
        \li Export assets in the selected format (JPG, PNG, or SVG). For SVG format, you
        can set a fallback option as not all assets can be exported properly to it.
    \row
        \li \uicontrol {Constraints settings}
        \li Defines how Figma constraints are exported into QML.
        By default, each Figma layer has a top-left constraint defined that references its
        parent, which can be exported to either XY coordinates or anchors with margins.
        Select the option to use for exporting constraints into anchors:
            \list
                \li No constraints - do not generate anchors. Ignore the constraints and use
                XY values to position the components.
                \li In-Component Only - generate anchors only for layers within Figma Components.
                Use XY coordinates otherwise. This setting is useful for component state
                transitions where anchors are essential for proper behavior.
                \li All constraints - generate anchors everywhere.
            \endlist
        You can skip the default top-left constraint in favor of X and Y coordinates when you select
        \uicontrol {In-Component Only} or \uicontrol {All Constraints}.
        Even if you skip the constraint:
            \list
                \li Anchors are generated for all Figma Group and Image types, as well as auto-layouts.
                \li X and Y coordinates are set for elements inside layouts because they should not have anchors.
            \endlist
    \row
        \li \uicontrol {Effect settings}
        \li Controls how the layers with effects are exported.
            \list
                \li Skipped - skip effect properties and export layers without any effect.
                \li Rasterized - rasterize layers with effects and export them as image assets.
                \li Design Effects - export layers with effects as items with \l{Design effects}.
                This option is disabled when exporting for \QMCU.
            \endlist
    \row
        \li \uicontrol {Mask settings}
        \li Exports masked items.
            \list
                \li Skipped - skip masks and export elements as if the Figma Mask layer was invisible.
                \li Rasterized - rasterize all masked objects and export them as image assets.
            \endlist
    \row
        \li \uicontrol {Gradient settings}
        \li Exports Component, Frame, and Rectangle layers with linear \l [QML] {Gradient}.
    \row
        \li \uicontrol {Shape gradients}
        \li Exports shape-based components with gradients following the selected rule. Currently
        limited to Vector, Ellipse, Arc, Pie.
            \list
                \li Rasterized - rasterize layers with gradients and export them as image assets.
                \li Only Linear - export layers with linear gradients as shape items with gradients.
                Rasterize the rest and export them as image assets.
                \li All Supported Types - export layers with supported gradients as shape items with
                gradients. Includes Linear, Radial, and Conical gradients. This option is disabled
                when exporting for \QMCU.
            \endlist
    \row
        \li \uicontrol {Reset plugin data}
        \li Resets all settings for all layers and groups (also in the
            \uicontrol Home tab) to default values.
    \endtable

    \section3 Additional settings
    \table
    \header
        \li Name
        \li Purpose
    \row
        \li \uicontrol {Export as shapes}
        \li Exports vectors as components of the type \l{SVG Path Item} from the
            Qt Quick Studio Components module. This option is disabled when exporting for \QMCU.
    \row
        \li \uicontrol {Export ellipse items as qml items}
        \li Export ellipses as ArcItem components. Uses \QUL ArcItem when exporting for \QMCU.
    \row
        \li \uicontrol {Use antialiasing on vector items}
        \li Generate vector items using antialiasing. Only applies to dynamic vector items, such
        as SVG Path Item and ArcItem. This option is disabled when exporting for \QMCU.
    \row
        \li \uicontrol {Export auto layouts}
        \li Export Figma auto layouts as \l{Using layouts}{Qt Quick Layouts} components.
    \row
        \li \uicontrol {Create page hierarchy}
        \li Organize the generated UI in \QDS under the directory named after the
            parent page of the respective component.
    \row
        \li \uicontrol {Export Variables}
        \li Enable exporting variables.
    \endtable

    \include qtdesignstudio-qt-academy.qdocinc qt-academy-using-qt-bridge-for-figma
*/
