Commit b43b6adb authored by Leena Miettinen's avatar Leena Miettinen
Browse files

Add information about using QML inspector.

Reviewed-by: Lasse Holmstedt
parent b3284a1e
......@@ -69,12 +69,19 @@
\o \l{Developing Qt Quick Applications}
\o \l{Optimizing Applications for Mobile Devices}
\o \l{Debugging}
\o \l {Debugging Qt Applications}
\o \l{Debugging the Example Application}
\o \l{Interacting with the Debugger}
\o \l{Setting Up Debugger}
\o \l{Using Debugging Helpers}
\o \l{Debugging Qt Quick Applications}
\o \l{Using the QML Inspector}
\o \l{Using Version Control Systems}
\o \l{Adding Qt Designer Plugins}
\o \l{Tips and Tricks}
......@@ -2493,7 +2500,7 @@
\contentspage index.html
\previouspage creator-debugging-helpers.html
\previouspage creator-qml-inspector.html
\page creator-version-control.html
\nextpage adding-plugins.html
......@@ -2938,14 +2945,236 @@
\contentspage index.html
\previouspage creator-usability.html
\page creator-debugging.html
\nextpage creator-debugging-example.html
\nextpage creator-debugging-cpp.html
\title Debugging
You can use the Qt Creator \gui Debug mode to inspect the state of your
Qt and Qt Quick projects while debugging.
Qt Creator does not include a debugger. It provides a debugger plugin that acts
as an interface between the Qt Creator core and external native debuggers
such as the GNU Symbolic Debugger (gdb), the Microsoft Console Debugger (CDB),
and an internal Java Script debugger.
and an internal Java Script debugger. You can use the native debuggers to
debug the C++ language.
\image qtcreator-debugger-views.png "Native debugger views"
Qt Creator includes a QML inspector plugin that you can use to debug QML.
\image qmldesigner-inspector.png "QML inspector views"
When you start debugging, the appropriate tool is automatically selected depending
on the type of the project. If you only develop one kind of projects, you can turn
off this automation in \gui {Tools > Options > Debugger > General}. Deselect the
\gui {Change debugger language automatically} check box.
The choice of language also determines the contents of the \gui Debug menu.
The \gui {Start Debugging > Start Debugging} command starts debugging by using the
tool appropriate for the project type. The availability of the other commands depends
on whether \gui C++ or \gui QML is selected in \gui {Debug > Language}.
You can create Qt Quick projects that contain C++ plugins or Qt projects that contain
QML content. While debugging such projects, you can switch between the native
debuggers and the QML inspector during debugging.
To switch between debugged languages, select \gui {Debug > Language > C++} or
\gui QML. You can also press \key {Ctrl+L, 1} to switch to the native debugger and
\key {Ctrl+L, 2} to switch to the QML inspector.
\contentspage index.html
\previouspage creator-debugging-helpers.html
\page creator-debugging-qml.html
\nextpage creator-qml-inspector.html
\title Debugging Qt Quick Applications
In the \gui Debug mode you can use the QML inspector plugin to:
\o View the status of the application when it is executed.
\o View debug output.
\o Write JavaScript expressions and evaluate them.
\o Modify the values of properties.
\o Watch the values of expressions.
\note You can press \key {Ctr+Alt+R} or select \gui {Tools > Qt Quick > Preview}
to view QML files that do not belong to projects in the QML viewer. However,
you can only debug QML files that belong to open projects, because the QML
inspector plugin needs information about the project.
\section1 Modes of Operation
When a Qt Quick project is active and you select \gui {Debug > Start Debugging >
Start Debugging} the application is started in the QML viewer and inspected by
the QML inspector.
If the Qt Quick project includes C++ plugins, select
\gui {Debug > Start Debugging > Start Debugging C++ and QML Simultaneously}.
The QML runtime is started, debugged with the native debugger, and attached to
the QML viewer.
\note This command is available only if \gui QML is selected in
\gui {Debug > Language (QML)}.
To debug a Qt project that contains QML content, select
\gui {Debug > Start Debugging > Start Debugging C++ and QML Simultaneously}.
The application is started under the control of the native debugger, attached
to the QML viewer, and inspected by the QML inspector.
You must use the native debugger to set breakpoints to C++ code and to examine
the state of the interrupted Qt application. When a C++ program is interrupted,
for example when a breakpoint is hit, you cannot use the QML inspector.
\contentspage index.html
\previouspage creator-debugging-qml.html
\page creator-qml-inspector.html
\nextpage creator-version-control.html
\title Using the QML Inspector
In \gui Debug mode, you can use several views to interact with the
application you are debugging. Frequently used views are shown by
default and rarely used ones are hidden. To change the default settings,
select \gui Debug > \gui Views, and then select views to display
or hide. You can also lock views. The position of views is saved for future
\image qmldesigner-inspector.png "QML inspector views"
\section1 Starting the QML Inspector
To start an active application under the control of the QML inspector, select
\gui {Debug > Start Debugging > Start Debugging}, or press \key{F5}.
The application is run in the QML viewer. It behaves and performs as usual.
You can view the status of the application when it is executed and the debug
output in the \gui {Application Output} view.
\image qmldesigner-application-output.png "Application Output view"
\section1 Starting Simultaneous QML and C++ Debugging
To debug a Qt Quick project that includes C++ plugins, select
\gui {Debug > Start Debugging > Start Debugging C++ and QML Simultaneously}.
\note This command is available only if \gui QML is selected in
\gui {Debug > Language (QML)}.
\image qmldesigner-debugging-simultaneous.png "Start Simultaneous QML and C++ Debugging view"
Usually, the settings for the QML viewer are specified automatically and you do
not need to change them:
\o \gui {Debugging address} is the local IP address to access the QML viewer.
\o \gui {Debugging port} is the port to access the QML viewer. You can use any
free port in the registered port range.
\o \gui {Viewer path} is the path to QML viewer executable.
\o \gui {Viewer arguments} sets arguments for running the QML viewer.
The \c{-I <directory>} argument searches for C++ or QML plugins from
the project folder. For a list of available arguments, enter \c {qml --help}
on the command line.
The QML runtime is started, debugged with the native debugger, and attached to
the QML viewer.
\section1 Viewing and Modifying Values of Properties
The \gui {Properties and Watchers} view lists the JavaScript expressions
in the project and their properties and values. The properties are grouped
by type, but you can also view them in one long list.
Right-click the list of properties to open a context-menu and then click
\gui {Group by Item Type} to change the way in which the properties are
If an item does not have an ID, you cannot change the values of its
properties. The item type is enclosed in angle brackets and the value
is grayed.
Double-click an item to move to the place in code where it is declared.
You can change the values of properties and see the results in the QML viewer.
If the QML inspector cannot retrieve the value for an item or a property for
inspection, the item or property is grayed in the view. Right-click the item list
to open a context menu, and then click \gui {Show Uninspectable Items} to hide
or show the items that cannot be inspected.
\section1 Watching Expressions
In the \gui {Properties and Watchers} view, you can specify that an expression is
watched. Right-click a property and then click \gui {Watch Expression}.
The \gui Name and \gui Value of the expression are displayed at the bottom
of the view.
\image qmldesigner-inspector-watchers.png "Watched expressions"
You can add JavaScript expressions to object instances to evaluate them.
Right-click the list of items and select \gui {Add Watch Expression}. Enter
the expression to evaluate and click \gui OK.
\image qmldesigner-inspector-add-watch.png "Add Watch Expression dialog"
To stop watching a expression, right-click it and select \gui {Stop Watching}.
The QML inspector cannot show the values for some items, such as composite objects
or complicated item that you cannot change. These items cannot be watched.
To show them, right-click the properties list, and then select
\gui {Show Unwatchable Properties}.
\section1 Executing JavaScript
In the \gui {Script Console} view, you can write JavaScript expressions, see
how they are executed, and evaluate them during runtime.
You can also test the C++ code without rebuilding the whole application.
\section1 Viewing Connections to the QML Viewer
The \gui Output view displays the status of the connection between the QML
inspector and the QML viewer.
You specify the connection in the \gui {Run Settings} in the \gui Projects mode.
For more information, see \l{Run Settings}.
If the connection does not work, check the values of the \gui {Debugging address}
and \gui {Debugging port} fields. Check that the default port number is not reserved
by another application or another instance of the QML viewer that was not shut
down properly. You can specify any free port number in the registered port range
\contentspage index.html
\previouspage creator-debugging.html
\page creator-debugging-cpp.html
\nextpage creator-debugging-example.html
\title Debugging Qt Applications
In the \gui Debug mode you can interact with the debugger in several ways, including
the following:
......@@ -3532,7 +3761,7 @@
\contentspage index.html
\previouspage creator-debugging.html
\previouspage creator-debugging-cpp.html
\page creator-debugging-example.html
\nextpage creator-debug-mode.html
......@@ -3617,7 +3846,7 @@
\contentspage index.html
\previouspage creator-debugger-engines.html
\page creator-debugging-helpers.html
\nextpage creator-version-control.html
\nextpage creator-debugging-qml.html
\title Using Debugging Helpers
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment