diff --git a/doc/config/qtcreator-project.qdocconf b/doc/config/qtcreator-project.qdocconf index 9eb4f835219..947a500950d 100644 --- a/doc/config/qtcreator-project.qdocconf +++ b/doc/config/qtcreator-project.qdocconf @@ -18,6 +18,7 @@ imagedirs = $SRCDIR/images \ $SRCDIR/../src/plugins/projectexplorer/images \ $SRCDIR/../src/plugins/qmldesigner/components/formeditor \ $SRCDIR/../src/plugins/qmldesigner/components/navigator \ + $SRCDIR/../src/plugins/scxmleditor/common/images \ $SRCDIR/../src/plugins/texteditor/images outputdir = $OUTDIR diff --git a/doc/images/creator-baremetal-device.png b/doc/images/creator-baremetal-device.png index f6f7caebbc2..ade88cc32db 100644 Binary files a/doc/images/creator-baremetal-device.png and b/doc/images/creator-baremetal-device.png differ diff --git a/doc/images/creator-baremetal-kit-for-project.png b/doc/images/creator-baremetal-kit-for-project.png index f7457c05863..2651a755e35 100644 Binary files a/doc/images/creator-baremetal-kit-for-project.png and b/doc/images/creator-baremetal-kit-for-project.png differ diff --git a/doc/images/creator-baremetal-kits.png b/doc/images/creator-baremetal-kits.png index 6df6d43b9fb..161b97096c7 100644 Binary files a/doc/images/creator-baremetal-kits.png and b/doc/images/creator-baremetal-kits.png differ diff --git a/doc/images/qtcreator-ios-add-kit.png b/doc/images/qtcreator-ios-add-kit.png index aecad231f00..fcde8b8c14e 100644 Binary files a/doc/images/qtcreator-ios-add-kit.png and b/doc/images/qtcreator-ios-add-kit.png differ diff --git a/doc/images/qtcreator-options-android1.png b/doc/images/qtcreator-options-android1.png index b4817e32096..1360b49cb61 100644 Binary files a/doc/images/qtcreator-options-android1.png and b/doc/images/qtcreator-options-android1.png differ diff --git a/doc/images/qtcreator-project-kits.png b/doc/images/qtcreator-project-kits.png index 2650290c9cd..bda596db606 100644 Binary files a/doc/images/qtcreator-project-kits.png and b/doc/images/qtcreator-project-kits.png differ diff --git a/doc/images/qtcreator-scxml-editor.png b/doc/images/qtcreator-scxml-editor.png new file mode 100644 index 00000000000..2598cfead8d Binary files /dev/null and b/doc/images/qtcreator-scxml-editor.png differ diff --git a/doc/src/android/androiddev.qdoc b/doc/src/android/androiddev.qdoc index 07a4f62b34d..5f01a32b82b 100644 --- a/doc/src/android/androiddev.qdoc +++ b/doc/src/android/androiddev.qdoc @@ -137,8 +137,8 @@ \list 1 - \li Select \uicontrol Tools > \uicontrol Options > \uicontrol Android to add paths to the - Android NDK and SDK. + \li Select \uicontrol Tools > \uicontrol Options > \uicontrol Devices > + \uicontrol Android to add paths to the Android NDK and SDK. You can use the \inlineimage download.png (\uicontrol Download) buttons to go to the sites where you can download @@ -219,7 +219,8 @@ \section1 Using the Android Emulator To run your application on the Android Emulator, you must create Android - virtual devices (AVD). Select \uicontrol Tools > \uicontrol Options > \uicontrol Android > + virtual devices (AVD). Select \uicontrol Tools > \uicontrol Options > + \uicontrol Devices > \uicontrol Android > \uicontrol Add. If you run an application without a device connected to the development PC and without an AVD specified, \QC asks you to add an AVD. diff --git a/doc/src/baremetal/creator-baremetal-dev.qdoc b/doc/src/baremetal/creator-baremetal-dev.qdoc index 895cf2ad956..4ee8d3b9eea 100644 --- a/doc/src/baremetal/creator-baremetal-dev.qdoc +++ b/doc/src/baremetal/creator-baremetal-dev.qdoc @@ -51,7 +51,7 @@ \li Restart \QC to be able to use the plugin. - \li Select \uicontrol Tools > \uicontrol Options > + \li Select \uicontrol Tools > \uicontrol Options > \uicontrol Devices > \uicontrol {Bare Metal} > \uicontrol Add > \uicontrol Default, \uicontrol OpenCD, or \uicontrol {ST-LINK Utility} to specify connections to GDB servers or hardware debuggers: @@ -113,10 +113,9 @@ \li Open a project for an application you want to develop for the device. - \li Select \uicontrol Projects > \uicontrol {Build & Run} > - \uicontrol {Add Kit}, and then select the kit for building and - running the application on the bare metal device specified in the - kit. + \li Select \uicontrol Projects > \uicontrol {Build & Run}, and then + select the kit for building and running the application on the bare + metal device specified in the kit. \image creator-baremetal-kit-for-project.png "Adding a bare metal kit for a project" diff --git a/doc/src/debugger/creator-debugger.qdoc b/doc/src/debugger/creator-debugger.qdoc index 606405a35eb..ec6571f64f9 100644 --- a/doc/src/debugger/creator-debugger.qdoc +++ b/doc/src/debugger/creator-debugger.qdoc @@ -902,100 +902,125 @@ structures, but it does usually not give enough insight into more complex structures, such as \c QObjects or associative containers. These items are internally represented by a complex arrangement of pointers, often highly - optimized, with part of the data not directly accessible through either - sub-structures or pointers. - - To give the user simple access also to these items, \QC employs so-called - \e{debugging helpers}. Debugging helpers come in two varieties, a compiled - one, for use with the CDB backend, and a set of Python scripts for use with - the GDB and LLDB backends. + optimized, with part of the data not directly accessible through neither + sub-structures nor pointers. + To give the user simple access also to these items, \QC employs Python + scripts that are called \e {debugging helpers}. Debugging helpers are always automatically used. To force a plain C-like display of structures, select \uicontrol Tools > \uicontrol Options > \uicontrol Debugger > \uicontrol {Locals & Expressions}, and then deselect - the \uicontrol {Use Debugging Helper} check box. For GDB and LLDB this will - still use the Python scripts, but generate more basic output. To force plain - display for a single object or for all objects of a given type, select the + the \uicontrol {Use Debugging Helper} check box. This will still use the + Python scripts, but generate more basic output. To force the plain display + for a single object or for all objects of a given type, select the corresponding option from the context menu. - \QC ships with debugging helpers for more than 130 of the most popular Qt - classes, Standard C++ containers and smart pointers, covering the usual + \QC ships with debugging helpers for more than 200 of the most popular Qt + classes, standard C++ containers, and smart pointers, covering the usual needs of a C++ application developer out-of-the-box. - \section1 Extending GDB and LLDB Debugging Helpers + \section1 Extending Debugging Helpers - When using either GDB or LLDB as the debugging backend, \QC uses Python - scripts to display information in the \uicontrol {Locals and Expressions} + \QC uses Python scripts to translate raw memory contents and type information + data from native debugger backends (GDB, LLDB, and CDB are currently supported) + into the form presented to the user in the \uicontrol {Locals and Expressions} view. - You can easily extend these scripts to cover your own types, using the same - code for both the GDB and the LLDB backend. No compilation is required, just - adding a few lines of Python. The scripts can address multiple versions of - Qt, or of your own library, at the same time. + Unlike GDB's + \l{https://sourceware.org/gdb/onlinedocs/gdb/Pretty-Printing.html#Pretty-Printing} + {pretty printers} and LLDB's \l{http://lldb.llvm.org/varformats.html} + {data formatters}, Qt Creator's debugging helpers are independent of the + native debugging backend. That is, the same code can be used with GDB on + Linux, LLDB on macOS, and CDB on Windows, or any other platform on which at + least one of the three supported backends is available. - To extend the shipped Python based debugging helpers for custom types, add - debugging helper implementations to the GDB startup file \c{~/.gdbinit}, or - specify them directly in the \uicontrol {Additional Startup Commands} in - \uicontrol Tools > \uicontrol Options > \uicontrol Debugger > - \uicontrol GDB. + To add debugging helpers for your own types, no compilation is required, + just adding a few lines of Python. The scripts can address multiple versions + of Qt, or of your own library, at the same time. + + To add debugging helpers for custom types, add debugging helper + implementations to the startup file of the native debuggers (for example, + \c{~/.gdbinit} or \c{~/.lldbinit}) or specify them directly in the + \uicontrol {Additional Startup Commands} in \uicontrol Tools > + \uicontrol Options > \uicontrol Debugger > \uicontrol GDB. + + \section2 Debugging Helper Overview The implementation of a debugging helper typically consists of a single Python function, which needs to be named \c{qdump__NS__Foo}, where \c{NS::Foo} is the class or class template to be examined. Note that the - \c{::} scope resolution operator is replaced by double underscores \c{__}. + \c{::} scope resolution operator is replaced by double underscores: \c{__}. Nested namespaces are possible. - The debugger plugin calls this function whenever you want to display an + \QC's debugger plugin calls this function whenever you want to display an object of this type. The function is passed the following parameters: \list - \li \c d of type \c Dumper, an object containing current settings and - providing facilities to build up an object representing part of the - Locals and Expressions view, + \li \c d of type \c Dumper, an object containing the current settings and + providing facilities to build up an object representing a part of + the \uicontrol {Locals and Expressions} view. - \li \c value of type \c Value, wrapping either a - \l{https://sourceware.org/gdb/onlinedocs/gdb/Values-From-Inferior.html}{gdb.Value} - or an - \l{http://lldb.llvm.org/cpp_reference/html/classlldb_1_1SBValue.html}{lldb.SBValue}. + \li \c value of type \c Value, wrapping either a + \l{https://sourceware.org/gdb/onlinedocs/gdb/Values-From-Inferior.html} + {gdb.Value} or an + \l{http://lldb.llvm.org/cpp_reference/html/classlldb_1_1SBValue.html} + {lldb.SBValue}. \endlist The \c{qdump__*} function has to feed the Dumper object with certain - information which is used to build up the object and its children's display + information that is used to build up the object and its children's display in the \uicontrol {Locals and Expressions} view. Example: \code def qdump__QFiniteStack(d, value): - alloc = int(value["_alloc"]) - size = int(value["_size"]) + alloc = value["_alloc"].integer() + size = value["_size"].integer() d.putItemCount(size) - d.putNumChild(size) if d.isExpanded(): - innerType = d.templateArgument(value.type, 0) - d.putArrayData(innerType, value["_array"], size) + d.putArrayData(value.type[0], value["_array"], size) \endcode \note To create dumper functions usable with both LLDB and GDB backends, - avoid direct access to the \c gdb.* and \c lldb.* namespaces and use + avoid direct access to the \c gdb.* and \c lldb.* namespaces and use the functions of the \c Dumper class instead. - \section2 Dumper Class + Debugging helpers can be set up to be called whenever a type name matches + a regular expression. To do so, the debugging helper's function name must + begin with \c{qdump__} (with two underscore characters). In addition, + the function needs to have a third parameter called \c regex with a default + value that specifies the regular expression that the type name should match. + + For example, the Nim 0.12 compiler assigns artificial names, such as \c{TY1} + and \c{TY2}, to all generic sequences it compiles. To visualize these in + \QC, the following debugging helper may be used: + + \code + def qdump__NimGenericSequence__(d, value, regex = "^TY.*$"): + size = value["Sup"]["len"] + base = value["data"].dereference() + typeobj = base.dereference().type + d.putArrayData(base, size, typeobj) + \endcode + + \section2 Debugging Helper Implementation + + A debugging helper creates a description of the displayed data item + in a format that is similar to GDB/MI and JSON. For each line in the \uicontrol {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 + { iname='some internal name', # optional + address='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', }, @@ -1006,99 +1031,42 @@ \endcode The value of the \c iname field is the internal name of the object, - constituting a dot-separated list of identifiers, corresponding to the + which consists of 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 + it is generated by concatenating the parent object's \c iname, a dot, and a sequential number. The value of the \c name field is displayed in the \uicontrol 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 functions to handle + As the format is not guaranteed to be stable, it is strongly recommended + not to generate the wire format directly, but to use the abstraction + layer provided by the Python Dumper classes, specifically the \c{Dumper} + class itself, and the \c{Dumper:Value} and \c{Dumper:Type} abstractions. + + These provide a complete framework to take care of the \c iname and \c addr + fields, to handle children of simple types, references, pointers, enums, and + known and unknown structs, as well as some convenience functions to handle common situations. + \section3 Dumper Class + + The \c Dumper class contains generic bookkeeping, low-level, and convenience + functions. + The member functions of the \c Dumper class are the following: \list - - \li \c{__init__(self)} - Initializes the output to an empty string and - empties the child stack. This should not be used in user code. - - \li \c{put(self, value)} - Low level function to directly append to the - output string. That is also the fastest way to append output. - - \li \c{putField(self, name, value)} - Appends a \c{name='value'} field. - - \li \c{childRange(self)} - Returns the range of children specified in - the current \c Children scope. - - \li \c{putItemCount(self, count)} - Appends a field - \c {value='<%d items'} to the output. - - \li \c{putName(self, name)} - Appends a \c {name=''} field. - - \li \c{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. - - \li \c{putBetterType(self, type)} - Overrides the last recorded - \c type. - - \li \c{putNumChild(self, numchild)} - Appends a field \c {numchild=''} - unless the \c numchild coincides with the parent's default child - numchild value. - - \li \c{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 - - \li 0: unencoded 8 bit data, interpreted as Latin1. - - \li 1: base64 encoded 8 bit data, used for QByteArray, double quotes - are added. - - \li 2: base64 encoded 16 bit data, used for QString, double quotes - are added. - - \li 3: base64 encoded 32 bit data, double quotes are added. - - \li 4: base64 encoded 16 bit data, without quotes (see 2) - - \li 5: base64 encoded 8 bit data, without quotes (see 1) - - \li 6: %02x encoded 8 bit data (as with \c QByteArray::toHex), - double quotes are added. - - \li 7: %04x encoded 16 bit data (as with \c QByteArray::toHex), - double quotes are added. - \endlist - - \li \c{putStringValue(self, value)} - Encodes a QString and calls - \c putValue with the correct \c encoding setting. - - \li \c{putByteArrayValue(self, value)} - Encodes a QByteArray and calls - \c putValue with the correct \c encoding setting. - - \li \c{isExpanded()} - Checks whether the current item is expanded in - the view. + \li \c{putItem(self, value)} - The \e {master function} that handles + basic types, references, pointers, and enums directly, iterates over + base classes and class members of compound types, and calls + \c qdump__* functions when appropriate. \li \c{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 @@ -1111,21 +1079,32 @@ self.putNumChild(0) \endcode - \li \c{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. Use \c{putCallItem} only if there is no other - way to access the data. Calls cannot be executed when inspecting a - core file, they are expensive to execute and have the potential to - change the state of the debugged program. + \li \c{putCallItem(self, name, value, func, *args)} - Uses the native + debugger backend to place the function call \c func on the value + specified by \a {value} and output the resulting item. - \li \c{putArrayData(self, type, address, size)} - Creates \c size - children of type \c type of an array-like object located at - \c address. + Native calls are extremely powerful and can leverage existing + debugging or logging facilities in the debugged process, for + example. However, they should only be used in a controlled + environment, and only if there is no other way to access the data, + for the following reasons: - \li \c{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. + \list + + \li Direct execution of code is dangerous. It runs native code + with the privileges of the debugged process, with the + potential to not only corrupt the debugged process, but also + to access the disk and network. + + \li Calls cannot be executed when inspecting a core file. + + \li Calls are expensive to set up and execute in the debugger. + + \endlist + + \li \c{putArrayData(self, type, address, itemCount)} - Creates the + number of children specified by \c itemCount of the type \c type of + an array-like object located at \c address. \li \c{putSubItem(self, component, value)} - Equivalent to: \code @@ -1141,9 +1120,247 @@ d.put('value="",type="",numchild="0",') \endcode + \li \c{put(self, value)} - A low-level function to directly append to + the output string. That is also the fastest way to append output. + + \li \c{putField(self, name, value)} - Appends a \c{name='value'} field. + + \li \c{childRange(self)} - Returns the range of children specified in + the current \c Children scope. + + \li \c{putItemCount(self, count)} - Appends the field + \c {value='<%d items>'} to the output. + + \li \c{putName(self, name)} - Appends the \c {name=''} field. + + \li \c{putType(self, type, priority=0)} - Appends the 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. + + \li \c{putBetterType(self, type)} - Overrides the last recorded \c type. + + \li \c{putNumChild(self, numchild)} - Announces the existence + (\c numchild > 0) or non-existence of child items for the current + value. If \c putNumChild is not explicitly called, the + existence of child items is implied. + + \li \c{putValue(self, value, encoding = None)} - Appends the file + \c {value=''}, optionally followed by the 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. The parameter + \c{encoding} is either a string of the form \c codec:itemsize:quote + where \c{codec} is any of \c{latin1}, \c{utf8}, \c{utf16}, \c{ucs4}, + \c{int}, or \c{float}. \c{itemsize} gives the size of the basic + component of the object if it is not implied by \c codec and + \c quote specifies whether or not the value should be surrounded by + quotes in the display. + + Example: + + \code + # Safe transport of quirky data. Put quotes around the result. + d.putValue(d.hexencode("ABC\"DEF"), "utf8:1:1") + \endcode + + \li \c{putStringValue(self, value)} - Encodes a QString and calls + \c putValue with the correct \c encoding setting. + + \li \c{putByteArrayValue(self, value)} - Encodes a QByteArray and calls + \c putValue with the correct \c encoding setting. + + \li \c{isExpanded(self)} - Checks whether the current item is expanded in + the view. + + \li \c{createType(self, pattern, size = None)} - Creates a \c{Dumper.Type} + object. The exact operation depends on \c pattern. + + \list + + \li If \c pattern matches the name of a well-known type, a + \c{Dumper.Type} object describing this type is returned. + + \li If \c pattern is the name of a type known to the native backend, + the returned type describes the native type. + + \li Otherwise, \c pattern is used to construct a type description by + interpreting a sequence of items describing the field of a + structure as follows. Field descriptions consist of one or + more characters as follows: + + \list + + \li \c q - Signed 8-byte integral value + \li \c Q - Unsigned 8-byte integral value + \li \c i - Signed 4-byte integral value + \li \c I - Unsigned 4-byte integral value + \li \c h - Signed 2-byte integral value + \li \c H - Unsigned 2-byte integral value + \li \c b - Signed 1-byte integral value + \li \c B - Unsigned 1-byte integral value + \li \c d - 8-byte IEEE 754 floating point value + \li \c f - 4-byte IEEE 754 floating point value + \li \c p - A pointer, that is, an unsigned integral value of + suitable size according to the target architecture + \li \c @ - Suitable padding. The size is determined by the + preceding and following field and the target architecture + \li \c s - A blob of bytes, with implied alignment of 1 + \li \c {} - A blob of suitable size and suitable + alignment determined by a \c{Dumper.Type} with the name + \c typename + + \endlist + + \endlist + \endlist - \section2 Children and SubItem Class + \section3 Dumper.Type Class + + The \c{Dumper.Type} class describes the type of a piece of data, typically + a C++ class or struct, a pointer to a struct, or a primitive type, such as + an integral or floating point type. + + Type objects, that is, instances of the \c{Dumper.Type} class, can be + created by native debugger backends, usually by evaluating Debug Information + built into or shipped alongside the debugged binary, or created on-the-fly + by the debugging helper. + + \QC uses the possibility to provide type information on-the-fly for most Qt + classes, obliterating the need to use \e Debug builds of Qt for the purpose + of object introspection. + + The member functions of the \c{Dumper.Type} class are the following: + + \list + + \li \c{name} - The name of this type as a string, or \c None if the type + is anonymous. + + \li \c{size(self)} - Returns the size of an object of this type in + bytes. + + \li \c{bitsize(self)} - Returns the size of an object of this type in + bits. + + \li \c{(alignment(self)} - Returns the required alignment for objects of + this type in bytes. + + \li \c{deference(self)} - Returns the dereferences type for pointer + type, \c None otherwise. + + \li \c{pointer(self)} - Returns a pointer type that can be dereferenced + to this type. + + \li \c{target(self)} - A convenience function that returns the item type + for array types and the dereferenced type for pointers and + references. + + \li \c{stripTypedefs(self)} - Returns the underlying type if this type + is an alias. + + \li \c{templateArgument(self, position, numeric = False)} - Returns the + template parameter located at \c{position} if this is a templated + type. If \c numeric is \c True, returns the parameter as an integral + value. + + \li \c{fields(self)} - Returns a list of \c{Dumper:Fields} describing + the base classes and data members of this type. + + \endlist + + + \section3 Dumper.Field Class + + The \c{Dumper.Field} class describes a base class or a data member of a type + object. + + The member function and properties of the \c{Dumper.Field} class are the + following: + + \list + + \li \c{isBaseClass} - Distinguishes between base classes and data + members. + + \li \c{fieldType(self)} - Returns the type of this base class or data + member. + + \li \c{parentType(self)} - Returns the owning type. + + \li \c{bitsize(self)} - Returns the size of this field in bits. + + \li \c{bitpos(self)} - Returns the offset of this field in the owning + type in bits. + + \endlist + + + \section3 Dumper.Value Class + + The \c{Dumper.Value} class describes a piece of data, such as instances of + C++ classes or primitive data types. It can also be used to describe + artificial items that have no direct representation in memory, such as + file contents, non-contiguous objects, or collections. + + A \c{Dumper.Value} has always an associated \c{Dumper.Type}. The two + main representations of the value's actual data are: + + \list + + \li Python object following the Python buffer protocol, such as a Python + \c memoryview, or a \c bytes object. The \c size() should match the + size of this value's type. + + \li An integral value representing a pointer to the begin of the object + in the current address space. The size of the object is given by its + type's \c{size()}. + + \endlist + + Knowledge of the internal representation of a \c{Dumper.Value} is typically + not required when creating a debugger helper for it. + + The member function and properties of the \c{Dumper.Value} class are the + following: + + \list + + \li \c{integer(self)} - Returns an interpretation of this value as a + signed integral value of a suitable size. + + \li \c{pointer(self)} - Returns an interpretation of this value as a + pointer in the current address space. + + \li \c{members(self)} - Returns a list of \c{Dumper.Value} objects + representing the base objects and data members of this value. + + \li \c{dereference(self)} - For values describing pointers, returns the + dereferenced value, and \c None otherwise. + + \li \c{cast(self, type)} - Returns a value that has the same data as + this value, but the type \c type. + + \li \c{address(self)} - Returns the address of this value if it consists + of a contiguous region in the current address space, and \c None + otherwise. + + \li \c{data(self)} - Returns the data of this value as a Python \c bytes + object. + + \li \c{split(self, pattern)} - Returns a list of values created + according to \c pattern from this value's data. Acceptable patterns + are the same as for \c{Dumper.createType}. + + \li \c{dynamicTypeName(self)} - Tries to retrieve the name of the + dynamic type of this value if this is a base class object. Returns + \c None if that is not possible. + + \endlist + + \section3 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 @@ -1164,7 +1381,6 @@ Example: \code - d.putNumChild(2) # Annouce children to make the item expandable in the view. if d.isExpanded(): with Children(d): with SubItem(d): diff --git a/doc/src/editors/creator-coding.qdoc b/doc/src/editors/creator-coding.qdoc index 4d518aa78e8..73ca7751cea 100644 --- a/doc/src/editors/creator-coding.qdoc +++ b/doc/src/editors/creator-coding.qdoc @@ -92,6 +92,15 @@ Modeling Language (UML) style models with structured diagrams and store them in XML format. + \li \l{Editing State Charts} + + You can use \QC to create applications that embed state machines. A + project wizard creates \l{https://www.w3.org/TR/scxml/} + {State Chart XML (SCXML)} files with boilerplate code that you can + edit using an experimental SCXML editor. You can use the classes in + the Qt SCXML module to embed state machines created from the files + in Qt applications. + \endlist */ diff --git a/doc/src/editors/creator-modeling.qdoc b/doc/src/editors/creator-modeling.qdoc index 6ae6696afa9..fedb7d703a2 100644 --- a/doc/src/editors/creator-modeling.qdoc +++ b/doc/src/editors/creator-modeling.qdoc @@ -33,7 +33,7 @@ \contentspage {Qt Creator Manual} \previouspage creator-mime-types.html \page creator-modeling.html - \nextpage creator-building-running.html + \nextpage creator-scxml.html \title Modeling diff --git a/doc/src/editors/creator-scxml.qdoc b/doc/src/editors/creator-scxml.qdoc new file mode 100644 index 00000000000..384f8c0abab --- /dev/null +++ b/doc/src/editors/creator-scxml.qdoc @@ -0,0 +1,297 @@ +/**************************************************************************** +** +** Copyright (C) 2016 The Qt Company Ltd. +** Contact: https://www.qt.io/licensing/ +** +** This file is part of the Qt Creator documentation. +** +** $QT_BEGIN_LICENSE:LGPL$ +** Commercial License Usage +** Licensees holding valid commercial Qt licenses may use this file in +** accordance with the commercial license agreement provided with the +** Software or, alternatively, in accordance with the terms contained in +** a written agreement between you and The Qt Company. For licensing terms +** and conditions see https://www.qt.io/terms-conditions. For further +** information use the contact form at https://www.qt.io/contact-us. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 3 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL3 included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 3 requirements +** will be met: https://www.gnu.org/licenses/lgpl-3.0.html. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 2.0 or (at your option) the GNU General +** Public license version 3 or any later version approved by the KDE Free +** Qt Foundation. The licenses are as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL2 and LICENSE.GPL3 +** included in the packaging of this file. Please review the following +** information to ensure the GNU General Public License requirements will +** be met: https://www.gnu.org/licenses/gpl-2.0.html and +** https://www.gnu.org/licenses/gpl-3.0.html. +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +// ********************************************************************** +// 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 {Qt Creator Manual} + \previouspage creator-modeling.html + \page creator-scxml.html + \nextpage creator-building-running.html + + \title Editing State Charts + + State charts provide a graphical way of modeling how a system reacts to + stimuli. This is done by defining the possible \e states that the system can + be in, and how the system can move from one state to another (\e transitions + between states). A key characteristic of event-driven systems (such as Qt + applications) is that behavior often depends not only on the last or current + \e event, but also the events that preceded it. With state charts, this + information is easy to express. + + \QC provides a project wizard for adding \l{https://www.w3.org/TR/scxml/} + {State Chart XML (SCXML)} files with boilerplate code to projects and an + experimental SCXML editor for editing the state charts. You can use the + SCXML editor to add \e states and \e transitions to the files. You can then + use the classes in the Qt SCXML module to embed the state machines created + from the files in Qt applications. + + \image qtcreator-scxml-editor.png SXCML Editor + + You can drag and drop states from the \uicontrol {Common States} view (1) to + the state editor (2). Select a state in the state editor and use the tool + buttons (3) to create a transition (4) and its \e {target state}. + + You can view the state chart structure in the \uicontrol Structure view (5) + and specify attributes for the selected state or transition in the + \uicontrol Attributes view (6). + + You can use the toolbar buttons (7) to execute functions such as editing, + zooming, magnifying, navigating, and panning state charts, as well as + taking screenshots and viewing statistics. + + To zoom into and out of the whole state chart in the state editor, select + \inlineimage icon-zoom-in.png + (\uicontrol {Zoom In}) or \inlineimage icon-zoom-out.png + (\uicontrol {Zoom Out}) or press \key Ctrl and use the mouse wheel. To make + the whole state chart visible in the state editor at a time, select + \inlineimage icon-fit-screen.png + (\uicontrol {Fit to View}). + + To view a particular part of a large state chart in the state editor, select + \inlineimage navigator.png + (\uicontrol {Navigator}) and move the navigator frame on the part you want + to view. + + To use the magnifier to zoom into a part of the state chart, select + \inlineimage zoom.png + (\uicontrol Magnifier). To move the magnifier faster, press down the + \key Alt key. + + To pan the state chart, select \inlineimage icon-pan.png + (\uicontrol Panning). To increase the pace of panning, press down the + \key Shift key. + + To view statistics about the numbers of states and transitions in the state + chart, select \inlineimage statistics.png + (\uicontrol {View Statistics}). + + To search from the state chart, use the \uicontrol Search pane. The search + checks the whole SCXML tree for attributes that match the search criteria. + + To save the currently visible part of the state chart as an image, select + \inlineimage screenshot.png + (\uicontrol {Save Screenshot}). To save the whole state chart as an image, + select \inlineimage icon-export-canvas.png + (\uicontrol {Export Canvas to Image}). + + \section1 Creating State Charts + + To create a state chart: + + \list 1 + + \li Select \uicontrol Help > \uicontrol {About Plugins} > + \uicontrol Modeling > \uicontrol ScxmlEditor and restart \QC to + enable the plugin. + + \li Select \uicontrol File > \uicontrol {New File or Project} > + \uicontrol {Files and Classes} > \uicontrol Modeling > + \uicontrol {State Chart} > \uicontrol Choose to create an empty + state chart and to open it in the SCXML editor. + + \li Drag and drop a state from the \uicontrol {Common States} view to + the state editor. + + \li Drag and drop child states to the initial state to create a + \e {compound state} or use the tool buttons to create a transition + from the selected state and its target state. + + \li Select a state to edit its attributes in the \uicontrol Attributes + view. + + \li Select the transition line to add edge points to it. + + \li To raise or send events, for example, use the context menu commands + to add executable content to the \c and \c + elements of states or to transitions. + + \endlist + + The following sections describe how to manage states, transitions, and + executable content. + + \section1 Managing States + + When the state machine enters a state in response to an event, the state + that it entered becomes the \e {active state}. + + State charts are hierarchical, and therefore states can be nested inside + other states, to create compound states. + + In addition to basic states, you can create the following types of states: + + \list + + \li \e Initial state is the state the state machine enters when it + starts. + + \li \e {Parallel state} contains child states that execute in parallel + and are all active simultaneously. Events are processed + independently by each child state and may trigger different + transitions for each child. + + \li \e {Final state} enables a state machine to finish. When the state + machine enters a top-level final state, it emits the finished signal + and halts. You can create final states in compound states to hide + the internal details of a compound state. The outside world can only + enter the state and get a notification when the state has finished. + A parallel state finishes when all its child states reach final + states. + + \li \e {History state} is a pseudo-state that represents the child state + the parent state was in the last time the parent state was exited. + + Create a history state as a child of the state for which you want to + record the current child state. When the state machine detects the + presence of such a state at runtime, it automatically records the + current (real) child state when the parent state is exited. A + transition to the history state is in fact a transition to the child + state that the state machine previously saved. The state machine + automatically forwards the transition to the real child state. + + \endlist + + You can add new states to the state chart in the following ways: + + \list + + \li Drag and drop states from the \uicontrol {Common States} view to the + state editor. + + \li Select a state in the state editor, and then select the + \uicontrol State tool button to create a transition and its target + state. + + \li Copy and paste states within the SCXML editor or between the SCXML + editor and the \uicontrol Edit mode. + + \endlist + + You can drag states on top of other states to create compound states, or + you can drag child states out of their parent state. To move child states + within their parent, press down the \key Ctrl key while moving them. + + You can use toolbar buttons to align states in the state editor, to adjust + their size, and to change the default color scheme. Overlapping states are + marked in red color. + + To expand or collapse the state tree structure in the \uicontrol Structure + view, double-click a state. + + To view a child state of a nested state in more detail in the state editor, + select \uicontrol {Zoom to State}. + + To ensure that the state ids are unique within a compound state machine, + select \inlineimage fullnamespace.png + (\uicontrol {Toggle Full Namespace}). The name of the parent state is + added to the names of the child states, separated by two colons (::). + For example: + + \badcode + + ... + + ... + + + ... + + + \endcode + + \section1 Managing Transitions + + Transitions define how a state reacts to \e events that are generated either + by the state machine or external entities. When events occur, the state + machine checks for a matching transition defined in the active state and + moves to its target state. + + To create a transition from the selected state to a new state, drag and + release the mouse at the location where you want to add the target state. + When you draw a transition to the center of another state, it points to the + center of the state, but you can also draw a transition to the edge of the + state. + + To add edge points to transitions, select a transition line. Only two edge + points are permitted for each line, and unnecessary edge points are removed + automatically. To remove the selected edge point, select + \uicontrol {Remove Point} in the context menu. + + To add new edge points with a mouse click, select the \uicontrol Transition + tool button. + + A transition label is automatically center-aligned, but you can drag it to + another position. + + To remove the selected transition, select \uicontrol Remove in the context + menu. + + \section1 Adding Executable Content + + You can add \e {executable content} to a state chart to enable the state + machine to modify its data model and to interact with external entities. + + Use the context menu commands to add executable content to the \c + and \c elements or to transitions: + + \list + \li \c to raise events + \li \c to communicate with external entities + \li \c