qtcreator.qdoc

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

        The tool tip of the target button 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}.


    \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}.
    The settings to specify depend on the type of the project: qmake project
    or Qt Quick project.

    \section1 Specifying Run Settings for qmake Projects

    The run configurations for qmake projects derive their executable from the parsed .pro
    files. You can also create custom executable run configurations where you
    can set the executable to be run.

    \image qtcreator-pprunsettings.png

    \section1 Specifying Run Settings for Qt Quick Projects

    To run Qt Quick projects in the QML viewer, specify the connection to the
    \gui {QML Runtime} in the \gui {Run configuration} field. The settings
    are specified automatically and, usually, you do not need to change them:

    \list

        \o \gui {QML runtime} is the path to QML viewer executable.

        \o \gui {QML runtime arguments} sets arguments for running the QML viewer.
        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 the QML viewer.

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

    \endlist

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

    To set the executable to run, select \gui {Custom Executable} in the
    \gui {Run configuration} field.

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

*/


/*!
    \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-writing-program.html

    \title Getting Started

    This section contains examples that illustrate how to use Qt Creator and the
    integrated design tools, \QD and \QMLD, to create simple applications:

    \list
        \o \l{Creating a Qt C++ Application}
        \o \l{Creating a Qt Quick Application}
    \endlist

*/


/*!
    \contentspage index.html
    \previouspage creator-writing-program.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://qt.nokia.com/doc/4.7-snapshot/declarativeui.html}
    {QML declarative language}.

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

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

*/


/*!
    \contentspage index.html
    \previouspage creator-getting-started.html
    \page creator-writing-program.html
    \nextpage creator-qml-application.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.trolltech.com/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 > OK}.

           \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.trolltech.com/qlabel.html}{QLabel})
    \o \gui{Line Edit} (\l{http://doc.trolltech.com/qlineedit.html}{QLineEdit})
    \o \gui{Push Button} (\l{http://doc.trolltech.com/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.trolltech.com/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.trolltech.com/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.trolltech.com/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.trolltech.com/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.trolltech.com/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.trolltech.com/qfile.html}{QFile}, read it with
    \l{http://doc.trolltech.com/qtextstream.html}{QTextStream}, and
    then display it on \c{textEdit} with
    \l{http://doc.trolltech.com/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.trolltech.com/qfile.html}{QFile} and
    \l{http://doc.trolltech.com/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.trolltech.com/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 > OK}.
    \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 set up the version control system's command line
    clients to access your repositories, 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 the settings pages shown by
    \gui{Tools} > \gui{Options...}.


    \section1 Setting Up Common Options

    Select \gui{Tools} > \gui{Options...} > \gui{Version Control} > \gui{Common}
    to view the common settings for version control systems. The following are
    the options present in \gui{Common}:
    \list
       \o   \gui{Submit message checking 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
    \bold{git} or \bold{hg}.
    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 version control sub-menus are in \gui{Tools} > \gui{Options...}.
    The \gui{Version Control} page also displays the
    version control system managing the current project

    Under \gui{Application Output} > \gui{Version Control}, there is an output
    pane showing the commands that are executed, prepended by a
    timestamp and the relevant output.


    \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, \bold{Perforce} and \bold{Subversion}. Alternatively, you can
    add files later by using the version control tool menus.

    With \bold{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 \bold{git}) or \gui{Filelog}(for \bold{Perforce} and
    \bold{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
    \image qtcreator-vcs-describe.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 \gui git/hg 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.

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

    \image qtcreator-vcs-commit.png



    \section2 Using git-specific Menu Entries

    The git sub-menu contains additional entries:

    \table
        \row
            \i  \gui{Stash Snapshot...}
            \i  Allows you to 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,