path: root/doc/src/howto/creator-ui.qdoc

/****************************************************************************
**
** Copyright (C) 2017 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 {Qt Creator Manual}
    \previouspage creator-overview.html
    \page creator-quick-tour.html
    \nextpage creator-configuring.html

    \title User Interface

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

    \list

        \li Open recent sessions and 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 qtcreator-breakdown.png

    You can use the 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 locator (6) to to browse through projects, files, classes,
    functions, documentation, and file systems.

    \section1 Modes

    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 Window > \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"

    You can use \QC in the following modes:

    \list

        \li \uicontrol Welcome mode for opening projects.

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

        \li \uicontrol{\l{Designing User Interfaces}{Design}} mode for designing and
            developing application user interfaces. This mode is available for
            UI files.

        \li \uicontrol{\l{Debugging}{Debug}} mode for inspecting the state of your
            application while debugging and for using code analysis tools
            to detect memory leaks and profile C++ or QML code.

        \li \uicontrol{\l{Specifying Build Settings}{Projects}} mode for configuring
            project building and execution. This mode is available when a
            project is open.

        \li \uicontrol{\l{Getting Help}{Help}} mode for viewing Qt documentation.

    \endlist

    Certain actions in \QC trigger a mode change. Clicking on \uicontrol {Debug} >
    \uicontrol {Start Debugging} > \uicontrol {Start Debugging} automatically switches to
    \uicontrol {Debug} mode.

    \section1 Browsing Project Contents

    A left and right sidebar are available in most \QC modes. The availability
    of the sidebars and their contents depend on the mode.

    In the \uicontrol Edit mode, you can use the sidebars to browse projects,
    files, and bookmarks, and to view the class hierarchy.

    \image qtcreator-sidebar.png

    You can select the contents of the sidebars in the sidebar menu (1):

    \list

        \li \uicontrol Projects shows a list of projects open in the current
            session and the project files needed by the build system.

        \li \uicontrol{Open Documents} shows currently open files.

        \li \uicontrol Bookmarks shows all bookmarks for the current session.

        \li \uicontrol{File System} shows all files in the currently selected
             directory.

        \li \uicontrol {Class View} shows the class hierarchy of the currently
            open projects.

        \li \uicontrol Outline shows the symbol hierarchy of a C++ file and the type
            hierarchy of a QML file.

        \li \uicontrol Tests lists autotests and Qt Quick tests in the project.
            For more information, see \l {Running Autotests}.

        \li \uicontrol {Type Hierarchy} shows the base classes of a class.

        \li \uicontrol {Include Hierarchy} shows which files are included in the current file
            and which files include the current file.

    \endlist

    For more information about the sidebar views that are only
    available when editing QML files in the Design mode, see
    \l{Editing QML Files in Design Mode}.

    You can change the view of the sidebars in the following ways:

    \list

        \li To toggle the left sidebar, click \inlineimage leftsidebaricon.png
            (\uicontrol {Hide Left Sidebar/Show Left Sidebar}) or press
            \key Alt+0 (\key Cmd+0 on \macos). To toggle the right
            sidebar, click \inlineimage rightsidebaricon.png
            (\uicontrol {Hide Right Sidebar/Show Right Sidebar}) or press
            \key Alt+Shift+0 (\key Cmd+Shift+0 on \macos).

        \li To split a sidebar, click \inlineimage splitbutton_horizontal.png
            (\uicontrol {Split}). Select new content to view in the split view.

        \li To close a sidebar view, click \inlineimage splitbutton_closetop.png
            (\uicontrol {Close}).

    \endlist

    The additional options in each view are described in the following
    sections.

    In some views, right-clicking opens a context menu that contains functions
    for managing the objects listed in the view.

    \section2 Viewing Project Files

    The sidebar displays projects in a project tree. The project tree contains
    a list of all projects open in the current session. For each project, the
    tree visualizes the build system structure of the project and lists all
    files that are part of the project.

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

    If the project is under version control, information from the version control system
    might be displayed in brackets after the project name. This is currently implemented for
    Git (the branch name or a tag is displayed) and ClearCase (the view name is displayed).

    You can use the project tree in the following ways:

    \list

        \li To open files that belong to a 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
            and image files in the \l{Viewing Images}{image viewer}.

        \li To bring up a context menu containing 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,
            build, re-build, clean and run the project.

        \li To hide the categories and sort project files alphabetically, click
            \inlineimage filtericon.png
            (\uicontrol {Filter Tree}) and select \uicontrol{Simplify Tree}.

        \li To hide source files which are automatically generated by the build
            system, select \uicontrol {Filter Tree > Hide Generated Files}.

        \li To stop synchronizing the position in the project tree with the file
            currently opened in the editor, deselect \inlineimage linkicon.png
            (\uicontrol {Synchronize with Editor}). You can specify a keyboard
            shortcut to use when synchronization is needed. Select
            \uicontrol Tools > \uicontrol Options > \uicontrol Environment >
            \uicontrol Keyboard, and then search for
            \uicontrol {Show in Explorer}.

        \li To see the absolute path of a file, move the mouse pointer over the
            file name.

    \endlist

    Files that are not sources or data can be still included into a project's
    distribution tarball by adding their paths to the \c DISTFILES variable in
    the .pro file. This way they also become known to \QC, so that they are
    visible in the \uicontrol Projects view and are known to the locator and search.

    The \uicontrol Projects view contains context menus for managing projects,
    subprojects, folders, and files. The following functions are available for
    managing projects and subprojects:

    \list

        \li Set a project as the active project.

        \li Execute the \uicontrol Build menu commands.

        \li Add subprojects, libraries, directories, and files.

        \li Remove subprojects.

        \li Search from the selected directory.

        \li Close projects.

    \endlist

    For managing files and directories, the same functions are available as in
    the \uicontrol {File System} view. In addition, you can remove and rename
    files.

    \section2 Viewing the File System

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

    \image qtcreator-filesystem-view.png

    By default, the contents of the directory that contains the file currently
    active in the editor are displayed. To stop the synchronization, delesect
    the \uicontrol {Synchronize Root Directory with Editor} button.

    The path to the active file is displayed
    as bread crumbs. You can move to any directory along the path by clicking
    it. To hide the bread crumbs, select \inlineimage filtericon.png
    (\uicontrol Options) and then deselect the \uicontrol {Show Bread Crumbs}
    check box.

    To move to the root directory of the
    file system, select \uicontrol Computer in the menu (1). Select
    \uicontrol Home to move to the user's home directory. Further, you can
    select a project to move to an open project or \uicontrol Projects to open
    the \uicontrol Projects view.

    By default, folders are separated from files and listed first in the view.
    To list all items in alphabetic order, select \uicontrol Options and then
    deselect the \uicontrol {Show Folders on Top} check box.

    To also show hidden files, select \uicontrol Options >
    \uicontrol {Show Hidden Files}.

    To stop the synchronization with the file currently opened in the editor,
    deselect \uicontrol {Synchronize with Editor}.

    Use the context menu functions to:

    \list

        \li Open files with the default editor or some other editor.

        \li Open a project located in the selected directory.

        \li Show the file or directory in the file explorer.

        \li Open a terminal window in the selected directory or in the directory
            that contains the file.

        \li Search from the selected directory.

        \li View file properties, such as MIME type, default editor, and size.

        \li Create new files. For more information, see
            \l{Adding Files to Projects}.

        \li Rename or remove existing files.

        \li Create new folders.

        \li Compare the selected file with the currently open file in the diff
            editor. For more information, see \l{Comparing Files}.

        \li Display the contents of a particular directory in the view.

        \li Collapse all open folders.

    \endlist

    \section2 Viewing the Class Hierarchy

    The \uicontrol {Class View} shows the class hierarchy of the currently
    open projects. To organize the view by subprojects, click
    \inlineimage qtcreator-show-subprojects.png
    (\uicontrol {Show Subprojects}).

    To visit all parts of a namespace, double-click on the namespace item
    multiple times.

    \section2 Viewing QML Types

    The \uicontrol Outline view shows the type hierarchy in a QML file.

    \list

        \li To see a complete list of all bindings, select \uicontrol {Filter Tree >
            Show All Bindings}.

        \li To stop the synchronization with the QML type selected in the
            editor, deselect \uicontrol {Synchronize with Editor}.

    \endlist

    \section2 Viewing Type Hierarchy

    To view the base classes of a class, right-click the class and select
    \uicontrol {Open Type Hierarchy}  or press \key {Ctrl+Shift+T}.

    \section2 Viewing Include Hierarchy

    To view which files are included in the current file and which files include
    the current file, right-click in the editor and select \uicontrol {Open Include Hierarchy}
    or press \key {Ctrl+Shift+I}.

    \section1 Viewing Output

    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 {Debugger Console}

       \li \uicontrol {To-Do Entries}

       \li \uicontrol{Version Control}

       \li \uicontrol{General Messages}

       \li \uicontrol{Test Results}

    \endlist

    Output panes are available in all \l{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 search within the \uicontrol{Application Output} and \uicontrol{Compile Output}
    panes, press \key {Ctrl+F} when the pane is active. Enter search criteria in
    the \uicontrol Find field and click the left and right arrows to search down and
    up in the pane. In these panes, you can also use the zoom buttons to increase and
    decrease the text size of the output.

    To open the \uicontrol{General Messages} and \l{Using Version Control Systems}
    {Version Control} panes, select
    \uicontrol {Window > Output Panes}. To display the \uicontrol {To-Do Entries} pane,
    enable the Todo plugin.

    \section2 Issues

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

    \list

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

        \li \uicontrol {Clang Code Model} -
            \l {Parsing C++ Files with the Clang Code Model}
            {Errors and warnings from the current editor}.

        \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.

        \li \uicontrol Debugger - Errors encountered while running the
            \l{Analyzing Code}{Valgrind code analysis tools}.

       \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}.

        \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.

        \li \uicontrol QML - Errors in QML syntax.

        \li \uicontrol {QML Analysis} - Results of the JavaScript
            \l{Checking JavaScript and QML Syntax}
            {code syntax and validation checks}

    \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-build-issues.png

    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.

    \section2 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}.

    \section2 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

    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 General. 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.

    \section2 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-pane.png

    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 General, and then select the
    \uicontrol {Open Compile Output pane when building} check box.
    In the \uicontrol {Limit build output to} field, you can specify the maximum
    amount of build output lines to display in the pane.

    \section2 Debugger Console

    In the \uicontrol {Debugger Console}, you can type JavaScript expressions and use them to get
    information about the state of your application during debugging. You can change property
    values temporarily, without editing the source, and view the results in the running
    application.

    \image qml-script-console.png "Debugger Console"

    You can change the property values permanently in the code editor.

    \section2 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 and restart
    \QC.

    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}.

    \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 > Options > Environment} and select a language
    in the \uicontrol Language field. The change takes effect after you restart \QC.

    \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 receive a freely scalable icon in the SVG format from an UI designer,
    you can export it to several images of different sizes to create a set of
    pixmaps. You can then use QIcon::addPixmap() to add the pixmaps to icons in
    different modes and states.

    \section1 Navigating with Keyboard

    \QC caters not only to developers who are used to using the mouse,
    but also to developers 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
    speed up the process of developing your application.

    \section1 Useful Features

    For a list of useful \QC features described in other parts of the
    documentation, see \l{Tips and Tricks}.

    \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

    \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

    \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.
*/