/****************************************************************************
**
** 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.
**
****************************************************************************/

/*!
    \page studio-projects.html
    \previouspage creator-keyboard-shortcuts.html
    \nextpage studio-use-cases.html

    \title Creating Projects

    One of the major advantages of \QDS is that it allows a team of designers
    and developers to share a project across different development platforms
    with a common tool for design, development, profiling, and debugging.

    Creating a project enables you to:

    \list
        \li Group files together
        \li Include \l{UI Files}{UI files} (.ui.qml), component files (.qml),
            and assets files
        \li Specify settings for previewing UIs
    \endlist

    Setting up a new project in \QDS is aided by a wizard that guides you
    step-by-step through the project creation process. The wizards prompt you
    to enter the settings needed for that particular type of project and create
    the necessary files for you.

    \QDS projects are useful for creating UIs. You cannot use them for
    application development, because they do not contain:

    \list
        \li C++ code
        \li Resource files (.qrc)
        \li Code needed for deploying applications to devices.
    \endlist

    Because the projects do not contain any C++ code, you do not need
    to build them. To test how well your designs work, you can preview the
    UIs on the desktop or embedded Linux devices. For more
    information, see \l{Validating with Target Hardware}.

    \image studio-project-wizards.png "A list of project wizards"

    You can export designs from other design tools and import them to projects
    or create them from scratch using the following wizards:

    \list
        \li \uicontrol {Qt for MCUs Application} creates an application that
            uses a subset of preset components (as supported by Qt for MCUs)
            that you can deploy, run, and debug on MCU boards.
        \li \uicontrol {Qt Quick Application - Empty} creates a project that
            uses default components and preset UI controls and can be run on
            all target platforms.
        \li \uicontrol {Qt Quick 3D Application} creates a project that uses
            default components, UI controls, and 3D components.
        \li \uicontrol {Qt Quick Application - Scroll} and
            \uicontrol {Qt Quick Application - Stack} create an application
            that uses UI controls to implement a scrollable list or a set of
            pages with a stack-based navigation model.
        \li \uicontrol {Qt Quick Application - Launcher} creates a
            project that uses default components and UI controls and
            defines a launcher application.
    \endlist

    For an example of creating a \uicontrol {Qt Quick 3D Application} project,
    watch the following video:

    \youtube 9ihYeC0YJ0M

    \section1 Using Project Wizards

    \list 1
        \li Select \uicontrol File > \uicontrol {New File or Project}.
        \li Select the type of your project, and then select \uicontrol Choose.
        \li In the \uicontrol Name field, enter a name for the project.
            When naming your own projects, keep in mind that they cannot be
            easily renamed later.
        \li In the \uicontrol {Create in} field, enter the path for the project
            files, and then select \uicontrol Next (or \uicontrol Continue on
            \macos). You can move project folders later without problems.
        \li In the \uicontrol {Screen resolution} field, select the screen
            resolution for previewing the UI on the desktop or on a device.
            You can easily change the screen size later in \l Properties.
        \li In the \uicontrol {Qt Quick Controls Style} field, select one of
            the predefined \l{Styling Qt Quick Controls}{UI styles} to use,
            and then select \uicontrol Finish (or \uicontrol Done on \macos).
    \endlist

    \QDS creates the following files and folders:

    \list
        \li .qmlproject project file defines that all component, JavaScript, and
            image files in the project folder belong to the project. Therefore,
            you do not need to individually list all the files in the project.
        \li .qml file defines the functionality and appearance of a component.
        \li \e Screen01.ui.qml defines a custom component that you can edit in
            \l{Form Editor}. For more information, see \l {UI Files}.

            By default, this is the main file in the project, but you can
            change that in the .qmlproject file. While the custom component
            is a good starting point for new users, you don't have to use it.
            Specifically, if you export and import designs using \QB, your main
            file is most likely called something else. For more information,
            see \l {Exporting from Design Tools}.
        \li qtquickcontrols2.conf file specifies the preferred style and some
            style-specific arguments.
        \li \e fonts folder contains font files that you have added in
            \l Library > \uicontrol Assets.
        \li \e imports folder contains a \e {Constants.qml} file that specifies
            a font loader for the Arial font and the screen resolution. The size
            of the default Screen.ui.qml \l{basic-rectangle}{Rectangle} should
            be set as \c {width: Constants.width & height: Constants.height} so
            that it inherits the global resolution saved here.
        \li \e qmldir module definition file declares the Constant component.
            For more information, see \l {Module Definition qmldir Files}.
    \endlist

    To use JavaScript and image files in the UI, select \uicontrol Library >
    \uicontrol Assets > \inlineimage plus.png
    .

    \section1 Adding Files to Projects

    You can use wizards also to add individual files to your projects.
    You can create the following types of files:

    \list
        \li \uicontrol {Qt Quick Files}
            \list
                \li \uicontrol {Flow Item} and \uicontrol {Flow View}
                    generate components that you can use to design the
                    \l{Designing Application Flows}{application flow}.
                \li \uicontrol {Qt Quick File} generates a component with one
                    of the following default components or \l{Using Positioners}
                    {positioners} as the root component: \l {basic-item}{Item},
                    \l {basic-rectangle}{Rectangle}, \l {Images}{Image},
                    \l {Border Image}, \l Flickable, Row, Column, Flow, or Grid.
                \li \uicontrol {Qt Quick UI File} generates a component file
                    with one of the above components as the root component.
                \li \uicontrol {Qt Quick Views} generates a Grid View or a
                    List View. For more information, see \l{List and Grid Views}.

            \endlist
        \li \uicontrol {Qt Quick Controls} create stylable versions of the
            components in the Qt Quick Controls module:
            \list
                \li \l {Button}{Custom Button} creates a push button with a text
                    label.
                \li \l {Check Box}{Custom CheckBox} creates a check box.
                \li \l {Slider and Dial}{Custom Dial} creates a dial.
                \li \l {Slider and Dial}{Custom Slider} creates a slider.
                \li \l {Spin Box}{Custom SpinBox} creates a spin box.
                \li \l {Switch}{Custom Switch} creates a switch with on and off
                    states.
                \li \l [Qt Quick Controls 2] {Pane} provides a background that
                    matches the UI style and theme.
                \li \l [Qt Quick Controls 2] {StackView} provides a stack-based
                    navigation model.
                \li \l [Qt Quick Controls 2] {SwipeView} enables users to
                    navigate pages by swiping sideways.
            \endlist
            For more information, see \l{Creating Custom Controls}.
        \li \uicontrol ListModel adds a \l{Editing List Models}{list model} to
            the project.
        \li \uicontrol {JavaScript File} generates files that you can use to
            write the application logic. This is useful for testing the
            application before the developers implement the application logic
            in C++, for example. For more information, see
            \l {Simulating Application Logic}.
    \endlist
*/
