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

/*!
    \page creator-projects-view.html
    \previouspage creator-how-tos.html

    \ingroup creator-how-to-ui

    \target Projects
    \title View projects

    Use the \uicontrol Projects view to see a list of projects in a project tree.

    The project tree has a list of all projects open in the current
    \l{Manage sessions}{session}. For each project, the tree visualizes
    the build system structure of the project and lists all files that
    are part of the project.

    \image {qtcreator-projects-view.webp} {Projects view in the sidebar}

    \note Usually, \l{Navigate with locator}{searching with the locator}
    is the fastest way to find a particular project, file, class, or function,
    or almost anything else in your project.

    You can use the project tree in the following ways:

    \list
        \li To open files that belong to a \l{Creating projects}{project},
            double-click them in the project tree. Files open in the
            appropriate editor, according to the file type. For example, code
            source files open in the code editor.
            Use the \l{Switch between modes} {mode selector} to open the current
            file in another editor.
        \li To open a
            \l{Projects view context menu}{context menu}
            that has the actions most commonly needed, right-click an
            item in the project tree. For example, through the menu of
            the project root directory, you can, among other actions, run
            and close the project.
        \li To see the absolute path of a file, move the mouse pointer over the
            file name.
        \li To move files from one project to another, drag them
            in the project tree. \QC makes the necessary changes to project
            configuration files.
    \endlist

    \note If you cannot see a file in the \l Projects view, switch to the
    \uicontrol {File System} view, which shows all the files in the file system.

    \section1 Projects view context menu

    The \uicontrol Projects view has context menus for managing projects,
    subprojects, folders, and files. Use the following functions to manage
    projects and subprojects:

    \list
        \li Set a project as the active project.
        \li Execute \uicontrol Build menu commands.
        \li Create new files. For more information, see
            \l{Adding files}.
        \li Create a corresponding source or header file for a C++ header or
            source file.
        \li Rename existing files. If you change the base name of a
            file, \QC displays a list of other files with the same base name
            and offers to rename them as well. If you rename a UI file (\c .ui),
            \QC also changes the corresponding include statements accordingly.
        \li Remove existing files.
        \li Remove existing directories from \l{Import an existing project}
            {generic projects}.
        \li Add existing files and directories.
        \li Add libraries. For more information, see
            \l{Add libraries to qmake projects}.
        \li Add and remove subprojects.
        \li Find unused functions.
        \li Search in the selected directory.
        \li Apply version control actions to the file or directory, like viewing
            the versioning history of a project directory or showing the diff of
            a modified file. For more information, see \l {git commit}.
        \li Open a terminal window in the project directory. To specify the
            terminal to use on Linux and \macos, select \preferences >
            \uicontrol Environment > \uicontrol System.
            To use an \l{Open a terminal}{internal terminal}, select \preferences >
            \uicontrol Terminal > \uicontrol {Use internal terminal}.
        \li Open a terminal window in the project directory that you configured
            for building or running the project.
        \li Expand or collapse the tree view to show or hide all files and
            folders.
        \li Close all files in a project.
        \li Close the selected project or all projects except the selected
            one. By default, this closes all files in the projects. To keep
            them open, go to \preferences > \uicontrol {Build & Run} >
            \uicontrol General, and clear \uicontrol {Close source files along with project}.
    \endlist

    For managing files and directories, use the same functions as in
    the \l {File System} view. To view a project in it, select
    \uicontrol {Show in File System View}.

    \section1 Projects view toolbar

    The toolbar in the \uicontrol Projects view has additional options.

    To filter view contents, select \inlineimage {icons/filtericon.png} {Filter Tree}
    (\uicontrol {Filter Tree}):

    \list
        \li \uicontrol {Simplify Tree} hides the categories and sorts project
            files alphabetically.
        \li \uicontrol {Hide Generated Files} hides the source files that the
            build system automatically generates.
        \li \uicontrol {Hide Disabled Files} hides the source files that you
            have not enabled for the current target.
        \li \uicontrol {Hide Empty Directories} hides directories that do not
            have any files.
        \li \uicontrol {Show Source and Header Groups} shows source and header
            files grouped together in the view, regardless of their location in
            the file system.
    \endlist

    To stop synchronizing the position in the project tree with the file
    currently opened in the editor, clear
    \inlineimage {icons/linkicon.png} {Synchronize with Editor}
    (\uicontrol {Synchronize with Editor}).

    Some build systems support adding and removing files to a project in \QC
    (currently qmake and Qbs). The faithful display of the project structure
    enables you to specify exactly where to place a new file in the build system.

    If you cannot see some files, you might have to declare them as part of the
    project. For more information, see \l{Specify project contents}.

    If the project is under version control, you might see information
    from the version control system in brackets after the project name.
    \QC currently implements this for Git (the view displays the branch name
    or a tag) and ClearCase (the view displays the branch name).

    \sa {View CMake project contents}, {File System}
*/
