/****************************************************************************
**
** 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 wizard templates
    prompt you to enter the settings needed for a 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 wizard templates:

    \table
    \header
        \li Category
        \li Wizard Template
        \li Purpose
    \row
        \li {1,2} General
        \li Qt Quick Application - Empty
        \li Creates a project that uses default components and preset UI
            controls and can be run on all target platforms.
    \row
        \li Qt Quick 3D Application
        \li Creates a project that uses default components, UI controls, and
            3D components.
    \row
        \li Qt for MCUs
        \li Qt for MCUs Application
        \li 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.
    \row
        \li {1,2} Mobile
        \li Qt Quick Application - Scroll
        \li Creates an application that uses UI controls to implement a
            scrollable list.
    \row
        \li Qt Quick Application - Stack
        \li Creates an application that uses UI controls to implement a
            set of pages with a stack-based navigation model.
    \row
        \li Desktop
        \li Qt Quick Application - Launcher
        \li Creates a project that uses default components and UI controls and
            defines a launcher application.
    \endtable

    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 Project}.
        \li Select a wizard template, and then select \uicontrol Choose.
        \li In the \uicontrol Name field, enter a name for the project.
            Keep in mind that projects cannot be easily renamed later.
            \image studio-project-location.png "Project Location dialog"
        \li In the \uicontrol {Create in} field, enter the path for the project
            files. You can move project folders later without problems.
        \li Select \uicontrol Next (or \uicontrol Continue on \macos).
        \li In the \uicontrol {Screen resolution} field, select the screen
            resolution for previewing the UI on the desktop or on a device.
            This determines the screen size.
            \image studio-project-custom-screen-size.png "Define Project Details dialog"
        \li To use a custom screen size, specify the width and height of the
            screen in the \uicontrol {Custom screen width} and
            \uicontrol {Custom screen height} fields.
            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.
        \li Select the \uicontrol {Use Qt Virtual Keyboard} check box to enable
            users to enter text using a virtual keyboard.
        \li In the \uicontrol {Target Qt Version} field, select the Qt version
            to use for developing the application. While you can change the
            Qt version later in the \uicontrol {Run Settings} of the project,
            keep in mind that the two versions are not fully compatible.
        \li Select \uicontrol Finish (or \uicontrol Done on \macos) to create
            the project.
    \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 wizard templates also to add individual files to projects.

    The wizard templates in the \uicontrol {Qt Quick Controls} category create
    stylable versions of the components in the \uicontrol {Qt Quick Controls}
    module. For more information, see \l{Creating Custom Controls}.

    You can create the following types of files:

    \table
    \header
        \li Category
        \li Wizard Template
        \li Purpose
    \row
        \li {1,4} Qt Quick Files
        \li Flow Item and Flow View
        \li Generate components that you can use to design the
            \l{Designing Application Flows}{application flow}.
    \row
        \li Qt Quick File
        \li 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.
    \row
        \li Qt Quick UI File
        \li Generates a UI file with one of the above components as the root
            component.
    \row
        \li Qt Quick Views
        \li Generates a Grid View or a List View. For more information, see
            \l{List and Grid Views}.
    \row
        \li {1,9} Qt Quick Controls
        \li Custom Button
        \li Creates a \l {Button}{push button} with a text label.
    \row
        \li Custom \CheckBox
        \li Creates a \l {Check Box}{check box}.
    \row
        \li Custom Dial
        \li Creates a \l {Slider and Dial}{dial}.
    \row
        \li Custom Slider
        \li Creates a \l {Slider and Dial}{slider}.
    \row
        \li Custom \SpinBox
        \li Creates a \l {Spin Box}{spin box}.
    \row
        \li Custom Switch
        \li Creates a \l {Switch}{switch} with on and off states.
    \row
        \li \l Pane
        \li Provides a background that matches the UI style and theme.
    \row
        \li StackView
        \li Provides a stack-based navigation model.
    \row
        \li SwipeView
        \li Enables users to navigate pages by swiping sideways.
    \row
        \li QML Files
        \li ListModel
        \li Adds a \l{Editing List Models}{list model} to the project.
    \row
        \li JavaScript
        \li JavaScript File
        \li 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}.
    \endtable
*/
