qt-creator/doc/qtcreator/src/user-interface/creator-ui.qdoc

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

// **********************************************************************
// 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 {Tutorials}
    \nextpage creator-using-qt-quick-designer.html
    \else
    \previouspage creator-overview.html
    \nextpage creator-views.html
    \endif

    \title User Interface

    \if defined(qtcreator)
    When you start \QC, it opens to the \uicontrol Welcome mode.

    \image qtcreator-breakdown.png {Welcome mode}

    \table
    \header
        \li Number
        \li UI Control
        \li Purpose
        \li Read More
    \row
        \li \inlineimage numbers/01.png
        \li Mode selector
        \li Perform a particular task, such as designing the UI, writing code, or
            debugging the application.
        \li \l{Switch between modes}
    \row
        \li \inlineimage numbers/02.png
        \li Kit selector
        \li Select the appropriate \l{glossary-buildandrun-kit}{kit} for building
            the project and running it on particular hardware.
        \li \l{Activating Kits for a Project}
    \row
        \li \inlineimage numbers/03.png
        \li Run button
        \li Run the application on the selected target platform.
        \li \l{Running on Multiple Platforms}
    \row
        \li \inlineimage numbers/04.png
        \li Debug button
        \li Debug the application on the selected target platform.
        \li \l{Debugging}
    \row
        \li \inlineimage numbers/05.png
        \li Build button
        \li Build the application using the selected kit.
        \li \l{Building for Multiple Platforms}
    \row
        \li \inlineimage numbers/06.png
        \li Locator
        \li Find a particular project, file, class, or function.
        \li \l{Searching with the Locator}
    \row
        \li \inlineimage numbers/07.png
        \li Output
        \li View output from building, running, and other actions.
        \li \l{Viewing Output}
    \endtable

    To see where the above controls are in the UI, select
    \uicontrol Help > \uicontrol {UI Tour}.

    The following video shows the parts of the UI and the \uicontrol Welcome
    mode:

    \youtube hOx3dod5-1A

    \section1 What's New?

    For information about new features and bug fixes in each \QC release,
    select \uicontrol Help > \uicontrol {Change Log}.

    \sa {Use the UI}{How-to: Use the UI}

    \else

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

    \list
        \li Open recent projects
        \li Create and open projects
        \li Open tutorials and example projects
        \li Read news from the online community and Qt blogs
        \li Create or manage a Qt Account
    \endlist

    \image studio-welcome-mode.webp {Welcome mode}

    \endif

    \if defined(qtdesignstudio)
    \section1 Customizing the Menu

    By default, top-level menu items \uicontrol Build, \uicontrol Debug, and
    \uicontrol Analyze are not visible. These menu items have options for
    advanced functionality.

    To toggle the visibility of these menu items:
    \list 1
      \li Go to \uicontrol Edit > \uicontrol Preferences.
      \li On the \uicontrol Environment tab, select
      \uicontrol{Qt Design Studio Configuration}.
      \li Clear the checkbox for the items that you want to be visible.
    \endlist

    \image studio-menu-item-visibility.png

    You need to restart \QDS to apply changes made to these settings.

    \section1 Customizing the UI

    The following topics describe how to customize the UI:

    \list
        \li \l {Find menu items on \macos}
        \li \l {Set high DPI scaling}
        \li \l {Switch UI themes}
    \endlist

    \section1 Viewing Images

    The following topics describe how to use the image viewer:

     \list
        \li \l {Export SVG images}
        \li \l {View images}
    \endlist

    \endif
*/

