"Fossies" - the Fresh Open Source Software Archive

Member "qt-creator-opensource-src-4.15.1/doc/qtdesignstudio/src/qtbridge/qtbridge-ps-using.qdoc" (8 Jun 2021, 17164 Bytes) of package /linux/misc/qt-creator-opensource-src-4.15.1.tar.xz:


As a special service "Fossies" has tried to format the requested text file into HTML format (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file. See also the latest Fossies "Diffs" side-by-side code changes report for "qtbridge-ps-using.qdoc": opensource-src-4.15.0_vs_opensource-src-4.15.1.

    1 /****************************************************************************
    2 **
    3 ** Copyright (C) 2021 The Qt Company Ltd.
    4 ** Contact: https://www.qt.io/licensing/
    5 **
    6 ** This file is part of the Qt Bridge documentation.
    7 **
    8 ** Commercial License Usage
    9 ** Licensees holding valid commercial Qt licenses may use this file in
   10 ** accordance with the commercial license agreement provided with the
   11 ** Software or, alternatively, in accordance with the terms contained in
   12 ** a written agreement between you and The Qt Company. For licensing terms
   13 ** and conditions see https://www.qt.io/terms-conditions. For further
   14 ** information use the contact form at https://www.qt.io/contact-us.
   15 **
   16 ** GNU Free Documentation License Usage
   17 ** Alternatively, this file may be used under the terms of the GNU Free
   18 ** Documentation License version 1.3 as published by the Free Software
   19 ** Foundation and appearing in the file included in the packaging of
   20 ** this file. Please review the following information to ensure
   21 ** the GNU Free Documentation License version 1.3 requirements
   22 ** will be met: https://www.gnu.org/licenses/fdl-1.3.html.
   23 **
   24 ****************************************************************************/
   25 
   26 /*!
   27     \previouspage qtbridge-ps-setup.html
   28     \page qtbridge-ps-using.html
   29     \nextpage sketchqtbridge.html
   30 
   31     \title Using \QBPS
   32 
   33     \section1 Organizing Assets
   34 
   35     To get the best results when you use \QBPS to export designs from Adobe
   36     Photoshop for importing them to \QDS, follow these guidelines when working
   37     with Photoshop:
   38 
   39     \list
   40         \li Arrange your art into \e artboards and organize it into groups and
   41             layers that are imported into \QDS as separate files, depending
   42             on the choices you make when exporting designs.
   43         \li Use the Type tool to make sure that all of your text labels
   44             are exported to \l Text items.
   45         \li Store all assets in vector format to be able to easily rescale them
   46             for different screen sizes and resolutions.
   47     \endlist
   48 
   49     To use the fonts that you use in Photoshop also in \QDS, you need to load
   50     them to \QDS. \QDS deploys them to devices when you preview the UI. For more
   51     information, see \l{Using Custom Fonts}.
   52 
   53     \note You can export only files that are saved in the Photoshop file format,
   54     such as \e {.psd} and \e {.psb}. For all other document formats, \QDS
   55     displays the following error message: \e {Document is not supported.}
   56 
   57     \section2 Using Artboards
   58 
   59     The relationships between the groups and layers on an artboard are preserved
   60     when you export designs from Adobe Photoshop and import them into \QDS.
   61 
   62     When you use \QBPS to export your designs, you will determine how you want
   63     each group or layer exported: as a \e component or \e child. A component
   64     will be imported as a single \l {UI Files}{UI file} that can contain other
   65     assets. A child will be imported as a single image file that you can use
   66     within UI files.
   67 
   68     If you plan to use pieces of your design as separate images in the UI,
   69     group them on an artboard as separate layers. You can then export the group
   70     as a component and each layer within it as a child. The children are
   71     imported to \QDS as separate PNG files that you can use as image sources.
   72 
   73     To use the contents of an artboard as a single image in the UI, you can
   74     merge the groups and layers when you export them. During import, the
   75     contents are flattened into one PNG file. The merge is done in a way that
   76     enables you to change the groups and layers in Photoshop or Adobe
   77     Illustrator and then export and import the artboard again. This is an easy
   78     way to create a reference image of how the final UI should look like, for
   79     example.
   80 
   81     Place different parts of the UI, such as menus and pop-ups, on separate
   82     artboards to be able to export them as components or children and to
   83     import them as code and PNG files that you can drag and drop to
   84     \l {Form Editor} in \QDS Design mode while creating a UI.
   85 
   86     \QDS offers predefined sets of UI controls that you can modify according
   87     to your needs. You can export your own controls as components, Qt Quick
   88     Controls, or Qt Quick Studio Components. The position and dimensions of your control
   89     are preserved.
   90 
   91     However, if you want your UI controls, such as check boxes, to look exactly
   92     like they do in Photoshop, you have to create the control in an Artboard and
   93     use the artboard in the layers where the control instance is to be created.
   94     \QB imports the control as a custom component that you can program in
   95     \QDS.
   96 
   97     \section1 Exporting Assets
   98 
   99     Each artboard is exported automatically as a component, which means that it
  100     will be imported as a separate file that contains all the artwork on the
  101     artboard, except layers that are set to be skipped or exported as child items.
  102     You determine how each group or layer in an artboard is exported: as a component
  103     or a child item. In addition, you can merge the groups and layers of an artboard
  104     into the parent as one item or skip layers completely.
  105 
  106     By default, layers are exported as follows:
  107 
  108     \list
  109         \li First level group layers are exported as child items of the
  110             artboard.
  111         \li Second level group layers are merged to their parent.
  112         \li Asset layers are exported as merged.
  113         \li Text layers are always exported as child items.
  114         \li Images are exported in JPG, PNG, or SVG format, depending on your
  115             selection.
  116     \endlist
  117 
  118     \QBPS automatically proposes identifiers (IDs) for all groups and layers.
  119     The IDs will be used as filenames in \QDS. You can change the IDs, so that
  120     you can easily find them in \QDS. Just keep in mind that the IDs must be
  121     unique and that they must follow some naming conventions.
  122 
  123     You can export assets using the default settings and make all the changes
  124     later in \QDS. If you are familiar with the \l{QML Syntax Basics}
  125     {QML syntax}, you can modify the settings to tailor the generated code to
  126     a certain degree. For example, you can specify the component or
  127     \l {Shapes}{Qt Quick Studio Component} to use for a artboard or layer.
  128     If you have drawn an arc that you mean to animate, you can export it as
  129     an \l Arc Studio component to avoid having to replace the arc image with
  130     an Arc component in \QDS. Or you could export a button as a
  131     Qt Quick Controls \l Button type.
  132 
  133     You can specify effects, such as a blur effect, to use for a group or layer.
  134 
  135     The QML types supported by \QDS are listed in the \uicontrol {Components}
  136     tab in the \l {Library} in the Design mode of \QDS. For more
  137     information, see \l{Creating Components}.
  138 
  139     You can also specify values for the properties of the component or create
  140     \l{Property Aliases}{property aliases} to fetch the values from other
  141     properties.
  142 
  143     \image qt-bridge.png
  144 
  145     \section2 Specifying Settings for Exporting Assets
  146 
  147     To export your design using \QBPS:
  148 
  149     \list 1
  150         \li \QBPS automatically proposes identifiers for all groups and layers
  151             that you can change in the \uicontrol {ID} field. The IDs must
  152             be unique, they must begin with a lower-case letter or an
  153             underscore, and they can only contain letters, numbers, and
  154             underscore characters. For more information, see
  155             \l {The id Attribute}.
  156         \li In the \uicontrol {Export As} field, select the export type for the
  157             group or layer:
  158             \list
  159                 \li \uicontrol Component exports the selected artboard, group,
  160                     or layer with metadata. The exported data can be used later
  161                     to import the component as a separate UI file that contains
  162                     all the artwork in it, except layers that are set to be
  163                     skipped or exported as child items.
  164                 \li \uicontrol Child exports each asset of the selected group
  165                     or layer as a separate PNG file, with references
  166                     to the images in the component file.
  167                 \li \uicontrol Merged merges the selected groups and layers into
  168                     the parent as one item.
  169                 \li \uicontrol Skipped completely skips the selected layer.
  170             \endlist
  171         \li In the \uicontrol {As Artboard} field, select an artboard
  172             to reuse. For example, you can use an artboard to define a
  173             component, such as a button, and reuse it in other artboards.
  174         \li In the \uicontrol {Component} field, specify the component
  175             or Studio component to morph this layer into. The component that is
  176             generated during import will be of this type. For example, if you
  177             drew a rectangle, you can export it as a \l {Studio Rectangle}{Rectangle}
  178             Studio component.
  179             You can provide the import statement of the module where the
  180             component type is defined in the \uicontrol {Imports} field.
  181             \note The implicit properties except position and size are not
  182             applied when the \uicontrol {Component} is defined. For example, all text
  183             properties will be ignored if \uicontrol {Component} is defined
  184             for a text layer, but explicit properties defined in the \uicontrol
  185             {Properties} field will be applied.
  186         \li Select the \uicontrol {Render Text} check box to render the text
  187             layer as an asset. The layer will be exported as an asset and the
  188             text data will not be exported. This allows the text layer to be
  189             merged to parent artboard or group as well.
  190         \li In the \uicontrol {Add Imports} field, enter additional
  191             import statements to have them added to the generated UI file.
  192             For example, to use Qt Quick Controls 2.3, you need the import
  193             statement \c {QtQuick.Controls 2.3} and to use Qt Studio
  194             Components 1.0, you need the import statement
  195             \c {QtQuick.Studio.Components 1.0}. You can also import a module
  196             as an alias.
  197         \li In the \uicontrol {Properties} field, specify properties for
  198             the component. You can add and modify properties in \QDS.
  199         \li Select the \uicontrol {Clip Contents} check box to enable clipping
  200             in the type generated from the layer. The generated type will clip
  201             its own painting, as well as the painting of its children, to its
  202             bounding rectangle.
  203         \li Select the \uicontrol {Create Alias} check box to export the item
  204             generated from this layer as an alias in the parent component.
  205         \li Select \uicontrol {Cascade properties} to apply the current set of
  206             properties to all the children of the selected layer.
  207         \li In the \uicontrol Annotations field, specify annotation for the
  208             component. See \l {Annotating Designs}.
  209         \li Select \uicontrol Export to copy your assets to the export path you
  210             specified.
  211         \li When the exporting is done, select \uicontrol OK.
  212     \endlist
  213 
  214     All the assets and metadata are copied to the directory you specified. This
  215     might take a little while depending on the complexity of your project.
  216 
  217     You can now create a project in \QDS and import the assets to it, as
  218     described in \l {Creating Projects} and \l{Importing Designs}.
  219 
  220     \note
  221     Exporting your design using \QBPS can be slow for documents with large number
  222     of layers. Closing Photoshop's Info, Layers, and Properties windows can improve
  223     the time it takes to export.
  224 
  225 
  226 
  227     \section1 Customizing IDs
  228 
  229     \QBPS enables customizing auto generated IDs. In the \uicontrol {ID Prefix}
  230     field, specify an ID prefix that will be prepended to all auto generated IDs.
  231     In the \uicontrol {ID Suffix} field, specify an ID suffix that will be
  232     appended to all auto generated IDs.
  233 
  234     \image qt-bridge-qml-id-settings.png
  235 
  236     \section1 Cloning Documents
  237 
  238     \QBPS enables creating a clone of the current document. The clone workflow
  239     allows the user to filter out certain kind of layers and groups. In the \QBPS
  240     \uicontrol Settings dialog, select \uicontrol {Clone} to start cloning the document.
  241 
  242     \image qt-bridge-clone.png
  243 
  244     \section2 Clone Options
  245     The following exclusion options can be selected to exclude certain kind of layers and
  246     groups in the cloned document:
  247     \list
  248         \li \uicontrol Invisible: Select this option to exclude the invisible layers
  249             and groups.
  250         \li \uicontrol Skipped: Select this option to exclude the layers where the
  251             \uicontrol {Export As} field value is set to \uicontrol Skipped.
  252         \li \uicontrol {Empty Groups}: Select this option to exclude any empty groups.
  253             This also applies to groups which will eventually become empty because of
  254             the other selected exclusion options.
  255     \endlist
  256 
  257     \section1 Sanitizing Documents
  258 
  259     \QBPS enables removing all \QBPS related metadata from the active
  260     document. In the \QBPS \uicontrol Settings dialog, select
  261     \uicontrol {Sanitize Document} to sanitize the active document.
  262     Once the sanitization is successfully done, the document will
  263     contain no \QBPS related metadata and the \QBPS layer settings will fall
  264     back to the \l{Exporting Assets}{default} values.
  265 
  266     \note The sanitization is done in memory and the document must be saved to
  267     keep the sanitized state.
  268 
  269     \image qt-bridge-sanitize.png
  270 
  271     \section1 Extending \QBPS
  272     You can change the default behavior of \QBPS with the help of a JSX script. One can write
  273     specific functions in the script that are called by \QBPS with useful parameters.
  274 
  275     \section2 Overridable JSX Functions
  276     You can define the following functions in the override JSX.
  277     \list
  278         \li preExport(document)
  279             This function is called before the document is exported. The parameter \a document is
  280             the PSD Document instance. This function can be used to make temporary changes in
  281             the document before export.
  282         \li postExport(document)
  283             This function is called after the document is exported. The parameter \a document is the
  284             PSD Document instance. You can undo the temporary changes done in the function
  285             \e preExport(...).
  286         \li customDefaultQmlId(name, instance)
  287             The function is called for setting the default ID of the layer. The returned value
  288             is used for the ID. Return \c false to use the auto generated ID instead.
  289             The parameter \a name is the auto generated ID by the plugin and \a instance is the
  290             PSD layer instance.
  291     \endlist
  292 
  293     \note Please refer to \l {https://www.adobe.com/devnet/photoshop/scripting.html}
  294     {Adobe Photoshop CC Javascript} scripting guide to understand the object model and \e Document
  295     and \e Layer instances.
  296 
  297     \image qt-bridge-override.png
  298 
  299     In the \QBPS \uicontrol Settings dialog, select \uicontrol {Override JSX Script} to set the
  300     override JSX script.
  301 
  302     \section1 Importing Metadata & Assets
  303 
  304     \QBPS can import metadata generated from other tools and generate a Photoshop document. A
  305     conventional workflow would be to generate metadata and assets by \l {Exporting Components} {exporting}
  306     a QML project from \QDS and use \QBPS to generate a Photoshop document.
  307 
  308     Imported text and the assets are organized into Artboards, layers, and groups.
  309 
  310     Select the \uicontrol Import button to launch the \uicontrol Import panel. Alternatively, \QB
  311     import can be launched from \uicontrol Window > \uicontrol Extensions.
  312 
  313     \image qt-bridge-import.png
  314 
  315     Create a new PSD document and launch the \uicontrol Import dialog. Open the metadata file to
  316     import and select \uicontrol Import.
  317 
  318     \note The import process removes all the existing layers in the selected PSD document.
  319 
  320     \image qt-bridge-import-warning.png
  321 
  322     The following guidelines are followed to generate the Photoshop document:
  323     \list
  324         \li An Artboard is created for each component exported and defined in the metadata file.
  325         \li An image layer is created for an item with an asset.
  326         \li A solid fill layer is created for an item without an asset.
  327         \li A paragraph text layer is created for Text items.
  328     \endlist
  329 
  330     All metadata specified in the metadata file is assigned to the generated layers.
  331 
  332     An important concept of \e {Virtual parent} is applied to translate the QML DOM to Photoshop
  333     DOM. A QML \l Item can have children but a layer in a Photoshop document cannot have child
  334     layers. To mitigate this variance, a Group layer is created and child items are added to this
  335     Group layer. The Group layer acts as a virtual parent and the correct parent is assigned when
  336     the Photoshop document is exported and re-imported in \QDS.
  337 
  338     \note The parent-child relationship may be lost if the virtual parent Group layer is moved or
  339     deleted.
  340 
  341 */