qt-creator/doc/qtcreator/src/howto/creator-ui.qdoc

/****************************************************************************
**
** Copyright (C) 2020 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.
// **********************************************************************

/*!
    \page creator-quick-tour.html
    \if defined(qtdesignstudio)
    \previouspage exporting-from-qt3ds.html
    \else
    \previouspage creator-overview.html
    \endif
    \nextpage creator-modes.html

    \title User Interface

    When you start \QC, it opens to the \uicontrol Welcome mode, where you can:

    \list
        \if defined(qtcreator)
        \li Open recent sessions
        \endif

        \li Open recent projects

        \li Create and open projects

        \li Open tutorials and example projects

        \if defined(qtcreator)
        \li Browse Qt extensions in the \l{https://marketplace.qt.io/}
            {Qt Marketplace}
        \endif

        \li Read news from the online community and Qt blogs

        \li Create or manage a Qt Account

    \endlist

    \if defined(qtcreator)
    \image qtcreator-breakdown.png
    \else
    \image studio-welcome-mode.png
    \endif

    \if defined(qtcreator)
    You can use the \l{Selecting Modes}{mode selector} (1) to change to another
    \QC mode.

    You can use the kit selector (2) to select the
    \l{glossary-buildandrun-kit}{kit} for running (3), debugging (4), or
    building (5) the application. Output from these actions is displayed in the
    output panes (7).

    You can use the \l{Searching with the Locator}{locator} (6) to browse
    through projects, files, classes, functions, documentation, and file
    systems.

    For a quick tour of the user interface that takes you to the locations of
    these controls, select \uicontrol Help > \uicontrol {UI Tour}.

    The following sections describe some \QC controls in more detail:

    \list
        \li \l{Selecting Modes}{Mode selector}
        \li \l{Working with Sidebars}{Sidebars}
        \li \l{Browsing Project Contents}{Views}
        \li \l{Managing Workspaces}{Workspaces}
        \li \l{Viewing Output}{Output panes}
    \endlist

    \else
    You can use the \l{Selecting Modes}{mode selector} to switch to the
    \l{Editing QML Files in Design Mode}{Design mode} (1), where you will do
    most of your work and the \l{Using the Help Mode}{Help} (2) mode, where
    you can read the product documentation. The other modes are for more
    advanced use, and you are likely to need them less often.

    Below the mode selector, you can find shortcuts to some more advanced
    functions, such as running the application or finding problems in the
    QML code by debugging or profiling it.
    \endif

    \section1 Navigating with Keyboard

    \QC caters not only to those users who like to use the mouse, but also
    to those who are more comfortable with the keyboard. A wide range of
    \l{keyboard-shortcuts}{keyboard} and \l{Searching with the Locator}
    {navigation} shortcuts are available to help you work faster.

    \if defined(qtcreator)
    \section1 Useful Features

    For a list of useful \QC features described in other parts of the
    documentation, see \l{How-tos}.
    \endif

    \section1 Changing Languages

    \QC has been localized into several languages. If the system language
    is one of the supported languages, it is automatically selected. To
    change the language, select \uicontrol Tools > \uicontrol Options >
    \uicontrol Environment and select a language in the \uicontrol Language
    field. Select \uicontrol {Restart Now} to restart \QC and have the change
    take effect.

    \section1 Viewing Images

    \QC opens image files in the image viewer.

    \image qtcreator-image-viewer.png "Image viewer"

    Use the toolbar buttons (1) or \l{Keyboard Shortcuts}{keyboard shortcuts}
    to:

    \list

        \li Export SVG images to pixmaps

        \li Switch between background and outline modes

        \li Zoom in and out

        \li Fit images to screen

        \li Return to original size

        \li Play and pause animated GIF and MNG images

    \endlist

    \section2 Exporting SVG Images

    If you have a freely scalable icon in the SVG format,
    you can export it to several images of different sizes to create a set of
    pixmaps.
    \if defined(qtcreator)
    You can then use QIcon::addPixmap() to add the pixmaps to icons in
    different modes and states.
    \endif

    \section1 Platform Notes

    This section describes the cases where the behavior of \QC depends on the
    operating system it runs on.

    \section2 Location of Functions

    \QC uses standard names and locations for standard features, such as
    \e options or \e preferences. In this manual, the names and locations on
    Windows and Linux are usually used to keep the instructions short. Here are
    some places to check if you cannot find a function, dialog, or keyboard
    shortcut on \macos when following the instructions:

    \table
        \header
            \li For
            \li Look In
        \row
            \li \uicontrol Tools > \uicontrol Options
            \li \uicontrol {\QC} > \uicontrol Preferences
        \row
            \li \uicontrol Help > \uicontrol {About Plugins}
            \li \uicontrol {\QC} > \uicontrol {About Plugins}
        \row
            \li Keyboard shortcuts
            \li \uicontrol {\QC} > \uicontrol Preferences > \uicontrol Environment >
                \uicontrol Keyboard
    \endtable

    \if defined(qtcreator)
    \section2 Location of Settings Files

    \QC creates the following files and directories:

    \list

        \li QtCreator.db

        \li QtCreator.ini

        \li qtversion.xml

        \li toolChains.xml

        \li qtcreator

        \li qtc-qmldump

    \endlist

    The location of the above files and directories depends on the platform:

    \list

        \li On Linux and other Unix platforms, the files are located in
            \c {~/.config/QtProject} and
            \c {~/.local/share/data/QtProject/qtcreator}.

        \li On \macos, the files are located in \c {~/.config/QtProject} and
            \c {~/Library/Application Support/QtProject/Qt Creator}.

        \li On Windows XP, the files are located in
            \c {%SystemDrive%\Documents and Settings\%USERNAME%\Application Data\QtProject} and
            \c {%SystemDrive%\Documents and Settings\%USERNAME%\Local Settings\Application Data\QtProject}.

        \li On Windows 7, the files are located in
            \c {%SystemDrive%\Users\%USERNAME%\AppData\Roaming\QtProject} and
            \c {%SystemDrive%\Users\%USERNAME%\AppData\Local\QtProject}.

    \endlist
    \endif

    \section2 High DPI Scaling

    The operating systems supported by \QC implement high dots-per-inch (DPI)
    scaling at varying levels. Therefore, \QC handles high DPI scaling
    differently on different operating system:

    \list

        \li On \macos, high DPI scaling is forced, which means that \QC allows
            Qt to use the system scaling factor as the \QC scaling factor.

        \li On Windows, if no \l{High DPI Support in Qt}
            {scaling environment variables} are set, \QC instructs Qt to detect
            the scaling factor and use it for \QC.

        \li On Linux, \QC leaves it to the user to enable high DPI scaling,
            because the process varies so much on different distributions
            and windowing systems that it cannot be reliably done automatically.

    \endlist

    To override the default approach and always enable high-DPI scaling, select
    \uicontrol Tools > \uicontrol Options > \uicontrol Environment >
    \uicontrol {Enable high DPI scaling}. The changes will take effect after you
    restart \QC.
*/

