path: root/doc/qtcreator.qdoc

/****************************************************************************
**
** This file is part of Qt Creator
**
** Copyright (c) 2011 Nokia Corporation and/or its subsidiary(-ies).
**
** Contact: Nokia Corporation (info@qt.nokia.com)
**
**
** GNU Free Documentation License
**
** 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.
**
** If you have questions regarding the use of this file, please contact
** Nokia at qt-info@nokia.com.
**
****************************************************************************/

// **********************************************************************
// 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}{Qt Creator}
    \page index.html
    \nextpage creator-overview.html

    \title Qt Creator Manual

    \section1 Version \qtcversion

    Qt Creator provides a cross-platform, complete integrated development
    environment (IDE) for application developers to create applications for
    multiple desktop and mobile device platforms. It is available for Linux,
    Mac OS X and Windows operating systems. For more information, see
    \l{Operating Systems and Supported Platforms}.

    \note Please report bugs and suggestions to the
    \l{http://bugreports.qt.nokia.com}{Qt Bug Tracker}.
    You can also join the Qt Creator mailing list at:
    \l{http://lists.qt.nokia.com}{http://lists.qt.nokia.com}.

    \raw HTML
    <img border="0" style="float:right;" src="images/qtcreator-screenshots.png" />
    \endraw

    \list
       \o \l{Introducing Qt Creator}
       \o \l{Qt Creator User Interface}
       \o \l{Getting Started}
           \list
               \o \l{Building and Running an Example Application}
               \o \l{Creating a Qt Widget Based Application}
               \o \l{Creating a Mobile Application with Qt SDK}
               \o \l{Creating a Qt Quick Application}
           \endlist
       \o \l{Managing Projects}
            \list
                \o \l{Creating a Project}
                \o \l{Opening a Project}
                \o \l{Adding Libraries to Projects}
                \o \l{Connecting Maemo and MeeGo Harmattan Devices}
                \o \l{Connecting Symbian Devices}
                \o \l{Managing Sessions}
            \endlist
       \o \l{Coding}
            \list
                \o \l{Using the Editor}
                \o \l{Semantic Highlighting}
                \o \l{Checking Code Syntax}
                \o \l{Completing Code}
                \o \l{Finding and Replacing}
                \o \l{Refactoring}
                \o \l{Using Qt Quick Toolbars}
                \o \l{Searching With the Locator}
                \o \l{Pasting and Fetching Code Snippets}
                \o \l{Using Text Editing Macros}
                \o \l{Configuring the Editor}
                \o \l{Using FakeVim Mode}
            \endlist
       \o \l{Developing Application UI}
       \list
           \o \l{Developing Qt Quick Applications}
                \list
                    \o \l {Creating Qt Quick Projects}
                    \o \l {Using Qt Quick Designer}
                    \o \l {Creating Components}
                    \o \l {Creating Buttons}
                    \o \l {Creating Scalable Buttons and Borders}
                    \o \l {Creating Screens}
                    \o \l {Animating Screens}
                    \o \l {Adding User Interaction Methods}
                    \o \l {Exporting Designs from Graphics Software}
                    \o \l {Implementing Application Logic}
                \endlist
           \o \l{Developing Widget Based Applications}
           \o \l{Optimizing Applications for Mobile Devices}
       \endlist
       \o \l{Building and Running Applications}
            \list
                \o \l{Building Applications for Multiple Targets}
                \o \l{Running Applications on Multiple Targets}
                \o \l{Specifying Build Settings}
                   \list
                       \o \l{Adding Qt Versions}
                       \o \l{Adding Tool Chains}
                   \endlist
                \o \l{Specifying Run Settings}
                \o \l{Specifying Editor Settings}
                \o \l{Specifying Dependencies}
            \endlist
       \o \l{Debugging}
            \list
                \o \l{Debugging the Example Application}
                \o \l{Launching the Debugger}
                \o \l{Interacting with the Debugger}
                \o \l{Setting Up Debugger}
                \o \l{Using Debugging Helpers}
                \o \l{Debugging Qt Quick Projects}
                \o \l{Detecting Memory Leaks}
                \o \l{Troubleshooting Debugger}
            \endlist
       \o \l{Deploying Applications to Mobile Devices}
            \list
                \o \l{Deploying Applications to Symbian Devices}
                \o \l{Deploying Applications to Maemo or MeeGo Harmattan Devices}
                \o \l{Publishing Maemo Applications to Extras-devel}
                \o \l{Publishing Applications to Ovi Store}
                \o \l{Building with Remote Compiler}
            \endlist
       \o \l{Getting Help}
       \o \l{Advanced Use}
           \list
               \o \l{Operating Systems and Supported Platforms}
               \o \l{Adding New Custom Wizards}
               \o \l{Setting Up a CMake Project}
               \o \l{Setting Up a Generic Project}
               \o \l{Using Version Control Systems}
               \o \l{Adding Qt Designer Plugins}
               \o \l{Using External Tools}
               \o \l{Using Maemo or MeeGo Harmattan Emulator}
               \o \l{Editing MIME Types}
               \o \l{Showing Task List Files in the Build Issues Pane}
               \o \l{Using Command Line Options}
               \o \l{Keyboard Shortcuts}
           \endlist
       \o \l{FAQ}
       \o \l{Tips and Tricks}
       \o \l{Known Issues}
       \o \l{Glossary}
       \o \l{Acknowledgements}
    \endlist
*/


/*!
    \contentspage index.html
    \previouspage index.html
    \page creator-overview.html
    \nextpage creator-quick-tour.html

  \title Introducing Qt Creator

    Qt Creator is an integrated development environment (IDE) that provides you with
    tools to design and develop applications with the Qt application framework. Qt is designed for
    developing applications and user interfaces once and deploying them across several
    desktop and mobile operating systems. Qt Creator provides you with tools for
    accomplishing your tasks throughout the whole application development life-cycle,
    from creating a project to deploying the application on the target platforms.

    \image qtcreator-overview.png "Qt Creator overview"

    \section1 Cross-platform Development

    One of the major advantages of Qt Creator is that it allows a team of developers
    to share a project across different development platforms with a common tool
    for development and debugging.

    The recommended way to build a project is to use a version control system.
    Store and edit only project source files and the .pro and .pri files (for qmake)
    or CMakeLists.txt and *.cmake files (for CMake). Do not store
    files generated by the build system or Qt Creator, such as makefiles,
    .pro.user, and object files. Other approaches are possible,
    but we recommend that you do not use network resources, for example.

    Qt Creator allows you to specify separate build settings
    for each development platform. By default, \l{glossary-shadow-build}{shadow builds} are used to
    keep the build specific files separate from the source.

    You can create separate versions of project files to keep platform-dependent
    code separate. You can use qmake
    \l{http://qt.nokia.com/doc/4.7/qmake-tutorial.html#adding-platform-specific-source-files}{scopes}
    to select the file to process depending on which platform qmake is run on.

    Items such as open files, breakpoints, and watchers are stored in
    sessions. They are not considered to be part of the
    information shared across platforms.

    \section1 Creating Projects

    But why do you need projects? To be able to build and run applications,
    Qt Creator needs the same information as a compiler would need. This information
    is specified in the project build and run settings.

    Creating a project allows you to:

        \list

            \o Group files together

            \o Add custom build steps

            \o Include forms and resource files

            \o Specify settings for running applications

        \endlist

    Setting up a new project in Qt Creator is aided by a wizard that guides
    you step-by-step through the project creation process. In the first step, you
    select the type of the project from the categories: Qt Quick project, Qt widget
    project, or other project. Next, you select a location for the project and
    specify settings for it.

    \image qtcreator-new-qt-quick-project-wizard.png

    When you have completed the steps, Qt Creator automatically generates the
    project with required headers, source files, user interface descriptions
    and project files, as defined by the wizard.
    For example, if you choose to create a Qt Quick application, Qt Creator
    generates a QML file that you can modify with the integrated \QMLD.

    \section2 Adding Libraries

    In addition to Qt libraries, you can link your application to other
    libraries, such as system libraries or your own libraries. Further, your
    own libraries might link to other libraries. To be able to compile your
    project, you must add the libraries to your project. This also enables
    code completion and syntax highlighting for the libraries.
    The procedure of adding a library to a project depends on the build
    system that you use.

    \section2 Version Control Systems

    Qt Creator uses the version control system's command line clients to access
    your repositories. The following version control systems are supported:

    \list

        \o Git

        \o Subversion

        \o Perforce

        \o CVS

        \o Mercurial

        \o Bazaar

    \endlist

    The functions available to you in Qt Creator depend on the version control
    system. Basic functions are available for all the supported systems. They include
    comparing files with the latest versions stored in the repository and displaying the
    differences, viewing versioning history and change details, annotating files,
    and committing and reverting changes.

    \section1 Designing User Interfaces

    Qt Creator provides two integrated visual editors, \QMLD and \QD.

    \image qtcreator-ui-designers.png "Qt Quick Designer and Qt Designer"

    Large high-resolution screens, touch input, and significant graphics power
    are becoming common in portable consumer devices, such as mobile
    phones, media players, set-top boxes, and netbooks. To fully benefit from
    these features and to create intuitive, modern-looking, fluid user interfaces,
    you can use \l {http://doc.qt.nokia.com/4.7/qtquick.html}{Qt Quick}.

    Qt Quick consists of a rich set of user interface elements, a declarative
    language for describing user interfaces, and a language runtime. A
    collection of C++ APIs is used to integrate these high level features with
    classic Qt applications.

    You can edit QML code in the code editor or in the integrated \QMLD.
    The integration includes project management and code completion.

    If you need a traditional user interface that is clearly structured and
    enforces a platform look and feel, you can use the integrated \QD. You can
    compose and customize your widgets or dialogs and test them using different
    styles and resolutions.

    \section1 Code Editor

    As an IDE, Qt Creator differs from a text editor in that it knows how to build and run
    applications. It understands the C++ and QML languages as code, not just as plain text. This allows
    it to:

    \list

        \o Enable you to write well formatted code

        \o Anticipate what you are going to write and complete the code

        \o Display inline error and warning messages

        \o Enable you to semantically navigate to classes, functions, and symbols

        \o Provide you with context-sensitive help on classes, functions, and symbols

        \o Rename symbols in an intelligent way, so that other symbols with the same name
         that belong to other scopes are not renamed

        \o Show you the locations in code where a function is declared or called

    \endlist

    You can use the code editor to write code in Qt C++ or in the
    QML declarative programming language.
    QML is an extension to JavaScript, that provides a mechanism to declaratively build
    an object tree of QML elements. QML improves the integration between JavaScript and
    Qt's existing QObject based type system, adds support for automatic property bindings
    and provides network transparency at the language level.

    \section1 Building

    Qt Creator is integrated with cross-platform systems for build automation:
    qmake and CMake. In addition, you can import generic projects that do not use qmake
    or CMake, and specify that Qt Creator ignores your build system.

    Qt Creator provides support for building and running Qt applications for
    desktop environment (Windows, Linux, and Mac OS) and mobile devices
    (Symbian, Maemo, and MeeGo Harmattan).
    Build settings allow you to quickly switch between build targets.

    When you install the \QSDK, the build and run settings for the Harmattan,
    Maemo, and Symbian
    targets are set up automatically. However, you need to install and configure some
    additional software on the devices to be able to connect to them from the
    development PC.

    \note The only supported build system for mobile applications in Qt
    Creator is qmake.

    \section1 Testing

    If you install Qt Creator as part of \QSDK, the GNU Symbolic Debugger
    is installed automatically and you should be ready to start debugging after
    you create a new project. However, you can change the setup to use debugging
    tools for Windows, for example.
    You can connect mobile devices to your development PC and debug processes
    running on the devices.

    You can test applications that are intended for mobile devices in Qt
    Simulator and Maemo or MeeGo Harmattan emulator, but you also need to test
    the applications
    on real devices.

    \section2 Debuggers

    Qt Creator is integrated to several external native debuggers:

    \list

        \o GNU Symbolic Debugger (GDB)

        \o Microsoft Console Debugger (CDB)

        \o internal JavaScript debugger

    \endlist

    You can use the Qt Creator \gui Debug mode to inspect the state of your
    application while debugging. You can interact with the debugger in several
    ways, including the following:

    \list
        \o Go through a program line-by-line or instruction-by-instruction.
        \o Interrupt running programs.
        \o Set breakpoints.
        \o Examine the contents of the call stack.
        \o Examine and modify registers and memory contents of
           the debugged program.
        \o Examine and modify registers and memory contents of
           local and global variables.
        \o Examine the list of loaded shared libraries.
        \o Create snapshots of the current state of the debugged program
           and re-examine them later.
    \endlist

    Qt Creator displays the raw information provided by the native debuggers
    in a clear and concise manner with the goal to simplify the debugging process
    as much as possible without losing the power of the native debuggers.

    In addition to the generic IDE functionality provided by stack view, views for
    locals and watchers, registers, and so on, Qt Creator includes
    features to make debugging Qt-based applications easy. The debugger
    plugin understands the internal layout of several Qt classes, for
    example, QString, the Qt containers, and most importantly QObject
    (and classes derived from it), as well as most containers of the C++
    Standard Library and some GCC and Symbian extensions. This
    deeper understanding is used to present objects of such classes in
    a useful way.

    \section3 QML Script Console

    You can use the Qt Creator \gui Debug mode to inspect the state of
    the application while debugging JavaScript functions. You can set breakpoints,
    view call stack trace, and examine locals and watchers.

    When the application is interrupted by a breakpoint, you can use the \gui {QML
    Script Console} to execute JavaScript expressions in the current context. You can
    type JavaScript expressions and use them to get information about the state of the
    application, such as property values.

    If you change property values or add properties in the code editor, the
    changes are updated in the running application when they are saved.

    \section3 QML Observer

    While the application is running, you can use the \gui {QML Observer} view to
    explore the object structure, debug animations, and inspect colors. When debugging
    complex applications, you can use the observe mode to jump to the position in code
    where an element is defined.

    \section2 Qt Simulator

    You can use the Qt Simulator to test Qt applications that are intended
    for mobile devices in an environment similar to that of the device. You
    can change the information that the device has about its configuration
    and environment.

    The Qt Simulator is installed as part of the \QSDK. After it is
    installed, you can select it as a build target in Qt Creator.

    \section2 Maemo and MeeGo Harmattan Emulator

    The Maemo 5 (Fremantle) and MeeGo Harmattan emulator are installed as part
    of the \QSDK. After they are installed, you can start them from Qt Creator.

    The Maemo 5 emulator emulates the Nokia N900 device environment. You can test
    applications in conditions practically identical to running the application
    on a Nokia N900 device with the software update release 1.3 (V20.2010.36-2).

    The Harmattan emulator emulates the Nokia N950 device environment.

    With the emulators, you can test how your application reacts to hardware
    controls, such as the power button, and to the touch screen.
    Usually, it is faster to test on a real device connected to the development
    PC than to use the emulators.

    \section1 Deploying

    Qt Creator deploy configurations handle the packaging of the application as an
    executable and copying it to a location developers want to run the executable at.
    The files can be copied to a location in the file system of the development PC
    or to a mobile device.

    Qt Creator allows you to create installation packages for Symbian, Maemo,
    and MeeGo Harmattan
    devices that are suitable for publishing on Ovi Store and other channels.

*/

/*!
    \contentspage index.html
    \previouspage creator-advanced.html
    \page creator-os-supported-platforms.html
    \nextpage creator-project-wizards.html

    \title Operating Systems and Supported Platforms

    \section1 Operating Systems

    Qt Creator is available in binary packages for the following operating
    systems:
    \list
        \o Windows 7
        \o Windows XP Service Pack 2
        \o Windows Vista
        \o (K)Ubuntu Linux 8.04 (32-bit and 64-bit) or later, with the following:
           \list
               \o g++
               \o make
               \o libglib2.0-dev
               \o libSM-dev
               \o libxrender-dev
               \o libfontconfig1-dev
               \o libxext-dev
               \o libfreetype6-dev
               \o libx11-dev
               \o libxcursor-dev
               \o libxfixes-dev
               \o libxft-dev
               \o libxi-dev
               \o libxrandr-dev
               \o If you are using QtOpenGL, libgl-dev and libglu-dev
           \endlist
        \o Mac OS 10.5 or later with the following:
           \list
               \o Xcode tools for your Mac OS X version available from your Mac
                  OS X installation DVDs or at \l http://developer.apple.com.
           \endlist
    \endlist

         \omit  ## Are the Xcode tools still needed separately? \endomit

    \section1 Compiling Qt Creator from Source

    To build Qt Creator itself from the source, see the requirements and
    instructions in the readme file that is located in the source repository.

    \section1 Supported Platforms

    You can develop applications for the following platforms:

    \list

        \o Desktop

        \o Qt Simulator

        \o Maemo 5

        \o MeeGo Harmattan

        \o Symbian

    \endlist

    The following table summarizes operating system support for developing
    applications for mobile device platforms.

    \table
        \header
            \o {1,5} Operating system
            \o {5,1} Platform
        \header
            \o Desktop
            \o Qt Simulator
            \o Maemo 5
            \o MeeGo Harmattan
            \o Symbian

        \row
            \o Windows
            \o Yes
            \o Yes
            \o Yes
            \o Yes
            \o Yes
        \row
            \o Linux
            \o Yes
            \o Yes
            \o Yes
            \o Yes
            \o Yes (by using Remote Compiler for building)
        \row
            \o Mac OS X
            \o Yes
            \o Yes
            \o Yes
            \o Yes
            \o Yes (by using Remote Compiler for building)
    \endtable
*/


/*!
    \contentspage index.html
    \previouspage creator-overview.html
    \page creator-quick-tour.html
    \nextpage creator-getting-started.html

    \title Qt Creator User Interface

    \image qtcreator-breakdown.png

    When you start Qt Creator, it opens to the \gui Welcome mode, where you can:

    \list

        \o Open tutorials and example projects

        \o View tips and hints on using Qt Creator

        \o Create and open projects

        \o Send feedback to the development team

        \o Open recent sessions and projects

        \o Read news from the Qt labs

        \o Ask for support

    \endlist

    You can use the mode selector to change to another Qt Creator mode.
    The following image displays an example application in \gui Edit mode
    and \gui Design mode.

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

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

    \section1 Qt Creator 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}.

    You can use Qt Creator in the following modes:

    \list
        \o \gui Welcome mode for opening projects.
        \o \gui{\l{Using the Editor}{Edit}} mode for editing project and source files.
        \o \gui{\l{Developing Application UI}{Design}} mode for designing and developing
           application user interfaces. This mode is available for UI files (.ui or
           .qml).
        \o \gui{\l{Debugging}{Debug}} mode for inspecting the state of your program while
           debugging.
        \o \gui{\l{Specifying Build Settings}{Projects}} mode for configuring project building and
           execution. This mode is available when a project is open.
        \o \gui{\l{Getting Help}{Help}} mode for viewing Qt documentation.
    \endlist

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


    \section1 Browsing Project Contents

    The sidebar is available in the \gui Edit and \gui Debug modes.
    Use the sidebar to browse projects, files, and bookmarks, and to view
    the class hierarchy.
    \image qtcreator-sidebar.png

    You can select the content of the sidebar in the sidebar menu:
    \list
        \o \gui Projects shows a list of projects open in the current
           session.
        \o \gui{Open Documents} shows currently open files.
        \o \gui Bookmarks shows all bookmarks for the current session.
        \o \gui{File System} shows all files in the currently selected
            directory.
        \o \gui {Class View} shows the class hierarchy of the currently
            open projects.
        \o \gui Outline shows the symbol hierachy of a C++ file and the element hierarchy of a QML file.
        \o \gui {Type Hierarchy} shows the base classes of a class.

    \endlist

    You can change the view of the sidebar in the following ways:
    \list
        \o To toggle the sidebar, click \inlineimage qtcreator-togglebutton.png
           or press \key Alt+0 (\key Cmd+0 on Mac OS X).
        \o To split the sidebar, click \inlineimage qtcreator-splitbar.png
           . Select new content to view in the split view.
        \o To close a sidebar view, click
           \inlineimage qtcreator-closesidebar.png
           .
    \endlist

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

    \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. The files for each
    project are grouped according to their file type.

    You can use the project tree in the following ways:
    \list
        \o 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.
        \o To hide the categories and sort project files alphabetically, click
           \inlineimage qtcreator-filter.png
           and select \gui{Simplify Tree}.
        \o To hide source files which are automatically generated by the build
           system, during a build, click \inlineimage qtcreator-filter.png
           and select \gui{Hide Generated Files}.
        \o To keep the position in the project tree synchronized with the file
           currently opened in the editor, click
           \inlineimage qtcreator-synchronizefocus.png
           .
        \o To see the absolute path of a file, move the mouse pointer over the
           file name.
    \endlist

    \section2 Viewing the File System

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

    To keep the position in the tree synchronized with the file
    opened in the editor, click
    \inlineimage qtcreator-synchronizefocus.png
    .

    \section2 Viewing the Class Hierarchy

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

    \section2 Viewing QML Elements

    The \gui Outline view shows the element hierarchy in a QML file.

    \list

        \o To see a complete list of all bindings, click
           \inlineimage qtcreator-filter.png
           and select \gui{Show All Bindings}.

        \o To keep the position in the view synchronized with the element
           selected in the editor, click
           \inlineimage qtcreator-synchronizefocus.png
           .

    \endlist

    \section2 Viewing Type Hierarchy

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

    \section1 Viewing Output

    The task pane in Qt Creator can display one of the following panes:
    \list
       \o  \gui{Build Issues}
       \o  \gui{Search Results}
       \o  \gui{Application Output}
       \o  \gui{Compile Output}
       \o  \gui{General Messages}
       \o  \gui{Analysis}
       \o  \gui{Version Control}
    \endlist

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

    To search within the \gui{Application Output} and \gui{Compile Output}
    panes, press \key {Ctrl+F} when the pane is active. Enter search
    criteria in the \gui Find field and click the left and right arrows to
    search down and up in the pane.

    To open the \gui{General Messages}, \gui{Analysis}, and \gui{Version Control}
    panes, select \gui {Window > Output Panes}.


    \section2 Build Issues

    The \gui{Build Issues} pane provides a list of errors and warnings
    encountered during a build. The pane filters out irrelevant output from
    the build tools and presents the issues in an organized way.

    Right-clicking on a line brings up a context menu with options to copy
    the contents and to show a version control annotation view of the
    line that causes the error message.

    \image qtcreator-build-issues.png

    To view task lists in the \gui{Build Issues} pane, click
    \inlineimage qtcreator-filter.png
    and select \gui{My Tasks}. Entries from a task list file (.tasks) are
    imported to the pane. Press \key F6 and \key Shift+F6 to jump from one issue
    to the next.

    For more information about creating task files, see
    \l{Showing Task List Files in the Build Issues Pane}.

    \section2 Search Results

    The \gui{Search Results} pane displays the results for global searches,
    for example, searching within a current document, files on disk, or all
    projects.

    The figure below shows an example search result for all
    occurrences of \c textfinder within the \c "/TextFinder" directory.

    \image qtcreator-search-pane.png


    \section2 Application Output

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

    The figure below shows an example output from qDebug().

    \image qtcreator-application-output.png


    \section2 Compile Output

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

    \image qtcreator-compile-pane.png

    \section1 Navigating with Keyboard

    Qt Creator 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.

*/


/*!
    \contentspage index.html
    \previouspage creator-remote-compiler.html
    \page creator-help.html
    \nextpage creator-advanced.html

    \title Getting Help

    Qt Creator comes fully integrated with Qt documentation and
    examples using the Qt Help plugin.

    \list
        \o To view documentation, switch to \gui Help mode.
        \o To obtain context sensitive help, move the text cursor to a Qt class
           or function and press \key F1. The documentation is displayed in a
           pane next to the code editor, or, if there is not enough vertical
           space, in the fullscreen \gui Help mode.
        \o To select and configure how the documentation is displayed in the
           \gui Help mode, select \gui Tools > \gui Options... > \gui Help.
    \endlist

    The following image displays the \gui Search pane in the \gui Help mode.

    \image qtcreator-help-search.png

    The following image displays the context sensitive help in the \gui Edit
    mode.

    \image qtcreator-context-sensitive-help.png

    \section1 Finding Information in Qt Documentation

    Qt Creator, \QSDK and other Qt deliverables contain documentation
    as .qch files. All the documentation is accessible in the \gui Help mode.

    To find information in the documentation, select:

    \list

        \o \gui Bookmarks to view a list of pages on which you have added bookmarks.

        \o \gui Contents to see all the documentation installed on the development
        PC and to browse the documentation contents.

        \o \gui Index to find information based on a list of keywords in all the
        installed documents.

        \o \gui {Open Pages} to view a list of currently open documentation pages.

        \o \gui Search to search from all the installed documents.

    \endlist

    \section2 Adding Bookmarks to Help Pages

    You can add bookmarks to useful help pages to easily find them later
    in the \gui Bookmarks view. You can either use the page title as the
    bookmark or change it to any text. You can organize the bookmarks in
    folders in the view.

    \image qtcreator-help-add-bookmark-dlg.png "Add Bookmark dialog"

    To add a bookmark to an open help page:

    \list 1

        \o Click the
        \inlineimage qtcreator-help-add-bookmark.png
        (\gui {Add Bookmark}) button on the toolbar.

        \o In the \gui {Add Bookmark} dialog, click \gui OK to save the
        page title as a bookmark in the \gui Bookmarks folder.

    \endlist

    To import and export bookmarks, select \gui {Tools > Options... > Help >
    General Settings > Import} or \gui Export.

    \section1 Adding External Documentation

    You can display external documentation in the \gui Help mode.
    To augment or replace the documentation that ships with Qt Creator and Qt:
    \list 1
        \o Create a .qch file from your documentation.

           For information on how to prepare your documentation and create a
           .qch file, see
           \l{http://doc.qt.nokia.com/4.7/qthelp-framework.html}{The Qt Help Framework}.
        \o To add the .qch file to Qt Creator, select \gui Tools >
           \gui Options... > \gui Help > \gui Documentation > \gui Add.
    \endlist

    \section1 Detaching the Help Window

    By default, context-sensitive help is opened in a window next to the
    code editor when you press \key F1. If there is not enough vertical
    space, the help opens in the full-screen help mode.

    You can specify that the help always opens in full-screen mode or
    is detached to an external window. Select \gui {Tools > Options... > Help >
    General Settings} and specify settings for displaying context-sensitive help
    in the \gui {On context help} field. To detach the help window, select
    \gui {Always Show Help in External Window}.

    You can select the help page to open upon startup in the \gui {Home Page}
    field.

    \section1 Using Documentation Filters

    You can filter the documents displayed in the \gui Help mode to find
    relevant information faster. Select from a list of filters in the
    \gui {Filtered by} field. The contents of the \gui Index and \gui Contents
    pane in the sidebar change accordingly.

    \image qtcreator-help-filters.png "Help filters"

    You can modify the filters to include external documentation, for example,
    or you can define your own filters. To construct filters, you can use the
    filter attributes that are specified in the documentation. Each document
    contains at least one filter attribute. If several documents contain the
    same filter attribute, such as \c tools, you can use that attribute to
    include all those documents.

    To add filters:

    \list 1

        \o Select \gui {Tools > Options... > Help > Filters > Add}.

        \o Enter a name for the filter and press \gui {OK}.

        \o In \gui Attributes, select the documents that you want to include
        in the filter.

        \image qtcreator-help-filter-attributes.png "Help filter attributes"

        \o Click \gui OK.

        \o In the \gui Help mode, select the filter in the \gui {Filtered by}
        field to see the filtered documentation in the sidebar.

    \endlist

    To modify filters, select a filter in \gui Filters, select the attributes,
    and then click \gui Apply.

    To remove filters, select them in \gui Filters, and click \gui Remove.

*/


/*!
    \contentspage index.html
    \previouspage creator-editor-fakevim.html
    \page creator-design-mode.html
    \nextpage creator-visual-editor.html

    \title Developing Application UI

    Large high-resolution screens, touch input, and significant graphics power
    are becoming common in portable consumer devices, such as mobile
    phones, media players, set-top boxes, and netbooks. To fully benefit from
    these features and to create intuitive, modern-looking, fluid user interfaces,
    you can use \l {http://doc.qt.nokia.com/4.7/qtquick.html}{Qt Quick}.

    Qt Quick consists of a rich set of user interface elements, a declarative
    language for describing user interfaces, and a language runtime. A
    collection of C++ APIs is used to integrate these high level features with
    classic Qt applications.

    You can edit QML code in the code editor or in the integrated \QMLD.

    \image qtcreator-design-mode.png "Design mode"

    The integration includes project management and code completion.

    If you need a traditional user interface that is clearly structured and
    enforces a platform look and feel, you can use the integrated \QD. You can
    compose and customize your widgets or dialogs and test them using different
    styles and resolutions.

    The following sections describe how to develop application UI:

       \list

           \o \l{Developing Qt Quick Applications}
           \o \l{Developing Widget Based Applications}
           \o \l{Optimizing Applications for Mobile Devices}

       \endlist

*/


/*!
    \contentspage index.html
    \previouspage quick-application-logic.html
    \page creator-using-qt-designer.html
    \nextpage creator-usability.html

    \title Developing Widget Based Applications

    Widgets and forms created with \QD are integrated seamlessly with
    programmed code by using the Qt signals and slots mechanism that allows you
    to easily assign behavior to
    graphical elements. All properties set in \QD can be changed dynamically within the code.
    Furthermore, features such as widget promotion and custom plugins allow you to use your
    own widgets with \QD. For more information, see
    \l{Adding Qt Designer Plugins}.

    Qt Creator automatically opens all .ui files in the integrated \QD, in
    \gui Design mode.

    \image qtcreator-formedit.png

    For more information about \QD, see the
    \l{http://doc.qt.nokia.com/4.7/designer-manual.html}{Qt Designer Manual}.

    Generally, the integrated \QD contains the same functions as the standalone
    \QD. The following sections describe the differences.

    \section1 Code Editor Integration

    To switch between forms (\gui Design mode) and code (\gui Edit mode),
    press \key Shift+F4.

    You can use Qt Creator to create stub implementations of slot functions.
    In the \gui Design mode, right-click a widget to open a context menu, and
    then select \gui {Go to Slot...}. Select a signal in the list to go to an
    existing slot function or to create a new slot function.

    \section1 Managing Image Resources

    In standalone \QD, image resources are created using the built-in
    \gui {Resource Editor}. In Qt Creator, .ui files are usually part of a
    project, which may contain several resource files (.qrc). They are created
    and maintained by using the Qt Creator Resource Editor. The \QD
    \gui {Resource Editor} is de-activated and the image resources are
    displayed in the \QD \gui {Resource Browser}.

    \section1 Specifying Settings for Qt Designer

    To change the layout of \QD user interface elements:

    \list 1
        \o Select \gui Tools > \gui{Form Editor} > \gui Views >
           \gui Locked.

           When this option is unchecked, you can change the layout.
        \o Click the header of an element and drag the element to a new
           position.
    \endlist

    To specify settings for \QD:

    \list

        \o  Select \gui Tools > \gui Options... > \gui Designer.

        \o  Specify settins for generating classes and code in \gui {Class
            Generation}.

        \o  Specify embedded device profiles, that determine style, font, and
            screen resolution, for example, in \gui{Embedded Design}.

        \o  Specify settings for the grid and previewing forms in \gui Forms.

        \o  Specify an additional folder for saving templates in \gui{Template
            Paths}.

    \endlist

    To preview the settings, select \gui Tools > \gui{Form Editor} >
    \gui Preview, or press \key Alt+Shift+R.

    \section1 Previewing Forms Using Device Skins

    A \e {device skin} is a set of configuration files that describe a mobile
    device. It includes a border image that surrounds the form and depicts a
    mobile device with its buttons.

    To preview your form using device skins:

    \list 1

        \o  Select \gui Tools > \gui Options... > \gui Designer.

        \o  Select the \gui{Print/Preview Configuration} check box.

        \o  In the \gui {Device skin} field, select a device skin.

        \o  When the form is open in \gui Design mode, press \key Alt+Shift+R.

        \o  To end the preview, right-click the skin and select \gui Close in
            the context menu.

    \endlist
*/


/*!
    \contentspage index.html
    \previouspage quick-projects.html
    \page creator-using-qt-quick-designer.html
    \nextpage quick-components.html

    \title Using Qt Quick Designer

    You can edit .qml files in the \QMLD visual editor or in the
    code editor.

    In \gui Projects, double-click a .qml file to open it in the code
    editor. Then select the \gui {Design} mode to edit the file in the
    visual editor.

    \image qmldesigner-visual-editor.png "Visual editor"

    Use the visual editor panes to manage your project:

    \list

    \o \gui {Navigator} pane displays the QML elements in the current QML file
    as tree structure.

    \o \gui {Library} pane displays the building blocks that you can use to design
    applications: predefined QML elements, your own QML components, and other
    resources.

    \o \gui Canvas is the working area where you create QML components and
    design applications.

    \o \gui {Properties} pane organizes the properties of the selected QML element
    or QML component. You can also change the properties in the code editor.

    \o \gui {State} pane displays the different states of the component. QML
    states typically describe user interface configurations, such as the UI
    elements, their properties and behavior and the available actions.

    \endlist

    \section1 Managing Element Hierarchy

    The \gui Navigator pane displays the
    \l{http://doc.qt.nokia.com/4.7/qdeclarativeelements.html}{QML elements}
    in the current QML file and their relationships.
    Elements are listed in a tree structure, below their parent.

    \image qmldesigner-navigator.png "Navigator pane"

    You can select elements in the \gui Navigator to edit their properties
    in the \gui Properties pane. Elements can access the properties of their
    parent element.

    Typically, child elements are located within the parent element on the
    canvas. However, they do not necessarily have to fit inside the parent element.
    For example, you might want to make a mouse area larger than the rectangle
    or image beneath it.

    \image qmldesigner-element-size.png "Mouse area for a button"

    When you copy an element, all its child elements are also copied. When
    you remove an element, the child elements are also removed.

    You can show and hide items to focus on specific parts of the application.
    Click the
    \inlineimage qmldesigner-show-hide-icon.png
    icon to change the visibility of an element on the canvas. To change the
    visibility of an element in the application, use the \gui Visibility
    check box or the \gui Opacity field in the \gui Properties pane. If you set
    \gui Opacity to 0, elements are hidden, but you can still apply animation
    to them.

    As all properties, visibility and opacity are inherited from the parent
    element. To hide or show child elements, edit the properties of the
    parent element.

    To view lists of files or projects, instead, select \gui {File System},
    \gui {Open Documents}, or \gui Projects in the menu.
    To view several types of content at a time, split the sidebar by clicking
    \inlineimage qtcreator-splitbar.png
    .

    \section2 Switching Parent Elements

    When you drag and drop QML elements to the canvas, Qt Quick Designer
    adds the new element as a child of the element beneath it.
    When you move elements on the canvas, Qt Quick Designer cannot determine
    whether you want to adjust their position or attach them to a new
    parent element. Therefore, the parent element is not automatically
    changed. To change the parent of the element, press down the \key Shift
    key before you drag and drop the element into a new position. The topmost
    element under the cursor becomes the new parent of the element.

    You can change the parent of an element also in the \gui Navigator pane.
    Drag and drop the element to another position in the tree.

    \section1 Element Library

    The \gui {Library} pane contains two tabs: \gui {Items} and \gui {Resources}.
    The \gui Items pane displays the QML elements grouped by type: your own QML
    components, basic elements, interaction elements, views, and widgets.

    \omit
    Sets of UI components with the MeeGo and Symbian look and feel have been
    defined for Qt Quick. They are based on standard QML elements. To view the
    UI components in \gui {QML Components}, click
    \inlineimage qtcreator-filter.png
    and select \gui {MeeGo Components} or \gui {Symbian Components}.
    \endomit

    \image qmldesigner-qml-components.png "QML Components pane"

    The \gui {Resources} pane displays the images and other files that you copy to
    the project folder (to the same subfolder as the QML files).

    \section1 Specifying Element Properties

    The \gui Properties pane displays all the properties of the selected QML element.
    The properties are grouped by type. The top part of the pane displays properties
    that are common to all elements, such as element type, position, size,
    and visibility.

    The bottom part of the pane displays properties that are specific to each element
    type. For example, the following image displays the properties you can set for
    \gui Rectangle and \gui Text elements.

    \image qmldesigner-element-properties.png

    The default values of properties are displayed in white color, while the values
    that you specify explicitly are highlighted with blue color. In addition, property
    changes in states are highlighted with blue.

    For more information on the properties available for an element, press \key {F1}.

    \section2 Setting Expressions

    \l{http://doc.qt.nokia.com/4.7/propertybinding.html}{Property binding}
    is a declarative way of specifying the value of a property.
    Binding allows a property value to be expressed as an JavaScript expression
    that defines the value relative to other property values or data accessible
    in the application. The property value is automatically kept up to date if
    the other properties or data values change.

    Property bindings are created implicitly in QML whenever a property is assigned
    an JavaScript expression. To set JavaScript expressions as values of properties
    in Qt Quick Designer, click the circle
    icon next to a property to open a context menu, and select \gui {Set Expression}.

    \image qmldesigner-set-expression.png "Element properties context menu"

    To remove expressions, select \gui Reset in the context menu.

    For more information on the JavaScript environment provided by QML, see
    \l{http://doc.qt.nokia.com/4.7/qdeclarativejavascript.html}{Integrating JavaScript}.

    \section2 Loading Placeholder Data

    Often, QML applications are prototyped with fake data that is later
    replaced by real data sources from C++ plugins. QML Viewer loads fake data
    into the application context: it looks for a directory named \e dummydata
    in the same directory as the target QML file, loads any .qml files in that
    directory as QML objects, and binds them to the root context as properties.
    For more information, see
    \l{http://doc.qt.nokia.com/latest/qmlviewer.html}{QML Viewer}.

    You can use dummydata files also to specify fake properties for QML
    components that you open for editing in \QMLD.
    A QML component provides a way of defining a new UI element that you can
    re-use in other QML files. A component is generally defined in its own QML
    file. You can use property binding to specify the properties of a component
    to make it easily reusable.

    For example, you can create a button bar component (buttonbar.qml) that
    inherits its width from the screen that is its parent:

    \code

    import QtQuick 1.0

    Item {
        width: parent.width
        }

    \endcode

    However, when you open the QML file for editing in \QMLD, the button bar
    component does not have a width, because it is specified outside the QML
    file (in the QML file that specifies the screen). To specify a fake width
    for the component, create a \c <component>_dummydata.qml file (here,
    buttonbar_dummydata.qml) that specifies the component width and copy it to
    the \c dummydata directory.

    For example:

    \code
    import QtQuick 1.0
    import QmlDesigner 1.0

    DummyContextObject {
        parent: QtObject {
        property real width: 1000
        }
    }
    \endcode

    The file is reloaded if you change it.

    \section2 Setting Anchors and Margins

    In addition to arranging elements in a grid, row, or column, you can use
    \l{http://doc.qt.nokia.com/4.7/qml-anchor-layout.html}{anchors} to lay out screens.
    In an anchor-based layout, each item can be thought of as having a set of
    invisible \e anchor lines: top, bottom, left, right, fill, horizontal center,
    vertical center, and baseline.

    In the \gui Layout pane you can set anchors and margins for elements. To set
    the anchors of an item, click the anchor buttons. You can combine the top/bottom,
    left/right, and horizontal/vertical anchors to anchor objects in the corners of
    the parent element or center them horizontally or vertically within the parent
    element.

    \image qmldesigner-anchor-buttons.png "Anchor buttons"

    In version 2.1, specifying the baseline anchor in Qt Quick Designer is
    not supported. You can specify it using the code editor.

    For performance reasons, you can only anchor an element to its siblings and
    direct parent. By default, an element is anchored to its parent when you
    use the anchor buttons. Select a sibling of the element in the \gui Target
    field to anchor to it, instead.

    Arbitrary anchoring is not supported. For example, you cannot specify:
    \c {anchor.left: parent.right}. You have to specify: \c {anchor.left: parent.left}.
    When you use the anchor buttons, anchors to the parent element are always
    specified to the same side. However, anchors to sibling elements are specified
    to the opposite side: \c {anchor.left: sibling.right}. This allows you to keep
    sibling elements together.

    In the following image, \gui{Rectangle 2} is anchored to its siblings on its
    right and left and to the bottom of its parent.

    \image qmldesigner-anchors.png "Anchoring sibling elements"

    The anchors for \gui{Rectangle 2} are specified as follows in code:

    \qml
    Rectangle {
        id: rectangle2
        anchors.right: rectangle3.left
        anchors.rightMargin: 15
        anchors.left: rectangle1.right
        anchors.leftMargin: 15
        anchors.bottom: parent.bottom
        anchors.bottomMargin: 15
        // ...
    }
    \endqml

    Margins specify the amount of empty space to leave to the outside of an item.
    Margins only have meaning for anchors. They do not take any effect when using
    other layouts or absolute positioning.

    \section2 Building Transformations on Items

    The \gui Advanced pane allows you configure advanced transformations, such as
    rotation, scale, and translation. You can assign any number of transformations
    to an item. Each transformation is applied in order, one at a time.

    For more information on Transform elements, see
    \l {http://doc.qt.nokia.com/4.7/qml-transform.html}{QML Transform Element}.

    \section1 Adding States

    User interfaces are designed to present different interface configurations
    in different scenarios, or to modify their appearances in response to user
    interaction. Often, there are a set of changes that are made concurrently,
    such that the interface could be seen to be internally changing from one
    \e state to another.

    This applies generally to interface elements regardless of their complexity.
    A photo viewer may initially present images in a grid, and when an image is
    clicked, change to a detailed state where the individual image is expanded
    and the interface is changed to present new options for image editing.
    On the other end of the scale, when a simple button is pressed, it may change
    to a \e pressed state in which its color and position is modified to give a
    pressed appearance.

    In QML, any object can change between different states to apply sets of changes
    that modify the properties of relevant items. Each state can present a
    different configuration that can, for example:

    \list

        \o Show some UI elements and hide others.

        \o Present different available actions to the user.

        \o Start, stop or pause animations.

        \o Execute some script required in the new state.

        \o Change a property value for a particular item.

        \o Show a different view or screen.

    \endlist

    The \gui State pane displays the different
    \l{http://doc.qt.nokia.com/4.7/qdeclarativestates.html}{states}
    of the component in the Qt Quick Designer.

    \image qmldesigner-transitions.png "State pane"

    To add states, click the empty slot. Then modify the new state in the editor.
    For example, to change the appearance of a button, you can hide the button
    image and show another image in its place. Or, to add movement to the screen,
    you can change the position of an object on the canvas and then add animation
    to the change between the states.

    You can preview the states in the \gui State pane and click them to switch
    between states on the canvas.

    For more information on using states, see \l{Creating Screens}.

    If you add animation to the states, you can run the application to test the
    animation.

    For more information on adding animation, see \l{Animating Screens}.

    \section1 Aligning and Positioning Elements

    The position of an element on the canvas can be either absolute or relative
    to other elements. In the element properties, you can set the x and y
    coordinates of an element, or \l{Setting Anchors and Margins}{anchor} it to its
    parent and sibling elements.

    \section2 Snap to Margins

    When you are working on a design, you can use snap and guides to align
    elements on the canvas. Click the
    \inlineimage qmldesigner-snap-to-guides-button.png
    button to have the elements snap to the guides.

    Choose \gui {Tools > Options... > Qt Quick} to specify settings for snap to
    margins. In the \gui {Snap margin} field, specify the position of the guides
    as pixels  from the edge of the canvas. In the \gui {Item spacing} field,
    specify the space in pixels to leave between elements on the screen.

    The following image shows the position of the guides when \gui {Snap margin}
    is set to 5 pixels.

    \image qmldesigner-snap-margins.png "Snap margins on canvas"

    \section2 Hiding Element Boundaries

    Qt Quick Designer displays the boundaries of elements on the canvas. To hide
    the element boundaries, click the
    \inlineimage qmldesigner-show-bounding-rectangles-button.png
    button.

    \section2 Selecting Elements

    When you point the mouse to overlapping elements, the frontmost element is
    selected by default. However, elements that do not have any content, such as
    the mouse area, are typically located in front of elements that do have
    content, such as rectangles or border images. To select elements with content
    by default, click the
    \inlineimage qmldesigner-only-select-items-with-content.png
    button.

    \section2 Previewing Element Size

    The width and height of the root item in a QML file determine the size of
    the QML element. You can reuse elements, such as buttons, in different
    sizes in other QML files and design screens for use with different device
    profiles, screen resolution, or screen orientation. The component size
    might also be zero (0,0) if its final size is determined by property
    bindings.

    To experiment with different element sizes, enter values in the
    \gui Height and \gui Width fields on the canvas toolbar. The changes are
    displayed in the \gui States pane and on the canvas, but the property
    values are not changed permanently in the QML file. You can permanently
    change the property values in the \gui Properties pane.

    \image qmldesigner-preview-size.png "Canvas width and height"

    \section1 Specifying Canvas Size

    To change the canvas size, select \gui {Tools > Options... > Qt Quick} and
    specify the canvas width and height in the \gui Canvas group.

    \section1 Refreshing the Canvas

    When you open QML files in \QMLD, the QML elements in the file are drawn on
    the canvas. When you edit the element properties in \QMLD, the QML file and
    the image on the canvas might get out of sync. For example, when you change
    the position of an item within a column or a row, the new position might
    not be displayed correctly on the canvas.

    To refresh the image on the canvas, press \key R or select the \gui {Reset
    View} button on the canvas toolbar.

*/


/*!
    \contentspage index.html
    \previouspage creator-project-managing-sessions.html
    \page creator-coding.html
    \nextpage creator-editor-using.html

    \title Coding

    Writing, editing, and navigating in source code are core tasks in
    application development. Therefore, the code editor is one of the key
    components of Qt Creator. You can use the code editor in the \gui Edit
    mode.

    The following sections describe coding with Qt Creator:

    \list

        \o  \l{Using the Editor} describes how to work in the code editor, use
            the editor toolbar, split the view, add bookmarks, and move between
            symbol definitions and declarations.

        \o  \l{Semantic Highlighting} describes highlighting code elements and
            blocks, as well as using syntax highlighting also for other types
            of files than C++ or QML.

        \o  \l{Checking Code Syntax} describes how errors are visualized
            while you write code.

        \o  \l{Completing Code} describes how code and code snippets are
            completed for elements, properties, an IDs.

        \o  \l{Finding and Replacing} describes the incremental search that
            highlights the matching strings in the window while typing and the
            advanced search that allows you to search from currently open
            projects or files on the file system. In addition, you can search
            for symbols when you want to refactor code.

        \o  \l{Refactoring} describes the features that help you improve the
            internal quality or your application, its performance and
            extendibility, and code readability and maintainability, as well as
            to simplify code structure.

        \o  \l{Using Qt Quick Toolbars} describes how to use the Qt Quick
            Toolbars to edit the properties of QML elements in the code editor.

        \o  \l{Searching With the Locator} describes how to browse through
            projects, files, classes, methods, documentation and file systems.

        \o  \l{Pasting and Fetching Code Snippets} describes how to cooperate
            with other developers by pasting and fetching snippets of code from
            a server.

        \o  \l{Using Text Editing Macros} describes how to record and play
            text editing macros.

        \o  \l{Configuring the Editor} describes how to change the text editor
            options to suit your specific needs.

        \o  \l{Using FakeVim Mode} run the main editor in a manner similar to
            the Vim editor.

    \endlist

*/


/*!
    \contentspage index.html
    \previouspage creator-coding.html
    \page creator-editor-using.html
    \nextpage creator-highlighting.html

    \title Using the Editor

    Qt Creator's code editor is designed to aid you in creating, editing and
    navigating code.  Qt Creator's code editor is fully equipped with syntax
    checking, code completion, context sensitive help and in-line error
    indicators while you are typing.

    \image qtcreator-edit-mode.png "Edit mode"

    \section1 Using the Editor Toolbar

    The editor toolbar is located at the top of the editor view. The editor
    toolbar is context sensitive and shows items relevant to the file currently
    open in the editor.

    \image qtcreator-editortoolbar-symbols.png

    Use the toolbar to navigate between open files and symbols in use.
    To browse forward or backward through your location history, click
           \inlineimage qtcreator-back.png
           and \inlineimage qtcreator-forward.png
           .

    To go to any open file, select it from the \gui{Open files} drop-down menu.
    Right-click the menu title and select \gui {Copy Full Path to Clipboard} to
    copy the path and name of the current file to the clipboard.

    To jump to any symbol used in the current file, select it from the
    \gui Symbols drop-down menu. By default, the symbols are displayed in the
    order in which they appear in the file. Right-click the menu title and select
    \gui {Sort Alphabetically} to arrange the symbols in alphabetic order.

    \section1 Splitting the Editor View

    Split the editor view when you want to work on and view multiple files on
    the same screen.

    \image qtcreator-spliteditorview.png

    You can split the editor view in the following ways:
    \list
        \o To split the editor view into a top and bottom view, select
           \gui Window > \gui Split or press \key{Ctrl+E, 2}.

           Split command creates views below the currently active editor view.
        \o To split the editor view into adjacent views, select
           \gui Window > \gui{Split Side by Side} or press
           \key{Ctrl+E, 3}.

           Side by side split command creates views to the right of the
           currently active editor view.
    \endlist

    To move between split views, select \gui Window >
    \gui{Go to Next Split} or press \key{Ctrl+E, O}.

    To remove a split view, place the cursor within the view you want to
    remove and select \gui Window > \gui{Remove Current Split} or press
    \key{Ctrl+E, 0}. To remove all but the currently selected split view,
    select \gui Window > \gui{Remove All Splits} or press \key{Ctrl+E, 1}.

    \section1 Using Bookmarks

    To insert or delete a bookmark right-click the line number and select
    \gui{Toggle Bookmark} or press \key{Ctrl+M}.

    \image qtcreator-togglebookmark.png

    To go to previous bookmark in the current session, press \key{Ctrl+,}.

    To go to next bookmark in the current session, press \key{Ctrl+.}.

    \section1 Moving to Symbol Definition or Declaration

    You can move directly to the definition or the declaration of a symbol by
    holding the \key Ctrl and clicking the symbol.

    To enable this moving function, in \gui Tools > \gui{Options...} >
    \gui{Text Editor} > \gui Behavior, select \gui{Enable mouse navigation}.

    You can also select the symbol and press \key F2, or right-click the symbol
    and select \gui {Follow Symbol Under Cursor} to move to its definition or
    declaration. This feature is supported for namespaces, classes, methods,
    variables, include statements, and macros.

    To switch between the definition and declaration of a symbol, press
    \key {Shift+F2} or right-click the symbol and select \gui {Switch Between
    Method Declaration/Definition}.

    \section1 Using Update Code Model

    To refresh the internal information in Qt Creator pertaining to your code,
    select \gui{Tools} > \gui{C++} > \gui{Update Code Model}.

    \note In Qt Creator indexing updates the code automatically. Use
    \gui{Update Code Model} only as an emergency command.
*/


/*!
    \contentspage index.html
    \previouspage creator-editor-using.html
    \page creator-highlighting.html
    \nextpage creator-checking-code-syntax.html

    \title Semantic Highlighting

    Qt Creator understands the C++ and QML languages as code, not as plain text.
    It reads the source code, analyzes it, and highlights it based on the
    semantic checks that it does for the following code elements:

    \list

        \o Types (such as classes, structs, and type definitions)

        \o Local variables

        \o Class fields

        \o Virtual methods

    \endlist

    To specify the color scheme to use for semantic highlighting, select
    \gui {Tools > Options... > Text Editor > Fonts & Color}.

    Qt Creator supports syntax highlighting also for other types of files than
    C++ or QML.

    \section1 Generic Highlighting

    Generic highlighting is based on highlight definition files that are
    provided by the
    \l{http://kate-editor.org/2005/03/24/writing-a-syntax-highlighting-file/}{Kate Editor}.
    You can download highlight definition files for use with Qt Creator.

    If you have a Unix installation that comes with the Kate Editor, you might
    already have the definition files installed. Typically, the files are
    located in a read-only directory, and therefore, you cannot manage them. Qt
    Creator can try to locate them and use them as fallback files, when the
    primary location does not contain the definition for the current file type.
    You can also specify the directory that contains preinstalled highlight
    definition files as the primary location.

    When you open a file for editing and the editor cannot find the highlight
    definition for it, an alert appears. You can turn off the alerts. You can
    also specify patterns for ignoring files. The editor will not alert you if
    highlight definitions for the ignored files are not found.

    To download highlight definition files:

    \list 1

        \o  Select \gui {Tools > Options... > Text Editor > Generic
            Highlighter}.

            \image qtcreator-generic-highlighter.png "Generic Highlighter options"

        \o  In the \gui Location field, specify the path to the primary
            location for highlight definition files.

        \o  Click \gui {Download Definitions} to open a list of highlight
            definition files available for download.

            \image qtcreator-manage-definitions.png "Download Definitions dialog"

        \o  Select highlight definition files in the list and click
            \gui {Download Selected Definitions}.

        \o  Select the \gui {Use fallback location} check box to specify the
            secondary location where the editor will look for highlight
            definition files.

        \o  Click \gui Autodetect to allow Qt Creator to look for highlight
            definition files on your system, or click \gui Browse to locate
            them in the file system yourself.

        \o  In the \gui {Ignored file patterns} field, specify file patterns.
            You will not receive alerts if the highlight definitions for the
            specified files are not found.

        \o  Click \gui OK to save your changes.

    \endlist

    \section1 Highlighting and Folding Blocks

    Use block highlighting to visually separate parts of the code that belong
    together. For example, when you place the cursor within the braces,
    the code enclosed in braces is highlighted.

    \image qtcreator-blockhighlighting.png

    To enable block highlighting, select \gui Tools > \gui{Options...} >
    \gui{Text Editor} > \gui Display > \gui{Highlight blocks}.

    Use the folding markers to collapse and expand blocks of code within
    braces. Click the folding marker to collapse or expand a block. In the
    figure above, the folding markers are located between the line number and
    the text pane.

    To show the folding markers, select \gui Tools > \gui{Options...} >
    \gui{Text Editor} > \gui Display > \gui{Display folding markers}. This
    option is enabled by default.

    When the cursor is on a brace, the matching brace is animated
    by default. To turn off the animation and just highlight the block and
    the braces, select \gui {Tools > Options... > Text Editor > Display} and
    deselect \gui {Animate matching parentheses}.

*/


/*!
    \contentspage index.html
    \previouspage creator-highlighting.html
    \page creator-checking-code-syntax.html
    \nextpage creator-completing-code.html

    \title Checking Code Syntax

    As you write code Qt Creator checks code syntax. When Qt Creator spots a
    syntax error in your code it underlines it and shows error details when you
    move the mouse pointer over the error.
    \list
        \o Syntax errors are underlined in red.

           In the following figure, a semicolon is missing at the end of the
           line.

           \image qtcreator-syntaxerror.png
        \o Semantic errors and warnings are underlined in olive.

           In the following figure, the type is unknown.

           \image qtcreator-semanticerror.png
    \endlist

*/


/*!
    \contentspage index.html
    \previouspage creator-checking-code-syntax.html
    \page creator-completing-code.html
    \nextpage creator-editor-finding.html

    \title Completing Code

    As you write code, Qt Creator suggests properties, IDs, and code
    snippets to complete the code. It provides a list of context-sensitive
    suggestions to the statement currently under your cursor. Press \key Tab
    or \key Enter to accept the selected suggestion and complete the code.

    \image qtcreator-codecompletion.png

    To open the list of suggestions at any time, press \key{Ctrl+Space}.
    If only one option is available, Qt Creator inserts it automatically.

    When completion is invoked manually, Qt Creator completes the common prefix
    of the list of suggestions. This is especially useful for classes with
    several similarly named members. To disable this functionality, uncheck
    \gui{Autocomplete common prefix} in the code completion preferences.
    Select \gui Tools > \gui{Options...} > \gui{Text Editor} > \gui Completion.

    By default, code completion considers only the first letter case-sensitive.
    To apply full or no case-sensitivity, select the option in the
    \gui {Case-sensitivity} field.

    \section2 Summary of Available Types

    The following table lists available types for code completion and icon
    used for each.

    \table
        \header
            \o Icon
            \o Description
        \row
            \i  \inlineimage completion/class.png
            \i  A class
        \row
            \i  \inlineimage completion/enum.png
            \i  An enum
        \row
            \i  \inlineimage completion/enumerator.png
            \i  An enumerator (value of an enum)
        \row
            \i  \inlineimage completion/func.png
            \i  A function
        \row
            \i  \inlineimage completion/func_priv.png
            \i  A private function
        \row
            \i  \inlineimage completion/func_prot.png
            \i  A protected function
        \row
            \i  \inlineimage completion/var.png
            \i  A variable
        \row
            \i  \inlineimage completion/var_priv.png
            \i  A private variable
        \row
            \i  \inlineimage completion/var_prot.png
            \i  A protected variable
        \row
            \i  \inlineimage completion/signal.png
            \i  A signal
        \row
            \i  \inlineimage completion/slot.png
            \i  A slot
        \row
            \i  \inlineimage completion/slot_priv.png
            \i  A private slot
        \row
            \i  \inlineimage completion/slot_prot.png
            \i  A protected slot
        \row
            \i  \inlineimage completion/keyword.png
            \i  A C++ keyword
        \row
            \i  \inlineimage completion/snippet.png
            \i  A C++ code snippet
        \row
            \i  \inlineimage completion/element.png
            \i  A QML element
        \row
            \i  \inlineimage completion/qmlsnippet.png
            \i  A QML code snippet
        \row
            \i  \inlineimage completion/macro.png
            \i  A macro
        \row
            \i  \inlineimage completion/namespace.png
            \i  A namespace
    \endtable

    \section2 Completing Code Snippets

    Code snippets can consist of multiple
    variables that you specify values for. Select an item in the list and press
    \key Tab or \key Enter to complete the code. Press \key Tab to
    move between the variables and specify values for them. When you specify a
    value for a variable, all instances of the variable within the snippet
    are renamed.

    \image qmldesigner-code-completion.png "Completing QML code"

    \section2 Editing Code Snippets

    Code snippets specify C++ or QML code constructs. You can add, modify,
    and remove snippets in the snippet editor. To open the editor, select
    \gui {Tools > Options... > Text Editor > Snippets}.

    \image qtcreator-edit-code-snippets.png "Snippet options"

    Qt Creator provides you with built-in snippets in the following categories:

    \list

        \o Text snippets, which can contain any text string. For example, code
        comments

        \o C++ code snippets, which specify C++ code constructs

        \o QML code snippets, which specify QML code constructs

    \endlist

    \section3 Adding and Editing Snippets

    Select a snippet in the list to edit it in the snippet editor. To add a new
    snippet, select \gui Add. Specify a trigger and, if the trigger is already
    in use, an optional variant, which appear in the list of suggestions when
    you write code. Also specify a text string or C++ or QML code construct in
    the snippet editor, depending on the snippet category.

    The snippet editor provides you with:

    \list

        \o Highlighting

        \o Indentation

        \o Parentheses matching

        \o Basic code completion

    \endlist

    Specify the variables for the snippets in the following format:

    \c $variable$

    Use unique variable names within a snippet, because all instances of a
    variable are renamed when you specify a value for it.

    The snippet editor does not check the syntax of the snippets that you edit
    or add. However, when you use the snippets, the code editor marks any
    errors by underlining them in red.

    To discard the changes you made to a built-in snippet, select \gui {Revert
    Built-in}.

    \section3 Removing Snippets

    Several similar built-in snippets might be provided for different use
    cases. To make the list of suggestions shorter when you write code, remove
    the built-in snippets that you do not need. If you need them later, you
    can restore them.

    To remove snippets, select a snippet in the list, and then select
    \gui Remove. To restore the removed snippets, select \gui {Restore Removed
    Built-ins}.

    \section3 Resetting Snippets

    To remove all added snippets and to restore all removed snippets, select
    \gui {Reset All}.

    \note If you now select \gui OK or \gui Apply, you permanently lose all
    your own snippets.

*/


/*!
    \contentspage index.html
    \previouspage creator-editor-locator.html
    \page creator-editor-codepasting.html
    \nextpage creator-macros.html

    \title Pasting and Fetching Code Snippets

    In Qt Creator, you can paste snippets of code to a server or fetch
    snippets of code from the server. To paste and fetch snippets of code,
    Qt Creator uses the following:
    \list
        \o \gui{CodePaster}
        \o \gui{Pastebin.Com}
        \o \gui{Pastebin.Ca}
    \endlist

    To configure the server, select \gui{Tools} > \gui{Options...} >
    \gui{Code Pasting}.

    To paste a snippet of code onto the server, select \gui{Tools} >
    \gui{Code Pasting} > \gui{Paste Snippet...} or press \key{Alt+C,Alt+P}.



    To fetch a snippet of code from the server, select \gui{Tools} >
    \gui{Code Pasting} > \gui{Fetch Snippet...} or press \key{Alt+C,Alt+F}.

    \note To use \gui{Pastebin.Com}, configure the domain
    prefix in \gui{Tools} > \gui{Options...} > \gui{Code Pasting} >
    \gui{Pastebin.com}.

    For example, you might ask colleagues to review a change that you plan to
    submit to a version control system. If you use the Git version control system,
    you can create a \e{diff} view by selecting \gui{Tools} > \gui{Git} >
    \gui{Diff Repository}. You can then upload its contents to the server by choosing
    \gui{Tools} > \gui{Code Pasting} > \gui{Paste Snippet...}. The reviewers can retrieve
    the code snippet by selecting \gui{Tools} > \gui{Code Pasting} > \gui{Fetch Snippet...}.
    If they have the project currently opened in Qt Creator, they can apply and test
    the change by choosing \gui{Tools} > \gui{Git} > \gui{Apply Patch}.

*/

/*!
    \contentspage index.html
    \previouspage creator-editor-codepasting.html
    \page creator-macros.html
    \nextpage creator-editor-options.html

    \title Using Text Editing Macros

    When you have a file open in the code editor, you can record a keyboard
    sequence as a macro. You can then play the macro to repeat the sequence.
    You can save the latest macro and assign a keyboard shortcut for running
    it or run it from the locator.

    To record a text editing macro, select \gui {Tools > Macros > Record Macro}
    or press \key {Alt+(}. To stop recording, select \gui {Tools > Macros >
    Stop Recording Macro} or press \key {Alt+)}.

    To play the last macro, select \gui {Tools > Macros > Play Last Macro} or
    press \key {Alt+R}.

    To save the last macro, select \gui {Tools > Macros > Save Last Macro}.

    To assign a keyboard shortcut to a text editing macro, select \gui {Tools >
    Options... > Environment > Keyboard}. For more information, see
    \l{Configuring Keyboard Shortcuts}.

    You can also use the \c rm locator filter to run a macro. For more
    information, see \l{Searching With the Locator}.

    To view and remove saved macros, select \gui {Tools > Options... > Text
    Editor > Macros}.

*/

/*!
    \contentspage index.html
    \previouspage creator-editor-options.html
    \page creator-editor-fakevim.html
    \nextpage creator-design-mode.html

    \title Using FakeVim Mode

    In the \gui{FakeVim} mode, you can run the main editor in a manner similar
    to the Vim editor. To run the editor in the \gui{FakeVim} mode, select
    \gui{Edit} > \gui{Advanced} > \gui{Use Vim-style Editing} or press
    \key{Alt+V,Alt+V}.

    In the \gui{FakeVim} mode, most keystrokes in the main editor will be
    intercepted and interpreted in a way that resembles Vim. Documentation for
    Vim is not included in Qt Creator. For more information on using Vim,
    see \l{http://www.vim.org/docs.php}{Documentation} on the Vim web site.

    To map commands entered on the \gui{FakeVim} command line to actions of the
    Qt Creator core, select \gui{Tools} > \gui{Options...} > \gui{FakeVim} >
    \gui{Ex Command Mapping}.

    To make changes to the Vim-style settings, select \gui{Tools} >
    \gui{Options...} > \gui FakeVim > \gui{General}.

    To use a Vim-style color scheme, select \gui {Tools > Options... >
    Text Editor > Fonts & Color}. In the \gui {Color Scheme} list, select
    \gui {Vim (dark)}.

    To quit the FakeVim mode, click \gui {Quit FakeVim} or press
    \key{Alt+V,Alt+V}.

    */


/*!
    \contentspage index.html
    \previouspage adding-plugins.html
    \page creator-editor-external.html
    \nextpage creator-maemo-emulator.html

    \title Using External Tools

    You can use external tools directly from Qt Creator. Qt Linguist, the
    default text editor for your system, and the \c sort tool are preconfigured
    for use. You can change their default configurations and configure new
    tools.

    \section1 Using Qt Linguist

    You can use the Qt Linguist release manager tools, lupdate and lrelease,
    directly from Qt Creator. The lupdate tool is used to synchronize source
    code and translations. The lrelease tool is used to create run-time
    translation files for use by the released application.

    To synchronize ts files from a translator with the application code,
    select \gui {Tools > External > Text > Linguist > Update Translations
    (lupdate)}.

    To generate from the ts files qm translation files that can be used by an
    application, select \gui {Tools > External > Text > Linguist > Release
    Translations (lrelease)}.

    By default, the project .pro file is passed to the tools as an argument. To
    specify other command line arguments for the tools, select \gui {Tools >
    External > Configure}.

    For more information about Qt Linguist, see
    \l{http://doc.qt.nokia.com/4.7/linguist-manual.html}{Qt Linguist Manual}.

    \section1 Using External Text Editors

    You can open files for editing in the default text editor for your system:
    Notepad on Windows and vi on Linux and Mac OS.
    To open the file you are currently viewing in an external editor, select
    \gui {Tools > External > Text > Notepad} or \gui vi, depending on your
    system.

    Qt Creator looks for the editor path in the PATH environment variable
    of your operating system.

    \section1 Sorting Text Alphabetically

    To sort selected text alphabetically, select \gui {Tools > External > Text
    > Sort Selection}. The \c sort tool takes the selected text as input and
    returns it in alphabetic order. By default, the output replaces the
    original selection in the code editor.

    To change the default configuration, select \gui {Tools > External >
    Configure}.

    \section1 Configuring External Tools

    You can change the configuration of preconfigured tools and configure
    additional tools in Qt Creator \gui Options.

    You can use Qt Creator variables in the fields that you can select from
    lists of available Qt Creator variables.

    \image qtcreator-external-tools.png "External Tools options"

    To configure external tools:

    \list 1

        \o  Select \gui {Tools > External > Configure}.

        \o  Select \gui {Add > Add Tool}
            to add a new tool. You can also select \gui {Add Category} to add a
            new category.

        \o  In the \gui Executable field, specify the executable to run. If the
            executable is found in your system PATH variable, do not specify
            the path to it.

        \o  In the \gui Arguments field, specify optional arguments for running
            the executable.

        \o  In the \gui {Working directory} field, specify the path to the
            working directory.

        \o  In the \gui {Output pane}, select how to handle output from the
            tool. You can ignore the output, view it in the \gui {General
            Messages} output pane, or replace the selected text with the
            output in the code editor.

        \o  In the \gui {Error output pane}, select how to handle error messages
            from the tool.

        \o In the \gui Input field, specify text that is passed as standard
        input to the tool.

    \endlist

    The category and tool are added to the \gui {Tools > External} menu.

    If you change the configuration of preconfigured tools, you can later
    revert the changes by selecting the \gui Revert button.

    The tool configurations that you add and modify are stored in XML format in
    the user configuration folder. For example,
    \c {~/config/Nokia/qtcreator/externaltools}
    on Linux and Mac OS and
    \c {C:\Users\username\AppData\Roaming\Nokia\qtcreator\externaltools}
    in Windows. To share a configuration with other users, copy an XML
    configuration file to the folder.

*/


/*!
    \contentspage index.html
    \previouspage creator-macros.html
    \page creator-editor-options.html
    \nextpage creator-editor-fakevim.html

    \title Configuring the Editor

    Qt Creator allows you to configure the text editor to suit your specific
    needs. To configure the editor, select  \gui Tools > \gui{Options...} >
    \gui{Text Editor}.

    These settings apply to all projects. To specify editor behavior for an
    open project, select \gui {Projects > Editor Settings}. For more
    information, see \l{Specifying Editor Settings}.

    \image qtcreator-font-colors.png "Text editor options"

    You can perform the following configuration actions:
    \list
        \o Set the font preferences and apply color schemes for syntax highlighting in
           \gui{Font & Colors}.
        \o Specify
           \l{Generic Highlighting}{definition files for syntax highlighting}
           for other types of files than
             C++ or QML in \gui{Generic Highlighter}.
        \o Set tabs, indentation, the handling of whitespace, and mouse operations in
           \gui Behavior.
        \o Set various display properties, for example,
           \l{Highlighting and folding blocks}{highlighting and folding blocks},
           text wrapping or \l{Moving to symbol definition or declaration}
           {moving to symbol definition or declaration}
           in \gui Display.
        \o Add, modify, and remove \l{Editing Code Snippets}{code snippets} in
           \gui Snippets.
        \o View and remove \l{Using Text Editing Macros}{text editing macros}
           in \gui Macros.
        \o Configure \l{Completing Code}{code completion} in \gui Completion.
    \endlist

    \section2 Configuring Fonts

    You can select the font family and size. You can specify a zoom setting in
    percentage for viewing the text. You can also zoom in or out by pressing
    \key {Ctrl++} or \key {Ctrl +-}, or by pressing \key Ctrl and rolling
    the mouse button up or down. To disable the mouse wheel function, select
    \gui {Tools > Options... > Text Editor > Behavior} and deselect the
    \gui {Enable scroll wheel zooming} check box.

    Antialiasing is used by default to make text look smoother and more
    readable on the screen. Deselect the \gui Antialias check box to
    turn off antialiasing.

    \section2 Defining Color Schemes

    You can select one of the predefined color schemes for syntax highlighting
    or create customized color schemes. The color schemes apply to highlighting
    both C++ and QML files and generic files.

    To create a color scheme:

    \list 1

        \o Select \gui {Tools > Options... > Text Editor > Fonts & Color > Copy}.

        \o Enter a name for the color scheme and click \gui OK.

        \o In the \gui Foreground field, specify the color of the selected
        code element.

        \o In the \gui Background field, select the background
        color for the code element.

        The backgound of the \gui Text element determines the background of the
        code editor.

    \endlist

    When you copy code from Qt Creator, it is copied in both plain text and HTML
    format. The latter makes sure that syntax highlighting is preserved when
    pasting to a rich-text editor.

    \section2 Indenting Code

    \image qtcreator-indentation.png "Text Editor Behavior options"

    When you type code, it is indented automatically according to the selected
    options. Select a block to indent it when you press \key Tab.
    Press \key {Shift+Tab} to decrease the indentation.

    When you press \gui Backspace the indentation is decreased by one level,
    instead of one space, by default.

    By default, the tab-length in code editor is 8 spaces, but you can change
    it. The code editor can also determine whether tabs or spaces are used
    on the previous or next line and copy the style.

    You can determine whether the block indent style includes braces,
    or you can use the GNU indent style. The GNU style places braces on a separate
    line, indented by 2 spaces, except when they open a function definition, where
    they are not indented.

    You can also specify whether continuation lines are aligned with the previous
    code or just indented to the logical depth. You can always use spaces for
    alignment or use spaces or tabs depending on the other options you selected.

    The following code snippet illustrates excluding braces from the indented block:

    \code

    void foobar(bool zoo)
    {
        if (zoo)
        {
            foo();
        }
    }

    \endcode

    The following code snippet illustrates including braces in the indented block:

    \code

    void foobar(bool zoo)
    {
        if (zoo)
            {
            foo();
            }
    }

    \endcode

    The following code snippet illustrates the GNU style:

    \code

    void foobar(bool zoo)
    {
      if (zoo)
        {
          foo();
        }
    }

    \endcode

\section2 File Encoding

    To define the default file encoding, select the desired encoding in
    \gui {Default encoding}. By default, Qt Creator uses the file encoding
    used by your system.

*/


/*!
    \contentspage index.html
    \previouspage creator-completing-code.html
    \page creator-editor-finding.html
    \nextpage creator-editor-refactoring.html

    \title Finding and Replacing

    To search through the currently open file:
    \list 1
        \o Press \key Ctrl+F or select \gui Edit > \gui Find/Replace >
           \gui{Find/Replace}.
        \o Enter the text you are looking for.

           If the text is found, all occurrences are highlighted as you type.
        \o To go to the next occurrence, click \inlineimage qtcreator-next.png
           , or press \key F3. To go to the previous occurrence click
           \inlineimage qtcreator-previous.png
           , or press \key Shift+F3.
    \endlist

    You can restrict the search in the \gui Find field by selecting one
    or several search criteria:
    \list
        \o To make your search case sensitive, select
           \inlineimage qtcreator-editor-casesensitive.png
           .
        \o To search only whole words, select
           \inlineimage qtcreator-editor-wholewords.png
           .
        \o To search using regular expressions, select
           \inlineimage qtcreator-editor-regularexpressions.png
           .
           Regular expressions used in Qt Creator are modeled on Perl regular
           expressions. For more information on using regular expressions, see
           \l {http://doc.qt.nokia.com/4.7/qregexp.html#details}
           {Detailed Description} in the QRegExp Class Reference.
    \endlist

    \note If you have selected text before selecting \gui Find/Replace, the
    search is conducted within the selection.

    To replace occurrences of the existing text, enter the new text in the
    \gui{Replace with} field.
    \list
        \o To replace the selected occurrence and move to the next one,
           click \inlineimage qtcreator-next.png
           or press \key Ctrl+=.
        \o To replace the selected occurrence and move to the previous one,
           click \inlineimage qtcreator-previous.png
           .
        \o To replace all occurrences in the file, click \gui{Replace All}.
    \endlist

    \section1 Advanced Search

    To search through projects, files on a file system or the currently open
    file:
    \list 1
        \o Press \key Ctrl+Shift+F or select \gui Edit >
           \gui Find/Replace > \gui{Advanced Find} >
           \gui{Open Advanced Find...}.
        \o Select the scope of your search:
           \list
            \o \gui{All Projects} searches files matching the defined file
               pattern in all currently open projects.

               For example, to search for \tt previewer only in \tt .cpp
               and \tt .h files, enter in \gui{File pattern}
               \tt *.cpp,*.h.

               \image qtcreator-search-allprojects.png

            \o \gui{Current Project} searches files matching the defined file
               pattern only in the project you are currently editing.
            \o \gui{Files on File System} recursively searches files matching
               the defined file pattern in the selected directory.
            \o \gui{Current File} searches only the current file.
           \endlist
        \o Enter the text you are looking for and click \gui Search.

           \image qtcreator-searchresults.png

           A list of files containing the searched text is displayed in the
           \gui{Search Results} pane.
           \list
            \o To see all occurrences in a file, double-click the file name in
               the list.
            \o To go to an occurrence, double-click it.
           \endlist
    \endlist

    \note You can use \gui{Advanced Find} also to search for symbols. For more
    information, see \l{Finding Symbols}.

*/


/*!
    \contentspage index.html
    \previouspage creator-editor-finding.html
    \page creator-editor-refactoring.html
    \nextpage qt-quick-toolbars.html

    \title Refactoring

    Code refactoring is the process of changing the code without modifying the
    existing functionality of your application. By refactoring your code you
    can:
    \list
        \o Improve internal quality of your application
        \o Improve performance and extensibility
        \o Improve code readability and maintainability
        \o Simplify code structure
    \endlist

    \section1 Finding Symbols

    To find the use of a specific symbol in your Qt C++ or Qt Quick project:
    \list 1
        \o In the editor, place the cursor on the symbol, and select:
        \list
            \o \gui {Tools > C++ > Find Usages}
            \o \gui {Tools > QML > Find Usages}
            \o \key Ctrl+Shift+U
        \endlist

           Qt Creator looks for the symbol in the following locations:
           \list
            \o Files listed as a part of the project
            \o Files directly used by the project files (for example, generated
               files)
            \o Header files of used frameworks and libraries
           \endlist

        \note You can also select \gui{Edit > Find/Replace > Advanced Find >
        C++ Symbols} to search for classes, methods, enums, and declarations
        either from files listed as part of the project or from all files that
        are used by the code, such as include files.

        \image qtcreator-search-cpp-symbols.png

        \o The \gui{Search Results} pane opens and shows the location and
           number of instances of the symbol in the current project.

           \image qtcreator-refactoring-find.png
    \endlist

    You can browse the search results in the following ways:
    \list
        \o To go directly to an instance, double-click the instance in the
           \gui{Search Results} pane.
        \o To move between instances, click
           \inlineimage qtcreator-forward.png
           and
           \inlineimage qtcreator-back.png
           in the \gui{Search Results} pane.
        \o To expand and collapse the list of all instances, click
           \inlineimage qtcreator-expand.png
           .
        \o To clear the search results, click \inlineimage qtcreator-clear.png
           .
    \endlist

    \section1 Renaming Symbols

    The functions available for renaming symbols depend on whether you are
    writing C++ or QML code. For QML, you can only rename IDs.

    To rename a specific symbol in a Qt project:
    \list 1
        \o In the editor, place the cursor on the symbol you would like to
           change and select \gui Tools > \gui C++ >
           \gui{Rename Symbol Under Cursor} or press \key Ctrl+Shift+R.

           The \gui{Search Results} pane opens and shows the location and
           number of instances of the symbol in the current project.

           \image qtcreator-refactoring-replace.png
        \o To replace all selected instances, enter the name of the new symbol
           in the \gui{Replace with} text box and click \gui Replace.

           To omit an instance, uncheck the check-box next to the instance.

           \note This action replaces all selected instances of the symbol in
           all files listed in the \gui{Search Results} pane. You cannot
           undo this action.
    \endlist

    \note Renaming local symbols does not open the \gui{Search Results} pane.
    The instances of the symbol are highlighted in code and you can edit the
    symbol. All instances of the local symbol are changed as you type.

    To rename an ID in a Qt Quick project:

    \list 1

        \o Right-click an ID in the QML code and select
        \gui {Rename id}.

        \o In the \gui {Rename id} field, enter the new ID.

    \endlist

    \section1 Applying Refactoring Actions

    Qt Creator allows you to quickly and conveniently apply actions to refactor
    your code by selecting them in a context menu. The actions available depend on
    the position of the cursor in the code editor and on whether you are writing
    C++ or QML code.

    To apply refactoring actions to C++ code, right-click an operand, conditional
    statement, string, or name to open a context menu. In QML code, click an element
    ID or name.

    In the context menu, select \gui {Refactoring} and then select a refactoring action.

    You can also press \gui {Alt+Enter} to open a context menu that contains refactoring
    actions available in the current cursor position.

   \section2 Refactoring C++ Code

   You can apply the following types of refactoring actions to C++ code:

   \list

        \o Change binary operands

        \o Simplify if and while conditions (for example, move declarations out of
        if conditions)

        \o Modify strings (for example, set the encoding for a string to Latin-1, mark
         strings translatable, and convert symbol names to camel case)

        \o Create variable declarations

        \o Create method declarations and definitions

   \endlist

    The following table summarizes the refactoring actions for C++ code. The
    action is available when the cursor is in the position described in the
    Activation column.

    \table
        \header
            \i Refactoring Action
            \i Description
            \i Activation
        \row
            \i Add Curly Braces
            \i Adds curly braces to an if statement that does not contain a
            compound statement. For example, rewrites

    \code
    if (a)
        b;
    \endcode

            as

    \code
    if (a) {
        b;
    }
    \endcode
            \i if
        \row
            \i Move Declaration out of Condition
            \i Moves a declaration out of an if or while condition to simplify the
            condition. For example, rewrites

    \code
    if (Type name = foo()) {...}
    \endcode

            as

    \code
    Type name = foo;
    if (name) {...}
    \endcode
            \i Name of the introduced variable
        \row
            \i Rewrite Condition Using ||
            \i Rewrites the expression according to De Morgan's laws. For example,
             rewrites:
    \code
    !a && !b
    \endcode

            as

    \code
    !(a || b)
    \endcode
            \i &&
        \row
            \i Rewrite Using \e operator
            \i Rewrites an expression negating it and using the inverse operator. For
            example, rewrites:

            \list

    \o     \code
    a op b
    \endcode

    as

    \code
    !(a invop b)
    \endcode

    \o     \code
    (a op b)
    \endcode

    as

    \code
    !(a invop b)
    \endcode

    \o    \code
    !(a op b)
    \endcode

    as

    \code
    (a invob b)
    \endcode

    \endlist

            \i <= < > >= == !=
        \row
            \i Split Declaration
            \i Splits a simple declaration into several declarations. For example,
            rewrites:
    \code
    int *a, b;
    \endcode

    as

    \code
    int *a;
    int b;
    \endcode
            \i Type name or variable name
        \row
            \i Split if Statement
            \i Splits an if statement into several statements. For example, rewrites:
    \code
    if (something && something_else) {
    }
    \endcode

    as

    \code
    if (something) {
       if (something_else) {
       }
    }
    \endcode

    and

    \code
    if (something || something_else)
        x;
    \endcode

    with

    \code
    if (something)
        x;
    else if (something_else)
        x;
    \endcode

            \i && ||
        \row
            \i Swap Operands
            \i Rewrites an expression in the inverse order using the inverse operator.
            For example, rewrites:
    \code
    a op b
    \endcode

    as
    \code
    b flipop a
    \endcode
            \i <= < > >= == != && ||
        \row
            \i Convert to Decimal
            \i Converts an integer literal to decimal representation
            \i Numeric literal
        \row
            \i Convert to Hexadecimal
            \i Converts an integer literal to hexadecimal representation
            \i Numeric literal
        \row
            \i Convert to Octal
            \i Converts an integer literal to octal representation
            \i Numeric literal
        \row
            \i Convert to Objective-C String Literal
            \i Converts a string literal to an Objective-C string literal
            if the file type is Objective-C(++). For example, rewrites the following strings

    \code
    "abcd"
    QLatin1String("abcd")
    QLatin1Literal("abcd")
    \endcode

    as

    \code
    @"abcd"
    \endcode
            \i String literal
        \row
            \i Enclose in QLatin1Char(...)
            \i Sets the encoding for a character to Latin-1, unless the character is
            already enclosed in QLatin1Char, QT_TRANSLATE_NOOP, tr, trUtf8,
            QLatin1Literal, or QLatin1String. For example, rewrites

    \code
    'a'
    \endcode

    as

    \code
    QLatin1Char('a')
    \endcode
            \i String literal
        \row
            \i Enclose in QLatin1String(...)
            \i Sets the encoding for a string to Latin-1, unless the string is
            already enclosed in QLatin1Char, QT_TRANSLATE_NOOP, tr, trUtf8,
            QLatin1Literal, or QLatin1String. For example, rewrites
    \code
    "abcd"
    \endcode

    as

    \code
    QLatin1String("abcd")
    \endcode

            \i String literal

        \row
            \i Mark as Translatable
            \i Marks a string translatable. For example, rewrites \c "abcd" with
            one of the following options, depending on which of them is available:

    \code
    tr("abcd")
    QCoreApplication::translate("CONTEXT", "abcd")
    QT_TRANSLATE_NOOP("GLOBAL", "abcd")
    \endcode

            \i String literal

        \row
            \i #include Header File
            \i Adds the matching #include statement for a forward-declared class or struct
            \i Forward-declared class or struct
        \row
            \i Add Definition in 'filename'
            \i Inserts a definition stub for a member function declaration in the
            implementation file
            \i Method name
        \row
            \i Add 'Function' Declaration
            \i Inserts the member function declaration that matches the member function
            definition into the class declaration. The function can be public,
            protected, private, public slot, protected slot, or private slot.
            \i Method name
        \row
            \i Add Local Declaration
            \i
            Adds the type of an assignee, if the type of the right-hand side of the assignment
            is known. For example, rewrites

    \code
    a = foo();
    \endcode

    as

    \code
    Type a = foo();
    \endcode

    where Type is the return type of \c {foo()}

            \i Assignee

        \row
            \i Convert to Camel Case...
            \i Converts a symbol name to camel case, where elements of the name are joined
            without delimiter characters and the initial character of each element is
            capitalized. For example, rewrites \c an_example_symbol
            as \c anExampleSymbol and \c AN_EXAMPLE_SYMBOL as \c AnExampleSymbol
            \i Indentifier
        \row
            \i Complete Switch Statement
            \i Adds all possible cases to a switch statement of the type \c enum
            \i Switch
        \row
            \i Generate Missing Q_PROPERTY Members...
            \i Adds missing members to a Q_PROPERTY:
            \list
                \o \c read method
                \o \c write method, if there is a WRITE
                \o \c {on...Changed} signal, if there is a NOTIFY
                \o data member with the name \c {m_<propertyName>}
            \endlist
            \i Q_PROPERTY
    \endtable

   \section2 Refactoring QML Code

   You can apply the following types of refactoring actions to QML code:

   \list

        \o Rename IDs

        \o Split initializers

        \o Move a QML element into a separate file to reuse it in other
        .qml files

   \endlist

    The following table summarizes the refactoring actions for QML code. The
    action is available when the cursor is in the position described in the
    Activation column.

    \table
        \header
            \i Refactoring Action
            \i Description
            \i Activation

        \row
            \i Move Component into 'filename.qml'
            \i Moves a QML element into a separate file
            \i Element name
        \row
            \i Rename id
            \i Renames all instances of an element ID in the currently open file
            \i Element ID
        \row
            \i Split Initializer
            \i Reformats a one-line element into a multi-line element. For example,
            rewrites

    \code
    Item { x: 10; y: 20; width: 10 }
    \endcode

    as

    \code
    Item {
        x: 10;
        y: 20;
        width: 10
    }
    \endcode
            \i Element property

    \endtable
   */

/*!
    \contentspage index.html
    \previouspage creator-qml-application.html
    \page creator-project-managing.html
    \nextpage creator-project-creating.html

    \title Managing Projects

    To set up a project, you first have to decide what kind of an
    application you want to develop: whether you want a user interface
    based on Qt Quick, Qt widgets, or HTML5. For a Qt Quick or HTML5 project,
    you must also
    choose the language to implement the application logic: C++ or JavaScript.
    You can also create other kinds of projects, such as Qt console
    applications, shared or static C++ libraries, or subprojects.

    You can use wizards to create and import projects. The wizards prompt you
    to enter the settings needed for that particular type of project and create
    the necessary files for you. You can add your own custom wizards to
    standardize the way subprojects and classes are added to a project.

    The wizards set up projects to use the Qt build tool, qmake. It is a
    cross-platform system for build automation that helps simplify the build
    process for development projects across different platforms. qmake
    automates the generation of build configurations so that only a few lines
    of information are needed to create each configuration. For more
    information about qmake, see the
    \l{http://qt.nokia.com/doc/4.7/qmake-manual.html}{qmake Manual}.

    You can modify the build and run settings for qmake projects in the
    \gui Projects mode.

    Alternatively, you can use the CMake build automation system and set up the
    projects manually. In addition, you can import generic projects that do not
    use qmake or CMake. This allows you to use Qt Creator as a code editor. For
    generic projects, Qt Creator ignores your build system.

    To develop applications for Symbian devices, you use
    qmake and the local Symbian compiler (on Windows) or qmake and a compilation
    service at Forum Nokia (on Linux and Mac OS) to build the applications for
    the Symbian devices target. The interface to the compilation service, Remote
    Compiler, is installed as a part of the \QSDK. For more information, see
    \l{Building with Remote Compiler}.

    When you install the \QSDK, the build and run settings for the Maemo, MeeGo
    Harmattan, and
    Symbian targets are set up automatically. However, you need to install and
    configure some additional software on the devices to be able to connect to
    them from the development PC.

    You can use sessions to store personal data, such as bookmarks and
    breakpoints that are usually not of interest to other developers working on
    the same projects. Sessions allow you to quickly switch between projects
    when you work on several projects.

    The following sections describe how to manage projects:

    \list
        \o \l{Creating a Project}
        \o \l{Opening a Project}
        \o \l{Adding Libraries to Projects}
        \o \l{Connecting Maemo and MeeGo Harmattan Devices}
        \o \l{Connecting Symbian Devices}
        \o \l{Managing Sessions}
    \endlist

    For advanced options, see the following topics:

    \list
        \o \l{Adding New Custom Wizards}
        \o \l{Setting Up a CMake Project}
        \o \l{Setting Up a Generic Project}
    \endlist

*/


/*!
    \contentspage index.html
    \previouspage creator-project-managing.html
    \page creator-project-creating.html
    \nextpage creator-project-opening.html

    \title Creating a Project

    \image qtcreator-new-project.png

    You can use wizards to create following types of projects:

    \list

        \o Qt Quick Project

        Use QML to define the user interface and,
        optionally, C++ or JavaScript to define the application logic

        \o Qt Widget Project

        Use \QD forms to define a Qt widget based
        user interface and C++ to define the application logic

        \o Other Project

        \list

            \o HTML5 based applications

            \o Qt console applications

            \o Shared or static C++ libraries

            \o Qt unit tests

            \o Qt Custom Designer Widgets

            \o Subprojects

        \endlist

        \o Project from Version Control

        Import a project from a supported version control system. For more
        information on how version control systems are integrated in
        Qt Creator, see \l{Using Version Control Systems}.

    \endlist

    To create a new project, select \gui File > \gui{New File or Project} and
    select the type of your
           project.
           The contents of the wizard dialogs depend on the project type and
           the build targets that you select in the \gui {Target Setup} dialog.
           Follow the instructions of the wizard.

    For examples of creating different types of projects, see
    \l{Getting Started}.

    For more information about creating Qt Quick projects, see
    \l {Creating Qt Quick Projects}.

    To change the location of the project directory, and to specify settings
    for building and running projects, select \gui{Tools} > \gui{Options...} >
    \gui{Projects} > \gui{General}.

    To specify build and run settings for different target platforms, select
    \gui Projects.

    \section1 Adding Files to Projects

    You can use wizards also to add individual files to your projects.
    You can create the following types of files:

    \list

        \o Qt resource files, which allow you to store binary files in the
        application executable

        \o \QD forms and \QD form classes, which specify parts of user
        interfaces in Qt widget based projects

        \o QML files, which specify elements in Qt Quick projects

        \o GLSL files that define fragment and vertex shaders in both Qt Quick
        projects and Qt widget based projects

        \o C++ class, source, or header files that you can use to write the
        application logic in both Qt Quick projects and Qt widget based
        projects

        \o JavaScript files that you can use to write the application logic in
        Qt Quick projects

        \o Text files

    \endlist

    \section2 Creating C++ Classes

    The \gui {C++ Class Wizard} allows you to create a C++ header and source file for
    a new class that you can add to a C++ project. Specify the class name, base
    class, and header and source files for the class.

    The  wizard supports namespaces. To use a namespace, enter a qualified
    class name in the \gui {Class name} field. For example:
    MyNamespace::MySubNamespace::MyClass.

    \image qtcreator-cpp-class-wizard.png "Enter Class Name dialog"

    The names of the header and source file are based on the class name. To change the
    default suffix of a file, click \gui Configure.

    You can create your own project and class wizards. For more information,
    see \l{Adding New Custom Wizards}.

    \section2 Creating OpenGL Fragment and Vertex Shaders

    Qt provides support for integration with OpenGL implementations on all
    platforms, which allows you to display hardware accelerated 3D graphics
    alongside a more conventional user interface. For more information, see
    \l{http://doc.qt.nokia.com/4.7/qtopengl.html}{QtOpenGL Module}.

    You can use the QGLShader class to compile OpenGL shaders written in the
    OpenGL Shading Language (GLSL) and in the OpenGL/ES Shading Language
    (GLSL/ES). QGLShader and QGLShaderProgram shelter you from the details of
    compiling and linking vertex and fragment shaders.

    You can use Qt Creator code editor to write fragment and vertex shaders
    in GLSL or GLSL/ES. The code editor provides syntax highlighting and code
    completion for the files.

    \image qtcreator-new-opengl-file.png "New OpenGL file wizard"

    \section2 Displaying Additional File Types in Projects Pane

    Qt Creator determines whether to display files from the project folder
    in the \gui Projects pane depending on the file type (.pro, .pri, .cpp,
    .h, .ui, .qrc, and so on). To display other types of files, edit the
    project file. Add filenames as values of the \c {OTHER_FILES} variable.
    You can also use wildcards.

    For example, the following code specifies that text files are displayed
    in the \gui Projects pane:

    \code

    OTHER_FILES += *.txt

    \endcode

    This also makes the files available in the \gui Locator.

    \section1 Adding Subprojects to Projects

    When you create a new project, you can add it to another project as a subproject
    in the \gui{Project Management} dialog. However, the root project must
    specify that qmake uses the \c subdirs template to build the project.

    To create a root project, select \gui {File > New File or Project... >
    Other Project > Subdirs Project > Choose}.

    On the \gui Summary page, select \gui {Finish & Add Subproject} to create
    the root project and to add another project, such as a C++ library.

    The wizard creates a project file (.pro) that defines a \c subdirs template
    and the subproject that you add as a value of the
    \l{http://doc.qt.nokia.com/4.7/qmake-variable-reference.html#subdirs}{SUBDIRS variable}.
    It also adds all the necessary files for the subproject.

    To add more subprojects, right-click the project name in the \gui Projects
    pane, and select \gui {New Subproject} in the context menu.

    To remove subprojects, right-click the project name in the \gui Projects
    pane, and select \gui {Remove Subproject} in the context menu.

    To specify dependencies, use the \gui{Add Library} wizard. For more information,
    see \l{Adding Libraries to Projects}.

*/


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

    \title Opening a Project

    Qt Creator stores information that it needs to build projects in a .user file.
    If Qt Creator cannot find the file when you open an existing project, it prompts you
    to enter the information. If you created the project by using another Qt Creator
    instance, Qt Creator asks whether you want to use the old settings. The settings
    are specific to the development environment, and should not be copied from one
    environment to another. Therefore, we recommend that you click \gui No and enter
    the information again in the \gui {Project Setup} dialog.

    The \gui {Project Setup} dialog displays a list of development environments for
    target platforms (such as desktop, Maemo5 devices, and Symbian devices) that are
    installed on the development PC. Select the Qt versions that you want to use to build
    the project for each target.

    \image qtcreator-open-project-targets.png "Target Setup dialog"

    If Qt Creator cannot find an existing build for a particular development
    environment (Qt version) and target, it starts out from a clean slate, and
    creates a new build in the specified directory. Qt Creator suggests a name
    and location for the directory that you can change.

    By default, Qt Creator does a \l{glossary-shadow-build}{shadow build} and also
    creates the directory. However, shadow building is not supported for the Symbian
    Devices, Maemo5, or Harmattan target on Windows.

    If you have built the project before, Qt Creator can use the existing build
    configuration to make the exact same build as found in the directory available to
    Qt Creator.

    If you know you have a build, but it is not listed, click \gui {Add Build}
    to locate it. Select a directory, and Qt Creator scans it (including
    subdirectories) for additional builds of the project. Qt Creator adds the found
    builds to the target list.

    You can edit the build configuration later. For more information, see
    \l{Editing Build Configurations}.

    To open a project:

    \list 1

        \o Select \gui File > \gui{Open File or Project} and select the project
        to open.

        \o In the \gui {Project Setup} dialog, select the Qt versions to use as
        build targets for your project, and click \gui{Finish}.

        \note If you have only one development environment installed, this dialog
        is skipped.

    \endlist

    Qt Creator parses all the source files in the project and performs a semantic
    analysis to build up the information that it needs for functions such as
    navigation and finding usages. Qt Creator also scans for all include files in
    your include path recursively, so that it can complete them.
    Progress bars are displayed during parsing and scanning.

*/


/*!
    \contentspage index.html
    \previouspage creator-os-supported-platforms.html
    \page creator-project-wizards.html
    \nextpage creator-project-cmake.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 classes.

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

    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.

    In a class wizard, you can allow developers to specify the class name, base
    class, and header and source files for the class.

    To see how this works, rename wizard_sample.xml as wizard.xml in the
    \c {\share\qtcreator\templates\wizards\listmodel\helloworld} and
    \c {\share\qtcreator\templates\wizards\listmodel\listmodels} folders. After
    you restart Qt Creator, the \gui {Custom Classes}
    and \gui {Custom Projects} categories appear in the \gui New dialog.

    \image qtcreator-custom-project-wizards.png "The New dialog with custom projects and classes"

    \section1 Overview of Custom Wizards

    A custom wizard defines the user interface of a wizard page. 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. File creation can happen in the following ways:

    \list 1

        \o Template-based, where source files that contain placeholders for
        the field names are provided. During processing, the placeholders are replaced
        by the values from the wizard page. Optionally, modifier
        characters are applied. For more information, see \l{Processing Template Files}.

        \o Generator script, where a script is called to create the files.

        \note This option mainly exists to accommodate existing generator scripts or
        cases where complicated algorithmic logic is required when generating files. Writing
        cross-platform scripts is inherently difficult, and therefore, it is not recommended
        for new wizards. For more information, see \l{Using Generator Scripts}.

    \endlist

    Custom wizards are located in subdirectories of the following directories:

    \list

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

        \o the local user's configuration folder,
        \c{$HOME/.config/Nokia/qtcreator/templates/wizards}

        \o \c{%APPDATA%\Nokia\qtcreator\templates\wizards}

    \endlist

    They contain an XML configuration file called wizard.xml, the
    template source files, and optionally, the generator script.

    \section1 Creating Project Wizards

    To create a project wizard:

    \list 1

        \o Make a copy of the \c {share/qtcreator/templates/wizards/helloworld} or
        \c {share/qtcreator/templates/wizards/listmodel} folder.

        \o Modify the wizard_example.xml file.

        \o The following code determines the type of the wizard and its place
        in the \gui New dialog:

        \code

        <wizard version="1" kind="project"
        class="qt4project" firstpage="10"
        id="A.HelloWorld" category="B.CustomProjects">

        \endcode

        \list

            \o \c version is the version of the file contents. Do not modify this value.

            \o \c kind specifies the type of the wizard: \c project or \c class.

            \o \c class specifies the type of the project. Currently the only available
            type is \c qt4project, which specifies a Qt console project.

            \o \c firstpage specifies the place of the new page in the standard project
            wizard. The value 10 ensures that the custom page appears after the standard
            pages, as the last page of the wizard.

            \o \c id is the unique identifier for your wizard. The letter specifies the
            position of the wizard within the \c category. The HelloWorld wizard appears
            as the first wizard in the second category in the \gui New dialog.

            \o \c category is the category in which to place the wizard in the list.
            The letter specifies the position of the category in the list in the \gui New
            dialog.

        \endlist

        \o The following code specifies the icon and text that appear in the \gui New
         dialog:

        \code

        <icon>console.png</icon>
        <description>Creates a hello-world-project with custom message.</description>
        <description xml:lang="de">Erzeugt ein Hello-Welt-Projekt mit einer Nachricht.</description>
        <displayname>Hello World</displayname>;
        <displayname xml:lang="de">Hallo Welt</displayname>;
        <displaycategory>Custom Projects</displaycategory>
        <displaycategory xml:lang="de">Benutzerdefinierte Projekte</displaycategory>

        \endcode

        \list


            \o \c icon appears next to the \c displayName.

            \o \c description appears at the bottom of the \gui New dialog when you
            select the display name.

            \o \c displayName appears in the \gui New dialog, under the
            \c displayCategory.

            You can add translations as values for the text elements. Specify the target
            language as an attribute for the element. Use locale names (QLocale).
            For example, \c {xml:lang="de"}.

        \endlist

        \o Files to be added to the project:

        \list
            \o Template-based: The following code specifies the files to add to the project:
            \code
        <files>
            <file source="main.cpp" openeditor="true" />
            <file source="project.pro" target="%ProjectName%.pro" openproject="true" />
            <file source="icon.png" target="%ProjectName%.png" binary="true" />
        \endcode
            \list

                \o \c source specifies the file to copy to the project. The files must be
                located in the wizard folder.

                \o \c openeditor indicates that the file is to be opened in an editor after
                the wizard has finished.

                \o \c binary indicates that the file is a binary file (for example, an
                image file). It is to be copied to the target folder as is. Placeholders
                are not replaced with values.

                \o \c target specifies the new filename for the file. The \c {%ProjectName%}
                variable is replaced with the string that users specify in the \gui Name
                field on the first page of the wizard.

                \o \c openproject indicates that the file is a project file which is to be opened
                after the wizard has finished.

            \endlist

            See also \l{Processing Template Files}.

            \o Generator-script: The following code specifies that the script \c generate.pl is to be used
               to create the files:
            \code
            <generatorscript binary="generate.pl">
                <argument value="--class-name=%ClassName%"/>
                <argument value="--project-name=%ProjectName%"/>
                <argument value="--header-suffix=%CppHeaderSuffix%" omit-empty="true"/>
                <argument value="--source-suffix=%CppSourceSuffix%" omit-empty="true"/>
                <argument value="--description=%Description%" omit-empty="true" write-file="true"/>
            </generatorscript>
            \endcode
            In each argument, the field placeholders are replaced by the field
            values. There are additional boolean attributes which give fine-grained control:

            \list
            \o \c omit-empty specifies that complete argument is to be omitted when all
               placeholders expand to empty values. In the above example,
               the option \c --source-suffix will not be passed to the script if the value is empty.

             \o \c write-file indicates that instead of the expanded value,
                the value will be written to a temporary file and its file name will be
                passed to the script instead. This is useful for multi-line text fields.
            \endlist

             See also \l{Using Generator Scripts}.
        \endlist

        \o The following code creates a page that specifies settings for the project:

        \code

        <!-- Create a 2nd wizard page with parameters -->
        <fieldpagetitle>Hello World Parameters</fieldpagetitle>
        <fieldpagetitle xml:lang="de">Hallo Welt Parameter</fieldpagetitle>
        <fields>
            <field mandatory="true" name="MESSAGE">
                <fieldcontrol class="QLineEdit" validator='^[^"]+$'  defaulttext="Hello world!" />
                <fielddescription>Hello world message:</fielddescription>
                <fielddescription xml:lang="de">Hallo-Welt-Nachricht:</fielddescription>
            </field>
        </fields>

        \endcode

        \list

            \o \c fieldpagetitle specifies the title of the page.

            \o \c field specifies whether the field is mandatory (\c true or \c false).
            You can use the value of the \c name field as a variable in other files (for
            example, \c {%MESSAGE%}.

            \o \c fieldcontrol specifies the field. \c class specifies the field type.
            You can use interface objects from the QWidget class to create fields. This
            example uses QLineEdit to create an input field.

            \o \c validator specifies a regular expression to check the characters allowed in
            the field.

            \o \c defaulttext specifies text that appears in the field by default.

            \o \c fielddescription specifies the field name that appears on the wizard page.

         \endlist

    \endlist

    \section1 Creating Class Wizards

    The widget.xml file for a class wizard is very similar to that for a project
    wizard. The differences are discussed below.

    To create a class wizard:

    \list 1

        \o The following code specifies settings for the wizard:

        \code

        <wizard version="1" kind="class" id="A.ListModel" category="B.CustomClasses">

           <description>Creates a QAbstractListModel implementation.</description>
           <description xml:lang="de">Erzeugt eine Implementierung von QAbstractListModel.</description>

           <displayname>QAbstractListModel implementation</displayname>
           <displayname xml:lang="de">Implementierung von QAbstractListModel</displayname>

           <displaycategory>Custom Classes</displaycategory>
           <displaycategory xml:lang="de">Benutzerdefinierte Klassen</displaycategory>

        \endcode

        For more information about the elements and their values, see
        \l {Creating Project Wizards}.

        \o The following code specifies the files to add to the project:

        \code

        <files>
            <file source="listmodel.cpp" target="%ClassName:l%.%CppSourceSuffix%"  openeditor="true" />
            <file source="listmodel.h" target="%ClassName:l%.%CppHeaderSuffix%"  openeditor="true" />
        </files>

        \endcode

        Here, \c target contains the following variables that are used to construct
        the filename:

        \list

        \o \c {%ClassName:l%} is replaced with the value of the \c ClassName field.
        The modifier \c l converts the string to lower case, to observe Qt
        conventions.

        \o \c {%CppSourceSuffix%} and \c {%CppHeaderSuffix%} are pre-defined.
        For more information, see \l{Pre-defined Standard Variables}.

        \endlist

        \code

        <!-- Create parameter wizard page -->

        <fieldpagetitle>ListModel parameters</fieldpagetitle>
        <fieldpagetitle xml:lang="de">Parameter des ListModel</fieldpagetitle>
        <fields>
            <field name="ClassName">

                <fieldcontrol class="QLineEdit" validator="^[a-zA-Z0-9_]+$" defaulttext="MyListModel" />

                <fielddescription>Class name:</fielddescription>
                <fielddescription xml:lang="de">Klassenname:</fielddescription>
            </field>
            <field name="Datatype">

                <fieldcontrol class="QComboBox" combochoices="QString,int" defaultindex="0" />

                <fielddescription>Data type:</fielddescription>
                <fielddescription xml:lang="de">Datentyp:</fielddescription>
            </field>
        </fields>

        \endcode

        In addition to QLineEdit, QComboBox is used in the class wizard to create
        a field. \c combochoices specifies the options in the combobox and
        \c defaultindex specifies that QString is the default value.

    \endlist

    \section1 Processing Template Files

    When processing a template source file, placeholders specifying the field names
    in the format \c{%FIELDNAME%} are replaced by the values entered by the user.
    In addition, modifier characters are supported. For example, \c{%FIELDNAME:u%}
    specifies that the value is converted to upper case. This enables generating header
    guards for C++ header files.

    The following modifier characters are supported:

    \list
    \o \c{l} for lower case.
    \o \c{u} for upper case.
    \o \c{c} for upper case initial letter ("project" > "Project").
    \endlist

    You can use conditions to add sections of the file depending on field values.
    Use a syntax that is similar to C++ preprocessing, as demonstrated in
    the profile of the \c{helloworld} example:

    \code

    @if "%SCRIPT%" == "true"
    QT += script
    @endif

    \endcode

    The value of the Boolean (QCheckBox) field labeled \c{SCRIPT} determines
    whether the script module is added. The expressions must expand to valid
    Javascript expressions after field replacement.

    \section1 Pre-defined Standard Variables

    In addition to the field values entered by the user, you can use
    the following pre-defined standard values:

    \list

    \o \c {%ProjectName%} is replaced by the name of the project in the case
    of project wizards.

    \o \c {%Path%} is replaced by the path to the target directory.
    For classes, this is the directory, where the files
    are created. For project wizards, an additional subdirectory
    named after the project is created.

    \o \c {%TargetPath%} is replaced by the path to the directory where the actual files
    are created. For non-project wizards, it is identical to \c %Path%.
    For project wizards, it is \c %Path%/%ProjectName%.

    \o \c {%CppSourceSuffix%} is replaced by the default source suffix, which
    is defined in Qt Creator in \gui {Tools > Options... > C++ > File Naming}.
    For example, if users enter \bold MyClass, the filename becomes myclass.cpp
    when the project is created.

    \o \c {%CppHeaderSuffix%} is replaced by the default header suffix, which
    is also defined in \gui {File Naming}.

    \endlist

    \section1 Validating User Input

    You can specify validation rules for user input. The rules consist of a Boolean
    JavaScript expression and an error message. The placeholders in them are
    replaced with values before they are evaluated or displayed.

    Consider the following rule used in the \l{Creating Class Wizards} example:

    \code
    <validationrules>
        <validationrule condition='"%ClassName%" != "QAbstractListModel"'>
            <message>%ClassName% cannot be used as class name.</message>
            <message xml:lang="de">%ClassName% kann nicht als Klassenname verwendet werden.</message>
        </validationrule>
    </validationrules>
    \endcode

    It ensures that the class name entered by the user does not match the name of
    the base class. If the validation fails, a red label displaying the message appears
    at the bottom of the wizard page.

    \section1 Using Generator Scripts

    The values entered in the wizard page are passed to the script
    as command line arguments as defined by the wizard configuration file.

    In addition, the script must implement a \c{--dry-run} command line option.

    Qt Creator needs to know the file names before the files are created to check
    whether files with identical names already exist, for example. Therefore,
    script file generation is a two-step process:

    \list 1

    \o  Determine file names and attributes: The script is called with the command line
        \c{--dry-run} option and the field values. It then prints the relative path
        names of the files it intends to create, followed by comma-separated attributes
        matching those of the \c{<file>} element, for example:

        \code
        myclass.cpp,openeditor
        myclass.h,openeditor
        myproject.pro,openproject
        \endcode

    \o Create files: The script is called with the parameters only in the working directory.
       It then actually creates the files. If directories are needed, the script
       should create them, too.

   \endlist

   The \c{scriptgeneratedproject} sample wizard illustrates the usage.
   A typical script invocation for this example (obtained by running Qt Creator with
   \c{--customwizard-verbose}) looks as follows:

   \code
   generate.pl --class-name=TestClass --project-name=TestProject --header-suffix=h --source-suffix=cpp --description=/tmp/qtcreatorj26629.txt
   \endcode

   By default, the scripts are run in the directory corresponding to
   \c %TargetPath%. This can be overriden by specifying the
   attribute \c workingdirectory on the element \c generatorscript.
   For example, if the script creates the project directory by itself,
   %Path% can be specified. In that case, \c --dry-run should output
   the correct relative paths or absolute paths constructed using the value of
   \c %Path%.

*/


/*!
    \contentspage index.html
    \previouspage creator-build-settings.html
    \page creator-project-qmake.html
    \nextpage creator-tool-chains.html

    \title Adding Qt Versions

    Qt Creator allows you to have multiple versions of Qt installed on
    your development PC and use different versions to build your projects for
    different targets. For example, \QSDK contains special Qt versions for
    MeeGo Harmattan, Maemo, and Symbian development.

    Qt Creator checks the directories listed in the \c{PATH} environment
    variable for the qmake executable. If a qmake executable is found, it is
    referred to as \bold{Qt in PATH} and selected as the Qt version to use
    in the \gui Projects mode in the \gui {Build Settings}. If Qt Creator
    cannot find qmake, the value in the \gui {Qt version} field might be
    invalid and you might need to change it.

    Qt Creator automatically detects the Qt versions that are registered by
    your system or by \QSDK. To view the settings for each Qt version, move the
    mouse pointer over it in the list. To add Qt versions, select
    \gui {Tools > Options... > Qt4 > Qt Versions}.

    Typically, you select the Qt versions for a project when you use project
    wizards to create the project. You can add Qt versions for a project in
    \gui {Build Settings}.

    \section2 Setting Up New Qt Versions

    To add a Qt version:

        \list 1

            \o  Select \gui Tools > \gui Options... > \gui Qt4 > \gui Add.

                \image qtcreator-qt4-qtversions-add.png

            \o  In the \gui{qmake location} field, enter the path to the
                directory where the qmake executable is located.

            \o  In the \gui{Version name} field, edit the name that Qt Creator
                suggests for the Qt version.

                Qt Creator automatically determines the path to the binaries in
                the Qt installation and displays it in the dialog.

            \o  In the \gui Helpers section, you can build the debugging
                helpers that are available for the Qt version. This is
                necessary, because the internal data structures of Qt can
                change between versions. For more information, see
                \l{Using Debugging Helpers}.

        \endlist

    \section2 Setting Up Qt for Symbian Versions

    If you install Qt for Symbian as a part of \QSDK, it is automatically
    detected by Qt Creator. If you install other Symbian SDKs and register them
    with devices.exe, Qt Creator automatically detects the Qt version.

    If the selected Qt version was built using the SBSv2 build system, that
    is available for Symbian OS 9.5 based SDKs, Qt Creator builds your projects
    using this build system. The \gui {SBS v2 directory} field is enabled and
    you must specify the path to the directory where the SBS executable (for
    example, sbs.bat on Windows) is located.

    To add a Qt for Symbian version:

    \list 1

        \o  Select \gui Tools > \gui Options... > \gui Qt4 > \gui{Qt Versions}.

        \o  Select the Qt for Symbian version you want the Qt Creator to use.

            \image qtcreator-qt4-qtversions-win-symbian.png

            For more information about how to add tool chains for using the
            GCCE and WINSCW compilers, see \l{Adding Tool Chains}.

        \o  In the \gui {S60 SDK} field, enter the path to the directory where
            the Symbian SDK is located.

        \o  In the \gui {SBS v2 directory} field, enter the path to the
            directory where the SBS v2 executable is located.

    \endlist

*/


/*!
    \contentspage index.html
    \previouspage creator-project-qmake.html
    \page creator-tool-chains.html
    \nextpage creator-run-settings.html

    \title Adding Tool Chains

    A \e {tool chain} specifies a compiler and a debugger and other necessary
    tools for building an application that is targeted for a particular desktop
    or mobile platform. Qt Creator automatically detects the tool chains that
    are registered by your system or by \QSDK.

    You can add tool chains to build applications by using other compilers or
    with different versions of the automatically detected compilers:

    \list

        \o  GNU Compiler Collection (GCC) is a cross compiler for Linux and
            Mac OS X.

        \o  MinGW (Minimalist GNU for Windows) is a native software port of GCC
            and GNU Binutils for use in the development of native Microsoft
            Windows applications on Windows or as cross compiler. MinGW is
            distributed together with Qt Creator and Qt SDK for Windows.

        \o  GCCE (GNU Compiler Collection for Embedded) is an ARM-based
            compiler used in Symbian OS 9 and distributed together with the
            Symbian OS 9 SDKs.

        \o  RVCT is an ARM-bases compiler for building applications for Symbian
            devices (requires a license).

        \o  WINSCW is a compiler for building applications that can be run or
            debugged on the Symbian Emulator. It is distributed together with
            Symbian SDKs.

    \endlist

    To build an application using MinGW or GCCE, specify the paths to the
    directories where the compiler and debugger are located and select the
    application binary interface (ABI) version from the list of available
    versions.

    Qt Creator allows you to select a tool chain that matches the Qt version
    in the \gui Projects mode \gui {Build Settins}.

    To add tool chains:

    \list 1

        \o  Select \gui {Tools > Options... Tool Chains > Add} and select a
            compiler in the list.

            To clone the selected tool chain, select \gui {Clone}.

        \o  In the \gui Name column, double-click the name to change it.

        \o  In the \gui{Compiler path} field, enter the path to the directory
            where the compiler is located. For WINSCW, enter the path to the
            Carbide C++ installation directory here.

            \image qtcreator-toolchains.png

            The other settings to specify depend on the tool chain.

        \o  For RVCT, select the ARM version to use in the \gui {ARM version}
            field.

    \endlist

    \section2 Troubleshooting MinGW Compilation Errors

    If error messages displayed in the \gui {Compile Output} pane contain
    paths where slashes are missing (for example, C:QtSDK),
    check your PATH variable. At the command line, enter the following commands:

    \code
        where sh.exe
        where make.exe
        where mingw32-make.exe
    \endcode

    If these commands show paths, they have been added to the global PATH variable
    during the installation of a tool chain based on Cygwin or MinGW, even though
    this is against Windows conventions.

    To keep working with the third-party tool chain, create a new shell link
    that adds the required paths (as Visual Studio and Qt do). The shell link
    must point to cmd.exe, as illustrated by the following example:

    \c {C:\Windows\System32\cmd.exe /K C:\path_to\myenv.bat}

    where the /K parameter carries out the command specified in the bat file.

    Create the myenv.bat file at \e path_to, which should be in a convenient location.
    In the file, specify the paths to the tool chains. For example,

    \c  {set PATH=C:\path1;C:\path2;%PATH%}

    where \e path1 and \e path2 are paths to the tool chains.

    Finally, remove the paths from the global PATH, reboot the computer, and
    run the \c where commands again to verify that the global PATH is now clean.

    You can use the shell link to run the tools in the third-party tool chains.

*/


/*!
    \contentspage index.html
    \previouspage creator-project-opening.html
    \page creator-project-qmake-libraries.html
    \nextpage creator-developing-maemo.html

    \title Adding Libraries to Projects

    In addition to Qt libraries, you can add other libraries to your projects.
    The way the library is added depends on whether it is a system library or
    your own library or a 3rd party library located in the build tree of the
    current project or in another build tree.

    \image qtcreator-add-library-wizard.png "Add Library wizard"

    Because system libraries do not typically change and are often found by
    default, you do not need to specify the path to the library or to its includes
    when you add it.

    For your own libraries and 3rd party libraries, you need to specify
    the paths. Qt Creator tries to quess the include path for an external library,
    but you need to check it and modify it if necessary. Qt Creator automatically
    adds the include path for an internal library.

    For all libraries, select the target platforms for the application, library,
    or plugin.

    Specify whether the library is statically or dynamically linked. For a
    statically linked internal library, Qt Creator adds dependencies
    (PRE_TARGETDEPS) in the project file.

    Depending on the development platform, some options might be detected
    automatically. For example, on Mac OS, the library type (\gui Library or
    \gui Framework) is detected automatically and the option is hidden. However,
    if you develop on another platform than Mac OS and want to build your
    project for the Mac OS, you must specify the library type.

    The default convention on Windows is that the debug and release versions
    of a library have the same name,
    but are placed in different subdirectories, usually called \e debug and
    \e release. If the library path does not contain either of these folders,
    you cannot select the option to place the libraries in separate
    folders.

    Alternatively, the letter \e d can be added to the library name for the debug
    version. For example, if the release version is called example.lib, the
    debug version is called exampled.lib. You can specify that the letter
    is added for the debug version and removed for the release version.
    If the library name ends in \e d, deselect the \gui {Remove "d" suffix
    for release version} option.

    Qt Creator supports code completion and syntax highlighting for the added
    libraries once your project successfully builds and links to them.

    \section1 To Add Libraries

    \list 1

        \o In the \gui Projects pane, open the project file (.pro).

        \o Right-click in the code editor to open the context menu and select
        \gui {Add Library...}.

        \o Follow the instructions of the wizard.

    \endlist

    For more information about the project file settings, see
    \l{http://doc.qt.nokia.com/4.7/qmake-project-files.html#declaring-other-libraries}{Declaring Other Libraries}.

    \section1 Example of Adding Internal Libraries

    The following example describes how to add a statically linked internal
    library to your project.

    \list 1

        \o Choose \gui {File > New File or Project... > Other Projects >
        C++ Library} to create the library.

        The \gui {Introduction and Product Location} dialog opens.

        \image qtcreator-add-library-wizard-ex-1.png "Introduction and Product Location dialog"

        \o In the \gui Type field, select \gui {Statically Linked Library}.

        \o In the \gui Name field, give a name for the library. For example,
        \bold mylib.

        \o Follow the instructions of the wizard until you get to the
        \gui {Project Management} dialog. In the \gui {Add to project}
        list, select a project. For example, \bold myapp.

        \o In the \gui Projects pane, open the project file (.pro).
        For example, \bold myapp.pro.

        \o Right-click in the code editor to open the context menu and select
        \gui {Add Library... > Internal Library > Next}.

        \o In the \gui Library field, select \bold mylib and click \gui Next.

        \o Click \gui Finish to add the following library declaration to the
        project file:

        \code
        win32:CONFIG(release, debug|release): LIBS += -L$$OUT_PWD/../../../projects/mylib/release/ -lmylib
        else:win32:CONFIG(debug, debug|release): LIBS += -L$$OUT_PWD/../../../projects/mylib/debug/ -lmylib
        else:symbian: LIBS += -lmylib
        else:unix: LIBS += -L$$OUT_PWD/../../../projects/mylib/ -lmylib

        INCLUDEPATH += $$PWD/../../../projects/mylib
        DEPENDPATH += $$PWD/../../../projects/mylib

        win32:CONFIG(release, debug|release): PRE_TARGETDEPS += $$OUT_PWD/../../../projects/mylib/release/mylib.lib
        else:win32:CONFIG(debug, debug|release): PRE_TARGETDEPS += $$OUT_PWD/../../../projects/mylib/debug/mylib.lib
        else:unix:!symbian: PRE_TARGETDEPS += $$OUT_PWD/../../../projects/mylib/libmylib.a
        \endcode

    \endlist

*/


/*!
    \contentspage index.html
    \previouspage creator-usability.html
    \page creator-building-running.html
    \nextpage creator-building-targets.html

    \title Building and Running Applications

    Qt Creator provides support for building, running, and deploying Qt
    applications for desktop environment and mobile devices.

    You can set up the following configurations:

    \list

        \o \e {Build configuration}, which contains everything you need to
        compile the sources into binaries.

        \o \e {Deploy configuration}, which handles the packaging and copying
        of the necessary files to a location you want to run the executable at.
        The files can be copied to a location in the file system of the development
        PC or a mobile device.

        \o \e {Run configuration}, which starts the application in the location
        where it was stored by the deploy configuration.

    \endlist

    By default, when you select the \gui Run function, Qt Creator builds, deploys,
    and runs the project. For more information about how to change the default
    behavior, see \l{Customizing the Build Process}.

     \section1 Setting Up a Project

    When you install the \QSDK, the build and run settings for the tool chains
    delivered with the \QSDK are set up automatically.

    To view and modify the settings for currently open projects, switch to the
    \gui Projects mode by pressing \key Ctrl+5.

    \image qtcreator-projectpane.png

    You can add a target if the development environment for the target
    platform is installed on the
    development PC and the Qt version is configured. Click
    \inlineimage qtcreator-qt4-addbutton.png "Add Target button"
    and select from a list of available
    targets. To remove a target, select it and click
    \inlineimage qtcreator-target-remove.png "Remove Target button"
    .

    You can select the targets and use the \gui Build menu commands to
    build, deploy, and run projects.

    The project pane consists of the following tabs:
    \list
       \o \l{Running Applications on Multiple Targets}{Targets}
       (If you have installed the development environment for only one target, the \gui Targets
       tab is replaced by a \gui Build tab and a \gui Run tab.)
       \o \l{Specifying Build Settings}{Build Settings}
       \o \l{Specifying Run Settings}{Run Settings}
       \o \l{Specifying Editor Settings}{Editor Settings}
       \o \l{Specifying Dependencies}{Dependencies}
    \endlist

    Use the \gui Build and \gui Run buttons to switch between
    the build and run settings for the active project.

    If you have multiple projects open in Qt Creator, use the tabs at the
    top of the window to navigate between their settings.

    \section1 Customizing the Build Process

    To specify the relationship between the release, build, and deploy configurations, select
    \gui {Tools > Options... > Project}. By default, the \gui {Always build project
    before deploying it} and the \gui {Always deploy project before running it}
    options are enabled. Therefore, when you select the \gui Run function,
    Qt Creator builds, deploys, and runs the project.

    \image qtcreator-project-options-deploy.png "Project General Options"

*/


/*!
    \contentspage index.html
    \previouspage creator-building-running.html
    \page creator-building-targets.html
    \nextpage creator-running-targets.html

    \title Building Applications for Multiple Targets

    You can build applications for multiple targets. By default, when
    you run the application on a target, you also build and deploy it to the
    target, first. However, you can also perform each operation separately.

    To check that the application code can be compiled and linked for a target,
    you can build the project. The build errors and warnings are displayed in
    the \gui {Build Issues} output pane. More detailed information is displayed in
    the \gui {Compile Output} pane.

    To build an application:

    \list 1

        \o Select a target for the project.

        \image qtcreator-target-selector.png "Target selector"

        \o Choose \gui {Build > Build Project} or press \key {Ctrl+B}.

    \endlist

    For more information on the options you have, see \l{Specifying Build Settings}.

    \section1 Building for Symbian

    The tool chain for building applications locally on the development PC for
    the \gui {Symbian Device} target is only supported on Windows.
    If you develop on Linux or Mac OS, you must use the Remote Compiler
    interface to a compilation service at Forum Nokia. For more information,
    see \l{Building with Remote Compiler}.

    \section2 Troubleshooting Build Issues

    If you cannot build the application for a Symbian device, check that:

     \list

        \o You selected the Symbian Device target to build the application.

        \o You selected the correct Qt version to build the application.

     \endlist

     \section1 Building for Symbian Emulator

     Qt Creator does not create release configurations for the
     \gui {Symbian Emulator} target, because Symbian Emulator supports only debug
     builds.

*/


/*!
    \contentspage index.html
    \previouspage creator-building-targets.html
    \page creator-running-targets.html
    \nextpage creator-build-settings.html

    \title Running Applications on Multiple Targets

    By default, running an application also builds it and deploys it to a
    location from where it can be run on the desktop, in Qt Simulator, or
    on a mobile device that is connected to the development PC.

    To run executable files without deploying them first, deselect the \gui {Tools >
    Options... > Project > Always deploy project before running it} option.
    This allows you to test SIS files that you receive from Ovi Publishing or
    Symbian Signed after you have them signed, for example.

    For more information on the options you have, see \l{Specifying Run Settings}.

    \section1 Running on Desktop

    \list 1

        \o Select \gui Desktop as the target.

        \image qtcreator-target-selector.png "Target selector"

        \o Click the \gui Run button.

    \endlist

    \section1 Running on Qt Simulator

    You can use the Qt Simulator to test Qt applications that are intended
    for mobile devices in an environment similar to that of the device. You
    can change the information that the device has about its configuration
    and environment.

    \list 1

        \o Select \gui {Qt Simulator} as the target.

        \o Click the \gui Run button.

    \endlist

    For more information about using the Qt Simulator, see the
    \l{http://doc.qt.nokia.com/qtsimulator/index.html}{Qt Simulator Manual}.

    \section1 Running on Maemo or MeeGo Harmattan

    \list 1

        \o Build and run the application for \l{Running on Qt Simulator}{Qt Simulator}.

        \o  Build and run the application for
            \l{Using Maemo or MeeGo Harmattan Emulator}
            {the Maemo or MeeGo Harmattan emulator}.

        \o Alternatively, you can build and run the application for a device:

        \list 1

        \o  Configure the device and specify a connection to it. For more
            information, see \l{Connecting Maemo and MeeGo Harmattan Devices}.

        \o Connect the device to the development PC.

        \o Click the \gui Run button.

        \endlist

    \endlist

        Qt Creator uses the compiler specified in the MADDE tool chain to
        build the application.

        Qt Creator generates an installation package, installs it on the device,
        and executes the selected application.
        The application views are displayed on the device.
        Command-line
        output is visible in the Qt Creator \gui {Application Output} view.

        Choose \gui {Projects > Maemo Run} to view the settings for deploying the
        application on the connected device and creating the installation package.
        For more information, see
        \l{Specifying Run Settings for Maemo and MeeGo Harmattan Devices}.

        Debugging also works transparently.

    \section1 Running on Symbian

    \list 1

        \o Build and run the application for \l{Running on Qt Simulator}{Qt Simulator}.

        \o If no problems are found, build and run the application for a device.

        \o To test functionality that uses Symbian APIs, you can build and
        run the application for Symbian Emulator.

    \endlist

    \section2 Running on a Device

    \list 1

        \o Install the required software on the device. For more information, see
        \l{Connecting Symbian Devices}.

        \o Connect the device to the development PC through a USB cable.
        The target selector displays a green check mark when a
        device is connected.

        \image qtcreator-qt4-symbian-device-connected.png

        The tool tip of the target selector shows more details about the actual
        device that will be used when you run your application.

        \o Start the debugging agent (CODA or App TRK) application on your device.

        \note If you use CODA over an USB connection, it starts up
        automatically when you connect the device to the development PC.

        \o Click the \gui Run button.

    \endlist

    You can connect several devices to your development PC simultaneously.
    In the details of the run configuration for the \gui{Symbian Device} target,
    select the device to run your application on.

    When your application is ready for delivery to users, specify run settings
    for creating the final SIS installation packages. For more information,
    see \l{Creating SIS Files}.

    If you cannot run the application on a device, check that:

     \list
        \o The Nokia USB drivers that come with \e{PC Suite} or \e{Ovi Suite}
        have been installed on the development PC.
        \o The device is connected through USB cable in \e{PC Suite} mode.
        \o The debugging agent (App TRK or CODA) is running on the device with
           the status \e connected.

           \note If you use the CODA debugging agent over WLAN, you must enter
           the WLAN address and port number in Qt Creator, separated by a
           colon (:). For example: 192.167.0.100:1534
        \o The device is detected and selected in the \gui {Run Settings}.
     \endlist

    If this does not help to solve your problem, search the qt-creator@trolltech.com
    mailing list archives or provide feedback to us via the methods described on the
    \l{http://developer.qt.nokia.com/wiki/Category:Tools::QtCreator}{Qt Creator Development Wiki}.

    \section2 Running on Symbian Emulator

    Select
    the \gui{Symbian Emulator} target as the active one, and build and run your
    project.

    If you cannot run the application in the emulator, check that:
     \list
        \o You selected the \gui{Symbian Emulator} target for your application.

        \o If you cannot select \gui {Symbian Emulator} as target, check that
        Carbide.c++ is installed correctly and that the path to the Carbide.c++
        installation directory is specified for the WINSCW tool chain in the
        \gui{Compiler path} field
        in \gui {Tools > Options... > Tool Chains}.

        \o If the emulator process cannot be started, try closing Qt Creator and
           starting the application directly from your file manager. Having
           done this, Qt Creator should be able to run your projects in the
           emulator.

     \endlist

*/


/*!
    \contentspage index.html
    \previouspage creator-publish-ovi.html
    \page creator-remote-compiler.html
    \nextpage creator-help.html

    \title Building with Remote Compiler

    The \gui {Remote Compiler} target is an interface to a compilation service at
    Forum Nokia. It provides a simple, standardized environment for building Qt
    applications and creating installation packages for Symbian, Maemo, and
    MeeGo Harmattan devices
    when you do not have the necessary tool chains and SDKs installed or they are
    not supported on the development PC. You can choose from a set of supported
    devices, such as S60 3rd Edition or S60 5th Edition devices.

    You need a Forum Nokia user account to use the Remote Compiler. You can
    create an account for free at \l{http://www.forum.nokia.com/}{Forum Nokia}.

    \note Remote Compiler is an experimental component that is installed as
    part of \QSDK.

    \list 1

        \o Select \gui {Start > \QSDK > Maintain \QSDK} to open the
        \gui {Maintain \QSDK} tool.

        \o In the \gui {Package Manager}, select \gui {Experimental >
        Remote Compiler} to install Remote Compiler.

        \o In Qt Creator, choose \gui {Tools > Options > Projects > Remote Compiler}
        to log on to Forum Nokia.

        \image remotecompiler-fn-logon.png "Remote Compiler options"

        \o Choose \gui {Projects}.

        \o Click
        \inlineimage qtcreator-qt4-addbutton.png "Add Target button"
        and select \gui {Remote Compiler} to add Remote Compiler as a target.

        \o Click \gui Add to add mobile device platforms as build configurations.

        \o Click the \gui {Target Selector} and select a build configuration.

        \o Choose \gui {Build > Build All}.

    \endlist

    The installation package is generated in the \gui {Build directory} on
    the development PC.

    For more information about Remote Compiler, choose \gui {Help > Contents >
    Remote Compiler Manual}. The document is added during the installation of
    Remote Compiler.

*/


/*!
    \contentspage index.html
    \previouspage creator-running-targets.html
    \page creator-build-settings.html
    \nextpage creator-project-qmake.html

    \title Specifying Build Settings

    Different build configurations allow you to quickly switch between
    different build settings. By default, Qt Creator creates \bold debug
    and \bold release build configurations. A debug build contains additional
    debug symbols that you need for debugging the application but that you
    can leave out from the release version. Generally, you use the debug
    configuration for testing and the release configuration for creating
    the final installation file.

    You specify build settings in the \gui Projects mode.

    \image qtcreator-projectpane.png

    To add a new build configuration, click \gui Add and select the type of
    configuration you would like to add. You can add as many build
    configurations as you need.

    To delete the build configuration currently selected, click \gui Remove.

    \section1 Editing Build Configurations

    To edit a build configuration:
    \list 1
        \o Select the build configuration you want to edit in
           \gui{Edit Build Configuration}.
        \o In the \gui {Qt version} field, select the Qt version to use for
           building project. You can add Qt versions to the list if they are
           installed on the development PC, but were not detected
           automatically. For more information, see \l{Adding Qt Versions}.
        \o In the \gui {Tool chain} field, select the tool chain required
           to build the project. The tool chains that are compatible with the
           selected Qt version are listed. You can add tool chains to the list
           if they are not automatically detected. For more information, see
           \l{Adding Tool Chains}.

        \o In the \gui {Build directory} field, specify the build directory for
           the project.
           By default, projects are built in a separate directory from the
           source directory, as \l{glossary-shadow-build}{shadow builds}.
               This keeps the files generated for each target platform separate.

               \note Shadow building is not supported by the Symbian build system.
               Also, shadow building on Windows is not supported for Maemo or
               MeeGo Harmattan.
               If you only build for one target platform, you can deselect
               the \gui{Shadow build} checkbox.
    \endlist

    \note The build configuration for the \gui{Symbian Device} target
    uses the GCCE tool chain by default. If you want to build
    for the device using RVCT, install the RVCT tool chain, and then
    select it in the \gui {Tool chain} field.

    \section1 Starting External Processes

    Qt Creator executes external processes to accomplish tasks such as building
    and running applications. To execute the processes, Qt Creator uses shell
    commands that are native to the system. It constructs the commands from
    an executable name and optional command line arguments.

    The executable name is specified in the executable fields: \gui qmake,
    \gui Make, \gui Command, or \gui Executable. It is either derived from the
    project or specified manually. When you specify executables manually, you
    can reference environment variables and Qt Creator variables. However, no
    quoting rules
    apply.

    You can specify command-line arguments in the arguments fields: \gui {Additional
    arguments}, \gui {Command arguments}, \gui {Make arguments}, or \gui Arguments.
    You can create shell command lines that can contain redirection and other
    advanced constructs. However, some more complex use cases, such as piping
    test data into the application being tested or grouping commands, are not
    supported because the value of the \gui Executable field is always placed
    first when constructing the command.

    \section2 Using Environment Variables

    You can use any environment variables as values in the fields. For a list
    of variable names, click \gui {Build Environment > Details} in the
    \gui {Build Settings}. Environment variables are referenced using the native
    syntax: $VARNAME or ${VARNAME} on Unix and %VARNAME% on Windows.

    \section2 Using Qt Creator Variables

    You can use Qt Creator variables in arguments, executable paths, and working
    directories.
    The variables take care of quoting their expansions, so you do not need to
    put them in quotes.

    The following Qt Creator variables are available:

    \list

        \o %{buildDir}

        \o %{sourceDir}

    \endlist

    \section1 Build Steps

    The build system of Qt Creator is built on qmake and make. In
    \gui{Build Steps} you can change the settings for qmake and make. Qt
   Creator runs the make command using the Qt version defined for the current
    build configuration.

    \image qtcreator-build-steps.png "Build steps"

    To override the shell command that Qt Creator constructs by default, remove
    the build step and add a custom build step that specifies another shell
    command.

    \section2 Adding Custom Build Steps

    To add custom steps to the build settings, select \gui {Add Build Step >
    Custom Process Step}.

    By default, custom steps are disabled. To activate a custom step, select
    the \gui{Enable custom process step} check-box.

    \image qtcreator-build-steps-custom.png "Custom Process Step"

    \section1 Clean Steps

    You can use the cleaning process to remove intermediate files. This process
    might help you to fix obscure issues during the process of building a
    project.

    \image qtcreator-clean-steps.png "Clean steps"

    You can define the cleaning steps for your builds in the \gui{Clean Steps}:
    \list
        \o To add a clean step using make or a custom process, click
           \gui{Add Clean Step} and select the type of step you want to add.

           By default, custom steps are disabled. To activate a custom step,
           select the \gui{Enable custom process step} check-box.
        \o To remove a clean step, click \gui{Remove Item}.
        \o To change the order of steps, click
           \inlineimage qtcreator-movestep.png
           .
    \endlist

    \section1 Build Environment

    You can specify the environment you want to use for building in the
    \bold{Build Environment} section. By default, the environment in which Qt
    Creator was started is used and modified to include the Qt version.
    Depending on the selected Qt version, Qt Creator automatically sets the
    necessary environment variables. You can edit existing environment
    variables or add, reset and unset new variables based on your project
    requirements.

    \image qtcreator-build-environment.png "Build Environment"

    \note The changes are stored in the local project specific \c{.pro.user}
    file. Therefore, they are not suitable for sharing between developers or
    development PCs. To share settings, incorporate them into the build system.
    For example, if you use qmake, make the changes in the \c{.pro} file.


    \section2 Clearing the System Environment

    To build with a clean system environment, select the \gui {Clear system
    environment} check box. Qt Creator discards the current environment, and
    populates a clean system environment with the environment variables that the
    compilers and tools need. Therefore, the environment is never totally empty,
    even after you clear it.

*/


/*!
    \contentspage index.html
    \previouspage creator-tool-chains.html
    \page creator-run-settings.html
    \nextpage creator-editor-settings.html

    \title Specifying Run Settings

    Qt Creator automatically creates run configurations for your project.
    To view and modify the settings, select \gui {Projects > Run}.

    The settings to specify depend on the type of the project: Qt project
    or Qt Quick project, and on the target for the project.

    Click \gui Add to add run settings for a project and \gui Remove to remove
    the current settings.

    \section1 Specifying Run Settings for qmake Projects

    The run configurations for qmake projects derive their executable from the parsed .pro
    files.
    For more information on how the commands are constructed, see
    \l{Starting External Processes}.

    \section2 Specifying Run Settings for Desktop Targets

    You can specify command line arguments to be passed to the executable
    and the working directory to use. The working directory defaults to
    the directory of the build result.

    For console applications, check the \gui{Run in Terminal} check box.
    If you need to run with special environment variables set up, you
    also do it in the run configuration settings.

    \image qtcreator-pprunsettings.png

    You can also create custom executable run configurations where you
    can set the executable to be run. For more information, see
    \l{Specifying a Custom Executable to Run}.

    \section2 Specifying Run Settings for Symbian Devices

    Qt Creator automatically detects Symbian devices that are connected to
    the development PC with a USB cable.
    If only one device is detected, the application is deployed to it
    and run on it. If multiple devices are connected to the PC,
    make sure that the correct device is selected in the
    \gui {Symbian Device} run settings for your project.

    You can also pass command line arguments to your application on the device.
    Press the \gui{Device info button} to get more information about the selected
    device, such as the CPU type and the running debugging agent version.

    \image qtcreator-symbian-run-settings.png "Run settings for Symbian devices"

    To use the CODA debugging agent over a WLAN connection, enter the WLAN
    address of the device and the port number to use, separated by a colon (:),
    in the \gui WLAN field. For example: 192.167.0.100:1534

    When you deploy the application for the \gui{Symbian Device} target, Qt
    Creator generates a Symbian installation system (SIS) file in the project folder
    and copies it to the device that is connected to the development PC.
    If no device is connected, you must remove the \gui {Deploy SIS Package} step,
    to create the package. Click \gui {Remove Item} to skip the step.

    \image qtcreator-remove-deploy-step.png "Removing deploy steps"

    When you are ready to publish the application on Ovi Store or some other
    channel, you must make sure that the SIS file meets the requirements for
    publishing and installing applications on Symbian devices. For more information,
    see \l{Deploying Applications to Symbian Devices}.

    \section2 Specifying Run Settings for Maemo and MeeGo Harmattan Devices

    To run an application on a Maemo or MeeGo Harmattan device, create and
    select a device configuration in the Maemo 5 or Harmattan run settings for
    your project.
    You can also pass command line arguments to your application.

    \image qtcreator-screenshot-run-settings-maemo.png "Run settings for Maemo devices"

    To run and debug applications on Maemo or MeeGo Harmattan devices, you must
    create connections
    from the development PC to the devices. Click \gui {Manage device
    configurations} to create connections. For more information, see
    \l {Configuring Connections in Qt Creator}.

    By default, Qt Creator runs the remote gdbserver daemon on the device for
    debugging. On Maemo 5, if the sysroot does not match that of the device,
    you
    can run remote GDB, instead. Select the \gui {Use remote GDB} option in
    \gui {Debugging details}. Select the \gui {Set debugger} link to specify
    settings for GDB.

    When you run the application on the \gui{Maemo5} or \gui Harmattan target,
    Qt Creator generates
    a Debian installation package in the build directory by default. You can deliver
    the installation package to users for installation on devices that are of
    the same type and run the same firmware as the connected device. For more
    information, see
    \l{Deploying Applications to Maemo or MeeGo Harmattan Devices}.

    \section1 Specifying a Custom Executable to Run

    If you use CMake or the generic project type in Qt Creator, or want
    to run a custom desktop executable, create a \gui {Custom Executable}
    run configuration for your project. For example, when working on a library,
    you can run a test application that links against the library.

    Specify the executable to run, command line arguments, working directory,
    and environment variables to use.

    \image qmldesigner-run-custom-exe.png "Run settings for custom executables"

    \section1 Specifying Run Settings for Qt Quick UI Projects

    You can specify run settings for the \gui Desktop target:

    \list

        \o In the \gui {Qt version} field, select a Qt version that has support
        for QML.

        \o In the \gui Arguments field, you can specify command line arguments
        to be passed to the executable.

        \o In the \gui {Main QML file}, select the file that \QQV will be
        started with.

        \o In the \gui Debugger group, select the languages to debug:
        \gui{C++} and \gui QML. \gui {Debug port} is the port to access \QQV.
        You can use any free port in the registered port range.
        For more information, see \l{Debugging Qt Quick Projects}.

    \endlist

    \note Opening a socket at a well-known port presents a security risk. Anyone
    on the Internet could connect to the application that you are debugging and
    execute any JavaScript functions. Therefore, you must make sure that the port
    is properly protected by a firewall.

    \image qmldesigner-run-settings.png "Run settings for Qt Quick UI projects"


*/


/*!
    \contentspage index.html
    \previouspage creator-deployment-symbian.html
    \page creator-deployment-maemo.html
    \nextpage creator-publishing-to-maemo-extras.html

    \title Deploying Applications to Maemo or MeeGo Harmattan Devices

    You can specify settings for deploying applications to Maemo 5 and MeeGo
    Harmattan devices in the
    project .pro file. You can view the settings in the \gui {Run Settings}.

    \image qtcreator-maemo-deployment.png "Deploy to device"

    The files to be installed are listed in the
    \gui {Deploy to Device} step, the \gui {Files to install for subproject}
    field. The
    \gui {Local File Path} field displays the location of the file on the development
    PC. The \gui {Remote Directory} field displays the folder where the file is installed on
    the device.
    Text in red color indicates that the information is missing. Select the
    text to edit it and add the missing information.

    You can use desktop files to display icons on the home screen of the
    device. To add desktop files to the project file, select \gui {Add Desktop
    File}. To specify the icon file to display, select \gui {Add Launcher
    Icon...}. To remove desktop files and icons, delete the definitions from
    the project file.

    If you develop your own libraries, Qt Creator needs to be able to find
    them when you compile projects depending on them. When you install MADDE,
    an instance of the device file
    system, called sysroot, is installed to the development PC. Libraries are copied to
    sysroot if the \gui {Also deploy to sysroot} check box is selected.

    \section1 Creating Debian Installation Packages

    When you run the application on the \gui{Maemo5} or \gui Harmattan target,
    Qt Creator generates
    a Debian installation package in the build directory by default. You can deliver
    the installation package to users for installation on devices that are of
    the same type and run the same firmware as the connected device.

    \image qtcreator-maemo-deb-package.png "Create installation package"

    The name of the installation package is displayed in the \gui {Package name}
    field in the \gui {Create Package} step. You can change the version number
    in the \gui {Package version} field.

    You can specify information that users see on a delivery channel, such as
    Ovi Store or Maemo.org. You can specify a short description of the
    application, package
    name, and application icon.

    The Debian control file contains an application icon in encoded form. To add the
    application icon to the file, select it in the \gui {Icon to be displayed
    in Package Manager} field.
    For more information about icon files and adding them manually, see
    \l{ http://wiki.maemo.org/Packaging#Displaying_an_icon_in_the_Application_Manager_next_to_your_package}{Displaying an icon in the Application Manager next to your package}.

    \note Qt Creator automates this process for you.

    Qt Creator provides templates for a set of files that must be included
    in Debian packages. When you create a \gui Maemo5 or \gui Harmattan target
    for a project, Qt Creator
    asks whether packaging files are to be added to the project and to version
    control. If you plan to edit the packaging files, add them to version
    control.

    To edit the files, select a file in \gui {Adapt Debian
    file} and click \gui Edit. The file opens in the text editor.

*/


/*!
    \contentspage index.html
    \previouspage creator-deployment-maemo.html
    \page creator-publishing-to-maemo-extras.html
    \nextpage creator-publish-ovi.html

    \title Publishing Maemo Applications to Extras-devel

    Extras is the primary repository for Maemo applications where most
    community software can be found. You can browse the applications available
    in Extras at \l{http://maemo.org/downloads/Maemo5/}{Maemo Downloads}.

    You can publish both free and commercial applications to Extras. Free
    applications must be open source and pass through a QA process.
    Commercial applications are usually closed, binary only, and the publisher
    is responsible for assuring their quality and security.

    You can upload free applications as Debian packages to
    \l{http://wiki.maemo.org/Extras-devel}{Extras-devel} at Maemo.org to share
    new updates to your application and to start the community QA process.
    You need a \l{https://garage.maemo.org/}{Garage} account for the uploads,
    but the package itself does not need to be hosted in the Garage.

    You can use the \gui {Publish for Fremantle Extras-devel Free Repository}
    wizard to create a source archive and, optionally, upload it to a build
    server for compiling and packaging. The package is then moved to the
    Extras-devel repository. From there on, you must follow the standard
    Maemo processes to get the application published to Extras.

    The wizard checks that the package contains all the information that is
    required to publish applications on Extras: package description and
    Package Manager icon. For more information about entering this information,
    see \l{Creating Debian Installation Packages}.

    To use the publishing wizard:

    \list 1

        \o  Select the \gui {Maemo5} build target for your project.

        \o  Choose \gui {Build > Publish Project}.

        \o  Select \gui {Publish for Fremantle Extras-devel Free Repository},
            and then select \gui {Start Wizard}.

        \o  Select the Qt version and device type to build against and click
            \gui Next.

            To create a source archive without uploading it to the build
            server, select the \gui {Only create source package, do not upload}
            check box.

        \o  In the \gui {Garage account name} field, enter your login name, or
            select \gui {Get an account} to create a new account.

            \image qtcreator-publish-maemo-extras.png "Upload Settings dialog"

            You can also select \gui {Request upload rights} to use the Maemo
            Extras Assistant to validate your Garage account.

        \o  Select \gui Commit to publish the application.

    \endlist

*/


/*!
    \contentspage index.html
    \previouspage creator-troubleshooting-debugging.html
    \page creator-deployment.html
    \nextpage creator-deployment-symbian.html

    \title Deploying Applications to Mobile Devices

    Deploy configurations in the \gui Project mode \gui {Run Settings} handle
    the packaging of the application as an executable and copying it to a
    location you want to run the executable at. The files can be copied to a location
    in  the file system of the development PC or a mobile device.

    When you are ready to publish the application on Ovi Store or some other
    channel, you must make sure that the installation file meets the requirements for
    publishing and installing applications to Symbian or Maemo devices. The following
    sections describe the steps that you have to take to create installation packages
    for Symbian, Maemo, or MeeGo Harmattan devices and for publishing on Ovi
    Store:

    \list
        \o \l{Deploying Applications to Symbian Devices}
        \o \l{Deploying Applications to Maemo or MeeGo Harmattan Devices}
        \o \l{Publishing Maemo Applications to Extras-devel}
        \o \l{Publishing Applications to Ovi Store}
        \o \l{Building with Remote Compiler}
    \endlist

*/


/*!
    \contentspage index.html
    \previouspage creator-deployment.html
    \page creator-deployment-symbian.html
    \nextpage creator-deployment-maemo.html

    \title Deploying Applications to Symbian Devices

    This section describes how to create installation packages that meet the
    requirements for installing applications to Symbian devices.

    \section1 Creating SIS Files

    When you deploy the application for the \gui{Symbian Device} target, Qt
    Creator automatically generates a Symbian installation system (SIS) file
    in the project folder. You can deliver the installation file to users for
    installation on Symbian devices.

    The name of the installation file is displayed in the \gui {Installation file}
    field in the \gui {Run Settings}. In the \gui {Installation drive} field, select the drive on the device
    to install the application to. To suppress notifications on the device during the
    installation, select the \gui {Silent installation} check box. If the silent
    installation fails, Qt Creator attempts installation again, this time displaying
    notifications and error messages.

    To create a SIS package without copying it to the device (for example, to submit it
    to \e {Application Signing Services for Ovi Store} or \e {Symbian Signed}),
    create a deploy configuration that contains only the
    \gui {Create SIS Package} step.

    \image qtcreator-run-settings-create.png "Create SIS Package step"


    \section1 Signing SIS Files

    Only installation files signed with a certificate and private key are
    allowed to be installed onto Symbian devices. By default, Qt Creator
    self-signs the installation file. This self-signing allows you to install
    the application on a mobile  device but places limits on what you can do
    with the installation file, including:
    \list
       \o  Self-signed applications cannot access the more sensitive
           \l{Capabilities and Signing}{capabilities} of the mobile device.
       \o  Security warnings will be displayed when you install the self-signed
           application on a mobile device.
       \o  Self-signed applications cannot be published to Ovi
           Store.
    \endlist

    To get around these limitations, you need to go through the Symbian Signed
    or Application Signing Services for Ovi Store. The Symbian Signed organisation
    manages a public key
    infrastructure to provide public authentication of the information in the
    application signing certificates. Their security partner can validate your
    certificate and give you a Publisher ID. Then, when you sign an
    application, other people can be confident that the information in your
    certificate is correct and that the application does actually come from you.

    Application Signing Services for Ovi Store is a variant of the Symbian
    Signed certification provided by Ovi
    Publishing. It is limited to the Basic and System capability sets
    (Express Signing). Participants can submit an unsigned SIS file to Ovi
    Publishing for signing. For more information about how
    to participate, see
    \l {http://wiki.forum.nokia.com/index.php/Guide_to_Publishing_Qt_Applications_to_the_Ovi_Store}{Guide to Publishing Qt Applications to the Ovi Store}.

    There are also options that do not require you to get a Publisher ID. For
    more detail about how the Symbian Signed process works, see
    \l{https://www.symbiansigned.com}{Symbian Signed}.

    When you have your own certificate and private key, you can specify them in
    the \gui{Create SIS Package} step in the \gui {Run Settings}.

    \image qtcreator-qt4-symbian-signing.png


    If your private key is protected by a passphrase, Qt Creator asks you for the
    passphrase when the package is signed and offers to store it. However, storing
    passphrases in Qt Creator presents a security risk. To make Qt Creator forget
    all saved passphrases, click \gui {Reset Passphrases}.

    \section2 Capabilities and Signing

    Capabilities allow the Symbian platform to control access by applications to
    the functionality provided by the platform APIs. Access to capabilities is
    determined by the device configuration and how the application has been signed.

    Symbian Signed offers the following signing options depending on the
    capabilities that the application accesses:

    \list

        \o \bold{Express signed} for applications that access only user and system
        capabilities.

        \o \bold{Certified signed} for applications that access also restricted or
        device manufacturer capabilities.

        \note You need to request the rights to access device manufacturer
        capabilities from the manufacturer.

    \endlist

    For more information about how to choose the appropriate signing option and
    how you can check which capabilities you need, see
    \l{https://www.symbiansigned.com}{Symbian Signed}
    and
    \l{http://doc.qt.nokia.com/4.7/platform-notes-symbian.html#required-capabilities}{Required Capabilities for Qt Applications}.

    For more information on how to define capabilities for a project, see
    \l{http://doc.qt.nokia.com/4.7/qmake-platform-notes.html#capabilities}{Capabilities}.

    \note In Qt 4.7.1 and later, if you select the \gui {Self-signed certificate}
    option, the SIS generation process checks that the package can be self-signed.
    If problems are found, it attempts to fix the package. If fixes cannot be made,
    a message appears in the \gui {Compile Output} view.

    The following modifications can be made:

    \list

        \o Package UID is changed to an UID from the unprotected range (if it was
        from the protected range).

        \o Vendor ID is set to zero on all binaries included in the package file.

        \o All restricted and device manufacturer capabilities are removed from all
        libraries included in the package file.

    \endlist

    The application UID or capabilities used in executables (.exe) cannot be changed,
    because that would break the application. If the executables use protected UIDs
    or restricted or device manufacturer capabilities, signing fails and an error
    message appears in the \gui {Compile Output} view.

    \section1 Creating Smart Installer for Symbian Packages

    To deploy Qt applications on Symbian devices, you must install the software that Qt applications
    require, typically Qt, QtWebkit, and Open C. Nokia Smart Installer for Symbian makes it easier
    for users to install Qt applications to Symbian phones by checking whether the device contains
    the necessary software and by installing the missing pieces.

    For this to work, the Nokia Smart Installer must be packaged with the Qt application. The
    application SIS file must first be Symbian Signed or signed by the Application
    Signing Services for Ovi Store. The capabilities used in the applications
    determine, which signing option must be selected. The wrapper package must be signed using
    either the same option or a more extensive option than the application SIS.

    \note If you use the Application Signing Services for Ovi Store, you can submit an unsigned
    wrapper package to Ovi Publishing. For more information, see
    \l{Publishing Applications to Ovi Store}.

    You can either install the Nokia Smart Installer for Symbian as part of
    the \QSDK, or download and install it from the
    \l{http://wiki.forum.nokia.com/index.php/Nokia_Smart_Installer_for_Symbian}{Nokia Smart Installer for Symbian}
    wiki.

    To package Nokia Smart Installer with the application, select the \gui {Create Smart Installer
    package} check box. This ensures that up-to-date and appropriate versions of Qt and its
    dependencies are installed on devices. Further, it reduces the file size of the application you
    publish, because you do not have to deliver the required libraries.

    Nokia has reserved the following UIDs to be used with Nokia Smart Installer for Symbian:

    \list

        \o 0xA000D7CE for self-signed applications
        \o 0x2002CCCF for Ovi Store or Symbian Signed packages

    \endlist

    \section2 Creating Self-signed Smart Installer Packages

    To create a self-signed Nokia Smart Installer for Symbian wrapped .sis file,
    you must use an UID from the unprotected UID range, provided by Symbian Signed
    and the wrapper package UID value 0xA000D7CE. If you used the Qt Creator project
    wizard to create the project, this wrapper package UID is used by default.

    \list 1

        \o Make sure that the source directory is clean. For example, if you use git,
        enter the following command:

        \c {git clean -dfx}

        \o Click \gui Projects to edit the \gui {Build Settings} for the
        \gui {Symbian Device} target.

        \o Select the \gui Release configuration.

        \o Open the \gui {Run Settings}.

        \o In the \gui {Create SIS Package} step, select \gui {Self-signed certificate}.

        \o In the \gui {Deploy SIS Package} step, click \gui {Remove Item} to
        skip the step of copying the SIS file to a device. The SIS file is created
        in the project folder.

        \image qtcreator-remove-deploy-step.png "Removing deploy steps"

        \o To package Nokia Smart Installer for Symbian with the application, select
        the \gui {Create Smart Installer package} check box.

        \o Edit the project .pro file to use the correct UIDs for the application and
        the wrapper package, as illustrated by the following code snippet:

       \code
       symbian {
            TARGET.UID3 = 0xE4DE5D27
            DEPLOYMENT.installer_header=0xA000D7CE

            vendorinfo = \
            "%{\"CustomVendor-EN\"}" \
            ":\"CustomVendor\""

            my_deployment.pkg_prerules = vendorinfo
            DEPLOYMENT += my_deployment
        }
        \endcode

        \o Choose \gui {Build > Run Project}.

    \endlist

    Qt Creator automatically generates a wrapper package in the project folder.

    \section2 Creating Symbian Signed Smart Installer Packages

    If the application uses functions that require advanced capabilities (AllFiles,
    DRM, TCB, CommDD, DiskAdmin, NetworkControl, MultimediaDD), you must use the
    standard Symbian Signed process to have the application Symbian Signed. Depending
    on the capabilities used, you may use either the Express Signed or the Certified
    Signed path, or the manufacturer-specific channel (for AllFiles, DRM, and TCB).

    \list 1

        \o Make sure that the source directory is clean. For example, if you use git,
        enter the following command:

        \c {git clean -dfx}

        \o Click \gui Projects to edit the \gui {Build Settings} for the
        \gui {Symbian Device} target.

        \o Select the \gui Release configuration.

        \o Open the \gui {Run Settings}.

        \o In the \gui {Create SIS Package} step, specify the developer certificate
        and key in the \gui {Custom certificate} and \gui {Key file} fields.

        \o In the \gui {Deploy SIS Package} step, click \gui {Remove Item} to
        skip the step of copying the SIS file to a device. The SIS file is created
        in the project folder.

        \o Edit the project .pro file to use the correct UIDs and vendor information
        for the application, as illustrated by the following code snippet:

       \code
       symbian {
            TARGET.UID3 = 0x2000D7D1
            DEPLOYMENT.installer_header=0x2002CCCF

            vendorinfo = \
            "%{\"CustomVendor-EN\"}" \
            ":\"CustomVendor\""

            my_deployment.pkg_prerules = vendorinfo
            DEPLOYMENT += my_deployment
        }
        \endcode

        \o Choose \gui {Build > Run Project}.

        \o Submit the created .sis file to Symbian Signed for certification.

        \note Ensure that your application complies with the Symbian Signed
        Test Criteria before submitting the file for certification. Also, if the file is
        intended for Ovi Store publishing, verify that the application complies with Ovi
        Store publishing requirements.

        \o After receiving the .sis file from Symbian Signed, copy it over the old
        application.sis.

        \note The instructions below assume that you have installed \QSDK.

        \o To package Nokia Smart Installer for Symbian with the application, choose
        \gui {Start > Qt SDK > Symbian > Qt for Symbian Command Prompt}
        to open the Qt command line environment.

        \o Change to the project directory. For example:

        \c{cd C:\Sources\Application}

        \o To create a Smart Installer wrapper package, enter the following
        command:

        \c {C:\Sources\Application> make ok_installer_sis QT_SIS_CERTIFICATE=publisherid.cer QT_SIS_KEY=publisherid.key}

        \o Submit the created wrapped .sis file, application_installer.sis, to
        Symbian Signed. Express Signed is a suitable signing option for the wrapper
        package. The capabilities used in the application do not play a role here,
        because the wrapper package is already signed.

    \endlist

    Qt Creator automatically generates a wrapper package in the project folder.

    \note Ensure that your application complies with the requirements before submitting
    the file to Ovi Store.

    For more information about the qmake DEPLOYMENT variable, see
    \l{http://doc.qt.nokia.com/4.7/qmake-variable-reference.html#deployment}{qmake Variable Reference}.

    For more information about the Nokia Smart Installer, see the
    \l{http://doc.qt.nokia.com/smart-installer/index.html}{Nokia Smart Installer for Symbian Manual}.

    Note: Nokia Smart Installer for Symbian is only available on Windows.

    \section1 Application UID

    A UID is a globally unique identifier that is used to
    uniquely identify, for example, an object or file type. In Symbian development,
    objects are identified by compound identifiers that are constructed from three
    UIDs, namely UID1, UID2, and UID3. UID1 and UID2 specify the category of an
    object, whereas UID3 identifies a particular object, such as an application.

    When you create a \gui {Mobile Qt Application}, Qt Creator adds a UID3 suitable for
    development and debugging automatically to the application .pro file. However, to
    distribute your application and get it Symbian Signed, you must apply for a UID
    from Symbian Signed, which manages the allocation of UIDs. You can request UIDs either one
    at a time or as preallocated blocks on the \l{https://www.symbiansigned.com/app/page}{Symbian Signed}
    web site.

    If you use the Ovi Signed process, Ovi Publisher Support allocates the UID for you.

    Replace the testing UID with the distribution UID in the .pro file before you
    build the final installation package. For more information, see
    \l{http://doc.qt.nokia.com/4.7/qmake-platform-notes.html#unique-identifiers}{Unique Identifiers}.

*/


/*!
    \contentspage index.html
    \previouspage creator-publishing-to-maemo-extras.html
    \page creator-publish-ovi.html
    \nextpage creator-remote-compiler.html

    \title Publishing Applications to Ovi Store

    Ovi Store is the global content market of Nokia, which reaches millions of
    people worldwide. Consumers can access Ovi Store through either of these
    platforms:

    \list

        \o  Ovi Store applications on mobile devices

        \o  Web browsers on desktop computers, laptops, netbooks, and tablets

    \endlist

    Consumers have access to a wide selection of content and can download
    content in a few easy clicks.

    The process and requirements to publish Qt applications to Ovi Store are
    described in the
    \l {http://wiki.forum.nokia.com/index.php/Guide_to_Publishing_Qt_Applications_to_the_Ovi_Store}{Guide to Publishing Qt Applications to the Ovi Store} wiki.

    This section describes how to
    generate installation packages that
    you can publish to Ovi Store.

    \section1 Publishing Qt Content for Symbian Devices

    You can use the \e {Application Signing Services for Ovi Store} to get your
    application Express Signed for
    free by Nokia. Make sure to use the \l{Application UID}{application UID} that you
    receive from Ovi Publisher Support.

    The \gui {Publish Qt Symbian Applications to Ovi Store} wizard allows you
    to check that your application can be
    published on Ovi Store. It checks that the application UID, vendor name,
    and the capabilities used meet the Ovi Publishing criteria.

    If you use Symbian Signed UIDs or the application uses functions that
    require advanced
    \l{Capabilities and Signing}{capabilities}, you must
    use the standard Symbian Signed process to have the application Symbian Signed
    (using the Certified Signed path or the manufacturer-specific channel).
    For more information, see \l{Deploying Applications to Symbian Devices}.

    To use the publishing wizard:

    \list 1

        \o Select \gui Projects to select the Qt version to build the
        application. For more information, see \l{Supported Configurations}.

        \o Select the \gui {Symbian Device} build target for your project.

        \o Choose \gui {Build > Publish Project}.

        \o Select \gui {Publish Qt Symbian Applications to Ovi Store}, and then
        select \gui {Start Wizard}.

        \o Select the Qt version and device type to build against and click
        \gui Next. We recommend that you select a release configuration.

        \o The wizard checks the information in the project file against the
        Ovi Publishing criteria and indicates possible problems. You can fix
        some of the problems in the wizard.

        \image qtcreator-publishing-wizard-symbian.png "Project File Checks dialog"

        \o Select \gui Commit to save changes and create the .sis file. The
        .sis file is packaged with Nokia Smart Installer for Symbian.

        \o Choose \gui {Open Containing Folder} to open the folder where the
        .sis file was created.

        \o Submit the created .sis file to Ovi Publishing as a Qt Content item.

        \note You cannot use this .sis file for testing.

    \endlist

    \note After you change the application UID, you must use the developer
    certificate-key pair that you receive from Ovi Publisher Support for testing
    the application on devices. The following error message is displayed on the
    device if you use UIDs from the trusted range (0x2xxxxxxx) in a self-signed
    application: \gui {Unable to install a trusted application from a trusted
    supplier.} For more
    information, see \l{http://wiki.forum.nokia.com/index.php/UID}{UID}.

    If you try to use more capabilites than the certificate permits, the
    following error message is displayed on the device: \gui {Requested
    application access not granted.} For example, if you try to install a
    self-signed application that uses a system capability.

    \section2 Supported Configurations

    When you select the Qt version to build the application with, consider
    which version provides the application with the widest support on different
    Symbian platforms. The binary compatibility promise of Qt and Symbian means
    that applications that are built against Qt 4.6.3 also run on Qt 4.7.3.
    Similarly, applications that are supported on Symbian^1 are also supported
    on Symbian^3. However, dependencies, such as QML or Qt Mobility API
    versions might restrict the choice of Qt versions that you have.

    In general, if you use only Qt widgets and APIs in the application, you
    can use \gui {Qt 4.6.3 for Symbian^1} to build it.
    The application is supported on both Symbian^1 and Symbian^3 devices.

    If you use QML in the application, you can use \gui {Qt 4.7.3 for
    Symbian^1} to build it. The application is supported on both Symbian^1 and
    Symbian^3 devices.

    If you use native Symbian APIs, you must check that they are available on
    the target devices. For more information about the API differences between
    Symbian^1 (S60 5th Edition) and Symbian^3, see the \bold {Symbian
    Reference Documentation for Qt}, which is delivered together with \QSDK
    and which you can view in the \gui Help mode.

    The following table summarizes the supported configurations for each Qt
    version available in Qt Creator build settings:

    \table
        \header
            \i  Qt Version
            \i  QML
            \i  Qt Mobility Version
            \i  Native Symbian C++ APIs
            \i  Open GL
        \row
            \i  Qt 4.6.3 for S60 3rd Edition
            \i  No
            \i  1.0.2
            \i  No
            \i  No
        \row
            \i  Qt 4.6.3 for Symbian^1 (S60 5th Edition)
            \i  No
            \i  1.0.2
            \i  No
            \i  No
        \row
            \i  Qt 4.6.3 for Symbian^3
            \i  No
            \i  1.0.2
            \i  Yes
            \i  No
        \row
            \i  Qt 4.7.3 for Symbian^1
            \i  Yes
            \i  1.1.3
            \i  No
            \i  No
        \row
            \i  Qt 4.7.3 for Symbian^3
            \i  Yes
            \i  1.1.3
            \i  Yes
            \i  Yes
    \endtable

    \section1 Publishing Qt Content for Maemo Devices

    The applications that you publish on Ovi Store, must meet the testing criteria
    listed in
    \l{http://www.forum.nokia.com/info/sw.nokia.com/id/9cd1eb18-821b-4228-a0a3-36b049c5d608/Maemo_5_Application_OVI_Store_Entry_Requirements.pdf.html}
    {Maemo 5 Applications: Ovi Store Entry Requirements}.

    Make sure that your application passes the following most commonly
    failed test cases:

    \list

        \o Package filename must include the application name and version
        number using three digits. For example: myapplication_1_0_1.deb

        \o Application files must be installed to the opt folder on the ext3
        partition.

        \o Debian packages must be given the category user/hidden.

        \o Application cannot crash or hang during use.

        \o The application must handle different memory situations correctly.

    \endlist

    You set the application name and installation folder in the
    \gui {Run Settings} for the project. For more information, see
    \l{Deploying Applications to Maemo or MeeGo Harmattan Devices}. Qt Creator
    specifies the correct
    category settings by default when it creates the Debian directory and
    the necessary files.

    You can test the application on Qt Simulator and Maemo emulator to make
    sure that it does not crash or hang and to check how it handles different
    memory situations. Before you submit the application to Ovi Publishing, you
    must also fully test it on a Maemo device.

    \section1 Publishing Qt Content for MeeGo Harmattan Devices

    You cannot publish applications that are built with the beta version of the
    MeeGo Harmattan tool chain to Ovi Store.

*/

/*!
    \contentspage index.html
    \previouspage creator-run-settings.html
    \page creator-editor-settings.html
    \nextpage creator-build-dependencies.html

    \title Specifying Editor Settings

    You can configure the code editor according to your needs. You can specify
    editor behavior either globally for all projects or separately for each
    project. To specify global editor behavior, select \gui {Tools > Options...
    > Text Editor > Behavior}.

    To configure the editor behavior for the current project, deselect the
    \gui {Use global settings} check box in the \gui {Editor Settings} for the
    project. For more information about the settings, see:

    \list

        \o \l{Indenting Code}

        \o \l{File Encoding}

        \o \l{Moving to Symbol Definition or Declaration}

        \o \l{Configuring Fonts}

    \endlist

    \image qtcreator-editor-settings.png "Editor Settings view"

*/


/*!
    \contentspage index.html
    \previouspage creator-editor-settings.html
    \page creator-build-dependencies.html
    \nextpage creator-debugging.html

    \title Specifying Dependencies

    If you have multiple projects loaded in a session, you can define the
    order in which they are built. For example, if project A depends on project
    B, project B must be built first.

    \note The build order is stored as a property of a session, not a project.
    You must open the session for these settings to take effect. For more
    information, see \l{Managing Sessions}.

    \image qtcreator-build-dependencies.png "Dependencies view"

    To define the build order of projects within a session:
    \list 1
        \o In \gui Projects, select a project.
        \o Click \gui Dependencies.
        \o Select projects that must be built before the current project is
        built.
    \endlist

    Qt Creator calculates the build order based on the dependencies that you
    specify for the projects loaded in the session.

    \note You cannot use this view to specify subprojects for projects.
    For more information on how to add subprojects, see \l{Adding Subprojects
    to Projects}.

*/


/*!
    \contentspage index.html
    \previouspage creator-quick-tour.html
    \page creator-getting-started.html
    \nextpage creator-build-example-application.html

    \title Getting Started

    This section contains examples that illustrate how to use Qt Creator
    to create, build, and run simple
    applications:

    \list
        \o \l{Building and Running an Example Application}
        \o \l{Creating a Qt Widget Based Application}
        \o \l{Creating a Mobile Application with Qt SDK}
        \o \l{Creating a Qt Quick Application}
    \endlist

*/


/*!
    \contentspage index.html
    \previouspage creator-writing-program.html
    \page creator-mobile-example.html
    \nextpage creator-qml-application.html

    \title Creating a Mobile Application with Qt SDK

    \note To complete this tutorial, you must install \QSDK.
    The installation program installs and configures the necessary tool chains
    for mobile application development.

    This tutorial describes how to use Qt Creator to create a small Qt
    application, Battery Indicator, that uses the System Information
    Mobility API to fetch battery information from the device.

    \image qtcreator-batteryindicator-screenshot.png

    \section1 Creating the Battery Indicator Project

    \note Create the project with the \gui{Help} mode active so that you can follow
    these instructions while you work.

    \list 1

        \o Select \gui{File > New File or Project > Qt Widget Project > Mobile
        Qt
        Application > Choose}.

        \image qtcreator-new-mobile-project.png "New File or Project dialog"

        The \gui{Introduction and Project Location} dialog opens.

        \image qtcreator-mobile-intro-and-location.png "Introduction and Project Location dialog"

        \o In the \gui{Name} field, type \bold {BatteryIndicator}.

        \o In the \gui {Create in} field, enter the path for the project files. For example,
        \c {C:\Qt\examples}, and then click \gui{Next}.

        The \gui{Target Setup} dialog opens.

        \image qtcreator-mobile-project-qt-versions.png "Target Setup dialog"

        \o Select \gui {Symbian Device}, \gui {Maemo5}, \gui Harmattan, and
        \gui {Qt Simulator} targets,
        and click \gui{Next}.

        \note Targets are listed if you installed the appropriate development
        environment, for example, as part of the \QSDK. You can add targets
        later in the \gui Projects mode.

        The \gui {Mobile Options} dialog opens.

        \image qtcreator-mobile-project-app-options.png "Mobile Options dialog"

        \o In the \gui {Orientation behavior} field, determine how the application
        behaves when the orientation of the device display rotates between portrait
        and landscape, and then click \gui{Next}.

        \note This dialog opens only if you select \gui Maemo5, \gui Harmattan,
        or
        \gui {Symbian Device} target in the \gui {Target Setup} dialog.

        The \gui {Symbian Specific} dialog opens.

        \image qtcreator-mobile-project-symbian-options.png "Symbian Specific dialog"

        \note Qt Creator contains a default program icon and generates an
        \l{Application UID}, for testing the application on a device. You only
        need to change the icon and UID if you deliver the application for public use.

        \o Click \gui Next.

        The \gui {Maemo Specific} dialog opens.

        \image qtcreator-mobile-project-maemo-options.png "Maemo Specific dialog"

        \o In the \gui {Application icon (64x64)} field, select the application
         icon to use on Maemo 5 or Harmattan targets, or click \gui Next to use
         the default icon.

        The \gui{Project Management} dialog opens.

        \image qtcreator-mobile-project-summary.png "Project Management dialog"

        \o Review the project settings, and click \gui{Finish} to create the project.

    \endlist

    The BatteryIndicator project now contains the following files:

    \list

        \o BatteryIndicator.pro
        \o main.cpp
        \o BatteryIndicator.svg
        \o BatteryIndicator.png
        \o BatteryIndicator.desktop
        \o deployment.pri
        \o mainwindow.cpp
        \o mainwindow.ui
        \o mainwindow.h
        \o templates for Debian deployment files

    \endlist

    \image qtcreator-mobile-project-contents.png "Project contents"

    The files come with the necessary boiler plate code that you must
    modify, as described in the following sections.

    \section1 Declaring the Qt Mobility API

    To use the Qt Mobility APIs or develop applications for Symbian
    devices, you must modify the .pro file to declare the Qt Mobility APIs
    that you use.

    This example uses the System Info API, so you must declare it, as
    illustrated by the following code snippet:

    \code

    CONFIG += mobility
    MOBILITY = systeminfo

    \endcode

    Each Mobility API has its corresponding value that you have to add
    as a value of MOBILITY to use the API. For a list of the APIs and the
    corresponding values that you can assign to MOBILITY, see the
    \l {http://doc.qt.nokia.com/qtmobility/quickstart.html}{Quickstart Example}.

    \section1 Designing the User Interface

    \list 1

        \o In the \gui{Editor} mode, double-click the mainwindow.ui
        file in the \gui{Projects} view to launch the integrated \QD.

        \o Drag and drop a \gui{Progress Bar} (\l{http://doc.qt.nokia.com/4.7/qprogressbar.html}{QProgressBar})
        widget to the form.

        \image qtcreator-mobile-project-widgets.png "Adding widgets to the UI"

        \o In the \gui Properties pane, change the \gui objectName to
        \bold batteryLevelBar.

        \o Right-click the \gui MainWindow object and select
        \gui {Lay Out > Lay Out Horizontally} to ensure that the battery
        indicator widget size is adjusted correctly on Maemo devices.

    \endlist

    \section1 Completing the Header File

    The mainwindow.h file contains some of the necessary #includes, a
    constructor, a destructor, and the \c{Ui} object. You must include
    the System Info header file, add a shortcut to the mobility name
    space, and add a private function to update the battery level value in
    the indicator when the battery power level changes.

    \list 1

        \o In the \gui{Projects} view, double-click the \c{mainwindow.h} file
        to open it for editing.

        \o Include the System Device Info header file, as illustrated by the following
        code snippet:

        \snippet examples/batteryindicator/mainwindow.h 1

        \o Add a shortcut to the mobility name space, as illustrated by the
        following code snippet:

        \snippet examples/batteryindicator/mainwindow.h 2

        \o Declare a private function in the \c{private} section, after the
        \c{Ui::MainWindow} function, as illustrated by the following code
        snippet:

        \snippet examples/batteryindicator/mainwindow.h 3

    \endlist

    \section1 Completing the Source File

    Now that the header file is complete, move on to the source file,
    mainwindow.cpp.

    \list 1

        \o In the \gui{Projects} view, double-click the mainwindow.cpp file
        to open it for editing.

        \o Create a QSystemDeviceInfo object and set its value. Then connect the signal
        that indicates that battery level changed to the \c setValue
        slot of the progress bar. This is illustrated by the following code snippet:

        \snippet examples/batteryindicator/mainwindow.cpp 1

        \o Use the constructor to set initial values and make sure that the
         created object is in a defined state, as illustrated by the following
         code snippet:

         \snippet examples/batteryindicator/mainwindow.cpp 2

    \endlist

    \section1 Compiling and Running Your Program

    Now that you have all the necessary code, select \gui {Qt Simulator}
    as the target and click the
    \inlineimage qtcreator-run.png
    button to build your program and run it in the Qt Simulator.

    In Qt Simulator, run the runOutOfBattery.qs example script
    to see the value change in the Battery Indicator application.
    Select \gui {Scripting > examples > runOutOfBattery.qs > Run}.

    \image qtcreator-mobile-simulated.png "Mobile example in Qt Simulator"

    \section1 Testing on a Symbian Device

    You also need to test the application on real devices. Before you can
    start testing on Symbian devices, you must connect them to the development
    PC by using a USB cable and install the necessary software on them.

    \list 1

        \o Install Qt libraries, Qt mobile libraries, and a
        debugging agent on the device. For more information,
        see \l{Connecting Symbian Devices}.

        \o Start the debugging agent, App TRK or CODA, on the device.

        \o Click the \gui {Target Selector} and select \gui {Symbian Device}.

        \o Click \gui Run to build the application for the Symbian device.

    \endlist

    \section1 Testing on the Maemo or MeeGo Harmattan Emulator

    The Maemo 5 (Fremantle) and MeeGo Harmattan emulator are installed as part
    of the \QSDK. After they are installed, you can start them from Qt Creator.

    The Maemo emulator emulates the Nokia N900 device environment. You can test
    applications in conditions practically identical to running the application
    on a Nokia N900 device with the software update release 1.3 (V20.2010.36-2).

    The MeeGo Harmattan emulator emulates the Nokia N950 device environment.

    For more information, see \l{Using Maemo or MeeGo Harmattan Emulator}.

*/

/*!
    \contentspage index.html
    \previouspage creator-getting-started.html
    \page creator-build-example-application.html
    \nextpage creator-writing-program.html

    \title Building and Running an Example Application

    You can test that your installation is successful by opening an existing
    example application project.

    \list 1

        \o On the \gui Welcome page, select \gui {Choose an Example...}
        in the \gui {Explore Qt Quick Examples} field, and then select
        \gui {Toys > Clocks}.

        \image qtcreator-gs-build-example-open.png "Selecting an example"

        \o Select targets for the project. Select at least Qt Simulator
        and one of the mobile targets, Symbian Device, Maemo 5, or Harmattan,
        depending on
        the device you develop for.

        \image qtcreator-gs-build-example-targets.png "Selecting targets"

        \note You can add targets later in the \gui Projects mode.

        \o To test the application in Qt Simulator, click the \gui {Target
        Selector} and select \gui {Qt Simulator}.

        \image {qtcreator-gs-build-example-select-qs.png} "Selecting Qt Simulator as target"

        \o Click
        \inlineimage{qtcreator-run.png}
        to build the application and run it in Qt Simulator.

        \o To see the compilation progress, press \key{Alt+4} to open the
        \gui {Compile Output} pane.

        The \gui Build progress bar on the toolbar turns green when the project
        is successfully built. The application opens in Qt Simulator.

        \image {qt-simulator.png} "Qt Simulator"

        \o Change the settings in the
        \gui View pane. For example, rotate the device by clicking the
        \gui {Orientation} buttons or choose from the various Symbian and Maemo
        configurations in the \gui {Device} field. You can also simulate various
        mobile functions and create your own scripts.

        \o To test the application on a Symbian device, install Qt libraries
        and a debugging agent on the device. For more information,
        see \l{Connecting Symbian Devices}.

        \o Click the \gui {Target Selector} and select \gui {Symbian Device}.

        \o Click \gui Run to build the application and run it on the Symbian device.

    \endlist

*/


/*!
    \contentspage index.html
    \previouspage creator-mobile-example.html
    \page creator-qml-application.html
    \nextpage creator-project-managing.html

    \title Creating a Qt Quick Application

    \note To complete this tutorial, you must have Qt 4.7 or later installed.

    This tutorial uses basic elements and illustrates basic concepts of
    \l {http://doc.qt.nokia.com/4.7/qtquick.html}{Qt Quick}.

    This tutorial describes how to use the Qt Creator to implement the
    \l{http://doc.qt.nokia.com/4.7/declarative-animation-states.html}
    {states and transitions example application}. The example application displays a
    Qt logo that moves between three rectangles on the page when you click them.

    \image qmldesigner-tutorial.png "States and transitions example"

    \section1 Creating the Project

    \list 1

        \o Select \gui{File > New File or Project > Qt Quick Project > Qt Quick UI >
        Choose}.

        \o Follow the instructions of the wizard to create a project called Transitions.

        \o Press \key {Ctrl+R} to run the application in the QML Viewer.

    \endlist

    Qt Creator generates a default QML file that you can modify to create the main view
    of the application.

    \image qmldesigner-tutorial-project.png "Transitions project in Edit mode"

    \section1 Creating the Main View

    The main view of the application displays a Qt logo in the top left corner of the
    screen and two empty rectangles.

    To use the states.png image in your application, you must copy it to the project
    directory (same subdirectory as the QML file) from the examples directory in the
    Qt installation directory. For example:
    \c {C:\QtSDK\Examples\4.7\declarative\animation\states}. The image appears
    in the \gui Resources pane. You can also use any other image or a QML element, instead.

    \list 1

        \o In the \gui Projects view, double-click the main .qml file (Transitions.qml)
        to open it in the code editor.

        \o Click \gui Design to open the file in \QMLD.

        \image qmldesigner-tutorial-desing-mode.png "Transitions project in Design Mode"

        \o In the \gui Navigator pane, select \gui Text and press \key Delete to delete it.

        \o Select \gui Rectangle to edit its properties.

        \image qmldesigner-tutorial-page.png "Page properties"

        \list a

            \o In the \gui Id field, enter \e page, to be able to reference the rectangle
            from other places.

            \o In the \gui Colors tab, \gui Rectangle field, set the color to #343434.

        \endlist

        \o In the \gui Library view, \gui Resources tab, select states.png and
        drag and drop it to the canvas.

        \image qmldesigner-tutorial-user-icon.png "Image properties"

        \list a

            \o In the \gui Id field, enter \e icon.

            \o In the \gui Position field, set \gui X to 10 and \gui Y to 20.

        \endlist



        \o In the \gui Library view, \gui Items tab, select \gui Rectangle,
         drag and drop it to the canvas, and edit its properties.

        \image qmldesigner-tutorial-topleftrect.png "Rectangle properties"

        \list a

            \o In the \gui Id field, enter \e topLeftRect.

            \o In the \gui Size field, set \gui W and \gui H to 64, for the rectangle size
            to match the image size.

            \o In the \gui Colors tab, \gui Rectangle field, click the
            \inlineimage qmldesigner-transparent-button.png
            button to make the rectangle transparent.

            \o In the \gui Border field, set the border color to #808080.

            \o In the \gui Rectangle tab, \gui Border field, set the border width to
            1.

            \note If the \gui Border field does not appear after you set the border
            color, try setting the border color to solid by clicking the
            \inlineimage qmldesigner-solid-color-button.png
            button.

            \o In the \gui Radius field, select 6 to create rounded corners for the
            rectangle.

            \o Click \gui {Layout}, and then click the top and left anchor buttons
            to anchor the rectangle to the top left corner of the page.

            \image qmldesigner-tutorial-topleftrect-layout.png "Layout tab"

            \o In the \gui Margin field, select 20 for the top anchor and 10 for
            the left anchor.

        \endlist

        \o In the \gui Navigator pane, drag and drop the \gui {Mouse Area} element from
        \e page to \e topLeftRect to make it apply only to the rectangle and not to the whole
        page.

        \o Edit \gui {Mouse Area} properties:

        \list a

            \o Click \gui {Layout}, and then click the
            \inlineimage qmldesigner-anchor-fill-screen.png
            button to anchor the mouse area to the rectangle.

            \o In the code editor, edit the pointer to the clicked expression in the mouse
            area element, as illustrated by the following code snippet:

            \qml
            MouseArea {
                anchors.fill: parent
                onClicked: page.state = ''
            }
            \endqml

            The expression sets the state to the base state and returns the image to
            its initial position.

        \endlist

    \o In the \gui Navigator pane, copy topLeftRect (by pressing \key {Ctrl+C}) and
    paste it to the canvas twice
    (by pressing \key {Ctrl+V}). Qt Creator renames the new instances of the element
    topLeftRect1 and topLeftRect2.

    \o Select topLeftRect1 and edit its properties:

        \list a

            \o In the \gui Id field, enter \e middleRightRect.

            \o In \gui {Layout}, select the vertical center anchor button and
            then the right anchor button to
            anchor the rectangle to the middle right margin of the screen.

            \o In the \gui Margin field, select 10 for the right anchor and 0 for
            the vertical center anchor.

            \o In the code editor,add a pointer to a clicked expression to the
            mouse area element. The following expression sets the state to \e State1:

            \c {onClicked: page.state = 'State1'}

            You will create State1 later.

        \endlist

    \o Select topLeftRect2 and edit its properties:

        \list a

            \o In the \gui Id field, enter \e bottomLeftRect.

            \o In \gui {Layout}, select the bottom and left anchor buttons to
            anchor the rectangle to the bottom left margin of the screen.

            \o In the \gui Margin field, select 20 for the bottom anchor and 10 for
            the left anchor.

            \o In the code editor, add a pointer to a clicked expression to the
            mouse area element. The following expression sets the state to \e State2:

            \c {onClicked: page.state = 'State2'}

            You will create State2 later.

        \endlist

    \o Press \key {Ctrl+S} to save the changes.

    \o Press \key {Ctrl+R} to run the application in the QML Viewer.

    \endlist

    \image qmldesigner-tutorial.png "States and transitions example"

    You should see the Qt logo in the top left rectangle, and two additional
    rectangles in the center right and bottom left of the screen.

    You can now create additional states to add views to the application.

    \section1 Adding Views

    In the .qml file, you already created pointers to two additional states:
    State1 and State2. To create the states:

    \list 1

        \o Click the empty slot in the \gui States pane to create State1.

        \o Click the empty slot in the \gui States pane to create State2.

        \o In the code editor, bind the position of the Qt logo to the rectangle
        to make sure that the logo is displayed within the rectangle when the view
        is scaled on different sizes of screens. Set expressions for the x and y
        properties, as illustrated by the following code snippet:

        \snippet snippets/qml/states-properties.qml states

        \image qmldesigner-tutorial-state1.png "States"

        \note When you set the expressions, drag and drop is disabled for
        the icon in \QMLD.

    \o Press \key {Ctrl+R} to run the application in the QML Viewer.

    \endlist

    Click the rectangles to move the Qt logo from one rectangle to another.

    \section1 Adding Animation to the View

    Add transitions to define how the properties change when the Qt logo moves
    between states. The transitions apply animations to the Qt logo. For example,
    the Qt logo bounces back when it moves to the middleRightRect and eases into
    bottomLeftRect. Add the transitions in the code editor.

    \list 1

        \o In the code editor, add the following code to specify that when moving to
        State1, the x and y coordinates of the Qt logo change linearly over a duration
        of 1 second:

        \snippet snippets/qml/list-of-transitions.qml first transition

        \o You can use the Qt Quick toolbar for animation to change the easing curve
        type from linear to OutBounce:

        \list a

            \o Click \gui NumberAnimation in the code editor to display the
            \inlineimage qml-toolbar-indicator.png
            icon, and then click the icon to open the toolbar:

            \image qmldesigner-tutorial-quick-toolbar.png "Qt Quick toolbar for animation"

            \o In the \gui Easing field, select \gui Bounce.

            \o In the \gui Subtype field, select \gui Out.

        \endlist

        \o Add the following code to specify that when moving to State2, the x and y
        coordinates of the Qt logo change over a duration of 2 seconds,
        and an InOutQuad easing function is used:

        \snippet snippets/qml/list-of-transitions.qml second transition

        \o Add the following code to specify that for any other state changes, the x
        and y coordinates of the Qt logo change linearly over a duration of 200
        milliseconds:

        \snippet snippets/qml/list-of-transitions.qml default transition

        \o Press \key {Ctrl+R} to run the application in the QML Viewer.

    \endlist

    Click the rectangles to view the animated transitions.

    \section1 Deploying the Application to Mobile Devices

    To deploy the application to mobile devices, use the \gui {Qt Quick Application} wizard
    to convert it into a Qt Quick application. For more information, see
    \l{Importing QML Applications}.

*/


/*!
    \contentspage index.html
    \previouspage creator-build-example-application.html
    \page creator-writing-program.html
    \nextpage creator-mobile-example.html

    \title Creating a Qt Widget Based Application

    This tutorial describes how to use Qt Creator
    to create a small Qt application, Text Finder. It is a simplified version of the
    QtUiTools \l{http://doc.qt.nokia.com/4.7/uitools-textfinder.html}{Text Finder}
    example.
    The application user interface is constructed from Qt widgets by using \QD.
    The application logic is written in C++ by using the code editor.

    \image qtcreator-textfinder-screenshot.png

    \section1 Creating the Text Finder Project

    \note Create the project with two instances of Qt Creator open and the \gui{Help} mode
    active in one of them so that you can follow
    these instructions while you work.

    \list 1

        \o Select \gui{File > New File or Project > Qt Widget Project > Qt Gui
        Application > Choose}.

        \image qtcreator-new-qt-gui-application.png "New File or Project dialog"

        The \gui{Introduction and Project Location} dialog opens.

        \image qtcreator-intro-and-location-qt-gui.png "Introduction and Project Location dialog"

        \o In the \gui{Name} field, type \bold {TextFinder}.


        \o In the \gui {Create in} field, enter the path for the project files. For example,
        \c {C:\Qt\examples}, and then click \gui{Next}.

        The \gui {Target Setup} dialog opens.

        \image qtcreator-new-project-qt-versions-qt-gui.png "Target Setup dialog"

        \o Select the Qt versions to use as build targets for your project, and click
        \gui{Next}.

        \note If you have only one Qt version installed, this dialog is skipped.

        The \gui{Class Information} dialog opens.

        \image qtcreator-class-info-qt-gui.png "Class Information dialog"

        \o In the \gui{Class name} field, type \bold {TextFinder} as the class name.

        \o In the \gui{Base class} list, select \bold {QWidget} as the base class type.

           \note The \gui{Header file}, \gui{Source file} and
           \gui{Form file} fields are automatically updated to match the name of the
           class.

        \o Click \gui{Next}.

        The \gui{Project Management} dialog opens.

        \image qtcreator-new-project-summary-qt-gui.png "Project Management dialog"

        \o Review the project settings, and click \gui{Finish} to create the project.


    \endlist



    The TextFinder project now contains the following files:

    \list
        \o textfinder.h
        \o textfinder.cpp
        \o main.cpp
        \o textfinder.ui
        \o textfinder.pro
    \endlist

    \image qtcreator-textfinder-contents.png "TextFinder project contents"

    The .h and .cpp files come with the necessary boiler plate code.
    The .pro file is complete.

    \section1 Filling in the Missing Pieces

    Begin by designing the user interface and then move on to filling
    in the missing code. Finally, add the find functionality.

    \section2 Designing the User Interface

    \image qtcreator-textfinder-ui.png "Text Finder UI"

    \list 1

    \o In the \gui{Editor} mode, double-click the textfinder.ui file in the \gui{Projects}
    view to launch the integrated \QD.

    \o Drag and drop the following widgets to the form:

    \list
    \o \gui{Label} (QLabel)
    \o \gui{Line Edit} (QLineEdit)
    \o \gui{Push Button} (QPushButton)

    \endlist

    \image qtcreator-textfinder-ui-widgets.png "Adding widgets to Text Finder UI"

    \note To easily locate the widgets, use the search box at the top of the
    \gui Sidebar. For example, to find the \gui Label widget, start typing
    the word \bold label.

    \image qtcreator-texfinder-filter.png "Filter field"

    \o Double-click the \gui{Label} widget and enter the text \bold{Keyword}.

    \o Double-click the \gui{Push Button} widget and enter the text \bold{Find}.

    \o In the \gui Properties pane, change the \gui objectName to \bold findButton.

    \image qtcreator-textfinder-objectname.png "Changing object names"

    \o Press \key {Ctrl+A} to select the widgets and click \gui{Lay out Horizontally}
    (or press \gui{Ctrl+H}) to apply a horizontal layout
    (QHBoxLayout).

    \image qtcreator-texfinder-ui-horizontal-layout.png "Applying horizontal layout"

    \o Drag and drop a \gui{Text Edit} widget (QTextEdit)
    to the form.

    \o Select the screen area and click \gui{Lay out Vertically} (or press \gui{Ctrl+L})
    to apply a vertical layout (QVBoxLayout).

    \image qtcreator-textfinder-ui.png "Text Finder UI"

    Applying the horizontal and vertical layouts ensures that the application UI scales to different
    screen sizes.

    \o To call a find function when users press the \gui Find button, you use the Qt signals
    and slots mechanism. A signal is emitted when a particular event occurs and a slot is
    a function that is called in response to a particular signal. Qt widgets have predefined
    signals and slots that you can use directly from \QD. To add a slot for the find function:

        \list

            \o Right-click the \gui Find button to open a context-menu.
            \o Select \gui {Go to Slot > clicked()}, and then select \gui OK.

            A private slot, \c{on_findButton_clicked()}, is added to the header file,
            textfinder.h and a private function, \c{TextFinder::on_findButton_clicked()},
            is added to the source file, textfinder.cpp.

        \endlist

    \o Press \gui{Ctrl+S} to save your changes.

    \endlist

    For more information about designing forms with \QD, see the
    \l{http://doc.qt.nokia.com/4.7/designer-manual.html}{Qt Designer Manual}.

    \section2 Completing the Header File

    The textfinder.h file already has the necessary #includes, a
    constructor, a destructor, and the \c{Ui} object. You need to add a private
    function, \c{loadTextFile()}, to read and display the
    contents of the input text file in the
    QTextEdit.

    \list 1

    \o In the \gui{Projects} pane in the \gui {Edit view}, double-click the \c{textfinder.h} file
    to open it for editing.

    \o Add a private function
    to the \c{private} section, after the \c{Ui::TextFinder} pointer, as
    illustrated by the following code snippet:

    \snippet examples/textfinder/textfinder.h 0

    \endlist

    \section2 Completing the Source File

    Now that the header file is complete, move on to the source file,
   textfinder.cpp.

    \list 1

    \o In the \gui{Projects} pane in the \gui Edit view, double-click the textfinder.cpp file
    to open it for editing.

    \o Add code to load a text file using
    QFile, read it with QTextStream, and
    then display it on \c{textEdit} with
    \l{http://doc.qt.nokia.com/4.7/qtextedit.html#plainText-prop}{setPlainText()}.
    This is illustrated by the following code snippet:

    \snippet examples/textfinder/textfinder.cpp 0

    \o To use QFile and QTextStream, add the
    following #includes to textfinder.cpp:

    \snippet examples/textfinder/textfinder.cpp 1

    \o For the \c{on_findButton_clicked()} slot, add code to extract the search string and
    use the \l{http://doc.qt.nokia.com/4.7/qtextedit.html#find}{find()} function
    to look for the search string within the text file. This is illustrated by
    the following code snippet:

    \snippet examples/textfinder/textfinder.cpp 2

    \o Once both of these functions are complete, add a line to call \c{loadTextFile()} in
    the constructor, as illustrated by the following code snippet:

    \snippet examples/textfinder/textfinder.cpp 3

    \endlist

    The \c{on_findButton_clicked()} slot is called automatically in
    the uic generated ui_textfinder.h file by this line of code:

    \code
    QMetaObject::connectSlotsByName(TextFinder);
    \endcode

    \section2 Creating a Resource File

    You need a resource file (.qrc) within which you embed the input
    text file. The input file can be any .txt file with a paragraph of text.
    Create a text file called input.txt and store it in the textfinder
    folder.

    To add a resource file:
    \list 1
        \o Select \gui{File > New File or Project > Qt > Qt Resource File > Choose}.
    \image qtcreator-add-resource-wizard.png "New File or Project dialog"

    The \gui {Choose the Location} dialog opens.

        \image qtcreator-add-resource-wizard2.png "Choose the Location dialog"

        \o In the \gui{Name} field, enter \bold{textfinder}.
        \o In the \gui{Path} field, enter \c{C:\Qt\examples\TextFinder},
        and click \gui{Next}.

        The \gui{Project Management} dialog opens.

        \image qtcreator-add-resource-wizard3.png "Project Management dialog"


        \o In the \gui{Add to project} field, select \bold{TextFinder.pro}
        and click \gui{Finish} to open the file in the code editor.

        \o Select \gui{Add > Add Prefix}.
        \o In the \gui{Prefix} field, replace the default prefix with a slash (/).
        \o Select \gui{Add > Add Files}, to locate and add input.txt.

        \image qtcreator-add-resource.png "Editing resource files"

    \endlist

    \section1 Compiling and Running Your Program

    Now that you have all the necessary files, click the \inlineimage qtcreator-run.png
    button to compile and run your program.

*/


/*!
    \contentspage index.html
    \previouspage creator-project-generic.html
    \page creator-version-control.html
    \nextpage adding-plugins.html

    \title Using Version Control Systems

    Version control systems supported by Qt Creator are:
    \table
        \header
            \i Version Control System
            \i Address
            \i Notes
        \row
            \i  Bazaar
            \i  \l{http://bazaar.canonical.com/}
            \i  Qt Creator 2.2 and later
        \row
            \i  CVS
            \i  \l{http://www.cvshome.org}
            \i
        \row
            \i  Git
            \i  \l{http://git-scm.com/}
            \i
        \row
            \i  Mercurial
            \i  \l{http://mercurial.selenic.com/}
            \i  Qt Creator 2.0 and later
        \row
            \i  Perforce
            \i  \l{http://www.perforce.com}
            \i  Server version 2006.1 and later
        \row
            \i  Subversion
            \i  \l{http://subversion.apache.org/}
            \i
    \endtable


    \section1 Setting Up Version Control Systems

    Qt Creator uses the version control system's command line clients to access
    your repositories. To allow access, make sure that the command line clients
    can be located using the \c{PATH} environment variable or specify the path to
    the command line client executables in \gui{Tools} > \gui{Options...} >
    \gui {Version Control}.

    After you set up the version control system, use the command line to check
    that everything works (for example, use the status command). If no issues arise,
    you should be ready to use the system also from Qt Creator.

    \section2 Using msysGit on Windows

    If you configure Git for use with \c {git bash}, only, and use SSH
    authorization, Git looks for the SSH keys in the directory where the
    \c HOME environment points to. The variable is always set by \c {git bash}.

    However, the variable is typically not set in a Windows command prompt.
    When you run Git from a Windows command prompt, it looks for the SSH keys in its
    installation directory, and therefore, the authorization fails.

    You can set the \c HOME environment variable from Qt Creator. Select \gui {Tools >
    Options... > Version Control > Git}. Select the \gui {Environment Variables}
    and the \gui {Set "HOME" environment variable} check boxes. \c HOME is set to
    \c %HOMEDRIVE%%HOMEPATH% when the Git executable is run and authorization works
    as it would with \c {git bash}.

    \section1 Setting Up Common Options

    Select \gui{Tools} > \gui{Options...} > \gui{Version Control} > \gui{Common}
    to specify settings for submit messages:
    \list
       \o   \gui{Submit message check script} is a script or program that
             can be used to perform checks on the submit message before
             submitting. The submit message is passed in as the script's first
             parameter. If there is an error, the script should output a
             message on standard error and return a non-zero exit code.

       \o    \gui{User/alias configuration file} takes a file in mailmap format
             that lists user names and aliases. For example:

             \code
             Jon Doe <Jon.Doe@company.com>
             Hans Mustermann <Hans.Mustermann@company.com> hm <info@company.com>
             \endcode

             \note The second line above specifies the alias \e{hm} and the
             corresponding email address for \e{Hans Mustermann}. If the
             user/alias configuration file is present, the submit editor
             displays a context menu with \gui{Insert name...} that pops up a
             dialog letting the user select a name.

       \o    \gui{User fields configuration file} is a simple text file
             consisting of lines specifying submit message fields that take
             user names, for example:

             \code
             Reviewed-by:
             Signed-off-by:
             \endcode

    The fields above appear below the submit message. They provide completion
    for the aliases/public user names specified in the
    \e{User/alias configuration file} as well as a button that opens the
    aforementioned user name dialog.

    \o    \gui{SSH prompt command} specifies an ssh-askpass command that you
          can use (on Linux) to prompt the user for a password when using SSH.
          For example, \c ssh-askpass or \c x11-ssh-askpass, depending on the
          ssh-askpass implementation that you use.

    \endlist

    \section1 Creating VCS Repositories for New Projects

    Qt Creator allows you to create repositories for version
    control systems that support local repository creation, such as
    Git, Mercurial, or Bazaar.
    When creating a new project by selecting \gui File >
    \gui{New File or Project...}, you can choose a version
    control system in the final wizard page.

    You can also select \gui Tools and then select \gui {Create Repository...}
    in the submenu for the version control system.

    To import a project that is under version control, choose \gui {File >
    New File or Project... > Project from Version Control} and select the
    version control system that you use. Follow the instructions of the
    wizard to import the project.

    \section1 Using Version Control Systems

    The \gui{Tools} menu contains a submenu for each supported version
    control system.

    The \gui{Version Control} output pane displays the commands
    that are executed, a timestamp, and the relevant output.
    Select \gui {Window > Output Panes > Version Control} to open
    the pane.


    \image qtcreator-vcs-pane.png


    \section2 Adding Files

    When you create a new file or a new project, the wizard displays a page
    asking whether the files should be added to a version control system.
    This happens when the parent directory or the project is already
    under version control and the system supports the concept of adding files,
    for example, Perforce and Subversion. Alternatively, you can
    add files later by using the version control tool menus.

    With Git, there is no concept of adding files. Instead, all modified
    files must be staged for a commit.


    \section2 Viewing Diff Output

    All version control systems provide menu options to \e{diff} the current
    file or project: to compare it with the latest version stored in the
    repository and to display the differences. In Qt Creator, a diff is
    displayed in a read-only editor. If the file is accessible, you can
    double-click on a selected diff chunk and Qt Creator opens an editor
    displaying the file, scrolled to the line in question.

    \image qtcreator-vcs-diff.png


    \section2 Viewing Versioning History and Change Details

    Display the versioning history of a file by selecting \gui{Log}
    or \gui{Filelog}. Typically, the log output contains the date, the commit
    message, and a change or revision identifier. Click on the identifier to
    display a description of the change including the diff.
    Right-clicking on an identifier brings up a context menu that lets you
    show annotation views of previous versions (see \l{Annotating Files}).

    \image qtcreator-vcs-log.png


    \section2 Annotating Files

    Annotation views are obtained by selecting \gui{Annotate} or \gui{Blame}.
    Selecting \gui{Annotate} or \gui{Blame} displays the lines of the file
    prepended by the change identifier they originate from. Clicking on the
    change identifier shows a detailed description of the change.

    To show the annotation of a previous version, right-click on the
    version identifier at the beginning of a line and choose one of the
    revisions shown at the bottom of the context menu. This allows you to
    navigate through the history of the file and obtain previous versions of
    it. It also works for Git and Mercurial using SHA's.

    The same context menu is available when right-clicking on a version
    identifier in the file log view of a single file.


    \section2 Committing Changes

    Once you have finished making changes, submit them to the version control
    system by choosing \gui{Commit} or \gui{Submit}. Qt Creator displays a
    commit page containing a text editor where you can enter your commit
    message and a checkable list of modified files to be included.

    \image qtcreator-vcs-commit.png

    When you have finished filling out the commit page information, click on
    \gui{Commit} to start committing.

    The \gui{Diff Selected Files} button brings up a diff view of the
    files selected in the file list. Since the commit page is just another
    editor, you can go back to it by closing the diff view. You can also check
    a diff view from the editor combo box showing the \gui{Opened files}.

    \section2 Reverting Changes

    All supported version control system support reverting your project to
    known states. This functionality is generally called \e reverting.

    The changes discarded depend on the version control system.

    A version control system can replace the \gui Revert menu option with other
    options.

    \section3 Reverting Changes Using Git

    The Git version control system has an index that is used to stage
    changes. The index is commited on the next commit. Git allows you to revert
    back to the state of the last commit as well as to the state staged in the
    index.

    \list

        \o \gui{Undo Unstaged Changes} reverts all changes and resets the working
        directory to the state of the index.

        \o \gui{Undo Uncommitted Changes} reverts all changes, discarding the index.
        This returns your working copy to the state it was in right after the last commit.

    \endlist

    \section2 Viewing Status

    You can select \gui{Status...} to view the status of the project or
    repository.

    \section2 Updating the Working Tree

    You can select \gui Update to update your working tree with the latest
    changes from the branch. Some version control systems allow you to choose
    between updating the current project and updating all projects.

    With Git, you stash your changes and then pull the changes from the
    repository.

    \section2 Deleting Files

    You can select \gui Delete to delete obsolete files from the repository.

    With Git, you delete the files from the working tree and then stage the
    deleted files for a commit.

    \section2 Using Additional Bazaar Functions

    Bazaar is a free version control system sponsored by Canonical.

    The \gui Bazaar submenu contains the following additional items:

    \table
        \header
            \o  Menu Item
            \o  Description
        \row
            \i  \gui{Pull...}
            \i  Turn the branch into a mirror of another branch.
        \row
            \i  \gui{Push...}
            \i  Update a mirror of the branch.

    \endtable

    \section2 Using Additional CVS Functions

    CVS is an open source version control system.

    The \gui CVS submenu contains the following additional items:

    \table
        \header
            \o  Menu Item
            \o  Description
        \row
            \i  \gui{Edit}
            \i  Open a file for editing.
        \row
            \i  \gui{Push...}
            \i  Push changes to the remote repository.
        \row
            \i  \gui{Unedit}
            \i  Discard the changes that you made in a file.

    \endtable

    \section2 Using Additional Git Functions

    Git is a fast decentralized version control system. Git is available
    for Windows, Linux and Mac.

    The \gui Git submenu contains the following additional items:

    \table
        \header
            \o  Menu Item
            \o  Description
        \row
            \i  \gui {Patch > Apply from Editor/Apply from File...}
            \i  Patches are rewriting instructions that can be applied to a set of files.
                You can either apply a patch file that is open in Qt Creator or select
                the patch file to apply from the file system.
        \row
            \i  \gui{Pull}
            \i  Pull changes from the remote repository. If there are locally
                modified files, you are prompted to stash those changes. Select \gui{Tools >
                Options... > Version Control > Git} and select the \gui {Pull with rebase}
                check box to perform a rebase operation while pulling.

        \row
            \i  \gui{Clean.../Clean Project...}
            \i  All files that are not under version control (with the exception
                of patches and project files) are displayed in the \gui {Clean Repository}
                dialog. Select the files to delete and click \gui Delete. This allows you to
                clean a build completely.
        \row
            \i  \gui{Launch gitk}
            \i  Start the commit viewer for Git, gitk.

        \row
            \i  \gui{Branches...}
            \i  Display the \gui Branch dialog that shows the local branches at the
                top and remote branches at the bottom. To switch to a local branch,
                double-click it. Double-clicking on a remote branch first creates a local
                branch with the same name that tracks the remote branch, and then switches
                to it.

                \image qtcreator-vcs-gitbranch.png

        \row
            \i  \gui {Stage File for Commit}
            \i  Mark new or modified files for committing to the repository.
                To undo this function, select \gui {Unstage File from Commit}.
        \row
            \i  \gui{Show Commit...}
            \i  Select a commit to view. Enter the SHA of the commit
                in the \gui Change field.
        \row
            \i  \gui{Amend Last Commit...}
            \i  Revert the last commit.

    \endtable

    \section3 Using Stashes

    With Git, you can put your current set of changes onto a virtual shelf called a \e stash.
    Stashes are useful, for example, to put aside a set of changes to work on higher
    priority tasks or to pull in new chages from another repository.

    Qt Creator exposes this functionality in the \gui{Tools > Git > Stash} menu.

    \table
        \header
            \o  Menu Item
            \o  Description
        \row
            \i  \gui{Stashes...}
            \i  Display a dialog that shows all known stashes with options to restore,
                display or delete them.
        \row
            \i  \gui{Stash}
            \i  Stash all local changes. The working copy is then reset to
                the state it had right after the last commit.
        \row
            \i  \gui{Stash Snapshot...}
            \i  Save a snapshot of your current work under a name for later reference. The
                working copy is unchanged.

                For example, if you want to try something and find out later that it does not work,
                you can discard it and return to the state of the snapshot.
        \row
            \i  \gui{Stash Pop}
            \i  Remove a single stashed state from the stash list and apply it on
                top of the current working tree state.
    \endtable

    \section2 Using Additional Mercurial Functionality

    Mercurial is a free, distributed source control management tool.

    The \gui Mercurial submenu contains the following additional items:

    \table
        \header
            \o  Menu Item
            \o  Description
        \row
            \i  \gui{Import}
            \i  Apply changes from a patch file.
        \row
            \i  \gui{Incoming}
            \i  Monitor the status of a remote repository by listing
                the changes that will be pulled.
        \row
            \i  \gui{Outgoing}
            \i  Monitor the status of a remote repository by listing
                the changes that will be pushed.
        \row
            \i  \gui{Pull}
            \i  Pull changes from the remote repository.
        \row
            \i  \gui{Push}
            \i  Push changes to the remote repository.
     \endtable

    \section2 Using Additional Perforce Functions

    Perforce is a fast software configuration management system developed by
    Perforce Software.

    When you start Qt Creator, it looks for the executable specified
    in the \gui{P4 command} field in \gui{Tools > Options... > Version
    Control > Perforce}. If the file is not found, the following error
    message is displayed in the \gui {Version Control} output pane:
    \gui {Perforce: Unable to determine the repository: "p4.exe"
    terminated with exit code 1}. If you use Perforce, check that the
    path to the executable is specified correctly in the \gui{P4 command}
    field.

    If you do not use Perforce, you can disable the Perforce plugin to
    get rid of the error message. Choose \gui {Help > About Plugins} and
    deselect the \gui Load check box for the \gui Perforce plugin in the
    \gui {Version Control} group.

    The \gui Perforce submenu contains the following additional items:

    \table
        \header
            \o  Menu Item
            \o  Description
        \row
            \i  \gui{Describe...}
            \i  View information about changelists and the files in them.
        \row
            \i  \gui{Edit File}
            \i  Open a file for editing.
        \row
            \i  \gui{Opened}
            \i  List files that are open for editing.
        \row
            \i  \gui{Pending Changes...}
            \i  Group files for commit.
    \endtable

    \section2 Using Additional Subversion Functions

    Subversion is an open source version control system.

    The \gui Subversion submenu contains the following additional items:

    \table
        \header
            \o  Menu Item
            \o  Description
        \row
            \i  \gui{Describe...}
            \i  Display commit log messages for a revision.
    \endtable

*/


/*!
    \contentspage index.html
    \previouspage qt-quick-toolbars.html
    \page creator-editor-locator.html
    \nextpage creator-editor-codepasting.html

    \title Searching With the Locator

    The locator provides one of the easiest ways in Qt Creator to browse
    through projects, files, classes, methods, documentation and file systems.
    You can find the locator in the bottom left of the Qt Creator window.

    To activate the locator, press \key Ctrl+K (\key Cmd+K on Mac OS
    X) or select \gui Tools > \gui Locate....

    \image qtcreator-locator.png

    To edit the currently open project's main.cpp file using the locator:
    \list 1
        \o Activate the locator by pressing \key Ctrl+K.
        \o Enter \tt{main.cpp}.

           \image qtcreator-locator-open.png
        \o Press \key Return.

           The main.cpp file opens in the editor.
    \endlist

    It is also possible to enter only a part of a search string.
    As you type, the locator shows the occurrences of that string regardless
    of where in the name of an component it appears.

    To narrow down the search results, you can use the following wildcard
    characters:
    \list
        \o To match any number of any or no characters, enter \bold{*}.
        \o To match a single instance of any character, enter \bold{?}.
    \endlist

    \section1 Using the Locator Filters

    The locator allows you to browse not only files, but any items
    defined by \bold{locator filters}. By default, the locator contains
    filters for:
    \list
        \o  Locating any open document
        \o  Locating files anywhere on your file system
        \o  Locating iles belonging to your project, such as source, header resource,
            and .ui files
        \o  Locating class and method definitions in your project or anywhere
            referenced
            from your project
        \o  Locating class and method definitions in the current document
        \o  Locating a specific line in the document displayed in your editor
        \o  Opening help topics, including Qt documentation
        \o  Performing web searches
        \o  Running text editing macros that you record and save. For more
            information, see \l{Using Text Editing Macros}
    \endlist

    To use a specific locator filter, type the assigned prefix followed by
    \key Space. The prefix is usually a single character.

    For example, to locate symbols matching
    QDataStream:
    \list 1
        \o Activate the locator.
        \o Enter \tt{\bold{: QDataStream}} (: (colon) followed by a
           \key Space and the symbol name (QDataStream)).

           The locator lists the results.

           \image qtcreator-navigate-popup.png
    \endlist

    By default the following filters are enabled and you do not need to use
    their prefixes explicitly:

    \list
        \o Going to a line in the current file (l).
        \o Going to an open file (o).
        \o Going to a file in any open project (a).
    \endlist

    \section2 Using the Default Locator Filters

    The following locator filters are available by default:

    \table
        \header
            \o  Function
            \o  Enter in locator
            \o  Example
        \row
            \o  Go to a line in the current file.
            \o  \tt{\bold{l \e{Line number}}}
            \o  \image qtcreator-locator-line.png
        \row
            \o  Go to a symbol definition.
            \o  \tt{\bold{: \e{Symbol name}}}
            \o  \image qtcreator-locator-symbols.png
        \row
            \o  Go to a symbol definition in the current file.
            \o  \tt{\bold{. \e{Symbol name}}}
            \o  \image qtcreator-locator-method-list.png
        \row
            \o  Go to a help topic.
            \o  \tt{\bold{? \e{Help topic}}}
            \o  \image qtcreator-locator-help.png
        \row
            \o  Search for a term by using a web search engine.
            \o  \tt{\bold{r \e{Search term}}}
            \o  \image qtcreator-locator-web.png
        \row
            \o  Go to an open file.
            \o  \tt{\bold{o \e{File name}}}
            \o  \image qtcreator-locator-opendocs.png
        \row
            \o  Go to a file in the file system (browse the file system).
            \o  \tt{\bold{f \e{File name}}}
            \o  \image qtcreator-locator-filesystem.png
        \row
            \o  Go to a file in any project currently open.
            \o  \tt{\bold{a \e{File name}}}
            \o  \image qtcreator-locator-files.png
        \row
            \o  Go to a file in the current project.
            \o  \tt{\bold{p \e{File name}}}
            \o  \image qtcreator-locator-current-project.png
        \row
            \o  Go to a class definition.
            \o  \tt{\bold{c \e{Class name}}}
            \o  \image qtcreator-locator-classes.png
        \row
            \o  Go to a method definition.
            \o  \tt{\bold{m \e{Method name}}}
            \o  \image qtcreator-locator-methods.png
        \row
            \o  Execute a text editing macro.
            \o  \tt{\bold{rm \e{Macro name}}}
            \o  \image qtcreator-locator-macros.png
    \endtable

    \section2 Creating Locator Filters

    To quickly access files not directly mentioned in your project, you can
    create your own locator filters. That way you can locate files in a
    directory structure you have defined.

    To create a locator filter:
    \list 1
        \o In the locator, click \inlineimage qtcreator-locator-magnify.png
           and select \gui Configure.... to open the \gui Locator options.

           \image qtcreator-locator-customize.png

        \o Click \gui Add.
        \o In the \gui{Filter Configuration} dialog:
        \list
            \o Name your filter.
            \o Select at least one directory. The locator searches directories
               recursively.
            \o Define the file pattern as a comma separated list. For example,
               to search all .h and .cpp files, enter \bold{*.h,*.cpp}
            \o Specify the prefix string.

               To show only results matching this filter, select
               \gui{Limit to prefix}.

               \image qtcreator-navigate-customfilter.png
        \endlist
        \o Click OK.
    \endlist

    \section2 Adding Web Search Engines

    You can use the \gui {Web Search (\c r)} locator filter to perform
    web searches. URLs and search commands for Bing, Google, Yahoo! Search,
    cplusplus.com, and Wikipedia are configured by default.

    To find out the format of the search command to use for your favorite
    web search engine, perform a search in your browser and copy the resulting
    URL to the locator filter configuration. Replace the search term with the
    variable \c {%1}.

    To add URLs and search commands to the list:

    \list 1

        \o  Select \gui {Tools > Options > Locator > Web Search (prefix: r) >
            Edit}.

        \o  Select \gui Add to add a new entry to the list.

            \image qtcreator-add-online-doc.png "Filter Configuration dialog"

        \o  Double-click the new entry to specify a URL and a search command.
            For example, http://www.google.com/search?q=%1.

        \o  Click \gui OK.

    \endlist

    \section2 Configuring the Locator Cache

    The locator searches the files matching your file pattern in the
    directories you have selected and caches that information. The cache for
    all default filters is updated as you write your code. By default,
    Qt Creator updates the filters created by you once an hour.

    To update the cached information manually, click
    \inlineimage qtcreator-locator-magnify.png
    and select \gui Refresh.

    To set a new cache update time:
    \list 1
        \o Select \gui Tools > \gui Options... > \gui Locator.
        \o In \gui{Refresh interval}, define new time in minutes.
    \endlist

*/


/*!
    \contentspage index.html
    \previouspage creator-developing-symbian.html
    \page creator-project-managing-sessions.html
    \nextpage creator-coding.html

    \title Managing Sessions

    When you exit Qt Creator, a snapshot of your current workspace is stored
    as a \e session. To restore the session automatically when you start Qt
    Creator, select \gui {File > Session Manager > Restore last session on
    startup}.

    A session is an arbitrary collection of:

    \list
        \o Open projects with their dependencies (including SUBDIRS projects)
        \o Open editors
        \o Breakpoints and watches
        \o Bookmarks
    \endlist

    A session is  personal, that is, not meant to be shared. It is not
    supposed to reflect the project structure. It contains personal data, such as
    bookmarks and breakpoints that are usually not of interest to other developers
    working on the same projects.

    For example, if you work on a project and need to switch to another project for a
    while, you can save your workspace as a session. This makes it easier
    to return to working on the first project later.

    To create a new session or remove existing sessions, select \gui File >
    \gui{Session Manager}.

    \image qtcreator-session-manager.png

    To switch between sessions, choose
    \gui {File > Session Manager}. If you do not create or select a session,
    Qt Creator always uses the default session, which was created the
    last time you exited Qt Creator.

    When you launch Qt Creator, a list of existing sessions is displayed on the
    \gui{Welcome screen}.

    \image qtcreator-welcome-session.png

*/


/*!
    \contentspage index.html
    \previouspage creator-build-dependencies.html
    \page creator-debugging.html
    \nextpage creator-debugging-example.html

    \title Debugging

    Qt Creator provides a debugger plugin that acts
    as an interface between the Qt Creator core and external native debuggers
    such as the GNU Symbolic Debugger (GDB), the Microsoft Console Debugger (CDB),
    and a QML/JavaScript debugger.

    The following sections describe debugging with Qt Creator:

    \list

        \o  \l{Debugging the Example Application} uses an example application
            to illustrate how to debug Qt C++ applications in the \gui Debug
            mode.

        \o  \l{Launching the Debugger} describes the
            operating modes in which the debugger plugin runs, depending on
            where and how the process is started and run.

        \o  \l{Interacting with the Debugger} describes the views and functions
            available in the \gui Debug mode.

        \o  \l{Setting Up Debugger} summarizes the support for debugging C++
            code and requirements for installation. Typically, the interaction
            between Qt Creator and the native debugger is set up automatically
            and you do not need to do anything.

        \o  \l{Using Debugging Helpers} describes how to get more detailed data
            on complex data.

        \o  \l{Debugging Qt Quick Projects} describes how to debug Qt Quick
            projects.

        \o  \l{Detecting Memory Leaks} describes how to use the Valgrind
            Memcheck tool to detect problems in memory management.

        \o  \l{Troubleshooting Debugger} lists some typical problems that you
            might encounter while debugging and solutions to them.

    \endlist

*/

/*!
    \contentspage index.html
    \previouspage creator-debugging-example.html
    \page creator-debugger-operating-modes.html
    \nextpage creator-debug-mode.html

    \title Launching the Debugger

    To start a program under the control of the debugger, select \gui{Debug} >
    \gui{Start Debugging} > \gui{Start Debugging}, or press \key{F5}.
    Qt Creator checks whether the compiled program is up-to-date, and rebuilds
    it if necessary. The debugger then takes over and starts the program.

    \note Starting a program in the debugger can take a long
    time, typically in the range of several seconds to minutes if complex
    features (like QtWebKit) are used.

    The debugger is launched in the appropriate operating mode (plain, terminal,
    or on-device), based on the build and run settings for the active project.
    Select \gui Debug menu options to launch the debugger in other modes.

    \note Debugging QML and JavaScript is supported only in plain mode.

    \section1 Launching the Debugger in Different Modes

    The debugger plugin runs in different operating modes depending on where and
    how the process is started and run. Some of the modes are only available for
    a particular operating system or platform.

    You can launch the debugger in the following modes:

    \list

       \o \bold Plain to debug locally started applications, such as a
        Qt based GUI application.

       \o \bold Terminal to debug locally started processes that need a
       console, typically without a GUI.

       \o \bold Attach to debug local processes started outside Qt Creator.

       \o \bold Remote to debug a process running on a different machine.

       \o \bold Core to debug crashed processes on Unix.

       \o \bold Post-mortem to debug crashed processes on Windows.

       \o \bold On-device to debug processes running on a mobile device.

    \endlist

    \note Debugging QML and JavaScript is supported only in plain mode.

    When you click the \gui {Start Debugging} button, the debugger is launched
    in the appropriate operating mode (plain, terminal, or on-device), based on the
    build and run settings for the active project. Select \gui Debug menu options
    to launch the debugger in the other modes.

    \section2 Launching in Plain Mode

    To launch the debugger in the plain mode, click the \gui {Start Debugging}
    button for the active project, or choose
    \gui {Debug > Start Debugging > Start and Debug External Application...}
    and specify an executable.

    \section2 Launching in Terminal Mode

    To launch the debugger in the terminal mode, select \gui {Projects > Run Settings}
    and select the \gui {Run in terminal} check box. Then click the
    \gui {Start Debugging} button for the active project.

    \section2 Launching in Attach Mode

    To launch the debugger in the attach mode, select
    \gui {Debug > Start Debugging >  Attach to Running External Application...},
    and then select a process by its name or process ID to attach to.

    You can load the source project in advance and set breakpoints in it before
    attaching to an already running process. For more information, see
    \l{Setting Breakpoints}.

    \section2 Launching in Remote Mode

    The remote mode allows you to debug processes that run on remote machines.

    \section3 Using GDB

    In remote mode, the local GDB process talks to a GDB server
    process running on the remote machine that controls the process to be
    debugged.

    The GDB server process is started on the remote machines by passing a port
    number and the executable:

    \code
    gdbserver :1234 <executable>
    \endcode

    It then typically responds:
    \code
    Process bin/qtcreator created; pid = 5159
    Listening on port 1234
    \endcode

    On the local machine that runs Qt Creator:

    \list 1

        \o  Select \gui {Debug > Start Debugging > Start and Attach to Remote
            Application...}.

        \o  In the \gui {Host and port} field, enter the name of the remote
            machine and the port number to use.

        \o  Select \gui{OK} to start debugging.

    \endlist

    \section3 Using CDB

    In remote mode, the local CDB process talks to a CDB process that
    runs on the remote machine. The process is started with special
    command line options that switch it into server mode. The remote CDB
    process must load the Qt Creator CDB extension library that is shipped with
    Qt Creator:

    \list 1

        \o  Install the \e{Debugging Tools for Windows} on the remote machine.
            The installation folder contains the CDB command line executable (cdb.exe).

        \o  Copy the Qt Creator CDB extension library from the Qt installation
            directory to the a new folder on the remote machine
            (32 or 64 bit version depending on the version of the Debugging
            Tools for Windows
            used):

        \list

            \o  \c {\lib\qtcreatorcdbext32\qtcreatorcdbext.dll} (32 bit)

            \o  \c {\lib\qtcreatorcdbext64\qtcreatorcdbext.dll} (64 bit)

        \endlist

        \o  Set the _NT_DEBUGGER_EXTENSION_PATH environment variable to point
            to that folder.

        \o  To use TCP/IP as communication protocol, launch remote CDB as
            follows:

            \code
            cdb.exe -server tcp:port=1234 <executable>
            \endcode

        \o  On the local machine running Qt Creator, select
            \gui {Debug > Start Debugging > Attach to Remote CDB Session...}


        \o  In the \gui Connection field enter the connection parameters.
            For example, for TCP/IP:

            \code
            Server:Port
            \endcode

            If you chose some other protocol, specify one of the alternative
            formats:

            \code
            tcp:server=Server,port=Port[,password=Password][,ipversion=6]
            tcp:clicon=Server,port=Port[,password=Password][,ipversion=6]
            npipe:server=Server,pipe=PipeName[,password=Password]
            com:port=COMPort,baud=BaudRate,channel=COMChannel[,password=Password]
            spipe:proto=Protocol,{certuser=Cert|machuser=Cert},server=Server,pipe=PipeName[,password=Password]
            ssl:proto=Protocol,{certuser=Cert|machuser=Cert},server=Server,port=Socket[,password=Password]
            ssl:proto=Protocol,{certuser=Cert|machuser=Cert},clicon=Server,port=Socket[,password=Password]
            \endcode

            \o Click \gui{OK} to start debugging.

    \endlist

    \section2 Launching in Core Mode

    The core mode it used to debug \e {core} files (crash dumps) that are
    generated from crashed processes if the system is set up to allow this.

    To enable the dumping of core files on a Unix system enter the following
    command in the shell from which the application will be launched:

    \code
    ulimit -c unlimited
    \endcode

    To launch the debugger in the core mode, select
    \gui{Debug > Start Debugging >  Attach to Core...}.

    \section2 Launching in Post-Mortem Mode

    The post-mortem mode is available only on Windows, if you have installed
    the debugging tools for Windows.

    The Qt Creator installation program asks you whether you want to
    register Qt Creator as a post-mortem debugger. To change the setting, select
    \gui{Tools > Options...  > Debugger > Common > Use Creator for post-mortem debugging}.

    You can launch the debugger in the post-mortem mode if an application crashes
    on Windows. Click the \gui {Debug in Qt Creator} button in the error message
    that is displayed by the Windows operating system.

    \section2 Launching in On-device Mode

    The on-device mode is a special mode available for run configurations
    targeting mobile devices. It debugs processes running on mobile
    devices using on-device debugging agents, such as CODA on Symbian and
    gdbserver on Maemo and MeeGo Harmattan.

    To launch the debugger in the on-device mode, open the project, select a
    run configuration that targets a mobile device, and click the
    \gui {Start Debugging} button.

*/

/*!
    \contentspage index.html
    \previouspage creator-debug-mode.html
    \page creator-debugger-engines.html
    \nextpage creator-debugging-helpers.html

    \title Setting Up Debugger

    \note The information in this section applies only to debugging the C++
    language.

    Typically, the interaction between Qt Creator and the native debugger is set
    up automatically and you do not need to do anything. However, you might have an
    unsupported GDB version installed, your Linux environment might not have GDB
    installed at all, or you might want to use the debugging tools for Windows.

    \note To use the debugging tools for Windows, you must install them and add the
    Symbol Server provided by Microsoft to the symbol search path of the debugger.
    For more information, see \l{Setting the Symbol Server in Windows}.

    This section explains the
    options you have for debugging C++ code and provides installation notes for the
    supported native debuggers.

    \section1 Supported Native Debugger Versions

    The debugger plugin supports different builds of the GDB debugger, both
    with and without the ability to use Python scripting. The Python enabled
    versions are preferred, but they are not available on Mac and on older
    versions of Linux.
    On Windows, Symbian, Maemo, and MeeGo Harmattan, only the Python version is
    supported.

    The non-Python versions use the compiled version of the debugging helpers,
    that you must enable separately. For more information, see
    \l{Debugging Helpers Based on C++}.

    The Python version uses a script version of the debugging helpers
    that does not need any special setup.

    The CDB native debugger has similar funtionality to the non-Python GDB debugger
    engine. Specifically, it also uses compiled C++ code for the debugging
    helper library.

    The following table summarizes the support for debugging C++ code:

    \table
        \header
            \o Platform
            \o Compiler
            \o Native Debugger
            \o Python
            \o Debugger Modes
        \row
            \o Linux
            \o GCC
            \o GDB
            \o Yes
            \o Plain, Terminal, Attach, Remote, Core
        \row
            \o Unix
            \o GCC
            \o GDB
            \o Yes
            \o Plain, Terminal, Attach, Remote, Core
        \row
            \o Mac OS
            \o GCC
            \o GDB
            \o No
            \o Plain, Terminal, Attach, Core
        \row
            \o Windows/MinGW
            \o GCC
            \o GDB
            \o Yes
            \o Plain, Terminal, Attach, Remote, Core
        \row
            \o Windows/MSVC
            \o Microsoft Visual C++ Compiler
            \o Debugging Tools for Windows/CDB
            \o Not applicable
            \o Plain, Terminal, Attach, Post-Mortem
        \row
            \o Symbian
            \o GCC
            \o GDB
            \o Yes
            \o On-device
        \row
            \o Maemo
            \o GCC
            \o GDB
            \o Yes
            \o On-device
        \row
            \o MeeGo Harmattan
            \o GCC
            \o GDB
            \o Yes
            \o On-device
    \endtable

    For more information on the debugger modes, see \l{Launching the Debugger in Different Modes}.

    \omit

    \section2 GDB Adapter Modes

    [Advanced Topic]

    The GDB native debugger used internally by the debugger plugin runs in
    different adapter modes to cope with the variety
    of supported platforms and environments. All GDB adapters inherit from
    AbstractGdbAdapter:

    \list

       \o PlainGdbAdapter debugs locally started GUI processes.
       It is physically split into parts that are relevant only when Python is
       available, parts relevant only when Python is not available, and mixed code.

       \o TermGdbAdapter debugs locally started processes that need a
       console.

       \o AttachGdbAdapter debugs local processes started outside Qt Creator.

       \o CoreGdbAdapter debugs core files generated from crashes.

       \o RemoteGdbAdapter interacts with the gdbserver running on Linux.

       \o CodaGdbAdapter interacts with Symbian devices. The GDB protocol and
       the GDB serial protocol are used between GDB and the adapter. The
       target communication framework (TCF) protocol is used between the
       adapter and the CODA debugging agent running on the device.

     \endlist

     \endomit

    \section1 Installing Native Debuggers

    There are various reasons why the debugger plugin may fail to automatically
    pick up a suitable native debugger. The native debugger might be missing
    (which is usually the case for the CDB debugger on Windows which always
    needs to be installed manually by the user) or the installed version is not
    supported.
    Check the table below for the supported versions and other important
    information about installing native debuggers.

    \table
        \header
            \o Native Debugger
            \o Notes
        \row
            \o GDB
            \o On Linux and Windows, use the Python-enabled GDB versions that
            are installed when you install Qt Creator and Qt SDK. On Mac OS X,
            use the GDB provided with Xcode.
            For a custom target, you can build your own Python-enabled GDB.
            Follow the instructions on
            \l{http://developer.qt.nokia.com/wiki/QtCreatorBuildGdb}{Building GDB}.
            You must use at least Python version 2.5, but we recommend that you
            use version 2.6.

        \row
            \o Debugging tools for Windows
            \o Using this engine requires you to install the
               \e{Debugging tools for Windows}
               \l{http://www.microsoft.com/whdc/devtools/debugging/installx86.Mspx}
               or
               \l{http://www.microsoft.com/whdc/devtools/debugging/install64bit.Mspx}
               package (Version 6.12 for the 32-bit or the 64-bit version
               of Qt Creator, respectively),
               which are freely available for download from the
               \l{http://msdn.microsoft.com/en-us/default.aspx}{Microsoft Developer Network}.

               The Qt Creator help browser does
               not allow you to download files, and therefore, you must copy
               the above links to a browser.

               \note Visual Studio does not include the Debugging tools needed,
               and therefore, you must install them separately.

               The pre-built \QSDK for Windows makes use of the library if it
               is present on the system. When manually building Qt Creator using
               the Microsoft Visual C++ Compiler, the build process checks for the
               required files in \c{"%ProgramFiles%\Debugging Tools for Windows"}.

               It is highly recommended that you add the Symbol Server provided
               by Microsoft to the symbol search path of the debugger. The Symbol
               Server provides you with debugging informaton for the operating
               system libraries for debugging Windows applications. For more
               information, see \l{Setting the Symbol Server in Windows}.

       \row
           \o Debugging tools for Mac OS X
           \o The Qt binary distribution contains both debug and release
              variants of the libraries. But you have to explicitly tell the
              runtime linker that you want to use the debug libraries even if
              your application is compiled as debug as release is the default
              library.

              If you use a qmake based project in Qt Creator,  you can set a
              flag in your run configuration, in \gui Projects mode. In the run
              configuration, select \gui{Use debug version of frameworks}.

              For more detailed information about debugging on the Mac OS X, see:
              \l{http://developer.apple.com/mac/library/technotes/tn2004/tn2124.html}{Mac OS X Debugging Magic}.

        \note The Mac OS X Snow Leopard (10.6) has a bug that might cause the
              application to crash. For a workaround, see:
              \l{http://bugreports.qt.nokia.com/browse/QTBUG-4962}{QTBUG-4962}.

    \endtable

    \section1 Setting the Symbol Server in Windows

    To obtain debugging information for the operating system libraries for
    debugging Windows applications, add the Symbol Server provided
    by Microsoft to the symbol search path of the debugger:
    \list 1
        \o  Select \gui Tools > \gui{Options...} > \gui Debugger > \gui CDB.
        \o  In the \gui {Symbol paths} field, open the \gui{Insert...} menu
            and select \gui{Symbol Server...}.
        \o  Select a directory where you want to store the cached information
            and click \gui OK.

            Use a subfolder in a temporary directory, such as
            \c {C:\temp\symbolcache}.
    \endlist

    \note Populating the cache might take a long time on a slow network
    connection.

    \note The first time you start debugging by using the
    Debugging tools for Windows, Qt Creator prompts you to add the Symbol
    Server.

*/

/*!
    \contentspage index.html
    \previouspage creator-debugger-operating-modes.html
    \page creator-debug-mode.html
    \nextpage creator-debugger-engines.html

    \title Interacting with the Debugger

    In \gui Debug mode, you can use several views to interact with the
    program you are debugging. The availability of views depends on whether
    you are debugging C++ or QML. Frequently used views are shown by
    default and rarely used ones are hidden. To change the default settings,
    select \gui {Window > Views}, and then select views to display or hide.

    \image qtcreator-debugger-views.png "Debug mode views"

    By default, the views are locked into place in the workspace. Select
    \gui {Window > Views > Locked} to unlock the views. Drag and drop the
    views into new positions on the screen. Drag view borders to resize the
    views. The size and position of views are saved for future sessions.

    \section1 Using the Debugger

    Once the program starts running under the control of the debugger, it
    behaves and performs as usual. You can interrupt a running C++ program by
    selecting \gui{Debug} > \gui {Interrupt}. The program is automatically
    interrupted when a breakpoint is hit.

    Once the program stops, Qt Creator:

    \list
        \o Retrieves data representing the call stack at the program's current
           position.
        \o Retrieves the contents of local variables.
        \o Examines \gui Watchers.
        \o Updates the \gui Registers, \gui Modules, and \gui Disassembler
           views if you are debugging the C++ based applications.
    \endlist

    You can use the \gui Debug mode views to examine the data in more detail.

    You can use the following keyboard shortcuts:

    \list

       \o  To finish debugging, press \key{Shift+F5}.
       \o  To execute a line of code as a whole, press \key{F10}.
       \o  To step into a function or a subfunction, press \key{F11}.
       \o  To continue running the program, press \key{F5}.
       \o  To run to the selected function when you are stepping into a nested
           function, press \key{Ctrl+F6}.

    \endlist

    It is also possible to continue executing the program until the current
    function completes or jump to an arbitrary position in the current function.


    \section1 Setting Breakpoints

    A breakpoint represents a position or sets of positions in the code that,
    when executed, interrupts the program being debugged and passes the control
    to you. You can then examine the state of the interrupted program, or
    continue execution either line-by-line or continuously.

    Qt Creator shows breakpoints in the \gui{Breakpoints} view which is enabled
    by default. The \gui{Breakpoints} view is also accessible when the debugger
    and the program being debugged is not running.

    \image qtcreator-debug-breakpoints.png "Breakpoints view"

    You can associate breakpoints with:

    \list

        \o  Source code files and lines

        \o  Functions

        \o  Addresses

        \o  Throwing and catching exceptions

        \o  Executing and forking processes

        \o  Executing some system calls

    \endlist

    You can also set watchpoints to monitor the changes in a block of memory
    at a particular address when a program is running.

    The interruption of a program by a breakpoint can be restricted with
    certain conditions.

    To set a breakpoint at a particular line you want the program to stop,
    click the left margin or press \key F9 (\key F8 for Mac OS X).

    To set breakpoints and watchpoints select \gui {Add Breakpoint...} in
    the context menu in the \gui Breakpoints view.

    \image qtcreator-add-breakpoint.png "Add Breakpoints" dialog

    \note You can remove a breakpoint:
    \list
        \o By clicking the breakpoint marker in the text editor.
        \o By selecting the breakpoint in the breakpoint view and pressing
           \key{Delete}.
        \o By selecting \gui{Delete Breakpoint} from the context
           menu in the \gui Breakpoints view.
    \endlist

    You can set and delete breakpoints before the program starts running or
    while it is running under the debugger's control. Breakpoints are saved
    together with a session.

    \section2 Setting Watchpoints

    To set a watchpoint at an address:

    \list 1

        \o  Right-click in the \gui Breakpoints view to open the context menu,
            and select \gui {Add Breakpoint...}.

        \o  In the \gui {Breakpoint type} field, select \gui {Address
            (Watchpoint)}.

        \o  In the \gui Address field, specify the address of the memory block.

        \o  Select \gui OK.

    \endlist

    If the address is displayed in the \gui {Locals and Watchers} view, you can
    select \gui {Add Watchpoint at Object's Address} in the context menu to set
    the watchpoint.

    \section1 Viewing Call Stack Trace

    When the program being debugged is interrupted, Qt Creator displays the
    nested function calls leading to the current position as a call stack
    trace. This stack trace is built up from call stack frames, each
    representing a particular function. For each function, Qt Creator tries
    to retrieve the file name and line number of the corresponding source
    file. This data is shown in the \gui Stack view.

    \image qtcreator-debug-stack.png

    Since the call stack leading to the current position may originate or go
    through code for which no debug information is available, not all stack
    frames have corresponding source locations. Stack frames without
    corresponding source locations are grayed out in the \gui{Stack} view.

    If you click a frame with a known source location, the text editor
    jumps to the corresponding location and updates the \gui{Locals and Watchers}
    view, making it seem like the program was interrupted before entering the
    function.

    \section1 Locals and Watchers

    Whenever a program stops under the control of the debugger, it retrieves
    information about the topmost stack frame and displays it in the
    \gui{Locals and Watchers} view. The \gui{Locals and Watchers} view
    typically includes information about parameters of the function in that
    frame as well as the local variables.

    \image qtcreator-watcher.png "Locals and Watchers view"

    Compound variables of struct or class type are displayed as
    expandable in the view. Expand entries to show
    all members. Together with the display of value and type, you can
    examine and traverse the low-level layout of object data.


    \table
        \row
            \i  \bold{Note:}

        \row
            \i  GDB, and therefore Qt Creator's debugger works for optimized
                builds on Linux and Mac OS X. Optimization can lead to
                re-ordering of instructions or removal of some local variables,
                causing the \gui{Locals and Watchers} view to show unexpected
                data.
        \row
            \i  The debug information provided by GCC does not include enough
                information about the time when a variable is initialized.
                Therefore, Qt Creator can not tell whether the contents of a
                local variable contains "real data", or "initial noise". If a
                QObject appears uninitialized, its value is reported as
                \gui {not in scope}. Not all uninitialized objects, however, can be
                recognized as such.
    \endtable


    The \gui{Locals and Watchers} view also provides access to the most
    powerful feature of the debugger: comprehensive display of data belonging
    to Qt's basic objects.

    To enable Qt's basic objects data display feature:
    \list
       \o  Select \gui Tools > \gui {Options...} > \gui Debugger >
           \gui{Debugging Helper} and check the \gui{Use Debugging Helper}
           checkbox.
       \o  The \gui{Locals and Watchers} view is reorganized to provide a
           high-level view of the objects.
    \endlist

    For example, in case of QObject, instead of displaying a pointer to some
    private data structure, you see a list of children, signals and slots.

    Similarly, instead of displaying many pointers and integers, Qt Creator's
    debugger displays the contents of a QHash or QMap in an orderly manner.
    Also, the debugger displays access data for QFileInfo and provides
    access to the "real" contents of QVariant.

    You can use the \gui{Locals and Watchers} view to change the contents of
    variables of simple data types, for example, \c int or \c float when the
    program is interrupted. To do so, click the \gui Value column, modify
    the value with the inplace editor, and press \key Enter (or \key Return).

    You can enable tooltips in the main editor displaying this information.
    For more information, see \l{Showing Tooltips in Debug Mode}.

    \note The set of watched items is saved in your session.

    \section1 Directly Interacting with Native Debuggers

    In some cases, it is convenient to directly interact with the command
    line of the native debugger. In Qt Creator, you can use the left
    pane of the \gui {Debugger Log} view for that purpose. When you press
    \key {Ctrl+Return}, the contents of the line under the text cursor
    are sent directly to the native debugger. Alternatively, you
    can use the line edit at the bottom of the view. Output is displayed in the
    right pane of the \gui {Debugger Log} view.

    \note Usually, you do not need this feature, because Qt Creator provides
    you with better ways to handle the task. For example, instead of using the
    GDB \c print command from the command line, you can create a watcher item
    in the \gui{Locals and Watchers} view and examine the expression there.

    \section1 Debugging C++ Based Applications

    The following sections describe additional debugging functions that apply
    only to debugging C++.

    \section2 Starting the Debugger from the Command Line

    You can use the Qt Creator debugger interface from the command line. To
    attach it to a running process, specify the process ID as a parameter for
    the \c {-debug} option. To examine a core file, specify the file name.
    Qt Creator executes all the necessary steps, such as searching for
    the binary that belongs to a core file.

    For example:

    \list

        \o \c {C:\qtcreator\bin>qtcreator -debug 2000}

        \o \c {C:\qtcreator\bin>qtcreator -debug core.2000}

    \endlist

    For more information, see \l{Using Command Line Options}.

    \section2 Stepping into Frameworks in Mac OS

    In Mac OS X, external libraries are usually built into so-called Frameworks,
    which may contain both release and debug versions of the library. When you run
    applications on the Mac OS desktop, the release version of Frameworks is used
    by default. To step into Frameworks, select the \gui {Use debug versions of
    Frameworks} option in the project run settings for \gui Desktop and
    \gui {Qt Simulator} targets.

    \section2 Viewing Threads

    If a multi-threaded program is interrupted, the \gui Thread view or the
    combobox named \gui Thread in the debugger's status bar can be used to
    switch from one thread to another. The \gui Stack view adjusts itself
    accordingly.

    \section2 Viewing Modules

    The \gui{Modules} view displays information that the debugger plugin has
    about modules included in the application that is being debugged. A module
    is a dynamic link library (.dll) in Windows, a shared object (.so) in
    Linux, and a dynamic shared library (.dylib) in Mac OS.

    In addition, the view displays symbols within the modules and indicates
    where each module was loaded.

    Right-click the view to open a context menu that contains menu items for:

    \list

        \o Updating the module list

        \o Loading symbols for modules

        \o Examining modules

        \o Editing module files

        \o Showing symbols in modules

        \o Showing dependencies between modules (Windows only)

    \endlist

    By default, the \gui{Modules} view is hidden.

    \section2 Viewing Source Files

    The \gui{Source Files} view lists all the source files included in the project.
    If you cannot step into an instruction, you can check whether the source file is
    actually part of the project, or whether it was compiled
    elsewhere. The view shows the path to each file in the file system.

    Right-click the view to open a context menu that contains menu items for
    reloading data and opening files.

    By default, the \gui{Source Files} view is hidden.


    \section2 Viewing Disassembled Code and Register State

    The \gui{Disassembler} view displays disassembled code for the current
    function. The \gui{Registers} view displays the current state of the CPU's
    registers.

    The \gui{Disassembler} view and the \gui{Registers} view are both useful
    for low-level commands for checking single instructions, such as \gui{Step Into}
    and \gui{Step Over}. By default, both \gui{Disassembler} and
    \gui{Registers} view are hidden.

*/


/*!
    \contentspage index.html
    \previouspage creator-debugging.html
    \page creator-debugging-example.html
    \nextpage creator-debugger-operating-modes.html

    \title Debugging the Example Application

    This section uses the \l{Creating a Qt Widget Based Application}{TextFinder} example to
    illustrate how to debug Qt C++ applications in the \gui Debug mode.

    TextFinder
    reads a text file into
    QString and then displays it with QTextEdit.
    To look at the example QString, \c{line}, and see the
    stored data, place a breakpoint and view the QString object
    data, as follows:

    \list 1
        \o Click in between the line number and the window border on the line
        where we invoke \l{http://doc.qt.nokia.com/4.7/qtextedit.html#plainText-prop}{setPlainText()}
        to set a breakpoint.

        \image qtcreator-setting-breakpoint1.png

        \o Select \gui{Debug > Start Debugging > Start Debugging} or press \key{F5}.


        \o To view the breakpoint, click the \gui{Breakpoints} tab.

        \image qtcreator-setting-breakpoint2.png

        \o To remove a breakpoint, right-click it and select \gui{Delete Breakpoint}.


        \o To view the contents of \c{line}, go to the \gui{Locals and
    Watchers} view.

        \image qtcreator-watcher.png

    \endlist

    Modify the \c{on_findButton_clicked()} function to move back to
    the start of the document and continue searching once the cursor hits the
    end of the document. Add the following code snippet:

    \code
    void TextFinder::on_findButton_clicked()
    {
        QString searchString = ui->lineEdit->text();

        QTextDocument *document = ui->textEdit->document();
        QTextCursor cursor = ui->textEdit->textCursor();
        cursor = document->find(searchString, cursor,
            QTextDocument::FindWholeWords);
        ui->textEdit->setTextCursor(cursor);

        bool found = cursor.isNull();

        if (!found && previouslyFound) {
            int ret = QMessageBox::question(this, tr("End of Document"),
            tr("I have reached the end of the document. Would you like "
            "me to start searching from the beginning of the document?"),
            QMessageBox::Yes | QMessageBox::No, QMessageBox::Yes);

            if (ret == QMessageBox::Yes) {
                cursor = document->find(searchString,
                    QTextDocument::FindWholeWords);
                ui->textEdit->setTextCursor(cursor);
            } else
                return;
        }
        previouslyFound = found;
    }
    \endcode

    If you compile and run the above code, however, the application does not
    work correctly due to a logic error. To locate this logic error, step
    through the code using the following buttons:

    \image qtcreator-debugging-buttons.png

 */


/*!
    \contentspage index.html
    \previouspage creator-debugger-engines.html
    \page creator-debugging-helpers.html
    \nextpage creator-debugging-qml.html

    \title Using Debugging Helpers

    Qt Creator is able to show complex data types in a customized,
    user-extensible manner. For this purpose, it takes advantage of
    two technologies, collectively referred to as \e{Debugging Helpers}.

    Using the debugging helpers is not \e essential for debugging
    with Qt Creator, but they enhance the user's ability to quickly
    examine complex data significantly.

    \section1 Debugging Helpers Based on C++

    This is the first and original approach to display complex data
    types. While it has been superseded on most platforms by the more
    robust and more flexible second approch using Python scripting,
    it is the only feasible one on Windows/MSVC, Mac OS, and
    old Linux distributions. Moreover, this approach will automatically
    be chosen as fallback in case the Python based approach fails.

    During debugging with the C++ based debugging helpers,
    Qt Creator dynamically loads a helper library in form of a DLL or a
    shared object into the debugged process.
    The \QSDK package already contains a prebuilt debugging helper
    library. To create your own debugging helper library, select \gui{Tools} >
    \gui{Options...} > \gui{Qt4} > \gui{Qt Versions}. As the internal data
    structures of Qt can change between versions, the debugging helper
    library is built for each Qt version.


    \section1 Debugging Helpers Based on Python

    Qt Creator uses GDB builds that enable Python scripting to display
    information in the \gui {Locals and Watchers} view. When Python scripting
    is used, code (Debugging helpers) does not need to be injected into the
    debugged process to nicely display QStringList or \c std::map contents, for
    example.

    The code injection caused problems and put an extra stress on the debugged
    process. You can now easily extend the debugging helpers to other types. No
    compilation is required, just adding a few lines of Python.

    Python scripting vastly reduces the communication overhead compared
    with the previous solution. However, there are some obstacles:

    \list

        \o  There is no Python-enabled GDB for Mac OS. Mac OS continues
            injection with C++ based debugging helpers.

        \o  On the Symbian platform, an on-device debugging agent restricts the
            communication between GDB and the device. Therefore, extracting
            QObject properties, for example, is not possible.

        \o  There is no GDB to communicate with MSVC compiled applications on
            Windows. So information can be displayed nicely only in a limited
            fashion by using a cdb extension DLL.

    \endlist

    \section2 Extending the Python Based Debugging Helpers

    On platforms featuring a Python-enabled version of the GDB debugger,
    the data extraction is done by a Python script. This is more robust
    as the script execution is separated from the debugged process. It
    is also easier to extend as the script is less dependent on the
    actual Qt version and does not need compilation.

    To extend the shipped Python based debugging helpers for custom types,
    define one Python function per user defined type in the
    GDB startup file. By default, the following startup file is used:
    \c{~/.gdbinit}. To use another file, select \gui {Tools > Options... >
    Debugger > GDB}
    and specify a filename in the \gui {GDB startup script} field.

    The function name has to be qdump__NS__Foo, where NS::Foo is the class
    or class template to be examined. Nested namespaces are possible.

    The debugger plugin calls this function whenever you want to
    display an object of this type. The function is passed the following
    parameters:
    \list
       \o  \c d of type \c Dumper
       \o  \c item of type \c Item
    \endlist

    The function has to feed the Dumper object with certain information
    which is used to build up the object and its children's display in the
    \gui{Locals and Watchers} view.


    Example:

    \code
    def qdump__QVector(d, item):
        d_ptr = item.value["d"]
        p_ptr = item.value["p"]
        alloc = d_ptr["alloc"]
        size = d_ptr["size"]

        check(0 <= size and size <= alloc and alloc <= 1000 * 1000 * 1000)
        check(d_ptr["ref"]["_q_value"] > 0)

        innerType = item.value.type.template_argument(0)
        d.putItemCount(size)
        d.putNumChild(size)
        if d.isExpanded(item):
            p = gdb.Value(p_ptr["array"]).cast(innerType.pointer())
            with Children(d, [size, 2000], innerType)
                for i in d.childRange():
                    d.putSubItem(Item(p.dereference(), item.iname, i))
                    p += 1
    \endcode

    \section2 Item Class

    The Item Python class is a thin wrapper around values corresponding to one
    line in the \gui{Locals and Watchers} view. The Item members are as follows :

    \list

    \o \gui{__init__(self, value, parentiname, iname, name = None)} - A
       constructor. The object's internal name is created by concatenating
       \c parentiname and \c iname. If \c None is passed as \c name, a
       serial number is used.

    \o \gui{value} - An object of type gdb.Value representing the value to
        be displayed.

    \o \gui{iname} - The internal name of the object, constituting a dot-separated
    list of identifiers, corresponding to the position of the object's
    representation in the view.

    \o \gui{name} - An optional name. If given, is used in the
    \gui{name} column of the view. If not, a simple number in brackets
    is used instead.

    \endlist


    \section2 Dumper Class

    For each line in the \gui{Locals and Watchers} view, a string like the
    following needs to be created and channeled to the debugger plugin.
    \code
    "{iname='some internal name',
      addr='object address in memory',
      name='contents of the name column',
      value='contents of the value column',
      type='contents of the type column',
      numchild='number of children',        // zero/nonzero is sufficient
      childtype='default type of children', // optional
      childnumchild='default number of grandchildren', // optional
      children=[              // only needed if item is expanded in view
         {iname='internal name of first child',
          ... },
         {iname='internal name of second child',
          ... },
         ...
      ]}"
    \endcode

    While in theory, you can build up the entire string above manually, it is
    easier to employ the Dumper Python class for that purpose. The Dumper
    Python class contains a complete framework to take care of the \c iname and
    \c addr fields, to handle children of simple types, references, pointers,
    enums, known and unknown structs as well as some convenience methods to
    handle common situations.

    The Dumper members are the following:

    \list

    \o \gui{__init__(self)} - Initializes the output to an empty string and
        empties the child stack.

    \o \gui{put(self, value)} - Low level method to directly append to the
        output string.

    \o \gui{putCommaIfNeeded(self)} - Appends a comma if the current output
        ends in '}', '"' or ']' .

    \o \gui{putField(self, name, value)} - Appends a comma if needed, and a
         name='value' field.

    \o \gui{beginItem(self, name)} - Starts writing a field by writing \c {name='}.

    \o \gui{endItem(self)} - Ends writing a field by writing \c {'}.

    \o \gui{endChildren(self)} - Ends writing a list of children.

    \o \gui{childRange(self)} - Returns the range of children specified in
        the current \c Children scope.

    \o \gui{putItemCount(self, count)} - Appends a field  \c {value='<%d items'}
        to the output.

    \o \gui{putEllipsis(self)} - Appends fields
        \c {'{name="<incomplete>",value="",type="",numchild="0"}'}. This is
        automatically done by \c endChildren if the number of children to
        print is smaller than the number of actual children.

    \o \gui{putName(self, name)} - Appends a \c {name='...'} field.

    \o \gui{putType(self, type)} - Appends a field \c {type='...'} unless the
        \a type coincides with the parent's default child type.

    \o \gui{putNumChild(self, numchild)} - Appends a field \c {numchild='...'}
        unless the \c numchild coincides with the parent's default child numchild
        value.

    \o \gui{putValue(self, value, encoding = None)} - Append a file \c {value='...'},
        optionally followed by a field \c {valueencoding='...'}. The \c value
        needs to be convertible to a string entirely consisting of
        alphanumerical values. The \c encoding parameter can be used to
        specify the encoding in case the real value had to be encoded in some
        way to meet the alphanumerical-only requirement.
        Currently the following encodings are supported:

        \list
            \o 0: unencoded 8 bit data, interpreted as Latin1.

            \o 1: base64 encoded 8 bit data, used for QByteArray,
                double quotes are added.

            \o 2: base64 encoded 16 bit data, used for QString,
                double quotes are added.

            \o 3: base64 encoded 32 bit data,
                double quotes are added.

            \o 4: base64 encoded 16 bit data, without quotes (see 2)

            \o 5: base64 encoded 8 bit data, without quotes (see 1)

            \o 6: %02x encoded 8 bit data (as with \c QByteArray::toHex),
                double quotes are added.

            \o 7: %04x encoded 16 bit data (as with \c QByteArray::toHex),
                double quotes are added.
        \endlist

    \o \gui{putStringValue(self, value)} - Encodes a QString and calls
        \c putValue with the correct \c encoding setting.

    \o \gui{putByteArrayValue(self, value)} - Encodes a QByteArray and calls
        \c putValue with the correct \c encoding setting.

    \o \gui{isExpanded(self, item)} - Checks whether the item with the
        internal name \c item.iname is expanded in the view.

    \o \gui{isExpandedIName(self, iname)} - Checks whether the item with the
        internal name \c iname is expanded in the view.

        \o \gui{putIntItem(self, name, value)} - Equivalent to:
        \code
        self.beginHash()
        self.putName(name)
        self.putValue(value)
        self.putType("int")
        self.putNumChild(0)
        self.endHash()
        \endcode

        \o \gui{putBoolItem(self, name, value)} - Equivalent to:
        \code
        self.beginHash()
        self.putName(name)
        self.putValue(value)
        self.putType("bool")
        self.putNumChild(0)
        self.endHash()
        \endcode

    \o \gui{pushOutput(self)} - Moves the output string to a safe location
        from with it is sent to the debugger plugin even if further operations
        raise an exception.

    \o \gui{putCallItem(self, name, item, func)} -
        Uses GDB to call the function \c func on the value specified by
        \a {item.value} and output the resulting item. This function is
        not available when debugging core dumps and it is not available
        on the Symbian platform due to restrictions imposed by the on-device
        debugging agent.

    \o \gui{putItem(self, item)} - The "master function", handling
        basic types, references, pointers and enums directly, iterates
        over base classes and class members of compound types and calls
        \c qdump__* functions whenever appropriate.

    \o \gui{putSubItem(self, item)} - Equivalent to:
        \code
        with SubItem(self):
            self.putItem(item)
        \endcode
        Exceptions raised by nested function calls are caught and all
        output produced by \c putItem is replaced by the output of:
        \code
            ...
        except RuntimeError:
            d.put('value="<invalid>",type="<unknown>",numchild="0",')
        \endcode

    \endlist


    \section2 Children and SubItem Class

    The attempt to create child items might lead to errors if data is
    uninitialized or corrupted. To gracefully recover in such situations,
    use \c Children and \c SubItem \e{Context Managers} to create the nested items.

    The \c Children constructor \gui{__init__(self, dumper, numChild = 1,
    childType = None, childNumChild = None)} uses one mandatory argument and three
    optional arguments.  The mandatory argument refers to the current \c Dumper
    object.  The optional arguments can be used to specify the number \c numChild
    of children, with type \c childType_ and \c childNumChild_ grandchildren each.
    If \c numChild_ is a list of two integers, the first one specifies the actual
    number of children and the second the maximum number of children to print.

    Similarly, using the \c SubItem class helps to protect individual items.

    Example:
    \code
    d.putNumChild(2)
    if d.isExpanded(item):
        with Children(d):
            with SubItem(d):
                d.putName("key")
                d.putItem(Item(key, item.iname, "key"))
            with SubItem(d):
                d.putName("value")
                d.putItem(Item(value, item.iname, "value"))
    \endcode

    \section1 Debugging Helpers for QML

    The debugging helpers for QML provide you with code completion for custom modules
    (\c qmldump) and debugging Qt Quick UI projects (\c qmlobserver).

    You have to build the QML Observer once for each Qt version that you want to debug
    with. Select \gui{Tools > Options... > Qt4 > Qt Versions}.

    \note QML Observer requires Qt 4.7.1 or later.

    \section1 Enabling Debugging Helpers for Qt's Bootstrapped Applications

    Qt's bootstrapped applications (such as moc and qmake) are built in a way
    that is incompatible with the default build of the debugging helpers. To
    work around this, add gdbmacros.cpp to the compiled sources in the
    application Makefile.

    Choose \gui {Tools > Options > Debugger > Debugging Helper > Use debugging
    helper from custom location}, and specify an invalid location, such as
    \c{/dev/null}.

*/


/*!
    \contentspage index.html
    \previouspage creator-project-wizards.html
    \page creator-project-cmake.html
    \nextpage creator-project-generic.html

    \title Setting Up a CMake Project

    CMake is an alternative to qmake for automating the generation of build
    configurations.
    It controls the software compilation process by using simple configuration
    files, called CMakeLists.txt files. CMake generates native build
    configurations and
    workspaces that you can use in the compiler environment of your choice.

    Since Qt Creator 1.1, CMake configuration files are supported.
    Qt Creator 1.3 supports the Microsoft tool chain if the CMake version
    is at least 2.8.

    \section1 Setting the Path for CMake

    You can set the path for the \c CMake executable in \gui{Tools} >
    \gui{Options... > Projects > CMake}.

    \image qtcreator-cmakeexecutable.png

    \note Before you open a \c CMake project it is necessary to modify the
    \c{PATH} environment variable to include the bin folders of \c mingw and
    Qt Creator in the SDK.

    For instance, if you have the Qt SDK installed in your C drive,
    use the following command to set the environment variables in
    the command line prompt:
    \code
    set PATH=C:\qtsdk\mingw\bin;C:\qtsdk\qt\bin;
    \endcode
    Then start Qt Creator by typing:
    \code
    C:\qtsdk\bin\qtcreator.exe
    \endcode

    \section1 Opening CMake Projects

    To open a \c CMake project:
    \list 1
        \o  Select \gui{File} > \gui{Open File or Project...}.
        \o  Select the \c{CMakeLists.txt} file from your \c CMake project.
    \endlist

    A wizard guides you through the rest of the process.

    \note If the \c CMake project does not have an in-place build, Qt Creator
    lets you specify the directory in which the project is built
   (\l{glossary-shadow-build}{shadow build}).

    \image qtcreator-cmake-import-wizard1.png

    The screenshot below shows how you can specify command line arguments to
    \c CMake for your project.

    \image qtcreator-cmake-import-wizard2.png

    Normally, there is no need to pass any command line arguments for projects
    that are already built, as \c CMake caches that information.


    \section1 Building CMake Projects

    Qt Creator builds \c CMake projects by running \c make, \c mingw32-make, or
    \c nmake depending on your platform. The build errors and warnings are
    parsed and displayed in the \gui{Build Issues} output pane.

    By default, Qt Creator builds the \bold{all} target. You can specify which
    targets to build in \gui{Project} mode, under \gui{Build Settings}.

    \image qtcreator-cmake-build-settings.png

    Qt Creator supports multiple build configurations. The build
    directory can also be modified after the initial import.

    \section1 Running CMake Projects
    Qt Creator automatically adds \gui{Run Configurations} for all targets
    specified in the \c CMake project file.

    Known issues for the current version can be found
    \l{Known Issues}{here}.


    \section1 Adding External Libraries to CMake Projects

    Through external libraries Qt Creator can support code completion and
    syntax highlighting as if they were part of the current project or the Qt
    library.

    Qt Creator detects the external libraries using the \c FIND_PACKAGE()
    macro. Some libraries come with the CMake installation. You can find those
    in the \bold{Modules} directory of your CMake installation.

    \note If you provide your own libraries, you also need to provide your own
    \c FindFoo.cmake file. For more information, see
    \l{http://vtk.org/Wiki/CMake_FAQ#Writing_FindXXX.cmake_files}{CMake FAQ}.

    Syntax completion and highlighting work once your project successfully
    builds and links against the external library.
*/


/*!
    \contentspage index.html
    \previouspage creator-debugging-helpers.html
    \page creator-debugging-qml.html
    \nextpage creator-analyzer.html

    \title Debugging Qt Quick Projects

    \note You need Qt 4.7.1 or later to debug Qt Quick projects.

    \section1 Setting Up QML Debugging

    The process of setting up debugging for Qt Quick projects depends on the type of
    the project: Qt Quick UI or Qt Quick Application.

    To debug Qt Quick UI projects:

    \list 1

        \o Select \gui Projects, and then select the \gui QML check box in the
        \gui {Run Settings}, to enable QML debugging.

        \o Compile the QML Observer debugging helper. For more information, see
        \l{Debugging Helpers for QML}.

    \endlist

    To debug Qt Quick Applications:

        \list 1

        \o Select \gui Projects, and then select the \gui {Link QML debugging
        library} check box in \gui {Build Steps}.

        You might have to compile the library first, by selecting the
        \gui Compile link.

        \image qml-link-debugging-library.png "Build Steps"

        \note Debugging requires opening a socket at a well-known port, which
        presents a security risk. Anyone on the Internet could connect to the
        application that you are debugging and execute any JavaScript
        functions. Therefore, you must make sure that the port is properly
        protected by a firewall.

        \o In the \gui {Run Settings}, select the \gui QML check box to enable
        QML debugging.

        \o Select \gui {Build > Rebuild Project} to clean and rebuild the
        project.

    \endlist

    \section1 Starting QML Debugging

    To start the application, choose \gui {Debug > Start Debugging
    > Start Debugging} or press \key F5. Once the application starts running, it behaves
    and performs as usual. You can then perform the following tasks:

    \list

        \o Debug JavaScript functions

        \o Preview QML changes at runtime

        \o Inspect QML at runtime

    \endlist

    \section1 Debugging JavaScript Functions

    You can use the Qt Creator \gui Debug mode to inspect the state of your
    application while debugging. You can interact with the debugger in several
    ways, as described in the following sections:

    \list

        \o \l{Setting Breakpoints}

        \o \l{Viewing Call Stack Trace}

        \o \l{Locals and Watchers}

    \endlist

    \section1 Executing JavaScript Expressions

    When the application is interrupted by a breakpoint, you can use the \gui {QML
    Script Console} to execute JavaScript expressions in the current context. To
    open it, choose \gui {Window > View > QML Script Console}.

    \image qml-script-console.png "QML Script Console view"

    You can type JavaScript expressions and use them to get information about the
    state or your application. For example, property values.

    You can see the current value of a property by hovering over it in the code editor.

    \section1 Previewing QML Changes at Runtime

    If you change property values or add properties in the code editor, the changes
    are updated in the running application when you save them. If live preview is not supported
    for an element, a message appears. Click \gui Reload to preview the changes.

    Reloading is enabled by default. To disable it, click
    \inlineimage qml-observer-bar-reload.png "Apply Changes on Save button"
    on the toolbar.

    \section1 Inspecting QML at Runtime

    While the application is running, you can use the \gui {QML Observer} view to
    explore the object structure, debug animations, and inspect colors.
    To open the \gui {QML Observer} view, choose \gui {Window > View > QML Observer}.
    The view shows the properties of the currently selected QML element.

    \image qml-observer-view.png "QML Observer view"

    When you debug complex applications, you can use the observe
    mode to jump to the position in code where an element is defined. To switch to
    the observe mode, click
    \inlineimage qml-observer-bar-observe.png
    on the toolbar.

    Click elements in the running application to jump to their definitions in the code.
    Double-click elements to browse the element hierarchy. The hierarchy is displayed
    as bread crumbs in the \gui {QML Observer} view.

    To move the application running in \QQV to the front, select the
    \gui {Show Application on Top} button.

    You can also right-click an element in the running application to view the element
    hierarchy as a context menu. Select an element to jump to its definition in code.

    \image qml-observer-context-menu.png "QML Observer"

    To zoom in and out of the application, click the \gui Zoom button.

    To inspect colors, click the \gui {Color Picker} button. You can also click
    \inlineimage qml-observer-bar-copy-color.png "Copy Color button"
    to copy the color definition to the clipboard.

    \section1 Debugging Animations

    \image qml-observer.png

    To play and pause animations in the running application, select the
    \gui {Play/Pause Animations} button on the toolbar or \gui {Debugging >
    Animations > Pause}, or press
    \key {Ctrl+.}.

    To change the speed at which animations are played, select a value in \gui {Debugging
    > Animations} or click and hold down the \gui {Play/Pause Animations}
    button to select a value.

*/


/*!
    \contentspage index.html
    \previouspage creator-project-cmake.html
    \page creator-project-generic.html
    \nextpage creator-version-control.html

    \title Setting Up a Generic Project

    Qt Creator supports generic projects, so you can import existing projects
    that do not use qmake or CMake and Qt Creator ignores your build system.

    Generic project support allows you to use Qt Creator as a code editor. You
    can change the way your project is built by modifying the \c make command
    in the \gui{Projects} mode under \gui{Build Settings}.

    When you import a project, Qt Creator creates the following files that
    allow you to specify which files belong to your project and which include
    directories or defines you want to pass to your compile:
    \tt{.files}, \tt{.includes}, and \tt{.config}.


    \section1 Importing a Generic Project

    To import an existing generic project:
    \list 1
        \o Select \gui File > \gui{New File or Project...} >
           \gui{Other Project} > \gui{Import Existing Project}.
        \o In \gui{Import Existing Project}, enter the project name
           and select the location of the project file you want to import.

           Qt Creator automatically generates the following files in the
           project directory:
           \list
               \o \l{Specifying Files}{.files}
               \o \l{Specifying Include Paths}{.includes}
               \o \l{Specifying Defines}{.config}
               \o .creator
           \endlist
    \endlist

    When the project is successfully imported, Qt Creator creates the project
    tree in the sidebar.

    After importing a generic project into Qt Creator, open it by selecting the
    \tt{.creator} file.


    \section1 Working with Generic Project Files

    For a generic project, you have to manually specify which files belong to
    your project and which include directories or defines you want to pass to
    your compiler.


    \section1 Specifying Files

    The list of files for a generic project is specified in the \tt{.files}
    file. When you first create a generic project, Qt Creator adds any
    files it recognizes to your project.

    To add or remove files, edit the \tt{.files} file in Qt Creator.
    Qt Creator recreates your project tree when you save the \tt{.files} file.
    Alternatively, you can add and remove files using the context menu in the
    project tree.

    If you frequently need to update the \tt{.files} file, you can do so
    efficiently by using a script that updates the file for you. If the file
    is modified externally, you have to restart Qt Creator for the changes to
    take effect.

    To update the \tt{.files} on the \gui Git repository use the following
    script:
    \code
    git ls-files "*.cpp" "*.h" > MyProject.files
    \endcode

    \section1 Specifying Include Paths

    The include paths are specified in the \tt{.includes} file, one include
    path per line. The paths can be either absolute or relative to the
    \tt{.includes} file.

    \section1 Specifying Defines

    The defines are specified in the \tt{.config} file. The \tt{.config} file is
    a regular C++ file, prepended to all your source files when they are parsed.
    Only use the \tt{.config} file to add lines as in the example below:

    \code
    #define NAME value
    \endcode


    \section1 Creating a Run Configuration

    Qt Creator cannot automatically determine which executable to run.

    In the \gui{Projects} mode under \gui{Run Settings}, define the executable
    file to run:
    \list 1
        \o Click \gui Add and select \gui{Custom Executable}.
        \o Define the configuration name, the location of the executable, any
           additional arguments and the working directory.
    \endlist

*/



/*!

    \contentspage index.html
    \previouspage creator-design-mode.html
    \page creator-visual-editor.html
    \nextpage quick-projects.html

    \title Developing Qt Quick Applications

    You can either create Qt Quick projects from scratch or import existing projects to
    Qt Creator.

    You can use the code editor (\l{Using the Editor}{Edit mode}) or the visual editor
    (\l{Using Qt Quick Designer}{Design mode}) to develop Qt Quick applications.

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

    The following sections describe typical tasks you can do with Qt Creator.

    \list

        \o \l {Creating Qt Quick Projects}
        \o \l {Using Qt Quick Designer}
        \o \l {Creating Components}
        \o \l {Creating Buttons}
        \o \l {Creating Scalable Buttons and Borders}
        \o \l {Creating Screens}
        \o \l {Animating Screens}
        \o \l {Adding User Interaction Methods}
        \o \l {Exporting Designs from Graphics Software}
        \o \l {Implementing Application Logic}

    \endlist

*/


/*!

    \contentspage index.html
    \previouspage creator-visual-editor.html
    \page quick-projects.html
    \nextpage creator-using-qt-quick-designer.html

    \title Creating Qt Quick Projects

        \image qmldesigner-new-project.png "New File or Project dialog"

    When you create a new Qt Quick project from scratch, you have the following options:

    \list

        \o \gui {Qt Quick Application} creates a Qt Quick application project that can
        contain both QML and C++ code. The project includes a QDeclarativeView. You can build
        the application and deploy it on desktop and mobile target platforms. For example, you
        can create signed Symbian Installation System (SIS) packages for this type of projects.

        \o \gui {Qt Quick UI} creates a Qt Quick UI project with a single QML file that
        contains the main view. You can review Qt Quick UI projects in the QML Viewer and you
        need not build them. You do not need to have the development environment installed on your
        computer to create and run this type of projects.

        \o \gui {Custom QML Extension Plugin} creates a C++ plugin that makes it possible
        to offer extensions that can be loaded dynamically into applications by using the
        QDeclarativeEngine class.

    \endlist

    If you have existing QML applications that you want to run in Qt Creator or deploy
    to mobile devices, use the \gui {Qt Quick Application} wizard to convert them
    to Qt Quick applications.

    \section1 Creating Qt Quick UI Projects

    \list 1

        \o Select \gui {File > New File or Project > Qt Quick Project > Qt Quick UI
        > Choose...}.

        The \gui{Introduction and Project Location} dialog opens.

        \image qmldesigner-new-ui-project-location.png "Introduction and Project Location dialog"

        \o In the \gui Name field, give a name to the project.

        Do not use spaces and special characters in the project name and path.

        \o In the \gui {Create in} field, enter the path for the project files. For example,
        \c {C:\Qt\examples}. To select the path from a directory tree, click \gui Browse.

        \o Click \gui{Next}.

        \image qmldesigner-new-ui-project-summary.png "Project Management dialog"

        \o Review the project settings, and click \gui{Finish} to create the project.


    \endlist

    Qt Creator creates the following files:

    \list

    \o .qmlproject project file defines that all QML, JavaScript, and image
    files in the project folder belong to the project. Therefore, you do not
    need to individually list all the files in the project.

    \o .qml file defines an element, such as a component, screen, or the whole
    application UI.

    \endlist

    The \c import statement in the beginning of the .qml file specifies the
    \l {http://doc.qt.nokia.com/4.7/qdeclarativemodules.html} {Qt modules}
    to import. Each Qt module contains a set of default elements.
    Specify a version to get the features you want.

    To use JavaScript and image files in the application, copy them to the
    project folder.

    \section1 Creating Qt Quick Applications

    \list 1

        \o Select \gui {File > New File or Project > Qt Quick Project > Qt Quick Application
        > Choose...}.

        The \gui{Introduction and Project Location} dialog opens.

        \image qmldesigner-new-project-location.png "Introduction and Project Location dialog"

        \o In the \gui Name field, give a name to the project.

        Do not use spaces and special characters in the project name and path.

        \o In the \gui {Create in} field, enter the path for the project files. For example,
        \c {C:\Qt\examples}. To select the path from a directory tree, click \gui Browse.

        \o Click \gui{Next}.

        The \gui {Target Setup} dialog opens.

        \image qmldesigner-new-project-qt-versions.png "Target Setup dialog"

        \o Select the Qt versions to use as build targets for your project,
        and then click \gui{Next}.

        \note Qt Quick is supported since Qt 4.7, and therefore, only Qt 4.7 and later
        versions are displayed. Further, if you have only one supported Qt version installed,
        this dialog is skipped.

        The \gui {Mobile Options} dialog opens.

        \image qmldesigner-new-app-project-mobile-options.png "Mobile Options dialog"

        \o In the \gui {Orientation behavior} field, determine how the application
        behaves when the orientation of the device display rotates between portrait
        and landscape, and then click \gui Next.

        \note This dialog opens only if you select \gui Harmattan, \gui Maemo5,
        or
        \gui {Symbian Device} target in the \gui {Target Setup} dialog.

        The \gui {Symbian Specific} dialog opens.

        \image qmldesigner-new-project-symbian-options.png "Symbian Specific dialog"

        \o In the \gui {Application icon (.svg)} field, select an application
        icon for the \gui {Symbian Device} target, or use the default icon.

        \o In the \gui {Target UID3} field, specify the \l{Application UID}, or
        use the default UID.

        \note Qt Creator generates a UID for testing the application on a device.
        You need to change the UID when you deliver the application for public
        use.

        \o Click \gui Next.

        The \gui {Maemo Specific} dialog opens.

        \image qmldesigner-new-project-maemo-options.png "Maemo Specific dialog"

        \o In the \gui {Application icon (64x64)} field, select the application
         icon to use on Maemo or Harmattan targets, or use the default icon.

        The \gui {QML Sources} dialog opens.

        \image qmldesigner-new-project-qml-sources.png "QML Sources" dialog

        \o In the \gui {QML Main File} group, select \gui {Generate a .qml file},
        and then click \gui{Next}.

        The \gui {Project Management} dialog opens.

        \image qmldesigner-new-project-summary.png "Project Management" dialog

        \o In the \gui {Add to project} field, you can add this project to another
        project as a subproject.

        \o In the \gui {Add to version control} field, you can add the project to
        a version control system.

        \o Click \gui Finish to create the project.

    \endlist

    Qt Creator creates the necessary boilerplate files. Some of the files are
    specific to the Symbian, Maemo, or MeeGo Harmattan platform.

    \section1 Importing QML Applications

    If you have existing QML applications that you want to run in Qt Creator or deploy
    to mobile devices, use the \gui {Qt Quick Application} wizard and select the main
    .qml file in your project. All the other files in the project are automatically added
    to the application project.

    To import QML applications:

    \list 1

        \o Select \gui {File > New File or Project > Qt Quick Project > Qt Quick Application
        > Choose...}.

        \o Name the project and set its path, and then click \gui Next.

        \o Select the Qt versions to use as build targets for your project, and click
        \gui{Next}.

        \o Specify options for deploying the application to mobile device targets, and
        click \gui{Next}.

        \o In the \gui {QML Sources} dialog, select the \gui {Import an existing .qml file}
        option and specify the main .qml file of the project you want to import.

        \image qmldesigner-import-project.png "QML Sources" dialog

        \o Click \gui Next.

        \o Review the project settings, and click \gui{Finish} to create the project.

    \endlist

    Qt Creator adds references to the QML files to a project and creates the additional files
    necessary for deploying applications to mobile devices.

*/


/*!

    \contentspage index.html
    \previouspage creator-using-qt-quick-designer.html
    \page quick-components.html
    \nextpage quick-buttons.html

    \title Creating Components

    A QML component provides a way of defining a new type that you can re-use in other QML
    files. A component is like a black box; it interacts with the outside world
    through properties, signals, and slots, and is generally defined in its own QML file.
    You can import components to screens and applications.

    You can use the following QML elements to create components:

    \list

        \o \l{http://doc.qt.nokia.com/4.7/qml-borderimage.html}{Border Image}
        uses an image as a border or background.
        \o \l{http://doc.qt.nokia.com/4.7/qml-image.html}{Image}
        adds a bitmap to the scene. You can stretch and tile images.
        \o \l{http://doc.qt.nokia.com/4.7/qml-item.html}{Item}
        is the most basic of all visual items in QML. Even though it has no visual appearance,
        it defines all the properties that are common across visual items, such as the x and
        y position, width and height, anchoring, and key handling.
        \o \l{http://doc.qt.nokia.com/4.7/qml-rectangle.html}{Rectangle}
        adds a rectangle that is painted with a solid fill color and an optional border.
        You can also use the radius property to create rounded rectangles.
        \o \l{http://doc.qt.nokia.com/4.7/qml-text.html}{Text}
        adds formatted read-only text.
        \o \l{http://doc.qt.nokia.com/4.7/qml-textedit.html}{Text Edit}
        adds a single line of editable formatted text that can be validated.
        \o \l{http://doc.qt.nokia.com/4.7/qml-textinput.html}{Text Input}
        adds a single line of editable plain text that can be validated.
        \o \l{http://doc.qt.nokia.com/4.7-snapshot/qml-webview.html}{Web View}
        adds web content to a canvas.

    \endlist

    You can experiment with a set of Qt Quick components that are designed to
    appear native to the Symbian devices target platform. For more information,
    see
    \l{http://labs.qt.nokia.com/2011/04/08/qt-quick-components-for-symbian-technology-preview/}{Qt Quick components for Symbian Technology Preview}.

    You can dowload a set of commonly used UI-components for generic use in
    Qt Quick projects from
    \l{https://projects.forum.nokia.com/QMLTemplates}{QML Templates}. You can
    open and edit the templates in \QD.

    \section1 Creating Components in Qt Quick Designer

    \list 1

        \o Select \gui {File > New File or Project > Files and Classes > QML
        > Choose...} to create a new .qml file.

        \note Components are listed in the \gui {QML Components} section of the
        \gui Library pane only if the filename begins with a capital letter.

        \o Click \gui Design to open the .qml file in \QMLD.

        \o Drag and drop an item from the \gui Library pane to the editor.

        \o Edit item properties in the \gui Properties pane.

        The available properties depend on the item.

    \endlist

    The following sections contain examples of how to create some common components:

    \list

        \o \l{Creating Buttons}

        \o \l{Creating Scalable Buttons and Borders}

    \endlist

*/


/*!
    \contentspage index.html
    \previouspage quick-components.html
    \page quick-buttons.html
    \nextpage quick-scalable-image.html

    \title Creating Buttons

    To create a button component:

    \list 1

        \o Select \gui {File > New File or Project > QML > QML File > Choose...} to
         create a QML file called Button.qml (for example).

        \note Components are listed in the \gui Library pane only if the filename
        begins with a capital letter.

        \o Click \gui {Design} to edit the file in the visual editor.

        \o In the \gui Navigator pane, click \gui Rectangle to set properties
        for it.

        \o In the \gui Properties pane, modify the appearance of the button.

        \list a

            \o In the \gui Size field, set the width (\gui W) and height (\gui H)
            of the button.

            \o In the \gui Color field, select the button color.

            \o In the \gui Radius field, use the slider to set the radius of the
            rectangle and produce rounded corners for the button.

        \endlist

        \o Drag and drop a \gui {Text} item on top of the \gui Rectangle. This
        creates a nested element where \gui Rectangle is the parent element of
        \gui Text. Elements are positioned relative to their parents.

        \o In the \gui Properties pane, edit the properties of the \gui Text item.

        \list a

            \o In the \gui Text field, type \bold Button.

            You can select the text color, font, size, and style in the \gui Font
            section.

            \o In the \gui Alignment field, select the center buttons to align
            the text to the center of the button.

            \o Click \gui {Layout}, and then click the
            \inlineimage qmldesigner-anchor-fill-screen.png
            button to anchor the text to the whole button area.

        \endlist

        \o Press \key {Ctrl+S} to save the button.

        \image qmldesigner-button.png "Button component"

    \endlist

    \note To view the button, you must add it to a Qt Quick Application or Qt Quick UI
    project.

    To create a graphical button that scales beautifully without using vector graphics,
    use the \l{http://doc.qt.nokia.com/4.7/qml-borderimage.html}{Border Image}
    element. For more information, see \l{Creating Scalable Buttons and Borders}.

    */


    /*!

    \contentspage index.html
    \previouspage quick-buttons.html
    \page quick-scalable-image.html
    \nextpage quick-screens.html

    \title Creating Scalable Buttons and Borders

    You can use the \l{http://doc.qt.nokia.com/4.7/qml-borderimage.html}{Border Image}
    element to display an image, such as a PNG file, as a border and a background.

    Use two Border Image elements and suitable graphics to make it look like the button
    is pushed down when it is clicked. One of the Border Image elements is visible by default.
    You can specify that it is hidden and the other one becomes visible when the mouse
    is clicked.

    Add a MouseArea that covers the whole area and emits the clicked signal (\c {parent.clicked()})
    when it detects a mouse click.

    You can add text to the button and set it up as a property. The text can then be initialized
    from the outside, making the button a reusable UI component. The font size is also available
    in case the default size is too big. You can scale down the button text and use smooth text
    rendering for some extra quality.

    \image qmldesigner-borderimage.png "Graphical button"

    To create a graphical button:

    \list 1

        \o Select \gui {File > New File or Project > QML > QML File > Choose...} to create
        a QML file called Button.qml (for example).

        \o Double-click the file to open it in the code editor.

        \o Replace the \gui Rectangle with an \gui Item, as illustrated by the
        following code snippet:

        \qml
        Item {

        }
        \endqml

        \o Specify properties and set expressions for the \gui Item, as
        illustrated by the following code snippet:

        \snippet snippets/qml/quick-scalable-image.qml properties and signal definitions

        You will point to the properties and expression later.

        \o Click \gui {Design} to edit the file in the visual editor.

        \o Drag and drop two \gui BorderImage items from the \gui Library pane to
        the scene.

        \o Drag and drop a \gui Text item to the scene.

        \o Drag and drop a \gui MouseArea to the screen.

        \o In the \gui Navigator pane, select \gui border_image1 to specify
        settings for it in the \gui Properties pane:

        \list a

            \o Select \gui {Set Expression} in the menu next to the \gui Visibility
            check box.

            \o Enter the following expression to specify that the image is visible
            when the mouse is not pressed down: \c {!mouse_area1.pressed}.

            \o In the \gui Source field, select the image file for the
            button, for example button_up.png.

            \o Click \gui {Layout}, and then click the
            \inlineimage qmldesigner-anchor-fill-screen.png
            button to anchor the border image to the \gui Item.

        \endlist

        \o Select \gui border_image2 to specify similar settings for it:

        \list a

            \o Set the following epression for \gui Visibility, to specify that
            the image is visible when the mouse is pressed down:
            \c {mouse_area1.pressed}.

            \o In the \gui Source field, select the image file for the
            button when it is clicked, for example button_down.png.

            \o Click \gui {Layout}, and then click the
            \inlineimage qmldesigner-anchor-fill-screen.png
            button to anchor the border image to the \gui Item.

        \endlist

        \o Select \gui text1 to specify font size and color, and text
        scaling and rendering:

        \list a

            \o In the \gui Color field, use the color picker to select
            the font color, or enter a value in the field.

            \o In the \gui Text field, select \gui {Set Expression} and
            enter a pointer to the \c {text} property that you specified
            earlier: \c {parent.txt}.

            \o Select the \gui Aliasing check box to enable smooth text
            rendering.

            \o In the \gui Size field, select \gui {Pixels} to specify
            the font size in pixels. By default, the size is specified in
            points.

            \o In the \gui Size field, select \gui {Set Expression} and
            enter a pointer to the \c {fontSize} property that you specified
            earlier.

            \o Click \gui {Layout}, and then click the
            \inlineimage qmldesigner-center-in.png "Anchor buttons"
            buttons to inherit the vertical and horizontal centering from
            the parent.

            \o Click \gui Advanced to specify scaling for the text in the
            \gui Scale field.

            \o Select \gui {Set Expression} and enter the following expression:
            \c {if (!mousearea1.pressed) { 1 } else { 0.95 }}.

            \note You can enter long and complicated expressions also in the
            code editor.

        \endlist

        \o In the code editor, add to the \c MouseArea item
        a pointer to the \c clicked expression that you added earlier:
        \c {onClicked: parent.clicked()}.

    \endlist

    \note To view the button, you must add it to a Qt Quick Application or Qt
    Quick UI project.

*/


/*!

    \contentspage index.html
    \previouspage quick-scalable-image.html
    \page quick-screens.html
    \nextpage quick-animations.html

    \title Creating Screens

    You can use predefined QML elements and your own components to create screens.
    Typically, the main qml file in a Qt Quick project specifies the main window of an
    application.

    The QML files in the project folder are displayed in \gui {QML Components} in the
    \gui Library pane.

    You can dowload QML templates that specify different types of screens from
    \l{https://projects.forum.nokia.com/QMLTemplates}{QML Templates} for use in
    your Qt Quick projects. You can open and edit the templates in \QD.

    \section1 Adding Components to Screens

    \list 1

        \o Drag and drop components from the \gui Library pane to the editor.

        \o Select components in the \gui Navigator pane to edit their properties
        in the \gui Properties pane.

        For example, you can anchor components to a position on the screen.

    \endlist

    \section1 Using Data Models

    You can create the following types of views to organize items provided by
    \l{http://doc.qt.nokia.com/4.7/qdeclarativemodels.html}{data models}:

    \list

        \o \l{http://doc.qt.nokia.com/4.7/qml-gridview.html}{Grid View}
        provides a grid vizualization of a model.

        \o \l{http://doc.qt.nokia.com/4.7/qml-listview.html}{List View}
        provides a list vizualization of a model.

        \o \l{http://doc.qt.nokia.com/4.7/qml-pathview.html}{Path View}
        visualizes the contents of a model along a path.

    \endlist

    In the code editor, write the code to use the data models.

    \section1 Positioning Items on Screens

    You can use the following items to arrange items on screens:

    \list

        \o  \l{http://doc.qt.nokia.com/4.7-snapshot/qml-column.html}{Column}
            arranges its child items vertically.

        \o  \l{http://doc.qt.nokia.com/4.7-snapshot/qml-row.html}{Row}
            arranges its child items horizontally.

        \o  \l{http://doc.qt.nokia.com/4.7-snapshot/qml-grid.html}{Grid}
            arranges its child items so that they are aligned in a grid and
            are not overlapping.

        \o  \l{http://doc.qt.nokia.com/4.7-snapshot/qml-flow.html}{Flow}
            arranges its child items side by side, wrapping as necessary.

    \endlist

    \section1 Using States

    Use states and transitions
    to navigate between screens.

    QML states typically describe user interface configurations, such as the UI elements,
    their properties and behavior and the available actions. For example, you can use
    states to create two screens.

    To add states, click the empty slot in the \gui States pane. Then modify the new state
    in the visual editor.

    \image qmldesigner-states.png "States pane"

    The properties that you change in a state are highlighted with blue color.
    In the code editor, you can see the changes recorded as changes to the base state.

    To keep the QML code clean, you should create a base state that contains all the
    elements you will need in the application. You can then create states, in
    which you hide and show a set of items and modify their properties.
    This allows you to:

    \list

        \o Align items on different screens with each other.

        \o Avoid excessive property changes. If an item is invisible in the base
        state, you must define all changes to its child elements as property changes,
        which leads to complicated QML code.

        \o Minimize the differences between the base state and the other states
        to keep the QML code short and readable and to improve performance.

        \o Avoid problems when using transitions and animation when changing
        states.

    \endlist

    To create screens for an application by using states:

    \list 1

        \o In the base state, add all elements you will need in the application.
        While you work on one screen, you can click the
        \inlineimage qmldesigner-show-hide-icon.png
        icon to hide elements on the canvas that are not part of a screen.

        \o In the \gui States pane, click the empty slot to create a new state
        and give it a name. For example, \c Normal.

        \o In the \gui Properties pane, deselect the \gui Visibility check box
        or set \gui Opacity to 0 for each element that is not needed in this view.
        If you specify the setting for the parent element, all child elements
        inherit it and are also hidden.

        \image qmldesigner-screen-design.png "Designing screens"

        \o Create additional states for each screen and set the visibility or
        opacity of the elements in the screen.

        \o To determine which view opens when the application starts, use the code
        editor to set the state of the root item of the .qml file, as specified by the
        following code snippet:

        \qml
        Item {
            state: "Normal"
        }
        \endqml

    \endlist


*/


/*!

    \contentspage index.html
    \previouspage quick-screens.html
    \page quick-animations.html
    \nextpage quick-user-interaction.html

    \title Animating Screens

    To make movement between states smooth, you can specify transitions.
    You can use different types of animated transitions. For example, you can animate changes
    to property values and colors. You can use rotation animation to control the direction of
    rotation. For more information, see
    \l{http://doc.qt.nokia.com/4.7/qdeclarativeanimation.html}{QML Animation}.

    You can use the \c ParallelAnimation element to start several animations at the same time.
    Or use the \c SequentialAnimation element to run them one after another.

    You can use the code editor to specify transitions. For more information, see
    \l{http://doc.qt.nokia.com/4.7/qml-transition.html}{QML Transition Element}.

*/



/*!

    \contentspage index.html
    \previouspage quick-animations.html
    \page quick-user-interaction.html
    \nextpage quick-export-to-qml.html

    \title Adding User Interaction Methods

    You can add the following basic interaction methods to scenes:

    \list

        \o \l{http://doc.qt.nokia.com/4.7/qml-flickable.html}{Flickable}
        items can be flicked horizontally or vertically.
        \o \l{http://doc.qt.nokia.com/4.7/qml-flipable.html}{Flipable}
        items can be flipped between their front and back sides by using rotation,
        state, and transition.
        \o \l{http://doc.qt.nokia.com/4.7/qml-focusscope.html}{Focus Scope}
        assists in keyboard focus handling when building reusable QML components.
        \o \l{http://doc.qt.nokia.com/4.7/qml-mousearea.html}{Mouse Area}
        enables simple mouse handling.

    \endlist

*/


/*!

    \contentspage index.html
    \previouspage quick-user-interaction.html
    \page quick-export-to-qml.html
    \nextpage quick-application-logic.html

    \title Exporting Designs from Graphics Software

    You can export designs from graphics software, such as Adobe Photoshop and GIMP,
    to QML files. Each scene is converted into a single QML file with an Image or a
    Text element for each layer and saved on the development PC. Top-level layer
    groups are converted into merged QML Image elements.

    Note: GIMP does not support grouping, and therefore, each layer is exported as
    an item in GIMP.

    The following rules apply to the conversions:

    \list

        \o Layer names are used as element names. Spaces and hash marks (#) are
         replaced with underscore characters to create valid ids for the elements.

        \o Layer styles, such as drop shadows, are converted to images.

        \o Offset, size, ordering and opacity are preserved.

        \o Text layers are converted to Text elements, unless you specify that they
        be converted to Image elements.

        \o Hidden layers can be exported, and their visibility is set to hidden.

        \o PNG images are copied to the images subirectory.

    \endlist

    You can open the QML file in Qt Creator for editing. If you edit the file in Adobe
    Photoshop and export it to the same directory again, any changes you made in Qt
    Creator are overwritten. However, you can re-export graphical assets without
    recreating the QML code.

    If you create vector graphics with other tools that have an Adobe Photoshop export
    option,such as Adobe Illustrator, you can export them first to Photoshop and then
    to QML.

    \section1 Exporting from Adobe Photoshop to QML

    \image qml-export-photoshop.png

    The script has been tested to work on Adobe Photoshop CS 4 and 5, but it might also
    work on other versions.

    \list 1

        \o Download the export script, \e{Export QML.jx}, from
        \l{http://qt.gitorious.org/qt-labs/photoshop-qmlexporter/trees/master}{Gitorious}.

        \note Read the README.txt file in the repository for latest information about
        the script.

        \o Double-click the export script to add the export command to the \gui Scripts
        menu. You can also copy the script file to the Adobe Photoshop scripts directory
        (typically, \c{\Presets\Scripts} in the Photoshop installation directory).

        \o In Adobe Photoshop, choose \gui {File > Scripts > Export to QML} to export the
        scene to a QML file.

        \o In the \gui {Export Document to QML} dialog, enter a name and location for the
        QML file.

        \o Select the \gui {Rasterize text} check box to export text layers as images,
        not as Text elements.

        \o Select the \gui {Group layers} check box to export each top-level group as a
        merged QML Image element.

        \o Select the \gui {Export hidden} check box to export hidden layers and to set
        their visibility property to hidden.

        \o Deselect the \gui {Export QML} check box if you have modified the QML document
        in Qt Creator, but still want to re-export graphical assets.

        \o Click \gui Export.

    \endlist

    The QML file is saved to the location that you specified.
    In Qt Creator, choose \gui {File > Open File or Project} to open the QML file.

    \note Existing files are replaced without warning.

    \section1 Exporting from GIMP to QML

    \image qml-export-gimp.png

    The script has been tested to work on GIMP 2. You can download GIMP 2 from
    \l{http://www.gimp.org/downloads/}{GIMP Downloads}.

    To use the export script on Microsoft Windows, you also need to install the
    GIMP Python extension (Python, PyCairo, PyGobject, PyGTK). However, GIMP is
    not officially supported on Windows, so we cannot guarantee that this will
    work.

    \list 1

        \o On Microsoft Windows, you must first add Python support to your GIMP
        installation, as instructed in
        \l {http://www.gimpusers.com/tutorials/install-python-for-gimp-2-6-windows}{Tutorial: Installing Python for GIMP 2.6 (Windows)}.

        \o Download the export script, \e qmlexporter.py, from
        \l{http://qt.gitorious.org/qt-labs/gimp-qmlexporter/trees/master}{Gitorious}.

        \note Read the INSTALL.txt in the repository for latest information about the
        script.

        \o Copy the export script to the plug-ins directory in the GIMP installation
        directory.

        \o Check the properties of the file to make sure that it is executable.

        On Linux, run the following command: \c {chmod u+rx}

        \o Restart GIMP to have the export command added to the \gui File menu.

        \o Choose \gui {File > Export to QML} to export the design to a QML file.

        \o In the \gui {Export Layers to a QML Document} dialog, enter a name and
        location for the QML file, and click \gui Export.

    \endlist

    The QML file is saved to the location that you specified.
    In Qt Creator, choose \gui {File > Open File or Project} to open the QML file.

    \note Existing files are replaced without warning.

*/


/*!

    \contentspage index.html
    \previouspage quick-export-to-qml.html
    \page quick-application-logic.html
    \nextpage creator-using-qt-designer.html

    \title Implementing Application Logic

    A user interface is only a part of an application, and not really useful by itself.
    You can use Qt or JavaScript to implement the application logic. For more information on
    using JavaScript, see
    \l {http://doc.qt.nokia.com/4.7/qdeclarativejavascript.html} {Integrating JavaScript}.

    For an example of how to use JavaScript to develop a game, see the
    \l {http://doc.qt.nokia.com/4.7/qml-advtutorial.html} {QML Advanced Tutorial}.

 */


/*!
    \contentspage index.html
    \previouspage creator-editor-refactoring.html
    \page qt-quick-toolbars.html
    \nextpage creator-editor-locator.html

    \title Using Qt Quick Toolbars

    When you edit QML code in the code editor, you specify the properties
    of QML components. For some properties, such as colors and font names,
    this is not a trivial task. For example, few people can visualize the
    color #18793f.

    To easily edit these properties, you can use the Qt Quick Toolbars.
    When you select a component in the code and a toolbar is available,
     a light bulb icon appears:
    \inlineimage qml-toolbar-indicator.png
    . Select the icon to open the toolbar.

    To open toolbars immediately when you select a component, select
    \gui{Tools > Options... > Qt Quick > Qt Quick Toolbar > Always show Quick
    Toolbar}.

    Drag the toolbar to pin it to another location. Select
    \inlineimage qml-toolbar-pin.png
    to unpin the toolbar and move it to its default location. To pin toolbars
    by default, select \gui{Tools > Options... > Qt Quick > Qt Quick Toolbar
    > Pin Quick Toolbar}.

    \section1 Previewing Images

    The Qt Quick Toolbar for images allows you to edit the properties of
    \l{http://doc.qt.nokia.com/latest/qml-borderimage.html}{Border Image}
    and \l{http://doc.qt.nokia.com/latest/qml-image.html}{Image} components.
    You can scale and tile the images, replace them with other images,
    preview them, and change the image margins.

    \image qml-toolbar-image.png "Qt Quick Toolbar for images"

    To preview an image, double-click it on the toolbar. In the preview
    dialog, you can zoom the image. Drag the image margins to change them.

    \image qml-toolbar-image-preview.png "Image preview dialog"

    \section1 Formatting Text

    The Qt Quick Toolbar for text allows you to edit the properties of
    \l{http://doc.qt.nokia.com/latest/qml-text.html}{Text} components.
    You can change the font family and size as well as text formatting, style,
    alignment, and color.

    If a property is assigned an expression instead of a value, you
    cannot use the toolbar to edit it. The button for editing the property
    is disabled.

    \image qml-toolbar-text.png "Qt Quick Toolbar for text"

    By default, font size is specified as pixels. To use points, instead,
    change \gui px to \gui pt in the size field.

    \section1 Previewing Animation

    The Qt Quick Toolbar for animation allows you to edit the properties of
    \l{http://doc.qt.nokia.com/4.7/qml-propertyanimation.html}{PropertyAnimation}
    components and the components that inherit it. You can change the easing curve
    type and duration. For some curves, you can also specify amplitude, period,
    and overshoot values.

    \image qml-toolbar-animation.png "Qt Quick Toolbar for animation"

    Select the play button to preview your changes.

    \section1 Editing Rectangles

    The Qt Quick Toolbar for rectangles allows you to edit the properties of
    \l{http://doc.qt.nokia.com/4.7/qml-rectangle.html}{Rectangle}
    components. You can change the fill and border colors and add
    gradients.

    \image qml-toolbar-rectangle.png "Qt Quick Toolbar for rectangles"

    To add gradient stop points, click above the gradient bar. To remove
    stop points, drag them upwards.

*/


/*!
    \contentspage index.html
    \previouspage creator-editor-external.html
    \page creator-maemo-emulator.html
    \nextpage creator-mime-types.html

    \title Using Maemo or MeeGo Harmattan Emulator

    The Maemo 5 (Fremantle) and MeeGo Harmattan emulator are installed as part
    of the \QSDK. After they are installed, you can start them from Qt Creator.

    The Maemo 5 emulator emulates the Nokia N900 device environment. You can test
    applications in conditions practically identical to running the application
    on a Nokia N900 device with software update release 1.3 (V20.2010.36-2).

    The MeeGo Harmattan emulator emulates the Nokia N950 device environment.

    With the emulators, you can test how your application reacts to hardware
    controls, such as the power button, and to the touch screen.

    To test the application UI, user interaction with the application, and
    functionality that uses the mobility APIs, use the Qt Simulator,
    instead. For more information, see the
    \l{http://doc.qt.nokia.com/qtsimulator/index.html}{Qt Simulator Manual}.

    The difference between Qt Simulator and the emulators is that when you
    compile your application binary for Qt Simulator, it is compiled against a
    host library. The binary run on the emulator is compiled for the actual
    device, using the Maemo 5 or Harmattan tool chain.

    \section1 Starting the Emulator

    The \gui {Start Maemo Emulator} button is visible if you have a project
    open in Qt Creator for which you have added the Maemo or MeeGo Harmattan
    build target. It starts the Maemo or MeeGo Harmattan emulator, depending
    on the selected target.

    To start the emulator, click
    \inlineimage qtcreator-maemo-emulator-button.png "Start Maemo Emulator button"
    .

    Test your application on the Maemo emulator as on a device. For a list of
    keyboard shortcuts that you can use to emulate keys and functions, see
    \l {Emulating Device Keys}.

    \section1 Rendering Graphics

    The emulators support OpenGL to improve graphics rendering. Hardware
    acceleration produces better results than software rendering. By default,
    Qt Creator automatically detects, whether hardware acceleration is
    supported on the development PC and tries to use it. However, sometimes
    the results of the automatic detection are not reliable, and
    hardware acceleration might be selected even if it is actually not
    available on the development PC. This causes the emulator to crash.

    If the emulator crashes, you are asked whether you want to try software
    rendering, instead.

    To specify the OpenGL mode, select \gui {Tools > Options... > Maemo > Qemu
    Settings}.

    \section1 Emulating Device Keys

    The following table summarizes the keyboard shortcuts that you can use
    to emulate device keys and functions.

    \table
        \header
            \o Device Key
            \o Keyboard Shortcut
        \row
            \o \list
                \o Alphabet keys
                \o Comma (,)
                \o Period (.)
                \o Space
                \o Arrow keys
                \o Enter
                \o Backspace
               \endlist
            \o Respective keys on the development PC keyboard.
        \row
            \o Shift
            \o Left Shift key (Maemo 5)

               Shift (Harmattan)
        \row
            \o Ctrl
            \o Left Ctrl key (Maemo 5)

               Ctrl (Harmattan)
        \row
            \o Mode
            \o Left Alt key (Maemo 5)

               Alt (Harmattan)
        \row
            \o Power
            \o Esc
        \row
            \o Keypad slider open and close
            \o F1
        \row
            \o Keypad lock (Maemo 5 only)
            \o F2
        \row
            \o Camera lens open and close (Maemo 5 only)
            \o F3
        \row
            \o Camera focus
            \o F4
        \row
            \o Camera take picture
            \o F5

            \note The actual camera functionality is not emulated.
        \row
            \o Stereo headphones connect and disconnect (Maemo 5 only)
            \o F6
        \row
            \o Volume down
            \o F7
        \row
            \o Volume up
            \o F8
        \row
            \o Accelerometer x axis, negative
            \o 1
        \row
            \o Accelerometer x axis, positive
            \o 2
        \row
            \o Accelerometer z axis, negative
            \o 4
        \row
            \o Accelerometer z axis, positive
            \o 5
        \row
            \o Accelerometer y axis, negative
            \o 7
        \row
            \o Accelerometer y axis, positive
            \o 8

    \endtable

    \note Each press of the accelerometer key turns the acceleration by 50
    percent.

    \section1 Closing the Emulator

    To close the emulator, click the X at the top right corner of the device
    emulator view. The emulator interprets this as a press of the power button
    and displays the text \e {Shutting down} in the emulator window title pane.
    The emulator closes shortly after this.

*/


/*!
    \contentspage index.html
    \previouspage creator-version-control.html
    \page adding-plugins.html
    \nextpage creator-editor-external.html

    \title Adding Qt Designer Plugins

     You can use Qt APIs to create plugins that extend Qt applications.
     This allows you to add your own widgets to \QD.
     The most flexible way to include a plugin with an application is to compile it
     into a dynamic library that is shipped separately, and detected and loaded at runtime.

     The applications can detect plugins that are stored in the standard plugin
     subdirectories. For more information on how to create and locate plugins and to
     change the default plugin path, see \l{How to Create Qt Plugins}.

     For more information about how to create plugins for \QD, see
     \l{http://doc.qt.nokia.com/4.7/designer-using-custom-widgets.html}{Creating and Using Components for Qt Designer}.

    \section1 Locating Qt Designer Plugins

     \QD fetches plugins from the standard locations and loads the plugins
     that match its build key. \QD is delivered both as a standalone application
     and as part of the SDK, where it is integrated into Qt Creator.
     The correct folder to place the plugins depends on
     which one you use.

     The integrated \QD fetches plugins from the \c {%SDK%\bin\designer} folder on Windows
     and Linux. For information about how to configure plugins on Mac OS, see
     \l{Configuring Qt Designer Plugins on Mac OS}.

     To check which plugins
     were loaded successfully and which failed, choose \gui{Tools > Form Editor >
     About Qt Designer Plugins}.

     The standalone \QD is part of the Qt library used for building projects,
     located under \c {%SDK%\qt}. Therefore, it fetches plugins from the following folder:
     \c {%SDK%\qt\plugins\designer}. To check which plugins were loaded successfully and which
     failed, choose \gui{Help > About Plugins}.

     \section2 Configuring Qt Designer Plugins on Mac OS

     On the Mac, a GUI application must be built and run from a bundle. A bundle is a
     directory structure that appears as a single entity when viewed in the Finder.
     A bundle for an application typcially contains the executable and all the resources
     it needs.

     Qt Creator uses its own set of Qt Libraries located in the bundle, and therefore,
     you need to configure the \QD plugins that you want to use with Qt Creator.
     Fore more information about how to deploy applications on Mac OS, see
     \l{http://doc.qt.nokia.com/4.7/deployment-mac.html}{Deploying an Application on Mac OS X}.

     The following example illustrates how to configure version 5.2.1 of the
     \l{http://qwt.sourceforge.net/}{Qwt - Qt Widgets for Technical Applications} library
     for use with Qt Creator:

     \list 1

    \o To check the paths used in the Qwt library, enter the following \c otool command:

    \snippet examples/doc_src_plugins.qdoc 0

    The output for Qwt 5.2.1 indicates that the plugin uses Qt core libraries (QtDesigner,
    QtScript, QtXml, QtGui and QtCore) and libqwt.5.dylib:

    \snippet examples/doc_src_plugins.qdoc 1


     \o You must copy the \QD plugin and the Qwt library files to the following locations:

                 \list
                 \o \c {libqwt_designer_plugin.dylib} to \c {QtCreator.app/Contents/MacOS/designer}
                 \o \c {libqwt.*.dylib} to \c {QtCreator.app/Contents/Frameworks}
                 \endlist

    Enter the following commands:

    \snippet examples/doc_src_plugins.qdoc 4

    \o Enter the following \c otool command to check the libraries that are used by the
    Qwt library:

    \snippet examples/doc_src_plugins.qdoc 2

    The command returns the following output:

    \snippet examples/doc_src_plugins.qdoc 3

    \o Enter the following \c install_name_tool command to fix the references of the
    libraries:

    \snippet examples/doc_src_plugins.qdoc 5

    \endlist


     \section1 Matching Build Keys

     The Qt Creator that is included in pre-built SDK packages on Windows is built with the
     Microsoft Visual Studio compiler, whereas the version of Qt shipped for building applications
     is configured and built to use the MinGW/g++ compiler. Plugins built by using this version of
     Qt cannot be loaded by Qt Creator because the build-keys do not match. The plugins can only be
     used in the standalone version of \QD. Choose \gui{Help > About Qt Creator} to check
     the Qt version Qt Creator was built with.

     To use \QD plugins that were built for the shipped Qt version, make sure that
     Qt Creator is built with the same compiler by either recompiling Qt Creator using MinGW or
     recompiling Qt with Microsoft Visual Studio, depending on which configuration you want to
     use for your applications.

*/


/*!
    \contentspage index.html
    \previouspage creator-using-qt-designer.html
    \page creator-usability.html
    \nextpage creator-building-running.html

    \title Optimizing Applications for Mobile Devices

    Before starting application development, analyze and define the requirements, scope, and
    functionality of the application to ensure efficient functionality and a smooth user
    experience. Design the application for a single purpose and analyze how it can best serve
    its users. Mobile devices have been designed for use when mobile. Keep the characteristics
    of mobile devices in mind when you create applications for them.

    The following guidelines help you design and develop usable applications for mobile devices
    with varying characteristics, such as screen size and support for input methods:

    \list

        \o Know your users

        Find out who will use the application, what they will use it for,
        and which mobile devices they have. Then design the application to fit a specific context
        of use.

        \o Design for small screens

        The screen size of mobile devices is significantly smaller
        than that available on desktop devices. Carefully consider what is the most relevant
        content to present on the application UI, as it might not be reasonable to try and fit as
        much content into the screen as you might have in a desktop application.

       \o Design for multiple screen sizes

       Relate the position and size of each control to the
       dimensions of the display. This enables the same set of information to be presented on the
       screen in all resolutions; higher resolution devices just display finer graphics.

       \o Design for changing screen orientation

       Some devices support screen rotation. On these
       devices, applications can be displayed in portrait or landscape orientation. Account for
       orientation and dynamically adjust the display when the screen is rotated.

       \o Design intuitive ways of moving within applications

       Mobile devices lack a mouse and
       full-size keyboard, so users must use the touch screen or five way navigation pad to move within
       applications. In addition, many users control the devices with one hand. To create an optimized user
       experience, allow users to access information with one click; do not make them scroll and type.

       \o Design for limited input methods

       Applications collect information from users on the task
       at hand. In addition to touch screen input, some devices contain physical keys such
       as a five way navigation pad, a keypad, and a keyboard. Users enter information by using screen
       controls, such as lists, check boxes, radio buttons, and text fields.

       \o Keep response times short

       Latency can cause delays in user interaction. If users perceive
       an application as being slow, they are likely to get frustrated and stop using it.

       \o Save battery time

       Mobile devices are not constantly connected to a power source but run on
       battery power. Optimize power consumption to keep the total consumption at an acceptable
       level and to prevent users from running out of battery time.

       \o Consider network issues

       If users do not have a flat-rate data plan or WLAN support, mobile
       network connections cost them money. Also, when users move around with the devices, the networks
       available for connections constantly change.

       \o Remember the processing limits of the device


       The memory available on devices is limited
       and you should use it carefully. Although all mobile devices have common functionality,
       each device is individual in terms of both the resources available and extra features.
       Therefore, you must consider the constraints of all the target devices.

       \endlist

       For more information about user experience techniques for mobile devices, see the
       \l{http://library.forum.nokia.com/topic/Design_and_User_Experience_Library/GUID-A8DF3EB8-E97C-4DA0-95F6-F464ECC995BC_cover.html}{Design and User Experience Library}
       on Forum Nokia.

 */


/*!
    \contentspage index.html
    \previouspage creator-faq.html
    \page creator-tips.html
    \nextpage creator-known-issues.html

    \title Tips and Tricks


    \section1 Switching Between Modes

    Qt Creator uses different modes for different purposes. You can quickly
    switch between these modes with the following keyboard shortcuts:
    \list
        \o \gui Welcome mode \key Ctrl+1
        \o \gui Edit mode \key Ctrl+2
        \o \gui Design mode \key Ctrl+3
        \o \gui Debug mode \key Ctrl+4
        \o \gui Projects mode \key Ctrl+5
        \o \gui Help mode \key Ctrl+6
    \endlist


    For more information about Qt Creator modes, see \l {Qt Creator Modes}.



    \section1 Moving Between Open Files

    To quickly move between currently open files, press
    \key Ctrl+Tab.

    To move forward in the location history, press \key {Alt+Right}
    (\key {Cmd+Opt+Right} on Mac OS). To move backward, press \key {Alt+Left}
    (\key {Cmd+Opt+Left} on Mac OS). For example, if you use the \gui Locator
    to jump to a symbol in the same file, you can jump back to your original
    location in that file by pressing \key {Alt+Left}.


    \section1 Moving To the Edit Mode

    To move to the \gui Edit mode and currently active file, press
    \key Esc.

    If you already are in the \gui Edit mode:
    \list
        \o The first press moves focus to the editor
        \o The second press closes secondary windows
    \endlist

    \section1 Using the Filter in Options Dialog

    To find specific settings you require in \gui{Tools} > \gui{Options...}
    use the filter located at the top left of the \gui Options dialog box.

    \section1 Opening Output Panes

    The output panes provide a list of errors and warnings encountered during
    a build, detailed output from the compiler, status of a program when it is
    executed and debug output, as well as search results.

    To open output panes, use the following shortcuts:

    \list

        \o \gui{Build Issues} pane Alt+1 (Cmd+1 on Mac OS X)

        \o \gui{Search Results} pane Alt+2 (Cmd+2 on Mac OS X)

        \o \gui{Application Output} pane Alt+3 (Cmd+3 on Mac OS X)

        \o \gui{Compile Output} pane Alt+4 (Cmd+4 on Mac OS X)

    \endlist

    For more information about output panes, see \l{Viewing Output}.


    \section1 Using Keyboard Shortcuts

    Qt Creator provides \l{Keyboard Shortcuts}{many useful keyboard shortcuts}.
    You can see the keyboard shortcut for a menu command in the menu
    or the tooltip for a button.

    To customize, import or export keyboard shortcuts, select \gui Tools >
    \gui Options... > \gui Environment > \gui Keyboard.


    \section1 Running Qt Creator From Command Line

    You can launch Qt Creator from command line using the name of an
    existing session or \c .pro file by giving the name as the command
    argument.

    For example, running \tt{qtcreator somesession}, launches Qt Creator and
    loads session somesession.

    \note Make sure Qt Creator is included in the PATH environment variable.
    This can be done by typing the following in the command line:
    \code
    set PATH=c:\qtsdk\mingw\bin;c:\qtsdk\qt\bin;%PATH%
    \endcode


    \section1 Showing and Hiding the Sidebar

    To toggle the sidebar in the \gui Edit and \gui Debug modes, click
    \inlineimage qtcreator-togglebutton.png
    or press \key Alt+0 (\key Cmd+0 on Mac OS X).

    For more information on using the sidebar, see \l {Browsing Project Contents}.



    \section1 Moving To Symbols

    To move straight to a symbol used in a project, select the symbol in the
    \gui Editor toolbar drop-down menu. For more information on the editor toolbar,
    see \l {Using the Editor Toolbar}.

    To jump to a symbol in the current file, press \key {Ctrl+K} to open the
    \gui Locator, enter a period (.), and start typing the symbol name. Then
    select the symbol in the list. For more information on using the locator,
    see \l{Searching With the Locator}.

    Press \key Ctrl (\key Cmd on Mac OS) and click a symbol to move directly to
    the definition or the declaration of the symbol. You can also move the cursor
    on the symbol and press \key {F2}. For more information, see
    \l{Moving to Symbol Definition or Declaration}.



    \section1 Displaying Signals and Slots

    If an instance of a class is derived from QObject, and you would like to
    find all other objects connected to one of your object's slots using
    Qt's signals and slots mechanism, select \gui Tools > \gui Options...
    > \gui{Debugger} > \gui{Debugging Helper} > \gui{Use Debugging Helper}.

    In the \gui{Locals and Watchers} view, expand the object's entry and open
    the slot in the \e slots subitem. The objects connected to this slot are
    shown as children of the slot. This method works with signals too.

    For more information about the \gui{Locals and Watchers} view, see
    \l{Locals and Watchers}.


    \section1 Displaying Low Level Data

    If special debugging of Qt objects fails due to data corruption within the
    debugged objects, you can switch off the debugging helpers. When debugging
    helpers are switched off low-level structures become visible.

    To switch off the debugging helpers:
    \list 1

        \o Select \gui Tools > \gui Options... > \gui Debugger >
           \gui{Debugging Helper}.
        \o Uncheck the \gui{Use Debugging Helper} checkbox.
    \endlist


    \section1 Showing Tooltips in Debug Mode

    To inspect the value of variables from the editor, you can turn
    on tooltips. Tooltips are hidden by default for performance reasons.

    \list 1
        \o Select \gui Tools > \gui Options... > \gui Debugger > \gui General.
        \o Select the \gui {Use tooltips in main editor while debugging} check box.
    \endlist

    When you hover over a variable in the code editor in \gui Debug mode, a
    tooltip is displayed. To keep the tooltip visible, click the pin button.
    You can expand pinned tooltips to view their full content.

    \image qtcreator-pin-tooltip.png

    Pinned tooltips are stored in the session. To close all pinned tooltips,
    select \gui {Close Editor Tooltips} in the context menu in the \gui {Locals
    and Watchers} view.


    \section1 Locating Files

    The \gui Locator provides one of the easiest ways in Qt Creator to browse
    through projects, files, classes, methods, documentation and file systems.
    To quickly access files not directly mentioned in your project, you can
    create your own locator filters. That way you can locate files in a
    directory structure you have defined.

    To create locator filters, select \gui {Tools > Options... > Locator > Add}.

    For more information, see \l{Creating Locator Filters}.

    \section1 Adding a License Header Template for C++ Code

    A file containing a license header for C++ can be specified under
    \gui{Tools > Options... > C++ > License Template}. It may contain special
    placeholders enclosed in \c{%%} that are replaced when generating a
    new file:

    \list 1
        \o \c %YEAR%: Year
        \o \c %MONTH%: Month
        \o \c %DAY%: Day of the month
        \o \c %DATE%: Date
        \o \c %USER%: User name
        \o \c %FILENAME%: File name
        \o \c %CLASS%: Class name (if applicable)
        \o \c %$VARIABLE%: Contents of environment variable \c{VARIABLE}.
    \endlist

*/


/*!
    \contentspage index.html
    \previouspage creator-cli.html
    \page creator-keyboard-shortcuts.html
    \nextpage creator-faq.html

    \title Keyboard Shortcuts

    Qt Creator provides various keyboard shortcuts to speed up your development
    process.


    \section1 Configuring Keyboard Shortcuts

    To customize a keyboard shortcut:
    \list 1
        \o Select \gui Tools > \gui Options... > \gui Environment >
           \gui Keyboard.
        \o Select an action from the list.
        \o In \gui{Key Sequence} enter the shortcut key you want to associate
           with the selected action.
    \endlist

    Qt Creator allows you to use different keyboard shortcut mapping schemes:
    \list
        \o To import a keyboard shortcut mapping scheme, click \gui Import
           and select the kms file containing keyboard shortcut mapping scheme
           you want to import.
        \o To export the current keyboard shortcut mapping scheme, click
           \gui Export and select the location where you want to save the
           exported kms file.
    \endlist


    \section1 Default Keyboard Shortcuts

    The following tables list the default keyboard shortcuts. They are
    categorized by actions.


    \section2 General Keyboard Shortcuts

    \table
        \header
            \o Action
            \o Keyboard shortcut
        \row
            \o Open file or project
            \o Ctrl+O
        \row
            \o New file or project
            \o Ctrl+N
        \row
            \o Open in external editor
            \o Alt+V, Alt+I
        \row
            \o Cut
            \o Ctrl+X
        \row
            \o Copy
            \o Ctrl+C
        \row
            \o Paste
            \o Ctrl+V
        \row
            \o Redo
            \o Ctrl+Y
        \row
            \o Save
            \o Ctrl+S
        \row
            \o Save all
            \o Ctrl+A
        \row
            \o Close window
            \o Ctrl+W
        \row
            \o Close all
            \o Ctrl+Shift+W
        \row
            \o Go back
            \o Alt+Left
        \row
            \o Go forward
            \o Alt+Right
        \row
            \o Go to line
            \o Ctrl+L
        \row
            \o Next open document in history
            \o Ctrl+Shift+Tab
        \row
            \o Goto other split
            \o Ctrl+E, O
        \row
            \o Previous open document in history
            \o Ctrl+Tab
        \row
            \o Activate \gui Locator
            \o Ctrl+K
        \row
            \o Switch to \gui Welcome mode
            \o Ctrl+1
        \row
            \o Switch to \gui Edit mode
            \o Ctrl+2
        \row
            \o Switch to \gui Design mode
            \o Ctrl+3
        \row
            \o Switch to \gui Debug mode
            \o Ctrl+4
        \row
            \o Switch to \gui Projects mode
            \o Ctrl+5
        \row
            \o Switch to \gui Help mode
            \o Ctrl+6
        \row
            \o Toggle \gui{Build Issues} pane
            \o Alt+1 (Cmd+1 on Mac OS X)
        \row
            \o Toggle \gui{Search Results} pane
            \o Alt+2 (Cmd+2 on Mac OS X)
        \row
            \o Toggle \gui{Application Output} pane
            \o Alt+3 (Cmd+3 on Mac OS X)
        \row
            \o Toggle \gui{Compile Output} pane
            \o Alt+4 (Cmd+4 on Mac OS X)
        \row
            \o Activate \gui Bookmarks pane
            \o Alt+M
        \row
            \o Activate \gui{File System} pane
            \o Alt+Y
        \row
            \o Activate \gui{Open Documents} pane
            \o Alt+O
        \row
            \o Activate \gui Projects pane
            \o Alt+X
        \row
            \o Full screen
            \o Ctrl+Shift+F11
        \row
            \o Toggle the sidebar
            \o Alt+0 (Cmd+0 on Mac OS X)
        \row
            \o Undo
            \o Ctrl+Z
        \row
            \o Move to \gui Edit mode

               In \gui Edit mode:
               \list
                \o The first press moves focus to the editor
                \o The second press closes secondary windows
               \endlist
            \o Esc
    \endtable


    \section2 Editing Keyboard Shortcuts

    \table
        \header
            \o Action
            \o Keyboard shortcut
        \row
            \o Auto-indent selection
            \o Ctrl+I
        \row
            \o Collapse
            \o Ctrl+<
        \row
            \o Expand
            \o Ctrl+>
        \row
            \o Trigger a completion in this scope
            \o Ctrl+Space
        \row
            \o Copy line down
            \o Ctrl+Alt+Down
        \row
            \o Copy line up
            \o Ctrl+Alt+Up
        \row
            \o Cut line
            \o Shift+Del
        \row
            \o Join lines
            \o Ctrl+J
        \row
            \o Decrease font size
            \o Ctrl+- (Ctrl+Roll mouse wheel down)
        \row
            \o Increase font size
            \o Ctrl++ (Ctrl+Roll mouse wheel up)
        \row
            \o Toggle Vim-style editing
            \o Alt+V, Alt+V
        \row
            \o Split
            \o Ctrl+E, 2
        \row
            \o Split side by side
            \o Ctrl+E, 3
        \row
            \o Remove all splits
            \o Ctrl+E, 1
        \row
            \o Remove current split
            \o Ctrl+E, 0
        \row
            \o Select all
            \o Ctrl+A
        \row
            \o Go to block end
            \o Ctrl+]
        \row
            \o Go to block start
            \o Ctrl+[
        \row
            \o Go to block end with selection
            \o Ctrl+}
        \row
            \o Go to block start with selection
            \o Ctrl+{
        \row
            \o Move current line down
            \o Ctrl+Shift+Down
        \row
            \o Move current line up
            \o Ctrl+Shift+Up
        \row
            \o Trigger a quick fix in this scope
            \o Alt+Return
        \row
            \o Rewrap paragraph
            \o Ctrl+E, R
        \row
            \o Select the current block

               The second press extends the selection to the parent block
            \o Ctrl+U
        \row
            \o Enable text wrapping
            \o Ctrl+E, Ctrl+W
        \row
            \o Toggle comment for selection
            \o Ctrl+/
        \row
            \o Visualize whitespace
            \o Ctrl+E, Ctrl+V
        \row
            \o Delete
            \o Del
        \row
            \o Adjust size
            \o Ctrl+J
        \row
            \o Lay out in a grid
            \o Ctrl+G
        \row
            \o Lay out horizontally
            \o Ctrl+H
        \row
            \o Lay out vertically
            \o Ctrl+L
        \row
            \o Preview
            \o Alt+Shift+R
        \row
            \o Edit signals and slots
            \o F4
        \row
            \o Edit widgets
            \o F3
        \row
            \o Toggle bookmark
            \o Ctrl+M
        \row
            \o Go to next bookmark
            \o Ctrl+.
        \row
            \o Go to previous bookmark
            \o Ctrl+,
        \row
            \o Fetch snippet
            \o Alt+C, Alt+F
        \row
            \o Paste snippet
            \o Alt+C, Alt+P
        \row
            \o Find usages
            \o Ctrl+Shift+U
        \row
            \o Follow symbol under cursor

               Works with namespaces, classes, methods, variables, include
               statements and macros
            \o F2
        \row
            \o Rename symbol under cursor
            \o Ctrl+Shift+R
        \row
            \o Switch between method declaration and definition
            \o Shift+F2
        \row
            \o Open type hierarchy
            \o Ctrl+Shift+T
        \row
            \o Switch between header and source file
            \o F4
    \endtable

    \section2 Debugging Keyboard Shortcuts

    \table
        \header
            \o Action
            \o Keyboard shortcut
        \row
            \o Start debugging
            \o F5
        \row
            \o Stop or interrupt debugger
            \o Shift+F5
        \row
            \o Reset debugger
            \o Ctrl+Shift+F5
        \row
            \o Step over
            \o F10
        \row
            \o Step into
            \o F11
        \row
            \o Step out
            \o Shift+F11
        \row
            \o Toggle breakpoint
            \o F9
        \row
            \o Run to selected function
            \o Ctrl+F6
    \endtable


    \section2 Project Keyboard Shortcuts

    \table
        \header
            \o Action
            \o Keyboard shortcut
        \row
            \o Build project
            \o Ctrl+B
        \row
            \o Build all
            \o Ctrl+Shift+B
        \row
            \o New project
            \o Ctrl+Shift+N
        \row
            \o Run
            \o Ctrl+R
    \endtable


    \section2 Help Keyboard Shortcuts

    \table
        \header
            \o Action
            \o Keyboard shortcut
        \row
            \o View context-sensitive help
            \o F1
        \row
            \o Activate contents in \gui Help mode
            \o Ctrl+T
        \row
            \o Add bookmark in \gui Help mode
            \o Ctrl+M
        \row
            \o Activate index in \gui Help mode
            \o Ctrl+I
        \row
            \o Reset font size in \gui Help mode
            \o Ctrl+0
        \row
            \o Activate search in \gui Help mode
            \o Ctrl+S
    \endtable


    \section2 Version Control Keyboard Shortcuts

    \table
        \header
            \o {1,2} Action
            \o {5,1} Version control system
        \header
            \o CVS
            \o Git
            \o Perforce
            \o Subversion
            \o Mercurial
        \row
            \o Add
            \o Alt+C, Alt+A
            \o Alt+G, Alt+A
            \o
            \o Alt+S, Alt+A
            \o
        \row
            \o Commit
            \o Alt+C, Alt+C
            \o Alt+G, Alt+C
            \o
            \o
            \o Alt+H, Alt+C
        \row
            \o Diff
            \o Alt+C, Alt+D
            \o Alt+G, Alt+D
            \o
            \o Alt+S, Alt+D
            \o Alt+H, Alt+D
        \row
            \o Diff project
            \o
            \o Alt+G, Alt+Shift+D
            \o Alt+P, Alt+D
            \o
            \o
        \row
            \o Blame
            \o
            \o Alt+G, Alt+B
            \o
            \o
            \o
        \row
            \o Log
            \o
            \o Alt+G, Alt+L
            \o Alt+P, Alt+F
            \o
            \o Alt+H, Alt+L
        \row
            \o Log project
            \o
            \o Alt+G, Alt+K
            \o
            \o
            \o
        \row
            \o Status
            \o
            \o Alt+G, Alt+S
            \o
            \o
            \o Alt+H, Alt+S
        \row
            \o Undo changes
            \o
            \o Alt+G, Alt+U
            \o
            \o
            \o
        \row
            \o Diff project
            \o
            \o Alt+G, Alt+Shift+D
            \o Alt+P, Alt+D
            \o
            \o
        \row
            \o Edit
            \o
            \o
            \o Alt+P, Alt+E
            \o
            \o
        \row
            \o Opened
            \o
            \o
            \o Alt+P, Alt+O
            \o
            \o
        \row
            \o Revert
            \o
            \o
            \o Alt+P, Alt+R
            \o
            \o
        \row
            \o Submit
            \o
            \o
            \o Alt+P, Alt+S
            \o
            \o
    \endtable
*/


/*!
    \contentspage index.html
    \previouspage creator-known-issues.html
    \page creator-glossary.html
    \nextpage creator-acknowledgements.html

    \title Glossary

    \table
        \header
            \o  Term
            \o  Meaning

        \row
            \o
                \raw HTML
                Qt&nbsp;in&nbsp;PATH
                \endraw
                \target glossary-system-qt
            \o  This is the Qt
                version for the \c qmake command found in your \c PATH
                environment variable.
                This is likely to be the system's Qt version.


        \row
            \o
                \raw HTML
                Project&nbsp;Qt
                \endraw
                \target glossary-project-qt
            \o  The version of Qt configured in the \gui{Projects} mode, \gui {Build
                Settings}, \gui {Qt Version} field. This is the Qt version that
                is actually used by a particular project.

        \row
            \o
                \raw HTML
                Shadow&nbsp;build
                \endraw
                \target glossary-shadow-build
            \o  Shadow building means building a project in a separate
                directory, the \e{build directory}. The build directory is
                different from the source directory. One of the benefits of
                shadow building is that it keeps your source directory clean.
                Shadow building is the best practice if you need many build
                configurations for a single set of source.
    \endtable

*/


/*!
    \contentspage index.html
    \previouspage creator-tips.html
    \page creator-known-issues.html
    \nextpage creator-glossary.html

    \title Known Issues

    This section lists known issues in Qt Creator version 2.2.0.
    The development team is aware of them, and therefore, you do not need to
    report them as bugs.

    For a list of fixed issues and added features, see the changelog file in
    the \c{qtcreator\dist} folder or the \l{http://bugreports.qt.nokia.com}{Qt Bug Tracker}.

    \section1 General Issues

    \list

        \o If you change the Input Languages in Windows, Qt Creator might not
           respond for 30 seconds. This is a known issue in the Advanced Text
           Service of Microsoft Windows.

        \o Qt Creator uses SQLite for storing some of its settings. SQLite is
           known to have problems with certain NFS servers (most notably the
           nfs-user-server 2.2beta), since they can lock up the application
           when it tries to lock the database. If your home directory is on an
           NFS share and you encounter this issue, one option would be to
           switch to the nfs-kernel-server, or create a symlink so that the
           settings are stored locally.

        \o The Okteta KDE custom widget plugin might be installed as part of
           some Linux distributions. It can cause Qt Designer to crash. For
           more information, see:

           \list

           \o  \l{https://bugs.launchpad.net/ubuntu/+source/kdeutils/+bug/662005}{Ubuntu bug 662005}
           \o  \l{http://bugreports.qt.nokia.com/browse/QTBUG-12025}{QTBUG-12025}

           \endlist

           To resolve the issue, enter the following command to remove the package:
           \code
           sudo apt-get remove okteta
           \endcode
           Or delete the following file:
           \c /usr/lib/kde4/plugins/designer/oktetadesignerplugin.so.

    \endlist

    \section1 Editing Issues

    \list

        \o Code completion does not support typedefs for nested classes.

    \endlist

    \section1 Projects Issues

    \list
        \o Paths or file names containing spaces or special characters
           (such as colons, dollar signs, and hash marks) may cause problems. This
           is because some of the tools Qt Creator uses in the background have
           restrictions on the characters allowed in file and directory names.
           To be on the safe side, we recommend creating projects and project
           items with names consisting of plain characters, numbers,
           underscores, and hyphens.

        \o Creating new CMake projects with Qt Creator is not supported.

        \o On Windows, you must create projects for Maemo 5 and Harmattan
        targets on the same partition where
        you installed \QSDK, Qt Creator, and MADDE.

        \o If error messages displayed in the \gui {Compile Output} pane contain
        paths where slashes are missing (for example, C:QtSDK),
        check your PATH variable. For more information, see
        \l{Troubleshooting MinGW Compilation Errors}.

    \endlist

    \section1 Debugging Issues

    \list

        \o Debugging large applications on Symbian devices using the Symbian^3
           operating system might not work, because the on-device debugging agent
           might not be able to
           access memory when the operating system starts paging. This causes breakpoint
           handling and symbol resolution to fail. For more information, see
           \l{http://bugreports.qt.nokia.com/browse/QTCREATORBUG-2158}{QTCREATORBUG-2158}.

           As a workaround, add the following section to the application .pro file to
           disable paging:

           \code
           debug {
               MMP_RULES -= PAGED
               MMP_RULES *= UNPAGED
           }
           \endcode

           \note You must completely clean and rebuild the project for the setting to
           take effect.

        \o When debugging executables created by the GNU Compiler version 4.5.0
           (all platforms), some data types will not be displayed in the
           \gui{Locals and Watchers} view due to missing debug information.

        \o GDB on Windows may not work if the 'Embassy \reg Security Center' software
           by 'Wave \reg Systems' is installed and active (causing crashes in \c{vxvault.dll)}).

        \o GDB may take long to load debugging symbols, especially from large
           libraries.

        \o Setting breakpoints in code that is compiled into the binary more
           than once does not work.

        \o Setting breakpoints in files that do not have unique absolute
           paths may fail. For example, remounting parts of a file system
           using the --bind mount option.

    \endlist

    \section1 Qt Quick Designer Issues

    \list

        \o  \QMLD uses external processes (QML Puppet) to render and preview
            images and to collect data. Executing C++ code might cause the QML
            Puppet to crash. If it crashes, an error message is displayed and
            you can continue editing the QML file in the code editor.

    \endlist
*/


/*!
    \contentspage index.html
    \previouspage creator-glossary.html
    \page creator-acknowledgements.html

    \title Acknowledgements

    \section1 Third-party Components

    Qt Creator contains the following third-party components:

    \list
    \o  \bold{Open Source front-end for C++ (license MIT)}, enhanced for use in
        Qt Creator.\br
        Roberto Raggi <roberto.raggi@gmail.com>\br
        QtCreator/src/shared/cplusplus\br\br

    \o  \bold{Botan, a C++ crypto library. Version 1.8.8}\br
        \list
        \o  Copyright (C) 1999-2004 The Botan Project. All rights reserved.
        \o  Copyright (C) 1999-2009 Jack Lloyd
        \o  2001 Peter J Jones
        \o  2004-2007 Justin Karneges
        \o  2005 Matthew Gregan
        \o  2005-2006 Matt Johnston
        \o  2006 Luca Piccarreta
        \o  2007 Yves Jerschow
        \o  2007-2008 FlexSecure GmbH
        \o  2007-2008 Technische Universitat Darmstadt
        \o  2007-2008 Falko Strenzke
        \o  2007-2008 Martin Doering
        \o  2007 Manuel Hartl
        \o  2007 Christoph Ludwig
        \o  2007 Patrick Sona
        \endlist
        All rights reserved.\br\br

        Redistribution and use in source and binary forms, with or without
        modification, are permitted provided that the following conditions are
        met:\br\br

        1. Redistributions of source code must retain the above copyright
        notice, this list of conditions, and the following disclaimer.\br\br

        2. Redistributions in binary form must reproduce the above copyright
        notice, this list of conditions, and the following disclaimer in the
        documentation and/or other materials provided with the distribution.\br
        \br

        THIS SOFTWARE IS PROVIDED BY THE AUTHOR(S) "AS IS" AND ANY EXPRESS OR
        IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
        WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE,
        ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR(S) OR CONTRIBUTOR(S) BE
        LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
        CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
        SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
        BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
        WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE
        OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN
        IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.\br\br
        The source code of Botan C++ crypto library can be found
        here:
        \list
        \o QtCreator/src/libs/3rdparty
        \o \l{http://qt.gitorious.org/qt-creator/qt-creator/trees/master/src/libs/3rdparty}
        \endlist
        \br\br

    \o  \bold{NetSieben SSH Library is a Secure Shell client library for C++.
         Version 1.3.2}\br
        \list
        \o \bold{Commercial License:} For organizations who do not want to
            release the source code for their applications as open source/
            free software; in other words they do not want to comply with the
            GNU General Public License (GPL) or Q Public License.
        \o \bold{Non Commercial / Open Source License:} NetSieben believes in
            contributing back to the open source community, thus it has released
            the SSH Library under Q Public License as it is defined by Trolltech
            AS of Norway. The Open Source License allows the user to use software
            under an open source / free software license, and distribute it
            freely. The software can be used at no charge with the condition
            that if the user uses the SSH Library in an application they wish to
            redistribute, then the complete source code for your application must
            be available and freely redistributable under reasonable conditions.
            For more information on the used QPL License see:
            QtCreator/src/libs/3rdparty/net7ssh/LICENSE.QPL
        \endlist\br\br
        The source code of NetSieben Secure Shell C++ Library can be found
        here:
        \list
        \o QtCreator/src/libs/3rdparty
        \o \l{http://qt.gitorious.org/qt-creator/qt-creator/trees/master/src/libs/3rdparty}
        \endlist
     \endlist
*/


/*!
    \contentspage index.html
    \previouspage creator-mime-types.html
    \page creator-task-lists.html
    \nextpage creator-cli.html

    \title Showing Task List Files in the Build Issues Pane

    Code scanning and analysis tools create report files in ASCII format.
    Usually, the report files consist of lines that contain a file name, a line
    number, and an error message. A similar format is used for stack traces
    obtained from crash reports. Traditionally, you would fix the errors by
    manually navigating to them and correcting them, which is tedious.

    Qt Creator makes this very easy by providing a way to load these files into
    the \gui{Build Issues} pane. You can navigate to the corresponding source
    code by clicking the error message. But first you must convert the files to
    the \l{Task List File Format} by using conversion scripts that based on
    standard text processing tools of the operating system.

    In addition, you can generate task list files from code.
    For an example of a script that checks new lines of code and matches them
    against regular expressions to generate a task list, see \c{scripts\mytasks.pl}
    in the Qt Creator repository.

    To open task list files, choose \gui{File} > \gui{Open}.

    \section1 Task List File Format

    The filename extension must be .tasks for Qt Creator to recognize a file as a
    task list file.

    Each line in a task list file is treated as a tab-separated list of strings with
    \c{\t}, \c{\n}, and \c{\\} used as escape characters. The strings are used to create
    one task per line. The lines can have one of the following formats:

    \list

    \o \c description

    \o \c{type\tdescription}

    \o \c{file\ttype\tdescription}

    \o \c{file\tline\ttype\tdescription}

    \endlist

    The task type can have one of the following values:

    \list

    \o A string starting with \c err, which displays the error icon in the beginning of the line
    \o A string starting with \c warn, which displays the warning icon
    \o Any other value, which sets the task type to Unknown and does not
    display an icon

    \endlist

    The values are not case sensitive.

    Lines starting with the hash mark character (#) in the first column are ignored.

*/


/*!
    \contentspage index.html
    \previouspage creator-task-lists.html
    \page creator-cli.html
    \nextpage creator-keyboard-shortcuts.html

    \title Using Command Line Options

    You can start Qt Creator and specify some options from the command line.
    For example, you can open a file to any line.

    To specify command line options, enter the following command in the Qt Creator
    installation or build directory:

    \c {qtcreator [option] [filename[:line_number]]}

    \note You can use either a colon (:) or a plus sign (+) as a separator
    between the filename and line number. You can also use a space between the
    separator and the line number.

    For example:

    \list

        \o  \c {C:\qtcreator\bin>qtcreator -help}

        \o  \c {C:\qtcreator\bin>qtcreator C:\TextFinder\textfinder.cpp:100}

        \o  \c {C:\qtcreator\bin>qtcreator C:\TextFinder\textfinder.cpp +100}

    \endlist

    The following table summarizes the available options:

    \table
        \header
            \o Option
            \o Description

        \row
            \o -help
            \o Display help on command line options.

        \row
            \o -version
            \o Display Qt Creator version.

        \row
            \o -client
            \o Attempt to connect to an already running instance of Qt Creator.

        \row
            \o -noload <plugin>
            \o Do not load the specified plugin.

        \row
            \o -profile
            \o Output plugin start up and shut down profiling data.

        \row
            \o -settingspath <path>
            \o Override the default path where user settings are stored.

        \row
            \o -color <color>
            \o Core plugin: override the selected UI color.

        \row
            \o -disable-cdb
            \o Debugger plugin: disable the Microsoft Console Debugger (CDB)
            engine. For more information, see \l{Debugging}.

        \row
            \o -disable-gdb
            \o Debugger plugin: disable the GNU Symbolic Debugger (GDB) engine.

        \row
            \o -disable-sdb
            \o Debugger plugin: disable the Qt Script debugger engine.

        \row
            \o -debug <PID-or-corefile>
            \o Debugger plugin: attach to process ID or core file.

        \row
            \o -wincrashevent <event-handle>
            \o Debugger plugin: Attach to crashed processes by using the specified
            event handle.

        \row
            \o -customwizard-verbose
            \o ProjectExplorer plugin: display additional information when loading
            custom wizards. For more information about custom wizards, see
            \l{Adding New Custom Wizards}

        \row
            \o -lastsession
            \o ProjectExplorer plugin: load the last session when Qt Creator starts.
            Open the projects and files that were open when you last exited Qt Creator.
            For more information about managing sessions, see \l{Managing Sessions}.

    \endtable


    */


    /*!
    \contentspage index.html
    \previouspage creator-maemo-emulator.html
    \page creator-mime-types.html
    \nextpage creator-task-lists.html

    \title Editing MIME Types

    Qt Creator uses the
    \l{http://en.wikipedia.org/wiki/Internet_media_type}{Internet media type}
    (MIME type) of the file to determine which mode and editor to use for
    opening the file. For example, Qt Creator opens C++ source and header files
    in the C++ editor, and Qt widget based UI files (.ui) in \QD.

    To identify the MIME type of a file, Qt Creator uses matching by pattern
    and matching by contents. First, Qt Creator looks at the filename to check
    whether it matches the patterns specified for any MIME type. If no match is
    found, it checks the contents of the file for magic headers specified for the
    file.

    The magic headers can contain text strings or bytes. The type of the
    header value, string or byte, determines how Qt Creator interprets the
    value. Qt Creator searches for the value within a specified
    range in the files and takes the priority of the magic header into account.
    If you specify wide search ranges, openging files in Qt Creator might take
    a long time. Therefore, you are advised to use the recommended values for
    the range and priority of the magic header.

    If your files do not match the predefined MIME types, you can edit the
    MIME types to add filename extensions and magic headers. You cannot
    add new MIME types, however.

    To edit MIME types:

    \list 1

        \o  Select \gui {Tools > Options... > Environment > MIME Types}.

            \image qtcreator-mime-types.png "MIME Types"

        \o  In \gui {MIME Type}, select a MIME type.

        \o  In \gui Patterns, add the filename extension for the type of files
            that you want to identify as having this MIME type.

        \o  Click \gui Add to add \gui {Magic Headers}.

            \image qtcreator-mime-types-magic-header.png "Magic Header"

        \o  In the \gui Value field, specify a text string or bytes that
            appear in the files.

        \o  In the \gui Type field, select the type of the value.

        \note You are recommended not to change the range and priority, because
        it might cause problems when opening files in Qt Creator.

        \o  Click \gui OK.

    \endlist

    To revert all the changes you have made to the MIME type definitions,
    select \gui {Reset All}.

    \note If you now select \gui OK or \gui Apply, you permanently lose all
    your own patterns and magic headers. The changes are reverted the next
    time you start Qt Creator.

    */


    /*!
    \contentspage index.html
    \previouspage creator-analyzer.html
    \page creator-troubleshooting-debugging.html
    \nextpage creator-deployment.html

    \title Troubleshooting Debugger

    This section lists some typical problems that you might encounter while
    debugging and solutions to them.

    \section1 Cannot Launch Debugger

    Some anti-virus applications do not allow debuggers to retrieve data. For
    example, on Windows, launching the debugger might fail with the following
    message if the Avira AntiVir is installed on the development PC: \e{The
    inferior stopped because it received a signal from the operating system.
    Signal name:? signal meaning: Unknown signal.}

    Some versions of Avira AntiVir Desktop-Products contain known issues in
    various development environments, including Qt Creator. To fix the problem,
    Avira instructs you to update to version \c {avipbb.sys 10.0.22.22}. For
    more information, see
    \l{http://www.avira.com/en/support-for-business-knowledgebase-detail/kbid/805}{Restricted Usability of IDE/Debuggers since 2010-12-08}.

   \section1 Debugger Does Not Hit Breakpoints

    You might have created a release build that does not contain debug
    information. A GNU Compiler Collection (GCC) debug build has the \c {-g}
    option on the compiler command line. Check that this option is present in
    the \gui {Compile Output} pane. If it is not, adjust your build settings
    in the \gui {Projects} mode.

    \section1 Debugger Does Not Work

    If the debugger does not work properly, try the following:

    \list 1

        \o  Make sure you use at least Qt Creator 2.1.

        \o  Make sure the debugger is set up properly. For more information,
            see \l{Setting Up Debugger}.

        \o  In the \gui Debug mode, select \gui {Windows > Views > Debugger
            Log} to open the \gui {Debugger Log} view. Browse the contents of
            the pane on the right hand side to find out what went wrong.
            Always attach the contents of the pane to debugger-related
            questions to the Qt Creator mailing list (qt-creator@trolltech.com)
            or paste them to
            \l{http://creator.pastebin.com}{creator.pastebin.com} before
            asking questions in the IRC (on the #qt-creator channel at
            FreeNode).

    \endlist

    \section1 Pointer Variable Members Are Not Displayed Directly

    When you use the \gui {Locals and Watchers} view to inspect a pointer
    variable and expand the variable tree item, another tree item level
    is displayed. To directly display the members of the pointer variable,
    select \gui {Dereference Pointers Automatically} in the context menu in the
    \gui {Locals and Watchers} view.

    \section1 Built-in Debugger Is Slow During Startup and Runtime

    The Qt Creator for Windows installation packages install GDB from MinGW.
    Unfortunately, GDB is quite slow on Windows. Qt Creator does not cause
    this, as it interacts with GDB and adds custom dumpers for Qt types.

    \note You can use Qt Creator with MSVC on Windows for debugging.

    \section1 Debugger Displays <not in scope> Message

    The message is created by the debugging helpers. Qt Creator posts an
    expression to the GDB command line to invoke the debugging helpers.
    The expression includes the address of the object to examine. This
    address might be modified by GDB before the helper function is called. It
    is unclear why and when this happens, but if it happens, the debugging
    helpers operate on wrong data and come to wrong conclusions. Most likely,
    they find garbage and declare the variable to be <not in scope>.

    \section1 Application Crashes when Debugging on Mac OS X Snow Leopard

    You must use a workaround to use the DYLD_IMAGE_SUFFIX option in the
    \gui Projects tab on Mac OS X  Snow Leopard. For more information on the
    issue, see
    \l{http://wimleers.com/blog/dyld-image-suffix-causing-havoc-on-mac-os-x-snow-leopard}{DYLD_IMAGE_SUFFIX causing havoc on Mac OS X Snow Leopard}.

    To use the option, enter the following commands in the Terminal
    application:
           \code
           sudo mv /usr/lib/libSystem.B_debug.dylib /usr/lib/libSystem.B_debug.dylib.backup
           sudo cp /usr/lib/libSystem.B.dylib /usr/lib/libSystem.B_debug.dylib.backup
           \endcode

     \section1 Debugger Cannot Attach to Running Process on Linux

    GDB uses \c ptrace to attach to running processes. Some Linux distributions
    do not allow this, which stops all attempts to either directly attach to an
    existing process or use the \gui {Run in terminal} option in Qt Creator.

    The reasons for this are described in
    \l{https://wiki.ubuntu.com/SecurityTeam/Roadmap/KernelHardening#ptrace%20Protection}{KernelHardening}.

    However, the usefulness of this security measure seems dubious,
    because this feature can be easily disabled. With root permissions, you can
    disable the feature immediately by writing \c{0} into
    \c{/proc/sys/kernel/yama/ptrace_scope}. Even if you do not have elevated
    permissions, you can disable the feature later by adding a library that
    calls \c{prctl(0x59616d61, getppid(), 0, 0, 0);}, such as the one in
    \c{$QTCREATORDIR/lib/libptracepreload.so} to the LD_PRELOAD environment.

    */


    /*!
    \contentspage index.html
    \previouspage creator-debugging-qml.html
    \page creator-analyzer.html
    \nextpage creator-troubleshooting-debugging.html

    \title Detecting Memory Leaks

    You can use the Memcheck tool included in the
    \l{http://valgrind.org/info/tools.html}{Valgrind tool suite} to detect
    problems that are related to memory management in applications.

    \note Memcheck is supported on Linux and Mac OS.

    After you download and install Memcheck, you can use it from Qt Creator.
    To analyze applications, select \gui {Debug > Start Analyzer > Start}.
    While the application is running, Memcheck checks all reads and writes of
    memory and intercepts calls that allocate or free memory or create or
    delete memory blocks.

    If problems are found, they are listed in the \gui Analysis output pane.
    Select a link to move to the problematic code.

    \image analyzer_issues.png "Analysis output pane"

    */


    /*!
    \contentspage index.html
    \previouspage creator-help.html
    \page creator-advanced.html
    \nextpage creator-os-supported-platforms.html

    \title Advanced Use

    Qt Creator attempts to meet your development needs, whether you are an
    experienced Qt developer or a newcomer to Qt. When you install Qt Creator
    as a part of \QSDK, the default configuration allows you to start coding,
    building, running and debugging applications with very little effort.

    However, you can easily change or extend the default configuration, by
    choosing a different build system, adding project wizards, integrating
    external tools, or editing the standard MIME types that Qt Creator uses
    to recognize your files.

    You can start Qt Creator and specify some options for running it from the
    command line.

    This following topics describe advanced use of Qt Creator:

    \list
        \o \l{Operating Systems and Supported Platforms}
        \o \l{Adding New Custom Wizards}
        \o \l{Setting Up a CMake Project}
        \o \l{Setting Up a Generic Project}
        \o \l{Using Version Control Systems}
        \o \l{Adding Qt Designer Plugins}
        \o \l{Using External Tools}
        \o \l{Using Maemo or MeeGo Harmattan Emulator}
        \o \l{Editing MIME Types}
        \o \l{Showing Task List Files in the Build Issues Pane}
        \o \l{Using Command Line Options}
        \o \l{Keyboard Shortcuts}
        \o \l{Glossary}
    \endlist

    */