path: root/doc/qtcreator.qdoc

// **********************************************************************
// 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 2.0

    Qt Creator provides integrated tools for both application designers
    and developers to create applications for multiple desktop and mobile device
    platforms.

    For application designers, Qt Creator provides an integrated
    visual editor, \QD,
    \if defined(qtquick)
    and \QMLD
    \endif
    that you can use to design and develop
    application user interfaces.

    For application developers,
    Qt Creator provides a cross-platform, complete integrated development
    environment (IDE) that 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. To subscribe,
    send a message with the word \e subscribe to
    \l{mailto:qt-creator-request@trolltech.com}
    {qt-creator-request@trolltech.com}. For more information about Qt mailing
    lists, visit \l{http://lists.trolltech.com}{http://lists.trolltech.com}.

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

    \list
       \o \l{Introducing Qt Creator}
       \o \l{Operating Systems and Supported Platforms}
       \o \l{Quick Tour}
       \o \l{Getting Started}
           \list
               \o \l{Building and Running an Example Application}
               \o \l{Creating a Qt C++ Application}
               \o \l{Creating a Mobile Application with Nokia Qt SDK}
               \if defined(qtquick)
               \o \l{Creating a Qt Quick Application}
               \endif
           \endlist
       \o \l{Using the Editor}
            \list
                \o \l{Finding and Replacing}
                \o \l{Refactoring}
                \o \l{Searching With the Locator}
                \o \l{Pasting and Fetching Code Snippets}
                \o \l{Configuring the Editor}
                \o \l{Using FakeVim Mode}
                \o \l{Using an External Editor}
            \endlist
       \o \l{Managing Projects}
            \list
                \o \l{Creating a Project}
                \o \l{Setting Up a qmake Project}
                \o \l{Setting Up a CMake Project}
                \o \l{Setting Up a Generic Project}
                \o \l{Setting Up Development Environment for Maemo}
                \o \l{Setting Up Development Environment for Symbian}
                \o \l{Managing Sessions}
            \endlist
       \o \l{Building and Running Applications}
            \list
                \o \l{Building for Multiple Targets}
                \o \l{Specifying Build Settings}
                \o \l{Specifying Run Settings}
                \o \l{Specifying Editor Settings}
                \o \l{Specifying Dependencies}
            \endlist
       \if defined(qtquick)
       \o \l{Developing Qt Quick Applications}
       \endif
       \o \l{Optimizing Applications for Mobile Devices}
       \o \l{Using the Maemo Emulator}
       \o \l{Debugging}
            \list
            \o \l {Debugging Qt Applications}
            \list
                \o \l{Debugging the Example Application}
                \o \l{Interacting with the Debugger}
                \o \l{Setting Up Debugger}
                \o \l{Using Debugging Helpers}
            \endlist
            \if defined(qtquick)
            \o \l{Debugging Qt Quick Applications}
            \endif
            \if defined(qtquick)
                \list
                    \o \l{Using the QML Inspector}
                \endlist
            \endif
            \endlist
       \o \l{Using Version Control Systems}
       \o \l{Adding Qt Designer Plugins}
       \o \l{Tips and Tricks}
       \o \l{Keyboard Shortcuts}
       \o \l{Known Issues}
       \o \l{Glossary}
       \o \l{Acknowledgements}
    \endlist
*/


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

  \title Introducing Qt Creator

  Qt Creator provides you with tools to design and develop user interfaces and
  complex applications for multiple desktop and mobile
  platforms.

  \section1 Designing User Interfaces

  \if defined(qtquick)

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

  \endif

  \QD is a tool for designing and building graphical user interfaces (GUIs) from
  Qt widgets. You can compose and customize your widgets or dialogs and test
  them using different styles and resolutions.

  Widgets and forms created with \QD are integrated seamlessly with programmed code,
  using the Qt signals and slots mechanism, that lets you easily assign behavior to
  graphical elements. All properties set in \QD can be changed dynamically within the code.
  Furthermore, features like widget promotion and custom plugins allow you to use your
  own widgets with \QD.

    \if defined(qtquick)

  UIs that use widgets are clearly structured and enforce a platform look and feel,
  which makes them useful for traditional applications. However, they are static, and
  do not fully make use of the large high-resolution screens, touch input, and significant
  graphics power that are becoming common in portable consumer devices, such as mobile
  phones, media players, set-top boxes, and netbooks.

  \QMLD allows you to easily develop animations by using a declarative programming
  language called \l {http://doc.qt.nokia.com/4.7-snapshot/declarativeui.html}{QML}.
  In QML, a user interface is specified as a tree of objects with properties.

  You use a visual editor to create items, screens, and applications, as well as define changes
  in their state. \QMLD generates the necessary code for you.

  \note The visual \QMLD editor is provided as an experimental plugin that you must
  enable to be able to edit QML files in the \gui Design mode. Enabling the
  visual editor can negatively affect the overall stability of Qt Creator.

  You can edit the code in the code editor to add transitions from one state to another,
  and interaction to specify user actions that change the states. You
  can use Qt or JavaScript to implement the application logic.

  \endif

  \section1 Coding Applications

  As an IDE, Qt Creator differs from a text editor in that it knows how to build and run
  applications. It understands the code 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

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

      You can either create a project from scratch or import an existing
      project. Qt Creator generates all the necessary files, depending on the type of
      project you create. For example, if you choose to create a graphical user
      interface (GUI) application, Qt Creator generates an empty .ui file
      that you can modify with the integrated \QD.

      \if defined(qtquick)

      If you choose to create a Qt Quick application, Qt Creator generates a .qml file
      that you can modify with the \QMLD visual editor and the code editor.

      \endif
*/

/*!
    \contentspage index.html
    \previouspage creator-overview.html
    \page creator-os-supported-platforms.html
    \nextpage creator-quick-tour.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 XP Service Pack 2
        \o Windows Vista
        \o (K)Ubuntu Linux 7.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 Build Environment

    To build Qt Creator itself from the source, you need:
    \list
        \o Qt 4.7 or later
        \o On Windows, MinGW 4.4 or Microsoft Visual Studio 2008
    \endlist

    \section1 Supported Mobile Device Platforms
    You can develop applications for the following mobile device
    platforms:

    \list

    \o Symbian

    \o Maemo and Maemo Application Development and Debugging Environment (MADDE)

    \endlist

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

    \table
        \header
            \o {1,3} Operating system
            \o {3,1} Platform
        \header
            \o Desktop
            \o Symbian
            \o Maemo
        \row
            \o Windows
            \o Yes
            \o Yes
            \o Yes
        \row
            \o Linux
            \o Yes
            \o No
            \o Yes
        \row
            \o Mac OS X
            \o Yes
            \o No
            \o No
    \endtable
*/


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

    \title Quick Tour

    The figure below shows some of the components of Qt Creator in
    \gui{Edit} mode.

    \image qtcreator-breakdown.png

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

    \list
        \o \gui Welcome mode for opening recent sessions and projects.
        \o \gui{\l{Using the Editor}{Edit}} mode for editing project and source files.
        \if defined(qtquick)
        \o \gui{\l{Developing Application UI}{Design}} mode for designing and developing
           application user interfaces.
        \else
        \o \gui{\l{Using Qt Designer}{Design}} mode for designing and developing
           application user interfaces.
        \endif
        \o \gui{\l{Debugging}{Debug}} mode for inspecting the state of your program while
           debugging.
        \o \gui{\l{Managing Projects}{Projects}} mode for configuring project building and
           execution.
        \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

    Use the sidebar to browse files, projects and bookmarks.
    \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{File System} shows the content of the currently selected
           directory.
        \o \gui Bookmarks shows all bookmarks for the current session.
        \o \gui{Open Documents} shows currently open files.
    \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


    \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 list all files in a project, 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 toggle the synchronization of your project tree with the file
           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


    \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{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 open the \gui{General Messages} 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


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

           \image qtcreator-context-sensitive-help.png

        \o To select and configure how the documentation is displayed in the
           \gui Help mode, select \gui Tools > \gui Options... > \gui Help.
    \endlist

    \section2 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.6/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

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

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

    \if defined(qtquick)

    \section1 Developing Application UI

    To help you design the user interface of your application, two visual
    editors are integrated into Qt Creator:

    \list
    \o \QD
    \o \QMLD
    \endlist

    The integration includes project management and code completion.

    \endif

    \section1 Using Qt Designer

    Qt Creator automatically opens all .ui files in \QD.

    \image qtcreator-formedit.png

    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 change \QD properties, select \gui Tools > \gui Options... >
    \gui Designer.
    \list
        \o Set the class properties and code generation preferences in \gui
           {Class Generation}.
        \o Set an additional folder for saving templates in \gui{Template
           Paths}.
        \o Set the grid settings and preview preferences in \gui Forms. To
           preview your form with skins, enable \gui{Print/Preview
           Configuration} and select your skin. Otherwise default preview
           settings are used.

           To preview the settings, select \gui Tools > \gui{Form Editor} >
           \gui Preview, or press \key Ctrl+Alt+R.
        \o To specify embedded device profiles, such as style, font, and screen
           resolution, select \gui{Embedded Design}.
    \endlist

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

    \if defined(qtquick)

    \section1 Using Qt Quick Designer

    You can edit .qml files in the visual \QMLD 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.

    \note The visual \QMLD editor is provided as an experimental plugin that you must
    enable to be able to edit QML files in the \gui Design mode. Enabling the
    visual editor can negatively affect the overall stability of Qt Creator.

    To enable or disable the \QMLD visual editor, select
    \gui {Help > About Plugins... > Qt Quick > QmlDesigner}. You must restart Qt Creator
    to enable or disable 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 items in the scene. You can
    show and hide items to focus on specific parts of the application.

    \o \gui {Library} pane displays lists of predefined \gui {Items} and
    imported \gui {Resources} that you can use to design applications. The
    images and other files that you copy to the project folder appear in the
    \gui {Resources} pane.

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

    \o \gui {State} pane displays the different states of the component. To add
    states, click the empty slot. Then modify the new state in the editor.
    In the code editor, you can see the changes recorded as changes to
    the base state.

    \endlist

    \endif

*/


/*!
    \contentspage index.html
    \previouspage creator-qml-application.html
    \page creator-editor-using.html
    \nextpage creator-editor-finding.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.

    \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:
    \list
        \o To browse forward or backward through your location history, click
           \inlineimage qtcreator-back.png
           and \inlineimage qtcreator-forward.png
           .
        \o To go to any open file, select it from the \gui{Open files}
           drop-down menu.
        \o To jump to any symbol used in the current file, select it from the
           \gui Symbols drop-down menu.
    \endlist

    When you create or edit forms in a \c{.ui} file, the toolbar contains
    Qt Designer specific tools.


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


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


    \section1 Completing Code

    Qt Creator understands the code as code, not just as plain text. This
    allows it to help you to write well formatted code and to anticipate
    what you are going to write and complete the code.
    \if defined(qtquick)
    The code completion differs somewhat depending on whether you write Qt code or QML code.
    \endif

    \if defined(qtquick)

    \section2 Completing Qt Code

    \endif

    As you write code, Qt Creator provides a list of context-sensitive
    suggestions to the statement currently under your cursor.

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

    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 keyword
        \row
            \i  \inlineimage completion/macro.png
            \i  A macro
        \row
            \i  \inlineimage completion/namespace.png
            \i  A namespace
    \endtable

    \if defined(qtquick)

    \section2 Completing QML Code

    As you write QML code, Qt Creator suggests properties, IDs, and code
    snippets to complete the code. The snippets can consist of multiple
    fields 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 fields and specify values for them.

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

    \endif

    \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

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


    \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-locator.html
    \page creator-editor-codepasting.html
    \nextpage creator-editor-options.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-options.html
    \page creator-editor-fakevim.html
    \nextpage creator-editor-external.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 creator-editor-fakevim.html
    \page creator-editor-external.html
    \nextpage creator-project-managing.html

    \title Using an External Editor

    To open the file you are currently viewing in an external editor, select
    \gui Edit > \gui Advanced > \gui{Open in External Editor}.

    To use the external editor of your choice:
    \list 1
        \o Add the editor path to the \c{PATH} environment variable of your
           operating system.
        \o In Qt Creator select \gui Tools > \gui Options... >
           \gui Environment > \gui General.
        \o In \gui{External editor} enter the name of the application followed
           by \key Space and \tt{\bold %f}. For example, to open the file in
           Smultron, enter \tt{\bold{smultron %f}}.

           To further define how to open the file in the external editor, you
           can use the following variables separated by a space:
           \list
            \o Current line number \tt{\bold %l}
            \o Current column number \tt{\bold %c}
            \o Editor's x position on the screen \tt{\bold %x}
            \o Editor's y position on the screen \tt{\bold %y}
            \o Editor's width in pixels \tt{\bold %w}
            \o Editor's height in pixels \tt{\bold %h}
            \o Editor's width in characters \tt{\bold %W}
            \o Editor's height in characters \tt{\bold %H}
            \o To pass % symbol to the editor \tt{\bold %%}
           \endlist

           \note Not all variables work with all editors.
    \endlist
*/


/*!
    \contentspage index.html
    \previouspage creator-editor-codepasting.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}.

    You can perform the following configuration actions:
    \list
        \o Set the font preferences and apply syntax highlighting in
           \gui{Font & Colors}.
        \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 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. 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

    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.

    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

*/


/*!
    \contentspage index.html
    \previouspage creator-editor-using.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.6/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
*/


/*!
    \contentspage index.html
    \previouspage creator-editor-finding.html
    \page creator-editor-refactoring.html
    \nextpage creator-editor-locator.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 project:
    \list 1
        \o In the editor place the cursor on the symbol and select \gui Tools
           > \gui C++ > \gui{Find Usages} or press
           \key Ctrl+Shift+U.

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

    \if defined(qtquick)

    The functions used to rename symbols depends on whether you are
    writing C++ or QML code. For QML, you can only rename IDs.

    \endif

    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.

    \if defined(qtquick)

    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

   \endif
*/

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

    \title Managing Projects

    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 \l{Using Version Control Systems} {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 \l{Building for Multiple Targets} {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.2/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 watches are stored in
    \l{Managing Sessions}{sessions}. They are not considered to be part of the
    information shared across platforms.

    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.
    \list
       \o To use \bold{qmake} to build applications, open a \c .pro file. For more
          information, see \l{Setting Up a qmake Project}.
       \o To use \bold{CMake} to build applications you need to have CMake version
          2.8.0 or later installed. For more information, see
          \l{Setting Up a CMake Project}.
       \o To use \bold{other build systems} to build applications, specify which files belong to
          your project and which include directories or defines you want to pass
          to your compiler. For more information, see
          \l{Setting Up a Generic Project}.
    \endlist

    Qt Creator provides support for \l{Building and Running Applications}{building and running} Qt applications for
    desktop environment and mobile devices. When you install the Nokia Qt SDK,
    the build and run settings for the desktop, Maemo, and Symbian targets are set up
    automatically. However, you need to install and configure some additional software
    on the devices:

    \list

       \o \l{Setting Up Development Environment for Maemo}.

       \o \l{Setting Up Development Environment for Symbian}.

    \endlist

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

    Once your mobile application is ready, you can test it in the Qt Simulator.
    You can also connect Maemo and Symbian devices to your development PC and
    debug applications on the devices. After you have tested the application,
    you can deploy it on mobile devices.

    Developing applications for mobile devices is different from developing
    desktop applications. For more information, see
    \l{Optimizing Applications for Mobile Devices}.

    To change the location of the project directory, and to make changes in
    the build and run settings, select \gui{Tools} > \gui{Options...} >
    \gui{Projects} > \gui{General}.

    \section1 External Libraries

    Through external libraries Qt Creator can support code completion and
    syntax highlighting for external libraries as if they were a part of the
    current project or the Qt library.

    The procedure of adding a library to a project depends on the type of
    project, which influences the build system used.

    \list
       \o For information on adding external libraries to qmake projects, see
          \l{Adding External Libraries to a qmake Project}.
       \o For information on adding external libraries to CMake projects, see
          \l{Adding External Libraries to a CMake Project}.
   \endlist

*/


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

    \title Creating a Project

    You use wizards to create and import several types of projects and files, such
    as Qt GUI or console applications.
    \if defined(qtquick)
    and Qt Quick applications
    \endif
    You can also use
    wizards to add individual files to your projects. For example, you can create
    the following types of files:

    \list

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

        \if defined(qtquick)

        \o \QD forms and Qt QML files, which specify parts of application user
        interfaces

        \endif

        \o C++ class, source, or header files

    \endlist

    The wizards prompt you to enter the settings needed
    for that particular type of project and create the necessary files for you.

    \image qtcreator-new-project.png

    \section1 Using Project Wizards

    To create a new project:
    \list 1
        \o Select \gui File > \gui{New File or Project} and select the type of your
           project.

           The contents of the following dialogs depend on the project type.
           Follow the instructions of the wizard.
           This example uses \gui {Qt Gui Application}.

        \o Name the project and set its path. To select the path from a
           directory tree, click \gui Browse.

           Avoid using spaces and special characters in the project name and
           path.

           \image qtcreator-intro-and-location.png
        \o Specify the name of the class you want to create and using the
           drop-down menu select its base class type.

           Note that the \gui{Header file}, \gui{Source file} and
           \gui{Form file} fields are automatically updated as you name your
           class.

           \image qtcreator-class-info.png
        \o Review the project settings.

           To create the project, click \gui Finish.

           \image qtcreator-new-project-summary.png
    \endlist

    \section1 Adding New Project 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 use the wizard templates in the \c {share/qtcreator/templates/wizards}
    folder to create your own project and class wizards. Qt Creator looks in the
    folder and adds all wizards defined in wizard.xml files to the \gui New dialog
    that opens when you select \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
    projcet.

    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_example.xml as wizard.xml in the helloworld
    and 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"

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

        \endcode

        \list

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

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

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

        \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

    \section2 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%} 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}. Here, the filename would
        become myclass.h.

        \endlist

        \o The following code creates a page that allows users to select the class
        name, base class, and header and source files for the class:

        \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

*/


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

    \title Setting Up a qmake Project

    The qmake tool helps simplify the build process for development projects
    across different platforms. qmake automates the generation of makefiles
    so that only a few lines of information are needed to create each makefile.
    qmake can be used for any software project, whether it is written in Qt or not.

    The qmake tool generates a makefile based on the information in a project
    file that is generated by Qt Creator. It can generate makefiles for MinGW,
    Microsoft Visual studio, and CSL ARM in Windows, and GNU Compiler Collection
    (GCC) in Linux and Mac OS X.

    For more information about qmake, see the
    \l{http://qt.nokia.com/doc/4.2/qmake-manual.html}{qmake Manual}.

    \section1 Selecting the Qt Version

    Qt Creator allows you to have multiple versions of Qt installed on
    your development PC and use different versions for each of your projects.

    If Qt Creator finds \bold qmake in the \c{PATH} environment variable, it uses
    that version. The \l{glossary-system-qt}{ qmake version of Qt} is referred
    to as \bold{Qt in PATH}. If you intend to use only one version of Qt and it
    is already in the \c{PATH} and correctly set up for command line use, you do
    not need to manually configure your Qt version.


    \section2 Windows

    To add a Qt version for \bold MinGW:
    \list 1
        \o Select \gui Tools > \gui Options... > \gui Qt4 >
           \gui{Qt Versions}.
        \o Click \inlineimage qtcreator-windows-add.png
           and enter the name of the version in \gui{Version Name} field.
        \o Enter the qmake binary path in the \gui{qmake Location}.
        \o Enter the MinGW installation path in the \gui{MinGW Directory}.

           \image qtcreator-qt4-qtversions-win-mingw.png
    \endlist

    To add a Qt version for a \bold{Microsoft Visual C++} compiler:
    \list 1
        \o Select \gui Tools > \gui Options... > \gui Qt4 >
           \gui{Qt Versions}.
        \o Qt Creator automatically sets the correct environment variables for
           compilation. Select the internal version number of the installed
           Microsoft Visual C++ tool chain in the \gui Toolchain list.

           \image qtcreator-qt4-qtversions-win-msvc.png
    \endlist

    If you are using \bold{Qt for Symbian} and your S60 SDK is registered
    with devices.exe, Qt Creator automatically detects the Qt version. To add a
    Qt for Symbian version:
    \list 1
        \o Select \gui Tools > \gui Options... > \gui Qt4 >
           \gui{Qt Versions}.
        \o Select the \gui{S60 SDK} you want the Qt Creator to use.

           \image qtcreator-qt4-qtversions-win-symbian.png
        \o To build an application for your device using GCCE, enter the path
           to the \bold{CSL ARM Toolchain} directory in
           \gui{CSL\\GCCE Directory}.

           You do not need to specify this path if the compiler is included in
           the \c{PATH} environment variable.
        \o To build an application for the emulator (WINSCW toolchain), enter
           the path to your Carbide C++ installation directory in
           \gui{Carbide Directory}.

           \note You need to have Carbide C++ version 2.0 or later installed.
    \endlist

    \section2 Compiling Projects With Linux

    To compile a project in Qt Creator, Linux uses GNU Compiler Collection
    (GCC). Intel Compiler Collection (ICC) is supported as a drop-in
    replacement for GCC.

    To add a Qt version:
    \list 1
        \o Select \gui Tools > \gui Options... > \gui Qt4 >
           \gui{Qt Versions}.
        \o Click \inlineimage qtcreator-linux-add.png
           and enter the name of the version in \gui{Version Name}.
        \o Enter the path to the qmake binary in \gui{Path to qmake}.
    \endlist

    \section2 Compiling Projects With Mac OS X

    To compile a project in Qt Creator, Mac OS X uses GNU Compiler Collection
    (GCC), which is part of Xcode.

    To add a Qt version:
    \list 1
        \o Select \gui{Qt Creator} > \gui Preferences... > \gui{Qt Versions}.
        \o Click \inlineimage qtcreator-macosx-add.png
           and enter the name of the version in \gui{Version Name}.
        \o Enter the path to the qmake binary in \gui{Path to qmake}.

           \image qtcreator-qt4-qtversions.png
    \endlist

    \section1 Adding External Libraries to a qmake Project

    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.

    To add an external library:
    \list 1
        \o Open your project file (.pro) using the \gui Projects pane.
        \o Follow the instructions at \l{http://doc.qt.nokia.com/4.7-snapshot/qmake-project-files.html#declaring-other-libraries}
           {Declaring other Libraries}.
    \endlist

    Syntax completion and highlighting work once your project successfully
    builds and links against the external library.

*/


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

    \title Building and Running Applications

    Qt Creator provides support for building and running Qt applications for
    desktop environment and mobile devices. When you install the Nokia Qt SDK,
    the build and run settings for the desktop, Maemo, and Symbian targets are
    set up automatically.

    You can select the targets and click the \gui Run button to build and
    run the applications on the targets. You can click the \gui {Build All}
    button to build all open projects, one after another.

     \section1 Setting Up a Project

    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

    The project pane consists of the following tabs:
    \list
       \o \l{Building for Multiple Targets}{Targets}
       \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
    \gui{Select a Project} option at the top to navigate between different
    project edits.

*/


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

    \title Building for Multiple Targets

    Different build configurations allow you to quickly switch between
    different build settings. By default, Qt Creator creates \bold debug
    and \bold release build configurations.

    \section1 Building for Desktop

    \list 1

        \o Select \gui Desktop as the target.

        \o Click the \gui Run button.

    \endlist

    \section1 Building for 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/qt-simulator-beta/index.html}{Qt Simulator Manual}.

    \section1 Building for Maemo

    \list 1

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

        \o Build and run the application for \l{Using the Maemo Emulator}{Maemo Emulator}.

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

        \list 1

        \o Set up the MADDE development environment and specify a connection
        to the device. For more information, see
        \l{Setting Up Development Environment for Maemo}.

        \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 toolchain to
        build the application.

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

        Debugging also works transparently.

        \section2 Creating Installation Packages

        When you build the application for the \gui{Maemo} target, Qt
        Creator automatically generates a debian installation package
        in the project folder. You can deliver the installation package to
        users for installation on Maemo devices.

        You can add other files to the installation package in the
        \gui {Create package} step in the build configuration. Add files
        to the \gui {Package contents} field. In \gui {Local File Path},
        specify the location of the file on the development PC. In
        \gui {Remote File Path}, specify the folder to install the file on
        the device.

        \image qtcreator-maemo-deb-package.png "Create installation package"


    \section1 Building for Symbian

    \list 1

        \o Build and run the application for \l{Building for 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

    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, select it in the \gui {Tool chain} field
    in the \gui{General} section.

    \section2 Building and Running for a Device

    \list 1

        \o Install the required software on the device. For more information, see
        \l{Setting Up Development Environment for Symbian}.

        \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 \gui{App TRK} application on your device.

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

    \section3 Creating Installation Packages

    When you build 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.

    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 distributed commercially on Ovi
           Store.
    \endlist

    To get around these limitations, you need to go through the Symbian Signed
    process. 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.

    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{http://developer.symbian.org/wiki/index.php/Complete_Guide_To_Symbian_Signed}
    {Complete Guide to Symbian Signed}.

    When you have your own certificate and private key, you can specify them in
    the \gui{Create SIS Package} step in your build configuration.

    \image qtcreator-qt4-symbian-signing.png

    \section3 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, see
    \l{http://developer.symbian.org/wiki/index.php/Symbian_Signed_For_Distributing_Your_Application}{Symbian Signed For Distributing Your Application}.

    If you select a signing option that does not allow the application to access
    the defined capabilities, installing the application on mobile devices
    fails. To avoid problems, only define capabilities and link libraries to a project
    if you really need them.

    For more information about capabilities and how you can check which ones you
    need, see
    \l{http://developer.symbian.org/wiki/index.php/Capabilities_(Symbian_Signed)}{Capabilities (Symbian Signed)}
    and
    \l{http://doc.qt.nokia.com/4.7-snapshot/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-snapshot/qmake-platform-notes.html#capabilities}{Capabilities}.

    \section3 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, who 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.

    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-snapshot/qmake-platform-notes.html#unique-identifiers}{Unique Identifiers}.

    \section2 Building and Running for Symbian Emulator

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

    \section2 Troubleshooting

    If you cannot build the application, check if:
     \list
        \o You selected the Symbian Device target for building the application.
        \o The settings for the Qt version you use to build your project are
           correct. The path to the S60 SDK must point to the S60 SDK
           installation directory.  Select \gui Tools > \gui Options...
           > \gui Debugger > \gui{Symbian TRK} and check if it points to the
           debugger toolchain.
     \endlist
    If you cannot run the application on a device, check if:
     \list
        \o The device is connected through the USB cable in \e{PC Suite} mode.
        \o \gui{App TRK} is running on the device, using the USB connection,
           with the status \e connected.
        \o The device is detected and selected in the run configuration
           details.
     \endlist

    If you cannot run the application in the emulator, check if:
     \list
        \o You selected the \gui{Symbian Emulator} target for your application.
        \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

    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://qt.gitorious.org/qt-creator/pages/Home}{Qt Creator Development Wiki}.

*/


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

    \title Specifying Build Settings

    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 section \gui General, you can specify:
        \list
            \o The \l{glossary-project-qt}{Qt version} you want to use to
               build your project. For more information, see
               \l{Selecting the Qt version}.
            \o The tool chain required to build the project.
            \o 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.
               If you only build for one target platform, you can deselect
               the \gui{Shadow Build} checkbox.
        \endlist
    \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"

    \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. Activate custom steps by
           checking 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.

*/


/*!
    \contentspage index.html
    \previouspage creator-build-settings.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}.

    \if defined(qtquick)
    The settings to specify depend on the type of the project: qmake project
    or Qt Quick project.
    \endif

    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.

    \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 an USB cable.
    If only one device is detected, the application is deployed
    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 TRK version.

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

    \section2 Specifying Run Settings for Maemo Devices

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

    \image qtcreator-screenshot-run-settings.png "Run settings for Maemo 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.

    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"

    \if defined(qtquick)

    \section1 Specifying Run Settings for Qt Quick Projects

    Select run settings in the \gui {Run configuration} field. The settings
    are specified automatically and, usually, you do not need to change them:

    \list

        \o \gui {QML Viewer} is the path to the \QQV executable.

        \o \gui {QML Viewer arguments} sets arguments for running \QQV.
        The \c{-I <directory>} argument searches for C++ or QML plugins from
        the project folder. For a list of available arguments, enter \c {qml --help}
        on the command line.

        \o \gui {Main QML file} is the Qt Quick project file.

        \o \gui {Debugging address} is the IP address to access \QQV.

        \o \gui {Debugging port} is the port to access \QQV. You can use any
        free port in the registered port range.

    \endlist

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

    \endif

*/


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

    \title Specifying Editor Settings

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

    \image qtcreator-editor-settings.png "Editor Settings view"

*/


/*!
    \contentspage index.html
    \previouspage creator-editor-settings.html
    \page creator-build-dependencies.html
    \nextpage creator-visual-editor.html

    \title Specifying Dependencies

    If you have multiple projects loaded in your session, you can define the
    dependencies between them. Inter-project dependencies affect the build
    order of your projects.

    \note Inter-project dependencies are unrelated inside a qmake
    project.

    \image qtcreator-build-dependencies.png "Dependencies view"

    To define the dependencies between projects:
    \list 1
        \o In \gui Projects, select a project.
        \o Click \gui Dependencies.
        \o Select projects as dependencies.
    \endlist

*/


/*!
    \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
    \if defined(qtquick)
    and the integrated design tools, \QD and \QMLD,
    \endif
    to create, build, and run simple
    applications:

    \list
        \o \l{Building and Running an Example Application}
        \o \l{Creating a Qt C++ Application}
        \o \l{Creating a Mobile Application with Nokia Qt SDK}
        \if defined(qtquick)
        \o \l{Creating a Qt Quick Application}
        \endif
    \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 Nokia Qt SDK

    \note To complete this tutorial, you must install Nokia Qt SDK.
    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 Application 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{Select Required Qt Versions} dialog opens.

        \image qtcreator-mobile-project-qt-versions.png "Select Required Qt Versions dialog"

        \o Select \gui Maemo, \gui {Qt Simulator}, and \gui {Symbian Device} targets,
        and click \gui{Next}.

        \note Targets are listed if you installed the appropriate development
        environment, for example, as part of the Nokia Qt SDK.

        The \gui{Class Information} dialog opens.

        \image qtcreator-mobile-class-info.png "Class Information dialog"

        \o In the \gui{Class Name} field, type \bold {BatteryIndicator} as the class name.

        \o In the \gui{Base Class} list, select \bold {QDialog} 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-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.h
        \o batteryindicator.cpp
        \o main.cpp
        \o batteryindicator.ui
        \o BatteryIndicator.pro

    \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. You do not need
    to change the main.cpp file.

    \section1 Declaring the Qt Mobility API

    The \gui New wizard automatically adds information to the .pro file
    that you need when you use the Qt Mobility APIs or develop applications
    for Symbian devices. You must modify the information 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-1.0/quickstart.html}{Quickstart Example}.

    The following code snippet shows information that is needed for
    applications developed for Symbian device. Qt Creator generated
    the UID for testing the application on a device. You only need
    to change the UID and capabilities if you deliver the application
    for public use and need to have it Symbian Signed.

    \code

    symbian {
        TARGET.UID3 = 0xecbd72d7
        # TARGET.CAPABILITY +=
        TARGET.EPOCSTACKSIZE = 0x14000
        TARGET.EPOCHEAPSIZE = 0x020000 0x800000
    }

    \endcode

    \section1 Designing the User Interface

    \list 1

        \o In the \gui{Editor} mode, double-click the batteryindicator.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-snapshot/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.

    \endlist

    \section1 Completing the Header File

    The batteryindicator.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{batteryindicator.h} file
        to open it for editing.

        \o Include the System Info header file, as illustrated by the following
        code snippet:

        \snippet examples/batteryindicator/batteryindicator.h 1

        \o Add a shortcut to the mobility name space, as illustrated by the
        following code snippet:

        \snippet examples/batteryindicator/batteryindicator.h 2

        \o Declare a private function in the \c{private} section, after the
        \c{Ui::BatteryIndicator} function, as illustrated by the following code
        snippet:

        \snippet examples/batteryindicator/batteryindicator.h 3

    \endlist

    \section1 Completing the Source File

    Now that the header file is complete, move on to the source file,
    batteryindicator.cpp.

    \list 1

        \o In the \gui{Projects} view, double-click the batteryindicator.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/batteryindicator.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/batteryindicator.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 an USB cable and install the necessary software on them.

    \list 1

        \o Install Qt 4.6.2 libraries, the Qt mobile libraries, and the TRK
        debugging application on the device. For more information,
        see \l{Setting Up Development Environment for Symbian}.

        \o Start TRK 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 Emulator

    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.2 (V10.2010.19-1).

    For more information, see \l{Using the Maemo 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... >
        Animation Framework > Animated Tiles}.

        \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, Maemo or Symbian Device, 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 for 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, to toggle the orientation by clicking
        \gui {Rotate Device}, or choose from the various Symbian and Maemo
        configurations by clicking \gui {Device}. You can also simulate various
        mobile functions and create your own scripts.

        \o To test the application on a Symbian device install Qt 4.6.2
        and the TRK debugging application on the device. For more information,
        see \l{Setting Up Development Environment for Symbian}.

        \o Click the \gui {Target Selector} and select \gui {Symbian Device}.

        \o Click \gui Run to build the application for the Symbian device.

    \endlist

*/


/*!
    \if defined(qtquick)
    \contentspage index.html
    \previouspage creator-mobile-example.html
    \page creator-qml-application.html
    \nextpage creator-editor-using.html

    \title Creating a Qt Quick Application

    \note This tutorial assumes that you are familiar with the \l {http://doc.qt.nokia.com/4.7-snapshot/declarativeui.html}
    {QML declarative language}.

    \note The Qt Quick specific features and the QDeclarative help are based on a
    preview version of the QtDeclarative package. Update Qt Creator when Qt 4.7 is
    released.

    This tutorial describes how to use Qt Creator to create a small animated
    Qt Quick application, Hello World.

    \image qmldesigner-helloworld.png "Hello World"

    \section1 Creating the Hello World 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 Quick Project > Qt QML Application > Choose}.

        \image qmldesigner-new-project.png "New File or Project dialog"

        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, type \bold {Hello World}.

        \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{Project Management} dialog opens.

        \image qmldesigner-new-project-summary.png "Project Management dialog"

        \o Review the project settings, and click \gui{Finish} to create the project.

    \endlist

    The HelloWorld project now contains the following files:

    \list
        \o HelloWorld.qmlproject
        \o HelloWorld.qml
    \endlist

    \image qmldesigner-new-project-contents.png "HelloWorld project contents"

    The .qmlproject file defines that all QML, JavaScript, and image files in
    the project folder belong to the project. The .qml file contains some example
    code that specifies the screen size (200x200) and a label that contains
    the text \bold {Hello World}.

    \section1 Designing the User Interface

    \list 1

        \o In the \gui{Edit} mode, double-click the HelloWorld.qml file in
         the \gui{Projects} pane to open it in the code editor.

        \o To set the screen size to that of some Symbian devices in portrait
        mode, for example, change the \c width to \bold 240 and \c height to \bold 320.

        \image qmldesigner-helloworld-screen-size.png "Setting the screen size"

        \o Click \gui{Design} to design the UI in the visual editor.

        \note The visual \QMLD editor is provided as an experimental plugin that you must
        enable to be able to edit QML files in the \gui Design mode. Enabling the
        visual editor can negatively affect the overall stability of Qt Creator.

        \o Restart Qt Creator to enable the visual editor.

        \o Drag and drop a \gui {Rectangle} from the \gui {Library} pane to the
        scene.

        \image qmldesigner-helloworld-widget-add.png "Add component to Hello World"

        \o Edit the \gui {Properties} of the component to turn it into a red ball:

        \list a

            \o In the \gui {Colors} section, click the color picker to select a red
            color.

            \o In the \gui {Radius} field, use the slider to set the radius value
            to \bold 50.

            \image qmldesigner-helloworld-widget-edit.png "Edit the component"

        \endlist

        \o To create a blue ball, press \key {Ctrl+C} and \key {Ctrl+V} to copy
        and paste the red one, and then change its color to blue.

        \image qmldesigner-helloworld-base-state.png "Hello World first view"

        The first view of your application is now ready.

        \note You can use graphical design tools to create nice images and
        copy them to the projects folder to display them in the \gui {Library}
        pane in \gui {Resources}.

        \o In the \gui State pane, click the plus sign to add another view, or \e state
        to the application.

        \o Modify the state by dragging and dropping the widgets to switch their
        places.

        \image qmldesigner-helloworld-state1.png "Hello World second view"

    \endlist

    \section1 Animating the Scene

    Animate the scene so that the widgets appear to switch places
    on the screen.

    \list 1

        \o Click \gui {Edit} to open HelloWorld.qml in the code editor.

        \o Add the following code to create a transition:

        \code
            transitions: [
            Transition {
                NumberAnimation { properties: "x, y"; duration: 500 }
            }
        \endcode

        \note The code editor completes the code for you as you type.

        \o  Click the \inlineimage qtcreator-run.png
        button to check that the application can be built and run.

    \endlist

    \section1 Adding Interaction

    Add interaction to the scene to allow users to click on the screen to start
    the animation.

    \list 1

        \o Click \gui{Design} to open HelloWorld.qml in the visual editor.

        \o Drag and drop a \gui {Mouse Area} from the \gui {Library} to the scene.

        \o In the \gui {Properties} pane, \gui {Geometry} tab, click the
        \inlineimage qmldesigner-anchor-fill-screen.png
        button to make the mouse region cover the whole screen.

        \o In the code editor, use data binding to add a \c when statement to
        the states sections, as illustrated by the following code:

        \code

        states: [
            State {
                name: "State1"
                when: mousearea1.pressed
        \endcode

    \endlist

    \section1 Building and Running the Application

    \list 1

        \o Press \key {Ctrl+R} to build and run the application.

        \o Click the screen and keep the mouse button pressed down to run the
        animation.

    \endlist

    \note In the \gui {QML Viewer}, select \gui {Skin} and select a mobile device
    type to view the application as on a mobile device.

    \endif
*/


/*!
    \contentspage index.html
    \previouspage creator-build-example-application.html
    \page creator-writing-program.html
    \nextpage creator-mobile-example.html

    \title Creating a Qt C++ Application

    \note This tutorial assumes that you have experience in writing basic Qt
    applications, using \QD to design user interfaces and using the Qt
    Resource System.

    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-snapshot/uitools-textfinder.html}{Text Finder}
    example.

    \image qtcreator-textfinder-screenshot.png

    \section1 Setting Up Your Environment

    Qt Creator automatically detects whether the location of Qt is in your \c PATH variable.
    If you have installed several Qt versions, follow the
    instructions in \l{Selecting the Qt version} to set the Qt path.

    \section1 Creating the Text Finder 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 Application Project > Qt Gui
        Application > Choose}.

           \image qtcreator-new-project.png "New File or Project dialog"

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

        \image qtcreator-intro-and-location.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{Select Required Qt Versions} dialog opens.

        \image qtcreator-new-project-qt-versions.png "Select Required Qt Versions dialog"

        \o Click \gui{Next} to use the Qt version set in the path in your project.

        The \gui{Class Information} dialog opens.

        \image qtcreator-class-info.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.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} (\l{http://doc.qt.nokia.com/4.7-snapshot/qlabel.html}{QLabel})
    \o \gui{Line Edit} (\l{http://doc.qt.nokia.com/4.7-snapshot/qlineedit.html}{QLineEdit})
    \o \gui{Push Button} (\l{http://doc.qt.nokia.com/4.7-snapshot/qpushbutton.html}{QPushButton})

    \endlist

    \image qtcreator-textfinder-ui-widgets.png "Adding widgets to Text Finder UI"

    \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
    (\l{http://doc.qt.nokia.com/4.7-snapshot/qhboxlayout.html}{QHBoxLayout}).

    \image qtcreator-texfinder-ui-horizontal-layout.png "Applying horizontal layout"

    \o Drag and drop a \gui{Text Edit} widget (\l{http://doc.qt.nokia.com/4.7-snapshot/qtextedit.html}{QTextEdit})
    to the form.

    \o Select the screen area and click \gui{Lay out Vertically} (or press \gui{Ctr+V})
    to apply a vertical layout (\l{http://doc.qt.nokia.com/4.7-snapshot/qvboxlayout.html}{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-snapshot/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
    \l{http://doc.qt.nokia.com/4.7-snapshot/qtextedit.html}{QTextEdit}.

    \list 1

    \o In the \gui{Projects} 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} function, 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} view, double-click the textfinder.cpp file
    to open it for editing.

    \o Add code to load a text file using
    \l{http://doc.qt.nokia.com/4.7-snapshot/qfile.html}{QFile}, read it with
    \l{http://doc.qt.nokia.com/4.7-snapshot/qtextstream.html}{QTextStream}, and
    then display it on \c{textEdit} with
    \l{http://doc.qt.nokia.com/4.7-snapshot/qtextedit.html#plainText-prop}{setPlainText()}.
    This is illustrated by the following code snippet:

    \snippet examples/textfinder/textfinder.cpp 0

    \o To use \l{http://doc.qt.nokia.com/4.7-snapshot/qfile.html}{QFile} and
    \l{http://doc.qt.nokia.com/4.7-snapshot/qtextstream.html}{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-snapshot/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 your program.

*/


/*!
    \contentspage index.html
    \previouspage creator-qml-inspector.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 \bold{Version Control System}
            \i \bold{Address}
            \i \bold{Notes}
        \row
            \i  \bold{Git}
            \i  \l{http://git-scm.com/}
            \i
        \row
            \i  \bold{Subversion}
            \i  \l{http://subversion.tigris.org/}
            \i
        \row
            \i  \bold{Perforce}
            \i  \l{http://www.perforce.com}
            \i  Server version 2006.1 and later
        \row
            \i  \bold{CVS}
            \i  \l{http://www.cvshome.org}
            \i
        \row
            \i  \bold{Mercurial}
            \i  \l{http://mercurial.selenic.com/}
            \i  Qt Creator 2.0 and later
    \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.

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

    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.

    \section1 Creating VCS Repositories for New Projects

    Qt Creator allows for creating VCS repositories for version
    control systems that support local repository creation, such as
    Git or Mercurial.
    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.

    \section1 Using Version Control Systems

    The \gui{Tools} menu contains a sub-menu 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}
    (for Git and Mercurial) or \gui{Filelog} (for CVS, Perforce, and
    Subversion). 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

    To discard local changes to a file or project, use the \gui Revert
    function or the \gui {Undo Changes/Undo Repository Changes} function
    (for Git). The changes discarded depend on the version control system.

    For example, in Perforce, select \gui{Revert File/Revert Project}
    to discard changes made to open files, reverting them to the
    revisions last synchronized from the repository. Select
    \gui{Revert Unchanged} to revert files if their contents or file
    type have not changed after they were opened for editing.

    \section2 Using Additional Git Functions

    The \gui Git sub-menu contains the following additional items:

    \table

        \row
            \i  \gui {Apply Patch/Apply Patch...}
            \i  Apply changes to a file or project from a diff file. 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{Stash Snapshot...}
            \i  Save a snapshot of your current
                work under a name for later reference. For example, if you
                want to try out 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}
            \i  Stash local changes prior to executing a \gui{Pull}.
        \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.
        \row
            \i  \gui{Pull}
            \i  Pull changes from the remote repository. If there are locally
                modified files, you are prompted to stash those changes.
                The \gui Git options page contains an option to do
                a rebase operation while pulling.

        \row
            \i  \gui{Clean Repository.../Clean Project...}
            \i  Collect all files that are not under version control
                with the exception of patches and project files
                and show them as a checkable list in a dialog
                prompting for deletion. This lets you completely clean a build.

        \row
            \i  \gui{Branches...}
            \i  Displays the branch dialog showing the local branches at the
                top and remote branches at the bottom. To switch to the local
                branch, double-click on 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{Stashes...}
            \i  Displays a dialog showing the stashes created by
                \gui{Stash Snapshot...} with options to restore,
                display or delete them.
        \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.
    \endtable

    \section2 Using Additional Mercurial Functions

    The \gui Mercurial sub-menu contains the following additional items:

    \table
        \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{Update}
            \i  Look at an earlier version of the code.
    \endtable

    \section2 Using Additional Perforce Functions

    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 you do not use Perforce and want to turn
    off the check, clear this field.

    The \gui Perforce sub-menu contains the following additional items:

    \table
        \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.
        \row
            \i  \gui{Update All/Update Current Project}
            \i  Fetch the current version of the current project or all
            projects from the repository.

    \endtable


    \section2 Using Additional Subversion Functions

    The \gui Subversion sub-menu contains the following additional items:

    \table
        \row
            \i  \gui{Describe...}
            \i  Display commit log messages for a revision.
        \row
            \i  \gui{Update Project/Update Repository}
            \i  Update your working copy.
    \endtable



*/


/*!
    \contentspage index.html
    \previouspage creator-editor-refactoring.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 \gui Locator allows you to browse not only files, but any items
    defined by \bold{locator filters}. By default, the locator contains
    filters which locate:
    \list
        \o  Any open document
        \o  Files anywhere on your file system
        \o  Files belonging to your project, such as source, header resource,
            and .ui files
        \o  Class and method definitions in your project or anywhere referenced
            from your project
        \o  Help topics, including Qt documentation
        \o  Specific line in the document displayed in your editor
    \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
    \l{http://doc.qt.nokia.com/4.7-snapshot/qdatastream.html}{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 help topic.
            \o  \tt{\bold{? \e{Help topic}}}
            \o  \image qtcreator-locator-help.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
    \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

    \section3 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-building-running.html

    \title Managing Sessions

    When you exit Qt Creator, a snapshot of your current workspace is stored
    as a session.
    A session is a collection of:

    \list
        \o Open projects with their dependencies
        \o Open editors
        \o Breakpoints and watches
        \o Bookmarks
    \endlist

    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 Sessions > \gui{Session Manager}.

    \image qtcreator-session-manager.png

    To switch between sessions, choose
    \gui File > \gui Session. 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-maemo-emulator.html
    \page creator-debugging.html
    \nextpage creator-debugging-cpp.html

    \title Debugging

    You can use the Qt Creator \gui Debug mode to inspect the state of your
    Qt
    \if defined(qtquick)
    and Qt Quick
    \endif
    projects while debugging.

    Qt Creator does not include a debugger. It 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 an internal Java Script debugger. You can use the native debuggers to
    debug the C++ language.

    \image qtcreator-debugger-views.png "Native debugger views"

    \if defined(qtquick)

    Qt Creator includes a QML inspector plugin that you can use to debug QML.

    \image qmldesigner-inspector.png "QML inspector views"

    When you start debugging, the appropriate tool is automatically selected depending
    on the type of the project. If you only develop one kind of projects, you can turn
    off this automation in \gui {Tools > Options... > Debugger > General}. Deselect the
    \gui {Change debugger language automatically} check box.

    The choice of language also determines the contents of the \gui Debug menu.
    The \gui {Start Debugging > Start Debugging} command starts debugging by using the
    tool appropriate for the project type. The availability of the other commands depends
    on whether \gui C++ or \gui QML is selected in \gui {Debug > Language}.

    You can create Qt Quick projects that contain C++ plugins or Qt projects that contain
    QML content. While debugging such projects, you can switch between the native
    debuggers and the QML inspector during debugging.

    To switch between debugged languages, select \gui {Debug > Language > C++} or
    \gui QML. You can also press \key {Ctrl+L, 1} to switch to the native debugger and
    \key {Ctrl+L, 2} to switch to the QML inspector.

    \endif

*/

/*!
    \if defined(qtquick)
    \contentspage index.html
    \previouspage creator-debugging-helpers.html
    \page creator-debugging-qml.html
    \nextpage creator-qml-inspector.html

    \title Debugging Qt Quick Applications

    In the \gui Debug mode you can use the QML inspector plugin to:

    \list

        \o View the status of the application when it is executed.

        \o View debug output.

        \o Write JavaScript expressions and evaluate them.

        \o Modify the values of properties.

        \o Watch the values of expressions.


    \note You can press \key {Ctr+Alt+R} or select \gui {Tools > Qt Quick > Preview}
    to view QML files that do not belong to projects in \QQV. However,
    you can only debug QML files that belong to open projects, because the QML
    inspector plugin needs information about the project.

    \endlist

    \section1 Modes of Operation

    When a Qt Quick project is active and you select \gui {Debug > Start Debugging >
    Start Debugging} the application is started in \QQV and inspected by
    the QML inspector.

    If the Qt Quick project includes C++ plugins, select
    \gui {Debug > Start Debugging > Start Debugging C++ and QML Simultaneously}.
    \QQV is started, the native debugger is attached to it, and
    the application is inspected by the QML inspector.

    \note This command is available only if \gui QML is selected in
    \gui {Debug > Language (QML)}.

    To debug a Qt project that contains QML content, select
    \gui {Debug > Start Debugging > Start Debugging C++ and QML Simultaneously}.
    The application is started under the control of the native debugger, attached
    to \QQV, and inspected by the QML inspector.

    You must use the native debugger to set breakpoints to C++ code and to examine
    the state of the interrupted Qt application. When a C++ program is interrupted,
    for example when a breakpoint is hit, you cannot use the QML inspector.
    \endif

*/


/*!
    \if defined(qtquick)
    \contentspage index.html
    \previouspage creator-debugging-qml.html
    \page creator-qml-inspector.html
    \nextpage creator-version-control.html

    \title Using the QML Inspector

    In \gui Debug mode, you can use several views to interact with the
    application you are debugging. Frequently used views are shown by
    default and rarely used ones are hidden. To change the default settings,
    select \gui Debug > \gui Views, and then select views to display
    or hide. You can also lock views. The position of views is saved for future
    sessions.

    \image qmldesigner-inspector.png "QML inspector views"

    \section1 Starting the QML Inspector

    To start an active application under the control of the QML inspector, select
    \gui {Debug > Start Debugging > Start Debugging}, or press \key{F5}.

    The application is run in \QQV. It behaves and performs as usual.
    You can view the status of the application when it is executed and the debug
    output in the \gui {Application Output} view.

    \image qmldesigner-application-output.png "Application Output view"

    \section1 Starting Simultaneous QML and C++ Debugging

    To debug a Qt Quick project that includes C++ plugins, select
    \gui {Debug > Start Debugging > Start Debugging C++ and QML Simultaneously}.

    \note This command is available only if \gui QML is selected in
    \gui {Debug > Language (QML)}.

    \image qmldesigner-debugging-simultaneous.png "Start Simultaneous QML and C++ Debugging view"

    Usually, the settings for \QQV are specified automatically and you do
    not need to change them:

    \list

        \o \gui {Debugging address} is the IP address to access \QQV.

        \o \gui {Debugging port} is the port to access \QQV. You can use any
        free port in the registered port range.

        \o \gui {Viewer path} is the path to \QQV executable.

        \o \gui {Viewer arguments} sets arguments for running \QQV.
        The \c{-I <directory>} argument searches for C++ or QML plugins from
        the project folder. For a list of available arguments, enter \c {qml --help}
        on the command line.

    \endlist

    \QQV is started, the native debugger is attached to it, and
    the application is inspected by the QML inspector.

    \section1 Viewing and Modifying Values of Properties

    The \gui {Properties and Watchers} view lists the JavaScript expressions
    in the project and their properties and values. The properties are grouped
    by type, but you can also view them in one long list.
    Right-click the list of properties to open a context-menu and then click
    \gui {Group by Item Type} to change the way in which the properties are
    sorted.

    If an item does not have an ID, you cannot change the values of its
    properties. The item type is enclosed in angle brackets and the value
    is grayed.

    Double-click an item to move to the place in code where it is declared.

    You can change the values of properties and see the results in \QQV.

    If the QML inspector cannot retrieve the value for an item or a property for
    inspection, the item or property is grayed in the view. Right-click the item list
    to open a context menu, and then click \gui {Show Uninspectable Items} to hide
    or show the items that cannot be inspected.

    \section1 Watching Expressions

    In the \gui {Properties and Watchers} view, you can specify that an expression is
    watched. Right-click a property and then click \gui {Watch Expression}.
    The \gui Name and \gui Value of the expression are displayed at the bottom
    of the view.

    \image qmldesigner-inspector-watchers.png "Watched expressions"

    You can add JavaScript expressions to object instances to evaluate them.
    Right-click the list of items and select \gui {Add Watch Expression}. Enter
    the expression to evaluate and click \gui OK.

    \image qmldesigner-inspector-add-watch.png "Add Watch Expression dialog"

    To stop watching a expression, right-click it and select \gui {Stop Watching}.

    The QML inspector cannot show the values for some items, such as composite objects
    or complicated item that you cannot change. These items cannot be watched.
    To show them, right-click the properties list, and then select
    \gui {Show Unwatchable Properties}.

    \section1 Executing JavaScript

    In the \gui {Script Console} view, you can write JavaScript expressions, see
    how they are executed, and evaluate them during runtime.

    You can also test the C++ code without rebuilding the whole application.

    \section1 Viewing Connections to \QQV

    The \gui Output view displays the status of the connection between the QML
    inspector and \QQV.

    You specify the connection in the \gui {Run Settings} in the \gui Projects mode.
    For more information, see \l{Specifying Run Settings for Qt Quick Projects}.

    If the connection does not work, check the values of the \gui {Debugging address}
    and \gui {Debugging port} fields. Check that the default port number is not reserved
    by another application or another instance of \QQV that was not shut
    down properly. You can specify any free port number in the registered port range
    (1024-49151).
    \endif

*/


/*!
    \contentspage index.html
    \previouspage creator-debugging.html
    \page creator-debugging-cpp.html
    \nextpage creator-debugging-example.html

    \title Debugging Qt Applications

    In the \gui Debug mode 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.

    For an example of how to debug applications in the \gui Debug mode, see
    \l{Debugging the Example Application}.

    For more information about the functions available in the \gui Debug mode,
    see \l{Interacting with the Debugger}.

    If you install Qt Creator as part of a Qt SDK, the GNU Symbolic Debugger
    is installed automatically and you should be ready to start debugging after
    you create a new
    project. If you want a special setup, such as using debugging tools for Windows,
    see \l {Setting Up Debugger}.

    \section1 Modes of Operation

    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 TRK to debug processes running on a Symbian device.

    \endlist

    When you click the \gui {Start Debugging} button, the debugger is launched
    in the appropriate operating mode (plain, terminal, or TRK), 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 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 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 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.

    \section2 Remote Mode

    The remote mode uses a \e{gdbserver} daemon that runs on the remote machine.

    To launch the debugger in the remote mode, select
    \gui {Debug > Start Debugging > Start and Attach to Remote Application...}.

    \section2 Core Mode

    The core mode is available only in Unix. It debugs crashed processes using
    the \e {core} files (crash dumps) that are generated if the setting
    is enabled in the shell.

    To enable the dumping of core files, 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 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 TRK Mode

    The TRK mode is a special mode available only for Symbian. It
    debugs processes running on a Symbian
    device using the App TRK application that runs on the device.

    To launch the debugger in the TRK mode, open the project, select Symbian as the
    target, and click the \gui {Start Debugging} button.

    For more information on setting up Symbian projects, see
    \l{Setting Up Development Environment for Symbian}.


*/

/*!
    \contentspage index.html
    \previouspage creator-debug-mode.html
    \page creator-debugger-engines.html
    \nextpage creator-debugging-helpers.html

    \title Setting Up Debugger

    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, and Maemo, 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 Helper Library with 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 Optional
            \o Term, Plain, Attach (with Python, only), Remote
        \row
            \o Unix
            \o gcc
            \o gdb
            \o Yes
            \o Term, Plain, Attach, Remote
        \row
            \o Mac OS
            \o gcc
            \o gdb
            \o No
            \o Term, Plain, Attach
        \row
            \o Windows/MinGW
            \o gcc
            \o gdb
            \o No
            \o Term, Plain, Attach, Remote
        \row
            \o Windows/MSVC
            \o Microsoft Visual C++ Compiler
            \o Debugging Tools for Windows/CDB
            \o Not applicable
            \o Term, Plain, Attach, Post-Mortem
        \row
            \o Symbian
            \o gcc
            \o gdb
            \o Yes
            \o TRK
        \row
            \o Maemo
            \o gcc
            \o gdb
            \o Yes
            \o Remote
    \endtable

    \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 TrkGdbAdapter interacts with Symbian devices. The gdb protocol and
       the gdb serial protocol are used between gdb and the adapter. The TRK
       protocol is used between the adapter and AppTRK 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, install version 6.8, 7.0.1 (version 7.0 is not supported),
            7.1, or later. On Mac OS X, install Apple gdb version 6.3.50-20050815
            (build 1344) or later.

        \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}{32-bit}
               or
               \l{http://www.microsoft.com/whdc/devtools/debugging/install64bit.Mspx}{64-bit}
               package (Version 6.11.1.404 for the 32-bit or the 64-bit version of Qt Creator, respectively),
               which is freely available for download from the
               \l{http://msdn.microsoft.com/en-us/default.aspx}
               {Microsoft Developer Network}.

               \note Visual Studio does not include the Debugging tools needed,
               and therefore, you must install them separately.

               The pre-built \e{Qt SDK 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, see:
              \l http://developer.apple.com/mac/library/technotes/tn2004/tn2124.html

        \note The Mac OS X Snow Leopard (10.6) has a bug, that can be worked
              around as described in the link provided below:
              \l http://bugreports.qt.nokia.com/browse/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.


    \omit In v2.1 and later:

    \note The first time you start debugging by using the
    Debugging tools for Windows, Qt Creator prompts you to add the Symbol
    Server.

    \endomit
*/

/*!
    \contentspage index.html
    \previouspage creator-debugging-example.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. Frequently used views are shown by
    default and rarely used ones are hidden. To change the default settings,
    select \gui Debug > \gui Views, and then select views to display
    or hide. You can also lock views. The position of views is saved for future
    sessions.

    \image qtcreator-debugger-views.png "Debug mode views"


    \section1 Starting the Debugger

    To start a program under the debugger's control, select \gui{Debug} >
    \gui{Start Debugging} > \gui{Start Debugging}, or press \key{F5}.
    Qt Creator checks whether the compiled program is up-to-date, rebuilding
    it if necessary. The debugger then takes over and starts the program.

    \note Starting a program in the debugger can take a considerable amount of
    time, typically in the range of several seconds to minutes if complex
    features (like QtWebKit) are used.

    Once the program starts running, it behaves and performs as usual.
    You can interrupt a running program by selecting \gui{Debug} >
    \gui {Interrupt}. The program is automatically interrupted as soon as 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.
    \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 sub-function, press \key{F11}.
       \o  To continue running the program, press \key{F5}.

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

    Typically, breakpoints are associated with a source code file and line, or
    the start of a function -- both are allowed in Qt Creator.

    The interruption of a program by a breakpoint can be restricted with
    certain conditions.

    To set a breakpoint:

    \list
       \o At a particular line you want the program to stop, click the
          left margin or press \key F9 (\key F8 for Mac OS X).
       \o At a function that you want the program to interrupt, enter the
          function's name in \gui{Set Breakpoint at Function...} located in the
          context menu of the \gui{Breakpoints} view.
    \endlist

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


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


    \section1 Viewing Modules and Source Files

    The \gui{Modules} view and \gui{Source Files} views display information
    that the debugger plugin has about modules and source files included in
    the project. The \gui{Modules} view lists the modules in the project and
    symbols within the modules. In addition, it indicates where the module
    was loaded.

    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.

    By default, the \gui{Modules} view and \gui{Source Files} view are hidden.


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

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

    \note The set of watched items is saved in your session.

*/


/*!
    \contentspage index.html
    \previouspage creator-debugging-cpp.html
    \page creator-debugging-example.html
    \nextpage creator-debug-mode.html

    \title Debugging the Example Application

    This section uses the \l{Creating a Qt C++ Application}{TextFinder} example to
    illustrate how to debug 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-snapshot/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

    \section1 Debugging Helper Library with C++

    While debugging, Qt Creator dynamically loads a helper library into your
    program. This helper library enables Qt Creator to pretty print Qt and STL
    types. The Qt SDK 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 Helper Library with Python

    With the gdb Python version, you can
    use debugging helpers also for user defined types. To do so,
    define one Python function per user defined type in \c{.gdbinit}.

    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.putItem(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 AppTRK.

    \o \gui{putItemHelper(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{putItem(self, item)} - Equivalent to:
        \code
        with SubItem(self):
            self.putItemHelper(item)
        \endcode
        Exceptions raised by nested function calls are caught and all
        output produced by \c putItemHelper 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 \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.putItemHelper(Item(key, item.iname, "key"))
            with SubItem(d):
                d.putName("value")
                d.putItemHelper(Item(value, item.iname, "value"))
    \endcode
*/


/*!
    \contentspage index.html
    \previouspage creator-project-qmake.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 makefiles.
    It controls the software compilation process by using simple configuration
    files, called CMakeLists.txt files. CMake generates native makefiles 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 Toolchain 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 Creator 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 of version 1.3.84}{here}.


    \section1 Adding External Libraries to a CMake Project

    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-project-cmake.html
    \page creator-project-generic.html
    \nextpage creator-developing-maemo.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-build-dependencies.html
    \page creator-visual-editor.html
    \nextpage creator-usability.html

    \title Developing Qt Quick Applications

    You can either create Qt Quick projects from scratch or import them to
    Qt Creator. For example, you can import and run the
    \l {http://doc.qt.nokia.com/4.7-snapshot/qdeclarativeexamples.html} {QML examples and demos}
    to learn how to use various aspects of QML.

    \note The Qt Quick specific features and the QDeclarative help are based on a
    preview version of the QtDeclarative package. Update Qt Creator when Qt 4.7 is
    released.

    You can use the code editor (\gui Edit mode) or the visual editor
    (\gui Design mode) to develop Qt Quick applications.

    \note The \QMLD visual editor is provided as an experimental plugin that you must
    enable to be able to edit QML files in the \gui Design mode. Enabling the
    visual editor can negatively affect the overall stability of Qt Creator.

    To enable or disable the \QMLD visual editor, select
    \gui {Help > About Plugins... > Qt Quick > QmlDesigner}. You must restart Qt Creator
    to enable or disable the visual editor.

    \section1 Creating Qt Quick Projects

    Select \gui {File > New File or Project > Qt Quick Project > Qt QML Application}.

    \QMLD 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-snapshot/qdeclarativemodules.html} {Qt modules}
    to import to \QMLD. 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.

    To import a QML project to Qt Creator, select
    \gui {File > New File or Project > Qt Quick Project > Import Existing Qt QML Directory}.

    \section1 Designing Application UI

    One .qml file can define a component, screen, or the whole application.

    \section2 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 \gui Library items to create components. Drag and drop
    the following QML elements to the editor and modify their properties in the \gui Properties pane:

    \list

        \o \l{http://doc.qt.nokia.com/4.7-snapshot/qml-borderimage.html}{Border Image}
        uses an image as a border or background.
        \o \l{http://doc.qt.nokia.com/4.7-snapshot/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-snapshot/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-snapshot/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-snapshot/qml-text.html}{Text}
        adds formatted read-only text.
        \o \l{http://doc.qt.nokia.com/4.7-snapshot/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-snapshot/qml-textinput.html}{Text Input}
        adds a single line of editable plain text that can be validated.

    \endlist

    You can use QML to add properties for a component in the code editor.

    The following sections describe some use cases for the QML elements.

    \section3 Creating Buttons

    To create a button component:

    \list 1

        \o Select \gui {File > New File or Project > Qt > Qt QML File} 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 Double-click the file to open it in the code editor.

        \o Click \gui {Design} to edit the file in the visual editor.

        \o Drag and drop a \gui Rectangle from the \gui Library pane to the scene.

        \o In the \gui Properties pane, modify the appearance of the button.

        \list a

        \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 button to align the text to the
        center of the button.

        \o Click \gui {Geometry}, and then click the
        \inlineimage qmldesigner-anchor-fill-screen.png
        button to anchor the text to the whole button area.

        \endlist

        \o Click \gui Edit to edit the \c width and \c height properties of the button
        to fit the button size.

        \o Press \key {Ctrl+S} to save the button.

        \image qmldesigner-button.png "Button component"

        \o Click the \gui Run button to view the button in \QQV.

    \endlist

    To create a graphical button that scales beautifully without using vector graphics,
    use the \l{http://doc.qt.nokia.com/4.7-snapshot/qml-borderimage.html}{Border Image}
    element.

    \section3 Creating Scalable Buttons and Borders

    You can use the \l{http://doc.qt.nokia.com/4.7-snapshot/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 > Qt > Qt QML File} 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:

        \code

        Item {

        }

        \endcode

        \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 Click \gui Edit to specify properties for the \gui Item, as
        illustrated by the following code snippet:

        \code

        property string text: ""
        property int fontSize: 44

        signal clicked

        \endcode

        \o In the \gui Navigator view, select \gui borderimage1 to specify
        settings for it in the \gui Properties pane:

        \list a

            \o In the \gui Source field, select the image file for the
            button, for example button_up.png.

            \o In the \gui Left, \gui Right, \gui Top, and \gui Bottom fields,
            enter 32 to set the margins for the image.

            \o Click \gui {Geometry}, and then click the
            \inlineimage qmldesigner-anchor-fill-screen.png
            button to anchor the border image to the \gui Item.

            \o Click \gui Advanced, and 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 {!mousearea1.pressed}.

        \endlist

        \o Select \gui borderimage2 to specify similar settings for it:

        \list a

            \o In the \gui Source field, select the image file for the
            button when it is clicked, for example button_down.png.

            \o In the \gui Left, \gui Right, \gui Top, and \gui Bottom fields,
            enter 32 to set the margins for the image.

            \o Click \gui {Geometry}, and then click the
            \inlineimage qmldesigner-anchor-fill-screen.png
            button to anchor the border image to the \gui Item.

            \o Click \gui Advanced, and set the following epression for
            \gui Visibility, to specify that the the image is visible
            when the mouse is pressed down: \c {mousearea1.pressed}.

        \endlist


        \o Select \gui Text 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 In the \gui Size field, select \gui {Pixel} 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 Select the \gui Smooth check box to enable smooth text
            rendering.

            \o Click \gui {Geometry}, 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()}.

        \o Click the \gui Run button to view the button in \QQV.

        \endlist

    \section2 Creating Screens

    You can use the \gui Library items and your own components to create screens.

    You can create the following types of views to organize items provided by
    \l{http://doc.qt.nokia.com/4.7-snapshot/qdeclarativemodels.html}{data models}:

    \list

        \o \l{http://doc.qt.nokia.com/4.7-snapshot/qml-gridview.html}{Grid View}
        \o \l{http://doc.qt.nokia.com/4.7-snapshot/qml-listview.html}{List View}
        \o \l{http://doc.qt.nokia.com/4.7-snapshot/qml-pathview.html}{Path View}

    \endlist

    In the code editor, write the code to use the data models.

    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:

    \list 1

        \o Use the \gui Library items, resources and your own components to create a screen.
        For example, drag and drop the button component from the \gui Library pane to the screen.

        \o In the \gui State pane, click the plus sign to add another view, or \e state
        to the application.

        \o Modify the second state of the screen to create a new screen.

    \endlist

    \section3 Creating List Views

    You use list views and list models to create lists. You use delegates to handle list items.
    Typically, the list model is provided by a QAbstractListModel C++ model object,
    but you can also create it in QML.

    \list 1

        \o Select \gui {File > New File or Project > Qt > Qt QML File} to create a QML file
        called ListView.qml (for example).

        \o Double-click the file to open it in the code editor.

        \o Add a list model that contains the data to be shown on the list, as
        illustrated by the following code snippet:

        \code

        import Qt 4.7

            Rectangle {
                width: 360
                height: 640

            ListModel {
                id: myListModel
                ListElement {
                   item_index: 0
                   item_name: "Item 1"
                   item_description: "Description 1"
            }
            ListElement {
                item_index: 1
                item_name: "Item 2"
                item_description: "Description 2"
            }
            ListElement {
                item_index: 2
                item_name: "Item 3"
                item_description: "Description 3"
            }
        }

        \endcode

        \o Add a delegate that draws each item in the list.

        \code

        Component {
            id: myListDelegate
            Item {
                id: wrapper
                width: parent.width
                height: 40
                Column {
                    x: 5; y: 5
                    Text { text: '<b>Name:</b> ' + item_name }
                    Text { text: '<b>Descriptionr:</b> ' + item_description }
                }
                MouseArea {
                    anchors.fill: parent
                    onClicked: myList.currentIndex = item_index
                }
            }
        }

        \endcode

        You can use a separate delegate to hilight the currently selected item.

        \code

        Component {
            id: myListHilight
            Rectangle {
                width: parent.width
                height: 40
                color: "lightsteelblue"
                radius: 5
                SpringFollow on y {
                    to: myList.currentItem.y
                    spring: 3
                    damping: 0.2
                }
            }
        }

        \endcode

        \o Add the list view, as illustrated by the following code snippet:

        \code

        ListView {
            id: myList
            width: parent.width; height: parent.height
            model: myListModel
            delegate: myListDelegate
            highlight: myListHilight
            focus: true
            }
        }

        \endcode

        \o Click the \gui Run button to view the list view in \QQV.

    \endlist

    \section2 Navigating Between 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-snapshot/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.



    \section2 Adding User Interaction Methods

    You can add the following basic interaction methods to scenes:

    \list

        \o \l{http://doc.qt.nokia.com/4.7-snapshot/qml-flickable.html}{Flickable}
        items can be flicked horizontally or vertically.
        \o \l{http://doc.qt.nokia.com/4.7-snapshot/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-snapshot/qml-focusscope.html}{Focus Scope}
        assists in keyboard focus handling when building reusable QML components.
        \o \l{http://doc.qt.nokia.com/4.7-snapshot/qml-mousearea.html}{Mouse Area}
        enables simple mouse handling.

    \endlist

    To add interaction methods, drag and drop a \gui {Focus Scope} or \gui {Mouse Area}
    to the screen. In the code editor, add signal handlers to execute when users select
    the scope or area. Signal handlers allow actions to be taken in response to an event.
    For instance, the \gui {MouseArea} element has signal handlers to handle mouse press,
    release, and click.

    \section1 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-snapshot/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-snapshot/qml-advtutorial.html} {QML Advanced Tutorial}.

 */


/*!

    \contentspage index.html
    \previouspage creator-project-generic.html
    \page creator-developing-maemo.html
    \nextpage creator-developing-symbian.html

    \title Setting Up Development Environment for Maemo

    Maemo is a software platform developed by Nokia for smartphones and
    Internet Tablets. The Maemo SDK provides an open development environment
    for different applications on top of the Maemo platform. The necessary
    tools from the Maemo SDK are also included in the Nokia Qt SDK.
    The whole tool chain that you need to create, build, debug, run, and deploy
    Maemo applictions is installed and configured when you install the Nokia
    Qt SDK.

    Maemo 5 is based on the Linux 2.6 operating system. For more
    information about the Maemo platform, see
    \l{http://maemo.org/intro/platform/}{Software Platform} on the Maemo web site.

    For more information about developing applications for the Maemo 5
    platform, select \gui {Help > Index} and look for \gui {Platform Notes},
    or see
    \l{http://doc.qt.nokia.com/qt-maemo-4.6/platform-notes.html}{Platform Notes - Maemo 5}.

    \section1 Hardware and Software Requirements

    To build and run Qt applications for Maemo, you need the following:
    \list
       \o  Nokia N900 device with software update release 1.2 (V10.2010.19-1)
       or later installed.
       \o  MADDE cross-platform Maemo development
           tool (installed as part of the Nokia Qt SDK).

           For more information about MADDE pertaining to its
           installation, configuration, and deployment on the device, see
          \l{http://wiki.maemo.org/MADDE}{Introduction to MADDE}.

       \o Nokia USB drivers.

       Only needed if you develop on Windows and if you use a USB connection
       to run applications on the device. The drivers are
       installed as part of the Nokia Qt SDK. You can also download them from
       \l{https://garage.maemo.org/frs/?group_id=801&release_id=2655}{PC Connectivity}
       on the Maemo web site. Download and install the latest
       PC_Connectivity_<version>.exe (at the time of writing,
       PC_Connectivity_0.9.4.exe).

    \endlist

     The Qt Creator/MADDE integration is supported on the following platforms:
    \list
       \o  Linux (32 bit and 64 bit)
       \o  Windows (32 bit and 64 bit)
       \omit \o  Mac OS 10.5 Leopard, or higher \endomit
    \endlist

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

    \section1 Setting Up the Nokia N900

    You can connect your device to your development PC using either a USB or
    WLAN connection.

    For the device, you need to use a tool called Mad Developer to create the
    device-side end point for USB and WLAN connections. It provides no
    diagnostics functions but is essential for creating connections between the
    device and your development PC.

    To use a WLAN connection, you must activate WLAN on the device and connect
    it to the same WLAN as the development PC. The network address is displayed
    in the Mad Developer.

    To use an USB connection, you need to set up the Nokia N900 as a network device
    on the development PC.

    \note If you plan to connect your development PC to the Nokia N900 only over WLAN, you can
    ignore the USB-specific parts in the following sections.

    \section2 Installing and Configuring Mad Developer

    Install Mad Developer on a device and configure
    a connection between the development PC and the device.

    To install and configure Mad Developer:

     \list 1
         \o On the Nokia N900, select \gui{Download} > \gui{Development} > \gui{mad-developer}
         to install the Mad Developer software package.
         \o Click \gui {Mad Developer} to start the Mad Developer application.

         \o To use a WLAN connection, activate WLAN on the device and connect
         to the same network as the development PC. You can see the network
         address in the \gui wlan0 field.

         \o To use an USB connection:

         \list a

         \o If you are using Microsoft Windows as development host, you must
         change the driver loaded for instantiating the connection.
         In the Mad Developer, select \gui{Manage USB} and select \gui{Load g_ether}.

         \o To set up the USB settings, click \gui Edit on the \gui usb0 row and
         confirm by clicking \gui Configure.

          \note By default, you do not need to make changes. The \gui usb0 row
          displays the IP address 192.168.2.15.

          \endlist

       \o Select \gui{Developer Password} to generate a password for a freshly
          created user called \bold developer. The password stays valid for as long
          as the password generation dialog is open. You enter the password when
          you configure the connection in Qt Creator.

          \image qtcreator-mad-developer-screenshot.png
    \endlist

    \section1 Setting Up Network Connectivity on Development PC

    Use the network configuration tools on your platform to specify the
    connection to the device on the development PC. You need to do this
    only if you use an USB connection.

    \section2 Linux

    The device uses the IP address 192.168.2.15 with the subnet 255.255.255.0
    for its USB connection by default, so you can create the network interface
    with a different address inside the same subnet too.

    \note If you have changed the IP address of the device when configuring
    Mad Developer, you need to reflect those changes in your development PC USB
    network settings.

    Run the following command in a shell as root user:
                  \c{ifconfig usb0 192.168.2.14 up}

    \section2 Windows

    When you connect the device to your Windows PC, Windows tries to install a
    driver for the Linux USB Ethernet connection. In the
    \gui{Found New Hardware Wizard}, select \gui{No, not this time} in the
    first dialog and \gui{Install the software automatically} in the second
    dialog.

    To specify a network connection:

    \list 1

    \o Open the Network Connections window.

    \o Select the Linux USB Ethernet
    connection that is displayed as a new Local Area Connection.

    \o Edit the \gui {Internet Protocol Version 4 (TCP/IPv4)} properties
    to specify the IP address for the connection.
    In the \gui {Use the following IP address} field, enter the following values:
    \list
       \o  \gui {IP Address}: \bold {192.168.2.14}
       \o  \gui SubnetMask: \bold {255.255.255.0}
       \o  \gui {Default gateway}: leave this field empty
    \endlist

    \endlist

    Depending on
    your version of Microsoft Windows you may have to unplug and re-plug the
    Nokia N900 to reload the driver with its configuration accordingly.

    \section1 Setting Up MADDE

    If you install Nokia Qt SDK, the MADDE package is installed and
    configured automatically on your development PC and you can omit this task.

    \list 1

    \o Download the MADDE installer file for your platform from the
    \l{http://wiki.maemo.org/MADDE}{MADDE} site.

    \o Execute the installer and follow the instructions.

    \o To see which targets are available, run \c{mad-admin list targets}.

    \o To install the target that starts with the string \bold fremantle, use the command:
    \c{mad-admin create fremantle-qt-xxx}

    \o In Qt Creator, register the MADDE tool chain:

       \image qtcreator-screenshot-toolchain.png

        \list a

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

            \o Click \inlineimage qtcreator-windows-add.png,
            to add a new Qt version.

            The \gui{qmake Location} is the qmake
            executable in \c{<MADDE dir>/targets/<fremantle target>/bin}.

        \endlist

    \endlist

    When you have installed the target, you have a toolchain and a sysroot
    environment for cross-compiling.

    \section1 Configuring Connections in Qt Creator

    To be able to run and debug applications on the Maemo emulator and
    devices, you must set up a connection to the emulator and the device in the
    Qt Creator build and run settings. If you install Nokia Qt SDK, the
    necessary software is installed and configured automatically and you
    only need to configure a connection to the device.

    You can protect the connections between Qt Creator and the Maemo emulator
    or a device by using either a password or an SSH key. You must always
    use a password for the initial connection, but can then deploy an SSH
    key and use it for subsequent connections. If you use a password, you
    must generate it in Mad Developer and enter it in Qt Creator every time
    you connect to the Maemo emulator or to a device.

    If you do not have an SSH key, you can create it in Qt Creator.
    Encrypted keys are not supported. For more
    information, see \l{Generating SSH Keys}.

    To configure connections between Qt Creator and the Maemo emulator or
    device:

    \list 1

        \o If you install the Maemo emulator (QEMU) separately, you must
           specify parameters to access it:

            \list a

            \o Start Mad Developer in the emulator.

            \o Click \gui {Developer Password} to generate a password for
            the connection.

            \o In Qt Creator, select \gui {Tools > Options... > Projects >
            Maemo Device Configurations > Add} to add a new configuration.

            \image qtcreator-maemo-emulator-connection.png

            \o In the \gui {Configuration name} field, enter a name for
            the connection.

            \o In the \gui {Device type} field, select \gui {Maemo emulator}.

            \o In the \gui {Authentication type} field, select \gui Password
            for the initial connection.

            \o In the \gui Password field, enter the password from the Mad
            Developer for the initial connection.

            You can use the default values for the other fields.

            \o Click \gui Test to test the connection.

            \o To avoid having to specify the password every time you connect
            to the Maemo emulator, click \gui {Deploy Key...} and select
            the file that contains your public key.

            \o When you have deployed the key to the device, change the
            configuration to use the SSH key for protection.

            \image qtcreator-maemo-emulator-connection-key.png

            The default location of the private key file is displayed in the
            \gui {Private key file} field.

            \endlist

            If you installed the Nokia Qt SDK, a connection has been configured
            and you only need to specify the password and deploy the SSH key.

        \o  To deploy applications and run them remotely, specify parameters
            for accessing devices:

            \list a

            \o Connect your device to the development PC via an USB cable or
            a WLAN. For an USB connection, you are prompted to select the mode
            to use. Choose \gui{PC suite mode}.

            \note If you experience connection problems due to a USB port issue,
            switch to a different port or use WLAN to connect to the device.

            \o Select \gui Tools > \gui Options... > \gui Projects >
            \gui{Maemo Device Configurations > Add}, and add a new configuration for a
            \gui {Remote device}.

            \image qtcreator-screenshot-devconf.png

            \o In the \gui {Host name} field, enter the IP address from the
            \gui usb0 or \gui wlan0 field in Mad Developer.

            \o Specify the other settings in the same way as for a Maemo emulator
            connection.

            \o Click \gui Test to test the connection.

            \o Click \gui OK to close the dialog.

            \endlist

         \o To specify build and run settings:

            \list a

                \o Open a project for an application you want to develop for your
                Nokia N900.

                \o Click \gui Projects to open the projects mode.

                \o In the \gui{Build Settings} section, choose the MADDE Qt version.

                 \image qtcreator-screenshot-build-settings.png

                 \o In the \gui{Run Settings} section, click \gui Add to add a new
                 run configuration.

                 \o Set a name and select the device configuration.

                 \image qtcreator-screenshot-run-settings.png

                 \note You can either add separate run settings for both the Maemo
                  emulator connection and the device connection or select the
                  \gui {Device configuration} before you run the application.

             \endlist

         \endlist

         \section2 Generating SSH Keys

         If you do not have an SSH public and private key pair, you can generate it
         in Qt Creator. You can specify key length and the key algorithm, RSA or DSA.
         If you only use the keys to protect connections to the Maemo emulator or
         device, you can use the default values.

         \list 1

             \o Select \gui {Tools > Options... > Projects > Maemo Device Configurations
             > Generate SSH Key...}.

             \o Click \gui {Generate SSH Key}.

             \image qtcreator-ssh-key-configuration.png "SSH Key Configuration dialog"

             \o Click \gui {Save Public Key...} to select the location to save the
             public key.

             \o Click \gui {Save Private Key...} to specify the location to save the
             private key.

             \o Click \gui Close to close the dialog.

         \endlist

*/


/*!
    \contentspage index.html
    \previouspage creator-usability.html
    \page creator-maemo-emulator.html
    \nextpage creator-debugging.html

    \title Using the Maemo Emulator

    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 software update release 1.2 (V10.2010.19-1).
    You can test user interaction by using the keypad and
    touch emulation.

    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/qt-simulator-beta/index.html}{Qt Simulator Manual}.

    The Maemo emulator is installed and configured as part of the Nokia Qt SDK
    package. You can also install and configure the MADDE environment and
    Maemo emulator separately. For more information, see
    \l{Setting Up Development Environment for Maemo}.

    \section1 Starting the Maemo 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 build target
    and if you have configured a connection between Qt Creator and the Maemo
    Emulator.

    To start the Maemo emulator:

    \list 1

    \o Click
    \inlineimage qtcreator-maemo-emulator-button.png "Start Maemo Emulator button"
    .

    \o Select \gui {Mad Developer} on the Maemo emulator, to start the Mad Developer
    application

    \o If you have not deployed an SSH key to protect the connection between
    Qt Creator and the Maemo emulator, select \gui {Developer Password} to generate
    a password.

    \o In Qt Creator, enter the password in the connection settings:
    \gui {Tools > Options... > Projects > Maemo Device Configurations}.

    \endlist

    Test your application on the Maemo emulator as on a device. For a list of
    keyboard shortcuts that you can use to emulate Nokia N900 keys and functions, see
    \l {Emulating Nokia N900 Keys}.

    \section1 Emulating Nokia N900 Keys

    The following table summarizes the keyboard shortcuts that you can use
    to emulate Nokia N900 keys and functions.

    \table
        \header
            \o Nokia N900 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
        \row
            \o Ctrl
            \o Left Ctrl key
        \row
            \o Mode
            \o Left Alt key
        \row
            \o Power
            \o Esc
        \row
            \o Keypad slider open and close
            \o F1
        \row
            \o Keypad lock
            \o F2
        \row
            \o Camera lens open and close
            \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
            \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


*/


/*!
    \contentspage index.html
    \previouspage creator-developing-maemo.html
    \page creator-developing-symbian.html
    \nextpage creator-project-managing-sessions.html

    \title Setting Up Development Environment for Symbian

    For more information about developing applications for the Symbian
    platform, select \gui {Help > Index} and look for \gui {Platform Notes},
    or see
    \l{http://doc.qt.nokia.com/4.6/platform-notes-symbian.html}{Platform Notes - Symbian}.

    \section1 Hardware and Software Requirements

    Windows is the only development platform for the Symbian target
    supported at the moment.

    For deploying and running applications on the device, you need the
    following:
    \list
        \o The Nokia USB drivers that come with \e{PC Suite} or \e{Ovi Suite}
        \o The \l{http://tools.ext.nokia.com/trk/}{App TRK} application for
           your device
        \o The \e{qt_installer.sis} package installed on the device, that is
         delivered with the Qt SDK.
    \endlist

    To run your applications in the Symbian emulator, you also need
    to install Carbide.c++ v2.0.0 or higher.

    \section1 Installing Required Applications on Devices

    The Nokia Qt SDK installation program creates shortcuts for installing
    the required applications on Symbian devices (you can also use any of
    the standard methods for installing applications on devices):

    \list 1

        \o Connect the device to the development PC with an USB cable in
        PC Suite Mode. If you have not previously used the device with Ovi Suite
        or PC Suite, all the necessary drivers are installed automatically.
        This takes approximately one minute.

        \o Choose \gui {Start > Nokia Qt SDK > Symbian > Install Qt to Symbian
        device} and follow the instructions on the screen to install Qt 4.6.2
        libraries on the device.

        \o Choose \gui {Start > Nokia Qt SDK > Symbian > Install QtMobility to Symbian
        device} and follow the instructions on the screen to install Qt
        mobility libraries on the device.

        \o Choose \gui {Start > Nokia Qt SDK > Symbian > Install TRK to Symbian
        device} and follow the instructions on the screen to install the TRK
        debugging application on the device.

        \note To check the Symbian platform version of your device, see
        \l{http://www.forum.nokia.com/devices}{Device Details}.

    \endlist

    \section1 Adding Symbian Platform SDKs

    Nokia Qt SDK contains all the tools you need for developing Qt applications for
    Symbian devices. To use Symbian APIs directly in your applications, you can
    install additional Symbian Platform SDKs:

    \list
        \o \l{http://www.forum.nokia.com/main/resources/tools_and_sdks/S60SDK/}
           {S60 Platform SDK 3rd Edition FP1 or higher}.
        \o Either the GCCE ARM Toolchain that is included in the S60 Platform
           SDKs, or RVCT 2.2 [build 686] or later (which is not available free
           of charge)(Your environment needs to find the compiler in the PATH).
        \o Qt for Symbian 4.6.2 or later, installed into the S60 SDKs you want
           to use.

    \endlist

    \section2 Setting Up Qt Creator

    When you run Qt Creator after installing the S60 Platform SDK and Qt for
    Symbian, the installed SDKs and their corresponding Qt versions are
    automatically detected. For each detected S60 SDK with Qt, a special entry
    is made in the Qt version management settings in \gui{Tools} >
    \gui{Options...} > \gui{Qt4} > \gui{Qt Versions}.

    \note If you manually add a Qt version for Symbian, you must
    also manually specify the S60 SDK to use for this version.

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

    If you want to run your applications in the Symbian emulator, you need to
    point Qt Creator to the Metrowerks Compiler that you want to use, by
    setting the \gui{Carbide Directory} of the Qt version to the corresponding
    Carbide.c++ installation directory.

    You can check what S60 SDKs and corresponding Qt versions are found in the
    \gui{Tools} > \gui{Options...} > \gui{Qt4} > \gui{S60 SDKs} preference
    page.

    \image qtcreator-qt4-s60sdks.png



*/

/*!
    \contentspage index.html
    \previouspage creator-version-control.html
    \page adding-plugins.html
    \nextpage creator-tips.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-snapshot/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 and \c {QtCreator.app/Contents/MacOS/designer} folder on Mac. 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}.

     \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-visual-editor.html
    \page creator-usability.html
    \nextpage creator-maemo-emulator.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 adding-plugins.html
    \page creator-tips.html
    \nextpage creator-keyboard-shortcuts.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.


    \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 Using Keyboard Shortcuts

    Qt Creator provides \l{Keyboard Shortcuts}{many useful keyboard shortcuts}.

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



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


    \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

*/


/*!
    \contentspage index.html
    \previouspage creator-tips.html
    \page creator-keyboard-shortcuts.html
    \nextpage creator-known-issues.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 Ctrl+Alt+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 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
    \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-keyboard-shortcuts.html
    \page creator-known-issues.html
    \nextpage creator-glossary.html

    \title Known Issues

    There are some known issues with Qt Creator.
    The development team is aware of them, there is no need to report them as bugs.

    \section1 Known Issues of Version 1.3.84

    \list
        \o On Windows, debugging a MinGW-built console application (with \gui{Run in terminal}
           checked) using gdb does not work due to a bug in gdb related to attaching to
           stopped processes (see \l{http://bugreports.qt.nokia.com/browse/QTCREATORBUG-1020}).

        \o Debugging Helper does not work while performing On-Device Debugging.

        \if defined(qtquick)

        \o QML Preview (Run Project) only works if built against Qt with
           Declarative UI.

        \endif

        \o Setting breakpoints in code that is compiled into the binary more
           than once does not work.

        \o On Linux and Windows, installing Qt with one user account and
        then using it with another requires other users to manually set
        the Qt version. On Windows, setting the MinGW location is
        required as well. The same applies to the location of GDB for Symbian.
        A workaround is to copy %APPDATA%/Nokia/qtcreator.ini (Windows) or
        $HOME/.config/Nokia/QtCreator.ini (Linux) from the directory
        of the user who installed Qt Creator to the other user.
        This issue does not exist on Mac OS X.
    \endlist

    \section1 Known Issues of Version 1.2.0 and 1.2.1

    \list
        \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 Only simple data types (POD) work in the Watch Window of CDB.

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

    \section1 Known Issues of Version 1.1.0

    \list
        \o Paths or file names containing spaces or special characters, e.g.,
           colons, dollar signs, hash marks etc. 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 \c{.pro} files are reformatted if files have been added or removed.
           Whitespace is not preserved.

        \o There is no IDE support for adding files to include (\c .pri) files.

        \o There is no IDE support for adding/removing sub-projects. Project
           hierarchies (SUBDIRS template) have to be created manually.

        \o The file system sidebar does not update automatically. As a
           workaround, switch to another directory and then back.

        \o Loading KDE4 designer plugins breaks the style in KDE < 4.2.1
           due to a bug in KDE.

        \o The DEFINES and INCLUDES set in \c{.pro} files are not dealt with
           on a file-specific level. Because of this, handling of DEFINES has
           been disabled completely. Also the \c{.qmake.cache} is not being
           parsed. In general, the \c{.pro} file parser is incomplete and
           problems are still to be expected.

        \o Code completion for generated UI header files is updated only
           after a build.

        \o Code completion does not support typedefs for nested classes.

        \o There is a kernel bug essentially making debugging unreliable on
           2.6.24 kernels for i386 (which is, unfortunately, the default on
           Ubuntu 8.04). See
           \l{https://bugs.launchpad.net/ubuntu/+source/gdb/+bug/230315/} for
           details. The only solution to this problem is to boot another
           kernel.

        \o Gdb may take long to load debugging symbols, especially from large
           libraries like \c libQtWebKit. Starting the debugging module can
           take up to several minutes without visible progress.

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

        \o There is no syntax highlighting for \c CMake project files.

        \o Project files included from \c{CMakeLists.txt} are not shown in the
           navigation tree.

        \o Using the Visual Studio Compiler with \c CMake is not supported.

        \o Creating new \c CMake projects with Qt Creator is not supported.

        \o Having more than one build directory for \c CMake is not supported.

        \o Changing the build directory for \c CMake after the initial import
           is disabled.
    \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
*/