/*!
    \page creator-output-panes.html
    \if defined(qtdesignstudio)
    \previouspage creator-editor-functions.html
    \nextpage creator-highlighting.html
    \else
    \previouspage creator-open-documents-view.html
    \nextpage creator-configuring.html
    \endif

    \title Viewing Output

    \image qtcreator-general-messages.webp {General Messages}

    You can view the following types of output:

    \list

       \li \l {Issues}

       \li \l {Search Results}

       \li \l {Application Output}

       \li \l {Compile Output}

       \if defined(qtcreator)
       \li \l {Terminal}
       \endif

       \li \uicontrol {QML Debugger Console}

       \li \uicontrol{General Messages}

       \if defined(qtcreator)
       \li \l {Static Code Analysis}{Axivion}
       \endif

       \li \uicontrol{Version Control}

       \if defined(qtcreator)
       \li \l{Running Autotests}{Test Results}

       \li \l{Using Squish}{Squish} test results and Squish Server and
            Runner logs

       \li \l {To-Do Entries}

       \endif

    \endlist

    Output is available on the taskbar in all
    \if defined(qtcreator)
    \l{Switch between modes}{modes}.
    \else
    \l{Mode}{modes}.
    \endif

    \image qtcreator-output-panes-taskbar.webp "Output on the taskbar"

    You can view output in the following ways:

    \list
        \li Select the output view on the taskbar.
        \li Select \key Alt (\key Cmd on \macos) and the number of the view on
            the taskbar.
        \li Select \inlineimage icons/output-pane-menu.png
            , and then select the view to open.
        \li Select \uicontrol View > \uicontrol Output.
            The menu items also display the \l{Keyboard Shortcuts}
            {keyboard shortcuts} that you can use.
    \endlist

    To maximize an open output view, select the \inlineimage icons/arrowup.png
    (\uicontrol Maximize) button or press \key {Alt+Shift+9}.


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

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

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

    If the text in the output is not displayed correctly, \QC might
    be using a different codec from the one used by the tools that generate
    the output. To specify the codec to use, select \uicontrol Edit >
    \uicontrol Preferences > \uicontrol Environment > \uicontrol Interface, and
    then select the codec in the \uicontrol {Text codec for tools} field.

    \image qtcreator-preferences-environment-interface.webp {Interface tab in Environment preferences}

    \section1 Finding and Filtering Output

    To search from output, press \key {Ctrl+F} when the view 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 icons/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 views.

    \section1 Issues

    \uicontrol{Issues} lists the following types of issues:

    \list

        \if defined(qtdesignstudio)
        \li \uicontrol {Asset Export} - Errors and warnings encountered
            while exporting assets.

        \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}.
        \li \uicontrol {Clang Tools} - Errors and warnings from
            \l {Using Clang Tools}{Clang-Tidy and Clazy}
        \endif

        \li \uicontrol Compile - Selected output from the compiler. Open
            \uicontrol {Compile Output} 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}
            {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}.

        \if defined(qtcreator)
        \li \uicontrol Sanitizer - Tasks created when you run an application if
            you used an \e {address sanitizer} to detect memory handling issues.
        \endif
    \endlist

    The view filters out irrelevant output from the build tools and presents the
    issues in an organized way. To further filter the output by type, select
    \inlineimage icons/filtericon.png
    (\uicontrol {Filter Tree}) and then select a filter. To find output in the
    view, enter search criteria in the \uicontrol Filter field.

    \image qtcreator-issues.webp {Issues}

    Select one or several lines to apply context-menu actions to their contents.
    You can remove the selected lines or copy their contents to the clipboard.
    For single lines, you can search the Internet for a solution using the
    contents of the line as search criteria or open a version control
    annotation view of the line that causes the error message.

    To view detailed information about the selected line (where available), press
    \key Space.

    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 \l {Compile Output},
    select \uicontrol {Show Compile Output} in the context menu.

    To jump from one issue to the next or previous
    one, select \inlineimage icons/arrowup.png
    and \inlineimage icons/arrowdown.png
    or press \key F6 and \key Shift+F6.

    By default, a new build clears the \uicontrol Issues view. To keep
    the issues from the previous build rounds, deselect \uicontrol Edit >
    \uicontrol Preferences > \uicontrol {Build & Run} > \uicontrol General >
    \uicontrol {Clear issues list on new build}.

    \section1 Search Results

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

    \image qtcreator-search-results.webp {Search Results - criteria}

    The search history (1) stores the search results. You can select earlier
    searches from the history.

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

    \image qtcreator-search-results-matches.webp {Search Results - matches found}

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

    \section1 Application Output

    \uicontrol{Application Output} displays the status of a program when
    you execute it, and the debug output.

    \image qtcreator-application-output.webp {Application Output}

    \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 Edit > \uicontrol Preferences > \uicontrol {Build & Run} >
    \uicontrol {Application Output}, or click the \inlineimage icons/settings.png
    (\uicontrol {Open Settings Page}) button. You can select whether to open
    \uicontrol{Application Output} 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

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

    \image qtcreator-compile-output.webp {Compile Output}

    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} view on output
    when building applications, select \uicontrol Edit > \uicontrol Preferences >
    \uicontrol {Build & Run} > \uicontrol {Compile Output}, and then select the
    \uicontrol {Open Compile Output when building} check box.
    In the \uicontrol {Limit output to} field, you can specify the maximum
    amount of build output lines to display.

    You can also open the preferences page by clicking \inlineimage icons/settings.png
    (\uicontrol {Open Settings Page}).

    To copy the output 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 \l Issues. By default, the
            view 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 Terminal

    When you select the \uicontrol {Run in Terminal} check box and run an
    application or the \uicontrol {Open Terminal} button to open a terminal,
    the default terminal opens. On Linux and \macos, you can set the default
    terminal by selecting \uicontrol Edit > \uicontrol Preferences >
    \uicontrol Environment > \uicontrol System.

    To open the terminal on the taskbar instead of in a separate window, select
    \uicontrol Edit > \uicontrol Preferences > \uicontrol Terminal >
    \uicontrol {Use internal terminal}.

    \image qtcreator-output-terminal.webp {Terminal pane}

    To clear the terminal, select \inlineimage icons/clean_pane_small.png
    (\uicontrol Clear).

    To close the current terminal, select \inlineimage icons/terminal-close.png
    .

    To open new terminals as tabs, select \inlineimage icons/terminal-create.png
    .

    To move between terminals, select the tabs or \inlineimage icons/arrowup.png
    and \inlineimage icons/arrowdown.png
    .

    To select a word in a terminal, double-click it. To select the whole line,
    triple-click it.

    To open links in a browser, files in the editor, or folders in the
    \l Projects view, hover the mouse over them, and press \key Ctrl.

    To \l{Finding and Replacing}{search} through the output, press \key {Ctrl+F}.

    To make the font larger or smaller, select the \inlineimage icons/plus.png
    and \inlineimage icons/minus.png
    buttons. You can also change the font size in terminal preferences.

    To open terminal preferences, select \inlineimage icons/settings.png
    (\uicontrol Configure).

    Most of the \QC keyboard shortcuts are disabled in the terminal, except the
    ones for opening terminal preferences or the locator and quitting \QC. To
    send the escape key to the terminal instead of closing the terminal, select
    \uicontrol {Shift+Esc}. You can also specify that the escape key is sent to
    the terminal in terminal preferences.

    \section2 Setting Terminal Preferences

    To set preferences for the internal terminal, select \uicontrol Edit >
    \uicontrol Preferences > \uicontrol Terminal, or select the
    \uicontrol Configure button in the \uicontrol Terminal pane.

    \image qtcreator-preferences-terminal.webp {Terminal tab in Preferences}

    \table
    \header
        \li Option
        \li Value
    \row
        \li \uicontrol {Use internal terminal}
        \li Open the \uicontrol Terminal pane when you select
            \uicontrol {Run in Terminal} or \uicontrol {Open Terminal}.
    \row
        \li \uicontrol {Send escape key to terminal}
        \li Send the escape key to the terminal instead of closing the terminal.
    \row
        \li \uicontrol {Audible bell}
        \li Play an audible bell when the a bell character is received.
    \row
        \li \uicontrol {Allow blinking cursor}
        \li Allow the cursor to blink.
    \row
        \li \uicontrol {Font}
        \li Select the \uicontrol {Font family} and \uicontrol Size for the text
            in the terminal. You can also use the \inlineimage icons/plus.png
            and \inlineimage icons/minus.png buttons in the \uicontrol Terminal
            pane to change the font size.
    \row
        \li \uicontrol {Colors}
        \li Set colors for the \uicontrol Terminal pane \uicontrol Foreground,
            \uicontrol Background, \uicontrol Selection, and
            \uicontrol {Find match}.
    \row
        \li \uicontrol {Default shell}
        \li Set the full path to the default terminal executable in
            \uicontrol {Shell path} and the arguments to pass to the shell
            in \uicontrol {Shell arguments}.
    \endtable

    To use an existing color scheme, select \uicontrol {Load Theme}. To revert
    color changes, select \uicontrol {Reset Theme}.

    \section1 To-Do Entries

    \uicontrol {To-Do Entries} 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-to-do-entries.webp {To-Do Entries}

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

    \image qtcreator-todo-options.png {To-Do preferences}

    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.

    \image qtcreator-todo-excluded-files.png {Excluded Files in To-Do preferences}

    Select \uicontrol Add and double-click the placeholder text in
    \uicontrol {Exclude Files} to 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.

    Select the link in \uicontrol {Use global settings} to open global
    To-Do preferences.

    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 \l Issues. For more information, see
    \l{Showing Task List Files in Issues}.
    \endif

*/