/*!
    \page creator-modes.html
    \previouspage creator-quick-tour.html
    \if defined(qtdesignstudio)
    \nextpage creator-using-qt-quick-designer.html
    \else
    \nextpage creator-sidebars.html
    \endif

    \title Selecting Modes

    \image qtcreator-mode-selector.png

    \if defined(qtcreator)
    The mode selector allows you to quickly switch between tasks such as editing
    project and source files, designing application UIs, configuring how
    projects are built and executed, and debugging your applications. To change
    modes, click the icons, or use the \l{keyboard-shortcuts}
    {corresponding keyboard shortcut}.

    To hide the mode selector and to save space on the display, select
    \uicontrol View > \uicontrol {Mode Selector Style} > \uicontrol Hidden.
    To only show icons on the mode selector, select the \uicontrol {Icons Only}
    style.

    The following image displays an example application in \uicontrol Edit mode (1)
    and \uicontrol Design mode (2).

    \image qtcreator-qt-quick-editors.png "Edit mode and Design mode"
    \endif

    You can use \QC in the following modes:

    \list

        \li \uicontrol {\l{User Interface}{Welcome}} mode for opening projects,
            tutorial, and examples.

        \li \uicontrol{\l{Coding}{Edit}} mode for editing project and source
            files.

        \if defined(qtcreator)
        \li \uicontrol{\l{Designing User Interfaces}{Design}}
            mode for designing and developing application user interfaces.
            This mode is available for UI files.
        \else
        \li \uicontrol{\l{Editing QML Files in Design Mode}{Design}}
            mode for designing and developing application user interfaces.
            As a designer, you'll do most of your work in this mode.
        \endif

        \if defined(qtcreator)
        \li \uicontrol{\l{Debugging}{Debug}}
        \else
        \li \uicontrol {\l{Debugging and Profiling}{Debug}}
        \endif
            mode for inspecting the state of your
            application while debugging and for using code analysis tools
            to detect memory leaks and profile code.

        \if defined(qtcreator)
        \li \uicontrol{\l{Specifying Build Settings}{Projects}} mode
            for configuring project building and execution.
        \else
        \li \uicontrol{\l{Selecting the Preview Tool}{Projects}} mode
            for selecting the tool to use for live preview.
        \endif
            This mode is available when a project is open.

        \li \uicontrol{\l{Using the Help Mode}{Help}} mode for viewing
            documentation.

    \endlist

    \if defined(qtcreator)
    Certain actions in \QC trigger a mode change. Clicking on \uicontrol {Debug} >
    \uicontrol {Start Debugging} > \uicontrol {Start Debugging} automatically switches to
    \uicontrol {Debug} mode.
    \endif
*/

