diff --git a/doc/qtcreator.qdoc b/doc/qtcreator.qdoc
index 5c7f9b41e0eed924313b71f8830456de2fa89dce..e9359f6b1ed2ee7d7dc8a1a1c9c2222a9ff42cc1 100644
--- a/doc/qtcreator.qdoc
+++ b/doc/qtcreator.qdoc
@@ -4713,14 +4713,13 @@
d.putNumChild(size)
if d.isExpanded(item):
p = gdb.Value(p_ptr["array"]).cast(innerType.pointer())
- d.beginChildren([size, 2000], innerType)
- for i in d.childRange():
- d.safePutItem(Item(p.dereference(), item.iname, i))
- p += 1
- d.endChildren()
+ with Children(d, [size, 2000], innerType)
+ for i in d.childRange():
+ d.putItem(Item(p.dereference(), item.iname, i))
+ p += 1
\endcode
- \section2 Item Python Class
+ \section2 Item Class
The Item Python class is a thin wrapper around values corresponding to one
line in the \gui{Locals and Watchers} view. The Item members are as follows :
@@ -4746,7 +4745,7 @@
\endlist
- \section2 Dumper Python Class
+ \section2 Dumper Class
For each line in the \gui{Locals and Watchers} view, a string like the
following needs to be created and channeled to the debugger plugin.
@@ -4791,26 +4790,14 @@
\o \gui{putField(self, name, value)} - Appends a comma if needed, and a
name='value' field.
- \o \gui{beginHash(self)} - Appends a comma if needed and a '{', marking
- the begin of a set of fields.
-
- \o \gui{endHash(self)} - Appends a '}', marking the end of a set of
- fields.
-
\o \gui{beginItem(self, name)} - Starts writing a field by writing \c {name='}.
\o \gui{endItem(self)} - Ends writing a field by writing \c {'}.
- \o \gui{beginChildren(self, numChild_ = 1, childType_ = None, childNumChild_ = None)}
- - Starts writing a list of \c numChild children, with type
- \c childType_ and \c childNumChild_ grandchildren each. If \c numChild_
- is a list of two integers, the first one specifies the actual number
- of children and the second the maximum number of children to print.
-
\o \gui{endChildren(self)} - Ends writing a list of children.
- \o \gui{childRange(self)} - Return the range of children specified in
- \c beginChildren.
+ \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.
@@ -4907,35 +4894,51 @@
over base classes and class members of compound types and calls
\c qdump__* functions whenever appropriate.
- \o \gui{putItem(self, item)} - Equivalent to:
+ \o \gui{putItem(self, item)} - Equivalent to:
\code
- self.beginHash()
- self.putItemHelper(item)
- self.endHash()
+ with SubItem(self):
+ self.putItemHelper(item)
\endcode
-
- \o \gui{safePutItemHelper(self, item)} - Calls \c putItemHelper(self, item).
- If an exception is raised, catches it, and replaces all output produced by
- \c putItemHelper with the output of:
+ Exceptions raised by nested function calls are caught and all
+ output produced by \c putItemHelper is replaced by the output of:
\code
- self.putName(item.name)
- self.putValue("<invalid>")
- self.putType(str(item.value.type))
- self.putNumChild(0)
- self.beginChildren()
- self.endChildren()
+ ...
+ except RuntimeError:
+ d.put('value="<invalid>",type="<unknown>",numchild="0",')
\endcode
+ \endlist
- \o \gui{safePutItem(self, item)} - Equivalent to:
- \code
- self.beginHash()
- self.safePutItemHelper(item)
- self.endHash()
- \endcode
- \endlist
+ \section2 Children and SubItem Class
+
+ Child items might report errors if data is uninitialized or corrupted
+ or if the helper code is broken. To gracefully recover from these
+ errors, use \c Children and \c SubItem \e{Context Managers} to create
+ nested items.
+
+ The \c Children constructor \gui{__init__(self, dumper, numChild = 1,
+ childType = None, childNumChild = None)} uses one non-optional argument
+ \c dumper to refer to the current \c Dumper object and three optional
+ arguments, specifying the number \c numChild of children, with type
+ \c childType_ and \c childNumChild_ grandchildren each. If \c numChild_
+ is a list of two integers, the first one specifies the actual number
+ of children and the second the maximum number of children to print.
+ Similarly, using the \SubItem class helps to protect individual items.
+
+ Example:
+ \code
+ d.putNumChild(2)
+ if d.isExpanded(item):
+ with Children(d):
+ with SubItem(d):
+ d.putName("key")
+ d.putItemHelper(Item(key, item.iname, "key"))
+ with SubItem(d):
+ d.putName("value")
+ d.putItemHelper(Item(value, item.iname, "value"))
+ \endcode
*/
diff --git a/tests/manual/gdbdebugger/simple/app.pro b/tests/manual/gdbdebugger/simple/app.pro
new file mode 100644
index 0000000000000000000000000000000000000000..cd157e8ceabfa34b0eb2b56a76275c665a719b1d
--- /dev/null
+++ b/tests/manual/gdbdebugger/simple/app.pro
@@ -0,0 +1,12 @@
+TEMPLATE = app
+TARGET = debuggertest
+DEPENDPATH += .
+INCLUDEPATH += .
+DESTDIR = .
+
+# Input
+SOURCES += app.cpp
+
+# SOURCES += ../../../share/qtcreator/gdbmacros/gdbmacros.cpp
+QT += network
+message("this says <foo & bar>")
diff --git a/tests/manual/gdbdebugger/simple/plugin.pro b/tests/manual/gdbdebugger/simple/plugin.pro
new file mode 100644
index 0000000000000000000000000000000000000000..911dc2481e2273abd34932be98486662dd602d7f
--- /dev/null
+++ b/tests/manual/gdbdebugger/simple/plugin.pro
@@ -0,0 +1,18 @@
+TEMPLATE = lib
+TARGET = plugin
+DESTDIR = ..
+CONFIG += shared
+
+SOURCES += ../plugin.cpp
+
+macx {
+ QMAKE_LFLAGS_SONAME = -Wl,-install_name,@executable_path/../PlugIns/$${PROVIDER}/
+} else:linux-* {
+ #do the rpath by hand since it's not possible to use ORIGIN in QMAKE_RPATHDIR
+ QMAKE_RPATHDIR += \$\$ORIGIN/..
+ IDE_PLUGIN_RPATH = $$join(QMAKE_RPATHDIR, ":")
+ QMAKE_LFLAGS += -Wl,-z,origin \'-Wl,-rpath,$${IDE_PLUGIN_RPATH}\'
+ QMAKE_RPATHDIR =
+}
+
+