/****************************************************************************
**
** Copyright (C) 2018 The Qt Company Ltd.
** Contact: https://www.qt.io/licensing/
**
** This file is part of the Qt Creator 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.
**
****************************************************************************/

// **********************************************************************
// NOTE: the sections are not ordered by their logical order to avoid
// reshuffling the file each time the index order changes (i.e., often).
// Run the fixnavi.pl script to adjust the links to the index order.
// **********************************************************************

/*!
    \contentspage index.html
    \previouspage creator-project-qmake-libraries.html
    \page creator-project-wizards.html
    \nextpage creator-project-wizards-json.html

    \title Adding New Custom Wizards

    If you have a team working on a large application or several applications,
    you might want to standardize the way the team members create projects and
    files.

    You can copy the wizard templates in the template folders to create your own
    project and file wizards. They are displayed in the \uicontrol New
    dialog that opens when you choose \uicontrol File >
    \uicontrol {New File or Project}.

    A custom wizard defines the user interface of a set of wizard pages. The
    values the user enters in the wizard are assigned field names. Field name
    and value pairs are then passed to the file creation process.

    \section1 Wizard Types

    In a project wizard, you can specify the files needed in a project.
    You can add wizard pages to allow developers to specify settings for the
    project.

    A file wizard is similar, but does not contain any project file.

    You are encouraged to create JSON-based wizards. They provide a super-set
    of the functionality available in the XML based wizards used before. For
    more information, see:

    \list
        \li \l{Adding JSON-Based Wizards}
        \li \l{Adding XML-Based Wizards} (deprecated)
    \endlist

    \section1 Locating Wizards

    Wizards are located in subdirectories of the following directories:

    \list

        \li \c {share/qtcreator/templates/wizards}

        \li the local user's configuration folder,
            \c {$HOME/.config/QtProject/qtcreator/templates/wizards} on Linux
            and \macos or \c {%APPDATA%\QtProject\qtcreator\templates\wizards} on
            Windows

    \endlist

    \note If you installed \QC on \macos, you can find the wizards in
    \c {Qt Creator.app/Contents/Resources/templates/wizards}.

    \section1 Tips for Wizard Development

    \QC has some actions that can improve the wizard development process. These
    are by default not bound to any keyboard shortcuts and can thus not be
    triggered. To enable them, assign keyboard shortcuts in \uicontrol Tools >
    \uicontrol Options > \uicontrol Environment > \uicontrol Keyboard >
    \uicontrol Wizard.

    The following actions can help with wizard development:

    \table
        \header
            \li Action Id
            \li Description

        \row
            \li \uicontrol Inspect
            \li Triggering this action opens a window that lists all the
                defined fields and variables in the wizard at the time the
                action was triggered. Each activation of this action opens a
                new non-modal window, so you can compare state at different
                pages of the wizard for example.

        \row
            \li \uicontrol {Factory.Reset}
            \li Triggering this action makes \QC forget all wizard factories,
                causing it to reload all wizard definitions when for example
                opening \uicontrol File > \uicontrol {New File or Project}.
                This way you can avoid having to restart \QC for your changes to
                a wizard definition to become visible.
    \endtable

    \section2 Verbose Output

    When developing custom wizards (both JSON as well as XML based), it is
    recommended to start \QC with the \c {-customwizard-verbose} argument. It
    causes each correctly set up wizard to produce output along the following
    lines:

    \code
    Checking "/home/jsmith/.config/QtProject/qtcreator/templates/wizards/mywizard"
    for wizard.json.
    * Configuration found and parsed.
    \endcode

    The output includes the name of the directory that was checked for a
    \c wizard.json file. If the file is not found, the message is not displayed.

    If the file contains errors, such as an invalid icon path, the following
    types of messages are displayed:

    \code
    Checking "/home/jsmith/.config/QtProject/qtcreator/templates/wizards/mywizard"
    for wizard.json.
    * Configuration found and parsed.
    * Failed to create: Icon file
    "/home/jsmith/.config/QtProject/qtcreator/templates/wizards/mywizard/../..
    /global/genericfilewizard.png" not found.
    \endcode

    See \l{Using Command Line Options} for more information about command line
    arguments.
*/