/*!
    \page creator-output-panes.html
    \if defined(qtdesignstudio)
    \previouspage creator-views.html
    \nextpage creator-highlighting.html
    \else
    \previouspage creator-project-managing-workspaces.html
    \nextpage creator-configuring.html
    \endif

    \title Viewing Output

    \image qtcreator-general-messages.png "General Messages output pane"

    The task pane in \QC can display one of the following panes:

    \list

       \li \uicontrol{Issues}

       \li \uicontrol{Search Results}

       \li \uicontrol{Application Output}

       \li \uicontrol{Compile Output}

       \li \uicontrol {QML Debugger Console}

       \li \uicontrol{General Messages}

       \li \uicontrol{Version Control}

       \if defined(qtcreator)
       \li \uicontrol{Test Results}

       \li \uicontrol {To-Do Entries}
       \endif

    \endlist

    Output panes are available in all \l{Selecting Modes}{modes}. Click the name
    of an output pane to open the pane. To maximize an open output pane, click
    the \uicontrol {Maximize Output Pane} button or press \key {Alt+9}.


    To increase or decrease the output text size, select \inlineimage plus.png
    (\uicontrol {Zoom In}) or \inlineimage minus.png
    (\uicontrol {Zoom Out}), or press \key Ctrl++ or \key Ctrl+-. Zooming is
    not supported in all output panes.

    To open the \uicontrol{General Messages} and
    \if defined(qtcreator)
    \l{Using Version Control Systems}{Version Control}
    \else
    \l{Using Git}{Version Control}
    \endif
     panes, select \uicontrol View > \uicontrol {Output Panes}.
    \if defined(qtcreator)
    To display the \uicontrol {To-Do Entries} pane, enable the Todo plugin.
    \endif

    For more information about the \uicontrol {QML Debugger Console} view, see
    \l{Executing JavaScript Expressions}.

    \section1 Finding and Filtering Output

    To search from output, press \key {Ctrl+F} when the pane is active. Enter
    search criteria in the \uicontrol Find field. For more information, see
    \l{Finding and Replacing}.

    Besides searching from the output, you can enter a string in the
    \uicontrol Filter field to filter it. To specify filtering options,
    select the \inlineimage magnifier.png "Filtering options menu"
    button. You can filter output by using regular expressions or
    case-sensitivity. Select \uicontrol {Show Non-matching Lines} to
    hide the lines that match the filter.

    Finding and filtering are not supported in all output panes.

    \section1 Issues

    The \uicontrol{Issues} pane provides lists of following types of issues:

    \list

        \if defined(qtdesignstudio)
        \li \uicontrol {Asset Importer Error} - Errors and warnings encountered
            while importing assets from a design tool.
        \else
        \li \uicontrol Autotests - Errors and warnings encountered while running
            tests.
        \endif

        \li \uicontrol {Build System} - Errors and warnings encountered during a
            build.

        \if defined(qtcreator)
        \li \uicontrol {Clang Code Model} -
            \l {Parsing C++ Files with the Clang Code Model}
            {Errors and warnings from the current editor}.
        \endif

        \li \uicontrol Compile - Selected output from the compiler. Open the
            \uicontrol {Compile Output} pane for more detailed information.

       \li \uicontrol{Debug Information} - Lists debug information packages that might
            be missing.

        \if defined(qtcreator)
        \li \uicontrol Debugger - Errors encountered while running the
            \l{Analyzing Code}{Valgrind code analysis tools}.
        \endif

       \li \uicontrol{Debugger Runtime} - Errors encountered when starting \QC. For
            example, information about missing DLLs.

       \li \uicontrol Deployment - Errors encountered between building an application
            successfully and starting it on a \l{glossary-device}{device}.

        \if defined(qtcreator)
        \li \uicontrol {My Tasks} - Entries from a task list file (.tasks) generated
            by \l{Showing Task List Files in Issues Pane}
            {code scanning and analysis tools}.

        \li \uicontrol Python - Runtime errors and exceptions of Python scripts.
        \endif

        \li \uicontrol QML and \uicontrol {QML Analysis} -
            \l{JavaScript and QML Error Codes}
            {QML and JavaScript syntax errors}.

    \endlist

    The pane filters out irrelevant output from the build tools and presents the
    issues in an organized way. To further filter the output by type, select
    \uicontrol {Filter Tree}
    and then select a filter.

    \image qtcreator-issues.png "Issues output pane"

    Right-clicking on a line brings up a context menu with actions that you can
    apply to the contents of the line. You can remove a line, copy its contents
    to the clipboard, or search the Internet for a solution using the contents
    of the line as search criteria. In addition, you can show a version control
    annotation view of the line that causes the error message.

    To navigate to the corresponding source code, click an issue or
    select \uicontrol {Show in Editor} in the context menu. The entry must contain the
    name of the file where the issue was found.

    To view more information about an issue in the \uicontrol {Compile Output} pane,
    select \uicontrol {Show Output} in the context menu.

    To jump from one issue to the next or previous one, press \key F6 and
    \key Shift+F6.

    By default, the \uicontrol Issues pane is cleared on a new build. To keep
    the issues from the previous build rounds, deselect \uicontrol Tools >
    \uicontrol Options > \uicontrol {Build & Run} > \uicontrol General >
    \uicontrol {Clear issues list on new build}.

    \section1 Search Results

    In the \uicontrol{Search Results} pane, you can search through projects, files on
    a file system or the currently open files:

    \image qtcreator-search-results.png "Search Results output pane"

    The search results are stored in the search history (1) from which you can
    select earlier searches.

    The figure below shows an example search result for all
    occurrences of the search string in the specified directory.

    \image qtcreator-searchresults.png

    For more information about the different search options, see
    \l {Finding and Replacing}.

    \section1 Application Output

    The \uicontrol{Application Output} pane displays the status of a program when
    it is executed, and the debug output.

    \image qtcreator-application-output.png

    \if defined(qtcreator)
    If you specify command line arguments in the run settings that are passed
    to the application when running it, they are displayed as a part of the
    application output. For more information, see
    \l{Specifying Run Settings for Desktop Device Types}.
    \endif

    Select toolbar buttons to run applications, to attach the debugger to the
    running application, and to stop running or debugging.

    To specify settings for displaying application output, select
    \uicontrol Tools > \uicontrol Options > \uicontrol {Build & Run} >
    \uicontrol Application Output, or click the \uicontrol {Open Settings Page}
    button. You can select whether to open the \uicontrol{Application Output} pane
    on output when running or debugging applications, to clear old output on a new run,
    to word-wrap output, and to limit output to the specified number of lines.

    \section1 Compile Output

    The \uicontrol{Compile Output} pane provides all output from the compiler.
    The \uicontrol{Compile Output} is a more detailed version of information
    displayed in the \uicontrol{Issues} pane.

    \image qtcreator-compile-output.png "Compile Output pane"

    Double-click on a file name in an error message to open the file in the
    code editor.

    Select the \uicontrol {Cancel Build} button to cancel the build.

    To specify whether to open the \uicontrol {Compile Output} pane on output
    when building applications, select \uicontrol Tools > \uicontrol Options >
    \uicontrol {Build & Run} > \uicontrol Compile Output, and then select the
    \uicontrol {Open pane when building} check box.
    In the \uicontrol {Limit output to} field, you can specify the maximum
    amount of build output lines to display in the pane.

    You can also reach the options page by clicking the \uicontrol {Open Settings Page}
    button.

    To copy the output from the pane to the clipboard, select
    \uicontrol {Select All} in the context menu, and then select
    \uicontrol Copy. Save the output as a file if you want to
    examine it later without having to build the project again.
    This is useful for large projects that take a long time to build.

    \section2 Parsing Existing Compile Output

    You can use \QC's output parsers to parse output from builds done outside
    of \QC or stored from previous build runs. By default, the parsers from the
    kit selected for the active project are used, but you can select another
    kit.

    To parse compile output:

    \list 1
        \li Select \uicontrol Tools > \uicontrol {Parse Build Output}.
            \image qtcreator-parse-build-output.png
        \li Paste the build output in the \uicontrol {Build Output} field, or
            select \uicontrol {Load from File} to load it from a file.
        \li Deselect the \uicontrol {Output went to stderr} check box if the
            parser expects issues on \c stdout.
        \li In the \uicontrol {Use parsers from kit} field, select the kit to
            use for parsing the output. Select \uicontrol Manage to view
            and modify kit settings.
        \li The parser displays the parsed output in the \uicontrol Issues
            pane. By default, the pane is cleared before adding the new output.
            Deselect the \uicontrol {Clear existing tasks} check box to append
            the new output to the old output.
        \li Select \uicontrol OK to start parsing.
    \endlist

    \if defined(qtcreator)
    \section1 To-Do Entries

    The \uicontrol {To-Do Entries} pane lists the BUG, FIXME, NOTE, TODO, and
    WARNING keywords from the current file, from all project files, or from a
    subproject. Click the icons on the toolbar to show only the selected
    keywords.

    \image qtcreator-todo-pane.png

    To add keywords, select \uicontrol Tools > \uicontrol Options >
    \uicontrol {To-Do} > \uicontrol Add. Set an icon and a line background color
    for the keyword.

    \image qtcreator-todo-options.png

    To change the icon and line background color of the selected keyword, select
    \uicontrol Edit.

    To remove the selected keyword, select \uicontrol Remove.

    To reset the list to predefined keywords, select \uicontrol Reset. All your
    changes will be permanently lost.

    To determine whether the keywords in the whole project, in the current file,
    or in a subproject are displayed by default, select the appropriate option
    in the \uicontrol {Scanning scope} group.

    To exclude files from scanning, select \uicontrol {Project Settings} >
    \uicontrol {To-Do} in the
    \uicontrol Projects mode. Select \uicontrol Add and enter a regular
    expression that matches the path to files to exclude. Use a forward slash
    (/) as a separator in the path also on Windows.

    The Todo plugin is disabled by default. To enable the plugin, select
    \uicontrol Help > \uicontrol {About Plugins} > \uicontrol Utilities >
    \uicontrol Todo. Then select \uicontrol {Restart Now} to restart \QC
    and load the plugin.

    In addition, you can open task list files generated by code scanning and
    analysis tools in the \uicontrol Issues pane. For more information, see
    \l{Showing Task List Files in Issues Pane}.
    \endif

*/