+++ /dev/null
-/****************************************************************************
-**
-** This file is part of Qt Creator
-**
-** Copyright (c) 2011 Nokia Corporation and/or its subsidiary(-ies).
-**
-** Contact: Nokia Corporation (info@qt.nokia.com)
-**
-**
-** GNU Free Documentation License
-**
-** Alternatively, this file may be used under the terms of the GNU Free
-** Documentation License version 1.3 as published by the Free Software
-** Foundation and appearing in the file included in the packaging of this
-** file.
-**
-** If you have questions regarding the use of this file, please contact
-** Nokia at info@qt.nokia.com.
-**
-****************************************************************************/
-
-// **********************************************************************
-// NOTE: the sections are not ordered by their logical order to avoid
-// reshuffling the file each time the index order changes (i.e., often).
-// Run the fixnavi.pl script to adjust the links to the index order.
-// **********************************************************************
-
-
-/*!
- \contentspage{index.html}{Qt Creator}
- \page index.html
- \nextpage creator-overview.html
-
- \title Qt Creator Manual
-
- \section1 Version \qtcversion
-
- Qt Creator provides a cross-platform, complete integrated development
- environment (IDE) for application developers to create applications for
- multiple desktop and mobile device platforms. It is available for Linux,
- Mac OS X and Windows operating systems. For more information, see
- \l{Operating Systems and Supported Platforms}.
-
- \note To report bugs and suggestions to the Qt Bug Tracker, select
- \gui {Help > Report Bug}.
- You can also join the Qt Creator mailing list at:
- \l{http://lists.qt.nokia.com}{http://lists.qt.nokia.com}.
-
- \raw HTML
- <img border="0" style="float:right;" src="images/qtcreator-screenshots.png" />
- \endraw
-
- \list
- \o \l{Introducing Qt Creator}
- \o \l{Qt Creator User Interface}
- \o \l{Getting Started}
- \list
- \o \l{Building and Running an Example Application}
- \o \l{Creating a Qt Quick Application}
- \o \l{Creating a Qt Quick Application Using Qt Quick Components}
- \o \l{Creating a Qt Widget Based Application}
- \o \l{Creating a Qt Widget Based Mobile Application}
-
- \endlist
- \o \l{Managing Projects}
- \list
- \o \l{Creating a Project}
- \o \l{Opening a Project}
- \o \l{Adding Libraries to Projects}
- \o \l{Connecting MeeGo Harmattan Devices}
- \o \l{Connecting Generic Linux Devices}
- \o \l{Connecting Maemo Devices}
- \o \l{Connecting Symbian Devices}
- \o \l{Managing Sessions}
- \endlist
- \o \l{Coding}
- \list
- \o \l{Using the Editor}
- \o \l{Semantic Highlighting}
- \o \l{Checking Code Syntax}
- \o \l{Completing Code}
- \o \l{Indenting Code}
- \o \l{Finding and Replacing}
- \o \l{Refactoring}
- \o \l{Using Qt Quick Toolbars}
- \o \l{Searching With the Locator}
- \o \l{Pasting and Fetching Code Snippets}
- \o \l{Using Text Editing Macros}
- \o \l{Configuring the Editor}
- \o \l{Using FakeVim Mode}
- \endlist
- \o \l{Developing Application UI}
- \list
- \o \l{Developing Qt Quick Applications}
- \list
- \o \l {Creating Qt Quick Projects}
- \o \l {Using Qt Quick Designer}
- \o \l {Creating Components}
- \o \l {Creating Buttons}
- \o \l {Creating Scalable Buttons and Borders}
- \o \l {Creating Screens}
- \o \l {Animating Screens}
- \o \l {Adding User Interaction Methods}
- \o \l {Exporting Designs from Graphics Software}
- \o \l {Implementing Application Logic}
- \o \l {Using QML Modules with Plugins}
- \endlist
- \o \l{Developing Widget Based Applications}
- \o \l{Optimizing Applications for Mobile Devices}
- \endlist
- \o \l{Building and Running Applications}
- \list
- \o \l{Building Applications for Multiple Targets}
- \o \l{Running Applications on Multiple Targets}
- \o \l{Specifying Build Settings}
- \list
- \o \l{Adding Qt Versions}
- \o \l{Adding Tool Chains}
- \endlist
- \o \l{Specifying Run Settings}
- \o \l{Specifying Editor Settings}
- \o \l{Specifying Code Style Settings}
- \o \l{Specifying Dependencies}
- \endlist
- \o \l{Debugging}
- \list
- \o \l{Debugging the Example Application}
- \o \l{Launching the Debugger}
- \o \l{Interacting with the Debugger}
- \o \l{Setting Up Debugger}
- \o \l{Using Debugging Helpers}
- \o \l{Debugging Qt Quick Projects}
- \o \l{Troubleshooting Debugger}
- \endlist
- \o \l{Analyzing Code}
- \list
- \o \l{Profiling QML Applications}
- \o \l{Detecting Memory Leaks}
- \o \l{Profiling Function Execution}
- \o \l{Running Valgrind Tools Remotely}
- \endlist
- \o \l{Deploying Applications to Mobile Devices}
- \list
- \o \l{Deploying Applications to Symbian Devices}
- \o \l{Deploying Applications to Maemo or MeeGo Harmattan Devices}
- \o \l{Publishing Maemo Applications to Extras-devel}
- \o \l{Publishing Applications to Ovi Store}
- \o \l{Building with Remote Compiler}
- \endlist
- \o \l{Getting Help}
- \o \l{Advanced Use}
- \list
- \o \l{Operating Systems and Supported Platforms}
- \o \l{Adding New Custom Wizards}
- \o \l{Setting Up a CMake Project}
- \o \l{Setting Up a Generic Project}
- \o \l{Using Version Control Systems}
- \o \l{Adding Qt Designer Plugins}
- \o \l{Using External Tools}
- \o \l{Using Maemo or MeeGo Harmattan Emulator}
- \o \l{Editing MIME Types}
- \o \l{Showing Task List Files in the Build Issues Pane}
- \o \l{Using Command Line Options}
- \o \l{Keyboard Shortcuts}
- \endlist
- \o \l{FAQ}
- \o \l{Tips and Tricks}
- \o \l{Known Issues}
- \o \l{Technical Support}
- \o \l{Glossary}
- \o \l{Acknowledgements}
- \endlist
-*/
-
-
-/*!
- \contentspage index.html
- \previouspage index.html
- \page creator-overview.html
- \nextpage creator-quick-tour.html
-
- \title Introducing Qt Creator
-
- Qt Creator is an integrated development environment (IDE) that provides you with
- tools to design and develop applications with the Qt application framework. Qt is designed for
- developing applications and user interfaces once and deploying them across several
- desktop and mobile operating systems. Qt Creator provides you with tools for
- accomplishing your tasks throughout the whole application development life-cycle,
- from creating a project to deploying the application on the target platforms.
-
- \image qtcreator-overview.png "Qt Creator overview"
-
- \section1 Cross-platform Development
-
- One of the major advantages of Qt Creator is that it allows a team of developers
- to share a project across different development platforms with a common tool
- for development and debugging.
-
- The recommended way to build a project is to use a version control system.
- Store and edit only project source files and the .pro and .pri files (for qmake)
- or CMakeLists.txt and *.cmake files (for CMake). Do not store
- files generated by the build system or Qt Creator, such as makefiles,
- .pro.user, and object files. Other approaches are possible,
- but we recommend that you do not use network resources, for example.
-
- Qt Creator allows you to specify separate build settings
- for each development platform. By default, \l{glossary-shadow-build}{shadow builds} are used to
- keep the build specific files separate from the source.
-
- You can create separate versions of project files to keep platform-dependent
- code separate. You can use qmake
- \l{http://qt.nokia.com/doc/4.7/qmake-tutorial.html#adding-platform-specific-source-files}{scopes}
- to select the file to process depending on which platform qmake is run on.
-
- Items such as open files, breakpoints, and evaluated expressions are stored in
- sessions. They are not considered to be part of the
- information shared across platforms.
-
- \section1 Creating Projects
-
- But why do you need projects? To be able to build and run applications,
- Qt Creator needs the same information as a compiler would need. This information
- is specified in the project build and run settings.
-
- Creating a project allows you to:
-
- \list
-
- \o Group files together
-
- \o Add custom build steps
-
- \o Include forms and resource files
-
- \o Specify settings for running applications
-
- \endlist
-
- Setting up a new project in Qt Creator is aided by a wizard that guides
- you step-by-step through the project creation process. In the first step, you
- select the type of the project from the categories: Qt Quick project, Qt widget
- project, or other project. Next, you select a location for the project and
- specify settings for it.
-
- \image qtcreator-new-qt-quick-project-wizard.png
-
- When you have completed the steps, Qt Creator automatically generates the
- project with required headers, source files, user interface descriptions
- and project files, as defined by the wizard.
- For example, if you choose to create a Qt Quick application, Qt Creator
- generates a QML file that you can modify with the integrated \QMLD.
-
- \section2 Adding Libraries
-
- In addition to Qt libraries, you can link your application to other
- libraries, such as system libraries or your own libraries. Further, your
- own libraries might link to other libraries. To be able to compile your
- project, you must add the libraries to your project. This also enables
- code completion and syntax highlighting for the libraries.
- The procedure of adding a library to a project depends on the build
- system that you use.
-
- \section2 Version Control Systems
-
- Qt Creator uses the version control system's command line clients to access
- your repositories. The following version control systems are supported:
-
- \list
-
- \o Git
-
- \o Subversion
-
- \o Perforce
-
- \o CVS
-
- \o Mercurial
-
- \o Bazaar
-
- \endlist
-
- The functions available to you in Qt Creator depend on the version control
- system. Basic functions are available for all the supported systems. They include
- comparing files with the latest versions stored in the repository and displaying the
- differences, viewing versioning history and change details, annotating files,
- and committing and reverting changes.
-
- \section1 Designing User Interfaces
-
- Qt Creator provides two integrated visual editors, \QMLD and \QD.
-
- \image qtcreator-ui-designers.png "Qt Quick Designer and Qt Designer"
-
- Large high-resolution screens, touch input, and significant graphics power
- are becoming common in portable consumer devices, such as mobile
- phones, media players, set-top boxes, and netbooks. To fully benefit from
- these features and to create intuitive, modern-looking, fluid user interfaces,
- you can use \l {http://doc.qt.nokia.com/4.7/qtquick.html}{Qt Quick}.
-
- Qt Quick consists of a rich set of user interface elements, a declarative
- language for describing user interfaces, and a language runtime. A
- collection of C++ APIs is used to integrate these high level features with
- classic Qt applications.
-
- You can edit QML code in the code editor or in the integrated \QMLD.
- The integration includes project management and code completion.
-
- If you need a traditional user interface that is clearly structured and
- enforces a platform look and feel, you can use the integrated \QD. You can
- compose and customize your widgets or dialogs and test them using different
- styles and resolutions.
-
- \section1 Code Editor
-
- As an IDE, Qt Creator differs from a text editor in that it knows how to build and run
- applications. It understands the C++ and QML languages as code, not just as plain text. This allows
- it to:
-
- \list
-
- \o Enable you to write well formatted code
-
- \o Anticipate what you are going to write and complete the code
-
- \o Display inline error and warning messages
-
- \o Enable you to semantically navigate to classes, functions, and symbols
-
- \o Provide you with context-sensitive help on classes, functions, and symbols
-
- \o Rename symbols in an intelligent way, so that other symbols with the same name
- that belong to other scopes are not renamed
-
- \o Show you the locations in code where a function is declared or called
-
- \endlist
-
- You can use the code editor to write code in Qt C++ or in the
- QML declarative programming language.
- QML is an extension to JavaScript, that provides a mechanism to declaratively build
- an object tree of QML elements. QML improves the integration between JavaScript and
- Qt's existing QObject based type system, adds support for automatic property bindings
- and provides network transparency at the language level.
-
- \section1 Building
-
- Qt Creator is integrated with cross-platform systems for build automation:
- qmake and CMake. In addition, you can import generic projects that do not use qmake
- or CMake, and specify that Qt Creator ignores your build system.
-
- Qt Creator provides support for building and running Qt applications for
- desktop environment (Windows, Linux, and Mac OS) and mobile devices
- (Symbian, Maemo, and MeeGo Harmattan).
- Build settings allow you to quickly switch between build targets.
-
- When you install the \QSDK, the build and run settings for the Harmattan,
- Maemo, and Symbian
- targets are set up automatically. However, you need to install and configure some
- additional software on the devices to be able to connect to them from the
- development PC.
-
- \note The only supported build system for mobile applications in Qt
- Creator is qmake.
-
- \section1 Testing
-
- If you install Qt Creator as part of \QSDK, the GNU Symbolic Debugger
- is installed automatically and you should be ready to start debugging after
- you create a new project. However, you can change the setup to use debugging
- tools for Windows, for example.
- You can connect mobile devices to your development PC and debug processes
- running on the devices.
-
- You can use code analysis tools to detect memory leaks, profile cache usage,
- and profile Qt Quick applications.
-
- You can test applications that are intended for mobile devices in the Qt
- Simulator and Maemo or MeeGo Harmattan emulator, but you also need to test
- the applications
- on real devices.
-
- \section2 Debuggers
-
- Qt Creator is integrated to several external native debuggers:
-
- \list
-
- \o GNU Symbolic Debugger (GDB)
-
- \o Microsoft Console Debugger (CDB)
-
- \o internal JavaScript debugger
-
- \endlist
-
- You can use the Qt Creator \gui Debug mode to inspect the state of your
- application while debugging. You can interact with the debugger in several
- ways, including the following:
-
- \list
- \o Go through a program line-by-line or instruction-by-instruction.
- \o Interrupt running programs.
- \o Set breakpoints.
- \o Examine the contents of the call stack.
- \o Examine and modify registers and memory contents of
- the debugged program.
- \o Examine and modify registers and memory contents of
- local and global variables.
- \o Examine the list of loaded shared libraries.
- \o Create snapshots of the current state of the debugged program
- and re-examine them later.
- \endlist
-
- Qt Creator displays the raw information provided by the native debuggers
- in a clear and concise manner with the goal to simplify the debugging process
- as much as possible without losing the power of the native debuggers.
-
- In addition to the generic IDE functionality provided by stack view, views for
- locals and expressions, registers, and so on, Qt Creator includes
- features to make debugging Qt-based applications easy. The debugger
- plugin understands the internal layout of several Qt classes, for
- example, QString, the Qt containers, and most importantly QObject
- (and classes derived from it), as well as most containers of the C++
- Standard Library and some GCC and Symbian extensions. This
- deeper understanding is used to present objects of such classes in
- a useful way.
-
- \section3 QML Script Console
-
- You can use the Qt Creator \gui Debug mode to inspect the state of
- the application while debugging JavaScript functions. You can set breakpoints,
- view call stack trace, and examine locals and expressions.
-
- When the application is interrupted by a breakpoint, you can use the \gui {QML
- Script Console} to execute JavaScript expressions in the current context. You can
- type JavaScript expressions and use them to get information about the state of the
- application, such as property values.
-
- If you change property values or add properties in the code editor, the
- changes are updated in the running application when they are saved.
-
- \section3 QML Inspector
-
- While the application is running, you can use the \gui {QML Inspector} view to
- explore the object structure, debug animations, and inspect colors. When debugging
- complex applications, you can use the inspection mode to jump to the position in code
- where an element is defined.
-
- \section2 Code Analysis Tools
-
- The memory available on devices is limited and you should use it carefully.
- Qt Creator integrates Valgrind code analysis tools for detecting memory
- leaks and profiling function execution. These tools are only supported on
- Linux and Mac OS, but you can run them remotely from Windows. You must
- download and install them separately to use them from Qt
- Creator.
-
- The QML Profiler is installed as part of Qt Creator. It allows you
- to profile your Qt Quick applications and is available on all supported
- development platforms.
-
- \section2 Qt Simulator
-
- You can use the Qt Simulator to test Qt applications that are intended
- for mobile devices in an environment similar to that of the device. You
- can change the information that the device has about its configuration
- and environment.
-
- Qt Simulator does not support any device specific APIs by design. Therefore,
- applications that run well on Qt Simulator also run on any device that hosts
- the Qt and Qt Mobility libraries. However, this means that you cannot use
- Qt Simulator to test applications that use device specific libraries, such
- as Symbian C++ APIs. To test such applications, use the device emulators or
- real devices.
-
- The Qt Simulator is installed as part of the \QSDK. After it is
- installed, you can select it as a build target in Qt Creator.
-
- \section2 Maemo and MeeGo Harmattan Emulator
-
- The Maemo 5 (Fremantle) and MeeGo Harmattan emulator are installed as part
- of the \QSDK. After they are installed, you can start them from Qt Creator.
-
- The Maemo 5 emulator emulates the Nokia N900 device environment. You can test
- applications in conditions practically identical to running the application
- on a Nokia N900 device with the software update release 1.3 (V20.2010.36-2).
-
- The Harmattan emulator emulates the Nokia N9 device environment.
-
- With the emulators, you can test how your application reacts to hardware
- controls, such as the power button, and to the touch screen.
- Usually, it is faster to test on a real device connected to the development
- PC than to use the emulators.
-
- \section1 Deploying
-
- Qt Creator deploy configurations handle the packaging of the application as an
- executable and copying it to a location developers want to run the executable at.
- The files can be copied to a location in the file system of the development PC
- or to a mobile device.
-
- Qt Creator allows you to create installation packages for Symbian, Maemo,
- and MeeGo Harmattan
- devices that are suitable for publishing on Ovi Store and other channels.
-
-*/
-
-/*!
- \contentspage index.html
- \previouspage creator-advanced.html
- \page creator-os-supported-platforms.html
- \nextpage creator-project-wizards.html
-
- \title Operating Systems and Supported Platforms
-
- \section1 Operating Systems
-
- Qt Creator is available in binary packages for the following operating
- systems:
- \list
- \o Windows 7
- \o Windows XP Service Pack 2
- \o Windows Vista
- \o (K)Ubuntu Linux 8.04 (32-bit and 64-bit) or later, with the following:
- \list
- \o g++
- \o make
- \o libglib2.0-dev
- \o libSM-dev
- \o libxrender-dev
- \o libfontconfig1-dev
- \o libxext-dev
- \o libfreetype6-dev
- \o libx11-dev
- \o libxcursor-dev
- \o libxfixes-dev
- \o libxft-dev
- \o libxi-dev
- \o libxrandr-dev
- \o If you are using QtOpenGL, libgl-dev and libglu-dev
- \endlist
- \o Mac OS 10.5 or later with the following:
- \list
- \o Xcode tools for your Mac OS X version available from your Mac
- OS X installation DVDs or at \l http://developer.apple.com.
- \endlist
- \endlist
-
- \omit ## Are the Xcode tools still needed separately? \endomit
-
- \section1 Compiling Qt Creator from Source
-
- To build Qt Creator itself from the source, see the requirements and
- instructions in the readme file that is located in the source repository.
-
- \section1 Supported Platforms
-
- You can develop applications for the following platforms:
-
- \list
-
- \o Desktop
-
- \o Qt Simulator
-
- \o Maemo 5
-
- \o MeeGo Harmattan
-
- \o Generic remote Linux
-
- \o Symbian
-
- \endlist
-
- The following table summarizes operating system support for developing
- applications for mobile device platforms.
-
- \table
- \header
- \o {1,6} Operating system
- \o {6,1} Platform
- \header
- \o Desktop
- \o Qt Simulator
- \o Maemo 5
- \o MeeGo Harmattan
- \o Generic Remote Linux
- \o Symbian
-
- \row
- \o Windows
- \o Yes
- \o Yes
- \o Yes
- \o Yes
- \o Yes
- \o Yes
- \row
- \o Linux
- \o Yes
- \o Yes
- \o Yes
- \o Yes
- \o Yes
- \o Yes (by using Remote Compiler for building)
- \row
- \o Mac OS X
- \o Yes
- \o Yes
- \o Yes
- \o Yes
- \o Yes
- \o Yes (by using Remote Compiler for building)
- \endtable
-*/
-
-
-/*!
- \contentspage index.html
- \previouspage creator-overview.html
- \page creator-quick-tour.html
- \nextpage creator-getting-started.html
-
- \title Qt Creator User Interface
-
- \image qtcreator-breakdown.png
-
- When you start Qt Creator, it opens to the \gui Welcome mode, where you can:
-
- \list
-
- \o Read news from the Qt labs
-
- \o Open tutorials and example projects
-
- \o Create and open projects
-
- \o Send feedback to the development team
-
- \o Open recent sessions and projects
-
- \endlist
-
- You can use the mode selector to change to another Qt Creator mode.
- The following image displays an example application in \gui Edit mode
- and \gui Design mode.
-
- \image qtcreator-qt-quick-editors.png "Edit mode and Design mode"
-
- Qt Creator has been localized into several languages. If the system language
- is one of the supported languages, it is automatically selected. To change
- the language, select \gui {Tools > Options > Environment} and select a language
- in the \gui Language field. The change takes effect after you restart Qt Creator.
-
- \section1 Qt Creator Modes
-
- The mode selector allows you to quickly switch between tasks such as
- editing project and source files, designing application UIs,
- configuring how projects are built and
- executed, and debugging your applications. To change modes, click the
- icons, or use the \l{keyboard-shortcuts}{corresponding keyboard shortcut}.
-
- You can use Qt Creator in the following modes:
-
- \list
- \o \gui Welcome mode for opening projects.
- \o \gui{\l{Using the Editor}{Edit}} mode for editing project and source files.
- \o \gui{\l{Developing Application UI}{Design}} mode for designing and developing
- application user interfaces. This mode is available for UI files (.ui or
- .qml).
- \o \gui{\l{Debugging}{Debug}} mode for inspecting the state of your program while
- debugging.
- \o \gui{\l{Specifying Build Settings}{Projects}} mode for configuring project building and
- execution. This mode is available when a project is open.
- \o \gui{\l{Analyzing Code}{Analyze}} mode for using code analysis tools
- to detect memory leaks and profile C++ or QML code.
- \o \gui{\l{Getting Help}{Help}} mode for viewing Qt documentation.
- \endlist
-
- Certain actions in Qt Creator trigger a mode change. Clicking on
- \gui {Debug} > \gui {Start Debugging} > \gui {Start Debugging}
- automatically switches to \gui {Debug} mode.
-
-
- \section1 Browsing Project Contents
-
- The sidebar is available in the \gui Edit and \gui Debug modes.
- Use the sidebar to browse projects, files, and bookmarks, and to view
- the class hierarchy.
- \image qtcreator-sidebar.png
-
- You can select the content of the sidebar in the sidebar menu:
- \list
- \o \gui Projects shows a list of projects open in the current
- session.
- \o \gui{Open Documents} shows currently open files.
- \o \gui Bookmarks shows all bookmarks for the current session.
- \o \gui{File System} shows all files in the currently selected
- directory.
- \o \gui {Class View} shows the class hierarchy of the currently
- open projects.
- \o \gui Outline shows the symbol hierachy of a C++ file and the element hierarchy of a QML file.
- \o \gui {Type Hierarchy} shows the base classes of a class.
-
- \endlist
-
- You can change the view of the sidebar in the following ways:
- \list
- \o To toggle the sidebar, click \inlineimage qtcreator-togglebutton.png
- or press \key Alt+0 (\key Cmd+0 on Mac OS X).
- \o To split the sidebar, click \inlineimage qtcreator-splitbar.png
- . Select new content to view in the split view.
- \o To close a sidebar view, click
- \inlineimage qtcreator-closesidebar.png
- .
- \endlist
-
- The additional options in each view are described in the following
- sections.
-
- \section2 Viewing Project Files
-
- The sidebar displays projects in a project tree. The project tree contains
- a list of all projects open in the current session. The files for each
- project are grouped according to their file type.
-
- You can use the project tree in the following ways:
- \list
- \o To bring up a context menu containing the actions most commonly
- needed right-click an item in the project tree.
- For example, through the menu of the project root directory you can,
- among other actions, build, re-build, clean and run the project.
- \o To hide the categories and sort project files alphabetically, click
- \inlineimage qtcreator-filter.png
- and select \gui{Simplify Tree}.
- \o To hide source files which are automatically generated by the build
- system, during a build, click \inlineimage qtcreator-filter.png
- and select \gui{Hide Generated Files}.
- \o To keep the position in the project tree synchronized with the file
- currently opened in the editor, click
- \inlineimage qtcreator-synchronizefocus.png
- .
- \o To see the absolute path of a file, move the mouse pointer over the
- file name.
- \endlist
-
- \section2 Viewing the File System
-
- If you cannot see a file in the \gui Projects view, switch to the
- \gui {File System} view, which shows all the files in the file system.
-
- To keep the position in the tree synchronized with the file
- opened in the editor, click
- \inlineimage qtcreator-synchronizefocus.png
- .
-
- \section2 Viewing the Class Hierarchy
-
- The \gui {Class View} shows the class hierarchy of the currently
- open projects. To organize the view by subprojects, click
- \inlineimage qtcreator-show-subprojects.png
- .
-
- \section2 Viewing QML Elements
-
- The \gui Outline view shows the element hierarchy in a QML file.
-
- \list
-
- \o To see a complete list of all bindings, click
- \inlineimage qtcreator-filter.png
- and select \gui{Show All Bindings}.
-
- \o To keep the position in the view synchronized with the element
- selected in the editor, click
- \inlineimage qtcreator-synchronizefocus.png
- .
-
- \endlist
-
- \section2 Viewing Type Hierarchy
-
- To view the base classes of a class, right-click the class and select
- \gui {Open Type Hierarchy} or press \key {Ctrl+Shift+T}.
-
- \section1 Viewing Output
-
- The task pane in Qt Creator can display one of the following panes:
- \list
- \o \gui{Build Issues}
- \o \gui{Search Results}
- \o \gui{Application Output}
- \o \gui{Compile Output}
- \o \gui{General Messages}
- \o \gui{Version Control}
- \endlist
-
- Output panes are available in all \l{Qt Creator modes}{modes}.
- Click the name of an output pane to open the pane. To maximize
- an open output pane, click the \gui {Maximize Output Pane} button
- or press \key {Alt+9}.
-
- To search within the \gui{Application Output} and \gui{Compile Output}
- panes, press \key {Ctrl+F} when the pane is active. Enter search
- criteria in the \gui Find field and click the left and right arrows to
- search down and up in the pane.
-
- To open the \gui{General Messages} and \gui{Version Control}
- panes, select \gui {Window > Output Panes}.
-
-
- \section2 Build Issues
-
- The \gui{Build Issues} pane provides a list of errors and warnings
- encountered during a build. The pane filters out irrelevant output from
- the build tools and presents the issues in an organized way.
-
- Right-clicking on a line brings up a context menu with options to copy
- the contents and to show a version control annotation view of the
- line that causes the error message.
-
- \image qtcreator-build-issues.png
-
- To view task lists in the \gui{Build Issues} pane, click
- \inlineimage qtcreator-filter.png
- and select \gui{My Tasks}. Entries from a task list file (.tasks) are
- imported to the pane. Press \key F6 and \key Shift+F6 to jump from one issue
- to the next.
-
- For more information about creating task files, see
- \l{Showing Task List Files in the Build Issues Pane}.
-
- \section2 Search Results
-
- The \gui{Search Results} pane displays the results for global searches,
- for example, searching within a current document, files on disk, or all
- projects.
-
- The figure below shows an example search result for all
- occurrences of \c textfinder within the \c "/TextFinder" directory.
-
- \image qtcreator-search-pane.png
-
-
- \section2 Application Output
-
- The \gui{Application Output} pane displays the status of a program when
- it is executed, and the debug output.
-
- The figure below shows an example output from qDebug().
-
- \image qtcreator-application-output.png
-
-
- \section2 Compile Output
-
- The \gui{Compile Output} pane provides all output from the compiler.
- The \gui{Compile Output} is a more detailed version of information
- displayed in the \gui{Build Issues} pane.
-
- \image qtcreator-compile-pane.png
-
- \section1 Navigating with Keyboard
-
- Qt Creator caters not only to developers who are used to using the mouse,
- but also to developers who are more comfortable with the keyboard. A wide
- range of \l{keyboard-shortcuts}{keyboard} and
- \l{Searching With the Locator}{navigation} shortcuts are available to help
- speed up the process of developing your application.
-
-*/
-
-
-/*!
- \contentspage index.html
- \previouspage creator-remote-compiler.html
- \page creator-help.html
- \nextpage creator-advanced.html
-
- \title Getting Help
-
- Qt Creator comes fully integrated with Qt documentation and
- examples using the Qt Help plugin.
-
- \list
- \o To view documentation, switch to \gui Help mode.
- \o To obtain context sensitive help, move the text cursor to a Qt class
- or function and press \key F1. The documentation is displayed in a
- pane next to the code editor, or, if there is not enough vertical
- space, in the fullscreen \gui Help mode.
- \o To select and configure how the documentation is displayed in the
- \gui Help mode, select \gui Tools > \gui Options... > \gui Help.
- \endlist
-
- The following image displays the \gui Search pane in the \gui Help mode.
-
- \image qtcreator-help-search.png
-
- The following image displays the context sensitive help in the \gui Edit
- mode.
-
- \image qtcreator-context-sensitive-help.png
-
- \section1 Finding Information in Qt Documentation
-
- Qt Creator, \QSDK and other Qt deliverables contain documentation
- as .qch files. All the documentation is accessible in the \gui Help mode.
-
- To find information in the documentation, select:
-
- \list
-
- \o \gui Bookmarks to view a list of pages on which you have added bookmarks.
-
- \o \gui Contents to see all the documentation installed on the development
- PC and to browse the documentation contents.
-
- \o \gui Index to find information based on a list of keywords in all the
- installed documents.
-
- \o \gui {Open Pages} to view a list of currently open documentation pages.
-
- \o \gui Search to search from all the installed documents.
-
- \endlist
-
- \section2 Adding Bookmarks to Help Pages
-
- You can add bookmarks to useful help pages to easily find them later
- in the \gui Bookmarks view. You can either use the page title as the
- bookmark or change it to any text. You can organize the bookmarks in
- folders in the view.
-
- \image qtcreator-help-add-bookmark-dlg.png "Add Bookmark dialog"
-
- To add a bookmark to an open help page:
-
- \list 1
-
- \o Click the
- \inlineimage qtcreator-help-add-bookmark.png
- (\gui {Add Bookmark}) button on the toolbar.
-
- \o In the \gui {Add Bookmark} dialog, click \gui OK to save the
- page title as a bookmark in the \gui Bookmarks folder.
-
- \endlist
-
- To import and export bookmarks, select \gui {Tools > Options... > Help >
- General Settings > Import} or \gui Export.
-
- \section1 Adding External Documentation
-
- You can display external documentation in the \gui Help mode.
- To augment or replace the documentation that ships with Qt Creator and Qt:
- \list 1
- \o Create a .qch file from your documentation.
-
- For information on how to prepare your documentation and create a
- .qch file, see
- \l{http://doc.qt.nokia.com/4.7/qthelp-framework.html}{The Qt Help Framework}.
- \o To add the .qch file to Qt Creator, select \gui Tools >
- \gui Options... > \gui Help > \gui Documentation > \gui Add.
- \endlist
-
- \section1 Detaching the Help Window
-
- By default, context-sensitive help is opened in a window next to the
- code editor when you press \key F1. If there is not enough vertical
- space, the help opens in the full-screen help mode.
-
- You can specify that the help always opens in full-screen mode or
- is detached to an external window. Select \gui {Tools > Options... > Help >
- General Settings} and specify settings for displaying context-sensitive help
- in the \gui {On context help} field. To detach the help window, select
- \gui {Always Show Help in External Window}.
-
- You can select the help page to open upon startup in the \gui {Home Page}
- field.
-
- \section1 Using Documentation Filters
-
- You can filter the documents displayed in the \gui Help mode to find
- relevant information faster. Select from a list of filters in the
- \gui {Filtered by} field. The contents of the \gui Index and \gui Contents
- pane in the sidebar change accordingly.
-
- \image qtcreator-help-filters.png "Help filters"
-
- You can modify the filters to include external documentation, for example,
- or you can define your own filters. To construct filters, you can use the
- filter attributes that are specified in the documentation. Each document
- contains at least one filter attribute. If several documents contain the
- same filter attribute, such as \c tools, you can use that attribute to
- include all those documents.
-
- To add filters:
-
- \list 1
-
- \o Select \gui {Tools > Options... > Help > Filters > Add}.
-
- \o Enter a name for the filter and press \gui {OK}.
-
- \o In \gui Attributes, select the documents that you want to include
- in the filter.
-
- \image qtcreator-help-filter-attributes.png "Help filter attributes"
-
- \o Click \gui OK.
-
- \o In the \gui Help mode, select the filter in the \gui {Filtered by}
- field to see the filtered documentation in the sidebar.
-
- \endlist
-
- To modify filters, select a filter in \gui Filters, select the attributes,
- and then click \gui Apply.
-
- To remove filters, select them in \gui Filters, and click \gui Remove.
-
-*/
-
-
-/*!
- \contentspage index.html
- \previouspage creator-editor-fakevim.html
- \page creator-design-mode.html
- \nextpage creator-visual-editor.html
-
- \title Developing Application UI
-
- Large high-resolution screens, touch input, and significant graphics power
- are becoming common in portable consumer devices, such as mobile
- phones, media players, set-top boxes, and netbooks. To fully benefit from
- these features and to create intuitive, modern-looking, fluid user interfaces,
- you can use \l {http://doc.qt.nokia.com/4.7/qtquick.html}{Qt Quick}.
-
- Qt Quick consists of a rich set of user interface elements, a declarative
- language for describing user interfaces, and a language runtime. A
- collection of C++ APIs is used to integrate these high level features with
- classic Qt applications.
-
- You can edit QML code in the code editor or in the integrated \QMLD.
-
- \image qtcreator-design-mode.png "Design mode"
-
- The integration includes project management and code completion.
-
- If you need a traditional user interface that is clearly structured and
- enforces a platform look and feel, you can use the integrated \QD. You can
- compose and customize your widgets or dialogs and test them using different
- styles and resolutions.
-
- The following sections describe how to develop application UI:
-
- \list
-
- \o \l{Developing Qt Quick Applications}
- \o \l{Developing Widget Based Applications}
- \o \l{Optimizing Applications for Mobile Devices}
-
- \endlist
-
-*/
-
-
-/*!
- \contentspage index.html
- \previouspage creator-qml-modules-with-plugins.html
- \page creator-using-qt-designer.html
- \nextpage creator-usability.html
-
- \title Developing Widget Based Applications
-
- Widgets and forms created with \QD are integrated seamlessly with
- programmed code by using the Qt signals and slots mechanism that allows you
- to easily assign behavior to
- graphical elements. All properties set in \QD can be changed dynamically within the code.
- Furthermore, features such as widget promotion and custom plugins allow you to use your
- own widgets with \QD. For more information, see
- \l{Adding Qt Designer Plugins}.
-
- Qt Creator automatically opens all .ui files in the integrated \QD, in
- \gui Design mode.
-
- \image qtcreator-formedit.png
-
- For more information about \QD, see the
- \l{http://doc.qt.nokia.com/4.7/designer-manual.html}{Qt Designer Manual}.
-
- Generally, the integrated \QD contains the same functions as the standalone
- \QD. The following sections describe the differences.
-
- \section1 Code Editor Integration
-
- To switch between forms (\gui Design mode) and code (\gui Edit mode),
- press \key Shift+F4.
-
- You can use Qt Creator to create stub implementations of slot functions.
- In the \gui Design mode, right-click a widget to open a context menu, and
- then select \gui {Go to Slot...}. Select a signal in the list to go to an
- existing slot function or to create a new slot function.
-
- \section1 Managing Image Resources
-
- In standalone \QD, image resources are created using the built-in
- \gui {Resource Editor}. In Qt Creator, .ui files are usually part of a
- project, which may contain several resource files (.qrc). They are created
- and maintained by using the Qt Creator Resource Editor. The \QD
- \gui {Resource Editor} is de-activated and the image resources are
- displayed in the \QD \gui {Resource Browser}.
-
- \section1 Specifying Settings for Qt Designer
-
- To change the layout of \QD user interface elements:
-
- \list 1
- \o Select \gui Tools > \gui{Form Editor} > \gui Views >
- \gui Locked.
-
- When this option is unchecked, you can change the layout.
- \o Click the header of an element and drag the element to a new
- position.
- \endlist
-
- To specify settings for \QD:
-
- \list
-
- \o Select \gui Tools > \gui Options... > \gui Designer.
-
- \o Specify settins for generating classes and code in \gui {Class
- Generation}.
-
- \o Specify embedded device profiles, that determine style, font, and
- screen resolution, for example, in \gui{Embedded Design}.
-
- \o Specify settings for the grid and previewing forms in \gui Forms.
-
- \o Specify an additional folder for saving templates in \gui{Template
- Paths}.
-
- \endlist
-
- To preview the settings, select \gui Tools > \gui{Form Editor} >
- \gui Preview, or press \key Alt+Shift+R.
-
- \section1 Previewing Forms Using Device Skins
-
- A \e {device skin} is a set of configuration files that describe a mobile
- device. It includes a border image that surrounds the form and depicts a
- mobile device with its buttons.
-
- To preview your form using device skins:
-
- \list 1
-
- \o Select \gui Tools > \gui Options... > \gui Designer.
-
- \o Select the \gui{Print/Preview Configuration} check box.
-
- \o In the \gui {Device skin} field, select a device skin.
-
- \o When the form is open in \gui Design mode, press \key Alt+Shift+R.
-
- \o To end the preview, right-click the skin and select \gui Close in
- the context menu.
-
- \endlist
-*/
-
-
-/*!
- \contentspage index.html
- \previouspage quick-projects.html
- \page creator-using-qt-quick-designer.html
- \nextpage quick-components.html
-
- \title Using Qt Quick Designer
-
- You can edit .qml files in the \QMLD visual editor or in the
- code editor.
-
- In \gui Projects, double-click a .qml file to open it in the code
- editor. Then select the \gui {Design} mode to edit the file in the
- visual editor.
-
- \image qmldesigner-visual-editor.png "Visual editor"
-
- Use the visual editor panes to manage your project:
-
- \list
-
- \o \gui {Navigator} pane displays the QML elements in the current QML file
- as tree structure.
-
- \o \gui {Library} pane displays the building blocks that you can use to design
- applications: predefined QML elements, your own QML components, Qt Quick
- components for Symbian or MeeGo that you import to the project, and other
- resources.
-
- \o \gui Canvas is the working area where you create QML components and
- design applications.
-
- \o \gui {Properties} pane organizes the properties of the selected QML element
- or QML component. You can change the properties also in the code editor.
-
- \o \gui {State} pane displays the different states of the component. QML
- states typically describe user interface configurations, such as the UI
- elements, their properties and behavior and the available actions.
-
- \endlist
-
- \section1 Managing Element Hierarchy
-
- The \gui Navigator pane displays the
- \l{http://doc.qt.nokia.com/4.7/qdeclarativeelements.html}{QML elements}
- in the current QML file and their relationships.
- Elements are listed in a tree structure, below their parent.
-
- \image qmldesigner-navigator.png "Navigator pane"
-
- You can select elements in the \gui Navigator to edit their properties
- in the \gui Properties pane. Elements can access the properties of their
- parent element. To select elements on the canvas, right-click an element,
- and select another element in the context menu.
-
- Typically, child elements are located within the parent element on the
- canvas. However, they do not necessarily have to fit inside the parent element.
- For example, you might want to make a mouse area larger than the rectangle
- or image beneath it.
-
- \image qmldesigner-element-size.png "Mouse area for a button"
-
- When you copy an element, all its child elements are also copied. When
- you remove an element, the child elements are also removed.
-
- You can show and hide items to focus on specific parts of the application.
- Click the
- \inlineimage qmldesigner-show-hide-icon.png
- icon to change the visibility of an element on the canvas. To change the
- visibility of an element in the application, use the \gui Visibility
- check box or the \gui Opacity field in the \gui Properties pane. If you set
- \gui Opacity to 0, elements are hidden, but you can still apply animation
- to them.
-
- As all properties, visibility and opacity are inherited from the parent
- element. To hide or show child elements, edit the properties of the
- parent element.
-
- To view lists of files or projects, instead, select \gui {File System},
- \gui {Open Documents}, or \gui Projects in the menu.
- To view several types of content at a time, split the sidebar by clicking
- \inlineimage qtcreator-splitbar.png
- .
-
- \section2 Setting the Stacking Order
-
- The \l{http://doc.qt.nokia.com/4.7/qml-item.html#z-prop}{z property} of an
- element determines its position in relation to its sibling elements in the
- element hierarchy. By default, elements with a higher stacking value are
- drawn on top of siblings with a lower stacking value. Elements with the same
- stacking value are drawn in the order they are listed, from the last item
- up.
-
- To change the stacking order of an item, right-click it on the canvas and
- select \gui {Stack (z)}. You can raise or lower the stack value of an item
- or move the item to the front or back of all its siblings. To remove the
- \c z property, select \gui Reset.
-
- \section2 Switching Parent Elements
-
- When you drag and drop QML elements to the canvas, Qt Quick Designer
- adds the new element as a child of the element beneath it.
- When you move elements on the canvas, Qt Quick Designer cannot determine
- whether you want to adjust their position or attach them to a new
- parent element. Therefore, the parent element is not automatically
- changed. To change the parent of the element, press down the \key Shift
- key before you drag and drop the element into a new position. The topmost
- element under the cursor becomes the new parent of the element.
-
- You can change the parent of an element also in the \gui Navigator pane.
- Drag and drop the element to another position in the tree or use the arrow
- buttons to move the element in the tree.
-
- \image qmldesigner-navigator-arrows.png "Navigator arrow buttons"
-
- \section1 Element Library
-
- The \gui {Library} pane contains two tabs: \gui {Items} and \gui {Resources}.
- The \gui Items pane displays the QML elements grouped by type: your own QML
- components, basic elements, positioner elements, and views.
-
- Sets of UI components with the MeeGo and Symbian look and feel have been
- defined for Qt Quick. They are based on standard QML elements. To view the
- UI components in the \gui {Library} pane, add import statements to the .pro
- file of your project:
-
- \list
-
- \o \c {import com.nokia.symbian 1.0} for Symbian
-
- \o \c {import com.nokia.meego 1.0} for MeeGo
-
- \endlist
-
- The Qt Quick Application wizard adds the import statements automatically
- when you select the component set to use for your project.
-
- \image qmldesigner-qml-components.png "QML Components pane"
-
- The \gui {Resources} pane displays the images and other files that you copy to
- the project folder (to the same subfolder as the QML files).
-
- \section1 Specifying Element Properties
-
- The \gui Properties pane displays all the properties of the selected QML element.
- The properties are grouped by type. The top part of the pane displays properties
- that are common to all elements, such as element type, position, size,
- and visibility.
-
- The bottom part of the pane displays properties that are specific to each element
- type. For example, the following image displays the properties you can set for
- \gui Rectangle and \gui Text elements.
-
- \image qmldesigner-element-properties.png
-
- You can use a context-menu to reset some element properties. To reset the
- position or size property of an element, right-click the element and select
- \gui {Edit > Reset Position} or \gui {Reset Size} in the context menu. To
- set the visibility of the component, select \gui {Edit > Visibility}.
-
- For more information on the properties available for an element, press \key {F1}.
-
- \section2 Viewing Changes in Properties
-
- The default values of properties are displayed in white color, while the
- values that you specify explicitly are highlighted with blue color. In
- addition, property changes in states are highlighted with blue.
-
- This allows you to easily see which values are set in the .qml file and
- which values are default characteristics of an element or a component.
-
- When editing states, you can easily see which values are explicitly set in
- the current state and which values are derived from the base state.
-
- The following images illustrate this. In the base state, the \gui Position,
- \gui Size, and \gui Colors values are explicitly set and highlighted.
-
- \image qmldesigner-properties-explicit-base.png "Explicitly set properties"
-
- In \gui State1, only the color is explicitly set and highlighted.
-
- \image qmldesigner-properties-explicit-state1.png "Explicitly set properties"
-
- Resetting a property sets it back to the default value and removes the value
- from the .qml file.
-
- \note As a result, all boolean values can be visualized in four different
- ways.
-
- For example, visibility can be visualized as follows:
-
- \table
- \row
- \i \image qmldesigner-boolean-true.png
- \i TRUE
- \i The element is visible by default. The visibility might be
- overridden by the visibility set in the base state.
- \row
- \i \image qmldesigner-boolean-true-blue.png
- \i TRUE (highlighted)
- \i The element is explicitly set to visible.
- \row
- \i \image qmldesigner-boolean-false.png
- \i FALSE
- \i The element is hidden by default. The visibility might be
- overridden by the visibility set in the base state.
- \row
- \i \image qmldesigner-boolean-false-blue.png
- \i FALSE (hightlighted)
- \i The item is explicitly set to hidden.
- \endtable
-
- \section2 Setting Expressions
-
- \l{http://doc.qt.nokia.com/4.7/propertybinding.html}{Property binding}
- is a declarative way of specifying the value of a property.
- Binding allows a property value to be expressed as an JavaScript expression
- that defines the value relative to other property values or data accessible
- in the application. The property value is automatically kept up to date if
- the other properties or data values change.
-
- Property bindings are created implicitly in QML whenever a property is assigned
- an JavaScript expression. To set JavaScript expressions as values of properties
- in Qt Quick Designer, click the circle
- icon next to a property to open a context menu, and select \gui {Set Expression}.
-
- \image qmldesigner-set-expression.png "Element properties context menu"
-
- To remove expressions, select \gui Reset in the context menu.
-
- For more information on the JavaScript environment provided by QML, see
- \l{http://doc.qt.nokia.com/4.7/qdeclarativejavascript.html}{Integrating JavaScript}.
-
- \section2 Marking Text Elements for Translation
-
- To support translators, mark each text element that should be translated.
- In the \gui Properties pane, \gui Text field, select \gui tr.
-
- \image qmldesigner-text-property-tr.png "Text properties"
-
- The text string is enclosed in a \c qsTr call.
-
- \image qml-translate.png "Text marked for translation"
-
- \section2 Loading Placeholder Data
-
- \QMLD supports views, models, and delegates, so that when you add a Grid
- View, List View, or Path View element, the ListModel and the delegate
- component are added automatically.
-
- However, the missing context of the application presents a challenge for
- \QMLD. Specific models defined in C++ are the most obvious case. Often,
- the context is missing simple properties, which are either defined in C++,
- or in other QML files. A typical example is a component which uses the
- properties of its parent, such as \c parent.width.
-
- \section3 Using Dummy Models
-
- If you open a file in \QMLD that references a C++ model, you see nothing on
- the canvas. If the data in the model is fetched from the internet, you have
- no control over it. To get reliable data, \e {dummy data} was introduced.
-
- For example, the following code snippet describes the file example.qml that
- contains a ListView that in turn specifies a C++ model:
-
- \snippet snippets/qml/dummydata.qml 0
-
- Create a directory named \e dummydata in the root directory of the project,
- so that it is not deployed to the device. In the \c dummydata directory,
- create a QML file that has the same name as the value of \c model:
-
- \code
- qml/exampleapp/example.qml
- dummydata/dataModel.qml
- \endcode
-
- Then create the dataModel.qml file that contains the dummy data:
-
- \snippet snippets/qml/datamodel.qml 0
-
- \section3 Creating Dummy Context
-
- The following example presents a common pattern in QML:
-
- \code
- Item {
- width: parent.width
- height: parent.height
- }
- \endcode
-
- This works nicely for applications but \QMLD displays a zero-sized item.
- A parent for the opened file does not exist, because the context is
- missing. To get around the missing context, the idea of a \e {dummy
- context} is introduced. If you place a file with the same name as the
- application (here, example.qml) in the \c {dummydata/context} directory,
- you can fake a parent context:
-
- \snippet snippets/qml/dummydatacontext.qml 0
-
- \section2 Setting Anchors and Margins
-
- In addition to arranging elements in a grid, row, or column, you can use
- \l{http://doc.qt.nokia.com/4.7/qml-anchor-layout.html}{anchors} to lay out screens.
- In an anchor-based layout, each item can be thought of as having a set of
- invisible \e anchor lines: top, bottom, left, right, fill, horizontal center,
- vertical center, and baseline.
-
- In the \gui Layout pane you can set anchors and margins for elements. To set
- the anchors of an item, click the anchor buttons. You can combine the top/bottom,
- left/right, and horizontal/vertical anchors to anchor objects in the corners of
- the parent element or center them horizontally or vertically within the parent
- element.
-
- \image qmldesigner-anchor-buttons.png "Anchor buttons"
-
- In version 2.1, specifying the baseline anchor in Qt Quick Designer is
- not supported. You can specify it using the code editor.
-
- For performance reasons, you can only anchor an element to its siblings and
- direct parent. By default, an element is anchored to its parent when you
- use the anchor buttons. Select a sibling of the element in the \gui Target
- field to anchor to it, instead.
-
- Arbitrary anchoring is not supported. For example, you cannot specify:
- \c {anchor.left: parent.right}. You have to specify: \c {anchor.left: parent.left}.
- When you use the anchor buttons, anchors to the parent element are always
- specified to the same side. However, anchors to sibling elements are specified
- to the opposite side: \c {anchor.left: sibling.right}. This allows you to keep
- sibling elements together.
-
- In the following image, \gui{Rectangle 2} is anchored to its siblings on its
- right and left and to the bottom of its parent.
-
- \image qmldesigner-anchors.png "Anchoring sibling elements"
-
- The anchors for \gui{Rectangle 2} are specified as follows in code:
-
- \qml
- Rectangle {
- id: rectangle2
- anchors.right: rectangle3.left
- anchors.rightMargin: 15
- anchors.left: rectangle1.right
- anchors.leftMargin: 15
- anchors.bottom: parent.bottom
- anchors.bottomMargin: 15
- // ...
- }
- \endqml
-
- Margins specify the amount of empty space to leave to the outside of an item.
- Margins only have meaning for anchors. They do not take any effect when using
- other layouts or absolute positioning.
-
- \section2 Building Transformations on Items
-
- The \gui Advanced pane allows you to configure advanced transformations,
- such as
- rotation, scale, and translation. You can assign any number of transformations
- to an item. Each transformation is applied in order, one at a time.
-
- For more information on Transform elements, see
- \l {http://doc.qt.nokia.com/4.7/qml-transform.html}{QML Transform Element}.
-
- \section1 Adding States
-
- User interfaces are designed to present different interface configurations
- in different scenarios, or to modify their appearances in response to user
- interaction. Often, there are a set of changes that are made concurrently,
- such that the interface could be seen to be internally changing from one
- \e state to another.
-
- This applies generally to interface elements regardless of their complexity.
- A photo viewer may initially present images in a grid, and when an image is
- clicked, change to a detailed state where the individual image is expanded
- and the interface is changed to present new options for image editing.
- On the other end of the scale, when a simple button is pressed, it may change
- to a \e pressed state in which its color and position is modified to give a
- pressed appearance.
-
- In QML, any object can change between different states to apply sets of changes
- that modify the properties of relevant items. Each state can present a
- different configuration that can, for example:
-
- \list
-
- \o Show some UI elements and hide others.
-
- \o Present different available actions to the user.
-
- \o Start, stop or pause animations.
-
- \o Execute some script required in the new state.
-
- \o Change a property value for a particular item.
-
- \o Show a different view or screen.
-
- \endlist
-
- The \gui State pane displays the different
- \l{http://doc.qt.nokia.com/4.7/qdeclarativestates.html}{states}
- of the component in the Qt Quick Designer.
-
- \image qmldesigner-transitions.png "State pane"
-
- To add states, click the empty slot. Then modify the new state in the editor.
- For example, to change the appearance of a button, you can hide the button
- image and show another image in its place. Or, to add movement to the screen,
- you can change the position of an object on the canvas and then add animation
- to the change between the states.
-
- You can preview the states in the \gui State pane and click them to switch
- between states on the canvas.
-
- For more information on using states, see \l{Creating Screens}.
-
- If you add animation to the states, you can run the application to test the
- animation.
-
- For more information on adding animation, see \l{Animating Screens}.
-
- \section1 Aligning and Positioning Elements
-
- The position of an element on the canvas can be either absolute or relative
- to other elements. In the element properties, you can set the x and y
- coordinates of an element, or \l{Setting Anchors and Margins}{anchor} it to its
- parent and sibling elements.
-
- \section2 Snap to Margins
-
- When you are working on a design, you can use snap and guides to align
- elements on the canvas. Click the
- \inlineimage qmldesigner-snap-to-guides-button.png
- button to have the elements snap to the guides.
-
- Choose \gui {Tools > Options... > Qt Quick} to specify settings for snap to
- margins. In the \gui {Snap margin} field, specify the position of the guides
- as pixels from the edge of the canvas. In the \gui {Item spacing} field,
- specify the space in pixels to leave between elements on the screen.
-
- The following image shows the position of the guides when \gui {Snap margin}
- is set to 5 pixels.
-
- \image qmldesigner-snap-margins.png "Snap margins on canvas"
-
- \section2 Hiding Element Boundaries
-
- Qt Quick Designer displays the boundaries of elements on the canvas. To hide
- the element boundaries, click the
- \inlineimage qmldesigner-show-bounding-rectangles-button.png
- button.
-
- \section2 Selecting Elements
-
- When you point the mouse to overlapping elements, the frontmost element is
- selected by default. However, elements that do not have any content, such as
- the mouse area, are typically located in front of elements that do have
- content, such as rectangles or border images. To select elements with content
- by default, click the
- \inlineimage qmldesigner-only-select-items-with-content.png
- button.
-
- \section2 Previewing Element Size
-
- The width and height of the root item in a QML file determine the size of
- the QML element. You can reuse elements, such as buttons, in different
- sizes in other QML files and design screens for use with different device
- profiles, screen resolution, or screen orientation. The component size
- might also be zero (0,0) if its final size is determined by property
- bindings.
-
- To experiment with different element sizes, enter values in the
- \gui Height and \gui Width fields on the canvas toolbar. The changes are
- displayed in the \gui States pane and on the canvas, but the property
- values are not changed permanently in the QML file. You can permanently
- change the property values in the \gui Properties pane.
-
- \image qmldesigner-preview-size.png "Canvas width and height"
-
- \section1 Specifying Canvas Size
-
- To change the canvas size, select \gui {Tools > Options... > Qt Quick} and
- specify the canvas width and height in the \gui Canvas group.
-
- \section1 Refreshing the Canvas
-
- When you open QML files in \QMLD, the QML elements in the file are drawn on
- the canvas. When you edit the element properties in \QMLD, the QML file and
- the image on the canvas might get out of sync. For example, when you change
- the position of an item within a column or a row, the new position might
- not be displayed correctly on the canvas.
-
- To refresh the image on the canvas, press \key R or select the \gui {Reset
- View} button on the canvas toolbar.
-
-*/
-
-
-/*!
- \contentspage index.html
- \previouspage creator-project-managing-sessions.html
- \page creator-coding.html
- \nextpage creator-editor-using.html
-
- \title Coding
-
- Writing, editing, and navigating in source code are core tasks in
- application development. Therefore, the code editor is one of the key
- components of Qt Creator. You can use the code editor in the \gui Edit
- mode.
-
- The following sections describe coding with Qt Creator:
-
- \list
-
- \o \l{Using the Editor} describes how to work in the code editor, use
- the editor toolbar, split the view, add bookmarks, and move between
- symbol definitions and declarations.
-
- \o \l{Semantic Highlighting} describes highlighting code elements and
- blocks, as well as using syntax highlighting also for other types
- of files than C++ or QML.
-
- \o \l{Checking Code Syntax} describes how errors are visualized
- while you write code.
-
- \o \l{Completing Code} describes how code and code snippets are
- completed for elements, properties, an IDs.
-
- \o \l{Indenting Code} describes how to specify indentation either
- globally for all files or separately for: text, C++, or QML files.
-
- \o \l{Finding and Replacing} describes the incremental search that
- highlights the matching strings in the window while typing and the
- advanced search that allows you to search from currently open
- projects or files on the file system. In addition, you can search
- for symbols when you want to refactor code.
-
- \o \l{Refactoring} describes the features that help you improve the
- internal quality or your application, its performance and
- extendibility, and code readability and maintainability, as well as
- to simplify code structure.
-
- \o \l{Using Qt Quick Toolbars} describes how to use the Qt Quick
- Toolbars to edit the properties of QML elements in the code editor.
-
- \o \l{Searching With the Locator} describes how to browse through
- projects, files, classes, methods, documentation and file systems.
-
- \o \l{Pasting and Fetching Code Snippets} describes how to cooperate
- with other developers by pasting and fetching snippets of code from
- a server.
-
- \o \l{Using Text Editing Macros} describes how to record and play
- text editing macros.
-
- \o \l{Configuring the Editor} describes how to change the text editor
- options to suit your specific needs.
-
- \o \l{Using FakeVim Mode} describes how to run the main editor in a
- manner similar to
- the Vim editor.
-
- \endlist
-
-*/
-
-
-/*!
- \contentspage index.html
- \previouspage creator-coding.html
- \page creator-editor-using.html
- \nextpage creator-highlighting.html
-
- \title Using the Editor
-
- Qt Creator's code editor is designed to aid you in creating, editing and
- navigating code. Qt Creator's code editor is fully equipped with syntax
- checking, code completion, context sensitive help and in-line error
- indicators while you are typing.
-
- \image qtcreator-edit-mode.png "Edit mode"
-
- \section1 Using the Editor Toolbar
-
- The editor toolbar is located at the top of the editor view. The editor
- toolbar is context sensitive and shows items relevant to the file currently
- open in the editor.
-
- \image qtcreator-editortoolbar-symbols.png
-
- Use the toolbar to navigate between open files and symbols in use.
- To browse forward or backward through your location history, click
- \inlineimage qtcreator-back.png
- and \inlineimage qtcreator-forward.png
- .
-
- To go to any open file, select it from the \gui{Open files} drop-down menu.
- Right-click the menu title and select \gui {Copy Full Path to Clipboard} to
- copy the path and name of the current file to the clipboard.
-
- To jump to any symbol used in the current file, select it from the
- \gui Symbols drop-down menu. By default, the symbols are displayed in the
- order in which they appear in the file. Right-click the menu title and select
- \gui {Sort Alphabetically} to arrange the symbols in alphabetic order.
-
- \section1 Splitting the Editor View
-
- Split the editor view when you want to work on and view multiple files on
- the same screen.
-
- \image qtcreator-spliteditorview.png
-
- You can split the editor view in the following ways:
- \list
- \o To split the editor view into a top and bottom view, select
- \gui Window > \gui Split or press \key{Ctrl+E, 2}.
-
- Split command creates views below the currently active editor view.
- \o To split the editor view into adjacent views, select
- \gui Window > \gui{Split Side by Side} or press
- \key{Ctrl+E, 3}.
-
- Side by side split command creates views to the right of the
- currently active editor view.
- \endlist
-
- To move between split views, select \gui Window >
- \gui{Go to Next Split} or press \key{Ctrl+E, O}.
-
- To remove a split view, place the cursor within the view you want to
- remove and select \gui Window > \gui{Remove Current Split} or press
- \key{Ctrl+E, 0}. To remove all but the currently selected split view,
- select \gui Window > \gui{Remove All Splits} or press \key{Ctrl+E, 1}.
-
- \section1 Using Bookmarks
-
- To insert or delete a bookmark right-click the line number and select
- \gui{Toggle Bookmark} or press \key{Ctrl+M}.
-
- \image qtcreator-togglebookmark.png
-
- To go to previous bookmark in the current session, press \key{Ctrl+,}.
-
- To go to next bookmark in the current session, press \key{Ctrl+.}.
-
- \section1 Moving to Symbol Definition or Declaration
-
- You can move directly to the definition or the declaration of a symbol by
- holding the \key Ctrl and clicking the symbol.
-
- To enable this moving function, in \gui Tools > \gui{Options...} >
- \gui{Text Editor} > \gui Behavior, select \gui{Enable mouse navigation}.
-
- You can also select the symbol and press \key F2, or right-click the symbol
- and select \gui {Follow Symbol Under Cursor} to move to its definition or
- declaration. This feature is supported for namespaces, classes, methods,
- variables, include statements, and macros.
-
- To switch between the definition and declaration of a symbol, press
- \key {Shift+F2} or right-click the symbol and select \gui {Switch Between
- Method Declaration/Definition}.
-
- \section1 Using Update Code Model
-
- To refresh the internal information in Qt Creator pertaining to your code,
- select \gui{Tools} > \gui{C++} > \gui{Update Code Model}.
-
- \note In Qt Creator indexing updates the code automatically. Use
- \gui{Update Code Model} only as an emergency command.
-*/
-
-
-/*!
- \contentspage index.html
- \previouspage creator-editor-using.html
- \page creator-highlighting.html
- \nextpage creator-checking-code-syntax.html
-
- \title Semantic Highlighting
-
- Qt Creator understands the C++ and QML languages as code, not as plain text.
- It reads the source code, analyzes it, and highlights it based on the
- semantic checks that it does for the following code elements:
-
- \list
-
- \o Types (such as classes, structs, and type definitions)
-
- \o Local variables
-
- \o Class fields
-
- \o Virtual methods
-
- \endlist
-
- To specify the color scheme to use for semantic highlighting, select
- \gui {Tools > Options... > Text Editor > Fonts & Color}.
-
- Qt Creator supports syntax highlighting also for other types of files than
- C++ or QML.
-
- \section1 Generic Highlighting
-
- Generic highlighting is based on highlight definition files that are
- provided by the
- \l{http://kate-editor.org/2005/03/24/writing-a-syntax-highlighting-file/}{Kate Editor}.
- You can download highlight definition files for use with Qt Creator.
-
- If you have a Unix installation that comes with the Kate Editor, you might
- already have the definition files installed. Typically, the files are
- located in a read-only directory, and therefore, you cannot manage them. Qt
- Creator can try to locate them and use them as fallback files, when the
- primary location does not contain the definition for the current file type.
- You can also specify the directory that contains preinstalled highlight
- definition files as the primary location.
-
- When you open a file for editing and the editor cannot find the highlight
- definition for it, an alert appears. You can turn off the alerts. You can
- also specify patterns for ignoring files. The editor will not alert you if
- highlight definitions for the ignored files are not found.
-
- To download highlight definition files:
-
- \list 1
-
- \o Select \gui {Tools > Options... > Text Editor > Generic
- Highlighter}.
-
- \image qtcreator-generic-highlighter.png "Generic Highlighter options"
-
- \o In the \gui Location field, specify the path to the primary
- location for highlight definition files.
-
- \o Click \gui {Download Definitions} to open a list of highlight
- definition files available for download.
-
- \image qtcreator-manage-definitions.png "Download Definitions dialog"
-
- \o Select highlight definition files in the list and click
- \gui {Download Selected Definitions}.
-
- \o Select the \gui {Use fallback location} check box to specify the
- secondary location where the editor will look for highlight
- definition files.
-
- \o Click \gui Autodetect to allow Qt Creator to look for highlight
- definition files on your system, or click \gui Browse to locate
- them in the file system yourself.
-
- \o In the \gui {Ignored file patterns} field, specify file patterns.
- You will not receive alerts if the highlight definitions for the
- specified files are not found.
-
- \o Click \gui OK to save your changes.
-
- \endlist
-
- \section1 Highlighting and Folding Blocks
-
- Use block highlighting to visually separate parts of the code that belong
- together. For example, when you place the cursor within the braces,
- the code enclosed in braces is highlighted.
-
- \image qtcreator-blockhighlighting.png
-
- To enable block highlighting, select \gui Tools > \gui{Options...} >
- \gui{Text Editor} > \gui Display > \gui{Highlight blocks}.
-
- Use the folding markers to collapse and expand blocks of code within
- braces. Click the folding marker to collapse or expand a block. In the
- figure above, the folding markers are located between the line number and
- the text pane.
-
- To show the folding markers, select \gui Tools > \gui{Options...} >
- \gui{Text Editor} > \gui Display > \gui{Display folding markers}. This
- option is enabled by default.
-
- When the cursor is on a brace, the matching brace is animated
- by default. To turn off the animation and just highlight the block and
- the braces, select \gui {Tools > Options... > Text Editor > Display} and
- deselect \gui {Animate matching parentheses}.
-
-*/
-
-
-/*!
- \contentspage index.html
- \previouspage creator-highlighting.html
- \page creator-checking-code-syntax.html
- \nextpage creator-completing-code.html
-
- \title Checking Code Syntax
-
- As you write code Qt Creator checks code syntax. When Qt Creator spots a
- syntax error in your code it underlines it and shows error details when you
- move the mouse pointer over the error.
- \list
- \o Syntax errors are underlined in red.
-
- In the following figure, a semicolon is missing at the end of the
- line.
-
- \image qtcreator-syntaxerror.png
- \o Semantic errors and warnings are underlined in olive.
-
- In the following figure, the type is unknown.
-
- \image qtcreator-semanticerror.png
- \endlist
-
-*/
-
-
-/*!
- \contentspage index.html
- \previouspage creator-checking-code-syntax.html
- \page creator-completing-code.html
- \nextpage creator-indenting-code.html
-
- \title Completing Code
-
- As you write code, Qt Creator suggests properties, IDs, and code
- snippets to complete the code. It provides a list of context-sensitive
- suggestions to the statement currently under your cursor. Press \key Tab
- or \key Enter to accept the selected suggestion and complete the code.
-
- \image qtcreator-codecompletion.png
-
- To open the list of suggestions at any time, press \key{Ctrl+Space}.
- If only one option is available, Qt Creator inserts it automatically.
-
- When completion is invoked manually, Qt Creator completes the common prefix
- of the list of suggestions. This is especially useful for classes with
- several similarly named members. To disable this functionality, uncheck
- \gui{Autocomplete common prefix} in the code completion preferences.
- Select \gui Tools > \gui{Options...} > \gui{Text Editor} > \gui Completion.
-
- By default, code completion considers only the first letter case-sensitive.
- To apply full or no case-sensitivity, select the option in the
- \gui {Case-sensitivity} field.
-
- \section2 Summary of Available Types
-
- The following table lists available types for code completion and icon
- used for each.
-
- \table
- \header
- \o Icon
- \o Description
- \row
- \i \inlineimage completion/class.png
- \i A class
- \row
- \i \inlineimage completion/enum.png
- \i An enum
- \row
- \i \inlineimage completion/enumerator.png
- \i An enumerator (value of an enum)
- \row
- \i \inlineimage completion/func.png
- \i A function
- \row
- \i \inlineimage completion/func_priv.png
- \i A private function
- \row
- \i \inlineimage completion/func_prot.png
- \i A protected function
- \row
- \i \inlineimage completion/var.png
- \i A variable
- \row
- \i \inlineimage completion/var_priv.png
- \i A private variable
- \row
- \i \inlineimage completion/var_prot.png
- \i A protected variable
- \row
- \i \inlineimage completion/signal.png
- \i A signal
- \row
- \i \inlineimage completion/slot.png
- \i A slot
- \row
- \i \inlineimage completion/slot_priv.png
- \i A private slot
- \row
- \i \inlineimage completion/slot_prot.png
- \i A protected slot
- \row
- \i \inlineimage completion/keyword.png
- \i A C++ keyword
- \row
- \i \inlineimage completion/snippet.png
- \i A C++ code snippet
- \row
- \i \inlineimage completion/element.png
- \i A QML element
- \row
- \i \inlineimage completion/qmlsnippet.png
- \i A QML code snippet
- \row
- \i \inlineimage completion/macro.png
- \i A macro
- \row
- \i \inlineimage completion/namespace.png
- \i A namespace
- \endtable
-
- \section2 Completing Code Snippets
-
- Code snippets can consist of multiple
- variables that you specify values for. Select an item in the list and press
- \key Tab or \key Enter to complete the code. Press \key Tab to
- move between the variables and specify values for them. When you specify a
- value for a variable, all instances of the variable within the snippet
- are renamed.
-
- \image qmldesigner-code-completion.png "Completing QML code"
-
- \section2 Editing Code Snippets
-
- Code snippets specify C++ or QML code constructs. You can add, modify,
- and remove snippets in the snippet editor. To open the editor, select
- \gui {Tools > Options... > Text Editor > Snippets}.
-
- \image qtcreator-edit-code-snippets.png "Snippet options"
-
- Qt Creator provides you with built-in snippets in the following categories:
-
- \list
-
- \o Text snippets, which can contain any text string. For example, code
- comments
-
- \o C++ code snippets, which specify C++ code constructs
-
- \o QML code snippets, which specify QML code constructs
-
- \endlist
-
- \section3 Adding and Editing Snippets
-
- Select a snippet in the list to edit it in the snippet editor. To add a new
- snippet, select \gui Add. Specify a trigger and, if the trigger is already
- in use, an optional variant, which appear in the list of suggestions when
- you write code. Also specify a text string or C++ or QML code construct in
- the snippet editor, depending on the snippet category.
-
- The snippet editor provides you with:
-
- \list
-
- \o Highlighting
-
- \o Indentation
-
- \o Parentheses matching
-
- \o Basic code completion
-
- \endlist
-
- Specify the variables for the snippets in the following format:
-
- \c $variable$
-
- Use unique variable names within a snippet, because all instances of a
- variable are renamed when you specify a value for it.
-
- The snippet editor does not check the syntax of the snippets that you edit
- or add. However, when you use the snippets, the code editor marks any
- errors by underlining them in red.
-
- To discard the changes you made to a built-in snippet, select \gui {Revert
- Built-in}.
-
- \section3 Removing Snippets
-
- Several similar built-in snippets might be provided for different use
- cases. To make the list of suggestions shorter when you write code, remove
- the built-in snippets that you do not need. If you need them later, you
- can restore them.
-
- To remove snippets, select a snippet in the list, and then select
- \gui Remove. To restore the removed snippets, select \gui {Restore Removed
- Built-ins}.
-
- \section3 Resetting Snippets
-
- To remove all added snippets and to restore all removed snippets, select
- \gui {Reset All}.
-
- \note If you now select \gui OK or \gui Apply, you permanently lose all
- your own snippets.
-
-*/
-
-
-/*!
- \contentspage index.html
- \previouspage creator-editor-locator.html
- \page creator-editor-codepasting.html
- \nextpage creator-macros.html
-
- \title Pasting and Fetching Code Snippets
-
- In Qt Creator, you can paste snippets of code to a server or fetch
- snippets of code from the server. To paste and fetch snippets of code,
- Qt Creator uses the following:
- \list
- \o \gui{CodePaster}
- \o \gui{Pastebin.Com}
- \o \gui{Pastebin.Ca}
- \endlist
-
- To configure the server, select \gui{Tools} > \gui{Options...} >
- \gui{Code Pasting}.
-
- To paste a snippet of code onto the server, select \gui{Tools} >
- \gui{Code Pasting} > \gui{Paste Snippet...} or press \key{Alt+C,Alt+P}.
-
-
-
- To fetch a snippet of code from the server, select \gui{Tools} >
- \gui{Code Pasting} > \gui{Fetch Snippet...} or press \key{Alt+C,Alt+F}.
-
- \note To use \gui{Pastebin.Com}, configure the domain
- prefix in \gui{Tools} > \gui{Options...} > \gui{Code Pasting} >
- \gui{Pastebin.com}.
-
- For example, you might ask colleagues to review a change that you plan to
- submit to a version control system. If you use the Git version control system,
- you can create a \e{diff} view by selecting \gui{Tools} > \gui{Git} >
- \gui{Diff Repository}. You can then upload its contents to the server by choosing
- \gui{Tools} > \gui{Code Pasting} > \gui{Paste Snippet...}. The reviewers can retrieve
- the code snippet by selecting \gui{Tools} > \gui{Code Pasting} > \gui{Fetch Snippet...}.
- If they have the project currently opened in Qt Creator, they can apply and test
- the change by choosing \gui{Tools} > \gui{Git} > \gui{Apply Patch}.
-
-*/
-
-/*!
- \contentspage index.html
- \previouspage creator-editor-codepasting.html
- \page creator-macros.html
- \nextpage creator-editor-options.html
-
- \title Using Text Editing Macros
-
- When you have a file open in the code editor, you can record a keyboard
- sequence as a macro. You can then play the macro to repeat the sequence.
- You can save the latest macro and assign a keyboard shortcut for running
- it or run it from the locator.
-
- To record a text editing macro, select \gui {Tools > Macros > Record Macro}
- or press \key {Alt+(}. To stop recording, select \gui {Tools > Macros >
- Stop Recording Macro} or press \key {Alt+)}.
-
- To play the last macro, select \gui {Tools > Macros > Play Last Macro} or
- press \key {Alt+R}.
-
- To save the last macro, select \gui {Tools > Macros > Save Last Macro}.
-
- To assign a keyboard shortcut to a text editing macro, select \gui {Tools >
- Options... > Environment > Keyboard}. For more information, see
- \l{Configuring Keyboard Shortcuts}.
-
- You can also use the \c rm locator filter to run a macro. For more
- information, see \l{Searching With the Locator}.
-
- To view and remove saved macros, select \gui {Tools > Options... > Text
- Editor > Macros}.
-
-*/
-
-/*!
- \contentspage index.html
- \previouspage creator-editor-options.html
- \page creator-editor-fakevim.html
- \nextpage creator-design-mode.html
-
- \title Using FakeVim Mode
-
- In the \gui{FakeVim} mode, you can run the main editor in a manner similar
- to the Vim editor. To run the editor in the \gui{FakeVim} mode, select
- \gui{Edit} > \gui{Advanced} > \gui{Use Vim-style Editing} or press
- \key{Alt+V,Alt+V}.
-
- In the \gui{FakeVim} mode, most keystrokes in the main editor will be
- intercepted and interpreted in a way that resembles Vim. Documentation for
- Vim is not included in Qt Creator. For more information on using Vim,
- see \l{http://www.vim.org/docs.php}{Documentation} on the Vim web site.
-
- To map commands entered on the \gui{FakeVim} command line to actions of the
- Qt Creator core, select \gui{Tools} > \gui{Options...} > \gui{FakeVim} >
- \gui{Ex Command Mapping}.
-
- To make changes to the Vim-style settings, select \gui{Tools} >
- \gui{Options...} > \gui FakeVim > \gui{General}.
-
- To use a Vim-style color scheme, select \gui {Tools > Options... >
- Text Editor > Fonts & Color}. In the \gui {Color Scheme} list, select
- \gui {Vim (dark)}.
-
- To quit the FakeVim mode, unselect \gui{Tools} > \gui(Options...} >
- \gui{FakeVim} > \gui {Use FakeVim} or press \key{Alt+V,Alt+V}.
-
- You can temporarily escape FakeVim mode to access the normal Qt Creator
- keyboard shortcuts like \key{Ctrl-R} for \gui{Run} by pressing
- \key{,} first.
-
- */
-
-
-/*!
- \contentspage index.html
- \previouspage adding-plugins.html
- \page creator-editor-external.html
- \nextpage creator-maemo-emulator.html
-
- \title Using External Tools
-
- You can use external tools directly from Qt Creator. Qt Linguist,
- QML Viewer, the
- default text editor for your system, and the \c sort tool are preconfigured
- for use. You can change their default configurations and configure new
- tools.
-
- \section1 Using Qt Linguist
-
- You can use the Qt Linguist release manager tools, lupdate and lrelease,
- directly from Qt Creator. The lupdate tool is used to synchronize source
- code and translations. The lrelease tool is used to create run-time
- translation files for use by the released application.
-
- To synchronize ts files from a translator with the application code,
- select \gui {Tools > External > Text > Linguist > Update Translations
- (lupdate)}.
-
- To generate from the ts files qm translation files that can be used by an
- application, select \gui {Tools > External > Text > Linguist > Release
- Translations (lrelease)}.
-
- By default, the project .pro file is passed to the tools as an argument. To
- specify other command line arguments for the tools, select \gui {Tools >
- External > Configure}.
-
- For more information about Qt Linguist, see
- \l{http://doc.qt.nokia.com/4.7/linguist-manual.html}{Qt Linguist Manual}.
-
- \section1 Using QML Viewer
-
- You can preview the current QML document in the QML Viewer. The QML Viewer
- invokes the QML runtime to load QML documents and also includes additional
- features useful for the development of QML-based applications.
-
- To preview the currently active QML file, select \gui {Tools > External >
- Qt Quick > Preview (qmlviewer)}.
-
- \section1 Using External Text Editors
-
- You can open files for editing in the default text editor for your system:
- Notepad on Windows and vi on Linux and Mac OS.
- To open the file you are currently viewing in an external editor, select
- \gui {Tools > External > Text > Notepad} or \gui vi, depending on your
- system.
-
- Qt Creator looks for the editor path in the PATH environment variable
- of your operating system.
-
- \section1 Sorting Text Alphabetically
-
- To sort selected text alphabetically, select \gui {Tools > External > Text
- > Sort Selection}. The \c sort tool takes the selected text as input and
- returns it in alphabetic order. By default, the output replaces the
- original selection in the code editor.
-
- To change the default configuration, select \gui {Tools > External >
- Configure}.
-
- \section1 Configuring External Tools
-
- You can change the configuration of preconfigured tools and configure
- additional tools in Qt Creator \gui Options.
-
- You can use Qt Creator variables in the fields that you can select from
- lists of available Qt Creator variables.
-
- \image qtcreator-external-tools.png "External Tools options"
-
- To configure external tools:
-
- \list 1
-
- \o Select \gui {Tools > External > Configure}.
-
- \o Select \gui {Add > Add Tool}
- to add a new tool. You can also select \gui {Add Category} to add a
- new category.
-
- \o In the \gui Executable field, specify the executable to run. If the
- executable is found in your system PATH variable, do not specify
- the path to it.
-
- \o In the \gui Arguments field, specify optional arguments for running
- the executable.
-
- \o In the \gui {Working directory} field, specify the path to the
- working directory.
-
- \o In the \gui {Output pane}, select how to handle output from the
- tool. You can ignore the output, view it in the \gui {General
- Messages} output pane, or replace the selected text with the
- output in the code editor.
-
- \o In the \gui {Error output pane}, select how to handle error messages
- from the tool.
-
- \o In the \gui Input field, specify text that is passed as standard
- input to the tool.
-
- \endlist
-
- The category and tool are added to the \gui {Tools > External} menu.
-
- If you change the configuration of preconfigured tools, you can later
- revert the changes by selecting the \gui Revert button.
-
- The tool configurations that you add and modify are stored in XML format in
- the user configuration folder. For example,
- \c {~/config/Nokia/qtcreator/externaltools}
- on Linux and Mac OS and
- \c {C:\Users\username\AppData\Roaming\Nokia\qtcreator\externaltools}
- in Windows. To share a configuration with other users, copy an XML
- configuration file to the folder.
-
-*/
-
-
-/*!
- \contentspage index.html
- \previouspage creator-macros.html
- \page creator-editor-options.html
- \nextpage creator-editor-fakevim.html
-
- \title Configuring the Editor
-
- Qt Creator allows you to configure the text editor to suit your specific
- needs. To configure the editor, select \gui Tools > \gui{Options...} >
- \gui{Text Editor}.
-
- These settings apply to all projects. To specify editor behavior for an
- open project, select \gui {Projects > Editor Settings}. For more
- information, see \l{Specifying Editor Settings}.
-
- You can also specify indentation settings separately for C++ and QML files
- either globally or for the open project. For more information, see
- \l{Indenting Code}.
-
- \image qtcreator-font-colors.png "Text editor options"
-
- You can perform the following configuration actions:
- \list
- \o Set the font preferences and apply color schemes for syntax highlighting in
- \gui{Font & Colors}.
- \o Specify
- \l{Generic Highlighting}{definition files for syntax highlighting}
- for other types of files than
- C++ or QML in \gui{Generic Highlighter}.
- \o Set tabs, indentation, the handling of whitespace, and mouse operations in
- \gui Behavior. For more information, see \l{Indenting Code}.
- \o Set various display properties, for example,
- \l{Highlighting and folding blocks}{highlighting and folding blocks},
- text wrapping or \l{Moving to symbol definition or declaration}
- {moving to symbol definition or declaration}
- in \gui Display.
- \o Add, modify, and remove \l{Editing Code Snippets}{code snippets} in
- \gui Snippets.
- \o View and remove \l{Using Text Editing Macros}{text editing macros}
- in \gui Macros.
- \o Configure \l{Completing Code}{code completion} in \gui Completion.
- \endlist
-
- \section2 Configuring Fonts
-
- You can select the font family and size. You can specify a zoom setting in
- percentage for viewing the text. You can also zoom in or out by pressing
- \key {Ctrl++} or \key {Ctrl +-}, or by pressing \key Ctrl and rolling
- the mouse button up or down. To disable the mouse wheel function, select
- \gui {Tools > Options... > Text Editor > Behavior} and deselect the
- \gui {Enable scroll wheel zooming} check box.
-
- Antialiasing is used by default to make text look smoother and more
- readable on the screen. Deselect the \gui Antialias check box to
- turn off antialiasing.
-
- \section2 Defining Color Schemes
-
- You can select one of the predefined color schemes for syntax highlighting
- or create customized color schemes. The color schemes apply to highlighting
- both C++ and QML files and generic files.
-
- To create a color scheme:
-
- \list 1
-
- \o Select \gui {Tools > Options... > Text Editor > Fonts & Color > Copy}.
-
- \o Enter a name for the color scheme and click \gui OK.
-
- \o In the \gui Foreground field, specify the color of the selected
- code element.
-
- \o In the \gui Background field, select the background
- color for the code element.
-
- The backgound of the \gui Text element determines the background of the
- code editor.
-
- \endlist
-
- When you copy code from Qt Creator, it is copied in both plain text and HTML
- format. The latter makes sure that syntax highlighting is preserved when
- pasting to a rich-text editor.
-
- \section2 File Encoding
-
- To define the default file encoding, select the desired encoding in
- \gui {Default encoding}. By default, Qt Creator uses the file encoding
- used by your system.
-
-*/
-
-
-/*!
- \contentspage index.html
- \previouspage creator-completing-code.html
- \page creator-indenting-code.html
- \nextpage creator-editor-finding.html
-
- \title Indenting Code
-
- When you type code, it is indented automatically according to the selected
- text editor and code style options. Select a block to indent it when you
- press \key Tab. Press \key {Shift+Tab} to decrease the indentation. You
- can disable automatic indentation.
-
- When you press \gui Backspace, the indentation is decreased by one level
- in leading white space, by default. You can disable this setting.
-
- Continuation lines are aligned with the previous line by using spaces. You
- can disable automatic alignment to have them indented to the logical depth.
- You can always use spaces for alignment or use spaces or tabs depending on
- the other options you selected.
-
- You can specify indentation either globally for all files or separately
- for:
-
- \list
-
- \o Text files
-
- \o C++ files
-
- \o QML files
-
- \endlist
-
- You can specify indentation either globally for all files of a particular
- type or separately for each project.
-
- \section1 Indenting Text Files
-
- To specify global indentation settings for the text editor, select
- \gui {Tools > Options... > Text Editor > Behavior}. You can also use these
- settings globally for all editors and files.
-
- \image qtcreator-indentation.png "Text Editor Behavior options"
-
- To specify settings for a particular project, select \gui {Projects >
- Editor Settings}.
-
- \section1 Indenting C++ Files
-
- To specify global indentation settings for the C++ editor, select
- \gui {Tools > Options... > C++}.
-
- \image qtcreator-options-code-style-cpp.png "C++ Code Style options"
-
- To specify the settings for a particular project, select \gui {Projects >
- Code Style Settings}.
-
- You can specify how to:
-
- \list
-
- \o Interpret the \key Tab and \key Backspace key presses.
-
- \o Indent the contents of classes, methods, blocks, and namespaces.
-
- \o Indent braces in classes, namespaces, enums, methods, and blocks.
-
- \o Control switch statements and their contents.
-
- \o Align continuation lines.
-
- \endlist
-
- You can use the live preview to see how the options change the indentation.
-
- \section1 Indenting QML Files
-
- To specify global settings for the Qt Quick editor, select \gui {Tools >
- Options... > Qt Quick}.
-
- \image qtcreator-options-code-style-qml.png "QML Code Style options"
-
- To specify the settings for a particular project, select \gui {Projects >
- Code Style Settings}.
-
- You can specify how to interpret the \key Tab and \key Backspace key
- presses.
-
- \section1 Specifying Tab Settings
-
- You can specify tab settings at the following levels:
-
- \list
-
- \o Global settings for all files
-
- \o Global C++ settings for C++ files
-
- \o Global Qt Quick settings for QML files
-
- \o Project specific settings for all editors of files in the project
-
- \o Project specific settings for C++ files in the project
-
- \o Project specific settings for QML files in the project
-
- \endlist
-
- By default, the tab-length in code editor is 8 spaces. You can specify the
- tab length separately for each project and for
- different types of files.
-
- The code editor can also determine whether tabs or spaces are used
- on the previous or next line and copy the style.
-
- The \key Tab key can automatically indent text when you press it, or only
- when the cursor is located within leading white space.
-
- \section1 Specifying Settings for Content
-
- You can indent public, protected, and private statements and declarations
- related to them within classes.
-
- You can also indent statements within methods and blocks and declarations
- within namespaces.
-
- \image qtcreator-code-style-content.png "Content options"
-
- \section1 Specifying Settings for Braces
-
- You can indent class, namespace, enum and method declarations and code
- blocks.
-
- \image qtcreator-code-style-braces.png "Braces options"
-
- \section1 Specifying Settings for Switch Statements
-
- You can indent case or default statements, or statements or blocks related
- to them within switch statements.
-
- \image qtcreator-code-style-switch.png "Switch options"
-
- \section1 Specifying Alignment
-
- To align continuation lines to tokens after assignments, such as = or
- +=, select the \gui {Align after assignments} check box. You can specify
- additional settings for aligning continuation lines in the \gui General
- tab.
-
- You can also add spaces to conditional statements, so that they are not
- aligned with the following line. Usually, this only affects \c if
- statements.
-
- \image qtcreator-code-style-alignment.png "Alignment options"
-
-*/
-
-
-/*!
- \contentspage index.html
- \previouspage creator-indenting-code.html
- \page creator-editor-finding.html
- \nextpage creator-editor-refactoring.html
-
- \title Finding and Replacing
-
- To search through the currently open file:
- \list 1
- \o Press \key Ctrl+F or select \gui Edit > \gui Find/Replace >
- \gui{Find/Replace}.
- \o Enter the text you are looking for.
-
- If the text is found, all occurrences are highlighted as you type.
- \o To go to the next occurrence, click \inlineimage qtcreator-next.png
- , or press \key F3. To go to the previous occurrence click
- \inlineimage qtcreator-previous.png
- , or press \key Shift+F3.
- \endlist
-
- You can restrict the search in the \gui Find field by selecting one
- or several search criteria:
- \list
- \o To make your search case sensitive, select
- \inlineimage qtcreator-editor-casesensitive.png
- .
- \o To search only whole words, select
- \inlineimage qtcreator-editor-wholewords.png
- .
- \o To search using regular expressions, select
- \inlineimage qtcreator-editor-regularexpressions.png
- .
- Regular expressions used in Qt Creator are modeled on Perl regular
- expressions. For more information on using regular expressions, see
- \l {http://doc.qt.nokia.com/4.7/qregexp.html#details}
- {Detailed Description} in the QRegExp Class Reference.
- \endlist
-
- \note If you have selected text before selecting \gui Find/Replace, the
- search is conducted within the selection.
-
- To replace occurrences of the existing text, enter the new text in the
- \gui{Replace with} field.
- \list
- \o To replace the selected occurrence and move to the next one,
- click \inlineimage qtcreator-next.png
- or press \key Ctrl+=.
- \o To replace the selected occurrence and move to the previous one,
- click \inlineimage qtcreator-previous.png
- .
- \o To replace all occurrences in the file, click \gui{Replace All}.
- \endlist
-
- \section1 Advanced Search
-
- To search through projects, files on a file system or the currently open
- file:
- \list 1
- \o Press \key Ctrl+Shift+F or select \gui Edit >
- \gui Find/Replace > \gui{Advanced Find} >
- \gui{Open Advanced Find...}.
- \o Select the scope of your search:
- \list
- \o \gui{All Projects} searches files matching the defined file
- pattern in all currently open projects.
-
- For example, to search for \tt previewer only in \tt .cpp
- and \tt .h files, enter in \gui{File pattern}
- \tt *.cpp,*.h.
-
- \image qtcreator-search-allprojects.png
-
- \o \gui{Current Project} searches files matching the defined file
- pattern only in the project you are currently editing.
- \o \gui{Files on File System} recursively searches files matching
- the defined file pattern in the selected directory.
- \o \gui{Current File} searches only the current file.
- \endlist
- \o Enter the text you are looking for and click \gui Search.
-
- \image qtcreator-searchresults.png
-
- A list of files containing the searched text is displayed in the
- \gui{Search Results} pane.
- \list
- \o To see all occurrences in a file, double-click the file name in
- the list.
- \o To go to an occurrence, double-click it.
- \endlist
- \endlist
-
- \note You can use \gui{Advanced Find} also to search for symbols. For more
- information, see \l{Finding Symbols}.
-
-*/
-
-
-/*!
- \contentspage index.html
- \previouspage creator-editor-finding.html
- \page creator-editor-refactoring.html
- \nextpage qt-quick-toolbars.html
-
- \title Refactoring
-
- Code refactoring is the process of changing the code without modifying the
- existing functionality of your application. By refactoring your code you
- can:
- \list
- \o Improve internal quality of your application
- \o Improve performance and extensibility
- \o Improve code readability and maintainability
- \o Simplify code structure
- \endlist
-
- \section1 Finding Symbols
-
- To find the use of a specific symbol in your Qt C++ or Qt Quick project:
- \list 1
- \o In the editor, place the cursor on the symbol, and select:
- \list
- \o \gui {Tools > C++ > Find Usages}
- \o \gui {Tools > QML > Find Usages}
- \o \key Ctrl+Shift+U
- \endlist
-
- Qt Creator looks for the symbol in the following locations:
- \list
- \o Files listed as a part of the project
- \o Files directly used by the project files (for example, generated
- files)
- \o Header files of used frameworks and libraries
- \endlist
-
- \note You can also select \gui{Edit > Find/Replace > Advanced Find >
- C++ Symbols} to search for classes, methods, enums, and declarations
- either from files listed as part of the project or from all files that
- are used by the code, such as include files.
-
- \image qtcreator-search-cpp-symbols.png
-
- \o The \gui{Search Results} pane opens and shows the location and
- number of instances of the symbol in the current project.
-
- \image qtcreator-refactoring-find.png
- \endlist
-
- You can browse the search results in the following ways:
- \list
- \o To go directly to an instance, double-click the instance in the
- \gui{Search Results} pane.
- \o To move between instances, click
- \inlineimage qtcreator-forward.png
- and
- \inlineimage qtcreator-back.png
- in the \gui{Search Results} pane.
- \o To expand and collapse the list of all instances, click
- \inlineimage qtcreator-expand.png
- .
- \o To clear the search results, click \inlineimage qtcreator-clear.png
- .
- \endlist
-
- \section1 Renaming Symbols
-
- 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 \gui Tools > \gui QML/JS >
- \gui{Rename Symbol Under Cursor}. Alternatively 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.
-
- \section1 Applying Refactoring Actions
-
- Qt Creator allows you to quickly and conveniently apply actions to refactor
- your code by selecting them in a context menu. The actions available depend on
- the position of the cursor in the code editor and on whether you are writing
- C++ or QML code.
-
- To apply refactoring actions to C++ code, right-click an operand, conditional
- statement, string, or name to open a context menu. In QML code, click an element
- ID or name.
-
- In the context menu, select \gui {Refactoring} and then select a refactoring action.
-
- You can also press \gui {Alt+Enter} to open a context menu that contains refactoring
- actions available in the current cursor position.
-
- \section2 Refactoring C++ Code
-
- You can apply the following types of refactoring actions to C++ code:
-
- \list
-
- \o Change binary operands
-
- \o Simplify if and while conditions (for example, move declarations out of
- if conditions)
-
- \o Modify strings (for example, set the encoding for a string to Latin-1, mark
- strings translatable, and convert symbol names to camel case)
-
- \o Create variable declarations
-
- \o Create method declarations and definitions
-
- \endlist
-
- The following table summarizes the refactoring actions for C++ code. The
- action is available when the cursor is in the position described in the
- Activation column.
-
- \table
- \header
- \i Refactoring Action
- \i Description
- \i Activation
- \row
- \i Add Curly Braces
- \i Adds curly braces to an if statement that does not contain a
- compound statement. For example, rewrites
-
- \code
- if (a)
- b;
- \endcode
-
- as
-
- \code
- if (a) {
- b;
- }
- \endcode
- \i if
- \row
- \i Move Declaration out of Condition
- \i Moves a declaration out of an if or while condition to simplify the
- condition. For example, rewrites
-
- \code
- if (Type name = foo()) {...}
- \endcode
-
- as
-
- \code
- Type name = foo;
- if (name) {...}
- \endcode
- \i Name of the introduced variable
- \row
- \i Rewrite Condition Using ||
- \i Rewrites the expression according to De Morgan's laws. For example,
- rewrites:
- \code
- !a && !b
- \endcode
-
- as
-
- \code
- !(a || b)
- \endcode
- \i &&
- \row
- \i Rewrite Using \e operator
- \i Rewrites an expression negating it and using the inverse operator. For
- example, rewrites:
-
- \list
-
- \o \code
- a op b
- \endcode
-
- as
-
- \code
- !(a invop b)
- \endcode
-
- \o \code
- (a op b)
- \endcode
-
- as
-
- \code
- !(a invop b)
- \endcode
-
- \o \code
- !(a op b)
- \endcode
-
- as
-
- \code
- (a invob b)
- \endcode
-
- \endlist
-
- \i <= < > >= == !=
- \row
- \i Split Declaration
- \i Splits a simple declaration into several declarations. For example,
- rewrites:
- \code
- int *a, b;
- \endcode
-
- as
-
- \code
- int *a;
- int b;
- \endcode
- \i Type name or variable name
- \row
- \i Split if Statement
- \i Splits an if statement into several statements. For example, rewrites:
- \code
- if (something && something_else) {
- }
- \endcode
-
- as
-
- \code
- if (something) {
- if (something_else) {
- }
- }
- \endcode
-
- and
-
- \code
- if (something || something_else)
- x;
- \endcode
-
- with
-
- \code
- if (something)
- x;
- else if (something_else)
- x;
- \endcode
-
- \i && ||
- \row
- \i Swap Operands
- \i Rewrites an expression in the inverse order using the inverse operator.
- For example, rewrites:
- \code
- a op b
- \endcode
-
- as
- \code
- b flipop a
- \endcode
- \i <= < > >= == != && ||
- \row
- \i Convert to Decimal
- \i Converts an integer literal to decimal representation
- \i Numeric literal
- \row
- \i Convert to Hexadecimal
- \i Converts an integer literal to hexadecimal representation
- \i Numeric literal
- \row
- \i Convert to Octal
- \i Converts an integer literal to octal representation
- \i Numeric literal
- \row
- \i Convert to Objective-C String Literal
- \i Converts a string literal to an Objective-C string literal
- if the file type is Objective-C(++). For example, rewrites the following strings
-
- \code
- "abcd"
- QLatin1String("abcd")
- QLatin1Literal("abcd")
- \endcode
-
- as
-
- \code
- @"abcd"
- \endcode
- \i String literal
- \row
- \i Enclose in QLatin1Char(...)
- \i Sets the encoding for a character to Latin-1, unless the character is
- already enclosed in QLatin1Char, QT_TRANSLATE_NOOP, tr, trUtf8,
- QLatin1Literal, or QLatin1String. For example, rewrites
-
- \code
- 'a'
- \endcode
-
- as
-
- \code
- QLatin1Char('a')
- \endcode
- \i String literal
- \row
- \i Enclose in QLatin1String(...)
- \i Sets the encoding for a string to Latin-1, unless the string is
- already enclosed in QLatin1Char, QT_TRANSLATE_NOOP, tr, trUtf8,
- QLatin1Literal, or QLatin1String. For example, rewrites
- \code
- "abcd"
- \endcode
-
- as
-
- \code
- QLatin1String("abcd")
- \endcode
-
- \i String literal
-
- \row
- \i Mark as Translatable
- \i Marks a string translatable. For example, rewrites \c "abcd" with
- one of the following options, depending on which of them is available:
-
- \code
- tr("abcd")
- QCoreApplication::translate("CONTEXT", "abcd")
- QT_TRANSLATE_NOOP("GLOBAL", "abcd")
- \endcode
-
- \i String literal
-
- \row
- \i #include Header File
- \i Adds the matching #include statement for a forward-declared class or struct
- \i Forward-declared class or struct
- \row
- \i Add Definition in 'filename'
- \i Inserts a definition stub for a member function declaration in the
- implementation file
- \i Method name
- \row
- \i Add 'Function' Declaration
- \i Inserts the member function declaration that matches the member function
- definition into the class declaration. The function can be public,
- protected, private, public slot, protected slot, or private slot.
- \i Method name
- \row
- \i Add Local Declaration
- \i
- Adds the type of an assignee, if the type of the right-hand side of the assignment
- is known. For example, rewrites
-
- \code
- a = foo();
- \endcode
-
- as
-
- \code
- Type a = foo();
- \endcode
-
- where Type is the return type of \c {foo()}
-
- \i Assignee
-
- \row
- \i Convert to Camel Case...
- \i Converts a symbol name to camel case, where elements of the name are joined
- without delimiter characters and the initial character of each element is
- capitalized. For example, rewrites \c an_example_symbol
- as \c anExampleSymbol and \c AN_EXAMPLE_SYMBOL as \c AnExampleSymbol
- \i Identifier
- \row
- \i Complete Switch Statement
- \i Adds all possible cases to a switch statement of the type \c enum
- \i Switch
- \row
- \i Generate Missing Q_PROPERTY Members...
- \i Adds missing members to a Q_PROPERTY:
- \list
- \o \c read method
- \o \c write method, if there is a WRITE
- \o \c {on...Changed} signal, if there is a NOTIFY
- \o data member with the name \c {m_<propertyName>}
- \endlist
- \i Q_PROPERTY
- \endtable
-
- \section2 Refactoring QML Code
-
- You can apply the following types of refactoring actions to QML code:
-
- \list
-
- \o Rename IDs
-
- \o Split initializers
-
- \o Move a QML element into a separate file to reuse it in other
- .qml files
-
- \endlist
-
- The following table summarizes the refactoring actions for QML code. The
- action is available when the cursor is in the position described in the
- Activation column.
-
- \table
- \header
- \i Refactoring Action
- \i Description
- \i Activation
-
- \row
- \i Move Component into 'filename.qml'
- \i Moves a QML element into a separate file
- \i Element name
- \row
- \i Rename id
- \i Renames all instances of an element ID in the currently open file
- \i Element ID
- \row
- \i Split Initializer
- \i Reformats a one-line element into a multi-line element. For example,
- rewrites
-
- \code
- Item { x: 10; y: 20; width: 10 }
- \endcode
-
- as
-
- \code
- Item {
- x: 10;
- y: 20;
- width: 10
- }
- \endcode
- \i Element property
-
- \endtable
- */
-
-/*!
- \contentspage index.html
- \previouspage creator-mobile-example.html
- \page creator-project-managing.html
- \nextpage creator-project-creating.html
-
- \title Managing Projects
-
- To set up a project, you first have to decide what kind of an
- application you want to develop: whether you want a user interface
- based on Qt Quick, Qt widgets, or HTML5. For a Qt Quick or HTML5 project,
- you must also
- choose the language to implement the application logic: C++ or JavaScript.
- You can also create other kinds of projects, such as Qt console
- applications, shared or static C++ libraries, or subprojects.
-
- You can use wizards to create and import projects. The wizards prompt you
- to enter the settings needed for that particular type of project and create
- the necessary files for you. You can add your own custom wizards to
- standardize the way subprojects and classes are added to a project.
-
- The wizards set up projects to use the Qt build tool, qmake. It is a
- cross-platform system for build automation that helps simplify the build
- process for development projects across different platforms. qmake
- automates the generation of build configurations so that only a few lines
- of information are needed to create each configuration. For more
- information about qmake, see the
- \l{http://qt.nokia.com/doc/4.7/qmake-manual.html}{qmake Manual}.
-
- You can modify the build and run settings for qmake projects in the
- \gui Projects mode.
-
- Alternatively, you can use the CMake build automation system and set up the
- projects manually. In addition, you can import generic projects that do not
- use qmake or CMake. This allows you to use Qt Creator as a code editor. For
- generic projects, Qt Creator ignores your build system.
-
- To develop applications for Symbian devices, you use
- qmake and the local Symbian compiler (on Windows) or qmake and a compilation
- service at Nokia Developer (on Linux and Mac OS) to build the applications for
- the Symbian devices target. The interface to the compilation service, Remote
- Compiler, is installed as a part of the \QSDK. For more information, see
- \l{Building with Remote Compiler}.
-
- You can install Maemo, MeeGo Harmattan, and Symbian targets as parts of
- the \QSDK. The build and run settings for the selected targets are set up
- automatically. However, you need to install and
- configure some additional software on the devices to be able to connect to
- them from the development PC.
-
- You can use sessions to store personal data, such as bookmarks and
- breakpoints that are usually not of interest to other developers working on
- the same projects. Sessions allow you to quickly switch between projects
- when you work on several projects.
-
- The following sections describe how to manage projects:
-
- \list
- \o \l{Creating a Project}
- \o \l{Opening a Project}
- \o \l{Adding Libraries to Projects}
- \o \l{Connecting Maemo Devices}
- \o \l{Connecting MeeGo Harmattan Devices}
- \o \l{Connecting Generic Linux Devices}
- \o \l{Connecting Symbian Devices}
- \o \l{Managing Sessions}
- \endlist
-
- For advanced options, see the following topics:
-
- \list
- \o \l{Adding New Custom Wizards}
- \o \l{Setting Up a CMake Project}
- \o \l{Setting Up a Generic Project}
- \endlist
-
-*/
-
-
-/*!
- \contentspage index.html
- \previouspage creator-project-managing.html
- \page creator-project-creating.html
- \nextpage creator-project-opening.html
-
- \title Creating a Project
-
- \image qtcreator-new-project.png
-
- You can use wizards to create following types of projects:
-
- \list
-
- \o Qt Quick Project
-
- Use QML elements or Qt Quick Components to define the user interface and,
- optionally, C++ or JavaScript to define the application logic.
-
-
-
- \o Qt Widget Project
-
- Use \QD forms to define a Qt widget based
- user interface and C++ to define the application logic
-
- \o Other Project
-
- \list
-
- \o HTML5 based applications
-
- \o Qt console applications
-
- \o Shared or static C++ libraries
-
- \o Qt unit tests
-
- \o Qt Custom Designer Widgets
-
- \o Subprojects
-
- \endlist
-
- \o Project from Version Control
-
- Import a project from a supported version control system. For more
- information on how version control systems are integrated in
- Qt Creator, see \l{Using Version Control Systems}.
-
- \endlist
-
- To create a new project, select \gui File > \gui{New File or Project} and
- select the type of your
- project.
- The contents of the wizard dialogs depend on the project type and
- the build targets that you select in the \gui {Target Setup} dialog.
- Follow the instructions of the wizard.
-
- For examples of creating different types of projects, see
- \l{Getting Started}.
-
- For more information about creating Qt Quick projects, see
- \l {Creating Qt Quick Projects}.
-
- To change the location of the project directory, and to specify settings
- for building and running projects, select \gui{Tools} > \gui{Options...} >
- \gui{Projects} > \gui{General}.
-
- To specify build and run settings for different target platforms, select
- \gui Projects.
-
- \section1 Adding Files to Projects
-
- You can use wizards also to add individual files to your projects.
- You can create the following types of files:
-
- \list
-
- \o Qt resource files, which allow you to store binary files in the
- application executable
-
- \o \QD forms and \QD form classes, which specify parts of user
- interfaces in Qt widget based projects
-
- \o QML files, which specify elements in Qt Quick projects
-
- \o GLSL files that define fragment and vertex shaders in both Qt Quick
- projects and Qt widget based projects
-
- \o C++ class, source, or header files that you can use to write the
- application logic in both Qt Quick projects and Qt widget based
- projects
-
- \o JavaScript files that you can use to write the application logic in
- Qt Quick projects
-
- \o Text files
-
- \endlist
-
- \section2 Creating C++ Classes
-
- The \gui {C++ Class Wizard} allows you to create a C++ header and source file for
- a new class that you can add to a C++ project. Specify the class name, base
- class, and header and source files for the class.
-
- The wizard supports namespaces. To use a namespace, enter a qualified
- class name in the \gui {Class name} field. For example:
- MyNamespace::MySubNamespace::MyClass.
-
- \image qtcreator-cpp-class-wizard.png "Enter Class Name dialog"
-
- The names of the header and source file are based on the class name. To change the
- default suffix of a file, click \gui Configure.
-
- You can create your own project and class wizards. For more information,
- see \l{Adding New Custom Wizards}.
-
- \section2 Creating OpenGL Fragment and Vertex Shaders
-
- Qt provides support for integration with OpenGL implementations on all
- platforms, which allows you to display hardware accelerated 3D graphics
- alongside a more conventional user interface. For more information, see
- \l{http://doc.qt.nokia.com/4.7/qtopengl.html}{QtOpenGL Module}.
-
- You can use the QGLShader class to compile OpenGL shaders written in the
- OpenGL Shading Language (GLSL) and in the OpenGL/ES Shading Language
- (GLSL/ES). QGLShader and QGLShaderProgram shelter you from the details of
- compiling and linking vertex and fragment shaders.
-
- You can use Qt Creator code editor to write fragment and vertex shaders
- in GLSL or GLSL/ES. The code editor provides syntax highlighting and code
- completion for the files.
-
- \image qtcreator-new-opengl-file.png "New OpenGL file wizard"
-
- \section2 Displaying Additional File Types in Projects Pane
-
- Qt Creator determines whether to display files from the project folder
- in the \gui Projects pane depending on the file type (.pro, .pri, .cpp,
- .h, .ui, .qrc, and so on). To display other types of files, edit the
- project file. Add filenames as values of the \c {OTHER_FILES} variable.
- You can also use wildcards.
-
- For example, the following code specifies that text files are displayed
- in the \gui Projects pane:
-
- \code
-
- OTHER_FILES += *.txt
-
- \endcode
-
- This also makes the files available in the \gui Locator.
-
- \section1 Adding Subprojects to Projects
-
- When you create a new project, you can add it to another project as a subproject
- in the \gui{Project Management} dialog. However, the root project must
- specify that qmake uses the \c subdirs template to build the project.
-
- To create a root project, select \gui {File > New File or Project... >
- Other Project > Subdirs Project > Choose}.
-
- On the \gui Summary page, select \gui {Finish & Add Subproject} to create
- the root project and to add another project, such as a C++ library.
-
- The wizard creates a project file (.pro) that defines a \c subdirs template
- and the subproject that you add as a value of the
- \l{http://doc.qt.nokia.com/4.7/qmake-variable-reference.html#subdirs}{SUBDIRS variable}.
- It also adds all the necessary files for the subproject.
-
- To add more subprojects, right-click the project name in the \gui Projects
- pane, and select \gui {New Subproject} in the context menu.
-
- To remove subprojects, right-click the project name in the \gui Projects
- pane, and select \gui {Remove Subproject} in the context menu.
-
- To specify dependencies, use the \gui{Add Library} wizard. For more information,
- see \l{Adding Libraries to Projects}.
-
-*/
-
-
-/*!
- \contentspage index.html
- \previouspage creator-project-creating.html
- \page creator-project-opening.html
- \nextpage creator-project-qmake-libraries.html
-
- \title Opening a Project
-
- Qt Creator stores information that it needs to build projects in a .user file.
- If Qt Creator cannot find the file when you open an existing project, it prompts you
- to enter the information. If you created the project by using another Qt Creator
- instance, Qt Creator asks whether you want to use the old settings. The settings
- are specific to the development environment, and should not be copied from one
- environment to another. Therefore, we recommend that you click \gui No and enter
- the information again in the \gui {Project Setup} dialog.
-
- The \gui {Project Setup} dialog displays a list of development environments for
- target platforms (such as desktop, Maemo5 devices, and Symbian devices) that are
- installed on the development PC. Select the Qt versions that you want to use to build
- the project for each target.
-
- \image qtcreator-open-project-targets.png "Target Setup dialog"
-
- If Qt Creator cannot find an existing build for a particular development
- environment (Qt version) and target, it starts out from a clean slate, and
- creates a new build in the specified directory. Qt Creator suggests a name
- and location for the directory that you can change.
-
- By default, Qt Creator does a \l{glossary-shadow-build}{shadow build} and also
- creates the directory. However, shadow building is not supported for the Symbian
- Devices, Maemo5, or Harmattan target on Windows.
-
- If you have built the project before, Qt Creator can use the existing build
- configuration to make the exact same build as found in the directory available to
- Qt Creator.
-
- If you know you have a build, but it is not listed, click \gui {Add Build}
- to locate it. Select a directory, and Qt Creator scans it (including
- subdirectories) for additional builds of the project. Qt Creator adds the found
- builds to the target list.
-
- You can edit the build configuration later. For more information, see
- \l{Editing Build Configurations}.
-
- To open a project:
-
- \list 1
-
- \o Select \gui File > \gui{Open File or Project} and select the project
- to open.
-
- \o In the \gui {Project Setup} dialog, select the Qt versions to use as
- build targets for your project, and click \gui{Finish}.
-
- \note If you have only one development environment installed, this dialog
- is skipped.
-
- \endlist
-
- Qt Creator parses all the source files in the project and performs a semantic
- analysis to build up the information that it needs for functions such as
- navigation and finding usages. A progress bar is displayed during parsing.
-
-*/
-
-
-/*!
- \contentspage index.html
- \previouspage creator-os-supported-platforms.html
- \page creator-project-wizards.html
- \nextpage creator-project-cmake.html
-
- \title Adding New Custom Wizards
-
- If you have a team working on a large application or several applications,
- you might want to standardize the way the team members create projects
- and classes.
-
- You can copy the wizard templates in the template folders
- to create your own project and class wizards. They are displayed in the
- \gui New dialog that opens when you choose \gui {File > New File or Project}.
-
- In a project wizard, you can specify the files needed in a project.
- You can add wizard pages to allow developers to specify settings for the
- project.
-
- In a class wizard, you can allow developers to specify the class name, base
- class, and header and source files for the class.
-
- To see how this works, rename wizard_sample.xml as wizard.xml in the
- \c {\share\qtcreator\templates\wizards\listmodel\helloworld} and
- \c {\share\qtcreator\templates\wizards\listmodel\listmodels} folders. After
- you restart Qt Creator, the \gui {Custom Classes}
- and \gui {Custom Projects} categories appear in the \gui New dialog.
-
- \image qtcreator-custom-project-wizards.png "The New dialog with custom projects and classes"
-
- \section1 Overview of Custom Wizards
-
- A custom wizard defines the user interface of a wizard page. The values the user enters
- in the wizard are assigned field names. Field name and value pairs are then passed to
- the file creation process. File creation can happen in the following ways:
-
- \list 1
-
- \o Template-based, where source files that contain placeholders for
- the field names are provided. During processing, the placeholders are replaced
- by the values from the wizard page. Optionally, modifier
- characters are applied. For more information, see \l{Processing Template Files}.
-
- \o Generator script, where a script is called to create the files.
-
- \note This option mainly exists to accommodate existing generator scripts or
- cases where complicated algorithmic logic is required when generating files. Writing
- cross-platform scripts is inherently difficult, and therefore, it is not recommended
- for new wizards. For more information, see \l{Using Generator Scripts}.
-
- \endlist
-
- Custom wizards are located in subdirectories of the following directories:
-
- \list
-
- \o \c{share/qtcreator/templates/wizards}
-
- \o the local user's configuration folder,
- \c{$HOME/.config/Nokia/qtcreator/templates/wizards}
-
- \o \c{%APPDATA%\Nokia\qtcreator\templates\wizards}
-
- \endlist
-
- They contain an XML configuration file called wizard.xml, the
- template source files, and optionally, the generator script.
-
- \section1 Creating Project Wizards
-
- To create a project wizard:
-
- \list 1
-
- \o Make a copy of the \c {share/qtcreator/templates/wizards/helloworld} or
- \c {share/qtcreator/templates/wizards/listmodel} folder.
-
- \o Modify the wizard_example.xml file.
-
- \o The following code determines the type of the wizard and its place
- in the \gui New dialog:
-
- \code
-
- <wizard version="1" kind="project"
- class="qt4project" firstpage="10"
- id="A.HelloWorld" category="B.CustomProjects">
-
- \endcode
-
- \list
-
- \o \c version is the version of the file contents. Do not modify this value.
-
- \o \c kind specifies the type of the wizard: \c project or \c class.
-
- \o \c class specifies the type of the project. Currently the only available
- type is \c qt4project, which specifies a Qt console project.
-
- \o \c firstpage specifies the place of the new page in the standard project
- wizard. The value 10 ensures that the custom page appears after the standard
- pages, as the last page of the wizard.
-
- \o \c id is the unique identifier for your wizard. The letter specifies the
- position of the wizard within the \c category. The HelloWorld wizard appears
- as the first wizard in the second category in the \gui New dialog.
-
- \o \c category is the category in which to place the wizard in the list.
- The letter specifies the position of the category in the list in the \gui New
- dialog.
-
- \endlist
-
- \o The following code specifies the icon and text that appear in the \gui New
- dialog:
-
- \code
-
- <icon>console.png</icon>
- <description>Creates a hello-world-project with custom message.</description>
- <description xml:lang="de">Erzeugt ein Hello-Welt-Projekt mit einer Nachricht.</description>
- <displayname>Hello World</displayname>;
- <displayname xml:lang="de">Hallo Welt</displayname>;
- <displaycategory>Custom Projects</displaycategory>
- <displaycategory xml:lang="de">Benutzerdefinierte Projekte</displaycategory>
-
- \endcode
-
- \list
-
-
- \o \c icon appears next to the \c displayName.
-
- \o \c description appears at the bottom of the \gui New dialog when you
- select the display name.
-
- \o \c displayName appears in the \gui New dialog, under the
- \c displayCategory.
-
- You can add translations as values for the text elements. Specify the target
- language as an attribute for the element. Use locale names (QLocale).
- For example, \c {xml:lang="de"}.
-
- \endlist
-
- \o Files to be added to the project:
-
- \list
- \o Template-based: The following code specifies the files to add to the project:
- \code
- <files>
- <file source="main.cpp" openeditor="true" />
- <file source="project.pro" target="%ProjectName%.pro" openproject="true" />
- <file source="icon.png" target="%ProjectName%.png" binary="true" />
- \endcode
- \list
-
- \o \c source specifies the file to copy to the project. The files must be
- located in the wizard folder.
-
- \o \c openeditor indicates that the file is to be opened in an editor after
- the wizard has finished.
-
- \o \c binary indicates that the file is a binary file (for example, an
- image file). It is to be copied to the target folder as is. Placeholders
- are not replaced with values.
-
- \o \c target specifies the new filename for the file. The \c {%ProjectName%}
- variable is replaced with the string that users specify in the \gui Name
- field on the first page of the wizard.
-
- \o \c openproject indicates that the file is a project file which is to be opened
- after the wizard has finished.
-
- \endlist
-
- See also \l{Processing Template Files}.
-
- \o Generator-script: The following code specifies that the script \c generate.pl is to be used
- to create the files:
- \code
- <generatorscript binary="generate.pl">
- <argument value="--class-name=%ClassName%"/>
- <argument value="--project-name=%ProjectName%"/>
- <argument value="--header-suffix=%CppHeaderSuffix%" omit-empty="true"/>
- <argument value="--source-suffix=%CppSourceSuffix%" omit-empty="true"/>
- <argument value="--description=%Description%" omit-empty="true" write-file="true"/>
- </generatorscript>
- \endcode
- In each argument, the field placeholders are replaced by the field
- values. There are additional boolean attributes which give fine-grained control:
-
- \list
- \o \c omit-empty specifies that complete argument is to be omitted when all
- placeholders expand to empty values. In the above example,
- the option \c --source-suffix will not be passed to the script if the value is empty.
-
- \o \c write-file indicates that instead of the expanded value,
- the value will be written to a temporary file and its file name will be
- passed to the script instead. This is useful for multi-line text fields.
- \endlist
-
- See also \l{Using Generator Scripts}.
- \endlist
-
- \o The following code creates a page that specifies settings for the project:
-
- \code
-
- <!-- Create a 2nd wizard page with parameters -->
- <fieldpagetitle>Hello World Parameters</fieldpagetitle>
- <fieldpagetitle xml:lang="de">Hallo Welt Parameter</fieldpagetitle>
- <fields>
- <field mandatory="true" name="MESSAGE">
- <fieldcontrol class="QLineEdit" validator='^[^"]+$' defaulttext="Hello world!" />
- <fielddescription>Hello world message:</fielddescription>
- <fielddescription xml:lang="de">Hallo-Welt-Nachricht:</fielddescription>
- </field>
- </fields>
-
- \endcode
-
- \list
-
- \o \c fieldpagetitle specifies the title of the page.
-
- \o \c field specifies whether the field is mandatory (\c true or \c false).
- You can use the value of the \c name field as a variable in other files (for
- example, \c {%MESSAGE%}.
-
- \o \c fieldcontrol specifies the field. \c class specifies the field type.
- You can use interface objects from the QWidget class to create fields. This
- example uses QLineEdit to create an input field.
-
- \o \c validator specifies a regular expression to check the characters allowed in
- the field.
-
- \o \c defaulttext specifies text that appears in the field by default.
-
- \o \c fielddescription specifies the field name that appears on the wizard page.
-
- \endlist
-
- \endlist
-
- \section1 Creating Class Wizards
-
- The widget.xml file for a class wizard is very similar to that for a project
- wizard. The differences are discussed below.
-
- To create a class wizard:
-
- \list 1
-
- \o The following code specifies settings for the wizard:
-
- \code
-
- <wizard version="1" kind="class" id="A.ListModel" category="B.CustomClasses">
-
- <description>Creates a QAbstractListModel implementation.</description>
- <description xml:lang="de">Erzeugt eine Implementierung von QAbstractListModel.</description>
-
- <displayname>QAbstractListModel implementation</displayname>
- <displayname xml:lang="de">Implementierung von QAbstractListModel</displayname>
-
- <displaycategory>Custom Classes</displaycategory>
- <displaycategory xml:lang="de">Benutzerdefinierte Klassen</displaycategory>
-
- \endcode
-
- For more information about the elements and their values, see
- \l {Creating Project Wizards}.
-
- \o The following code specifies the files to add to the project:
-
- \code
-
- <files>
- <file source="listmodel.cpp" target="%ClassName:l%.%CppSourceSuffix%" openeditor="true" />
- <file source="listmodel.h" target="%ClassName:l%.%CppHeaderSuffix%" openeditor="true" />
- </files>
-
- \endcode
-
- Here, \c target contains the following variables that are used to construct
- the filename:
-
- \list
-
- \o \c {%ClassName:l%} is replaced with the value of the \c ClassName field.
- The modifier \c l converts the string to lower case, to observe Qt
- conventions.
-
- \o \c {%CppSourceSuffix%} and \c {%CppHeaderSuffix%} are pre-defined.
- For more information, see \l{Pre-defined Standard Variables}.
-
- \endlist
-
- \code
-
- <!-- Create parameter wizard page -->
-
- <fieldpagetitle>ListModel parameters</fieldpagetitle>
- <fieldpagetitle xml:lang="de">Parameter des ListModel</fieldpagetitle>
- <fields>
- <field name="ClassName">
-
- <fieldcontrol class="QLineEdit" validator="^[a-zA-Z0-9_]+$" defaulttext="MyListModel" />
-
- <fielddescription>Class name:</fielddescription>
- <fielddescription xml:lang="de">Klassenname:</fielddescription>
- </field>
- <field name="Datatype">
-
- <fieldcontrol class="QComboBox" combochoices="QString,int" defaultindex="0" />
-
- <fielddescription>Data type:</fielddescription>
- <fielddescription xml:lang="de">Datentyp:</fielddescription>
- </field>
- </fields>
-
- \endcode
-
- In addition to QLineEdit, QComboBox is used in the class wizard to create
- a field. \c combochoices specifies the options in the combobox and
- \c defaultindex specifies that QString is the default value.
-
- \endlist
-
- \section1 Processing Template Files
-
- When processing a template source file, placeholders specifying the field names
- in the format \c{%FIELDNAME%} are replaced by the values entered by the user.
- In addition, modifier characters are supported. For example, \c{%FIELDNAME:u%}
- specifies that the value is converted to upper case. This enables generating header
- guards for C++ header files.
-
- The following modifier characters are supported:
-
- \list
- \o \c{l} for lower case.
- \o \c{u} for upper case.
- \o \c{c} for upper case initial letter ("project" > "Project").
- \endlist
-
- You can use conditions to add sections of the file depending on field values.
- Use a syntax that is similar to C++ preprocessing, as demonstrated in
- the profile of the \c{helloworld} example:
-
- \code
-
- @if "%SCRIPT%" == "true"
- QT += script
- @endif
-
- \endcode
-
- The value of the Boolean (QCheckBox) field labeled \c{SCRIPT} determines
- whether the script module is added. The expressions must expand to valid
- Javascript expressions after field replacement.
-
- \section1 Pre-defined Standard Variables
-
- In addition to the field values entered by the user, you can use
- the following pre-defined standard values:
-
- \list
-
- \o \c {%ProjectName%} is replaced by the name of the project in the case
- of project wizards.
-
- \o \c {%Path%} is replaced by the path to the target directory.
- For classes, this is the directory, where the files
- are created. For project wizards, an additional subdirectory
- named after the project is created.
-
- \o \c {%TargetPath%} is replaced by the path to the directory where the actual files
- are created. For non-project wizards, it is identical to \c %Path%.
- For project wizards, it is \c %Path%/%ProjectName%.
-
- \o \c {%CppSourceSuffix%} is replaced by the default source suffix, which
- is defined in Qt Creator in \gui {Tools > Options... > C++ > File Naming}.
- For example, if users enter \bold MyClass, the filename becomes myclass.cpp
- when the project is created.
-
- \o \c {%CppHeaderSuffix%} is replaced by the default header suffix, which
- is also defined in \gui {File Naming}.
-
- \endlist
-
- \section1 Validating User Input
-
- You can specify validation rules for user input. The rules consist of a Boolean
- JavaScript expression and an error message. The placeholders in them are
- replaced with values before they are evaluated or displayed.
-
- Consider the following rule used in the \l{Creating Class Wizards} example:
-
- \code
- <validationrules>
- <validationrule condition='"%ClassName%" != "QAbstractListModel"'>
- <message>%ClassName% cannot be used as class name.</message>
- <message xml:lang="de">%ClassName% kann nicht als Klassenname verwendet werden.</message>
- </validationrule>
- </validationrules>
- \endcode
-
- It ensures that the class name entered by the user does not match the name of
- the base class. If the validation fails, a red label displaying the message appears
- at the bottom of the wizard page.
-
- \section1 Using Generator Scripts
-
- The values entered in the wizard page are passed to the script
- as command line arguments as defined by the wizard configuration file.
-
- In addition, the script must implement a \c{--dry-run} command line option.
-
- Qt Creator needs to know the file names before the files are created to check
- whether files with identical names already exist, for example. Therefore,
- script file generation is a two-step process:
-
- \list 1
-
- \o Determine file names and attributes: The script is called with the command line
- \c{--dry-run} option and the field values. It then prints the relative path
- names of the files it intends to create, followed by comma-separated attributes
- matching those of the \c{<file>} element, for example:
-
- \code
- myclass.cpp,openeditor
- myclass.h,openeditor
- myproject.pro,openproject
- \endcode
-
- \o Create files: The script is called with the parameters only in the working directory.
- It then actually creates the files. If directories are needed, the script
- should create them, too.
-
- \endlist
-
- The \c{scriptgeneratedproject} sample wizard illustrates the usage.
- A typical script invocation for this example (obtained by running Qt Creator with
- \c{--customwizard-verbose}) looks as follows:
-
- \code
- generate.pl --class-name=TestClass --project-name=TestProject --header-suffix=h --source-suffix=cpp --description=/tmp/qtcreatorj26629.txt
- \endcode
-
- By default, the scripts are run in the directory corresponding to
- \c %TargetPath%. This can be overriden by specifying the
- attribute \c workingdirectory on the element \c generatorscript.
- For example, if the script creates the project directory by itself,
- %Path% can be specified. In that case, \c --dry-run should output
- the correct relative paths or absolute paths constructed using the value of
- \c %Path%.
-
-*/
-
-
-/*!
- \contentspage index.html
- \previouspage creator-build-settings.html
- \page creator-project-qmake.html
- \nextpage creator-tool-chains.html
-
- \title Adding Qt Versions
-
- Qt Creator allows you to have multiple versions of Qt installed on
- your development PC and use different versions to build your projects for
- different targets. For example, \QSDK contains special Qt versions for
- MeeGo Harmattan, Maemo, and Symbian development.
-
- Qt Creator checks the directories listed in the \c{PATH} environment
- variable for the qmake executable. If a qmake executable is found, it is
- referred to as \bold{Qt in PATH} and selected as the Qt version to use
- in the \gui Projects mode in the \gui {Build Settings}. If Qt Creator
- cannot find qmake, the value in the \gui {Qt version} field might be
- invalid and you might need to change it.
-
- Qt Creator automatically detects the Qt versions that are registered by
- your system or by \QSDK. To view the settings for each Qt version, move the
- mouse pointer over it in the list. To add Qt versions, select
- \gui {Tools > Options... > Qt4 > Qt Versions}.
-
- Typically, you select the Qt versions for a project when you use project
- wizards to create the project. You can add Qt versions for a project in
- \gui {Build Settings}.
-
- \section2 Setting Up New Qt Versions
-
- To add a Qt version:
-
- \list 1
-
- \o Select \gui Tools > \gui Options... > \gui Qt4 > \gui Add.
-
- \image qtcreator-qt4-qtversions-add.png
-
- \o In the \gui{qmake location} field, enter the path to the
- directory where the qmake executable is located.
-
- \o In the \gui{Version name} field, edit the name that Qt Creator
- suggests for the Qt version.
-
- Qt Creator automatically determines the path to the binaries in
- the Qt installation and displays it in the dialog.
-
- \o In the \gui Helpers section, you can build the debugging
- helpers that are available for the Qt version. This is
- necessary, because the internal data structures of Qt can
- change between versions. For more information, see
- \l{Using Debugging Helpers}.
-
- \endlist
-
- \section2 Setting Up Qt for Symbian Versions
-
- If you install Qt for Symbian as a part of \QSDK, it is automatically
- detected by Qt Creator. If you install other Symbian SDKs and register them
- with devices.exe, Qt Creator automatically detects the Qt version.
-
- If the selected Qt version was built using the SBSv2 build system, that
- is available for Symbian OS 9.5 based SDKs, Qt Creator builds your projects
- using this build system. The \gui {SBS v2 directory} field is enabled and
- you must specify the path to the directory where the SBS executable (for
- example, sbs.bat on Windows) is located.
-
- To add a Qt for Symbian version:
-
- \list 1
-
- \o Select \gui Tools > \gui Options... > \gui Qt4 > \gui{Qt Versions}.
-
- \o Select the Qt for Symbian version you want the Qt Creator to use.
-
- \image qtcreator-qt4-qtversions-win-symbian.png
-
- For more information about how to add tool chains for using the
- GCCE and WINSCW compilers, see \l{Adding Tool Chains}.
-
- \o In the \gui {S60 SDK} field, enter the path to the directory where
- the Symbian SDK is located.
-
- \o In the \gui {SBS v2 directory} field, enter the path to the
- directory where the SBS v2 executable is located.
-
- \endlist
-
-*/
-
-
-/*!
- \contentspage index.html
- \previouspage creator-project-qmake.html
- \page creator-tool-chains.html
- \nextpage creator-run-settings.html
-
- \title Adding Tool Chains
-
- A \e {tool chain} specifies a compiler and a debugger and other necessary
- tools for building an application that is targeted for a particular desktop
- or mobile platform. Qt Creator automatically detects the tool chains that
- are registered by your system or by \QSDK.
-
- You can add tool chains to build applications by using other compilers or
- with different versions of the automatically detected compilers:
-
- \list
-
- \o GNU Compiler Collection (GCC) is a compiler for Linux and
- Mac OS X.
-
- \o MinGW (Minimalist GNU for Windows) is a native software port of GCC
- and GNU Binutils for use in the development of native Microsoft
- Windows applications on Windows. MinGW is
- distributed together with Qt Creator and Qt SDK for Windows.
-
- \o Linux ICC (Intel C++ Compiler) is a group of C and C++ compilers
- for Linux.
-
- \o Clang is a C, C++, Objective C, and Objective C++ front-end for the
- LLVM compiler for Windows, Linux, Mac OS X, and Symbian.
-
- \o GCCE (GNU Compiler Collection for Embedded) is an ARM-based
- compiler used in Symbian OS 9 and distributed together with \QSDK.
-
- \o RVCT is an ARM-based compiler for building applications for Symbian
- devices (requires a license).
-
- \o WINSCW is a compiler for building applications that can be run or
- debugged on the Symbian Emulator. It is distributed together with
- Symbian SDKs (but not with the \QSDK).
-
- \endlist
-
- To build an application using GCC, MinGW, GCCE, or Clang, specify the paths
- to the
- directories where the compiler and debugger are located and select the
- application binary interface (ABI) version from the list of available
- versions. You can also create a custom ABI definition.
-
- Qt Creator allows you to select a tool chain that matches the Qt version
- in the \gui Projects mode \gui {Build Settins}.
-
- To add tool chains:
-
- \list 1
-
- \o Select \gui {Tools > Options... Tool Chains > Add} and select a
- compiler in the list.
-
- \image qtcreator-toolchains.png
-
- To clone the selected tool chain, select \gui {Clone}.
-
- \o In the \gui Name column, double-click the name to change it.
-
- \o In the \gui{Compiler path} field, enter the path to the directory
- where the compiler is located. For WINSCW, enter the path to the
- Carbide C++ installation directory here.
-
- The other settings to specify depend on the tool chain.
-
- \o For RVCT, select the ARM version to use in the \gui {ARM version}
- field. RVCT 2.2 is supported on Symbian^3 and earlier. RVCT 4.0 b902
- or later is required for Symbian Belle.
-
- \endlist
-
- \section2 Troubleshooting MinGW Compilation Errors
-
- If error messages displayed in the \gui {Compile Output} pane contain
- paths where slashes are missing (for example, C:QtSDK),
- check your PATH variable. At the command line, enter the following commands:
-
- \code
- where sh.exe
- where make.exe
- where mingw32-make.exe
- \endcode
-
- If these commands show paths, they have been added to the global PATH variable
- during the installation of a tool chain based on Cygwin or MinGW, even though
- this is against Windows conventions.
-
- To keep working with the third-party tool chain, create a new shell link
- that adds the required paths (as Visual Studio and Qt do). The shell link
- must point to cmd.exe, as illustrated by the following example:
-
- \c {C:\Windows\System32\cmd.exe /K C:\path_to\myenv.bat}
-
- where the /K parameter carries out the command specified in the bat file.
-
- Create the myenv.bat file at \e path_to, which should be in a convenient location.
- In the file, specify the paths to the tool chains. For example,
-
- \c {set PATH=C:\path1;C:\path2;%PATH%}
-
- where \e path1 and \e path2 are paths to the tool chains.
-
- Finally, remove the paths from the global PATH, reboot the computer, and
- run the \c where commands again to verify that the global PATH is now clean.
-
- You can use the shell link to run the tools in the third-party tool chains.
-
-*/
-
-
-/*!
- \contentspage index.html
- \previouspage creator-project-opening.html
- \page creator-project-qmake-libraries.html
- \nextpage creator-developing-meego.html
-
- \title Adding Libraries to Projects
-
- In addition to Qt libraries, you can add other libraries to your projects.
- The way the library is added depends on whether it is a system library or
- your own library or a 3rd party library located in the build tree of the
- current project or in another build tree.
-
- \image qtcreator-add-library-wizard.png "Add Library wizard"
-
- Because system libraries do not typically change and are often found by
- default, you do not need to specify the path to the library or to its includes
- when you add it.
-
- For your own libraries and 3rd party libraries, you need to specify
- the paths. Qt Creator tries to guess the include path for an external library,
- but you need to check it and modify it if necessary. Qt Creator automatically
- adds the include path for an internal library.
-
- For all libraries, select the target platforms for the application, library,
- or plugin.
-
- Specify whether the library is statically or dynamically linked. For a
- statically linked internal library, Qt Creator adds dependencies
- (PRE_TARGETDEPS) in the project file.
-
- Depending on the development platform, some options might be detected
- automatically. For example, on Mac OS, the library type (\gui Library or
- \gui Framework) is detected automatically and the option is hidden. However,
- if you develop on another platform than Mac OS and want to build your
- project for the Mac OS, you must specify the library type.
-
- The default convention on Windows is that the debug and release versions
- of a library have the same name,
- but are placed in different subdirectories, usually called \e debug and
- \e release. If the library path does not contain either of these folders,
- you cannot select the option to place the libraries in separate
- folders.
-
- Alternatively, the letter \e d can be added to the library name for the debug
- version. For example, if the release version is called example.lib, the
- debug version is called exampled.lib. You can specify that the letter
- is added for the debug version and removed for the release version.
- If the library name ends in \e d, deselect the \gui {Remove "d" suffix
- for release version} option.
-
- Qt Creator supports code completion and syntax highlighting for the added
- libraries once your project successfully builds and links to them.
-
- \section1 To Add Libraries
-
- \list 1
-
- \o In the \gui Projects pane, open the project file (.pro).
-
- \o Right-click in the code editor to open the context menu and select
- \gui {Add Library...}.
-
- \o Follow the instructions of the wizard.
-
- \endlist
-
- For more information about the project file settings, see
- \l{http://doc.qt.nokia.com/4.7/qmake-project-files.html#declaring-other-libraries}{Declaring Other Libraries}.
-
- \section1 Example of Adding Internal Libraries
-
- The following example describes how to add a statically linked internal
- library to your project.
-
- \list 1
-
- \o Choose \gui {File > New File or Project... > Other Projects >
- C++ Library} to create the library.
-
- The \gui {Introduction and Product Location} dialog opens.
-
- \image qtcreator-add-library-wizard-ex-1.png "Introduction and Product Location dialog"
-
- \o In the \gui Type field, select \gui {Statically Linked Library}.
-
- \o In the \gui Name field, give a name for the library. For example,
- \bold mylib.
-
- \o Follow the instructions of the wizard until you get to the
- \gui {Project Management} dialog. In the \gui {Add to project}
- list, select a project. For example, \bold myapp.
-
- \o In the \gui Projects pane, open the project file (.pro).
- For example, \bold myapp.pro.
-
- \o Right-click in the code editor to open the context menu and select
- \gui {Add Library... > Internal Library > Next}.
-
- \o In the \gui Library field, select \bold mylib and click \gui Next.
-
- \o Click \gui Finish to add the following library declaration to the
- project file:
-
- \code
- win32:CONFIG(release, debug|release): LIBS += -L$$OUT_PWD/../../../projects/mylib/release/ -lmylib
- else:win32:CONFIG(debug, debug|release): LIBS += -L$$OUT_PWD/../../../projects/mylib/debug/ -lmylib
- else:symbian: LIBS += -lmylib
- else:unix: LIBS += -L$$OUT_PWD/../../../projects/mylib/ -lmylib
-
- INCLUDEPATH += $$PWD/../../../projects/mylib
- DEPENDPATH += $$PWD/../../../projects/mylib
-
- win32:CONFIG(release, debug|release): PRE_TARGETDEPS += $$OUT_PWD/../../../projects/mylib/release/mylib.lib
- else:win32:CONFIG(debug, debug|release): PRE_TARGETDEPS += $$OUT_PWD/../../../projects/mylib/debug/mylib.lib
- else:unix:!symbian: PRE_TARGETDEPS += $$OUT_PWD/../../../projects/mylib/libmylib.a
- \endcode
-
- \endlist
-
-*/
-
-
-/*!
- \contentspage index.html
- \previouspage creator-usability.html
- \page creator-building-running.html
- \nextpage creator-building-targets.html
-
- \title Building and Running Applications
-
- Qt Creator provides support for building, running, and deploying Qt
- applications for desktop environment and mobile devices.
-
- You can set up the following configurations:
-
- \list
-
- \o \e {Build configuration}, which contains everything you need to
- compile the sources into binaries.
-
- \o \e {Deploy configuration}, which handles the packaging and copying
- of the necessary files to a location you want to run the executable at.
- The files can be copied to a location in the file system of the development
- PC or a mobile device.
-
- \o \e {Run configuration}, which starts the application in the location
- where it was stored by the deploy configuration.
-
- \endlist
-
- By default, when you select the \gui Run function, Qt Creator builds, deploys,
- and runs the project. For more information about how to change the default
- behavior, see \l{Customizing the Build Process}.
-
- \section1 Setting Up a Project
-
- When you install the \QSDK, the build and run settings for the tool chains
- delivered with the \QSDK are set up automatically.
-
- To view and modify the settings for currently open projects, switch to the
- \gui Projects mode by pressing \key Ctrl+5.
-
- \image qtcreator-projectpane.png
-
- You can add a target if the development environment for the target
- platform is installed on the
- development PC and the Qt version is configured. Click
- \inlineimage qtcreator-qt4-addbutton.png "Add Target button"
- and select from a list of available
- targets. To remove a target, select it and click
- \inlineimage qtcreator-target-remove.png "Remove Target button"
- .
-
- You can select the targets and use the \gui Build menu commands to
- build, deploy, and run projects.
-
- The project pane consists of the following tabs:
- \list
- \o \l{Running Applications on Multiple Targets}{Targets}
- (If you have installed the development environment for only one target, the \gui Targets
- tab is replaced by a \gui Build tab and a \gui Run tab.)
- \o \l{Specifying Build Settings}{Build Settings}
- \o \l{Specifying Run Settings}{Run Settings}
- \o \l{Specifying Editor Settings}{Editor Settings}
- \o \l{Specifying Code Style Settings}{Code Style Settings}
- \o \l{Specifying Dependencies}{Dependencies}
- \endlist
-
- Use the \gui Build and \gui Run buttons to switch between
- the build and run settings for the active project.
-
- If you have multiple projects open in Qt Creator, use the tabs at the
- top of the window to navigate between their settings.
-
- \section1 Customizing the Build Process
-
- To specify the relationship between the release, build, and deploy configurations, select
- \gui {Tools > Options... > Project}. By default, the \gui {Always build project
- before deploying it} and the \gui {Always deploy project before running it}
- options are enabled. Therefore, when you select the \gui Run function,
- Qt Creator builds, deploys, and runs the project.
-
- \image qtcreator-project-options-deploy.png "Project General Options"
-
-*/
-
-
-/*!
- \contentspage index.html
- \previouspage creator-building-running.html
- \page creator-building-targets.html
- \nextpage creator-running-targets.html
-
- \title Building Applications for Multiple Targets
-
- You can build applications for multiple targets. By default, when
- you run the application on a target, you also build and deploy it to the
- target, first. However, you can also perform each operation separately.
-
- To check that the application code can be compiled and linked for a target,
- you can build the project. The build errors and warnings are displayed in
- the \gui {Build Issues} output pane. More detailed information is displayed in
- the \gui {Compile Output} pane.
-
- To build an application:
-
- \list 1
-
- \o Select a target for the project.
-
- \image qtcreator-target-selector.png "Target selector"
-
- \o Choose \gui {Build > Build Project} or press \key {Ctrl+B}.
-
- \endlist
-
- For more information on the options you have, see \l{Specifying Build Settings}.
-
- \section1 Building for Symbian
-
- The tool chain for building applications locally on the development PC for
- the \gui {Symbian Device} target is only supported on Windows.
- If you develop on Linux or Mac OS, you must use the Remote Compiler
- interface to a compilation service at Nokia Developer. For more information,
- see \l{Building with Remote Compiler}.
-
- \section2 Troubleshooting Build Issues
-
- If you cannot build the application for a Symbian device, check that:
-
- \list
-
- \o You selected the Symbian Device target to build the application.
-
- \o You selected the correct Qt version to build the application.
-
- \endlist
-
- \section1 Building for Symbian Emulator
-
- Qt Creator does not create release configurations for the
- \gui {Symbian Emulator} target, because Symbian Emulator supports only debug
- builds.
-
-*/
-
-
-/*!
- \contentspage index.html
- \previouspage creator-building-targets.html
- \page creator-running-targets.html
- \nextpage creator-build-settings.html
-
- \title Running Applications on Multiple Targets
-
- By default, running an application also builds it and deploys it to a
- location from where it can be run on the desktop, in Qt Simulator, or
- on a mobile device that is connected to the development PC.
-
- To run executable files without deploying them first, deselect the \gui {Tools >
- Options... > Project > Always deploy project before running it} option.
- This allows you to test SIS files that you receive from Ovi Publishing or
- Symbian Signed after you have them signed, for example.
-
- For more information on the options you have, see \l{Specifying Run Settings}.
-
- \section1 Running on Desktop
-
- \list 1
-
- \o Select \gui Desktop as the target.
-
- \image qtcreator-target-selector.png "Target selector"
-
- \o Click the \gui Run button.
-
- \endlist
-
- \section1 Running on Qt Simulator
-
- You can use the Qt Simulator to test Qt applications that are intended
- for mobile devices in an environment similar to that of the device. You
- can change the information that the device has about its configuration
- and environment.
-
- \list 1
-
- \o Select \gui {Qt Simulator} as the target.
-
- \o Click the \gui Run button.
-
- \endlist
-
- For more information about using the Qt Simulator, see the
- \l{http://doc.qt.nokia.com/qtsimulator/index.html}{Qt Simulator Manual}.
-
- \section1 Running on Maemo or MeeGo Harmattan
-
- \list 1
-
- \o Build and run the application for \l{Running on Qt Simulator}{Qt Simulator}.
-
- \o Build and run the application for
- \l{Using Maemo or MeeGo Harmattan Emulator}
- {the Maemo or MeeGo Harmattan emulator}.
-
- \o Alternatively, you can build and run the application for a device:
-
- \list 1
-
- \o Configure the device and specify a connection to it. For more
- information, see \l{Connecting Maemo Devices} and
- \l{Connecting MeeGo Harmattan Devices}.
-
- \o Connect the device to the development PC.
-
- \o Click the \gui Run button.
-
- \endlist
-
- \endlist
-
- Qt Creator uses the compiler specified in the MADDE tool chain to
- build the application.
-
- Qt Creator generates an installation package, installs it on the device,
- and executes the selected application.
- The application views are displayed on the device.
- Command-line
- output is visible in the Qt Creator \gui {Application Output} view.
-
- Choose \gui {Projects > Maemo Run} to view the settings for deploying the
- application on the connected device and creating the installation package.
- For more information, see
- \l{Specifying Run Settings for Maemo and MeeGo Harmattan Devices}.
-
- Debugging also works transparently.
-
- \section1 Running on Generic Linux Devices
-
- \list 1
-
- \o Build and run the application for \l{Running on Qt Simulator}
- {Qt Simulator}.
-
- \o Build and run the application for a device:
-
- \list 1
-
- \o Specify a connection to the device. For more information, see
- \l{Connecting Generic Linux Devices}.
-
- \o Click the \gui Run button.
-
- \endlist
-
- \endlist
-
- Qt Creator uses the compiler specified in the project build settings
- (tool chain) to build the application.
-
- Qt Creator generates an installation package, installs it on the
- device, and executes the selected application. The application views are
- displayed on the device. Command-line output is visible in the Qt
- Creator \gui {Application Output} view.
-
- Choose \gui {Projects > Desktop > Run} to view the settings for deploying
- the application on the connected device and creating the installation
- package. For more information, see
- \l{Specifying Run Settings for Generic Linux Devices}.
-
- Debugging works transparently if GDB server is installed on the device and
- it is compatible with the GDB on the host.
-
- \section1 Running on Symbian
-
- \list 1
-
- \o Build and run the application for \l{Running on Qt Simulator}{Qt Simulator}.
-
- \o If no problems are found, build and run the application for a device.
-
- \o To test functionality that uses Symbian APIs, you can build and
- run the application for Symbian Emulator.
-
- \endlist
-
- \section2 Running on a Device
-
- \list 1
-
- \o Install the required software on the device. For more information, see
- \l{Connecting Symbian Devices}.
-
- \o Connect the device to the development PC through a USB cable.
- The target selector displays a green check mark when a
- device is connected.
-
- \image qtcreator-qt4-symbian-device-connected.png
-
- The tool tip of the target selector shows more details about the actual
- device that will be used when you run your application.
-
- \o Start the CODA debugging agent on the device.
-
- \note If you use CODA over an USB connection, it starts up
- automatically when you connect the device to the development PC.
-
- \o Click the \gui Run button.
-
- \endlist
-
- You can connect several devices to your development PC simultaneously.
- In the details of the run configuration for the \gui{Symbian Device} target,
- select the device to run your application on.
-
- When your application is ready for delivery to users, specify run settings
- for creating the final SIS installation packages. For more information,
- see \l{Creating SIS Files}.
-
- If you cannot run the application on a device, check that:
-
- \list
- \o The Nokia USB drivers that come with \e{PC Suite} or \e{Ovi Suite}
- have been installed on the development PC.
- \o The device is connected through USB cable in \e{PC Suite} mode.
- \o The CODA debugging agent is running on the device with
- the status \e connected.
-
- \note If you use the CODA debugging agent over WLAN, you must enter
- the WLAN address and port number in Qt Creator, separated by a
- colon (:). For example: 192.167.0.100:1534
- \o The device is detected and selected in the \gui {Run Settings}.
- \endlist
-
- If this does not help to solve your problem, search the qt-creator@trolltech.com
- mailing list archives or provide feedback to us via the methods described on the
- \l{http://developer.qt.nokia.com/wiki/Category:Tools::QtCreator}{Qt Creator Development Wiki}.
-
- \section2 Running on Symbian Emulator
-
- Select
- the \gui{Symbian Emulator} target as the active one, and build and run your
- project.
-
- If you cannot run the application in the emulator, check that:
- \list
- \o You selected the \gui{Symbian Emulator} target for your application.
-
- \o If you cannot select \gui {Symbian Emulator} as target, check that
- Carbide.c++ is installed correctly and that the path to the Carbide.c++
- installation directory is specified for the WINSCW tool chain in the
- \gui{Compiler path} field
- in \gui {Tools > Options... > Tool Chains}.
-
- \o If the emulator process cannot be started, try closing Qt Creator and
- starting the application directly from your file manager. Having
- done this, Qt Creator should be able to run your projects in the
- emulator.
-
- \endlist
-
-*/
-
-
-/*!
- \contentspage index.html
- \previouspage creator-publish-ovi.html
- \page creator-remote-compiler.html
- \nextpage creator-help.html
-
- \title Building with Remote Compiler
-
- The \gui {Remote Compiler} target is an interface to a compilation service at
- Nokia Developer. It provides a simple, standardized environment for building Qt
- applications and creating installation packages for Symbian, Maemo, and
- MeeGo Harmattan devices
- when you do not have the necessary tool chains and SDKs installed or they are
- not supported on the development PC. You can choose from a set of supported
- devices, such as S60 3rd Edition or S60 5th Edition devices.
-
- You need a Nokia Developer user account to use the Remote Compiler. You can
- create an account for free at \l{http://www.developer.nokia.com/}{Nokia Developer}.
-
- \note Remote Compiler is an experimental component that is installed as
- part of \QSDK.
-
- \list 1
-
- \o Select \gui {Start > \QSDK > Maintain \QSDK} to open the
- \gui {Maintain \QSDK} tool.
-
- \o In the \gui {Package Manager}, select \gui {Experimental >
- Remote Compiler} to install Remote Compiler.
-
- \o In Qt Creator, choose \gui {Tools > Options > Projects > Remote Compiler}
- to log on to Nokia Developer.
-
- \image remotecompiler-fn-logon.png "Remote Compiler options"
-
- \o Choose \gui {Projects}.
-
- \o Click
- \inlineimage qtcreator-qt4-addbutton.png "Add Target button"
- and select \gui {Remote Compiler} to add Remote Compiler as a target.
-
- \o Click \gui Add to add mobile device platforms as build configurations.
-
- \o Click the \gui {Target Selector} and select a build configuration.
-
- \o Choose \gui {Build > Build All}.
-
- \endlist
-
- The installation package is generated in the \gui {Build directory} on
- the development PC.
-
- For more information about Remote Compiler, choose \gui {Help > Contents >
- Remote Compiler Manual}. The document is added during the installation of
- Remote Compiler.
-
-*/
-
-
-/*!
- \contentspage index.html
- \previouspage creator-running-targets.html
- \page creator-build-settings.html
- \nextpage creator-project-qmake.html
-
- \title Specifying Build Settings
-
- Different build configurations allow you to quickly switch between
- different build settings. By default, Qt Creator creates \bold debug
- and \bold release build configurations. A debug build contains additional
- debug symbols that you need for debugging the application but that you
- can leave out from the release version. Generally, you use the debug
- configuration for testing and the release configuration for creating
- the final installation file.
-
- You specify build settings in the \gui Projects mode.
-
- \image qtcreator-projectpane.png
-
- To add a new build configuration, click \gui Add and select the type of
- configuration you would like to add. You can add as many build
- configurations as you need.
-
- To delete the build configuration currently selected, click \gui Remove.
-
- \section1 Editing Build Configurations
-
- To edit a build configuration:
- \list 1
- \o Select the build configuration you want to edit in
- \gui{Edit Build Configuration}.
- \o In the \gui {Qt version} field, select the Qt version to use for
- building project. You can add Qt versions to the list if they are
- installed on the development PC, but were not detected
- automatically. For more information, see \l{Adding Qt Versions}.
- \o In the \gui {Tool chain} field, select the tool chain required
- to build the project. The tool chains that are compatible with the
- selected Qt version are listed. You can add tool chains to the list
- if they are not automatically detected. For more information, see
- \l{Adding Tool Chains}.
-
- \o In the \gui {Build directory} field, specify the build directory for
- the project.
- By default, projects are built in a separate directory from the
- source directory, as \l{glossary-shadow-build}{shadow builds}.
- This keeps the files generated for each target platform separate.
-
- \note Shadow building is not supported by the Symbian build system.
- Also, shadow building on Windows is not supported for Maemo or
- MeeGo Harmattan.
- If you only build for one target platform, you can deselect
- the \gui{Shadow build} checkbox.
- \endlist
-
- \note The build configuration for the \gui{Symbian Device} target
- uses the GCCE tool chain by default. If you want to build
- for the device using RVCT, install the RVCT tool chain, and then
- select it in the \gui {Tool chain} field. RVCT 2.2 is supported on Symbian^3
- and earlier. RVCT 4.0 b902 or later is required for Symbian Belle.
-
- \section1 Starting External Processes
-
- Qt Creator executes external processes to accomplish tasks such as building
- and running applications. To execute the processes, Qt Creator uses shell
- commands that are native to the system. It constructs the commands from
- an executable name and optional command line arguments.
-
- The executable name is specified in the executable fields: \gui qmake,
- \gui Make, \gui Command, or \gui Executable. It is either derived from the
- project or specified manually. When you specify executables manually, you
- can reference environment variables and Qt Creator variables. However, no
- quoting rules
- apply.
-
- You can specify command-line arguments in the arguments fields: \gui {Additional
- arguments}, \gui {Command arguments}, \gui {Make arguments}, or \gui Arguments.
- You can create shell command lines that can contain redirection and other
- advanced constructs. However, some more complex use cases, such as piping
- test data into the application being tested or grouping commands, are not
- supported because the value of the \gui Executable field is always placed
- first when constructing the command.
-
- \section2 Using Environment Variables
-
- You can use any environment variables as values in the fields. For a list
- of variable names, click \gui {Build Environment > Details} in the
- \gui {Build Settings}. Environment variables are referenced using the native
- syntax: $VARNAME or ${VARNAME} on Unix and %VARNAME% on Windows.
-
- \section2 Using Qt Creator Variables
-
- You can use Qt Creator variables in arguments, executable paths, and working
- directories.
- The variables take care of quoting their expansions, so you do not need to
- put them in quotes.
-
- The following Qt Creator variables are available:
-
- \list
-
- \o %{buildDir}
-
- \o %{sourceDir}
-
- \endlist
-
- \section1 Build Steps
-
- The build system of Qt Creator is built on qmake and make. In
- \gui{Build Steps} you can change the settings for qmake and make. Qt
- Creator runs the make command using the Qt version defined for the current
- build configuration.
-
- \image qtcreator-build-steps.png "Build steps"
-
- To override the shell command that Qt Creator constructs by default, remove
- the build step and add a custom build step that specifies another shell
- command.
-
- \section2 Adding Custom Build Steps
-
- To add custom steps to the build settings, select \gui {Add Build Step >
- Custom Process Step}.
-
- By default, custom steps are disabled. To activate a custom step, select
- the \gui{Enable custom process step} check-box.
-
- \image qtcreator-build-steps-custom.png "Custom Process Step"
-
- \section1 Clean Steps
-
- You can use the cleaning process to remove intermediate files. This process
- might help you to fix obscure issues during the process of building a
- project.
-
- \image qtcreator-clean-steps.png "Clean steps"
-
- You can define the cleaning steps for your builds in the \gui{Clean Steps}:
- \list
- \o To add a clean step using make or a custom process, click
- \gui{Add Clean Step} and select the type of step you want to add.
-
- By default, custom steps are disabled. To activate a custom step,
- select the \gui{Enable custom process step} check-box.
- \o To remove a clean step, click \gui{Remove Item}.
- \o To change the order of steps, click
- \inlineimage qtcreator-movestep.png
- .
- \endlist
-
- \section1 Build Environment
-
- You can specify the environment you want to use for building in the
- \bold{Build Environment} section. By default, the environment in which Qt
- Creator was started is used and modified to include the Qt version.
- Depending on the selected Qt version, Qt Creator automatically sets the
- necessary environment variables. You can edit existing environment
- variables or add, reset and unset new variables based on your project
- requirements.
-
- \image qtcreator-build-environment.png "Build Environment"
-
- \note The changes are stored in the local project specific \c{.pro.user}
- file. Therefore, they are not suitable for sharing between developers or
- development PCs. To share settings, incorporate them into the build system.
- For example, if you use qmake, make the changes in the \c{.pro} file.
-
-
- \section2 Clearing the System Environment
-
- To build with a clean system environment, select the \gui {Clear system
- environment} check box. Qt Creator discards the current environment, and
- populates a clean system environment with the environment variables that the
- compilers and tools need. Therefore, the environment is never totally empty,
- even after you clear it.
-
-*/
-
-
-/*!
- \contentspage index.html
- \previouspage creator-tool-chains.html
- \page creator-run-settings.html
- \nextpage creator-editor-settings.html
-
- \title Specifying Run Settings
-
- Qt Creator automatically creates run configurations for your project.
- To view and modify the settings, select \gui {Projects > Run}.
-
- The settings to specify depend on the type of the project: Qt project
- or Qt Quick project, and on the target for the project.
-
- Click \gui Add to add run settings for a project and \gui Remove to remove
- the current settings.
-
- \section1 Specifying Run Settings for qmake Projects
-
- The run configurations for qmake projects derive their executable from the parsed .pro
- files.
- For more information on how the commands are constructed, see
- \l{Starting External Processes}.
-
- \section2 Specifying Run Settings for Desktop Targets
-
- You can specify command line arguments to be passed to the executable
- and the working directory to use. The working directory defaults to
- the directory of the build result.
-
- For console applications, check the \gui{Run in Terminal} check box.
- If you need to run with special environment variables set up, you
- also do it in the run configuration settings.
-
- \image qtcreator-pprunsettings.png
-
- You can also create custom executable run configurations where you
- can set the executable to be run. For more information, see
- \l{Specifying a Custom Executable to Run}.
-
- \section2 Specifying Run Settings for Symbian Devices
-
- Qt Creator automatically detects Symbian devices that are connected to
- the development PC with a USB cable.
- If only one device is detected, the application is deployed to it
- and run on it. If multiple devices are connected to the PC,
- make sure that the correct device is selected in the
- \gui {Symbian Device} run settings for your project.
-
- You can also pass command line arguments to your application on the device.
- Press the \gui{Device info button} to get more information about the selected
- device, such as the CPU type and the running debugging agent version.
-
- \image qtcreator-symbian-run-settings.png "Run settings for Symbian devices"
-
- To use the CODA debugging agent over a WLAN connection, enter the WLAN
- address of the device and the port number to use, separated by a colon (:),
- in the \gui WLAN field. For example: 192.167.0.100:1534
-
- When you deploy the application for the \gui{Symbian Device} target, Qt
- Creator generates a Symbian installation system (SIS) file in the project folder
- and copies it to the device that is connected to the development PC.
- If no device is connected, you must remove the \gui {Deploy SIS Package} step,
- to create the package. Click \gui {Remove Item} to skip the step.
-
- \image qtcreator-remove-deploy-step.png "Removing deploy steps"
-
- When you are ready to publish the application on Ovi Store or some other
- channel, you must make sure that the SIS file meets the requirements for
- publishing and installing applications on Symbian devices. For more information,
- see \l{Deploying Applications to Symbian Devices}.
-
- \section2 Specifying Run Settings for Maemo and MeeGo Harmattan Devices
-
- To run an application on a Maemo or MeeGo Harmattan device, create and
- select a device configuration in the Maemo 5 or Harmattan run settings for
- your project.
- You can also pass command line arguments to your application.
-
- \image qtcreator-screenshot-run-settings-maemo.png "Run settings for Maemo devices"
-
- To run and debug applications on Maemo or MeeGo Harmattan devices, you must
- create connections
- from the development PC to the devices. Click \gui {Manage device
- configurations} to create connections. For more information, see
- \l{Configuring Connections to Maemo Devices} and
- \l{Configuring Connections to Harmattan Devices}.
-
- When you run the application on the \gui{Maemo5} or \gui Harmattan target,
- Qt Creator generates
- a Debian installation package in the build directory by default. You can deliver
- the installation package to users for installation on devices that are of
- the same type and run the same firmware as the connected device. For more
- information, see
- \l{Deploying Applications to Maemo or MeeGo Harmattan Devices}.
-
- \section2 Specifying Run Settings for Generic Linux Devices
-
- To run an application on a generic Linux device (without MADDE support),
- create and select a device configuration in the Desktop run settings for
- your project. You can also pass command line arguments to your application.
-
- \image qtcreator-run-settings-linux-devices.png "Run settings for Generic Linux devices"
-
- In addition, you must create a connection from the development PC to the
- device. Click \gui {Manage device configurations} to create connections.
- For more information, see \l {Connecting Generic Linux Devices}.
-
- When you run the application on the \gui Desktop target, Qt Creator
- generates an installation package in the build directory. The name of the
- directory is displayed in the \gui {Create tarball} step. Qt Creator copies
- the tarball to devices by using the SSH file transfer protocol (SFTP) and
- extracts it.
-
- \section1 Specifying a Custom Executable to Run
-
- If you use CMake or the generic project type in Qt Creator, or want
- to run a custom desktop executable, create a \gui {Custom Executable}
- run configuration for your project. For example, when working on a library,
- you can run a test application that links against the library.
-
- Specify the executable to run, command line arguments, working directory,
- and environment variables to use.
-
- \image qmldesigner-run-custom-exe.png "Run settings for custom executables"
-
- \section1 Specifying Run Settings for Qt Quick UI Projects
-
- You can specify run settings for the \gui Desktop target:
-
- \list
-
- \o In the \gui {Qt version} field, select a Qt version that has support
- for QML.
-
- \o In the \gui Arguments field, you can specify command line arguments
- to be passed to the executable.
-
- \o In the \gui {Main QML file}, select the file that \QQV will be
- started with.
-
- \o In the \gui Debugger group, select the languages to debug:
- \gui{C++} and \gui QML. \gui {Debug port} is the port to access \QQV.
- You can use any free port in the registered port range.
- For more information, see \l{Debugging Qt Quick Projects}.
-
- \endlist
-
- \note Opening a socket at a well-known port presents a security risk. Anyone
- on the Internet could connect to the application that you are debugging and
- execute any JavaScript functions. Therefore, you must make sure that the port
- is properly protected by a firewall.
-
- \image qmldesigner-run-settings.png "Run settings for Qt Quick UI projects"
-
-
-*/
-
-
-/*!
- \contentspage index.html
- \previouspage creator-deployment-symbian.html
- \page creator-deployment-maemo.html
- \nextpage creator-publishing-to-maemo-extras.html
-
- \title Deploying Applications to Maemo or MeeGo Harmattan Devices
-
- You can specify settings for deploying applications to Maemo 5 and MeeGo
- Harmattan devices in the
- project .pro file. You can view the settings in the \gui {Run Settings}.
-
- \image qtcreator-maemo-deployment.png "Deploy to device"
-
- The files to be installed are listed in the
- \gui {Deploy to Device} step, the \gui {Files to install for subproject}
- field. The
- \gui {Local File Path} field displays the location of the file on the development
- PC. The \gui {Remote Directory} field displays the folder where the file is installed on
- the device.
- Text in red color indicates that the information is missing. Select the
- text to edit it and add the missing information.
-
- You can use desktop files to display icons on the home screen of the
- device. To add desktop files to the project file, select \gui {Add Desktop
- File}. To specify the icon file to display, select \gui {Add Launcher
- Icon...}. To remove desktop files and icons, delete the definitions from
- the project file.
-
- If you develop your own libraries, Qt Creator needs to be able to find
- them when you compile projects depending on them. When you install MADDE,
- an instance of the device file
- system, called sysroot, is installed to the development PC. Libraries are copied to
- sysroot if the \gui {Also deploy to sysroot} check box is selected.
-
- \section1 Creating Debian Installation Packages
-
- When you run the application on the \gui{Maemo5} or \gui Harmattan target,
- Qt Creator generates
- a Debian installation package in the build directory by default. You can deliver
- the installation package to users for installation on devices that are of
- the same type and run the same firmware as the connected device.
-
- \image qtcreator-maemo-deb-package.png "Create installation package"
-
- The name of the installation package is displayed in the \gui {Package name}
- field in the \gui {Create Package} step. You can change the version number
- in the \gui {Package version} field.
-
- You can specify information that users see on a delivery channel, such as
- Ovi Store or Maemo.org. You can specify a short description of the
- application, package
- name, and application icon.
-
- The Debian control file contains an application icon in encoded form. To add the
- application icon to the file, select it in the \gui {Icon to be displayed
- in Package Manager} field.
- For more information about icon files and adding them manually, see
- \l{ http://wiki.maemo.org/Packaging#Displaying_an_icon_in_the_Application_Manager_next_to_your_package}{Displaying an icon in the Application Manager next to your package}.
-
- \note Qt Creator automates this process for you.
-
- Qt Creator provides templates for a set of files that must be included
- in Debian packages. When you create a \gui Maemo5 or \gui Harmattan target
- for a project, Qt Creator
- asks whether packaging files are to be added to the project and to version
- control. If you plan to edit the packaging files, add them to version
- control.
-
- To edit the files, select a file in \gui {Adapt Debian
- file} and click \gui Edit. The file opens in the text editor.
-
-*/
-
-
-/*!
- \contentspage index.html
- \previouspage creator-deployment-maemo.html
- \page creator-publishing-to-maemo-extras.html
- \nextpage creator-publish-ovi.html
-
- \title Publishing Maemo Applications to Extras-devel
-
- Extras is the primary repository for Maemo applications where most
- community software can be found. You can browse the applications available
- in Extras at \l{http://maemo.org/downloads/Maemo5/}{Maemo Downloads}.
-
- You can publish both free and commercial applications to Extras. Free
- applications must be open source and pass through a QA process.
- Commercial applications are usually closed, binary only, and the publisher
- is responsible for assuring their quality and security.
-
- You can upload free applications as Debian packages to
- \l{http://wiki.maemo.org/Extras-devel}{Extras-devel} at Maemo.org to share
- new updates to your application and to start the community QA process.
- You need a \l{https://garage.maemo.org/}{Garage} account for the uploads,
- but the package itself does not need to be hosted in the Garage.
-
- You can use the \gui {Publish for Fremantle Extras-devel Free Repository}
- wizard to create a source archive and, optionally, upload it to a build
- server for compiling and packaging. The package is then moved to the
- Extras-devel repository. From there on, you must follow the standard
- Maemo processes to get the application published to Extras.
-
- The wizard checks that the package contains all the information that is
- required to publish applications on Extras: package description and
- Package Manager icon. For more information about entering this information,
- see \l{Creating Debian Installation Packages}.
-
- To use the publishing wizard:
-
- \list 1
-
- \o Select the \gui {Maemo5} build target for your project.
-
- \o Choose \gui {Build > Publish Project}.
-
- \o Select \gui {Publish for Fremantle Extras-devel Free Repository},
- and then select \gui {Start Wizard}.
-
- \o Select the Qt version and device type to build against and click
- \gui Next.
-
- To create a source archive without uploading it to the build
- server, select the \gui {Only create source package, do not upload}
- check box.
-
- \o In the \gui {Garage account name} field, enter your login name, or
- select \gui {Get an account} to create a new account.
-
- \image qtcreator-publish-maemo-extras.png "Upload Settings dialog"
-
- You can also select \gui {Request upload rights} to use the Maemo
- Extras Assistant to validate your Garage account.
-
- \o Select \gui Commit to publish the application.
-
- \endlist
-
-*/
-
-
-/*!
- \contentspage index.html
- \previouspage creator-running-valgrind-remotely.html
- \page creator-deployment.html
- \nextpage creator-deployment-symbian.html
-
- \title Deploying Applications to Mobile Devices
-
- Deploy configurations in the \gui Project mode \gui {Run Settings} handle
- the packaging of the application as an executable and copying it to a
- location you want to run the executable at. The files can be copied to a location
- in the file system of the development PC or a mobile device.
-
- When you are ready to publish the application on Ovi Store or some other
- channel, you must make sure that the installation file meets the requirements for
- publishing and installing applications to Symbian or Maemo devices. The following
- sections describe the steps that you have to take to create installation packages
- for Symbian, Maemo, or MeeGo Harmattan devices and for publishing on Ovi
- Store:
-
-
- \list
- \o \l{Deploying Applications to Symbian Devices}
- \o \l{Deploying Applications to Maemo or MeeGo Harmattan Devices}
- \o \l{Publishing Maemo Applications to Extras-devel}
- \o \l{Publishing Applications to Ovi Store}
- \o \l{Building with Remote Compiler}
- \endlist
-
-*/
-
-
-/*!
- \contentspage index.html
- \previouspage creator-deployment.html
- \page creator-deployment-symbian.html
- \nextpage creator-deployment-maemo.html
-
- \title Deploying Applications to Symbian Devices
-
- This section describes how to create installation packages that meet the
- requirements for installing applications to Symbian devices.
-
- \section1 Creating SIS Files
-
- When you deploy the application for the \gui{Symbian Device} target, Qt
- Creator automatically generates a Symbian installation system (SIS) file
- in the project folder. You can deliver the installation file to users for
- installation on Symbian devices.
-
- The name of the installation file is displayed in the \gui {Installation file}
- field in the \gui {Run Settings}. In the \gui {Installation drive} field, select the drive on the device
- to install the application to. To suppress notifications on the device during the
- installation, select the \gui {Silent installation} check box. If the silent
- installation fails, Qt Creator attempts installation again, this time displaying
- notifications and error messages.
-
- To create a SIS package without copying it to the device (for example, to submit it
- to \e {Application Signing Services for Ovi Store} or \e {Symbian Signed}),
- create a deploy configuration that contains only the
- \gui {Create SIS Package} step.
-
- \image qtcreator-run-settings-create.png "Create SIS Package step"
-
-
- \section1 Signing SIS Files
-
- Only installation files signed with a certificate and private key are
- allowed to be installed onto Symbian devices. By default, Qt Creator
- self-signs the installation file. This self-signing allows you to install
- the application on a mobile device but places limits on what you can do
- with the installation file, including:
- \list
- \o Self-signed applications cannot access the more sensitive
- \l{Capabilities and Signing}{capabilities} of the mobile device.
- \o Security warnings will be displayed when you install the self-signed
- application on a mobile device.
- \o Self-signed applications cannot be published to Ovi
- Store.
- \endlist
-
- To get around these limitations, you need to go through the Symbian Signed
- or Application Signing Services for Ovi Store. The Symbian Signed organisation
- manages a public key
- infrastructure to provide public authentication of the information in the
- application signing certificates. Their security partner can validate your
- certificate and give you a Publisher ID. Then, when you sign an
- application, other people can be confident that the information in your
- certificate is correct and that the application does actually come from you.
-
- Application Signing Services for Ovi Store is a variant of the Symbian
- Signed certification provided by Ovi
- Publishing. It is limited to the Basic and System capability sets
- (Express Signing). Participants can submit an unsigned SIS file to Ovi
- Publishing for signing. For more information about how
- to participate, see
- \l {http://www.developer.nokia.com/Community/Wiki/Guide_to_Publishing_Qt_Applications_to_the_Ovi_Store}{Guide to Publishing Qt Applications to the Ovi Store}.
-
- There are also options that do not require you to get a Publisher ID. For
- more detail about how the Symbian Signed process works, see
- \l{https://www.symbiansigned.com}{Symbian Signed}.
-
- When you have your own certificate and private key, you can specify them in
- the \gui{Create SIS Package} step in the \gui {Run Settings}.
-
- \image qtcreator-qt4-symbian-signing.png
-
-
- If your private key is protected by a passphrase, Qt Creator asks you for the
- passphrase when the package is signed and offers to store it. However, storing
- passphrases in Qt Creator presents a security risk. To make Qt Creator forget
- all saved passphrases, click \gui {Reset Passphrases}.
-
- \section2 Capabilities and Signing
-
- Capabilities allow the Symbian platform to control access by applications to
- the functionality provided by the platform APIs. Access to capabilities is
- determined by the device configuration and how the application has been signed.
-
- Symbian Signed offers the following signing options depending on the
- capabilities that the application accesses:
-
- \list
-
- \o \bold{Express signed} for applications that access only user and system
- capabilities.
-
- \o \bold{Certified signed} for applications that access also restricted or
- device manufacturer capabilities.
-
- \note You need to request the rights to access device manufacturer
- capabilities from the manufacturer.
-
- \endlist
-
- For more information about how to choose the appropriate signing option and
- how you can check which capabilities you need, see
- \l{https://www.symbiansigned.com}{Symbian Signed}
- and
- \l{http://doc.qt.nokia.com/4.7/platform-notes-symbian.html#required-capabilities}{Required Capabilities for Qt Applications}.
-
- For more information on how to define capabilities for a project, see
- \l{http://doc.qt.nokia.com/4.7/qmake-platform-notes.html#capabilities}{Capabilities}.
-
- \note In Qt 4.7.1 and later, if you select the \gui {Self-signed certificate}
- option, the SIS generation process checks that the package can be self-signed.
- If problems are found, it attempts to fix the package. If fixes cannot be made,
- a message appears in the \gui {Compile Output} view.
-
- The following modifications can be made:
-
- \list
-
- \o Package UID is changed to an UID from the unprotected range (if it was
- from the protected range).
-
- \o Vendor ID is set to zero on all binaries included in the package file.
-
- \o All restricted and device manufacturer capabilities are removed from all
- libraries included in the package file.
-
- \endlist
-
- The application UID or capabilities used in executables (.exe) cannot be changed,
- because that would break the application. If the executables use protected UIDs
- or restricted or device manufacturer capabilities, signing fails and an error
- message appears in the \gui {Compile Output} view.
-
- \section1 Creating Smart Installer for Symbian Packages
-
- You can run Qt applications on Symbian devices if the software that Qt
- applications require (typically Qt, Qt Mobility, QtWebkit, and Open C) is
- installed on the device. On Symbian^3 and later devices, some version of Qt
- is pre-installed. On earlier devices, you must install the modules that Qt
- applications require. Nokia Smart Installer for Symbian makes it easier
- for users to install Qt applications to Symbian phones by checking whether the device contains
- the necessary software and by installing the missing pieces.
-
- For this to work, the Nokia Smart Installer must be packaged with the Qt application. The
- application SIS file must first be Symbian Signed or signed by the Application
- Signing Services for Ovi Store. The capabilities used in the applications
- determine, which signing option must be selected. The wrapper package must be signed using
- either the same option or a more extensive option than the application SIS.
-
- \note If you use the Application Signing Services for Ovi Store, you can submit an unsigned
- wrapper package to Ovi Publishing. For more information, see
- \l{Publishing Applications to Ovi Store}.
-
- You can either install the Nokia Smart Installer for Symbian as part of
- the \QSDK, or download and install it from the
- \l{http://www.developer.nokia.com/Community/Wiki/Nokia_Smart_Installer_for_Symbian}{Nokia Smart Installer for Symbian}
- wiki.
-
- To package Nokia Smart Installer with the application, select the \gui {Create Smart Installer
- package} check box. This ensures that up-to-date and appropriate versions of Qt and its
- dependencies are installed on devices. Further, it reduces the file size of the application you
- publish, because you do not have to deliver the required libraries.
-
- Nokia has reserved the following UIDs to be used with Nokia Smart Installer for Symbian:
-
- \list
-
- \o 0xA000D7CE for self-signed applications
- \o 0x2002CCCF for Ovi Store or Symbian Signed packages
-
- \endlist
-
- \section2 Creating Self-signed Smart Installer Packages
-
- To create a self-signed Nokia Smart Installer for Symbian wrapped .sis file,
- you must use an UID from the unprotected UID range, provided by Symbian Signed
- and the wrapper package UID value 0xA000D7CE. If you used the Qt Creator project
- wizard to create the project, this wrapper package UID is used by default.
-
- \list 1
-
- \o Make sure that the source directory is clean. For example, if you use Git,
- enter the following command:
-
- \c {git clean -dfx}
-
- \o Click \gui Projects to edit the \gui {Build Settings} for the
- \gui {Symbian Device} target.
-
- \o Select the \gui Release configuration.
-
- \o Open the \gui {Run Settings}.
-
- \o In the \gui {Create SIS Package} step, select \gui {Self-signed certificate}.
-
- \o In the \gui {Deploy SIS Package} step, click \gui {Remove Item} to
- skip the step of copying the SIS file to a device. The SIS file is created
- in the project folder.
-
- \image qtcreator-remove-deploy-step.png "Removing deploy steps"
-
- \o To package Nokia Smart Installer for Symbian with the application, select
- the \gui {Create Smart Installer package} check box.
-
- \o Edit the project .pro file to use the correct UIDs for the application and
- the wrapper package, as illustrated by the following code snippet:
-
- \code
- symbian {
- TARGET.UID3 = 0xE4DE5D27
- DEPLOYMENT.installer_header=0xA000D7CE
-
- vendorinfo = \
- "%{\"CustomVendor-EN\"}" \
- ":\"CustomVendor\""
-
- my_deployment.pkg_prerules = vendorinfo
- DEPLOYMENT += my_deployment
- }
- \endcode
-
- \o Choose \gui {Build > Run Project}.
-
- \endlist
-
- Qt Creator automatically generates a wrapper package in the project folder.
-
- \section2 Creating Symbian Signed Smart Installer Packages
-
- If the application uses functions that require advanced capabilities (AllFiles,
- DRM, TCB, CommDD, DiskAdmin, NetworkControl, MultimediaDD), you must use the
- standard Symbian Signed process to have the application Symbian Signed. Depending
- on the capabilities used, you may use either the Express Signed or the Certified
- Signed path, or the manufacturer-specific channel (for AllFiles, DRM, and TCB).
-
- \list 1
-
- \o Make sure that the source directory is clean. For example, if you use Git,
- enter the following command:
-
- \c {git clean -dfx}
-
- \o Click \gui Projects to edit the \gui {Build Settings} for the
- \gui {Symbian Device} target.
-
- \o Select the \gui Release configuration.
-
- \o Open the \gui {Run Settings}.
-
- \o In the \gui {Create SIS Package} step, specify the developer certificate
- and key in the \gui {Custom certificate} and \gui {Key file} fields.
-
- \o In the \gui {Deploy SIS Package} step, click \gui {Remove Item} to
- skip the step of copying the SIS file to a device. The SIS file is created
- in the project folder.
-
- \o Edit the project .pro file to use the correct UIDs and vendor information
- for the application, as illustrated by the following code snippet:
-
- \code
- symbian {
- TARGET.UID3 = 0x2000D7D1
- DEPLOYMENT.installer_header=0x2002CCCF
-
- vendorinfo = \
- "%{\"CustomVendor-EN\"}" \
- ":\"CustomVendor\""
-
- my_deployment.pkg_prerules = vendorinfo
- DEPLOYMENT += my_deployment
- }
- \endcode
-
- \o Choose \gui {Build > Run Project}.
-
- \o Submit the created .sis file to Symbian Signed for certification.
-
- \note Ensure that your application complies with the Symbian Signed
- Test Criteria before submitting the file for certification. Also, if the file is
- intended for Ovi Store publishing, verify that the application complies with Ovi
- Store publishing requirements.
-
- \o After receiving the .sis file from Symbian Signed, copy it over the old
- application.sis.
-
- \note The instructions below assume that you have installed \QSDK.
-
- \o To package Nokia Smart Installer for Symbian with the application, choose
- \gui {Start > Qt SDK > Symbian > Qt for Symbian Command Prompt}
- to open the Qt command line environment.
-
- \o Change to the project directory. For example:
-
- \c{cd C:\Sources\Application}
-
- \o To create a Smart Installer wrapper package, enter the following
- command:
-
- \c {C:\Sources\Application> make ok_installer_sis QT_SIS_CERTIFICATE=publisherid.cer QT_SIS_KEY=publisherid.key}
-
- \o Submit the created wrapped .sis file, application_installer.sis, to
- Symbian Signed. Express Signed is a suitable signing option for the wrapper
- package. The capabilities used in the application do not play a role here,
- because the wrapper package is already signed.
-
- \endlist
-
- Qt Creator automatically generates a wrapper package in the project folder.
-
- \note Ensure that your application complies with the requirements before submitting
- the file to Ovi Store.
-
- For more information about the qmake DEPLOYMENT variable, see
- \l{http://doc.qt.nokia.com/4.7/qmake-variable-reference.html#deployment}{qmake Variable Reference}.
-
- For more information about the Nokia Smart Installer, see the
- \l{http://doc.qt.nokia.com/smart-installer/index.html}{Nokia Smart Installer for Symbian Manual}.
-
- Note: Nokia Smart Installer for Symbian is only available on Windows.
-
- \section1 Application UID
-
- A UID is a globally unique identifier that is used to
- uniquely identify, for example, an object or file type. In Symbian development,
- objects are identified by compound identifiers that are constructed from three
- UIDs, namely UID1, UID2, and UID3. UID1 and UID2 specify the category of an
- object, whereas UID3 identifies a particular object, such as an application.
-
- When you create a \gui {Mobile Qt Application}, Qt Creator adds a UID3 suitable for
- development and debugging automatically to the application .pro file. However, to
- distribute your application and get it Symbian Signed, you must apply for a UID
- from Symbian Signed, which manages the allocation of UIDs. You can request UIDs either one
- at a time or as preallocated blocks on the \l{https://www.symbiansigned.com/app/page}{Symbian Signed}
- web site.
-
- If you use the Ovi Signed process, Ovi Publisher Support allocates the UID for you.
-
- Replace the testing UID with the distribution UID in the .pro file before you
- build the final installation package. For more information, see
- \l{http://doc.qt.nokia.com/4.7/qmake-platform-notes.html#unique-identifiers}{Unique Identifiers}.
-
-*/
-
-
-/*!
- \contentspage index.html
- \previouspage creator-publishing-to-maemo-extras.html
- \page creator-publish-ovi.html
- \nextpage creator-remote-compiler.html
-
- \title Publishing Applications to Ovi Store
-
- Ovi Store is the global content market of Nokia, which reaches millions of
- people worldwide. Consumers can access Ovi Store through either of these
- platforms:
-
- \list
-
- \o Ovi Store applications on mobile devices
-
- \o Web browsers on desktop computers, laptops, netbooks, and tablets
-
- \endlist
-
- Consumers have access to a wide selection of content and can download
- content in a few easy clicks.
-
- The process and requirements to publish Qt applications to Ovi Store are
- described in the
- \l {http://www.developer.nokia.com/Community/Wiki/Guide_to_Publishing_Qt_Applications_to_the_Ovi_Store}{Guide to Publishing Qt Applications to the Ovi Store} wiki.
-
- This section describes how to
- generate installation packages that
- you can publish to Ovi Store.
-
- \section1 Publishing Qt Content for Symbian Devices
-
- You can use the \e {Application Signing Services for Ovi Store} to get your
- application Express Signed for
- free by Nokia. Make sure to use the \l{Application UID}{application UID} that you
- receive from Ovi Publisher Support.
-
- The \gui {Publish Qt Symbian Applications to Ovi Store} wizard allows you
- to check that your application can be
- published on Ovi Store. It checks that the application UID, vendor name,
- and the capabilities used meet the Ovi Publishing criteria.
-
- If you use Symbian Signed UIDs or the application uses functions that
- require advanced
- \l{Capabilities and Signing}{capabilities}, you must
- use the standard Symbian Signed process to have the application Symbian Signed
- (using the Certified Signed path or the manufacturer-specific channel).
- For more information, see \l{Deploying Applications to Symbian Devices}.
-
- To use the publishing wizard:
-
- \list 1
-
- \o Select \gui Projects to select the Qt version to build the
- application. For more information, see
- \l{Selecting Qt Versions in Qt Creator}.
-
- \o Select the \gui {Symbian Device} build target for your project.
-
- \o Choose \gui {Build > Publish Project}.
-
- \o Select \gui {Publish Qt Symbian Applications to Ovi Store}, and then
- select \gui {Start Wizard}.
-
- \o Select the Qt version and device type to build against and click
- \gui Next. We recommend that you select a release configuration.
-
- \o The wizard checks the information in the project file against the
- Ovi Publishing criteria and indicates possible problems. You can fix
- some of the problems in the wizard.
-
- \image qtcreator-publishing-wizard-symbian.png "Project File Checks dialog"
-
- \o Select \gui Commit to save changes and create the .sis file. The
- .sis file is packaged with Nokia Smart Installer for Symbian.
-
- \o Choose \gui {Open Containing Folder} to open the folder where the
- .sis file was created.
-
- \o Submit the created .sis file to Ovi Publishing as a Qt Content item.
-
- \note You cannot use this .sis file for testing.
-
- \endlist
-
- \note After you change the application UID, you must use the developer
- certificate-key pair that you receive from Ovi Publisher Support for testing
- the application on devices. The following error message is displayed on the
- device if you use UIDs from the trusted range (0x2xxxxxxx) in a self-signed
- application: \gui {Unable to install a trusted application from a trusted
- supplier.} For more
- information, see \l{http://www.developer.nokia.com/Community/Wiki/UID}{UID}.
-
- If you try to use more capabilites than the certificate permits, the
- following error message is displayed on the device: \gui {Requested
- application access not granted.} For example, if you try to install a
- self-signed application that uses a system capability.
-
-
-
- \section1 Publishing Qt Content for Maemo Devices
-
- The applications that you publish on Ovi Store, must meet the testing criteria
- listed in
- \l{http://www.developer.nokia.com/info/sw.nokia.com/id/9cd1eb18-821b-4228-a0a3-36b049c5d608/Maemo_5_Application_OVI_Store_Entry_Requirements.pdf.html}
- {Maemo 5 Applications: Ovi Store Entry Requirements}.
-
- Make sure that your application passes the following most commonly
- failed test cases:
-
- \list
-
- \o Package filename must include the application name and version
- number using three digits. For example: myapplication_1_0_1.deb
-
- \o Application files must be installed to the opt folder on the ext3
- partition.
-
- \o Debian packages must be given the category user/hidden.
-
- \o Application cannot crash or hang during use.
-
- \o The application must handle different memory situations correctly.
-
- \endlist
-
- You set the application name and installation folder in the
- \gui {Run Settings} for the project. For more information, see
- \l{Deploying Applications to Maemo or MeeGo Harmattan Devices}. Qt Creator
- specifies the correct
- category settings by default when it creates the Debian directory and
- the necessary files.
-
- You can test the application on Qt Simulator and Maemo emulator to make
- sure that it does not crash or hang and to check how it handles different
- memory situations. Before you submit the application to Ovi Publishing, you
- must also fully test it on a Maemo device.
-
- \section1 Publishing Qt Content for MeeGo Harmattan Devices
-
- You cannot publish applications that are built with the beta version of the
- MeeGo Harmattan tool chain to Ovi Store.
-
- However, you can prepare for publishing by making sure that your application
- meets the
- \l{http://www.developer.nokia.com/info/sw.nokia.com/id/44affcd1-ceba-4aca-8b65-670ce2cbbd1e/MeeGo_1_2_Harmattan_Applications_Ovi_Store_Entry_Requirements.html}
- {MeeGo 1.2 Harmattan Applications: Ovi Store Entry Requirements}.
-
-*/
-
-/*!
- \contentspage index.html
- \previouspage creator-run-settings.html
- \page creator-editor-settings.html
- \nextpage creator-code-style-settings.html
-
- \title Specifying Editor Settings
-
- Qt Creator uses the \l{Editing MIME Types}{MIME type} of the file to
- determine which mode and editor to use for opening the file. For example,
- Qt Creator opens .txt files in \gui Edit mode in the text editor.
-
- You can configure the text editor according to your needs. You can specify
- editor behavior either globally for all projects or separately for each
- project. To specify global editor behavior, select \gui {Tools > Options...
- > Text Editor > Behavior}.
-
- To configure the text editor behavior for the current project:
-
- \list
-
- \o Select \gui {Projects > Editor Settings}.
-
- \o Deselect the \gui {Use global settings} check box.
-
- \o Specify text editor settings for the project.
-
- \endlist
-
- \image qtcreator-editor-settings.png "Editor Settings view"
-
- For more information about the settings, see:
-
- \list
-
- \o \l{Indenting Code}
-
- \o \l{File Encoding}
-
- \o \l{Moving to Symbol Definition or Declaration}
-
- \o \l{Configuring Fonts}
-
- \endlist
-
-*/
-
-
-/*!
- \contentspage index.html
- \previouspage creator-editor-settings.html
- \page creator-code-style-settings.html
- \nextpage creator-build-dependencies.html
-
- \title Specifying Code Style Settings
-
- Qt Creator uses the \l{Editing MIME Types}{MIME type} of the file to
- determine which mode and editor to use for opening the file.
- Qt Creator opens C++ files in \gui Edit mode in the C++ code editor and
- QML files in the Qt Quick editor.
-
- You can configure the code style according to your needs. You can specify
- code style either globally for all projects or separately for each
- project. To specify global code style for C++ files, select \gui {Tools >
- Options... > C++}.
-
- To specify global code style for QML files, select \gui {Tools > Options...
- > Qt Quick}.
-
- To configure the editor behavior for the current project:
-
- \list
-
- \o Select \gui {Projects > Code Style Settings}.
-
- \o In the \gui Language field, select \gui C++ or \gui Qt Quick.
-
- \o Deselect the \gui {Use global settings} check box.
-
- \o In the \gui Settings field, select \gui Custom.
-
- \o Specify code style settings for the project. Only \gui General
- settings are available for QML files.
-
- \endlist
-
- \image qtcreator-code-style-settings.png "Code Style Settings view"
-
- For more information about the settings, see \l{Indenting Code}.
-
-*/
-
-
-/*!
- \contentspage index.html
- \previouspage creator-code-style-settings.html
- \page creator-build-dependencies.html
- \nextpage creator-debugging.html
-
- \title Specifying Dependencies
-
- If you have multiple projects loaded in a session, you can define the
- order in which they are built. For example, if project A depends on project
- B, project B must be built first.
-
- \note The build order is stored as a property of a session, not a project.
- You must open the session for these settings to take effect. For more
- information, see \l{Managing Sessions}.
-
- \image qtcreator-build-dependencies.png "Dependencies view"
-
- To define the build order of projects within a session:
- \list 1
- \o In \gui Projects, select a project.
- \o Click \gui Dependencies.
- \o Select projects that must be built before the current project is
- built.
- \endlist
-
- Qt Creator calculates the build order based on the dependencies that you
- specify for the projects loaded in the session.
-
- \note You cannot use this view to specify subprojects for projects.
- For more information on how to add subprojects, see \l{Adding Subprojects
- to Projects}.
-
-*/
-
-
-/*!
- \contentspage index.html
- \previouspage creator-quick-tour.html
- \page creator-getting-started.html
- \nextpage creator-build-example-application.html
-
- \title Getting Started
-
- This section contains examples that illustrate how to use Qt Creator
- to create, build, and run simple
- applications:
-
- \list
- \o \l{Building and Running an Example Application}
- \o \l{Creating a Qt Quick Application}
- \o \l{Creating a Qt Quick Application Using Qt Quick Components}
- \o \l{Creating a Qt Widget Based Application}
- \o \l{Creating a Qt Widget Based Mobile Application}
-
- \endlist
-
-*/
-
-
-/*!
- \contentspage index.html
- \previouspage creator-qml-application.html
- \page creator-qml-components-example.html
- \nextpage creator-writing-program.html
-
- \title Creating a Qt Quick Application Using Qt Quick Components
-
- \note To complete this tutorial, you must install the Qt Quick Components
- for Symbian and the Symbian^3 tool chain as part of the \QSDK. In addition,
- you must install the Qt Quick Components on the test device.
-
- This tutorial describes how to use Qt Creator to create a small Qt
- application, Battery Status, that uses the System Information
- Mobility API to fetch battery information from the device.
-
- \image qtcreator-symbian-components-example.png "Mobile example"
-
- The user interface for the application is designed using Qt Quick Components
- for Symbian. This enforces a platform look and feel for Symbian^3 devices.
-
- \section1 Creating the Project
-
- \list 1
-
- \o Select \gui{File > New File or Project > Qt Quick Project > Qt Quick
- Application > Choose}.
-
- \o In the \gui{Name} field, type \bold {BatteryStatus}.
-
- \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}.
-
- \o In the \gui {Application Type} dialog, select \gui {Qt Quick
- Components (Symbian Applications)}, and then click \gui{Next}.
-
- \o Select \gui {Symbian Device} and \gui {Qt Simulator} targets, and
- then click \gui{Next}.
-
- \note Targets are listed if you installed the appropriate
- development environment, for example, as part of the \QSDK. You can
- add targets later in the \gui Projects mode.
-
- \o Select \gui Next in the following dialogs to use the default
- settings.
-
- \note Qt Creator contains a default program icon and generates an
- \l{Application UID}, for testing the application on a device. You
- only need to change the icon and UID if you deliver the application
- for public use.
-
- \o Review the project settings, and click \gui{Finish} to create the
- project.
-
- \endlist
-
- Qt Creator generates the necessary files that contain boiler plate code. The
- wizard creates an application that uses
- \l{http://doc.qt.nokia.com/qt-components-symbian-1.0/qt-components-pages-and-navigation-overview.html}
- {page-based application navigation}.
-
- Modify the files as described in the following sections.
-
- \section1 Declaring the Qt Mobility API
-
- To use the Qt Mobility APIs or develop applications for Symbian
- devices, you must modify the .pro file to declare the Qt Mobility APIs
- that you use.
-
- This example uses the System Info API, so you must declare it, as
- illustrated by the following code snippet:
-
- \code
-
- CONFIG += mobility
- MOBILITY = systeminfo
-
- \endcode
-
- Each Mobility API has its corresponding value that you have to add
- as a value of MOBILITY to use the API. For a list of the APIs and the
- corresponding values that you can assign to MOBILITY, see the
- \l {http://doc.qt.nokia.com/qtmobility/quickstart.html}{Quickstart Example}.
-
- \section1 Adding Import Statements
-
- The wizard adds the import statements for Qt Quick and the Qt Quick
- Components for Symbian to the MainPage.qml file:
-
- \code
- import QtQuick 1.0
- import com.nokia.symbian 1.0
- \endcode
-
- To use the Qt Mobility APIs, you must add the import statements for the
- Qt Mobility APIs that you use. This example uses the System Info API, so you
- must import it, as illustrated by the following code snippet:
-
- \code
- import QtMobility.systeminfo 1.1
- \endcode
-
- Use the values as you can assign to MOBILITY also to construct import
- statements.
-
- \section1 Creating the Main View
-
- Qt Creator generates a default QML file that you can modify to create the
- main view of the application. It displays a progress bar and a text label
- that indicate the battery status.
-
- \list 1
-
- \o Click \gui Design to open MainPage.qml in \QMLD.
-
- \o In the \gui Navigator pane, select the \gui Text element to edit its
- properties in the \gui Properties pane.
-
- \o In the \gui Text field, change the text from \bold {Hello World!}
- to \gui {Battery status: 1%}.
-
- \o In the \gui Library view, \gui Items tab, select the
- \gui ProgressBar element, drag and drop it to the canvas, and edit
- its properties.
-
- \image qtcreator-symbian-components-example-ui.png "Qt Quick Components for Symbian"
-
- \list 1
-
- \o Click \gui {Layout}, and then click the top anchor button.
-
- \o In the \gui Target field, select \gui text1, to anchor the
- progress bar to the bottom of the text field.
-
- \o In the \gui Margin field, select 20.
-
- \o Click the horizontal anchor button, and select \gui text1 in
- the \gui Target field to anchor the progress bar
- horizontally to the text field.
-
- \o To check that the application can be built and run, select
- \gui {Qt Simulator} as the target and click the
- \inlineimage qtcreator-run.png
- button.
-
- \endlist
-
- \endlist
-
- \section1 Fetching Battery Status
-
- To fetch the battery status, open MainPage.qml in the code editor and add
- some code to it:
-
- \list 1
-
- \o Add an invisible
- \l{http://doc.qt.nokia.com/qtmobility/qml-deviceinfo.html}
- {DeviceInfo element} that contains two signals. The
- \l{http://doc.qt.nokia.com/4.7/qml-component.html#onCompleted-signal}
- {onCompleted} signal starts battery level notification when the
- component is initialized. The
- \l{http://doc.qt.nokia.com/qtmobility/qml-deviceinfo.html#batteryLevelChanged-signal}
- {batteryLevelChanged} signal is called when the battery level
- changes.
-
- \snippet examples/batterystatus/qml/BatteryStatus/MainPage.qml 0
-
- \o Set an expression as the value of the text property of the Text
- element to display the battery level as a percentage:
-
- \snippet examples/batterystatus/qml/BatteryStatus/MainPage.qml 1
-
- \o Set values for the ProgressBar element to display the battery level
- on the progress bar:
-
- \snippet examples/batterystatus/qml/BatteryStatus/MainPage.qml 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 Status application.
- Select \gui {Scripting > examples > runOutOfBattery.qs > Run Selected
- Script}.
-
- \image qtcreator-symbian-components-example-simulated.png "Mobile example in Qt Simulator"
-
- \section1 Testing on a Symbian Device
-
- You also need to test the application on real devices. Before you can
- start testing on Symbian devices, you must connect them to the development
- PC by using a USB cable and install the necessary software on them.
-
- \list 1
-
- \o Install Qt libraries, Qt mobile libraries, Qt Quick components for
- Symbian, and a debugging agent on the device. For more information,
- see \l{Connecting Symbian Devices}.
-
- \o Start the CODA debugging agent 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
-
-*/
-
-
-/*!
- \contentspage index.html
- \previouspage creator-writing-program.html
- \page creator-mobile-example.html
- \nextpage creator-project-managing.html
-
- \title Creating a Qt Widget Based Mobile Application
-
- \note To complete this tutorial, you must install \QSDK.
- The installation program installs and configures the necessary tool chains
- for mobile application development.
-
- This tutorial describes how to use Qt Creator to create a small Qt
- application, Battery Indicator, that uses the System Information
- Mobility API to fetch battery information from the device.
-
- The user interface for the application is designed using Qt widgets. This
- enforces a platform look and feel for Symbian devices and Maemo 5 devices.
- However, to achieve a platform look and feel for MeeGo Harmattan devices,
- \l{Creating Qt Quick Applications}{create a Qt Quick Application} and use
- the Qt Quick components for MeeGo.
-
- \image qtcreator-batteryindicator-screenshot.png
-
- \section1 Creating the Battery Indicator Project
-
- \note Create the project with the \gui{Help} mode active so that you can follow
- these instructions while you work.
-
- \list 1
-
- \o Select \gui{File > New File or Project > Qt Widget Project > Mobile
- Qt
- Application > Choose}.
-
- \image qtcreator-new-mobile-project.png "New File or Project dialog"
-
- The \gui{Introduction and Project Location} dialog opens.
-
- \image qtcreator-mobile-intro-and-location.png "Introduction and Project Location dialog"
-
- \o In the \gui{Name} field, type \bold {BatteryIndicator}.
-
- \o In the \gui {Create in} field, enter the path for the project files. For example,
- \c {C:\Qt\examples}, and then click \gui{Next}.
-
- The \gui{Target Setup} dialog opens.
-
- \image qtcreator-mobile-project-qt-versions.png "Target Setup dialog"
-
- \o Select \gui {Symbian Device}, \gui {Maemo5}, \gui Harmattan, and
- \gui {Qt Simulator} targets,
- and click \gui{Next}.
-
- \note Targets are listed if you installed the appropriate development
- environment, for example, as part of the \QSDK. You can add targets
- later in the \gui Projects mode.
-
- The \gui {Mobile Options} dialog opens.
-
- \image qtcreator-mobile-project-app-options.png "Mobile Options dialog"
-
- \o In the \gui {Orientation behavior} field, determine how the application
- behaves when the orientation of the device display rotates between portrait
- and landscape, and then click \gui{Next}.
-
- \note This dialog opens only if you select \gui Maemo5 or
- \gui {Symbian Device} target in the \gui {Target Setup} dialog. On
- Harmattan, the Qt Quick Components for MeeGo provide native-looking
- rotation.
-
- The \gui {Symbian Specific} dialog opens.
-
- \image qtcreator-mobile-project-symbian-options.png "Symbian Specific dialog"
-
- \note Qt Creator contains a default program icon and generates an
- \l{Application UID}, for testing the application on a device. You only
- need to change the icon and UID if you deliver the application for public use.
-
- \o Click \gui Next.
-
- The \gui {Maemo Specific} dialog opens.
-
- \image qtcreator-mobile-project-maemo-options.png "Maemo Specific dialog"
-
- \o In the \gui {Application icon} field, select the application
- icon to use on Maemo 5 or Harmattan targets, or click \gui Next to use
- the default icon.
-
- The \gui{Project Management} dialog opens.
-
- \image qtcreator-mobile-project-summary.png "Project Management dialog"
-
- \o Review the project settings, and click \gui{Finish} to create the project.
-
- \endlist
-
- The BatteryIndicator project now contains the following files:
-
- \list
-
- \o BatteryIndicator.pro
- \o main.cpp
- \o BatteryIndicator.svg
- \o BatteryIndicator.png
- \o BatteryIndicator.desktop
- \o deployment.pri
- \o mainwindow.cpp
- \o mainwindow.ui
- \o mainwindow.h
- \o templates for Debian deployment files
-
- \endlist
-
- \image qtcreator-mobile-project-contents.png "Project contents"
-
- The files come with the necessary boiler plate code that you must
- modify, as described in the following sections.
-
- \section1 Declaring the Qt Mobility API
-
- To use the Qt Mobility APIs or develop applications for Symbian
- devices, you must modify the .pro file to declare the Qt Mobility APIs
- that you use.
-
- This example uses the System Info API, so you must declare it, as
- illustrated by the following code snippet:
-
- \code
-
- CONFIG += mobility
- MOBILITY = systeminfo
-
- \endcode
-
- Each Mobility API has its corresponding value that you have to add
- as a value of MOBILITY to use the API. For a list of the APIs and the
- corresponding values that you can assign to MOBILITY, see the
- \l {http://doc.qt.nokia.com/qtmobility/quickstart.html}{Quickstart Example}.
-
- \section1 Designing the User Interface
-
- \list 1
-
- \o In the \gui{Editor} mode, double-click the mainwindow.ui
- file in the \gui{Projects} view to launch the integrated \QD.
-
- \o Drag and drop a \gui{Progress Bar} (\l{http://doc.qt.nokia.com/4.7/qprogressbar.html}{QProgressBar})
- widget to the form.
-
- \image qtcreator-mobile-project-widgets.png "Adding widgets to the UI"
-
- \o In the \gui Properties pane, change the \gui objectName to
- \bold batteryLevelBar.
-
- \o Right-click the \gui MainWindow object and select
- \gui {Lay Out > Lay Out Horizontally} to ensure that the battery
- indicator widget size is adjusted correctly on Maemo devices.
-
- \endlist
-
- \section1 Completing the Header File
-
- The mainwindow.h file contains some of the necessary #includes, a
- constructor, a destructor, and the \c{Ui} object. You must include
- the System Info header file, add a shortcut to the mobility name
- space, and add a private function to update the battery level value in
- the indicator when the battery power level changes.
-
- \list 1
-
- \o In the \gui{Projects} view, double-click the \c{mainwindow.h} file
- to open it for editing.
-
- \o Include the System Device Info header file, as illustrated by the following
- code snippet:
-
- \snippet examples/batteryindicator/mainwindow.h 1
-
- \o Add a shortcut to the mobility name space, as illustrated by the
- following code snippet:
-
- \snippet examples/batteryindicator/mainwindow.h 2
-
- \o Declare a private function in the \c{private} section, after the
- \c{Ui::MainWindow} function, as illustrated by the following code
- snippet:
-
- \snippet examples/batteryindicator/mainwindow.h 3
-
- \endlist
-
- \section1 Completing the Source File
-
- Now that the header file is complete, move on to the source file,
- mainwindow.cpp.
-
- \list 1
-
- \o In the \gui{Projects} view, double-click the mainwindow.cpp file
- to open it for editing.
-
- \o Create a QSystemDeviceInfo object and set its value. Then connect the signal
- that indicates that battery level changed to the \c setValue
- slot of the progress bar. This is illustrated by the following code snippet:
-
- \snippet examples/batteryindicator/mainwindow.cpp 1
-
- \o Use the constructor to set initial values and make sure that the
- created object is in a defined state, as illustrated by the following
- code snippet:
-
- \snippet examples/batteryindicator/mainwindow.cpp 2
-
- \endlist
-
- \section1 Compiling and Running Your Program
-
- Now that you have all the necessary code, select \gui {Qt Simulator}
- as the target and click the
- \inlineimage qtcreator-run.png
- button to build your program and run it in the Qt Simulator.
-
- In Qt Simulator, run the runOutOfBattery.qs example script
- to see the value change in the Battery Indicator application.
- Select \gui {Scripting > examples > runOutOfBattery.qs > Run}.
-
- \image qtcreator-mobile-simulated.png "Mobile example in Qt Simulator"
-
- \section1 Testing on a Symbian Device
-
- You also need to test the application on real devices. Before you can
- start testing on Symbian devices, you must connect them to the development
- PC by using a USB cable and install the necessary software on them.
-
- \list 1
-
- \o Install Qt libraries, Qt mobile libraries, and a
- debugging agent on the device. For more information,
- see \l{Connecting Symbian Devices}.
-
- \o Start the CODA debugging agent on the device.
-
- \o Click the \gui {Target Selector} and select \gui {Symbian Device}.
-
- \o Click \gui Run to build the application for the Symbian device.
-
- \endlist
-
- \section1 Testing on the Maemo or MeeGo Harmattan Emulator
-
- The Maemo 5 (Fremantle) and MeeGo Harmattan emulator are installed as part
- of the \QSDK. After they are installed, you can start them from Qt Creator.
-
- The Maemo emulator emulates the Nokia N900 device environment. You can test
- applications in conditions practically identical to running the application
- on a Nokia N900 device with the software update release 1.3 (V20.2010.36-2).
-
- The MeeGo Harmattan emulator emulates the Nokia N9 device environment.
-
- For more information, see \l{Using Maemo or MeeGo Harmattan Emulator}.
-
-*/
-
-/*!
- \contentspage index.html
- \previouspage creator-getting-started.html
- \page creator-build-example-application.html
- \nextpage creator-qml-application.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 the \gui {Show Examples and Demos}
- check box, and then search for \gui {Toys: Clocks Example} in the list
- of examples.
-
- \image qtcreator-gs-build-example-open.png "Selecting an example"
-
- \o Select targets for the project. Select at least Qt Simulator
- and one of the mobile targets, Symbian Device, Maemo 5, or Harmattan,
- depending on
- the device you develop for.
-
- \image qtcreator-gs-build-example-targets.png "Selecting targets"
-
- \note You can add targets later in the \gui Projects mode.
-
- \o To test the application in Qt Simulator, click the \gui {Target
- Selector} and select \gui {Qt Simulator}.
-
- \image {qtcreator-gs-build-example-select-qs.png} "Selecting Qt Simulator as target"
-
- \o Click
- \inlineimage{qtcreator-run.png}
- to build the application and run it in Qt Simulator.
-
- \o To see the compilation progress, press \key{Alt+4} to open the
- \gui {Compile Output} pane.
-
- The \gui Build progress bar on the toolbar turns green when the project
- is successfully built. The application opens in Qt Simulator.
-
- \image {qt-simulator.png} "Qt Simulator"
-
- \o Change the settings in the
- \gui Model view. For example, rotate the device by clicking the
- \gui {Orientation} buttons or choose from the various mobile device
- configurations in the \gui {Device} field. You can also simulate various
- mobile functions and create your own scripts.
-
- \o To test the application on a Symbian device, install Qt libraries
- and a debugging agent on the device. For more information,
- see \l{Connecting Symbian Devices}.
-
- \o Click the \gui {Target Selector} and select \gui {Symbian Device}.
-
- \o Click \gui Run to build the application and run it on the Symbian device.
-
- \endlist
-
-*/
-
-
-/*!
- \contentspage index.html
- \previouspage creator-build-example-application.html
- \page creator-qml-application.html
- \nextpage creator-qml-components-example.html
-
- \title Creating a Qt Quick Application
-
- \note To complete this tutorial, you must have Qt 4.7 or later installed.
-
- This tutorial uses basic elements and illustrates basic concepts of
- \l {http://doc.qt.nokia.com/4.7/qtquick.html}{Qt Quick}.
-
- This tutorial describes how to use the Qt Creator to implement the
- \l{http://doc.qt.nokia.com/4.7/declarative-animation-states.html}
- {states and transitions example application}. The example application displays a
- Qt logo that moves between three rectangles on the page when you click them.
-
- \image qmldesigner-tutorial.png "States and transitions example"
-
- For more information about using \QMLD, see
- \l{Developing Qt Quick Applications}.
-
- \section1 Creating the Project
-
- \list 1
-
- \o Select \gui{File > New File or Project > Qt Quick Project > Qt Quick
- Application > Choose}.
-
- \o Follow the instructions of the wizard to create a project called Transitions.
-
- \o Press \key {Ctrl+R} to run the application.
-
- \endlist
-
- Qt Creator generates a default QML file that you can modify to create the main view
- of the application.
-
- \image qmldesigner-tutorial-project.png "Transitions project in Edit mode"
-
- \section1 Creating the Main View
-
- The main view of the application displays a Qt logo in the top left corner of the
- screen and two empty rectangles.
-
- To use the states.png image in your application, you must copy it to the project
- directory (same subdirectory as the QML file) from the examples directory in the
- Qt installation directory. For example:
- \c {C:\QtSDK\Examples\4.7\declarative\animation\states}. The image appears
- in the \gui Resources pane. You can also use any other image or a QML element, instead.
-
- \list 1
-
- \o In the \gui Projects view, double-click the main.qml file
- to open it in the code editor.
-
- \o Click \gui Design to open the file in \QMLD.
-
- \image qmldesigner-tutorial-desing-mode.png "Transitions project in Design Mode"
-
- \o In the \gui Navigator pane, select \gui Text and press \key Delete to delete it.
-
- \o Select \gui Rectangle to edit its properties.
-
- \image qmldesigner-tutorial-page.png "Page properties"
-
- \list a
-
- \o In the \gui Id field, enter \e page, to be able to reference the rectangle
- from other places.
-
- \o In the \gui Colors group, \gui Rectangle field, set the color to #343434.
-
- \endlist
-
- \o In the \gui Library view, \gui Resources tab, select states.png and
- drag and drop it to the canvas.
-
- \image qmldesigner-tutorial-user-icon.png "Image properties"
-
- \list a
-
- \o In the \gui Id field, enter \e icon.
-
- \o In the \gui Position field, set \gui X to 10 and \gui Y to 20.
-
- \endlist
-
-
-
- \o In the \gui Library view, \gui Items tab, select \gui Rectangle,
- drag and drop it to the canvas, and edit its properties.
-
- \image qmldesigner-tutorial-topleftrect.png "Rectangle properties"
-
- \list a
-
- \o In the \gui Id field, enter \e topLeftRect.
-
- \o In the \gui Size field, set \gui W and \gui H to 64, for the rectangle size
- to match the image size.
-
- \o In the \gui Colors group, \gui Rectangle field, click the
- \inlineimage qmldesigner-transparent-button.png
- button to make the rectangle transparent.
-
- \o In the \gui Border field, set the border color to #808080.
-
- \o In the \gui Rectangle group, \gui Border field, set the border width to
- 1.
-
- \note If the \gui Border field does not appear after you set the border
- color, try setting the border color to solid by clicking the
- \inlineimage qmldesigner-solid-color-button.png
- button.
-
- \o In the \gui Radius field, select 6 to create rounded corners for the
- rectangle.
-
- \o Click \gui {Layout}, and then click the top and left anchor buttons
- to anchor the rectangle to the top left corner of the page.
-
- \image qmldesigner-tutorial-topleftrect-layout.png "Layout tab"
-
- \o In the \gui Margin field, select 20 for the top anchor and 10 for
- the left anchor.
-
- \endlist
-
- \o In the \gui Navigator pane, drag and drop the \gui {Mouse Area} element from
- \e page to \e topLeftRect to make it apply only to the rectangle and not to the whole
- page.
-
- \o Edit \gui {Mouse Area} properties:
-
- \list a
-
- \o Click \gui {Layout}, and then click the
- \inlineimage qmldesigner-anchor-fill-screen.png
- button to anchor the mouse area to the rectangle.
-
- \o In the code editor, edit the pointer to the clicked expression in the mouse
- area element, as illustrated by the following code snippet:
-
- \qml
- MouseArea {
- anchors.fill: parent
- onClicked: page.state = ''
- }
- \endqml
-
- The expression sets the state to the base state and returns the image to
- its initial position.
-
- \endlist
-
- \o In the \gui Navigator pane, copy topLeftRect (by pressing \key {Ctrl+C}) and
- paste it to the canvas twice
- (by pressing \key {Ctrl+V}). Qt Creator renames the new instances of the element
- topLeftRect1 and topLeftRect2.
-
- \o Select topLeftRect1 and edit its properties:
-
- \list a
-
- \o In the \gui Id field, enter \e middleRightRect.
-
- \o In \gui {Layout}, select the vertical center anchor button and
- then the right anchor button to
- anchor the rectangle to the middle right margin of the screen.
-
- \o In the \gui Margin field, select 10 for the right anchor and 0 for
- the vertical center anchor.
-
- \o In the code editor,add a pointer to a clicked expression to the
- mouse area element. The following expression sets the state to \e State1:
-
- \c {onClicked: page.state = 'State1'}
-
- You will create State1 later.
-
- \endlist
-
- \o Select topLeftRect2 and edit its properties:
-
- \list a
-
- \o In the \gui Id field, enter \e bottomLeftRect.
-
- \o In \gui {Layout}, select the bottom and left anchor buttons to
- anchor the rectangle to the bottom left margin of the screen.
-
- \o In the \gui Margin field, select 20 for the bottom anchor and 10 for
- the left anchor.
-
- \o In the code editor, add a pointer to a clicked expression to the
- mouse area element. The following expression sets the state to \e State2:
-
- \c {onClicked: page.state = 'State2'}
-
- You will create State2 later.
-
- \endlist
-
- \o Press \key {Ctrl+S} to save the changes.
-
- \o Press \key {Ctrl+R} to run the application.
-
- \endlist
-
- \image qmldesigner-tutorial.png "States and transitions example"
-
- You should see the Qt logo in the top left rectangle, and two additional
- rectangles in the center right and bottom left of the screen.
-
- You can now create additional states to add views to the application.
-
- \section1 Adding Views
-
- In the .qml file, you already created pointers to two additional states:
- State1 and State2. To create the states:
-
- \list 1
-
- \o Click the empty slot in the \gui States pane to create State1.
-
- \o Click the empty slot in the \gui States pane to create State2.
-
- \o In the code editor, bind the position of the Qt logo to the rectangle
- to make sure that the logo is displayed within the rectangle when the view
- is scaled on different sizes of screens. Set expressions for the x and y
- properties, as illustrated by the following code snippet:
-
- \snippet snippets/qml/states-properties.qml states
-
- \image qmldesigner-tutorial-state1.png "States"
-
- \note When you set the expressions, drag and drop is disabled for
- the icon in \QMLD.
-
- \o Press \key {Ctrl+R} to run the application.
-
- \endlist
-
- Click the rectangles to move the Qt logo from one rectangle to another.
-
- \section1 Adding Animation to the View
-
- Add transitions to define how the properties change when the Qt logo moves
- between states. The transitions apply animations to the Qt logo. For example,
- the Qt logo bounces back when it moves to the middleRightRect and eases into
- bottomLeftRect. Add the transitions in the code editor.
-
- \list 1
-
- \o In the code editor, add the following code to specify that when moving to
- State1, the x and y coordinates of the Qt logo change linearly over a duration
- of 1 second:
-
- \snippet snippets/qml/list-of-transitions.qml first transition
-
- \o You can use the Qt Quick toolbar for animation to change the easing curve
- type from linear to OutBounce:
-
- \list a
-
- \o Click \gui NumberAnimation in the code editor to display the
- \inlineimage qml-toolbar-indicator.png
- icon, and then click the icon to open the toolbar:
-
- \image qmldesigner-tutorial-quick-toolbar.png "Qt Quick toolbar for animation"
-
- \o In the \gui Easing field, select \gui Bounce.
-
- \o In the \gui Subtype field, select \gui Out.
-
- \endlist
-
- \o Add the following code to specify that when moving to State2, the x and y
- coordinates of the Qt logo change over a duration of 2 seconds,
- and an InOutQuad easing function is used:
-
- \snippet snippets/qml/list-of-transitions.qml second transition
-
- \o Add the following code to specify that for any other state changes, the x
- and y coordinates of the Qt logo change linearly over a duration of 200
- milliseconds:
-
- \snippet snippets/qml/list-of-transitions.qml default transition
-
- \o Press \key {Ctrl+R} to run the application.
-
- \endlist
-
- Click the rectangles to view the animated transitions.
-
-*/
-
-
-/*!
- \contentspage index.html
- \previouspage creator-qml-components-example.html
- \page creator-writing-program.html
- \nextpage creator-mobile-example.html
-
- \title Creating a Qt Widget Based Application
-
- This tutorial describes how to use Qt Creator
- to create a small Qt application, Text Finder. It is a simplified version of the
- QtUiTools \l{http://doc.qt.nokia.com/4.7/uitools-textfinder.html}{Text Finder}
- example.
- The application user interface is constructed from Qt widgets by using \QD.
- The application logic is written in C++ by using the code editor.
-
- \image qtcreator-textfinder-screenshot.png
-
- \section1 Creating the Text Finder Project
-
- \note Create the project with two instances of Qt Creator open and the \gui{Help} mode
- active in one of them so that you can follow
- these instructions while you work.
-
- \list 1
-
- \o Select \gui{File > New File or Project > Qt Widget Project > Qt Gui
- Application > Choose}.
-
- \image qtcreator-new-qt-gui-application.png "New File or Project dialog"
-
- The \gui{Introduction and Project Location} dialog opens.
-
- \image qtcreator-intro-and-location-qt-gui.png "Introduction and Project Location dialog"
-
- \o In the \gui{Name} field, type \bold {TextFinder}.
-
-
- \o In the \gui {Create in} field, enter the path for the project files. For example,
- \c {C:\Qt\examples}, and then click \gui{Next}.
-
- The \gui {Target Setup} dialog opens.
-
- \image qtcreator-new-project-qt-versions-qt-gui.png "Target Setup dialog"
-
- \o Select the Qt versions to use as build targets for your project, and click
- \gui{Next}.
-
- \note If you have only one Qt version installed, this dialog is skipped.
-
- The \gui{Class Information} dialog opens.
-
- \image qtcreator-class-info-qt-gui.png "Class Information dialog"
-
- \o In the \gui{Class name} field, type \bold {TextFinder} as the class name.
-
- \o In the \gui{Base class} list, select \bold {QWidget} as the base class type.
-
- \note The \gui{Header file}, \gui{Source file} and
- \gui{Form file} fields are automatically updated to match the name of the
- class.
-
- \o Click \gui{Next}.
-
- The \gui{Project Management} dialog opens.
-
- \image qtcreator-new-project-summary-qt-gui.png "Project Management dialog"
-
- \o Review the project settings, and click \gui{Finish} to create the project.
-
-
- \endlist
-
-
-
- The TextFinder project now contains the following files:
-
- \list
- \o textfinder.h
- \o textfinder.cpp
- \o main.cpp
- \o textfinder.ui
- \o textfinder.pro
- \endlist
-
- \image qtcreator-textfinder-contents.png "TextFinder project contents"
-
- The .h and .cpp files come with the necessary boiler plate code.
- The .pro file is complete.
-
- \section1 Filling in the Missing Pieces
-
- Begin by designing the user interface and then move on to filling
- in the missing code. Finally, add the find functionality.
-
- \section2 Designing the User Interface
-
- \image qtcreator-textfinder-ui.png "Text Finder UI"
-
- \list 1
-
- \o In the \gui{Editor} mode, double-click the textfinder.ui file in the \gui{Projects}
- view to launch the integrated \QD.
-
- \o Drag and drop the following widgets to the form:
-
- \list
- \o \gui{Label} (QLabel)
- \o \gui{Line Edit} (QLineEdit)
- \o \gui{Push Button} (QPushButton)
-
- \endlist
-
- \image qtcreator-textfinder-ui-widgets.png "Adding widgets to Text Finder UI"
-
- \note To easily locate the widgets, use the search box at the top of the
- \gui Sidebar. For example, to find the \gui Label widget, start typing
- the word \bold label.
-
- \image qtcreator-texfinder-filter.png "Filter field"
-
- \o Double-click the \gui{Label} widget and enter the text \bold{Keyword}.
-
- \o Double-click the \gui{Push Button} widget and enter the text \bold{Find}.
-
- \o In the \gui Properties pane, change the \gui objectName to \bold findButton.
-
- \image qtcreator-textfinder-objectname.png "Changing object names"
-
- \o Press \key {Ctrl+A} to select the widgets and click \gui{Lay out Horizontally}
- (or press \gui{Ctrl+H}) to apply a horizontal layout
- (QHBoxLayout).
-
- \image qtcreator-texfinder-ui-horizontal-layout.png "Applying horizontal layout"
-
- \o Drag and drop a \gui{Text Edit} widget (QTextEdit)
- to the form.
-
- \o Select the screen area and click \gui{Lay out Vertically} (or press \gui{Ctrl+L})
- to apply a vertical layout (QVBoxLayout).
-
- \image qtcreator-textfinder-ui.png "Text Finder UI"
-
- Applying the horizontal and vertical layouts ensures that the application UI scales to different
- screen sizes.
-
- \o To call a find function when users press the \gui Find button, you use the Qt signals
- and slots mechanism. A signal is emitted when a particular event occurs and a slot is
- a function that is called in response to a particular signal. Qt widgets have predefined
- signals and slots that you can use directly from \QD. To add a slot for the find function:
-
- \list
-
- \o Right-click the \gui Find button to open a context-menu.
- \o Select \gui {Go to Slot > clicked()}, and then select \gui OK.
-
- A private slot, \c{on_findButton_clicked()}, is added to the header file,
- textfinder.h and a private function, \c{TextFinder::on_findButton_clicked()},
- is added to the source file, textfinder.cpp.
-
- \endlist
-
- \o Press \gui{Ctrl+S} to save your changes.
-
- \endlist
-
- For more information about designing forms with \QD, see the
- \l{http://doc.qt.nokia.com/4.7/designer-manual.html}{Qt Designer Manual}.
-
- \section2 Completing the Header File
-
- The textfinder.h file already has the necessary #includes, a
- constructor, a destructor, and the \c{Ui} object. You need to add a private
- function, \c{loadTextFile()}, to read and display the
- contents of the input text file in the
- QTextEdit.
-
- \list 1
-
- \o In the \gui{Projects} pane in the \gui {Edit view}, double-click the \c{textfinder.h} file
- to open it for editing.
-
- \o Add a private function
- to the \c{private} section, after the \c{Ui::TextFinder} pointer, as
- illustrated by the following code snippet:
-
- \snippet examples/textfinder/textfinder.h 0
-
- \endlist
-
- \section2 Completing the Source File
-
- Now that the header file is complete, move on to the source file,
- textfinder.cpp.
-
- \list 1
-
- \o In the \gui{Projects} pane in the \gui Edit view, double-click the textfinder.cpp file
- to open it for editing.
-
- \o Add code to load a text file using
- QFile, read it with QTextStream, and
- then display it on \c{textEdit} with
- \l{http://doc.qt.nokia.com/4.7/qtextedit.html#plainText-prop}{setPlainText()}.
- This is illustrated by the following code snippet:
-
- \snippet examples/textfinder/textfinder.cpp 0
-
- \o To use QFile and QTextStream, add the
- following #includes to textfinder.cpp:
-
- \snippet examples/textfinder/textfinder.cpp 1
-
- \o For the \c{on_findButton_clicked()} slot, add code to extract the search string and
- use the \l{http://doc.qt.nokia.com/4.7/qtextedit.html#find}{find()} function
- to look for the search string within the text file. This is illustrated by
- the following code snippet:
-
- \snippet examples/textfinder/textfinder.cpp 2
-
- \o Once both of these functions are complete, add a line to call \c{loadTextFile()} in
- the constructor, as illustrated by the following code snippet:
-
- \snippet examples/textfinder/textfinder.cpp 3
-
- \endlist
-
- The \c{on_findButton_clicked()} slot is called automatically in
- the uic generated ui_textfinder.h file by this line of code:
-
- \code
- QMetaObject::connectSlotsByName(TextFinder);
- \endcode
-
- \section2 Creating a Resource File
-
- You need a resource file (.qrc) within which you embed the input
- text file. The input file can be any .txt file with a paragraph of text.
- Create a text file called input.txt and store it in the textfinder
- folder.
-
- To add a resource file:
- \list 1
- \o Select \gui{File > New File or Project > Qt > Qt Resource File > Choose}.
- \image qtcreator-add-resource-wizard.png "New File or Project dialog"
-
- The \gui {Choose the Location} dialog opens.
-
- \image qtcreator-add-resource-wizard2.png "Choose the Location dialog"
-
- \o In the \gui{Name} field, enter \bold{textfinder}.
- \o In the \gui{Path} field, enter \c{C:\Qt\examples\TextFinder},
- and click \gui{Next}.
-
- The \gui{Project Management} dialog opens.
-
- \image qtcreator-add-resource-wizard3.png "Project Management dialog"
-
-
- \o In the \gui{Add to project} field, select \bold{TextFinder.pro}
- and click \gui{Finish} to open the file in the code editor.
-
- \o Select \gui{Add > Add Prefix}.
- \o In the \gui{Prefix} field, replace the default prefix with a slash (/).
- \o Select \gui{Add > Add Files}, to locate and add input.txt.
-
- \image qtcreator-add-resource.png "Editing resource files"
-
- \endlist
-
- \section1 Compiling and Running Your Program
-
- Now that you have all the necessary files, click the \inlineimage qtcreator-run.png
- button to compile and run your program.
-
-*/
-
-
-/*!
- \contentspage index.html
- \previouspage creator-project-generic.html
- \page creator-version-control.html
- \nextpage adding-plugins.html
-
- \title Using Version Control Systems
-
- Version control systems supported by Qt Creator are:
- \table
- \header
- \i Version Control System
- \i Address
- \i Notes
- \row
- \i Bazaar
- \i \l{http://bazaar.canonical.com/}
- \i Qt Creator 2.2 and later
- \row
- \i CVS
- \i \l{http://www.cvshome.org}
- \i
- \row
- \i Git
- \i \l{http://git-scm.com/}
- \i
- \row
- \i Mercurial
- \i \l{http://mercurial.selenic.com/}
- \i Qt Creator 2.0 and later
- \row
- \i Perforce
- \i \l{http://www.perforce.com}
- \i Server version 2006.1 and later
- \row
- \i Subversion
- \i \l{http://subversion.apache.org/}
- \i
- \endtable
-
-
- \section1 Setting Up Version Control Systems
-
- Qt Creator uses the version control system's command line clients to access
- your repositories. To allow access, make sure that the command line clients
- can be located using the \c{PATH} environment variable or specify the path to
- the command line client executables in \gui{Tools} > \gui{Options...} >
- \gui {Version Control}.
-
- After you set up the version control system, use the command line to check
- that everything works (for example, use the status command). If no issues arise,
- you should be ready to use the system also from Qt Creator.
-
- \section2 Using msysGit on Windows
-
- If you configure Git for use with \c {git bash}, only, and use SSH
- authorization, Git looks for the SSH keys in the directory where the
- \c HOME environment points to. The variable is always set by \c {git bash}.
-
- However, the variable is typically not set in a Windows command prompt.
- When you run Git from a Windows command prompt, it looks for the SSH keys in its
- installation directory, and therefore, the authorization fails.
-
- You can set the \c HOME environment variable from Qt Creator. Select \gui {Tools >
- Options... > Version Control > Git}. Select the \gui {Environment Variables}
- and the \gui {Set "HOME" environment variable} check boxes. \c HOME is set to
- \c %HOMEDRIVE%%HOMEPATH% when the Git executable is run and authorization works
- as it would with \c {git bash}.
-
- \section1 Setting Up Common Options
-
- Select \gui{Tools} > \gui{Options...} > \gui{Version Control} > \gui{Common}
- to specify settings for submit messages:
- \list
- \o \gui{Submit message check script} is a script or program that
- can be used to perform checks on the submit message before
- submitting. The submit message is passed in as the script's first
- parameter. If there is an error, the script should output a
- message on standard error and return a non-zero exit code.
-
- \o \gui{User/alias configuration file} takes a file in mailmap format
- that lists user names and aliases. For example:
-
- \code
- Jon Doe <Jon.Doe@company.com>
- Hans Mustermann <Hans.Mustermann@company.com> hm <info@company.com>
- \endcode
-
- \note The second line above specifies the alias \e{hm} and the
- corresponding email address for \e{Hans Mustermann}. If the
- user/alias configuration file is present, the submit editor
- displays a context menu with \gui{Insert name...} that pops up a
- dialog letting the user select a name.
-
- \o \gui{User fields configuration file} is a simple text file
- consisting of lines specifying submit message fields that take
- user names, for example:
-
- \code
- Reviewed-by:
- Signed-off-by:
- \endcode
-
- The fields above appear below the submit message. They provide completion
- for the aliases/public user names specified in the
- \e{User/alias configuration file} as well as a button that opens the
- aforementioned user name dialog.
-
- \o \gui{SSH prompt command} specifies an ssh-askpass command that you
- can use (on Linux) to prompt the user for a password when using SSH.
- For example, \c ssh-askpass or \c x11-ssh-askpass, depending on the
- ssh-askpass implementation that you use.
-
- \endlist
-
- \section1 Creating VCS Repositories for New Projects
-
- Qt Creator allows you to create repositories for version
- control systems that support local repository creation, such as
- Git, Mercurial, or Bazaar.
- When creating a new project by selecting \gui File >
- \gui{New File or Project...}, you can choose a version
- control system in the final wizard page.
-
- You can also select \gui Tools and then select \gui {Create Repository...}
- in the submenu for the version control system.
-
- To import a project that is under version control, choose \gui {File >
- New File or Project... > Project from Version Control} and select the
- version control system that you use. Follow the instructions of the
- wizard to import the project.
-
- \section1 Using Version Control Systems
-
- The \gui{Tools} menu contains a submenu for each supported version
- control system.
-
- The \gui{Version Control} output pane displays the commands
- that are executed, a timestamp, and the relevant output.
- Select \gui {Window > Output Panes > Version Control} to open
- the pane.
-
-
- \image qtcreator-vcs-pane.png
-
-
- \section2 Adding Files
-
- When you create a new file or a new project, the wizard displays a page
- asking whether the files should be added to a version control system.
- This happens when the parent directory or the project is already
- under version control and the system supports the concept of adding files,
- for example, Perforce and Subversion. Alternatively, you can
- add files later by using the version control tool menus.
-
- With Git, there is no concept of adding files. Instead, all modified
- files must be staged for a commit.
-
-
- \section2 Viewing Diff Output
-
- All version control systems provide menu options to \e{diff} the current
- file or project: to compare it with the latest version stored in the
- repository and to display the differences. In Qt Creator, a diff is
- displayed in a read-only editor. If the file is accessible, you can
- double-click on a selected diff chunk and Qt Creator opens an editor
- displaying the file, scrolled to the line in question.
-
- \image qtcreator-vcs-diff.png
-
-
- \section2 Viewing Versioning History and Change Details
-
- Display the versioning history of a file by selecting \gui{Log}
- or \gui{Filelog}. Typically, the log output contains the date, the commit
- message, and a change or revision identifier. Click on the identifier to
- display a description of the change including the diff.
- Right-clicking on an identifier brings up a context menu that lets you
- show annotation views of previous versions (see \l{Annotating Files}).
-
- \image qtcreator-vcs-log.png
-
-
- \section2 Annotating Files
-
- Annotation views are obtained by selecting \gui{Annotate} or \gui{Blame}.
- Selecting \gui{Annotate} or \gui{Blame} displays the lines of the file
- prepended by the change identifier they originate from. Clicking on the
- change identifier shows a detailed description of the change.
-
- To show the annotation of a previous version, right-click on the
- version identifier at the beginning of a line and choose one of the
- revisions shown at the bottom of the context menu. This allows you to
- navigate through the history of the file and obtain previous versions of
- it. It also works for Git and Mercurial using SHA's.
-
- The same context menu is available when right-clicking on a version
- identifier in the file log view of a single file.
-
-
- \section2 Committing Changes
-
- Once you have finished making changes, submit them to the version control
- system by choosing \gui{Commit} or \gui{Submit}. Qt Creator displays a
- commit page containing a text editor where you can enter your commit
- message and a checkable list of modified files to be included.
-
- \image qtcreator-vcs-commit.png
-
- When you have finished filling out the commit page information, click on
- \gui{Commit} to start committing.
-
- The \gui{Diff Selected Files} button brings up a diff view of the
- files selected in the file list. Since the commit page is just another
- editor, you can go back to it by closing the diff view. You can also check
- a diff view from the editor combo box showing the \gui{Opened files}.
-
- \section2 Reverting Changes
-
- All supported version control system support reverting your project to
- known states. This functionality is generally called \e reverting.
-
- The changes discarded depend on the version control system.
-
- A version control system can replace the \gui Revert menu option with other
- options.
-
- \section3 Reverting Changes Using Git
-
- The Git version control system has an index that is used to stage
- changes. The index is commited on the next commit. Git allows you to revert
- back to the state of the last commit as well as to the state staged in the
- index.
-
- \list
-
- \o \gui{Undo Unstaged Changes} reverts all changes and resets the working
- directory to the state of the index.
-
- \o \gui{Undo Uncommitted Changes} reverts all changes, discarding the index.
- This returns your working copy to the state it was in right after the last commit.
-
- \endlist
-
- \section2 Viewing Status
-
- You can select \gui{Status...} to view the status of the project or
- repository.
-
- \section2 Updating the Working Tree
-
- You can select \gui Update to update your working tree with the latest
- changes from the branch. Some version control systems allow you to choose
- between updating the current project and updating all projects.
-
- With Git, you stash your changes and then pull the changes from the
- repository.
-
- \section2 Deleting Files
-
- You can select \gui Delete to delete obsolete files from the repository.
-
- With Git, you delete the files from the working tree and then stage the
- deleted files for a commit.
-
- \section2 Using Additional Bazaar Functions
-
- Bazaar is a free version control system sponsored by Canonical.
-
- The \gui Bazaar submenu contains the following additional items:
-
- \table
- \header
- \o Menu Item
- \o Description
- \row
- \i \gui{Pull...}
- \i Turn the branch into a mirror of another branch.
- \row
- \i \gui{Push...}
- \i Update a mirror of the branch.
-
- \endtable
-
- \section2 Using Additional CVS Functions
-
- CVS is an open source version control system.
-
- The \gui CVS submenu contains the following additional items:
-
- \table
- \header
- \o Menu Item
- \o Description
- \row
- \i \gui{Edit}
- \i Open a file for editing.
- \row
- \i \gui{Push...}
- \i Push changes to the remote repository.
- \row
- \i \gui{Unedit}
- \i Discard the changes that you made in a file.
-
- \endtable
-
- \section2 Using Additional Git Functions
-
- Git is a fast decentralized version control system. Git is available
- for Windows, Linux and Mac.
-
- The \gui Git submenu contains the following additional items:
-
- \table
- \header
- \o Menu Item
- \o Description
- \row
- \i \gui {Patch > Apply from Editor/Apply from File...}
- \i Patches are rewriting instructions that can be applied to a set of files.
- You can either apply a patch file that is open in Qt Creator or select
- the patch file to apply from the file system.
- \row
- \i \gui{Pull}
- \i Pull changes from the remote repository. If there are locally
- modified files, you are prompted to stash those changes. Select \gui{Tools >
- Options... > Version Control > Git} and select the \gui {Pull with rebase}
- check box to perform a rebase operation while pulling.
-
- \row
- \i \gui{Clean.../Clean Project...}
- \i All files that are not under version control (with the exception
- of patches and project files) are displayed in the \gui {Clean Repository}
- dialog. Select the files to delete and click \gui Delete. This allows you to
- clean a build completely.
- \row
- \i \gui{Launch gitk}
- \i Start the commit viewer for Git, gitk.
- \row
- \i \gui{Branches...}
- \i Manage local and remote branches.
- \row
- \i \gui Remotes...
- \i Manage remote repositories available in Git.
- \row
- \i \gui {Stage File for Commit}
- \i Mark new or modified files for committing to the repository.
- To undo this function, select \gui {Unstage File from Commit}.
- \row
- \i \gui{Show Commit...}
- \i Select a commit to view. Enter the SHA of the commit
- in the \gui Change field.
- \row
- \i \gui Stash
- \i Store local changes temporarily.
- \row
- \i \gui{Amend Last Commit...}
- \i Revert the last commit.
-
- \endtable
-
- \section3 Working with Branches
-
- To work with Git branches, select \gui{Branches...}. The checked out branch
- is shown in bold and underlined in the list of branches. Double-click branch
- names to edit them.
-
- \image qtcreator-vcs-gitbranch.png "Branches dialog"
-
- The following operations are supported:
-
- \table
- \header
- \o Menu Item
- \o Description
- \row
- \i \gui{Add...}
- \i Create new tracking and non-tracking branches.
- \row
- \i \gui{Checkout}
- \i Check out the selected branch and make it current.
- \row
- \i \gui{Remove}
- \i Remove a local branch. You cannot delete remote branches.
- \row
- \i \gui{Diff}
- \i Show the differences between the selected and the current
- branch.
- \row
- \i \gui{Log}
- \i Show the changes in a branch.
- \row
- \i \gui{Refresh}
- \i Refresh the list of branches.
- \endtable
-
- \section3 Working with Remote Repositories
-
- To manage remote repositories available in Git, select \gui{Remotes...}.
- Double-click the names and URLs of the remote repositories to edit them.
-
- The following operations are supported:
-
- \table
- \header
- \o Menu Item
- \o Description
- \row
- \i \gui{Add...}
- \i Add a new remote repository.
- \row
- \i \gui{Fetch}
- \i Fetch all the branches and change information from a remote
- repository.
- \row
- \i \gui{Remove}
- \i Remove a remote repository.
- \row
- \i \gui{Refresh}
- \i Refresh the list of remote repositories.
- \endtable
-
-
- \section3 Using Stashes
-
- With Git, you can put your current set of changes onto a virtual shelf called a \e stash.
- Stashes are useful, for example, to put aside a set of changes to work on higher
- priority tasks or to pull in new chages from another repository.
-
- Qt Creator exposes this functionality in the \gui{Tools > Git > Stash} menu.
-
- \table
- \header
- \o Menu Item
- \o Description
- \row
- \i \gui{Stashes...}
- \i Display a dialog that shows all known stashes with options to restore,
- display or delete them.
- \row
- \i \gui{Stash}
- \i Stash all local changes. The working copy is then reset to
- the state it had right after the last commit.
- \row
- \i \gui{Stash Snapshot...}
- \i Save a snapshot of your current work under a name for later reference. The
- working copy is unchanged.
-
- For example, if you want to try something and find out later that it does not work,
- you can discard it and return to the state of the snapshot.
- \row
- \i \gui{Stash Pop}
- \i Remove a single stashed state from the stash list and apply it on
- top of the current working tree state.
- \endtable
-
- \section2 Using Additional Mercurial Functionality
-
- Mercurial is a free, distributed source control management tool.
-
- The \gui Mercurial submenu contains the following additional items:
-
- \table
- \header
- \o Menu Item
- \o Description
- \row
- \i \gui{Import}
- \i Apply changes from a patch file.
- \row
- \i \gui{Incoming}
- \i Monitor the status of a remote repository by listing
- the changes that will be pulled.
- \row
- \i \gui{Outgoing}
- \i Monitor the status of a remote repository by listing
- the changes that will be pushed.
- \row
- \i \gui{Pull}
- \i Pull changes from the remote repository.
- \row
- \i \gui{Push}
- \i Push changes to the remote repository.
- \endtable
-
- \section2 Using Additional Perforce Functions
-
- Perforce is a fast software configuration management system developed by
- Perforce Software.
-
- When you start Qt Creator, it looks for the executable specified
- in the \gui{P4 command} field in \gui{Tools > Options... > Version
- Control > Perforce}. If the file is not found, the following error
- message is displayed in the \gui {Version Control} output pane:
- \gui {Perforce: Unable to determine the repository: "p4.exe"
- terminated with exit code 1}. If you use Perforce, check that the
- path to the executable is specified correctly in the \gui{P4 command}
- field.
-
- If you do not use Perforce, you can disable the Perforce plugin to
- get rid of the error message. Choose \gui {Help > About Plugins} and
- deselect the \gui Load check box for the \gui Perforce plugin in the
- \gui {Version Control} group.
-
- The \gui Perforce submenu contains the following additional items:
-
- \table
- \header
- \o Menu Item
- \o Description
- \row
- \i \gui{Describe...}
- \i View information about changelists and the files in them.
- \row
- \i \gui{Edit File}
- \i Open a file for editing.
- \row
- \i \gui{Opened}
- \i List files that are open for editing.
- \row
- \i \gui{Pending Changes...}
- \i Group files for commit.
- \endtable
-
- \section2 Using Additional Subversion Functions
-
- Subversion is an open source version control system.
-
- The \gui Subversion submenu contains the following additional items:
-
- \table
- \header
- \o Menu Item
- \o Description
- \row
- \i \gui{Describe...}
- \i Display commit log messages for a revision.
- \endtable
-
-*/
-
-
-/*!
- \contentspage index.html
- \previouspage qt-quick-toolbars.html
- \page creator-editor-locator.html
- \nextpage creator-editor-codepasting.html
-
- \title Searching With the Locator
-
- The locator provides one of the easiest ways in Qt Creator to browse
- through projects, files, classes, methods, documentation and file systems.
- You can find the locator in the bottom left of the Qt Creator window.
-
- To activate the locator, press \key Ctrl+K (\key Cmd+K on Mac OS
- X) or select \gui Tools > \gui Locate....
-
- \image qtcreator-locator.png
-
- To edit the currently open project's main.cpp file using the locator:
- \list 1
- \o Activate the locator by pressing \key Ctrl+K.
- \o Enter \tt{main.cpp}.
-
- \image qtcreator-locator-open.png
- \o Press \key Return.
-
- The main.cpp file opens in the editor.
- \endlist
-
- It is also possible to enter only a part of a search string.
- As you type, the locator shows the occurrences of that string regardless
- of where in the name of an component it appears.
-
- To narrow down the search results, you can use the following wildcard
- characters:
- \list
- \o To match any number of any or no characters, enter \bold{*}.
- \o To match a single instance of any character, enter \bold{?}.
- \endlist
-
- \section1 Using the Locator Filters
-
- The locator allows you to browse not only files, but any items
- defined by \bold{locator filters}. By default, the locator contains
- filters for:
- \list
- \o Locating any open document
- \o Locating files anywhere on your file system
- \o Locating iles belonging to your project, such as source, header resource,
- and .ui files
- \o Locating class and method definitions in your project or anywhere
- referenced
- from your project
- \o Locating class and method definitions in the current document
- \o Locating a specific line in the document displayed in your editor
- \o Opening help topics, including Qt documentation
- \o Performing web searches
- \o Running text editing macros that you record and save. For more
- information, see \l{Using Text Editing Macros}
- \endlist
-
- To use a specific locator filter, type the assigned prefix followed by
- \key Space. The prefix is usually a single character.
-
- For example, to locate symbols matching
- QDataStream:
- \list 1
- \o Activate the locator.
- \o Enter \tt{\bold{: QDataStream}} (: (colon) followed by a
- \key Space and the symbol name (QDataStream)).
-
- The locator lists the results.
-
- \image qtcreator-navigate-popup.png
- \endlist
-
- By default the following filters are enabled and you do not need to use
- their prefixes explicitly:
-
- \list
- \o Going to a line in the current file (l).
- \o Going to an open file (o).
- \o Going to a file in any open project (a).
- \endlist
-
- \section2 Using the Default Locator Filters
-
- The following locator filters are available by default:
-
- \table
- \header
- \o Function
- \o Enter in locator
- \o Example
- \row
- \o Go to a line in the current file.
- \o \tt{\bold{l \e{Line number}}}
- \o \image qtcreator-locator-line.png
- \row
- \o Go to a symbol definition.
- \o \tt{\bold{: \e{Symbol name}}}
- \o \image qtcreator-locator-symbols.png
- \row
- \o Go to a symbol definition in the current file.
- \o \tt{\bold{. \e{Symbol name}}}
- \o \image qtcreator-locator-method-list.png
- \row
- \o Go to a help topic.
- \o \tt{\bold{? \e{Help topic}}}
- \o \image qtcreator-locator-help.png
- \row
- \o Search for a term by using a web search engine.
- \o \tt{\bold{r \e{Search term}}}
- \o \image qtcreator-locator-web.png
- \row
- \o Go to an open file.
- \o \tt{\bold{o \e{File name}}}
- \o \image qtcreator-locator-opendocs.png
- \row
- \o Go to a file in the file system (browse the file system).
- \o \tt{\bold{f \e{File name}}}
- \o \image qtcreator-locator-filesystem.png
- \row
- \o Go to a file in any project currently open.
- \o \tt{\bold{a \e{File name}}}
- \o \image qtcreator-locator-files.png
- \row
- \o Go to a file in the current project.
- \o \tt{\bold{p \e{File name}}}
- \o \image qtcreator-locator-current-project.png
- \row
- \o Go to a class definition.
- \o \tt{\bold{c \e{Class name}}}
- \o \image qtcreator-locator-classes.png
- \row
- \o Go to a method definition.
- \o \tt{\bold{m \e{Method name}}}
- \o \image qtcreator-locator-methods.png
- \row
- \o Execute a text editing macro.
- \o \tt{\bold{rm \e{Macro name}}}
- \o \image qtcreator-locator-macros.png
- \endtable
-
- \section2 Creating Locator Filters
-
- To quickly access files not directly mentioned in your project, you can
- create your own locator filters. That way you can locate files in a
- directory structure you have defined.
-
- To create a locator filter:
- \list 1
- \o In the locator, click \inlineimage qtcreator-locator-magnify.png
- and select \gui Configure.... to open the \gui Locator options.
-
- \image qtcreator-locator-customize.png
-
- \o Click \gui Add.
- \o In the \gui{Filter Configuration} dialog:
- \list
- \o Name your filter.
- \o Select at least one directory. The locator searches directories
- recursively.
- \o Define the file pattern as a comma separated list. For example,
- to search all .h and .cpp files, enter \bold{*.h,*.cpp}
- \o Specify the prefix string.
-
- To show only results matching this filter, select
- \gui{Limit to prefix}.
-
- \image qtcreator-navigate-customfilter.png
- \endlist
- \o Click OK.
- \endlist
-
- \section2 Adding Web Search Engines
-
- You can use the \gui {Web Search (\c r)} locator filter to perform
- web searches. URLs and search commands for Bing, Google, Yahoo! Search,
- cplusplus.com, and Wikipedia are configured by default.
-
- To find out the format of the search command to use for your favorite
- web search engine, perform a search in your browser and copy the resulting
- URL to the locator filter configuration. Replace the search term with the
- variable \c {%1}.
-
- To add URLs and search commands to the list:
-
- \list 1
-
- \o Select \gui {Tools > Options > Locator > Web Search (prefix: r) >
- Edit}.
-
- \o Select \gui Add to add a new entry to the list.
-
- \image qtcreator-add-online-doc.png "Filter Configuration dialog"
-
- \o Double-click the new entry to specify a URL and a search command.
- For example, http://www.google.com/search?q=%1.
-
- \o Click \gui OK.
-
- \endlist
-
- \section2 Configuring the Locator Cache
-
- The locator searches the files matching your file pattern in the
- directories you have selected and caches that information. The cache for
- all default filters is updated as you write your code. By default,
- Qt Creator updates the filters created by you once an hour.
-
- To update the cached information manually, click
- \inlineimage qtcreator-locator-magnify.png
- and select \gui Refresh.
-
- To set a new cache update time:
- \list 1
- \o Select \gui Tools > \gui Options... > \gui Locator.
- \o In \gui{Refresh interval}, define new time in minutes.
- \endlist
-
-*/
-
-
-/*!
- \contentspage index.html
- \previouspage creator-developing-symbian.html
- \page creator-project-managing-sessions.html
- \nextpage creator-coding.html
-
- \title Managing Sessions
-
- When you exit Qt Creator, a snapshot of your current workspace is stored
- as a \e session. To restore the session automatically when you start Qt
- Creator, select \gui {File > Session Manager > Restore last session on
- startup}.
-
- A session is an arbitrary collection of:
-
- \list
- \o Open projects with their dependencies (including SUBDIRS projects)
- \o Open editors
- \o Breakpoints and expressions
- \o Bookmarks
- \endlist
-
- A session is personal, that is, not meant to be shared. It is not
- supposed to reflect the project structure. It contains personal data, such as
- bookmarks and breakpoints that are usually not of interest to other developers
- working on the same projects.
-
- For example, if you work on a project and need to switch to another project for a
- while, you can save your workspace as a session. This makes it easier
- to return to working on the first project later.
-
- To create a new session or remove existing sessions, select \gui File >
- \gui{Session Manager}.
-
- \image qtcreator-session-manager.png
-
- To switch between sessions, choose
- \gui {File > Session Manager}. If you do not create or select a session,
- Qt Creator always uses the default session, which was created the
- last time you exited Qt Creator.
-
- When you launch Qt Creator, a list of existing sessions is displayed on the
- \gui{Welcome screen}.
-
- \image qtcreator-welcome-session.png
-
-*/
-
-
-/*!
- \contentspage index.html
- \previouspage creator-build-dependencies.html
- \page creator-debugging.html
- \nextpage creator-debugging-example.html
-
- \title Debugging
-
- Qt Creator provides a debugger plugin that acts
- as an interface between the Qt Creator core and external native debuggers
- such as the GNU Symbolic Debugger (GDB), the Microsoft Console Debugger (CDB),
- and a QML/JavaScript debugger.
-
- The following sections describe debugging with Qt Creator:
-
- \list
-
- \o \l{Debugging the Example Application} uses an example application
- to illustrate how to debug Qt C++ applications in the \gui Debug
- mode.
-
- \o \l{Launching the Debugger} describes the
- operating modes in which the debugger plugin runs, depending on
- where and how the process is started and run.
-
- \o \l{Interacting with the Debugger} describes the views and functions
- available in the \gui Debug mode.
-
- \o \l{Setting Up Debugger} summarizes the support for debugging C++
- code and requirements for installation. Typically, the interaction
- between Qt Creator and the native debugger is set up automatically
- and you do not need to do anything.
-
- \o \l{Using Debugging Helpers} describes how to get more detailed data
- on complex data.
-
- \o \l{Debugging Qt Quick Projects} describes how to debug Qt Quick
- projects.
-
- \o \l{Troubleshooting Debugger} lists some typical problems that you
- might encounter while debugging and solutions to them.
-
- \endlist
-
-*/
-
-/*!
- \contentspage index.html
- \previouspage creator-debugging-example.html
- \page creator-debugger-operating-modes.html
- \nextpage creator-debug-mode.html
-
- \title Launching the Debugger
-
- To start a program under the control of the debugger, select \gui{Debug} >
- \gui{Start Debugging} > \gui{Start Debugging}, or press \key{F5}.
- Qt Creator checks whether the compiled program is up-to-date, and rebuilds
- it if necessary. The debugger then takes over and starts the program.
-
- \note Starting a program in the debugger can take a long
- time, typically in the range of several seconds to minutes if complex
- features (like QtWebKit) are used.
-
- The debugger is launched in the appropriate operating mode (plain, terminal,
- or on-device), based on the build and run settings for the active project.
- Select \gui Debug menu options to launch the debugger in other modes.
-
- \note Debugging QML and JavaScript is supported only in plain mode.
-
- \section1 Launching the Debugger in Different Modes
-
- The debugger plugin runs in different operating modes depending on where and
- how the process is started and run. Some of the modes are only available for
- a particular operating system or platform.
-
- You can launch the debugger in the following modes:
-
- \list
-
- \o \bold Plain to debug locally started applications, such as a
- Qt based GUI application.
-
- \o \bold Terminal to debug locally started processes that need a
- console, typically without a GUI.
-
- \o \bold Attach to debug local processes started outside Qt Creator.
-
- \o \bold Remote to debug a process running on a different machine.
-
- \o \bold Core to debug crashed processes on Unix.
-
- \o \bold Post-mortem to debug crashed processes on Windows.
-
- \o \bold On-device to debug processes running on a mobile device.
-
- \endlist
-
- \note Debugging QML and JavaScript is supported only in plain mode.
-
- \section2 Launching in Plain Mode
-
- To launch the debugger in the plain mode, click the \gui {Start Debugging}
- button for the active project, or choose
- \gui {Debug > Start Debugging > Start and Debug External Application...}
- and specify an executable.
-
- \section2 Launching in Terminal Mode
-
- To launch the debugger in the terminal mode, select \gui {Projects > Run Settings}
- and select the \gui {Run in terminal} check box. Then click the
- \gui {Start Debugging} button for the active project.
-
- \section2 Launching in Attach Mode
-
- To launch the debugger in the attach mode, select
- \gui {Debug > Start Debugging > Attach to Running External Application...},
- and then select a process by its name or process ID to attach to.
-
- You can load the source project in advance and set breakpoints in it before
- attaching to an already running process. For more information, see
- \l{Setting Breakpoints}.
-
- \section2 Launching in Remote Mode
-
- The remote mode allows you to debug processes that run on remote machines.
-
- \section3 Using GDB
-
- In remote mode, the local GDB process talks to a GDB server
- process running on the remote machine that controls the process to be
- debugged.
-
- The GDB server process is started on the remote machines by passing a port
- number and the executable:
-
- \code
- gdbserver :1234 <executable>
- \endcode
-
- It then typically responds:
- \code
- Process bin/qtcreator created; pid = 5159
- Listening on port 1234
- \endcode
-
- On the local machine that runs Qt Creator:
-
- \list 1
-
- \o Select \gui {Debug > Start Debugging > Start and Attach to Remote
- Application...}.
-
- \o In the \gui {Host and port} field, enter the name of the remote
- machine and the port number to use.
-
- \o Select \gui{OK} to start debugging.
-
- \endlist
-
- \section3 Using CDB
-
- In remote mode, the local CDB process talks to a CDB process that
- runs on the remote machine. The process is started with special
- command line options that switch it into server mode. The remote CDB
- process must load the Qt Creator CDB extension library that is shipped with
- Qt Creator:
-
- \list 1
-
- \o Install the \e{Debugging Tools for Windows} on the remote machine.
- The installation folder contains the CDB command line executable (cdb.exe).
-
- \o Copy the Qt Creator CDB extension library from the Qt installation
- directory to the a new folder on the remote machine
- (32 or 64 bit version depending on the version of the Debugging
- Tools for Windows
- used):
-
- \list
-
- \o \c {\lib\qtcreatorcdbext32\qtcreatorcdbext.dll} (32 bit)
-
- \o \c {\lib\qtcreatorcdbext64\qtcreatorcdbext.dll} (64 bit)
-
- \endlist
-
- \o Set the _NT_DEBUGGER_EXTENSION_PATH environment variable to point
- to that folder.
-
- \o To use TCP/IP as communication protocol, launch remote CDB as
- follows:
-
- \code
- cdb.exe -server tcp:port=1234 <executable>
- \endcode
-
- \o On the local machine running Qt Creator, select
- \gui {Debug > Start Debugging > Attach to Remote CDB Session...}
-
-
- \o In the \gui Connection field enter the connection parameters.
- For example, for TCP/IP:
-
- \code
- Server:Port
- \endcode
-
- If you chose some other protocol, specify one of the alternative
- formats:
-
- \code
- tcp:server=Server,port=Port[,password=Password][,ipversion=6]
- tcp:clicon=Server,port=Port[,password=Password][,ipversion=6]
- npipe:server=Server,pipe=PipeName[,password=Password]
- com:port=COMPort,baud=BaudRate,channel=COMChannel[,password=Password]
- spipe:proto=Protocol,{certuser=Cert|machuser=Cert},server=Server,pipe=PipeName[,password=Password]
- ssl:proto=Protocol,{certuser=Cert|machuser=Cert},server=Server,port=Socket[,password=Password]
- ssl:proto=Protocol,{certuser=Cert|machuser=Cert},clicon=Server,port=Socket[,password=Password]
- \endcode
-
- \o Click \gui{OK} to start debugging.
-
- \endlist
-
- \section2 Launching in Core Mode
-
- The core mode it used to debug \e {core} files (crash dumps) that are
- generated from crashed processes if the system is set up to allow this.
-
- To enable the dumping of core files on a Unix system enter the following
- command in the shell from which the application will be launched:
-
- \code
- ulimit -c unlimited
- \endcode
-
- To launch the debugger in the core mode, select
- \gui{Debug > Start Debugging > Attach to Core...}.
-
- \section2 Launching in Post-Mortem Mode
-
- The post-mortem mode is available only on Windows, if you have installed
- the debugging tools for Windows.
-
- The Qt Creator installation program asks you whether you want to
- register Qt Creator as a post-mortem debugger. To change the setting, select
- \gui{Tools > Options... > Debugger > Common > Use Creator for post-mortem debugging}.
-
- You can launch the debugger in the post-mortem mode if an application crashes
- on Windows. Click the \gui {Debug in Qt Creator} button in the error message
- that is displayed by the Windows operating system.
-
- \section2 Launching in On-device Mode
-
- The on-device mode is a special mode available for run configurations
- targeting mobile devices. It debugs processes running on mobile
- devices using on-device debugging agents, such as CODA on Symbian and
- gdbserver on Linux-based devices.
-
- To launch the debugger in the on-device mode, open the project, select a
- run configuration that targets a mobile device, and click the
- \gui {Start Debugging} button.
-
-*/
-
-/*!
- \contentspage index.html
- \previouspage creator-debug-mode.html
- \page creator-debugger-engines.html
- \nextpage creator-debugging-helpers.html
-
- \title Setting Up Debugger
-
- \note The information in this section applies only to debugging the C++
- language.
-
- Typically, the interaction between Qt Creator and the native debugger is set
- up automatically and you do not need to do anything. However, you might have an
- unsupported GDB version installed, your Linux environment might not have GDB
- installed at all, or you might want to use the debugging tools for Windows.
-
- \note To use the debugging tools for Windows, you must install them and add the
- Symbol Server provided by Microsoft to the symbol search path of the debugger.
- For more information, see \l{Setting the Symbol Server in Windows}.
-
- \note To use the Free Software Foundation (FSF) GDB on Mac OS, you must
- sign it and add it to Qt Creator as a tool chain.
-
- 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. Use a Python enabled
- version if one is available.
- On Windows, Symbian, Maemo, and MeeGo Harmattan, only the Python version is
- supported.
-
- The non-Python versions use the compiled version of the debugging helpers,
- that you must enable separately. For more information, see
- \l{Debugging Helpers Based on C++}.
-
- The Python version uses a script version of the debugging helpers
- that does not need any special setup.
-
- The CDB native debugger has similar funtionality to the non-Python GDB debugger
- engine. Specifically, it also uses compiled C++ code for the debugging
- helper library.
-
- The following table summarizes the support for debugging C++ code:
-
- \table
- \header
- \o Platform
- \o Compiler
- \o Native Debugger
- \o Python
- \o Debugger Modes
- \row
- \o Linux
- \o GCC
- \o GDB
- \o Yes
- \o Plain, Terminal, Attach, Remote, Core
- \row
- \o Unix
- \o GCC
- \o GDB
- \o Yes
- \o Plain, Terminal, Attach, Remote, Core
- \row
- \o Mac OS/GDB
- \o GCC
- \o GDB
- \o No
- \o Plain, Terminal, Attach, Core
- \row
- \o Mac OS/FSF GDB (experimental)
- \o GCC
- \o FSF GDB
- \o Yes
- \o Plain, Terminal, Attach, Core
- \row
- \o Windows/MinGW
- \o GCC
- \o GDB
- \o Yes
- \o Plain, Terminal, Attach, Remote, Core
- \row
- \o Windows/MSVC
- \o Microsoft Visual C++ Compiler
- \o Debugging Tools for Windows/CDB
- \o Not applicable
- \o Plain, Terminal, Attach, Post-Mortem
- \row
- \o Symbian
- \o GCC
- \o GDB
- \o Yes
- \o On-device
- \row
- \o Maemo
- \o GCC
- \o GDB
- \o Yes
- \o On-device
- \row
- \o MeeGo Harmattan
- \o GCC
- \o GDB
- \o Yes
- \o On-device
- \endtable
-
- For more information on the debugger modes, see \l{Launching the Debugger in Different Modes}.
-
- \omit
-
- \section2 GDB Adapter Modes
-
- [Advanced Topic]
-
- The GDB native debugger used internally by the debugger plugin runs in
- different adapter modes to cope with the variety
- of supported platforms and environments. All GDB adapters inherit from
- AbstractGdbAdapter:
-
- \list
-
- \o PlainGdbAdapter debugs locally started GUI processes.
- It is physically split into parts that are relevant only when Python is
- available, parts relevant only when Python is not available, and mixed code.
-
- \o TermGdbAdapter debugs locally started processes that need a
- console.
-
- \o AttachGdbAdapter debugs local processes started outside Qt Creator.
-
- \o CoreGdbAdapter debugs core files generated from crashes.
-
- \o RemoteGdbAdapter interacts with the gdbserver running on Linux.
-
- \o CodaGdbAdapter interacts with Symbian devices. The GDB protocol and
- the GDB serial protocol are used between GDB and the adapter. The
- target communication framework (TCF) protocol is used between the
- adapter and the CODA debugging agent running on the device.
-
- \endlist
-
- \endomit
-
- \section1 Installing Native Debuggers
-
- There are various reasons why the debugger plugin may fail to automatically
- pick up a suitable native debugger. The native debugger might be missing
- (which is usually the case for the CDB debugger on Windows which always
- needs to be installed manually by the user) or the installed version is not
- supported.
- Check the table below for the supported versions and other important
- information about installing native debuggers.
-
- \table
- \header
- \o Native Debugger
- \o Notes
- \row
- \o GDB
- \o On Linux and Windows, use the Python-enabled GDB versions that
- are installed when you install Qt Creator and Qt SDK. On Mac OS X,
- use the GDB provided with Xcode.
- For a custom target, you can build your own Python-enabled GDB.
- Follow the instructions on
- \l{http://developer.qt.nokia.com/wiki/QtCreatorBuildGdb}{Building GDB}.
- You must use at least Python version 2.5, but we recommend that you
- use version 2.6.
-
- \row
- \o Debugging tools for Windows
- \o Using this engine requires you to install the
- \e{Debugging tools for Windows}
- \l{http://www.microsoft.com/whdc/devtools/debugging/installx86.Mspx}
- or
- \l{http://www.microsoft.com/whdc/devtools/debugging/install64bit.Mspx}
- package (Version 6.12 for the 32-bit or the 64-bit version
- of Qt Creator, respectively),
- which are freely available for download from the
- \l{http://msdn.microsoft.com/en-us/default.aspx}{Microsoft Developer Network}.
-
- The Qt Creator help browser does
- not allow you to download files, and therefore, you must copy
- the above links to a browser.
-
- \note Visual Studio does not include the Debugging tools needed,
- and therefore, you must install them separately.
-
- The pre-built \QSDK for Windows makes use of the library if it
- is present on the system. When manually building Qt Creator using
- the Microsoft Visual C++ Compiler, the build process checks for the
- required files in \c{"%ProgramFiles%\Debugging Tools for Windows"}.
-
- It is highly recommended that you add the Symbol Server provided
- by Microsoft to the symbol search path of the debugger. The Symbol
- Server provides you with debugging informaton for the operating
- system libraries for debugging Windows applications. For more
- information, see \l{Setting the Symbol Server in Windows}.
-
- \row
- \o Debugging tools for Mac OS X
- \o The Qt binary distribution contains both debug and release
- variants of the libraries. But you have to explicitly tell the
- runtime linker that you want to use the debug libraries even if
- your application is compiled as debug, as release is the default
- library.
-
- If you use a qmake based project in Qt Creator, you can set a
- flag in your run configuration, in \gui Projects mode. In the run
- configuration, select \gui{Use debug version of frameworks}.
-
- For more detailed information about debugging on the Mac OS X, see:
- \l{http://developer.apple.com/library/mac/#technotes/tn2124/_index.html#//apple_ref/doc/uid/DTS10003391}
- {Mac OS X Debugging Magic}.
-
- You can download an experimental version of FSF GDB that
- supports Python from
- \l{ftp://ftp.qt.nokia.com/misc/gdb/7.2/gdb72_mac_platform.tar.bz2}.
- To use FSF GDB on Mac OS, you must sign it and add it to the Qt
- Creator tool chains. For more information, see
- \l{Setting up FSF GDB for Mac OS}.
-
- \note The Mac OS X Snow Leopard (10.6) has a bug that might cause the
- application to crash. For a workaround, see:
- \l{https://bugreports.qt.nokia.com/browse/QTBUG-4962}{QTBUG-4962}.
-
- \endtable
-
- \section1 Setting the Symbol Server in Windows
-
- To obtain debugging information for the operating system libraries for
- debugging Windows applications, add the Symbol Server provided
- by Microsoft to the symbol search path of the debugger:
- \list 1
- \o Select \gui Tools > \gui{Options...} > \gui Debugger > \gui CDB.
- \o In the \gui {Symbol paths} field, open the \gui{Insert...} menu
- and select \gui{Symbol Server...}.
- \o Select a directory where you want to store the cached information
- and click \gui OK.
-
- Use a subfolder in a temporary directory, such as
- \c {C:\temp\symbolcache}.
- \endlist
-
- \note Populating the cache might take a long time on a slow network
- connection.
-
- \note The first time you start debugging by using the
- Debugging tools for Windows, Qt Creator prompts you to add the Symbol
- Server.
-
- \section1 Setting up FSF GDB for Mac OS
-
- To use FSF GDB on Mac OS, you must sign it and add it to the Qt Creator tool
- chains.
-
- \list 1
-
- \o To create a key for signing FSF GDB, select \gui {Keychain Access >
- Certificate Assistant > Create a Certificate}:
-
- \list 1
-
- \o In the \gui {Certificate Type} field, select \gui {Code Signing}.
-
- \o Select the \gui {Let me override defaults} check box.
-
- \o Select \gui Continue, and follow the instructions of the
- wizard (use the default settings), until the \gui {Select a
- Location for the Certificate} dialog opens.
-
- \o In the \gui Keychain field, select \gui System.
-
- \o Select \gui {Keychain Access > System}, and locate the
- certificate.
-
- \o Double click the certificate to view certificate information.
-
- \o In the \gui Trust field, select \gui {Always Trust}.
-
- \endlist
-
- \o To sign the binary, enter the following command in the terminal,
- where $USER is the name of the certificate (which is the same as the
- user name, by default):
-
- \code
- codesign -f -s "$USER" $INSTALL_LOCATION/fsfgdb
- \endcode
-
- \o In Qt Creator, select \gui {Tools > Preferences\85 > Tool Chains}, to
- add a tool chain that uses the debugger:
-
- \list 1
-
- \o Select a native tool chain (usually, a x86 64-bit tool chain)
- and click \gui Clone to clone it.
-
- \o In the \gui Debugger field, specify the path to FSF GDB
- (\c $HOME/gdb72/bin/fsfgdb, but with an explicit value for
- \c $HOME).
-
- \endlist
-
- \o To use the debugger, select the tool chain in the \gui {Tool chain}
- field in the \gui {Build Settings} of the project.
-
- \endlist
-
-*/
-
-/*!
- \contentspage index.html
- \previouspage creator-debugger-operating-modes.html
- \page creator-debug-mode.html
- \nextpage creator-debugger-engines.html
-
- \title Interacting with the Debugger
-
- In \gui Debug mode, you can use several views to interact with the
- program you are debugging. The availability of views depends on whether
- you are debugging C++ or QML. Frequently used views are shown by
- default and rarely used ones are hidden. To change the default settings,
- select \gui {Window > Views}, and then select views to display or hide.
-
- \image qtcreator-debugger-views.png "Debug mode views"
-
- By default, the views are locked into place in the workspace. Select
- \gui {Window > Views > Locked} to unlock the views. Drag and drop the
- views into new positions on the screen. Drag view borders to resize the
- views. The size and position of views are saved for future sessions. Select
- \gui {Window > Views > Reset to Default Layout} to reset the views to
- their original sizes and positions.
-
- \section1 Using the Debugger
-
- Once the program starts running under the control of the debugger, it
- behaves and performs as usual. You can interrupt a running C++ program by
- selecting \gui{Debug} > \gui {Interrupt}. The program is automatically
- interrupted when a breakpoint is hit.
-
- Once the program stops, Qt Creator:
-
- \list
- \o Retrieves data representing the call stack at the program's current
- position.
- \o Retrieves the contents of local variables.
- \o Examines \gui Expressions.
- \o Updates the \gui Registers, \gui Modules, and \gui Disassembler
- views if you are debugging the C++ based applications.
- \endlist
-
- You can use the \gui Debug mode views to examine the data in more detail.
-
- You can use the following keyboard shortcuts:
-
- \list
-
- \o To finish debugging, press \key{Shift+F5}.
- \o To execute a line of code as a whole, press \key{F10}.
- \o To step into a function or a subfunction, press \key{F11}.
- \o To continue running the program, press \key{F5}.
- \o To run to the selected function when you are stepping into a nested
- function, press \key{Ctrl+F6}.
-
- \endlist
-
- It is also possible to continue executing the program until the current
- function completes or jump to an arbitrary position in the current function.
-
-
- \section1 Setting Breakpoints
-
- A breakpoint represents a position or sets of positions in the code that,
- when executed, interrupts the program being debugged and passes the control
- to you. You can then examine the state of the interrupted program, or
- continue execution either line-by-line or continuously.
-
- Qt Creator shows breakpoints in the \gui{Breakpoints} view which is enabled
- by default. The \gui{Breakpoints} view is also accessible when the debugger
- and the program being debugged is not running.
-
- \image qtcreator-debug-breakpoints.png "Breakpoints view"
-
- You can associate breakpoints with:
-
- \list
-
- \o Source code files and lines
-
- \o Functions
-
- \o Addresses
-
- \o Throwing and catching exceptions
-
- \o Executing and forking processes
-
- \o Executing some system calls
-
- \o Changes in a block of memory at a particular address when a
- program is running
-
- \endlist
-
- The interruption of a program by a breakpoint can be restricted with
- certain conditions.
-
- To set a breakpoint at a particular line you want the program to stop,
- click the left margin or press \key F9 (\key F8 for Mac OS X).
-
- To set breakpoints, select \gui {Add Breakpoint...} in
- the context menu in the \gui Breakpoints view.
-
- \image qtcreator-add-breakpoint.png "Add Breakpoints" dialog
-
- \note You can remove a breakpoint:
- \list
- \o By clicking the breakpoint marker in the text editor.
- \o By selecting the breakpoint in the breakpoint view and pressing
- \key{Delete}.
- \o By selecting \gui{Delete Breakpoint} from the context
- menu in the \gui Breakpoints view.
- \endlist
-
- You can set and delete breakpoints before the program starts running or
- while it is running under the debugger's control. Breakpoints are saved
- together with a session.
-
- \section2 Setting Data Breakpoints
-
- To set a data breakpoint at an address:
-
- \list 1
-
- \o Right-click in the \gui Breakpoints view to open the context menu,
- and select \gui {Add Breakpoint...}.
-
- \o In the \gui {Breakpoint type} field, select \gui {Break on data
- access at fixed address}.
-
- \o In the \gui Address field, specify the address of the memory block.
-
- \o Select \gui OK.
-
- \endlist
-
- If the address is displayed in the \gui {Locals and Expressions} view, you can
- select \gui {Add Data Breakpoint at Object's Address} in the context menu to set
- the data breakpoint.
-
- \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 Expressions}
- view, making it seem like the program was interrupted before entering the
- function.
-
- \section1 Locals and Expressions
-
- 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 Expressions} view. The \gui{Locals and Expressions} view
- typically includes information about parameters of the function in that
- frame as well as the local variables.
-
- \image qtcreator-locals-expressions.png "Locals and Expressions 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 Expressions} 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 Expressions} 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 Expressions} 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 Expressions} view to change the contents of
- variables of simple data types, for example, \c int or \c float when the
- program is interrupted. To do so, click the \gui Value column, modify
- the value with the inplace editor, and press \key Enter (or \key Return).
-
- You can enable tooltips in the main editor displaying this information.
- For more information, see \l{Showing Tooltips in Debug Mode}.
-
- \note The set of evaluated expressions is saved in your session.
-
- \section1 Directly Interacting with Native Debuggers
-
- In some cases, it is convenient to directly interact with the command
- line of the native debugger. In Qt Creator, you can use the left
- pane of the \gui {Debugger Log} view for that purpose. When you press
- \key {Ctrl+Return}, the contents of the line under the text cursor
- are sent directly to the native debugger. Alternatively, you
- can use the line edit at the bottom of the view. Output is displayed in the
- right pane of the \gui {Debugger Log} view.
-
- \note Usually, you do not need this feature, because Qt Creator provides
- you with better ways to handle the task. For example, instead of using the
- GDB \c print command from the command line, you can evaluate an expression
- in the \gui{Locals and Expressions} view.
-
- \section1 Debugging C++ Based Applications
-
- The following sections describe additional debugging functions that apply
- only to debugging C++.
-
- \section2 Starting the Debugger from the Command Line
-
- You can use the Qt Creator debugger interface from the command line. To
- attach it to a running process, specify the process ID as a parameter for
- the \c {-debug} option. To examine a core file, specify the file name.
- Qt Creator executes all the necessary steps, such as searching for
- the binary that belongs to a core file.
-
- For example:
-
- \list
-
- \o \c {C:\qtcreator\bin>qtcreator -debug 2000}
-
- \o \c {C:\qtcreator\bin>qtcreator -debug core.2000}
-
- \endlist
-
- For more information, see \l{Using Command Line Options}.
-
- \section2 Stepping into Frameworks in Mac OS
-
- In Mac OS X, external libraries are usually built into so-called Frameworks,
- which may contain both release and debug versions of the library. When you run
- applications on the Mac OS desktop, the release version of Frameworks is used
- by default. To step into Frameworks, select the \gui {Use debug versions of
- Frameworks} option in the project run settings for \gui Desktop and
- \gui {Qt Simulator} targets.
-
- \section2 Viewing Threads
-
- If a multi-threaded program is interrupted, the \gui Thread view or the
- combobox named \gui Thread in the debugger's status bar can be used to
- switch from one thread to another. The \gui Stack view adjusts itself
- accordingly.
-
- \section2 Viewing Modules
-
- The \gui{Modules} view displays information that the debugger plugin has
- about modules included in the application that is being debugged. A module
- is a dynamic link library (.dll) in Windows, a shared object (.so) in
- Linux, and a dynamic shared library (.dylib) in Mac OS.
-
- In addition, the view displays symbols within the modules and indicates
- where each module was loaded.
-
- Right-click the view to open a context menu that contains menu items for:
-
- \list
-
- \o Updating the module list
-
- \o Loading symbols for modules
-
- \o Examining modules
-
- \o Editing module files
-
- \o Showing symbols in modules
-
- \o Showing dependencies between modules (Windows only)
-
- \endlist
-
- By default, the \gui{Modules} view is hidden.
-
- \section2 Viewing Source Files
-
- The \gui{Source Files} view lists all the source files included in the project.
- If you cannot step into an instruction, you can check whether the source file is
- actually part of the project, or whether it was compiled
- elsewhere. The view shows the path to each file in the file system.
-
- Right-click the view to open a context menu that contains menu items for
- reloading data and opening files.
-
- By default, the \gui{Source Files} view is hidden.
-
-
- \section2 Viewing Disassembled Code and Register State
-
- The \gui{Disassembler} view displays disassembled code for the current
- function. The \gui{Registers} view displays the current state of the CPU's
- registers.
-
- The \gui{Disassembler} view and the \gui{Registers} view are both useful
- for low-level commands for checking single instructions, such as \gui{Step Into}
- and \gui{Step Over}. By default, both \gui{Disassembler} and
- \gui{Registers} view are hidden.
-
-*/
-
-
-/*!
- \contentspage index.html
- \previouspage creator-debugging.html
- \page creator-debugging-example.html
- \nextpage creator-debugger-operating-modes.html
-
- \title Debugging the Example Application
-
- This section uses the \l{Creating a Qt Widget Based Application}{TextFinder} example to
- illustrate how to debug Qt C++ applications in the \gui Debug mode.
-
- TextFinder reads a text file into QString and then displays it with
- QTextEdit. To look at the TextFinder class and see the stored data, place
- a breakpoint in textfinder.cpp, as follows:
-
- \list 1
- \o Click in between the line number and the window border on the line
- where we change the cursor position 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 base classes and data members of the TextFinder class,
- go to the \gui{Locals and Expressions} view.
-
- \image qtcreator-watcher.png
-
- \endlist
-
- Modify the \c{on_findButton_clicked()} function to move back to
- the start of the document and continue searching once the cursor hits the
- end of the document. Add the following code snippet:
-
- \code
- void TextFinder::on_findButton_clicked()
- {
- QString searchString = ui->lineEdit->text();
-
- QTextDocument *document = ui->textEdit->document();
- QTextCursor cursor = ui->textEdit->textCursor();
- cursor = document->find(searchString, cursor,
- QTextDocument::FindWholeWords);
- ui->textEdit->setTextCursor(cursor);
-
- bool found = cursor.isNull();
-
- if (!found && previouslyFound) {
- int ret = QMessageBox::question(this, tr("End of Document"),
- tr("I have reached the end of the document. Would you like "
- "me to start searching from the beginning of the document?"),
- QMessageBox::Yes | QMessageBox::No, QMessageBox::Yes);
-
- if (ret == QMessageBox::Yes) {
- cursor = document->find(searchString,
- QTextDocument::FindWholeWords);
- ui->textEdit->setTextCursor(cursor);
- } else
- return;
- }
- previouslyFound = found;
- }
- \endcode
-
- If you compile and run the above code, however, the application does not
- work correctly due to a logic error. To locate this logic error, step
- through the code using the following buttons:
-
- \image qtcreator-debugging-buttons.png
-
- */
-
-
-/*!
- \contentspage index.html
- \previouspage creator-debugger-engines.html
- \page creator-debugging-helpers.html
- \nextpage creator-debugging-qml.html
-
- \title Using Debugging Helpers
-
- Qt Creator is able to show complex data types in a customized,
- user-extensible manner. For this purpose, it takes advantage of
- two technologies, collectively referred to as \e{Debugging Helpers}.
-
- Using the debugging helpers is not \e essential for debugging
- with Qt Creator, but they enhance the user's ability to quickly
- examine complex data significantly.
-
- \section1 Debugging Helpers Based on C++
-
- This is the first and original approach to display complex data
- types. While it has been superseded on most platforms by the more
- robust and more flexible second approch using Python scripting,
- it is the only feasible one on Windows/MSVC, Mac OS, and
- old Linux distributions. Moreover, this approach will automatically
- be chosen as fallback in case the Python based approach fails.
-
- During debugging with the C++ based debugging helpers,
- Qt Creator dynamically loads a helper library in form of a DLL or a
- shared object into the debugged process.
- The \QSDK package already contains a prebuilt debugging helper
- library. To create your own debugging helper library, select \gui{Tools} >
- \gui{Options...} > \gui{Qt4} > \gui{Qt Versions}. As the internal data
- structures of Qt can change between versions, the debugging helper
- library is built for each Qt version.
-
-
- \section1 Debugging Helpers Based on Python
-
- Qt Creator uses GDB builds that enable Python scripting to display
- information in the \gui {Locals and Expressions} view. When Python scripting
- is used, code (Debugging helpers) does not need to be injected into the
- debugged process to nicely display QStringList or \c std::map contents, for
- example.
-
- The code injection caused problems and put an extra stress on the debugged
- process. You can now easily extend the debugging helpers to other types. No
- compilation is required, just adding a few lines of Python.
-
- Python scripting vastly reduces the communication overhead compared
- with the previous solution. However, there are some obstacles:
-
- \list
-
- \o There is no Python-enabled GDB for Mac OS. Mac OS continues
- injection with C++ based debugging helpers.
-
- \o On the Symbian platform, an on-device debugging agent restricts the
- communication between GDB and the device. Therefore, extracting
- QObject properties, for example, is not possible.
-
- \o There is no GDB to communicate with MSVC compiled applications on
- Windows. So information can be displayed nicely only in a limited
- fashion by using a cdb extension DLL.
-
- \endlist
-
- \section2 Extending the Python Based Debugging Helpers
-
- On platforms featuring a Python-enabled version of the GDB debugger,
- the data extraction is done by a Python script. This is more robust
- as the script execution is separated from the debugged process. It
- is also easier to extend as the script is less dependent on the
- actual Qt version and does not need compilation.
-
- To extend the shipped Python based debugging helpers for custom types,
- define one Python function per user defined type in the
- GDB startup file. By default, the following startup file is used:
- \c{~/.gdbinit}. To use another file, select \gui {Tools > Options... >
- Debugger > GDB}
- and specify a filename in the \gui {GDB startup script} field.
-
- The function name has to be qdump__NS__Foo, where NS::Foo is the class
- or class template to be examined. Nested namespaces are possible.
-
- The debugger plugin calls this function whenever you want to
- display an object of this type. The function is passed the following
- parameters:
- \list
- \o \c d of type \c Dumper
- \o \c value of type \c gdb.Value
- \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 Expressions} view.
-
-
- Example:
-
- \code
- def qdump__QVector(d, value):
- d_ptr = value["d"]
- p_ptr = value["p"]
- alloc = d_ptr["alloc"]
- size = d_ptr["size"]
-
- check(0 <= size and size <= alloc and alloc <= 1000 * 1000 * 1000)
- checkRef(d_ptr["ref"])
-
- innerType = templateArgument(value.type, 0)
- d.putItemCount(size)
- d.putNumChild(size)
- if d.isExpanded():
- p = gdb.Value(p_ptr["array"]).cast(innerType.pointer())
- charPtr = lookupType("char").pointer()
- d.putField("size", size)
- with Children(d, size, maxNumChild=2000, childType=innerType, addrBase=p,
- addrStep=(p+1).cast(charPtr) - p.cast(charPtr)):
- for i in d.childRange():
- d.putSubItem(i, p.dereference())
- p += 1
- \endcode
-
- \section2 Dumper Class
-
- For each line in the \gui{Locals and Expressions} view, a string like the
- following needs to be created and channeled to the debugger plugin.
- \code
- "{iname='some internal name', # optional
- addr='object address in memory', # optional
- name='contents of the name column', # optional
- 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
-
- The value of the \gui{iname} field is 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. If it is not
- present, is it generated by concatenating the parent object's iname,
- a dot, and a sequential number.
-
- The value of the\gui{name} field is displayed in the \gui{name} column
- of the view. If it is not specified, a simple number in brackets
- is used instead.
-
- 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 member functions of the \gui{Dumper} class are the following:
-
- \list
-
- \o \gui{__init__(self)} - Initializes the output to an empty string and
- empties the child stack. This should not be used in user code.
-
- \o \gui{put(self, value)} - Low level method to directly append to the
- output string. That is also the fastest way to append output.
-
- \o \gui{putField(self, name, value)} - Appends a name='value' field.
-
- \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, priority=0)} - Appends a field \c {type='...'}
- unless the \a type coincides with the parent's default child type or
- \c putType was already called for the current item with a higher
- value of \c priority.
-
- \o \gui{putBetterType(self, type)} - Overrides the last recorded \c 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()} - Checks whether the current item
- is expanded in the view.
-
- \o \gui{putIntItem(self, name, value)} - Equivalent to:
- \code
- with SubItem(self, name):
- self.putValue(value)
- self.putAddress(value.address)
- self.putType("int")
- self.putNumChild(0)
- \endcode
-
- \o \gui{putBoolItem(self, name, value)} - Equivalent to:
- \code
- with SubItem(self, name):
- self.putValue(value)
- self.putType("bool")
- self.putNumChild(0)
- \endcode
-
- \o \gui{putCallItem(self, name, value, func, *args)} -
- Uses GDB to call the function \c func on the value specified by
- \a {value} and output the resulting item. This function is
- not available when debugging core dumps and it is not available
- on the Symbian platform due to restrictions imposed by the on-device
- debugging agent.
-
- \o \gui{putItem(self, value)} - The "master function", handling
- basic types, references, pointers and enums directly, iterates
- over base classes and class members of compound types and calls
- \c qdump__* functions whenever appropriate.
-
- \o \gui{putSubItem(self, component, value)} - Equivalent to:
- \code
- with SubItem(self, component):
- self.putItem(value)
- \endcode
- Exceptions raised by nested function calls are caught and all
- output produced by \c putItem is replaced by the output of:
- \code
- ...
- except RuntimeError:
- d.put('value="<invalid>",type="<unknown>",numchild="0",')
- \endcode
-
- \endlist
-
-
- \section2 Children and SubItem Class
-
- The attempt to create child items might lead to errors if data is
- uninitialized or corrupted. To gracefully recover in such situations,
- use \c Children and \c SubItem \e{Context Managers} to create the nested items.
-
- The \c Children constructor \gui{__init__(self, dumper, numChild = 1,
- childType = None, childNumChild = None, maxNumChild = None, addrBase = None,
- addrStep = None)} uses one mandatory argument and several
- 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 maxNumChild is specified, only that many children are displayed.
- This should be used when dumping container contents that might take
- overly long otherwise. The parameters \c addrBase and \c addrStep
- can be used to reduce the amount of data produced by the child dumpers.
- Address printing for the \e{n}th child item will be suppressed if its address
- equals with \e{addrBase + n * addrStep}.
-
- Example:
- \code
- d.putNumChild(2) # Annouce children to make the item expandable in the view.
- if d.isExpanded():
- with Children(d):
- with SubItem(d):
- d.putName("key")
- d.putItem(key)
- with SubItem(d):
- d.putName("value")
- d.putItem(value)
- \endcode
-
- Note that this can be written more conveniently as:
- \code
- d.putNumChild(2)
- if d.isExpanded():
- with Children(d):
- d.putSubItem("key", key)
- d.putSubItem("value", value)
- \endcode
-
-
- \section1 Debugging Helpers for QML
-
- The debugging helpers for QML provide you with code completion for custom modules
- (\c qmldump) and debugging Qt Quick UI projects (\c qmlobserver).
-
- You have to build the QML Inspector once for each Qt version that you want
- to debug
- with. Select \gui{Tools > Options... > Qt4 > Qt Versions}.
-
- \note QML Inspector requires Qt 4.7.1 or later.
-
- \section1 Enabling Debugging Helpers for Qt's Bootstrapped Applications
-
- Qt's bootstrapped applications (such as moc and qmake) are built in a way
- that is incompatible with the default build of the debugging helpers. To
- work around this, add \c{dumper.cpp} to the compiled sources in the
- application Makefile.
-
- Choose \gui {Tools > Options > Debugger > Debugging Helper > Use debugging
- helper from custom location}, and specify an invalid location, such as
- \c{/dev/null}.
-
-*/
-
-
-/*!
- \contentspage index.html
- \previouspage creator-project-wizards.html
- \page creator-project-cmake.html
- \nextpage creator-project-generic.html
-
- \title Setting Up a CMake Project
-
- CMake is an alternative to qmake for automating the generation of build
- configurations.
- It controls the software compilation process by using simple configuration
- files, called CMakeLists.txt files. CMake generates native build
- configurations and
- workspaces that you can use in the compiler environment of your choice.
-
- Since Qt Creator 1.1, CMake configuration files are supported.
- Qt Creator 1.3 supports the Microsoft tool chain if the CMake version
- is at least 2.8.
-
- \section1 Setting the Path for CMake
-
- You can set the path for the \c CMake executable in \gui{Tools} >
- \gui{Options... > Projects > CMake}.
-
- \image qtcreator-cmakeexecutable.png
-
- \note Before you open a \c CMake project it is necessary to modify the
- \c{PATH} environment variable to include the bin folders of \c mingw and
- Qt Creator in the SDK.
-
- For instance, if you have the Qt SDK installed in your C drive,
- use the following command to set the environment variables in
- the command line prompt:
- \code
- set PATH=C:\qtsdk\mingw\bin;C:\qtsdk\qt\bin;
- \endcode
- Then start Qt Creator by typing:
- \code
- C:\qtsdk\bin\qtcreator.exe
- \endcode
-
- \section1 Opening CMake Projects
-
- To open a \c CMake project:
- \list 1
- \o Select \gui{File} > \gui{Open File or Project...}.
- \o Select the \c{CMakeLists.txt} file from your \c CMake project.
- \endlist
-
- A wizard guides you through the rest of the process.
-
- \note If the \c CMake project does not have an in-place build, Qt Creator
- lets you specify the directory in which the project is built
- (\l{glossary-shadow-build}{shadow build}).
-
- \image qtcreator-cmake-import-wizard1.png
-
- The screenshot below shows how you can specify command line arguments to
- \c CMake for your project.
-
- \image qtcreator-cmake-import-wizard2.png
-
- Normally, there is no need to pass any command line arguments for projects
- that are already built, as \c CMake caches that information.
-
-
- \section1 Building CMake Projects
-
- Qt Creator builds \c CMake projects by running \c make, \c mingw32-make, or
- \c nmake depending on your platform. The build errors and warnings are
- parsed and displayed in the \gui{Build Issues} output pane.
-
- By default, Qt Creator builds the \bold{all} target. You can specify which
- targets to build in \gui{Project} mode, under \gui{Build Settings}.
-
- \image qtcreator-cmake-build-settings.png
-
- Qt Creator supports multiple build configurations. The build
- directory can also be modified after the initial import.
-
- \section1 Running CMake Projects
- Qt Creator automatically adds \gui{Run Configurations} for all targets
- specified in the \c CMake project file.
-
- Known issues for the current version can be found
- \l{Known Issues}{here}.
-
-
- \section1 Adding External Libraries to CMake Projects
-
- Through external libraries Qt Creator can support code completion and
- syntax highlighting as if they were part of the current project or the Qt
- library.
-
- Qt Creator detects the external libraries using the \c FIND_PACKAGE()
- macro. Some libraries come with the CMake installation. You can find those
- in the \bold{Modules} directory of your CMake installation.
-
- \note If you provide your own libraries, you also need to provide your own
- \c FindFoo.cmake file. For more information, see
- \l{http://vtk.org/Wiki/CMake_FAQ#Writing_FindXXX.cmake_files}{CMake FAQ}.
-
- Syntax completion and highlighting work once your project successfully
- builds and links against the external library.
-*/
-
-
-/*!
- \contentspage index.html
- \previouspage creator-debugging-helpers.html
- \page creator-debugging-qml.html
- \nextpage creator-troubleshooting-debugging.html
-
- \title Debugging Qt Quick Projects
-
- \note You need Qt 4.7.1 or later to debug Qt Quick projects. Debugging projects
- not created with the Qt Quick wizards is only supported with Qt 4.8, or later.
-
- To debug Qt Quick applications running on devices, you must install
- Qt 4.7.4, or later, libraries on devices. To debug applications on Symbian
- devices, you must install also QML Viewer on them.
-
- \section1 Setting Up QML Debugging
-
- The process of setting up debugging for Qt Quick projects depends on the type of
- the project: Qt Quick UI or Qt Quick Application.
-
- To debug Qt Quick UI projects:
-
- \list 1
-
- \o Select \gui Projects, and then select the \gui QML check box in the
- \gui {Run Settings}, to enable QML debugging.
-
- \o Compile the QML Inspector debugging helper. For more information, see
- \l{Debugging Helpers for QML}.
-
- \endlist
-
- To debug Qt Quick Applications:
-
- \list 1
-
- \o Select \gui Projects, and then select the \gui {Link QML debugging
- library} check box in \gui {Build Steps}.
-
- You might have to compile the library first, by selecting the
- \gui Compile link.
-
- \image qml-link-debugging-library.png "Build Steps"
-
- \note Debugging requires opening a socket at a well-known port, which
- presents a security risk. Anyone on the Internet could connect to the
- application that you are debugging and execute any JavaScript
- functions. Therefore, you must make sure that the port is properly
- protected by a firewall.
-
- \o In the \gui {Run Settings}, select the \gui QML check box to enable
- QML debugging.
-
- \o Select \gui {Build > Rebuild Project} to clean and rebuild the
- project.
-
- \endlist
-
- To debug Qt Quick Applications on devices, install Qt 4.7.4, or later,
- libraries on devices. Then select the device as the target before you
- start debugging.
-
- \section1 Mixed C++/QML Debugging
-
- You can debug both the C++ and QML parts of your application at the same time:
- Select the checkboxes for both languages in the \gui{Run Settings}. However,
- C++ breakpoints will be ignored until the debugger has attached also to the QML
- engine.
-
- \section1 Starting QML Debugging
-
- To start the application, choose \gui {Debug > Start Debugging
- > Start Debugging} or press \key F5. Once the application starts running, it behaves
- and performs as usual. You can then perform the following tasks:
-
- \list
-
- \o Debug JavaScript functions
-
- \o Preview QML changes at runtime
-
- \o Inspect QML at runtime
-
- \endlist
-
- \section1 Debugging JavaScript Functions
-
- You can use the Qt Creator \gui Debug mode to inspect the state of your
- application while debugging. You can interact with the debugger in several
- ways, as described in the following sections:
-
- \list
-
- \o \l{Setting Breakpoints}
-
- \o \l{Viewing Call Stack Trace}
-
- \o \l{Locals and Expressions}
-
- \endlist
-
- \section1 Executing JavaScript Expressions
-
- When the application is interrupted by a breakpoint, you can use the \gui {QML
- Script Console} to execute JavaScript expressions in the current context. To
- open it, choose \gui {Window > View > QML Script Console}.
-
- \image qml-script-console.png "QML Script Console view"
-
- You can type JavaScript expressions and use them to get information about the
- state or your application. For example, property values.
-
- You can see the current value of a property by hovering over it in the code editor.
-
- \section1 Applying QML Changes at Runtime
-
- If you change property values or add properties in the code editor, the changes
- are updated in the running application when you save them. If live preview is not supported
- for an element, a message appears. Click \gui Reload to preview the changes.
-
- Reloading is enabled by default. To disable it, click
- \inlineimage qml-observer-bar-reload.png "Apply Changes on Save button"
- on the toolbar.
-
- \section1 Inspecting QML at Runtime
-
- While the application is running, you can use the \gui {QML Inspector} view to
- explore the object structure, debug animations, and inspect colors.
- To open the \gui {QML Inspector} view, choose \gui {Window > View >
- QML Inspector}.
- The view shows the properties of the currently selected QML element.
-
- \image qml-observer-view.png "QML Inspector view"
-
- When you debug complex applications, you can use the inspection
- mode to jump to the position in code where an element is defined. You are
- switched to the inspection mode, when you click the \gui Select, \gui Zoom,
- or \gui {Color Picker} button
- on the toolbar.
-
- \image qml-observer-buttons.png "QML Inspector toolbar"
-
- When the \gui Select tool is enabled, you can click elements in the running
- application to jump to their definitions in the code. The properties of the
- selected element are displayed in the \gui {QML Inspector} view. The element
- hierarchy is displayed as a bread crumb path.
-
- You can also right-click an element in the running application to view the element
- hierarchy as a context menu.
-
- \image qml-observer-context-menu.png "QML Inspector"
-
- To switch to the zoom mode, click the \gui Zoom button. Click in the
- running application to zoom in. Right-click to open a context menu that
- contains zoom controls.
-
- To inspect colors, click the \gui {Color Picker} button. You can also click
- \inlineimage qml-observer-bar-copy-color.png "Copy Color button"
- to copy the color definition to the clipboard.
-
- To switch out of the inspection mode, deselect the \gui Select, \gui Zoom,
- and \gui {Color Picker} button.
-
- To move the application running in \QQV to the front, select the
- \gui {Show Application on Top} button.
-
- \section1 Debugging Animations
-
- \image qml-observer.png
-
- To play and pause animations in the running application, select the
- \gui {Play/Pause Animations} button on the toolbar or \gui {Debugging >
- Animations > Pause}, or press
- \key {Ctrl+.}.
-
- To change the speed at which animations are played, select a value in \gui {Debugging
- > Animations} or click and hold down the \gui {Play/Pause Animations}
- button to select a value.
-
-*/
-
-
-/*!
- \contentspage index.html
- \previouspage creator-project-cmake.html
- \page creator-project-generic.html
- \nextpage creator-version-control.html
-
- \title Setting Up a Generic Project
-
- Qt Creator supports generic projects, so you can import existing projects
- that do not use qmake or CMake and Qt Creator ignores your build system.
-
- Generic project support allows you to use Qt Creator as a code editor. You
- can change the way your project is built by modifying the \c make command
- in the \gui{Projects} mode under \gui{Build Settings}.
-
- When you import a project, Qt Creator creates the following files that
- allow you to specify which files belong to your project and which include
- directories or defines you want to pass to your compile:
- \tt{.files}, \tt{.includes}, and \tt{.config}.
-
-
- \section1 Importing a Generic Project
-
- To import an existing generic project:
- \list 1
- \o Select \gui File > \gui{New File or Project...} >
- \gui{Other Project} > \gui{Import Existing Project}.
- \o In \gui{Import Existing Project}, enter the project name
- and select the location of the project file you want to import.
-
- Qt Creator automatically generates the following files in the
- project directory:
- \list
- \o \l{Specifying Files}{.files}
- \o \l{Specifying Include Paths}{.includes}
- \o \l{Specifying Defines}{.config}
- \o .creator
- \endlist
- \endlist
-
- When the project is successfully imported, Qt Creator creates the project
- tree in the sidebar.
-
- After importing a generic project into Qt Creator, open it by selecting the
- \tt{.creator} file.
-
-
- \section1 Working with Generic Project Files
-
- For a generic project, you have to manually specify which files belong to
- your project and which include directories or defines you want to pass to
- your compiler.
-
-
- \section1 Specifying Files
-
- The list of files for a generic project is specified in the \tt{.files}
- file. When you first create a generic project, Qt Creator adds any
- files it recognizes to your project.
-
- To add or remove files, edit the \tt{.files} file in Qt Creator.
- Qt Creator recreates your project tree when you save the \tt{.files} file.
- Alternatively, you can add and remove files using the context menu in the
- project tree.
-
- If you frequently need to update the \tt{.files} file, you can do so
- efficiently by using a script that updates the file for you. If the file
- is modified externally, you have to restart Qt Creator for the changes to
- take effect.
-
- To update the \tt{.files} on the \gui Git repository use the following
- script:
- \code
- git ls-files "*.cpp" "*.h" > MyProject.files
- \endcode
-
- \section1 Specifying Include Paths
-
- The include paths are specified in the \tt{.includes} file, one include
- path per line. The paths can be either absolute or relative to the
- \tt{.includes} file.
-
- \section1 Specifying Defines
-
- The defines are specified in the \tt{.config} file. The \tt{.config} file is
- a regular C++ file, prepended to all your source files when they are parsed.
- Only use the \tt{.config} file to add lines as in the example below:
-
- \code
- #define NAME value
- \endcode
-
-
- \section1 Creating a Run Configuration
-
- Qt Creator cannot automatically determine which executable to run.
-
- In the \gui{Projects} mode under \gui{Run Settings}, define the executable
- file to run:
- \list 1
- \o Click \gui Add and select \gui{Custom Executable}.
- \o Define the configuration name, the location of the executable, any
- additional arguments and the working directory.
- \endlist
-
-*/
-
-
-
-/*!
-
- \contentspage index.html
- \previouspage creator-design-mode.html
- \page creator-visual-editor.html
- \nextpage quick-projects.html
-
- \title Developing Qt Quick Applications
-
- You can either create Qt Quick projects from scratch or import existing projects to
- Qt Creator.
-
- You can use the code editor (\l{Using the Editor}{Edit mode}) or the visual editor
- (\l{Using Qt Quick Designer}{Design mode}) to develop Qt Quick applications.
-
- \image qtcreator-qt-quick-editors.png "Edit mode and Design mode"
-
- The following sections describe typical tasks you can do with Qt Creator.
-
- \list
-
- \o \l {Creating Qt Quick Projects}
- \o \l {Using Qt Quick Designer}
- \o \l {Creating Components}
- \o \l {Creating Buttons}
- \o \l {Creating Scalable Buttons and Borders}
- \o \l {Creating Screens}
- \o \l {Animating Screens}
- \o \l {Adding User Interaction Methods}
- \o \l {Exporting Designs from Graphics Software}
- \o \l {Implementing Application Logic}
- \o \l {Using QML Modules with Plugins}
-
- \endlist
-
-*/
-
-
-/*!
-
- \contentspage index.html
- \previouspage creator-visual-editor.html
- \page quick-projects.html
- \nextpage creator-using-qt-quick-designer.html
-
- \title Creating Qt Quick Projects
-
- \image qmldesigner-new-project.png "New File or Project dialog"
-
- When you create a new Qt Quick project from scratch, you have the following options:
-
- \list
-
- \o \gui {Qt Quick Application} creates a Qt Quick application project that can
- contain both QML and C++ code. The project includes a QDeclarativeView. You can build
- the application and deploy it on desktop and mobile target platforms. For example, you
- can create signed Symbian Installation System (SIS) packages for this type of projects.
-
- \o \gui {Qt Quick UI} creates a Qt Quick UI project with a single QML file that
- contains the main view. You can review Qt Quick UI projects in the QML Viewer and you
- need not build them. You do not need to have the development environment installed on your
- computer to create and run this type of projects.
-
- \o \gui {Custom QML Extension Plugin} creates a C++ plugin that makes it possible
- to offer extensions that can be loaded dynamically into applications by using the
- QDeclarativeEngine class.
-
- \endlist
-
- If you have existing QML applications that you want to run in Qt Creator or deploy
- to mobile devices, use the \gui {Qt Quick Application} wizard to convert them
- to Qt Quick applications.
-
- \section1 Creating Qt Quick UI Projects
-
- \list 1
-
- \o Select \gui {File > New File or Project > Qt Quick Project > Qt Quick UI
- > Choose...}.
-
- The \gui{Introduction and Project Location} dialog opens.
-
- \image qmldesigner-new-ui-project-location.png "Introduction and Project Location dialog"
-
- \o In the \gui Name field, give a name to the project.
-
- Do not use spaces and special characters in the project name and path.
-
- \o In the \gui {Create in} field, enter the path for the project files. For example,
- \c {C:\Qt\examples}. To select the path from a directory tree, click \gui Browse.
-
- \o Click \gui{Next}.
-
- \image qmldesigner-new-ui-project-summary.png "Project Management dialog"
-
- \o Review the project settings, and click \gui{Finish} to create the project.
-
-
- \endlist
-
- Qt Creator creates the following files:
-
- \list
-
- \o .qmlproject project file defines that all QML, JavaScript, and image
- files in the project folder belong to the project. Therefore, you do not
- need to individually list all the files in the project.
-
- \o .qml file defines an element, such as a component, screen, or the whole
- application UI.
-
- \endlist
-
- The \c import statement in the beginning of the .qml file specifies the
- \l {http://doc.qt.nokia.com/4.7/qdeclarativemodules.html} {Qt modules}
- to import. Each Qt module contains a set of default elements.
- Specify a version to get the features you want.
-
- To use JavaScript and image files in the application, copy them to the
- project folder.
-
- \section1 Creating Qt Quick Applications
-
- \list 1
-
- \o Select \gui {File > New File or Project > Qt Quick Project > Qt Quick Application
- > Choose...}.
-
- The \gui{Introduction and Project Location} dialog opens.
-
- \image qmldesigner-new-project-location.png "Introduction and Project Location dialog"
-
- \o In the \gui Name field, give a name to the project.
-
- Do not use spaces and special characters in the project name and path.
-
- \o In the \gui {Create in} field, enter the path for the project files. For example,
- \c {C:\Qt\examples}. To select the path from a directory tree, click \gui Browse.
-
- \o Click \gui{Next}.
-
- The \gui {Application Type} dialog opens.
-
- \image qmldesigner-new-project-qml-sources.png "Application Type dialog"
-
- \o Select the Qt Quick Component Set to use in your application. The
- built-in elements allow you to write cross-platform applications with
- custom look and feel. The components for Symbian and MeeGo Harmattan
- allow you to create applications with a native look and feel for the
- selected mobile platform.
-
- You can also import an existing QML file in this dialog.
-
- \o Click \gui{Next}.
-
- The \gui {Target Setup} dialog opens.
-
- \image qmldesigner-new-project-qt-versions.png "Target Setup dialog"
-
- \o Select the Qt versions to use as build targets for your project,
- and then click \gui{Next}.
-
- \note Qt Quick is supported since Qt 4.7, and therefore, only Qt 4.7 and later
- versions are displayed. Further, if you have only one supported Qt version installed,
- this dialog is skipped.
-
- The \gui {Mobile Options} dialog opens.
-
- \image qmldesigner-new-app-project-mobile-options.png "Mobile Options dialog"
-
- \o In the \gui {Orientation behavior} field, determine how the application
- behaves when the orientation of the device display rotates between portrait
- and landscape, and then click \gui Next.
-
- \note This dialog opens only if you select \gui Maemo5 or
- \gui {Symbian Device} target in the \gui {Target Setup} dialog. On
- Harmattan, the Qt Quick Components for MeeGo provide native-looking
- rotation.
-
- The \gui {Symbian Specific} dialog opens.
-
- \image qmldesigner-new-project-symbian-options.png "Symbian Specific dialog"
-
- \o In the \gui {Application icon (.svg)} field, select an application
- icon for the \gui {Symbian Device} target, or use the default icon.
-
- \o In the \gui {Target UID3} field, specify the \l{Application UID}, or
- use the default UID.
-
- \note Qt Creator generates a UID for testing the application on a device.
- You need to change the UID when you deliver the application for public
- use.
-
- \o Click \gui Next.
-
- The \gui {Maemo Specific} dialog opens.
-
- \image qmldesigner-new-project-maemo-options.png "Maemo Specific dialog"
-
- \o In the \gui {Application icon} field, select the application
- icon to use on Maemo or Harmattan targets, or use the default icon.
-
- The \gui {Project Management} dialog opens.
-
- \image qmldesigner-new-project-summary.png "Project Management" dialog
-
- \o In the \gui {Add to project} field, you can add this project to another
- project as a subproject.
-
- \o In the \gui {Add to version control} field, you can add the project to
- a version control system.
-
- \o Click \gui Finish to create the project.
-
- \endlist
-
- Qt Creator creates the necessary boilerplate files. Some of the files are
- specific to the Symbian, Maemo, or MeeGo Harmattan platform.
-
- \section1 Importing QML Applications
-
- If you have existing QML applications that you want to run in Qt Creator or deploy
- to mobile devices, use the \gui {Qt Quick Application} wizard and select the main
- .qml file in your project. All the other files in the project are automatically added
- to the application project.
-
- To import QML applications:
-
- \list 1
-
- \o Select \gui {File > New File or Project > Qt Quick Project > Qt Quick Application
- > Choose...}.
-
- \o Name the project and set its path, and then click \gui Next.
-
- \o In the \gui {Application Type} dialog, select the \gui {Use an
- existing .qml file}
- option and specify the main .qml file of the project you want to import.
-
- \image qmldesigner-import-project.png "Application Type dialog"
-
- \o Click \gui Next.
-
- \o Select the Qt versions to use as build targets for your project, and click
- \gui{Next}.
-
- \o Specify options for deploying the application to mobile device targets, and
- click \gui{Next}.
-
- \o Review the project settings, and click \gui{Finish} to create the project.
-
- \endlist
-
- Qt Creator adds references to the QML files to a project and creates the additional files
- necessary for deploying applications to mobile devices.
-
-*/
-
-
-/*!
-
- \contentspage index.html
- \previouspage creator-using-qt-quick-designer.html
- \page quick-components.html
- \nextpage quick-buttons.html
-
- \title Creating Components
-
- A QML component provides a way of defining a new type that you can re-use in other QML
- files. A component is like a black box; it interacts with the outside world
- through properties, signals, and slots, and is generally defined in its own QML file.
- You can import components to screens and applications.
-
- You can use the following QML elements to create components:
-
- \list
-
- \o \l{http://doc.qt.nokia.com/4.7/qml-borderimage.html}{Border Image}
- uses an image as a border or background.
- \o \l{http://doc.qt.nokia.com/4.7/qml-image.html}{Image}
- adds a bitmap to the scene. You can stretch and tile images.
- \o \l{http://doc.qt.nokia.com/4.7/qml-item.html}{Item}
- is the most basic of all visual items in QML. Even though it has no visual appearance,
- it defines all the properties that are common across visual items, such as the x and
- y position, width and height, anchoring, and key handling.
- \o \l{http://doc.qt.nokia.com/4.7/qml-rectangle.html}{Rectangle}
- adds a rectangle that is painted with a solid fill color and an optional border.
- You can also use the radius property to create rounded rectangles.
- \o \l{http://doc.qt.nokia.com/4.7/qml-text.html}{Text}
- adds formatted read-only text.
- \o \l{http://doc.qt.nokia.com/4.7/qml-textedit.html}{Text Edit}
- adds a single line of editable formatted text that can be validated.
- \o \l{http://doc.qt.nokia.com/4.7/qml-textinput.html}{Text Input}
- adds a single line of editable plain text that can be validated.
- \o \l{http://doc.qt.nokia.com/4.7-snapshot/qml-webview.html}{Web View}
- adds web content to a canvas.
-
- \endlist
-
- QML elements allow you to write cross-platform applications with custom look
- and feel. You can also use ready-made Qt Quick Components for Symbian and
- MeeGo Harmattan that allow you to create applications with a native look and
- feel for the selected mobile platform. You can install the components as
- part of \QSDK.
-
- When you use the Qt Creator project wizard to create Qt Quick applications,
- you can select which component set to use in your application.
-
- Even if you use the Qt Quick Components, you can still write cross-platform
- applications, by using different sets of QML files for each platform.
-
- You can dowload a set of commonly used UI-components for generic use in
- Qt Quick projects from
- \l{https://projects.forum.nokia.com/QMLTemplates}{QML Templates}. You can
- open and edit the templates in \QD.
-
- \section1 Creating Components in Qt Quick Designer
-
- \list 1
-
- \o Select \gui {File > New File or Project > Files and Classes > QML
- > Choose...} to create a new .qml file.
-
- \note Components are listed in the \gui {QML Components} section of the
- \gui Library pane only if the filename begins with a capital letter.
-
- \o Click \gui Design to open the .qml file in \QMLD.
-
- \o Drag and drop an item from the \gui Library pane to the editor.
-
- \o Edit item properties in the \gui Properties pane.
-
- The available properties depend on the item.
-
- \endlist
-
- The following sections contain examples of how to create some common components:
-
- \list
-
- \o \l{Creating Buttons}
-
- \o \l{Creating Scalable Buttons and Borders}
-
- \endlist
-
-*/
-
-
-/*!
- \contentspage index.html
- \previouspage quick-components.html
- \page quick-buttons.html
- \nextpage quick-scalable-image.html
-
- \title Creating Buttons
-
- To create a button component:
-
- \list 1
-
- \o Select \gui {File > New File or Project > QML > QML File > Choose...} to
- create a QML file called Button.qml (for example).
-
- \note Components are listed in the \gui Library pane only if the filename
- begins with a capital letter.
-
- \o Click \gui {Design} to edit the file in the visual editor.
-
- \o In the \gui Navigator pane, click \gui Rectangle to set properties
- for it.
-
- \o In the \gui Properties pane, modify the appearance of the button.
-
- \list a
-
- \o In the \gui Size field, set the width (\gui W) and height (\gui H)
- of the button.
-
- \o In the \gui Color field, select the button color.
-
- \o In the \gui Radius field, use the slider to set the radius of the
- rectangle and produce rounded corners for the button.
-
- \endlist
-
- \o Drag and drop a \gui {Text} item on top of the \gui Rectangle. This
- creates a nested element where \gui Rectangle is the parent element of
- \gui Text. Elements are positioned relative to their parents.
-
- \o In the \gui Properties pane, edit the properties of the \gui Text item.
-
- \list a
-
- \o In the \gui Text field, type \bold Button.
-
- You can select the text color, font, size, and style in the \gui Font
- section.
-
- \o In the \gui Alignment field, select the center buttons to align
- the text to the center of the button.
-
- \o Click \gui {Layout}, and then click the
- \inlineimage qmldesigner-anchor-fill-screen.png
- button to anchor the text to the whole button area.
-
- \endlist
-
- \o Press \key {Ctrl+S} to save the button.
-
- \image qmldesigner-button.png "Button component"
-
- \endlist
-
- \note To view the button, you must add it to a Qt Quick Application or Qt Quick UI
- project.
-
- To create a graphical button that scales beautifully without using vector graphics,
- use the \l{http://doc.qt.nokia.com/4.7/qml-borderimage.html}{Border Image}
- element. For more information, see \l{Creating Scalable Buttons and Borders}.
-
- */
-
-
- /*!
-
- \contentspage index.html
- \previouspage quick-buttons.html
- \page quick-scalable-image.html
- \nextpage quick-screens.html
-
- \title Creating Scalable Buttons and Borders
-
- You can use the \l{http://doc.qt.nokia.com/4.7/qml-borderimage.html}{Border Image}
- element to display an image, such as a PNG file, as a border and a background.
-
- Use two Border Image elements and suitable graphics to make it look like the button
- is pushed down when it is clicked. One of the Border Image elements is visible by default.
- You can specify that it is hidden and the other one becomes visible when the mouse
- is clicked.
-
- Add a MouseArea that covers the whole area and emits the clicked signal (\c {parent.clicked()})
- when it detects a mouse click.
-
- You can add text to the button and set it up as a property. The text can then be initialized
- from the outside, making the button a reusable UI component. The font size is also available
- in case the default size is too big. You can scale down the button text and use smooth text
- rendering for some extra quality.
-
- \image qmldesigner-borderimage.png "Graphical button"
-
- To create a graphical button:
-
- \list 1
-
- \o Select \gui {File > New File or Project > QML > QML File > Choose...} to create
- a QML file called Button.qml (for example).
-
- \o Double-click the file to open it in the code editor.
-
- \o Replace the \gui Rectangle with an \gui Item, as illustrated by the
- following code snippet:
-
- \qml
- Item {
-
- }
- \endqml
-
- \o Specify properties and set expressions for the \gui Item, as
- illustrated by the following code snippet:
-
- \snippet snippets/qml/quick-scalable-image.qml properties and signal definitions
-
- You will point to the properties and expression later.
-
- \o Click \gui {Design} to edit the file in the visual editor.
-
- \o Drag and drop two \gui BorderImage items from the \gui Library pane to
- the scene.
-
- \o Drag and drop a \gui Text item to the scene.
-
- \o Drag and drop a \gui MouseArea to the screen.
-
- \o In the \gui Navigator pane, select \gui border_image1 to specify
- settings for it in the \gui Properties pane:
-
- \list a
-
- \o Select \gui {Set Expression} in the menu next to the \gui Visibility
- check box.
-
- \o Enter the following expression to specify that the image is visible
- when the mouse is not pressed down: \c {!mouse_area1.pressed}.
-
- \o In the \gui Source field, select the image file for the
- button, for example button_up.png.
-
- \o Click \gui {Layout}, and then click the
- \inlineimage qmldesigner-anchor-fill-screen.png
- button to anchor the border image to the \gui Item.
-
- \endlist
-
- \o Select \gui border_image2 to specify similar settings for it:
-
- \list a
-
- \o Set the following epression for \gui Visibility, to specify that
- the image is visible when the mouse is pressed down:
- \c {mouse_area1.pressed}.
-
- \o In the \gui Source field, select the image file for the
- button when it is clicked, for example button_down.png.
-
- \o Click \gui {Layout}, and then click the
- \inlineimage qmldesigner-anchor-fill-screen.png
- button to anchor the border image to the \gui Item.
-
- \endlist
-
- \o Select \gui text1 to specify font size and color, and text
- scaling and rendering:
-
- \list a
-
- \o In the \gui Color field, use the color picker to select
- the font color, or enter a value in the field.
-
- \o In the \gui Text field, select \gui {Set Expression} and
- enter a pointer to the \c {text} property that you specified
- earlier: \c {parent.txt}.
-
- \o Select the \gui Aliasing check box to enable smooth text
- rendering.
-
- \o In the \gui Size field, select \gui {Pixels} to specify
- the font size in pixels. By default, the size is specified in
- points.
-
- \o In the \gui Size field, select \gui {Set Expression} and
- enter a pointer to the \c {fontSize} property that you specified
- earlier.
-
- \o Click \gui {Layout}, and then click the
- \inlineimage qmldesigner-center-in.png "Anchor buttons"
- buttons to inherit the vertical and horizontal centering from
- the parent.
-
- \o Click \gui Advanced to specify scaling for the text in the
- \gui Scale field.
-
- \o Select \gui {Set Expression} and enter the following expression:
- \c {if (!mousearea1.pressed) { 1 } else { 0.95 }}.
-
- \note You can enter long and complicated expressions also in the
- code editor.
-
- \endlist
-
- \o In the code editor, add to the \c MouseArea item
- a pointer to the \c clicked expression that you added earlier:
- \c {onClicked: parent.clicked()}.
-
- \endlist
-
- \note To view the button, you must add it to a Qt Quick Application or Qt
- Quick UI project.
-
-*/
-
-
-/*!
-
- \contentspage index.html
- \previouspage quick-scalable-image.html
- \page quick-screens.html
- \nextpage quick-animations.html
-
- \title Creating Screens
-
- You can use predefined QML elements and your own components to create screens.
- Typically, the main qml file in a Qt Quick project specifies the main window of an
- application.
-
- The QML files in the project folder are displayed in \gui {QML Components} in the
- \gui Library pane.
-
- You can also use ready-made Qt Quick Components for Symbian and
- MeeGo Harmattan that allow you to create screens with a native look and
- feel for the selected mobile platform. You can install the components as
- part of \QSDK.
-
- You can dowload QML templates that specify different types of screens from
- \l{https://projects.developer.nokia.com/QMLTemplates}{QML Templates} for use in
- your Qt Quick projects. You can open and edit the templates in \QD.
-
- \section1 Adding Components to Screens
-
- \list 1
-
- \o Drag and drop components from the \gui Library pane to the editor.
-
- \o Select components in the \gui Navigator pane to edit their properties
- in the \gui Properties pane.
-
- For example, you can anchor components to a position on the screen.
-
- \endlist
-
- \section1 Using Data Models
-
- You can create the following types of views to organize items provided by
- \l{http://doc.qt.nokia.com/4.7/qdeclarativemodels.html}{data models}:
-
- \list
-
- \o \l{http://doc.qt.nokia.com/4.7/qml-gridview.html}{Grid View}
- provides a grid vizualization of a model.
-
- \o \l{http://doc.qt.nokia.com/4.7/qml-listview.html}{List View}
- provides a list vizualization of a model.
-
- \o \l{http://doc.qt.nokia.com/4.7/qml-pathview.html}{Path View}
- visualizes the contents of a model along a path.
-
- \endlist
-
- When you add a Grid View, List View, or Path View element, the
- \l{http://doc.qt.nokia.com/4.7/qml-listmodel.html}{ListModel} and the
- delegate component that creates an instance for each item in the model are
- added automatically. You can edit element properties in the \gui Properties
- pane or in the code editor. You can also replace the default model and
- delegate with other, more complex models and delegates in the code editor.
-
- \section1 Positioning Items on Screens
-
- You can use the following items to arrange items on screens:
-
- \list
-
- \o \l{http://doc.qt.nokia.com/4.7-snapshot/qml-column.html}{Column}
- arranges its child items vertically.
-
- \o \l{http://doc.qt.nokia.com/4.7-snapshot/qml-row.html}{Row}
- arranges its child items horizontally.
-
- \o \l{http://doc.qt.nokia.com/4.7-snapshot/qml-grid.html}{Grid}
- arranges its child items so that they are aligned in a grid and
- are not overlapping.
-
- \o \l{http://doc.qt.nokia.com/4.7-snapshot/qml-flow.html}{Flow}
- arranges its child items side by side, wrapping as necessary.
-
- \endlist
-
- \section1 Using States
-
- Use states and transitions
- to navigate between screens.
-
- QML states typically describe user interface configurations, such as the UI elements,
- their properties and behavior and the available actions. For example, you can use
- states to create two screens.
-
- To add states, click the empty slot in the \gui States pane. Then modify the new state
- in the visual editor.
-
- \image qmldesigner-states.png "States pane"
-
- The properties that you change in a state are highlighted with blue color.
- In the code editor, you can see the changes recorded as changes to the base state.
-
- To keep the QML code clean, you should create a base state that contains all the
- elements you will need in the application. You can then create states, in
- which you hide and show a set of items and modify their properties.
- This allows you to:
-
- \list
-
- \o Align items on different screens with each other.
-
- \o Avoid excessive property changes. If an item is invisible in the base
- state, you must define all changes to its child elements as property changes,
- which leads to complicated QML code.
-
- \o Minimize the differences between the base state and the other states
- to keep the QML code short and readable and to improve performance.
-
- \o Avoid problems when using transitions and animation when changing
- states.
-
- \endlist
-
- To create screens for an application by using states:
-
- \list 1
-
- \o In the base state, add all elements you will need in the application.
- While you work on one screen, you can click the
- \inlineimage qmldesigner-show-hide-icon.png
- icon to hide elements on the canvas that are not part of a screen.
-
- \o In the \gui States pane, click the empty slot to create a new state
- and give it a name. For example, \c Normal.
-
- \o In the \gui Properties pane, deselect the \gui Visibility check box
- or set \gui Opacity to 0 for each element that is not needed in this view.
- If you specify the setting for the parent element, all child elements
- inherit it and are also hidden.
-
- \image qmldesigner-screen-design.png "Designing screens"
-
- \o Create additional states for each screen and set the visibility or
- opacity of the elements in the screen.
-
- \o To determine which view opens when the application starts, use the code
- editor to set the state of the root item of the .qml file, as specified by the
- following code snippet:
-
- \qml
- Item {
- state: "Normal"
- }
- \endqml
-
- \endlist
-
-
-*/
-
-
-/*!
-
- \contentspage index.html
- \previouspage quick-screens.html
- \page quick-animations.html
- \nextpage quick-user-interaction.html
-
- \title Animating Screens
-
- To make movement between states smooth, you can specify transitions.
- You can use different types of animated transitions. For example, you can animate changes
- to property values and colors. You can use rotation animation to control the direction of
- rotation. For more information, see
- \l{http://doc.qt.nokia.com/4.7/qdeclarativeanimation.html}{QML Animation}.
-
- You can use the \c ParallelAnimation element to start several animations at the same time.
- Or use the \c SequentialAnimation element to run them one after another.
-
- You can use the code editor to specify transitions. For more information, see
- \l{http://doc.qt.nokia.com/4.7/qml-transition.html}{QML Transition Element}.
-
-*/
-
-
-
-/*!
-
- \contentspage index.html
- \previouspage quick-animations.html
- \page quick-user-interaction.html
- \nextpage quick-export-to-qml.html
-
- \title Adding User Interaction Methods
-
- You can add the following basic interaction methods to scenes:
-
- \list
-
- \o \l{http://doc.qt.nokia.com/4.7/qml-flickable.html}{Flickable}
- items can be flicked horizontally or vertically.
- \o \l{http://doc.qt.nokia.com/4.7/qml-flipable.html}{Flipable}
- items can be flipped between their front and back sides by using rotation,
- state, and transition.
- \o \l{http://doc.qt.nokia.com/4.7/qml-focusscope.html}{Focus Scope}
- assists in keyboard focus handling when building reusable QML components.
- \o \l{http://doc.qt.nokia.com/4.7/qml-mousearea.html}{Mouse Area}
- enables simple mouse handling.
-
- \endlist
-
-*/
-
-
-/*!
-
- \contentspage index.html
- \previouspage quick-user-interaction.html
- \page quick-export-to-qml.html
- \nextpage quick-application-logic.html
-
- \title Exporting Designs from Graphics Software
-
- You can export designs from graphics software, such as Adobe Photoshop and GIMP,
- to QML files. Each scene is converted into a single QML file with an Image or a
- Text element for each layer and saved on the development PC. Top-level layer
- groups are converted into merged QML Image elements.
-
- Note: GIMP does not support grouping, and therefore, each layer is exported as
- an item in GIMP.
-
- You can open the QML file in Qt Creator for editing. If you edit the file in Adobe
- Photoshop and export it to the same directory again, any changes you made in Qt
- Creator are overwritten. However, you can re-export graphical assets without
- recreating the QML code.
-
- If you create vector graphics with other tools that have an Adobe Photoshop export
- option, such as Adobe Illustrator, you can export them first to Photoshop
- and then
- to QML.
-
- \section1 Conversion Rules
-
- The following rules apply to the conversions:
-
- \list
-
- \o Layer names are used as element names. Spaces and hash marks (#) are
- replaced with underscore characters to create valid ids for the elements.
-
- \o Layer styles, such as drop shadows, are converted to images.
-
- \o Offset, size, ordering and opacity are preserved.
-
- \o Text layers are converted to Text elements, unless you specify that they
- be converted to Image elements.
-
- \o Hidden layers can be exported, and their visibility is set to hidden.
-
- \o PNG images are copied to the images subirectory.
-
- \endlist
-
- \section1 Preparing Files for Conversion
-
- To create QML files that are easy to use, prepare the Adobe Photoshop or
- GIMP designs for exporting, as follows:
-
- \list
-
- \o To minimize the number of elements, minimize the number of layers or
- use top-level layer groups, because each layer or layer group is
- exported as a Text or Image element.
-
- \o To make sure that all related elements are exported to the same
- element, use top-level layer groups.
-
- \o To determine that some layers are not exported, hide them, and
- deselect the \gui {Export hidden} check box during exporting.
-
- \o To make it easier to find the layers and layer groups after
- exporting them, use descriptive names for them.
-
- \o To make sure that image dimensions are preserved during export,
- create at least one fully filled layer (which can be hidden), such
- as a background layer. If the export script does not find a fully
- filled layer, it resizes all images to the size of the canvas.
-
- \o To prevent errors during export, make sure that the layers are not
- locked. Locked layers cannot be exported.
-
- \o To avoid unexpected results, do not use Blending Mode effects. They
- are not exported.
-
- \endlist
-
- \section1 Exporting from Adobe Photoshop to QML
-
- \image qml-export-photoshop.png
-
- The script has been tested to work on Adobe Photoshop CS 4 and 5, but it might also
- work on other versions.
-
- \list 1
-
- \o Download the export script, \e{Export QML.jx}, from
- \l{http://qt.gitorious.org/qt-labs/photoshop-qmlexporter/trees/master}{Gitorious}.
-
- \note Read the README.txt file in the repository for latest information about
- the script.
-
- \o Double-click the export script to add the export command to the \gui Scripts
- menu. You can also copy the script file to the Adobe Photoshop scripts directory
- (typically, \c{\Presets\Scripts} in the Photoshop installation directory).
-
- \o In Adobe Photoshop, choose \gui {File > Scripts > Export to QML} to export the
- scene to a QML file.
-
- \o In the \gui {Export Document to QML} dialog, enter a name and location for the
- QML file.
-
- \o Select the \gui {Rasterize text} check box to export text layers as images,
- not as Text elements.
-
- \o Select the \gui {Group layers} check box to export each top-level group as a
- merged QML Image element.
-
- \o Select the \gui {Export hidden} check box to export hidden layers and to set
- their visibility property to hidden.
-
- \o Deselect the \gui {Export QML} check box if you have modified the QML document
- in Qt Creator, but still want to re-export graphical assets.
-
- \o Click \gui Export.
-
- \endlist
-
- The QML file is saved to the location that you specified.
- In Qt Creator, choose \gui {File > Open File or Project} to open the QML file.
-
- \note Existing files are replaced without warning.
-
- \section1 Exporting from GIMP to QML
-
- \image qml-export-gimp.png
-
- The script has been tested to work on GIMP 2. You can download GIMP 2 from
- \l{http://www.gimp.org/downloads/}{GIMP Downloads}.
-
- To use the export script on Microsoft Windows, you also need to install the
- GIMP Python extension (Python, PyCairo, PyGobject, PyGTK). However, GIMP is
- not officially supported on Windows, so we cannot guarantee that this will
- work.
-
- \list 1
-
- \o On Microsoft Windows, you must first add Python support to your GIMP
- installation, as instructed in
- \l {http://www.gimpusers.com/tutorials/install-python-for-gimp-2-6-windows}{Tutorial: Installing Python for GIMP 2.6 (Windows)}.
-
- \o Download the export script, \e qmlexporter.py, from
- \l{http://qt.gitorious.org/qt-labs/gimp-qmlexporter/trees/master}{Gitorious}.
-
- \note Read the INSTALL.txt in the repository for latest information about the
- script.
-
- \o Copy the export script to the plug-ins directory in the GIMP installation
- directory.
-
- \o Check the properties of the file to make sure that it is executable.
-
- On Linux, run the following command: \c {chmod u+rx}
-
- \o Restart GIMP to have the export command added to the \gui File menu.
-
- \o Choose \gui {File > Export to QML} to export the design to a QML file.
-
- \o In the \gui {Export Layers to a QML Document} dialog, enter a name and
- location for the QML file, and click \gui Export.
-
- \endlist
-
- The QML file is saved to the location that you specified.
- In Qt Creator, choose \gui {File > Open File or Project} to open the QML file.
-
- \note Existing files are replaced without warning.
-
-*/
-
-
-/*!
-
- \contentspage index.html
- \previouspage quick-export-to-qml.html
- \page quick-application-logic.html
- \nextpage creator-qml-modules-with-plugins.html
-
- \title Implementing Application Logic
-
- A user interface is only a part of an application, and not really useful by itself.
- You can use Qt or JavaScript to implement the application logic. For more information on
- using JavaScript, see
- \l {http://doc.qt.nokia.com/4.7/qdeclarativejavascript.html} {Integrating JavaScript}.
-
- For an example of how to use JavaScript to develop a game, see the
- \l {http://doc.qt.nokia.com/4.7/qml-advtutorial.html} {QML Advanced Tutorial}.
-
- */
-
-
-/*!
- \contentspage index.html
- \previouspage quick-application-logic.html
- \page creator-qml-modules-with-plugins.html
- \nextpage creator-using-qt-designer.html
-
- \title Using QML Modules with Plugins
-
- QML modules may use plugins to expose components defined in C++ to
- QML applications. Since Qt Creator cannot load the plugins to determine
- the details of the contained components, these modules need to provide
- extra type information for code completion and the semantic checks to work
- correctly.
-
- Ideally, QML modules have a \c{plugins.qmltypes} file in the same directory
- as the \c qmldir file. The \c qmltypes file contains a description of the
- components exported by the module's plugins and is loaded by Qt Creator
- when the module is imported.
-
- For Qt 4.8 and later, one or more \c qmltypes files can be listed in the
- \c qmldir file under the \c typeinfo header. These files will be read in addition
- to \c{plugins.qmltypes}. For more information, see
- \l{http://doc.qt.nokia.com/4.8-snapshot/qdeclarativemodules.html#writing-a-qmldir-file}{Writing a qmldir File}.
-
- \section1 Generating qmltypes Files
-
- You can create and edit \c qmltypes files manually, but you are recommended
- to use the \c qmlplugindump tool shipped with Qt 4.8 and later to generate
- them automatically. For earlier versions of Qt, you can compile a version
- of the tool called \c qmldump from the sources in
- \c{<QtCreator>/share/qtcreator/qml/qmldump} if the Qt version contains private headers.
-
- Once you have obtained qmlplugindump for the Qt version the QML module's
- plugins were compiled with, run the following command to load My.Module
- version 1.0 from \c{/import/path/my/module} including all its plugins and
- output a description of the plugins' types to
- \c{/import/path/my/module/plugins.qmltypes}:
-
- \code
- qmlplugindump My.Module 1.0 /import/path > /import/path/my/module/plugins.qmltypes
- \endcode
-
- You can safely ignore the debug output.
-
- \section1 Dumping Plugins Automatically
-
- If a module with plugins lacks the \c qmltypes file, Qt Creator tries to
- generate a temporary file itself by running the \c qmldump program in the
- background. However, this automatic dumping is a fallback mechanism with
- many points of failure and cannot be relied upon.
-
-*/
-
-/*!
- \contentspage index.html
- \previouspage creator-editor-refactoring.html
- \page qt-quick-toolbars.html
- \nextpage creator-editor-locator.html
-
- \title Using Qt Quick Toolbars
-
- When you edit QML code in the code editor, you specify the properties
- of QML components. For some properties, such as colors and font names,
- this is not a trivial task. For example, few people can visualize the
- color #18793f.
-
- To easily edit these properties, you can use the Qt Quick Toolbars.
- When you select a component in the code and a toolbar is available,
- a light bulb icon appears:
- \inlineimage qml-toolbar-indicator.png
- . Select the icon to open the toolbar.
-
- To open toolbars immediately when you select a component, select
- \gui{Tools > Options... > Qt Quick > Qt Quick Toolbar > Always show Quick
- Toolbar}.
-
- Drag the toolbar to pin it to another location. Select
- \inlineimage qml-toolbar-pin.png
- to unpin the toolbar and move it to its default location. To pin toolbars
- by default, select \gui{Tools > Options... > Qt Quick > Qt Quick Toolbar
- > Pin Quick Toolbar}.
-
- \section1 Previewing Images
-
- The Qt Quick Toolbar for images allows you to edit the properties of
- \l{http://doc.qt.nokia.com/latest/qml-borderimage.html}{Border Image}
- and \l{http://doc.qt.nokia.com/latest/qml-image.html}{Image} components.
- You can scale and tile the images, replace them with other images,
- preview them, and change the image margins.
-
- \image qml-toolbar-image.png "Qt Quick Toolbar for images"
-
- To preview an image, double-click it on the toolbar. In the preview
- dialog, you can zoom the image. Drag the image margins to change them.
-
- \image qml-toolbar-image-preview.png "Image preview dialog"
-
- \section1 Formatting Text
-
- The Qt Quick Toolbar for text allows you to edit the properties of
- \l{http://doc.qt.nokia.com/latest/qml-text.html}{Text} components.
- You can change the font family and size as well as text formatting, style,
- alignment, and color.
-
- If a property is assigned an expression instead of a value, you
- cannot use the toolbar to edit it. The button for editing the property
- is disabled.
-
- \image qml-toolbar-text.png "Qt Quick Toolbar for text"
-
- By default, font size is specified as pixels. To use points, instead,
- change \gui px to \gui pt in the size field.
-
- \section1 Previewing Animation
-
- The Qt Quick Toolbar for animation allows you to edit the properties of
- \l{http://doc.qt.nokia.com/4.7/qml-propertyanimation.html}{PropertyAnimation}
- components and the components that inherit it. You can change the easing curve
- type and duration. For some curves, you can also specify amplitude, period,
- and overshoot values.
-
- \image qml-toolbar-animation.png "Qt Quick Toolbar for animation"
-
- Select the play button to preview your changes.
-
- \section1 Editing Rectangles
-
- The Qt Quick Toolbar for rectangles allows you to edit the properties of
- \l{http://doc.qt.nokia.com/4.7/qml-rectangle.html}{Rectangle}
- components. You can change the fill and border colors and add
- gradients.
-
- \image qml-toolbar-rectangle.png "Qt Quick Toolbar for rectangles"
-
- To add gradient stop points, click above the gradient bar. To remove
- stop points, drag them upwards.
-
-*/
-
-
-/*!
- \contentspage index.html
- \previouspage creator-editor-external.html
- \page creator-maemo-emulator.html
- \nextpage creator-mime-types.html
-
- \title Using Maemo or MeeGo Harmattan Emulator
-
- The Maemo 5 (Fremantle) and MeeGo Harmattan emulator are installed as part
- of the \QSDK. After they are installed, you can start them from Qt Creator.
-
- The Maemo 5 emulator emulates the Nokia N900 device environment. You can test
- applications in conditions practically identical to running the application
- on a Nokia N900 device with software update release 1.3 (V20.2010.36-2).
-
- The MeeGo Harmattan emulator emulates the Nokia N9 device environment.
-
- With the emulators, you can test how your application reacts to hardware
- controls, such as the power button, and to the touch screen.
-
- To test the application UI, user interaction with the application, and
- functionality that uses the mobility APIs, use the Qt Simulator,
- instead. For more information, see the
- \l{http://doc.qt.nokia.com/qtsimulator/index.html}{Qt Simulator Manual}.
-
- The difference between Qt Simulator and the emulators is that when you
- compile your application binary for Qt Simulator, it is compiled against a
- host library. The binary run on the emulator is compiled for the actual
- device, using the Maemo 5 or Harmattan tool chain.
-
- \section1 Starting the Emulator
-
- The \gui {Start MeeGo Emulator} button is visible if you have a project
- open in Qt Creator for which you have added the Maemo or MeeGo Harmattan
- build target. It starts the Maemo or MeeGo Harmattan emulator, depending
- on the selected target.
-
- To start the emulator, click
- \inlineimage qtcreator-maemo-emulator-button.png "Start MeeGo Emulator button"
- .
-
- Test your application on the emulator as on a device. For a list of
- keyboard shortcuts that you can use to emulate keys and functions, see
- \l {Emulating Device Keys}.
-
- \section1 Rendering Graphics
-
- The emulators support OpenGL to improve graphics rendering. Hardware
- acceleration produces better results than software rendering. By default,
- Qt Creator automatically detects, whether hardware acceleration is
- supported on the development PC and tries to use it. However, sometimes
- the results of the automatic detection are not reliable, and
- hardware acceleration might be selected even if it is actually not
- available on the development PC. This causes the emulator to crash.
-
- If the emulator crashes, you are asked whether you want to try software
- rendering, instead.
-
- To specify the OpenGL mode, select \gui {Tools > Options... > Linux Devices
- > Maemo Qemu
- Settings}.
-
- \section1 Emulating Device Keys
-
- The following table summarizes the keyboard shortcuts that you can use
- to emulate device keys and functions.
-
- \table
- \header
- \o Device Key
- \o Keyboard Shortcut
- \row
- \o \list
- \o Alphabet keys
- \o Comma (,)
- \o Period (.)
- \o Space
- \o Arrow keys
- \o Enter
- \o Backspace
- \endlist
- \o Respective keys on the development PC keyboard.
- \row
- \o Shift
- \o Left Shift key (Maemo 5)
-
- Shift (Harmattan)
- \row
- \o Ctrl
- \o Left Ctrl key (Maemo 5)
-
- Ctrl (Harmattan)
- \row
- \o Mode
- \o Left Alt key (Maemo 5)
-
- Alt (Harmattan)
- \row
- \o Power
- \o Esc
- \row
- \o Keypad slider open and close
- \o F1
- \row
- \o Keypad lock (Maemo 5 only)
- \o F2
- \row
- \o Camera lens open and close (Maemo 5 only)
- \o F3
- \row
- \o Camera focus
- \o F4
- \row
- \o Camera take picture
- \o F5
-
- \note The actual camera functionality is not emulated.
- \row
- \o Stereo headphones connect and disconnect (Maemo 5 only)
- \o F6
- \row
- \o Volume down
- \o F7
- \row
- \o Volume up
- \o F8
- \row
- \o Accelerometer x axis, negative
- \o 1
- \row
- \o Accelerometer x axis, positive
- \o 2
- \row
- \o Accelerometer z axis, negative
- \o 4
- \row
- \o Accelerometer z axis, positive
- \o 5
- \row
- \o Accelerometer y axis, negative
- \o 7
- \row
- \o Accelerometer y axis, positive
- \o 8
-
- \endtable
-
- \note Each press of the accelerometer key turns the acceleration by 50
- percent.
-
- \section1 Closing the Emulator
-
- To close the emulator, click the X at the top right corner of the device
- emulator view. The emulator interprets this as a press of the power button
- and displays the text \e {Shutting down} in the emulator window title pane.
- The emulator closes shortly after this.
-
- You can also select the \gui {Start MeeGo Emulator} button to close the
- emulator. This is a faster way to close the emulator, because it does not
- wait for the operating system running on the emulated machine to shut down,
- but this also means that it is less safe.
-
-*/
-
-
-/*!
- \contentspage index.html
- \previouspage creator-version-control.html
- \page adding-plugins.html
- \nextpage creator-editor-external.html
-
- \title Adding Qt Designer Plugins
-
- You can use Qt APIs to create plugins that extend Qt applications.
- This allows you to add your own widgets to \QD.
- The most flexible way to include a plugin with an application is to compile it
- into a dynamic library that is shipped separately, and detected and loaded at runtime.
-
- The applications can detect plugins that are stored in the standard plugin
- subdirectories. For more information on how to create and locate plugins and to
- change the default plugin path, see \l{How to Create Qt Plugins}.
-
- For more information about how to create plugins for \QD, see
- \l{http://doc.qt.nokia.com/4.7/designer-using-custom-widgets.html}{Creating and Using Components for Qt Designer}.
-
- \section1 Locating Qt Designer Plugins
-
- \QD fetches plugins from the standard locations and loads the plugins
- that match its build key. \QD is delivered both as a standalone application
- and as part of the SDK, where it is integrated into Qt Creator.
- The correct folder to place the plugins depends on
- which one you use.
-
- The integrated \QD fetches plugins from the \c {%SDK%\bin\designer} folder on Windows
- and Linux. For information about how to configure plugins on Mac OS, see
- \l{Configuring Qt Designer Plugins on Mac OS}.
-
- To check which plugins
- were loaded successfully and which failed, choose \gui{Tools > Form Editor >
- About Qt Designer Plugins}.
-
- The standalone \QD is part of the Qt library used for building projects,
- located under \c {%SDK%\qt}. Therefore, it fetches plugins from the following folder:
- \c {%SDK%\qt\plugins\designer}. To check which plugins were loaded successfully and which
- failed, choose \gui{Help > About Plugins}.
-
- \section2 Configuring Qt Designer Plugins on Mac OS
-
- On the Mac, a GUI application must be built and run from a bundle. A bundle is a
- directory structure that appears as a single entity when viewed in the Finder.
- A bundle for an application typcially contains the executable and all the resources
- it needs.
-
- Qt Creator uses its own set of Qt Libraries located in the bundle, and therefore,
- you need to configure the \QD plugins that you want to use with Qt Creator.
- Fore more information about how to deploy applications on Mac OS, see
- \l{http://doc.qt.nokia.com/4.7/deployment-mac.html}{Deploying an Application on Mac OS X}.
-
- The following example illustrates how to configure version 5.2.1 of the
- \l{http://qwt.sourceforge.net/}{Qwt - Qt Widgets for Technical Applications} library
- for use with Qt Creator:
-
- \list 1
-
- \o To check the paths used in the Qwt library, enter the following \c otool command:
-
- \snippet examples/doc_src_plugins.qdoc 0
-
- The output for Qwt 5.2.1 indicates that the plugin uses Qt core libraries (QtDesigner,
- QtScript, QtXml, QtGui and QtCore) and libqwt.5.dylib:
-
- \snippet examples/doc_src_plugins.qdoc 1
-
-
- \o You must copy the \QD plugin and the Qwt library files to the following locations:
-
- \list
- \o \c {libqwt_designer_plugin.dylib} to \c {QtCreator.app/Contents/MacOS/designer}
- \o \c {libqwt.*.dylib} to \c {QtCreator.app/Contents/Frameworks}
- \endlist
-
- Enter the following commands:
-
- \snippet examples/doc_src_plugins.qdoc 4
-
- \o Enter the following \c otool command to check the libraries that are used by the
- Qwt library:
-
- \snippet examples/doc_src_plugins.qdoc 2
-
- The command returns the following output:
-
- \snippet examples/doc_src_plugins.qdoc 3
-
- \o Enter the following \c install_name_tool command to fix the references of the
- libraries:
-
- \snippet examples/doc_src_plugins.qdoc 5
-
- \endlist
-
-
- \section1 Matching Build Keys
-
- The Qt Creator that is included in pre-built SDK packages on Windows is built with the
- Microsoft Visual Studio compiler, whereas the version of Qt shipped for building applications
- is configured and built to use the MinGW/g++ compiler. Plugins built by using this version of
- Qt cannot be loaded by Qt Creator because the build-keys do not match. The plugins can only be
- used in the standalone version of \QD. Choose \gui{Help > About Qt Creator} to check
- the Qt version Qt Creator was built with.
-
- To use \QD plugins that were built for the shipped Qt version, make sure that
- Qt Creator is built with the same compiler by either recompiling Qt Creator using MinGW or
- recompiling Qt with Microsoft Visual Studio, depending on which configuration you want to
- use for your applications.
-
-*/
-
-
-/*!
- \contentspage index.html
- \previouspage creator-using-qt-designer.html
- \page creator-usability.html
- \nextpage creator-building-running.html
-
- \title Optimizing Applications for Mobile Devices
-
- Before starting application development, analyze and define the requirements, scope, and
- functionality of the application to ensure efficient functionality and a smooth user
- experience. Design the application for a single purpose and analyze how it can best serve
- its users. Mobile devices have been designed for use when mobile. Keep the characteristics
- of mobile devices in mind when you create applications for them.
-
- The following guidelines help you design and develop usable applications for mobile devices
- with varying characteristics, such as screen size and support for input methods:
-
- \list
-
- \o Know your users
-
- Find out who will use the application, what they will use it for,
- and which mobile devices they have. Then design the application to fit a specific context
- of use.
-
- \o Design for small screens
-
- The screen size of mobile devices is significantly smaller
- than that available on desktop devices. Carefully consider what is the most relevant
- content to present on the application UI, as it might not be reasonable to try and fit as
- much content into the screen as you might have in a desktop application.
-
- \o Design for multiple screen sizes
-
- Relate the position and size of each control to the
- dimensions of the display. This enables the same set of information to be presented on the
- screen in all resolutions; higher resolution devices just display finer graphics.
-
- \o Design for changing screen orientation
-
- Some devices support screen rotation. On these
- devices, applications can be displayed in portrait or landscape orientation. Account for
- orientation and dynamically adjust the display when the screen is rotated.
-
- \o Design intuitive ways of moving within applications
-
- Mobile devices lack a mouse and
- full-size keyboard, so users must use the touch screen or five way navigation pad to move within
- applications. In addition, many users control the devices with one hand. To create an optimized user
- experience, allow users to access information with one click; do not make them scroll and type.
-
- \o Design for limited input methods
-
- Applications collect information from users on the task
- at hand. In addition to touch screen input, some devices contain physical keys such
- as a five way navigation pad, a keypad, and a keyboard. Users enter information by using screen
- controls, such as lists, check boxes, radio buttons, and text fields.
-
- \o Keep response times short
-
- Latency can cause delays in user interaction. If users perceive
- an application as being slow, they are likely to get frustrated and stop using it.
-
- \o Save battery time
-
- Mobile devices are not constantly connected to a power source but run on
- battery power. Optimize power consumption to keep the total consumption at an acceptable
- level and to prevent users from running out of battery time.
-
- \o Consider network issues
-
- If users do not have a flat-rate data plan or WLAN support, mobile
- network connections cost them money. Also, when users move around with the devices, the networks
- available for connections constantly change.
-
- \o Remember the processing limits of the device
-
-
- The memory available on devices is limited
- and you should use it carefully. Although all mobile devices have common functionality,
- each device is individual in terms of both the resources available and extra features.
- Therefore, you must consider the constraints of all the target devices.
-
- \endlist
-
- For more information about user experience techniques for mobile devices, see the
- \l{http://www.developer.nokia.com/Resources/Library/Design_and_UX} on Nokia Developer.
-
- */
-
-
-/*!
- \contentspage index.html
- \previouspage creator-faq.html
- \page creator-tips.html
- \nextpage creator-known-issues.html
-
- \title Tips and Tricks
-
-
- \section1 Switching Between Modes
-
- Qt Creator uses different modes for different purposes. You can quickly
- switch between these modes with the following keyboard shortcuts:
- \list
- \o \gui Welcome mode \key Ctrl+1
- \o \gui Edit mode \key Ctrl+2
- \o \gui Design mode \key Ctrl+3
- \o \gui Debug mode \key Ctrl+4
- \o \gui Projects mode \key Ctrl+5
- \o \gui Help mode \key Ctrl+6
- \endlist
-
-
- For more information about Qt Creator modes, see \l {Qt Creator Modes}.
-
-
-
- \section1 Moving Between Open Files
-
- To quickly move between currently open files, press
- \key Ctrl+Tab.
-
- To move forward in the location history, press \key {Alt+Right}
- (\key {Cmd+Opt+Right} on Mac OS). To move backward, press \key {Alt+Left}
- (\key {Cmd+Opt+Left} on Mac OS). For example, if you use the \gui Locator
- to jump to a symbol in the same file, you can jump back to your original
- location in that file by pressing \key {Alt+Left}.
-
-
- \section1 Moving To the Edit Mode
-
- To move to the \gui Edit mode and currently active file, press
- \key Esc.
-
- If you already are in the \gui Edit mode:
- \list
- \o The first press moves focus to the editor
- \o The second press closes secondary windows
- \endlist
-
- \section1 Using the Filter in Options Dialog
-
- To find specific settings you require in \gui{Tools} > \gui{Options...}
- use the filter located at the top left of the \gui Options dialog box.
-
- \section1 Opening Output Panes
-
- The output panes provide a list of errors and warnings encountered during
- a build, detailed output from the compiler, status of a program when it is
- executed and debug output, as well as search results.
-
- To open output panes, use the following shortcuts:
-
- \list
-
- \o \gui{Build Issues} pane Alt+1 (Cmd+1 on Mac OS X)
-
- \o \gui{Search Results} pane Alt+2 (Cmd+2 on Mac OS X)
-
- \o \gui{Application Output} pane Alt+3 (Cmd+3 on Mac OS X)
-
- \o \gui{Compile Output} pane Alt+4 (Cmd+4 on Mac OS X)
-
- \endlist
-
- For more information about output panes, see \l{Viewing Output}.
-
-
- \section1 Using Keyboard Shortcuts
-
- Qt Creator provides \l{Keyboard Shortcuts}{many useful keyboard shortcuts}.
- You can see the keyboard shortcut for a menu command in the menu
- or the tooltip for a button.
-
- To customize, import or export keyboard shortcuts, select \gui Tools >
- \gui Options... > \gui Environment > \gui Keyboard.
-
-
- \section1 Running Qt Creator From Command Line
-
- You can launch Qt Creator from command line using the name of an
- existing session or \c .pro file by giving the name as the command
- argument.
-
- For example, running \tt{qtcreator somesession}, launches Qt Creator and
- loads session somesession.
-
- \note Make sure Qt Creator is included in the PATH environment variable.
- This can be done by typing the following in the command line:
- \code
- set PATH=c:\qtsdk\mingw\bin;c:\qtsdk\qt\bin;%PATH%
- \endcode
-
-
- \section1 Showing and Hiding the Sidebar
-
- To toggle the sidebar in the \gui Edit and \gui Debug modes, click
- \inlineimage qtcreator-togglebutton.png
- or press \key Alt+0 (\key Cmd+0 on Mac OS X).
-
- For more information on using the sidebar, see \l {Browsing Project Contents}.
-
-
-
- \section1 Moving To Symbols
-
- To move straight to a symbol used in a project, select the symbol in the
- \gui Editor toolbar drop-down menu. For more information on the editor toolbar,
- see \l {Using the Editor Toolbar}.
-
- To jump to a symbol in the current file, press \key {Ctrl+K} to open the
- \gui Locator, enter a period (.), and start typing the symbol name. Then
- select the symbol in the list. For more information on using the locator,
- see \l{Searching With the Locator}.
-
- Press \key Ctrl (\key Cmd on Mac OS) and click a symbol to move directly to
- the definition or the declaration of the symbol. You can also move the cursor
- on the symbol and press \key {F2}. For more information, see
- \l{Moving to Symbol Definition or Declaration}.
-
-
-
- \section1 Displaying Signals and Slots
-
- If an instance of a class is derived from QObject, and you would like to
- find all other objects connected to one of your object's slots using
- Qt's signals and slots mechanism, select \gui Tools > \gui Options...
- > \gui{Debugger} > \gui{Debugging Helper} > \gui{Use Debugging Helper}.
-
- In the \gui{Locals and Expressions} view, expand the object's entry and open
- the slot in the \e slots subitem. The objects connected to this slot are
- shown as children of the slot. This method works with signals too.
-
- For more information about the \gui{Locals and Expressions} view, see
- \l{Locals and Expressions}.
-
-
- \section1 Displaying Low Level Data
-
- If special debugging of Qt objects fails due to data corruption within the
- debugged objects, you can switch off the debugging helpers. When debugging
- helpers are switched off low-level structures become visible.
-
- To switch off the debugging helpers:
- \list 1
-
- \o Select \gui Tools > \gui Options... > \gui Debugger >
- \gui{Debugging Helper}.
- \o Uncheck the \gui{Use Debugging Helper} checkbox.
- \endlist
-
-
- \section1 Showing Tooltips in Debug Mode
-
- To inspect the value of variables from the editor, you can turn
- on tooltips. Tooltips are hidden by default for performance reasons.
-
- \list 1
- \o Select \gui Tools > \gui Options... > \gui Debugger > \gui General.
- \o Select the \gui {Use tooltips in main editor while debugging} check box.
- \endlist
-
- When you hover over a variable in the code editor in \gui Debug mode, a
- tooltip is displayed. To keep the tooltip visible, click the pin button.
- You can expand pinned tooltips to view their full content.
-
- \image qtcreator-pin-tooltip.png
-
- Pinned tooltips are stored in the session. To close all pinned tooltips,
- select \gui {Close Editor Tooltips} in the context menu in the \gui {Locals
- and Expressions} view.
-
-
- \section1 Locating Files
-
- The \gui Locator provides one of the easiest ways in Qt Creator to browse
- through projects, files, classes, methods, documentation and file systems.
- To quickly access files not directly mentioned in your project, you can
- create your own locator filters. That way you can locate files in a
- directory structure you have defined.
-
- To create locator filters, select \gui {Tools > Options... > Locator > Add}.
-
- For more information, see \l{Creating Locator Filters}.
-
- \section1 Adding a License Header Template for C++ Code
-
- A file containing a license header for C++ can be specified under
- \gui{Tools > Options... > C++ > License Template}. It may contain special
- placeholders enclosed in \c{%%} that are replaced when generating a
- new file:
-
- \list 1
- \o \c %YEAR%: Year
- \o \c %MONTH%: Month
- \o \c %DAY%: Day of the month
- \o \c %DATE%: Date
- \o \c %USER%: User name
- \o \c %FILENAME%: File name
- \o \c %CLASS%: Class name (if applicable)
- \o \c %$VARIABLE%: Contents of environment variable \c{VARIABLE}.
- \endlist
-
-*/
-
-
-/*!
- \contentspage index.html
- \previouspage creator-cli.html
- \page creator-keyboard-shortcuts.html
- \nextpage creator-faq.html
-
- \title Keyboard Shortcuts
-
- Qt Creator provides various keyboard shortcuts to speed up your development
- process.
-
-
- \section1 Configuring Keyboard Shortcuts
-
- To customize a keyboard shortcut:
- \list 1
- \o Select \gui Tools > \gui Options... > \gui Environment >
- \gui Keyboard.
- \o Select an action from the list.
- \o In \gui{Key Sequence} enter the shortcut key you want to associate
- with the selected action.
- \endlist
-
- Qt Creator allows you to use different keyboard shortcut mapping schemes:
- \list
- \o To import a keyboard shortcut mapping scheme, click \gui Import
- and select the kms file containing keyboard shortcut mapping scheme
- you want to import.
- \o To export the current keyboard shortcut mapping scheme, click
- \gui Export and select the location where you want to save the
- exported kms file.
- \endlist
-
-
- \section1 Default Keyboard Shortcuts
-
- The following tables list the default keyboard shortcuts. They are
- categorized by actions.
-
-
- \section2 General Keyboard Shortcuts
-
- \table
- \header
- \o Action
- \o Keyboard shortcut
- \row
- \o Open file or project
- \o Ctrl+O
- \row
- \o New file or project
- \o Ctrl+N
- \row
- \o Open in external editor
- \o Alt+V, Alt+I
- \row
- \o Cut
- \o Ctrl+X
- \row
- \o Copy
- \o Ctrl+C
- \row
- \o Paste
- \o Ctrl+V
- \row
- \o Redo
- \o Ctrl+Y
- \row
- \o Save
- \o Ctrl+S
- \row
- \o Save all
- \o Ctrl+A
- \row
- \o Close window
- \o Ctrl+W
- \row
- \o Close all
- \o Ctrl+Shift+W
- \row
- \o Go back
- \o Alt+Left
- \row
- \o Go forward
- \o Alt+Right
- \row
- \o Go to line
- \o Ctrl+L
- \row
- \o Next open document in history
- \o Ctrl+Shift+Tab
- \row
- \o Goto other split
- \o Ctrl+E, O
- \row
- \o Previous open document in history
- \o Ctrl+Tab
- \row
- \o Activate \gui Locator
- \o Ctrl+K
- \row
- \o Switch to \gui Welcome mode
- \o Ctrl+1
- \row
- \o Switch to \gui Edit mode
- \o Ctrl+2
- \row
- \o Switch to \gui Design mode
- \o Ctrl+3
- \row
- \o Switch to \gui Debug mode
- \o Ctrl+4
- \row
- \o Switch to \gui Projects mode
- \o Ctrl+5
- \row
- \o Switch to \gui Help mode
- \o Ctrl+6
- \row
- \o Toggle \gui{Build Issues} pane
- \o Alt+1 (Cmd+1 on Mac OS X)
- \row
- \o Toggle \gui{Search Results} pane
- \o Alt+2 (Cmd+2 on Mac OS X)
- \row
- \o Toggle \gui{Application Output} pane
- \o Alt+3 (Cmd+3 on Mac OS X)
- \row
- \o Toggle \gui{Compile Output} pane
- \o Alt+4 (Cmd+4 on Mac OS X)
- \row
- \o Activate \gui Bookmarks pane
- \o Alt+M
- \row
- \o Activate \gui{File System} pane
- \o Alt+Y
- \row
- \o Activate \gui{Open Documents} pane
- \o Alt+O
- \row
- \o Activate \gui Projects pane
- \o Alt+X
- \row
- \o Full screen
- \o Ctrl+Shift+F11
- \row
- \o Toggle the sidebar
- \o Alt+0 (Cmd+0 on Mac OS X)
- \row
- \o Undo
- \o Ctrl+Z
- \row
- \o Move to \gui Edit mode
-
- In \gui Edit mode:
- \list
- \o The first press moves focus to the editor
- \o The second press closes secondary windows
- \endlist
- \o Esc
- \endtable
-
-
- \section2 Editing Keyboard Shortcuts
-
- \table
- \header
- \o Action
- \o Keyboard shortcut
- \row
- \o Auto-indent selection
- \o Ctrl+I
- \row
- \o Collapse
- \o Ctrl+<
- \row
- \o Expand
- \o Ctrl+>
- \row
- \o Trigger a completion in this scope
- \o Ctrl+Space
- \row
- \o Copy line down
- \o Ctrl+Alt+Down
- \row
- \o Copy line up
- \o Ctrl+Alt+Up
- \row
- \o Cut line
- \o Shift+Del
- \row
- \o Join lines
- \o Ctrl+J
- \row
- \o Decrease font size
- \o Ctrl+- (Ctrl+Roll mouse wheel down)
- \row
- \o Increase font size
- \o Ctrl++ (Ctrl+Roll mouse wheel up)
- \row
- \o Toggle Vim-style editing
- \o Alt+V, Alt+V
- \row
- \o Split
- \o Ctrl+E, 2
- \row
- \o Split side by side
- \o Ctrl+E, 3
- \row
- \o Remove all splits
- \o Ctrl+E, 1
- \row
- \o Remove current split
- \o Ctrl+E, 0
- \row
- \o Select all
- \o Ctrl+A
- \row
- \o Go to block end
- \o Ctrl+]
- \row
- \o Go to block start
- \o Ctrl+[
- \row
- \o Go to block end with selection
- \o Ctrl+}
- \row
- \o Go to block start with selection
- \o Ctrl+{
- \row
- \o Move current line down
- \o Ctrl+Shift+Down
- \row
- \o Move current line up
- \o Ctrl+Shift+Up
- \row
- \o Trigger a quick fix in this scope
- \o Alt+Return
- \row
- \o Rewrap paragraph
- \o Ctrl+E, R
- \row
- \o Select the current block
-
- The second press extends the selection to the parent block
- \o Ctrl+U
- \row
- \o Enable text wrapping
- \o Ctrl+E, Ctrl+W
- \row
- \o Toggle comment for selection
- \o Ctrl+/
- \row
- \o Visualize whitespace
- \o Ctrl+E, Ctrl+V
- \row
- \o Delete
- \o Del
- \row
- \o Adjust size
- \o Ctrl+J
- \row
- \o Lay out in a grid
- \o Ctrl+G
- \row
- \o Lay out horizontally
- \o Ctrl+H
- \row
- \o Lay out vertically
- \o Ctrl+L
- \row
- \o Preview
- \o Alt+Shift+R
- \row
- \o Edit signals and slots
- \o F4
- \row
- \o Edit widgets
- \o F3
- \row
- \o Toggle bookmark
- \o Ctrl+M
- \row
- \o Go to next bookmark
- \o Ctrl+.
- \row
- \o Go to previous bookmark
- \o Ctrl+,
- \row
- \o Fetch snippet
- \o Alt+C, Alt+F
- \row
- \o Paste snippet
- \o Alt+C, Alt+P
- \row
- \o Find usages
- \o Ctrl+Shift+U
- \row
- \o Follow symbol under cursor
-
- Works with namespaces, classes, methods, variables, include
- statements and macros
- \o F2
- \row
- \o Rename symbol under cursor
- \o Ctrl+Shift+R
- \row
- \o Switch between method declaration and definition
- \o Shift+F2
- \row
- \o Open type hierarchy
- \o Ctrl+Shift+T
- \row
- \o Switch between header and source file
- \o F4
- \row
- \o Turn selected text into lowercase
- \o Alt+U
- \row
- \o Turn selected text into uppercase
- \o Alt+Shift+U
- \endtable
-
- \section2 Debugging Keyboard Shortcuts
-
- \table
- \header
- \o Action
- \o Keyboard shortcut
- \row
- \o Start debugging
- \o F5
- \row
- \o Stop or interrupt debugger
- \o Shift+F5
- \row
- \o Reset debugger
- \o Ctrl+Shift+F5
- \row
- \o Step over
- \o F10
- \row
- \o Step into
- \o F11
- \row
- \o Step out
- \o Shift+F11
- \row
- \o Toggle breakpoint
- \o F9
- \row
- \o Run to selected function
- \o Ctrl+F6
- \endtable
-
-
- \section2 Project Keyboard Shortcuts
-
- \table
- \header
- \o Action
- \o Keyboard shortcut
- \row
- \o Build project
- \o Ctrl+B
- \row
- \o Build all
- \o Ctrl+Shift+B
- \row
- \o New project
- \o Ctrl+Shift+N
- \row
- \o Run
- \o Ctrl+R
- \endtable
-
-
- \section2 Help Keyboard Shortcuts
-
- \table
- \header
- \o Action
- \o Keyboard shortcut
- \row
- \o View context-sensitive help
- \o F1
- \row
- \o Activate contents in \gui Help mode
- \o Ctrl+T
- \row
- \o Add bookmark in \gui Help mode
- \o Ctrl+M
- \row
- \o Activate index in \gui Help mode
- \o Ctrl+I
- \row
- \o Reset font size in \gui Help mode
- \o Ctrl+0
- \row
- \o Activate search in \gui Help mode
- \o Ctrl+S
- \endtable
-
-
- \section2 Version Control Keyboard Shortcuts
-
- \table
- \header
- \o {1,2} Action
- \o {5,1} Version control system
- \header
- \o CVS
- \o Git
- \o Perforce
- \o Subversion
- \o Mercurial
- \row
- \o Add
- \o Alt+C, Alt+A
- \o Alt+G, Alt+A
- \o
- \o Alt+S, Alt+A
- \o
- \row
- \o Commit
- \o Alt+C, Alt+C
- \o Alt+G, Alt+C
- \o
- \o
- \o Alt+H, Alt+C
- \row
- \o Diff
- \o Alt+C, Alt+D
- \o Alt+G, Alt+D
- \o
- \o Alt+S, Alt+D
- \o Alt+H, Alt+D
- \row
- \o Diff project
- \o
- \o Alt+G, Alt+Shift+D
- \o Alt+P, Alt+D
- \o
- \o
- \row
- \o Blame
- \o
- \o Alt+G, Alt+B
- \o
- \o
- \o
- \row
- \o Log
- \o
- \o Alt+G, Alt+L
- \o Alt+P, Alt+F
- \o
- \o Alt+H, Alt+L
- \row
- \o Log project
- \o
- \o Alt+G, Alt+K
- \o
- \o
- \o
- \row
- \o Status
- \o
- \o Alt+G, Alt+S
- \o
- \o
- \o Alt+H, Alt+S
- \row
- \o Undo changes
- \o
- \o Alt+G, Alt+U
- \o
- \o
- \o
- \row
- \o Diff project
- \o
- \o Alt+G, Alt+Shift+D
- \o Alt+P, Alt+D
- \o
- \o
- \row
- \o Edit
- \o
- \o
- \o Alt+P, Alt+E
- \o
- \o
- \row
- \o Opened
- \o
- \o
- \o Alt+P, Alt+O
- \o
- \o
- \row
- \o Revert
- \o
- \o
- \o Alt+P, Alt+R
- \o
- \o
- \row
- \o Submit
- \o
- \o
- \o Alt+P, Alt+S
- \o
- \o
- \endtable
-*/
-
-
-/*!
- \contentspage index.html
- \previouspage technical-support.html
- \page creator-glossary.html
- \nextpage creator-acknowledgements.html
-
- \title Glossary
-
- \table
- \header
- \o Term
- \o Meaning
-
- \row
- \o
- \raw HTML
- Qt in 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 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 build
- \endraw
- \target glossary-shadow-build
- \o Shadow building means building a project in a separate
- directory, the \e{build directory}. The build directory is
- different from the source directory. One of the benefits of
- shadow building is that it keeps your source directory clean.
- Shadow building is the best practice if you need many build
- configurations for a single set of source.
- \endtable
-
-*/
-
-
-/*!
- \contentspage index.html
- \previouspage creator-tips.html
- \page creator-known-issues.html
- \nextpage technical-support.html
-
- \title Known Issues
-
- This section lists known issues in Qt Creator version 2.2.0.
- The development team is aware of them, and therefore, you do not need to
- report them as bugs.
-
- For a list of fixed issues and added features, see the changelog file in
- the \c{qtcreator\dist} folder or the \l{https://bugreports.qt.nokia.com}{Qt Bug Tracker}.
-
- \section1 General Issues
-
- \list
-
- \o If you change the Input Languages in Windows, Qt Creator might not
- respond for 30 seconds. This is a known issue in the Advanced Text
- Service of Microsoft Windows.
-
- \o Qt Creator uses SQLite for storing some of its settings. SQLite is
- known to have problems with certain NFS servers (most notably the
- nfs-user-server 2.2beta), since they can lock up the application
- when it tries to lock the database. If your home directory is on an
- NFS share and you encounter this issue, one option would be to
- switch to the nfs-kernel-server, or create a symlink so that the
- settings are stored locally.
-
- \o The Okteta KDE custom widget plugin might be installed as part of
- some Linux distributions. It can cause Qt Designer to crash. For
- more information, see:
-
- \list
-
- \o \l{https://bugs.launchpad.net/ubuntu/+source/kdeutils/+bug/662005}{Ubuntu bug 662005}
- \o \l{https://bugreports.qt.nokia.com/browse/QTBUG-12025}{QTBUG-12025}
-
- \endlist
-
- To resolve the issue, enter the following command to remove the package:
- \code
- sudo apt-get remove okteta
- \endcode
- Or delete the following file:
- \c /usr/lib/kde4/plugins/designer/oktetadesignerplugin.so.
-
- \endlist
-
- \section1 Editing Issues
-
- \list
-
- \o Code completion does not support typedefs for nested classes.
-
- \endlist
-
- \section1 Projects Issues
-
- \list
- \o Paths or file names containing spaces or special characters
- (such as colons, dollar signs, and hash marks) may cause problems. This
- is because some of the tools Qt Creator uses in the background have
- restrictions on the characters allowed in file and directory names.
- To be on the safe side, we recommend creating projects and project
- items with names consisting of plain characters, numbers,
- underscores, and hyphens.
-
- \o Creating new CMake projects with Qt Creator is not supported.
-
- \o On Windows, you must create projects for Maemo 5 and Harmattan
- targets on the same partition where
- you installed \QSDK, Qt Creator, and MADDE.
-
- \o If error messages displayed in the \gui {Compile Output} pane contain
- paths where slashes are missing (for example, C:QtSDK),
- check your PATH variable. For more information, see
- \l{Troubleshooting MinGW Compilation Errors}.
-
- \endlist
-
- \section1 Debugging Issues
-
- \list
-
- \o Debugging large applications on Symbian devices using the Symbian^3
- operating system might not work, because the on-device debugging agent
- might not be able to
- access memory when the operating system starts paging. This causes breakpoint
- handling and symbol resolution to fail. For more information, see
- \l{https://bugreports.qt.nokia.com/browse/QTCREATORBUG-2158}{QTCREATORBUG-2158}.
-
- As a workaround, add the following section to the application .pro file to
- disable paging:
-
- \code
- debug {
- MMP_RULES -= PAGED
- MMP_RULES *= UNPAGED
- }
- \endcode
-
- \note You must completely clean and rebuild the project for the setting to
- take effect.
-
- \o When debugging executables created by the GNU Compiler version 4.5.0
- (all platforms), some data types will not be displayed in the
- \gui{Locals and Expressions} view due to missing debug information.
-
- \o GDB on Windows may not work if the 'Embassy \reg Security Center' software
- by 'Wave \reg Systems' is installed and active (causing crashes in \c{vxvault.dll)}).
-
- \o GDB may take long to load debugging symbols, especially from large
- libraries.
-
- \o Setting breakpoints in code that is compiled into the binary more
- than once does not work.
-
- \o Setting breakpoints in files that do not have unique absolute
- paths may fail. For example, remounting parts of a file system
- using the --bind mount option.
-
- \endlist
-
- \section1 Qt Quick Designer Issues
-
- \list
-
- \o \QMLD uses external processes (QML Puppet) to render and preview
- images and to collect data. Executing C++ code might cause the QML
- Puppet to crash. If it crashes, an error message is displayed and
- you can continue editing the QML file in the code editor.
-
- \endlist
-*/
-
-
-/*!
- \contentspage index.html
- \previouspage creator-glossary.html
- \page creator-acknowledgements.html
-
- \title Acknowledgements
-
- \section1 Third-party Components
-
- Qt Creator contains the following third-party components:
-
- \list
- \o \bold{Open Source front-end for C++ (license MIT)}, enhanced for use in
- Qt Creator.\br
- Roberto Raggi <roberto.raggi@gmail.com>\br
- QtCreator/src/shared/cplusplus\br\br
-
- \o \bold{Botan, a C++ crypto library. Version 1.8.8}\br
- \list
- \o Copyright (C) 1999-2004 The Botan Project. All rights reserved.
- \o Copyright (C) 1999-2009 Jack Lloyd
- \o 2001 Peter J Jones
- \o 2004-2007 Justin Karneges
- \o 2005 Matthew Gregan
- \o 2005-2006 Matt Johnston
- \o 2006 Luca Piccarreta
- \o 2007 Yves Jerschow
- \o 2007-2008 FlexSecure GmbH
- \o 2007-2008 Technische Universitat Darmstadt
- \o 2007-2008 Falko Strenzke
- \o 2007-2008 Martin Doering
- \o 2007 Manuel Hartl
- \o 2007 Christoph Ludwig
- \o 2007 Patrick Sona
- \endlist
- All rights reserved.\br\br
-
- Redistribution and use in source and binary forms, with or without
- modification, are permitted provided that the following conditions are
- met:\br\br
-
- 1. Redistributions of source code must retain the above copyright
- notice, this list of conditions, and the following disclaimer.\br\br
-
- 2. Redistributions in binary form must reproduce the above copyright
- notice, this list of conditions, and the following disclaimer in the
- documentation and/or other materials provided with the distribution.\br
- \br
-
- THIS SOFTWARE IS PROVIDED BY THE AUTHOR(S) "AS IS" AND ANY EXPRESS OR
- IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
- WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE,
- ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR(S) OR CONTRIBUTOR(S) BE
- LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
- CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
- SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
- BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
- WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE
- OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN
- IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.\br\br
- The source code of Botan C++ crypto library can be found
- here:
- \list
- \o QtCreator/src/libs/3rdparty
- \o \l{http://qt.gitorious.org/qt-creator/qt-creator/trees/master/src/libs/3rdparty}
- \endlist
- \br\br
-
- \o \bold{NetSieben SSH Library is a Secure Shell client library for C++.
- Version 1.3.2}\br
- \list
- \o \bold{Commercial License:} For organizations who do not want to
- release the source code for their applications as open source/
- free software; in other words they do not want to comply with the
- GNU General Public License (GPL) or Q Public License.
- \o \bold{Non Commercial / Open Source License:} NetSieben believes in
- contributing back to the open source community, thus it has released
- the SSH Library under Q Public License as it is defined by Trolltech
- AS of Norway. The Open Source License allows the user to use software
- under an open source / free software license, and distribute it
- freely. The software can be used at no charge with the condition
- that if the user uses the SSH Library in an application they wish to
- redistribute, then the complete source code for your application must
- be available and freely redistributable under reasonable conditions.
- For more information on the used QPL License see:
- QtCreator/src/libs/3rdparty/net7ssh/LICENSE.QPL
- \endlist\br\br
- The source code of NetSieben Secure Shell C++ Library can be found
- here:
- \list
- \o QtCreator/src/libs/3rdparty
- \o \l{http://qt.gitorious.org/qt-creator/qt-creator/trees/master/src/libs/3rdparty}
- \endlist
- \endlist
-*/
-
-
-/*!
- \contentspage index.html
- \previouspage creator-mime-types.html
- \page creator-task-lists.html
- \nextpage creator-cli.html
-
- \title Showing Task List Files in the Build Issues Pane
-
- Code scanning and analysis tools create report files in ASCII format.
- Usually, the report files consist of lines that contain a file name, a line
- number, and an error message. A similar format is used for stack traces
- obtained from crash reports. Traditionally, you would fix the errors by
- manually navigating to them and correcting them, which is tedious.
-
- Qt Creator makes this very easy by providing a way to load these files into
- the \gui{Build Issues} pane. You can navigate to the corresponding source
- code by clicking the error message. But first you must convert the files to
- the \l{Task List File Format} by using conversion scripts that based on
- standard text processing tools of the operating system.
-
- In addition, you can generate task list files from code.
- For an example of a script that checks new lines of code and matches them
- against regular expressions to generate a task list, see \c{scripts\mytasks.pl}
- in the Qt Creator repository.
-
- To open task list files, choose \gui{File} > \gui{Open}.
-
- \section1 Task List File Format
-
- The filename extension must be .tasks for Qt Creator to recognize a file as a
- task list file.
-
- Each line in a task list file is treated as a tab-separated list of strings with
- \c{\t}, \c{\n}, and \c{\\} used as escape characters. The strings are used to create
- one task per line. The lines can have one of the following formats:
-
- \list
-
- \o \c description
-
- \o \c{type\tdescription}
-
- \o \c{file\ttype\tdescription}
-
- \o \c{file\tline\ttype\tdescription}
-
- \endlist
-
- The task type can have one of the following values:
-
- \list
-
- \o A string starting with \c err, which displays the error icon in the beginning of the line
- \o A string starting with \c warn, which displays the warning icon
- \o Any other value, which sets the task type to Unknown and does not
- display an icon
-
- \endlist
-
- The values are not case sensitive.
-
- Lines starting with the hash mark character (#) in the first column are ignored.
-
-*/
-
-
-/*!
- \contentspage index.html
- \previouspage creator-task-lists.html
- \page creator-cli.html
- \nextpage creator-keyboard-shortcuts.html
-
- \title Using Command Line Options
-
- You can start Qt Creator and specify some options from the command line.
- For example, you can open a file to any line.
-
- To specify command line options, enter the following command in the Qt Creator
- installation or build directory:
-
- \c {qtcreator [option] [filename[:line_number]]}
-
- \note You can use either a colon (:) or a plus sign (+) as a separator
- between the filename and line number. You can also use a space between the
- separator and the line number.
-
- For example:
-
- \list
-
- \o \c {C:\qtcreator\bin>qtcreator -help}
-
- \o \c {C:\qtcreator\bin>qtcreator C:\TextFinder\textfinder.cpp:100}
-
- \o \c {C:\qtcreator\bin>qtcreator C:\TextFinder\textfinder.cpp +100}
-
- \endlist
-
- The following table summarizes the available options:
-
- \table
- \header
- \o Option
- \o Description
-
- \row
- \o -help
- \o Display help on command line options.
-
- \row
- \o -version
- \o Display Qt Creator version.
-
- \row
- \o -client
- \o Attempt to connect to an already running instance of Qt Creator.
-
- \row
- \o -noload <plugin>
- \o Do not load the specified plugin.
-
- \row
- \o -profile
- \o Output plugin start up and shut down profiling data.
-
- \row
- \o -settingspath <path>
- \o Override the default path where user settings are stored.
-
- \row
- \o -color <color>
- \o Core plugin: override the selected UI color.
-
- \row
- \o -disable-cdb
- \o Debugger plugin: disable the Microsoft Console Debugger (CDB)
- engine. For more information, see \l{Debugging}.
-
- \row
- \o -disable-gdb
- \o Debugger plugin: disable the GNU Symbolic Debugger (GDB) engine.
-
- \row
- \o -disable-sdb
- \o Debugger plugin: disable the Qt Script debugger engine.
-
- \row
- \o -debug <PID-or-corefile>
- \o Debugger plugin: attach to process ID or core file.
-
- \row
- \o -wincrashevent <event-handle>
- \o Debugger plugin: Attach to crashed processes by using the specified
- event handle.
-
- \row
- \o -customwizard-verbose
- \o ProjectExplorer plugin: display additional information when loading
- custom wizards. For more information about custom wizards, see
- \l{Adding New Custom Wizards}
-
- \row
- \o -lastsession
- \o ProjectExplorer plugin: load the last session when Qt Creator starts.
- Open the projects and files that were open when you last exited Qt Creator.
- For more information about managing sessions, see \l{Managing Sessions}.
-
- \endtable
-
-
- */
-
-
- /*!
- \contentspage index.html
- \previouspage creator-maemo-emulator.html
- \page creator-mime-types.html
- \nextpage creator-task-lists.html
-
- \title Editing MIME Types
-
- Qt Creator uses the
- \l{http://en.wikipedia.org/wiki/Internet_media_type}{Internet media type}
- (MIME type) of the file to determine which mode and editor to use for
- opening the file. For example, Qt Creator opens C++ source and header files
- in the C++ editor, and Qt widget based UI files (.ui) in \QD.
-
- To identify the MIME type of a file, Qt Creator uses matching by pattern
- and matching by contents. First, Qt Creator looks at the filename to check
- whether it matches the patterns specified for any MIME type. If no match is
- found, it checks the contents of the file for magic headers specified for the
- file.
-
- The magic headers can contain text strings or bytes. The type of the
- header value, string or byte, determines how Qt Creator interprets the
- value. Qt Creator searches for the value within a specified
- range in the files and takes the priority of the magic header into account.
- If you specify wide search ranges, openging files in Qt Creator might take
- a long time. Therefore, you are advised to use the recommended values for
- the range and priority of the magic header.
-
- If your files do not match the predefined MIME types, you can edit the
- MIME types to add filename extensions and magic headers. You cannot
- add new MIME types, however.
-
- To edit MIME types:
-
- \list 1
-
- \o Select \gui {Tools > Options... > Environment > MIME Types}.
-
- \image qtcreator-mime-types.png "MIME Types"
-
- \o In \gui {MIME Type}, select a MIME type.
-
- \o In \gui Patterns, add the filename extension for the type of files
- that you want to identify as having this MIME type.
-
- \o Click \gui Add to add \gui {Magic Headers}.
-
- \image qtcreator-mime-types-magic-header.png "Magic Header"
-
- \o In the \gui Value field, specify a text string or bytes that
- appear in the files.
-
- \o In the \gui Type field, select the type of the value.
-
- \note You are recommended not to change the range and priority, because
- it might cause problems when opening files in Qt Creator.
-
- \o Click \gui OK.
-
- \endlist
-
- To revert all the changes you have made to the MIME type definitions,
- select \gui {Reset All}.
-
- \note If you now select \gui OK or \gui Apply, you permanently lose all
- your own patterns and magic headers. The changes are reverted the next
- time you start Qt Creator.
-
- */
-
-
- /*!
- \contentspage index.html
- \previouspage creator-debugging-qml.html
- \page creator-troubleshooting-debugging.html
- \nextpage creator-analyze-mode.html
-
- \title Troubleshooting Debugger
-
- This section lists some typical problems that you might encounter while
- debugging and solutions to them.
-
- \section1 Cannot Launch Debugger
-
- Some anti-virus applications do not allow debuggers to retrieve data. For
- example, on Windows, launching the debugger might fail with the following
- message if the Avira AntiVir is installed on the development PC: \e{The
- inferior stopped because it received a signal from the operating system.
- Signal name:? signal meaning: Unknown signal.}
-
- Some versions of Avira AntiVir Desktop-Products contain known issues in
- various development environments, including Qt Creator. To fix the problem,
- Avira instructs you to update to version \c {avipbb.sys 10.0.22.22}. For
- more information, see
- \l{http://www.avira.com/en/support-for-business-knowledgebase-detail/kbid/805}{Restricted Usability of IDE/Debuggers since 2010-12-08}.
-
- \section1 Debugger Does Not Hit Breakpoints
-
- You might have created a release build that does not contain debug
- information. A GNU Compiler Collection (GCC) debug build has the \c {-g}
- option on the compiler command line. Check that this option is present in
- the \gui {Compile Output} pane. If it is not, adjust your build settings
- in the \gui {Projects} mode.
-
- \section1 Debugger Does Not Work
-
- If the debugger does not work properly, try the following:
-
- \list 1
-
- \o Make sure you use at least Qt Creator 2.1.
-
- \o Make sure the debugger is set up properly. For more information,
- see \l{Setting Up Debugger}.
-
- \o In the \gui Debug mode, select \gui {Windows > Views > Debugger
- Log} to open the \gui {Debugger Log} view. Browse the contents of
- the pane on the right hand side to find out what went wrong.
- Always attach the contents of the pane to debugger-related
- questions to the Qt Creator mailing list (qt-creator@trolltech.com)
- or paste them to
- \l{http://creator.pastebin.com}{creator.pastebin.com} before
- asking questions in the IRC (on the #qt-creator channel at
- FreeNode).
-
- \endlist
-
- \section1 Pointer Variable Members Are Not Displayed Directly
-
- When you use the \gui {Locals and Expressions} view to inspect a pointer
- variable and expand the variable tree item, another tree item level
- is displayed. To directly display the members of the pointer variable,
- select \gui {Dereference Pointers Automatically} in the context menu in the
- \gui {Locals and Expressions} view.
-
- \section1 Structure Members Are Not Sorted According to Structure Layout
-
- By default, structure members are displayed in alphabetic order.
- To inspect the real layout in memory, deselect \gui {Sort Members of
- Classes and Structs Alphabetically} in the context menu in the
- \gui {Locals and Expressions} view.
-
- \section1 Built-in Debugger Is Slow During Startup and Runtime
-
- The Qt Creator for Windows installation packages install GDB from MinGW.
- Unfortunately, GDB is quite slow on Windows. Qt Creator does not cause
- this, as it interacts with GDB and adds custom dumpers for Qt types.
-
- \note You can use Qt Creator with MSVC on Windows for debugging.
-
- \section1 Debugger Displays <not in scope> Message
-
- The message is created by the debugging helpers. Qt Creator posts an
- expression to the GDB command line to invoke the debugging helpers.
- The expression includes the address of the object to examine. This
- address might be modified by GDB before the helper function is called. It
- is unclear why and when this happens, but if it happens, the debugging
- helpers operate on wrong data and come to wrong conclusions. Most likely,
- they find garbage and declare the variable to be <not in scope>.
-
- \section1 Application Crashes when Debugging on Mac OS X Snow Leopard
-
- You must use a workaround to use the DYLD_IMAGE_SUFFIX option in the
- \gui Projects tab on Mac OS X Snow Leopard. For more information on the
- issue, see
- \l{http://wimleers.com/blog/dyld-image-suffix-causing-havoc-on-mac-os-x-snow-leopard}{DYLD_IMAGE_SUFFIX causing havoc on Mac OS X Snow Leopard}.
-
- To use the option, enter the following commands in the Terminal
- application:
- \code
- sudo mv /usr/lib/libSystem.B_debug.dylib /usr/lib/libSystem.B_debug.dylib.backup
- sudo cp /usr/lib/libSystem.B.dylib /usr/lib/libSystem.B_debug.dylib.backup
- \endcode
-
- \section1 Debugger Cannot Attach to Running Process on Linux
-
- GDB uses \c ptrace to attach to running processes. Some Linux distributions
- do not allow this, which stops all attempts to either directly attach to an
- existing process or use the \gui {Run in terminal} option in Qt Creator.
-
- The reasons for this are described in
- \l{https://wiki.ubuntu.com/SecurityTeam/Roadmap/KernelHardening#ptrace%20Protection}{KernelHardening}.
-
- However, the usefulness of this security measure seems dubious,
- because this feature can be easily disabled. With root permissions, you can
- disable the feature immediately by writing \c{0} into
- \c{/proc/sys/kernel/yama/ptrace_scope}. Even if you do not have elevated
- permissions, you can disable the feature later by adding a library that
- calls \c{prctl(0x59616d61, getppid(), 0, 0, 0);}, such as the one in
- \c{$QTCREATORDIR/lib/libptracepreload.so} to the LD_PRELOAD environment.
-
- */
-
-
- /*!
- \contentspage index.html
- \previouspage creator-qml-performance-monitor.html
- \page creator-analyzer.html
- \nextpage creator-cache-profiler.html
-
- \title Detecting Memory Leaks
-
- You can use the Memcheck tool included in the
- \l{http://valgrind.org/info/tools.html}{Valgrind tool suite} to detect
- problems that are related to memory management in applications.
-
- \note Memcheck is supported locally on Linux and Mac OS. You can run it on
- a remote host from Windows.
-
- After you download and install Valgrind tools, you can use Memcheck from Qt
- Creator.
- To analyze applications:
-
- \list 1
-
- \o In the \gui Projects mode, select a release build configuration.
-
- \o Select \gui Analyze to open the \gui Analyze mode.
-
- \o Select \gui {Analyze Memory} on the toolbar.
-
- \o Select the
- \inlineimage qtcreator-analyze-start-button.png "Start button"
- button to start the application.
-
- \o Use the application to analyze it.
-
- \o Select the
- \inlineimage qtcreator-analyzer-stop-button.png "Stop button"
- button to view the results of the analysis in the
- \gui {Analysis} view.
-
- \endlist
-
- While the application is running, Memcheck checks all reads and writes of
- memory and intercepts calls that allocate or free memory or create or
- delete memory blocks. When you stop Memcheck, it displays the results in
- the \gui Analysis view. Click a line to view where a memory leak
- occurred and a stack trace that shows what caused it.
-
- \image analyzer-issues.png "Analysis view"
-
- Move the mouse on on a row to view more information about the function.
-
- For more information about using Memcheck, see
- \l{http://valgrind.org/docs/manual/quick-start.html#quick-start.mcrun}
- {Interpreting Memcheck's Output} in the Valgrind documentation.
-
- \section1 Selecting Options for Memory Analysis
-
- Stack traces can get quite large and confusing, and therefore, reading them
- from the bottom up can help. If the stack trace is not big enough or it is
- too big, select \gui {Tools > Options... > Analyzer}.
- Define the length of the stack trace in the \gui {Backtrace frame count}
- field.
-
- \image qtcreator-valgrind-memcheck-options.png "Memory Analysis options"
-
- Memcheck also reports uses of uninitialised values, most commonly with the
- message \gui {Conditional jump or move depends on uninitialised value(s).}
- To determine the root cause of these errors, the \gui {Track origins of
- uninitialized memory} check box is selected by default. You can deselect it
- to make Memcheck run faster.
-
- Memcheck detects numerous problems in the system libraries, such as the C
- library, which come pre-installed with your OS. As you cannot easily fix
- them, you want to suppress them. Valgrind reads a list of errors to suppress
- at startup. A default suppression file is created by the ./configure script
- when the system is built.
-
- You can write your own suppression files if parts of your project contain
- errors you cannot fix and you do not want to be reminded of them. Click
- \gui Add in the \gui {Memory Analysis} dialog to add the suppression files.
- For more information about writing suppression files, see
- \l{http://valgrind.org/docs/manual/manual-core.html#manual-core.suppress}
- {Suppressing Errors} in the Valgrind documentation.
-
- */
-
-/*!
- \contentspage index.html
- \previouspage creator-analyzer.html
- \page creator-cache-profiler.html
- \nextpage creator-running-valgrind-remotely.html
-
- \title Profiling Function Execution
-
- You can use the Callgrind tool included in the
- \l{http://valgrind.org/info/tools.html}{Valgrind tool suite} to detect
- problems that are related to executing functions.
-
- After you download and install Valgrind tools, you can use Callgrind from Qt
- Creator.
-
- \note Callgrind is supported locally on Linux and Mac OS. You can run it on
- a remote host from Windows.
-
- To analyze applications:
-
- \list 1
-
- \o In the \gui Projects mode, select a release build configuration.
-
- \o Select \gui Analyze to open the \gui Analyze mode.
-
- \o Select \gui Profile on the toolbar.
-
- \o Select the
- \inlineimage qtcreator-analyze-start-button.png "Start button"
- button to start the application.
-
- \o Use the application to analyze it.
-
- \o Select the
- \inlineimage qtcreator-analyzer-stop-button.png "Stop button"
- button to view the results of the analysis in the \gui Profile
- view.
-
- \endlist
-
- Callgrind records the call history of functions that are executed when the
- application is run. It collects the number of instructions that are
- executed, their relationship to source lines, the relationships of the
- caller and callee between functions, and the numbers of such calls. You can
- also use cache simulation or branch prediction to gather information about
- the runtime behavior of an application.
-
- Double-click a function to view information about the calling functions in
- the \gui Callers view and about the called functions in the \gui Callees
- view.
-
- \image qtcreator-valgrind-callgrind.png "Profile view"
-
- \section1 Selecting Profiling Options
-
- To specify settings for Valgrind, select \gui {Tools > Options... >
- Analyzer}. The \gui {Profiling Options} group contains Callgrind options.
-
- \image qtcreator-valgrind-callgrind-options.png "Valgrind options"
-
- In the \gui {Result view: Minimum event cost}
- field, limit the amount of results the profiler gives you to increase
- profiler performance.
-
- You can collect information about the system call times and the number of
- global bus events of the event type \c Ge that are executed.
-
- \section2 Enabling Full Cache Simulation
-
- By default, only instruction read accesses (Ir) are counted. To fully
- simulate the cache, select the \gui {Enable cache simulation} check box.
- This enables the following additional event counters:
-
- \list
-
- \o Cache misses on instruction reads (I1mr/I2mr)
-
- \o Data read accesses (Dr) and related cache misses (D1mr/D2mr)
-
- \o Data write accesses (Dw) and related cache misses (D1mw/D2mw)
-
- \endlist
-
- \section2 Enabling Branch Prediction Simulation
-
- To enable the following additional event counters, select the
- \gui {Enable branch prediction simulation} check box:
-
- \list
-
- \o Number of conditional branches executed and related predictor misses
- (Bc/Bcm)
-
- \o Executed indirect jumps and related misses of the jump address
- predictor (Bi/Bim)
-
- \endlist
-
-*/
-
-
- /*!
- \contentspage index.html
- \previouspage creator-help.html
- \page creator-advanced.html
- \nextpage creator-os-supported-platforms.html
-
- \title Advanced Use
-
- Qt Creator attempts to meet your development needs, whether you are an
- experienced Qt developer or a newcomer to Qt. When you install Qt Creator
- as a part of \QSDK, the default configuration allows you to start coding,
- building, running and debugging applications with very little effort.
-
- However, you can easily change or extend the default configuration, by
- choosing a different build system, adding project wizards, integrating
- external tools, or editing the standard MIME types that Qt Creator uses
- to recognize your files.
-
- You can start Qt Creator and specify some options for running it from the
- command line.
-
- This following topics describe advanced use of Qt Creator:
-
- \list
- \o \l{Operating Systems and Supported Platforms}
- \o \l{Adding New Custom Wizards}
- \o \l{Setting Up a CMake Project}
- \o \l{Setting Up a Generic Project}
- \o \l{Using Version Control Systems}
- \o \l{Adding Qt Designer Plugins}
- \o \l{Using External Tools}
- \o \l{Using Maemo or MeeGo Harmattan Emulator}
- \o \l{Editing MIME Types}
- \o \l{Showing Task List Files in the Build Issues Pane}
- \o \l{Using Command Line Options}
- \o \l{Keyboard Shortcuts}
- \o \l{Glossary}
- \endlist
-
- */
-
- /*!
- \contentspage index.html
- \previouspage creator-known-issues.html
- \page technical-support.html
- \nextpage creator-glossary.html
-
- \title Technical Support
-
- The following table lists Qt support sites and other useful links.
-
- \table
- \header
- \o What Do You Want to Do
- \o Where to Go
-
- \row
- \o Learn more about Qt
- \o \l{http://qt.nokia.com/developer/learning/online/training/specialized-elearning/}
- {Specialized eLearning Modules Based on Qt Training Modules}
-
- \row
- \o Develop Qt applications for desktop and mobile devices
- \o \l{http://developer.qt.nokia.com/}{Qt Developer Network}
-
- \row
- \o Develop Qt applications for Nokia mobile devices
- \o \l{http://www.developer.nokia.com/Develop/Qt/}{Nokia Developer - Qt}
-
- \row
- \o Participate in Qt development
- \o \l{http://qt.gitorious.org/}{Qt Git Hosting}
-
- \row
- \o Find free Qt-based applications
- \o \l{http://qt-apps.org/}{Qt Apps}
-
- \row
- \o Buy commercial Qt support from Digia
- \o \l{http://qt.digia.com/}{Qt Commercial}
- \endtable
-
- */
-
-
-/*!
- \contentspage index.html
- \previouspage creator-troubleshooting-debugging.html
- \page creator-analyze-mode.html
- \nextpage creator-qml-performance-monitor.html
-
- \title Analyzing Code
-
- The memory available on mobile devices is limited and you should use it
- carefully. Qt Creator contains tools that you can use to analyze your code.
-
- The \gui {QML Profiler} allows you to profile your Qt
- Quick applications. You can inspect binding evaluations, signal handling,
- and painting operations when running QML code. This is useful for
- identifying potential bottlenecks, especially in the evaluation of bindings.
-
- In addition, Qt Creator integrates Valgrind code analysis tools for
- detecting memory leaks and profiling function execution. These tools are
- supported locally only on Linux and Mac OS. You can run them on a remote
- host from Windows. You have to download and install them
- separately to use them from Qt Creator.
-
- You can use the code analysis tools in the \gui Analyze mode. To switch to
- \gui Analyze mode, select \gui Analyze in the mode selector, or select the
- \gui {Analyze} menu and then select a tool. When you are in the
- \gui Analyze mode, you can switch
- between tools by selecting them in the menu on the toolbar.
-
- \image qtcreator-analyze-menu.png "Analyze mode menu"
-
- By default, the views in the \gui Analyze mode are locked into place in the
- workspace. Select \gui {Window > Views > Locked} to unlock the views. Drag
- and drop the views into new positions on the screen. Drag view borders to
- resize the views. The size and position of views are saved for future
- sessions. Select \gui {Window > Views > Reset to Default Layout} to reset
- the views to their original sizes and positions.
-
- To run the Valgrind tools on a remote host over SSH, select \gui {Analyze
- > Valgrind Analyze Memory (Remote)} or \gui {Valgrind Function Profile
- (Remote)}.
-
- To stop the currently running analyzer, select \gui {Analyze
- > Stop}.
-
- To select options for the Valgrind tools, select \gui {Tools > Options... >
- Analyzer}. You can override the general settings for each project in the
- \gui {Run Settings} for the project.
-
- The following sections describe how to use the code analysis tools:
-
- \list
-
- \o \l{Profiling QML Applications} describes how to inspect binding
- evaluations, signal handling, and painting operations when running
- QML code.
-
- \o \l{Detecting Memory Leaks} describes how to use the Valgrind
- Memcheck tool to detect problems in memory management.
-
- \o \l{Profiling Function Execution} describes how to use the Valgrind Callgrind
- tool to find cache misses in the code.
-
- \o \l{Running Valgrind Tools Remotely} describes how to run the
- Valgrind tools on a remote host.
-
- \endlist
-
-*/
-
-
-/*!
- \contentspage index.html
- \previouspage creator-analyze-mode.html
- \page creator-qml-performance-monitor.html
- \nextpage creator-analyzer.html
-
- \title Profiling QML Applications
-
- To monitor the performance of an application in the QML Profiler:
-
- \list 1
-
- \o To be able to profile an application, you must set up QML debugging
- for the project. For more information, see
- \l{Setting Up QML Debugging}.
-
- \o In the \gui Projects mode, select Qt 4.7.4 in the \gui {Qt version}
- field.
-
- \note To profile applications on devices, you must install Qt 4.7.4
- or later libraries on them.
-
- \o Select \gui {Analyze > QML Profiler} to profile the current
- application.
-
- \image qtcreator-qml-performance-monitor-toolbar.png "QML Profiler toolbar"
-
- \o Select the
- \inlineimage qtcreator-analyze-start-button.png "Start button"
- button to start the application from the QML Profiler.
-
- \note If data collection does not start automatically, select the
- \inlineimage qtcreator-analyzer-button.png "Analyzer button"
- button.
-
- \endlist
-
- When you start analyzing an application, the application is launched, and
- the QML Profiler immediately begins to collect data. This is indicated by
- the time running in the \gui Elapsed field.
-
- Data is collected until you select the
- \inlineimage qtcreator-analyzer-stop-button.png "Stop button"
- button. Data collection takes time, and therefore, there might be a delay
- before the data is displayed.
-
- Do not use application commands to exit the application, because data is
- sent to the QML Profiler when you select the \gui Stop button.
- The application continues to run for some seconds, after which it is stopped
- automatically. If you exit the application, the data is not sent.
-
- Select the \inlineimage qtcreator-analyzer-button.png "Analyzer button"
- button to disable the automatic start of the data collection when an
- application is launched. Data collection starts when you select the button
- again.
-
- \section1 Analyzing Collected Data
-
- The \gui Timeline view displays graphical representations of:
-
- \list
-
- \o Painting operations
-
- \o Compiling the QML sources
-
- \o Creating elements
-
- \o Binding evaluations
-
- \o Signal handling
-
- \o Summary of the recorded period
-
- \endlist
-
- \image qtcreator-qml-performance-monitor.png "QML Profiler"
-
- The outline summarizes the period for which data was collected. Drag the
- zoom range or click the outline to move on the outline. You can also move
- between events by clicking the \gui Previous and \gui Next buttons.
-
- Click the zoom buttons or drag the zoom handles to zoom in and out.
-
- You can define an event range to view the frame rate of events and to
- compare it with the frame rate of similar events. Click on the timeline to
- specify the beginning of the event range. Drag the cursor to define the end
- of the range. The length of the range indicates the frame rate of the event.
- You can drag the timeline below the event range to compare events.
-
- Additional information is displayed on the rows above the outline.
- Each row in the timeline describes a type of QML events that were recorded.
- Move the cursor on an event on a row to see how long it takes and where
- in the source it is being called.
-
- On the \gui Binding row, you can see when a binding is evaluated and how
- long the evaluation takes. Move the mouse over the binding for details
- about the binding: location in the source code, duration, and source
- code.
-
- Click the binding to move the cursor in the code editor to the part of the
- code where the binding is called.
-
- The time bar at the top of the \gui Timeline view displays the time in
- seconds. To see the time in milliseconds, move the mouse on the time bar.
-
- \section1 Viewing Events
-
- The \gui Events view displays the number of times each binding is called
- and the time the calls take. This allows you to examine which events you
- need to optimize. A high number of calls might indicate that a binding is
- called unnecessarily. Click on a binding to move to it in the source code
- in the code editor.
-
- \image qtcreator-analyzer-bindings.png "Events view"
-
- \section1 Viewing Calling and Called Events
-
- The \gui Callees and \gui Callers views show dependencies between events.
- They allow you to examine the internal functions of the application.
-
- The \gui Callees view summarizes the QML events that a binding triggers.
- This tells you which QML events are affected if you change a binding.
-
- \image qtcreator-qml-performance-monitor-callees.png "Callees view"
-
- The \gui Callers view summarizes the QML events that trigger a binding.
- This tells you what caused a change in a binding.
-
- \image qtcreator-qml-performance-monitor-callers.png "Callers view"
-
- Click on a binding to move to it in the source code in the code editor.
-
- \section2 Viewing More Data
-
- The QML JavaScript engine optimizes trivial bindings. The QML Profiler
- does not receive information about optimized bindings, and
- therefore, it displays the text \gui {<bytecode>} and the message
- \gui {Source code not available} in the \gui Callees and \gui {Callers}
- views.
-
- To inspect the optimized bindings, turn off the QML optimizer by setting the
- environment variable QML_DISABLE_OPTIMIZER to 1. To set the environment
- variable for the current project in the project settings:
-
- \list 1
-
- \o Select \gui {Projects > Run}.
-
- \o In \gui {Run Environment}, click \gui Add.
-
- \o Add the QML_DISABLE_OPTIMIZER variable and set its value to 1.
-
- \endlist
-
-*/
-
-
-/*!
- \contentspage index.html
- \previouspage creator-cache-profiler.html
- \page creator-running-valgrind-remotely.html
- \nextpage creator-deployment.html
-
- \title Running Valgrind Tools Remotely
-
- Qt Creator integrates Valgrind code analysis tools for detecting memory
- leaks and profiling function execution. These tools are supported locally
- only on Linux and Mac OS, but you can run them on a remote host from
- Windows.
-
- To run the Valgrind tools on a remote host over SSH:
-
- \list 1
-
- \o Select \gui {Analyze > Valgrind Analyze Memory (Remote)} or
- \gui {Valgrind Function Profile (Remote)}.
-
- \image qtcreator-valgrind-remote-settings.png "Start Debugger dialog"
-
- \o In the \gui Remote group, specify the connection to the remote host.
-
- \o In the \gui Target group, specify the application to run and analyze
- on the remote host.
-
- \endlist
-
-*/
OSDN Git Service
