diff options
-rw-r--r-- | doc/classic.css | 199 | ||||
-rw-r--r-- | doc/scxml.qdoc | 208 | ||||
-rw-r--r-- | doc/scxml.qdocconf | 192 | ||||
-rw-r--r-- | src/qscxml.cpp | 22 |
4 files changed, 614 insertions, 7 deletions
diff --git a/doc/classic.css b/doc/classic.css new file mode 100644 index 0000000..3704a15 --- /dev/null +++ b/doc/classic.css @@ -0,0 +1,199 @@ +BODY,H1,H2,H3,H4,H5,H6,P,CENTER,TD,TH,UL,DL,DIV { + font-family: Geneva, Arial, Helvetica, sans-serif; +} +BODY,TD { + font-size: 90%; +} +H1 { + text-align: center; + font-size: 160%; +} +H2 { + font-size: 120%; +} +H3 { + font-size: 100%; +} + +h3.fn,span.fn +{ + background-color: #d5e1e8; + border-width: 1px; + border-style: solid; + border-color: #84b0c7; + font-weight: bold; + -moz-border-radius: 8px 8px 8px 8px; + padding: 6px 0px 6px 10px; +} + +a:link +{ + color: #004faf; + text-decoration: none +} + +a:visited +{ + color: #672967; + text-decoration: none +} + +a.obsolete +{ + color: #661100; + text-decoration: none +} + +a.compat +{ + color: #661100; + text-decoration: none +} + +a.obsolete:visited +{ + color: #995500; + text-decoration: none +} + +a.compat:visited +{ + color: #995500; + text-decoration: none +} + +td.postheader +{ + font-family: sans-serif +} + +tr.address +{ + font-family: sans-serif +} + +body +{ + background: #ffffff; + color: black +} + +table td.memItemLeft { + width: 200px; + padding: 1px 0px 0px 8px; + margin: 4px; + border-top-width: 1px; + border-right-width: 1px; + border-bottom-width: 1px; + border-left-width: 1px; + border-top-color: #E0E0E0; + border-right-color: #E0E0E0; + border-bottom-color: #E0E0E0; + border-left-color: #E0E0E0; + border-top-style: solid; + border-right-style: none; + border-bottom-style: none; + border-left-style: none; + background-color: #FAFAFA; + font-size: 80%; +} +table td.memItemRight { + padding: 1px 8px 0px 8px; + margin: 4px; + border-top-width: 1px; + border-right-width: 1px; + border-bottom-width: 1px; + border-left-width: 1px; + border-top-color: #E0E0E0; + border-right-color: #E0E0E0; + border-bottom-color: #E0E0E0; + border-left-color: #E0E0E0; + border-top-style: solid; + border-right-style: none; + border-bottom-style: none; + border-left-style: none; + background-color: #FAFAFA; + font-size: 80%; +} + +table tr.odd { + background: #f0f0f0; + color: black; +} + +table tr.even { + background: #e4e4e4; + color: black; +} + +table.annotated th { + padding: 3px; + text-align: left +} + +table.annotated td { + padding: 3px; +} + +table tr pre +{ + padding-top: none; + padding-bottom: none; + padding-left: none; + padding-right: none; + border: none; + background: none +} + +tr.qt-style +{ + background: #96E066; + color: black +} + +body pre +{ + padding: 0.2em; + border: #e7e7e7 1px solid; + background: #f1f1f1; + color: black +} + +table tr.qt-code pre +{ + padding: 0.2em; + border: #e7e7e7 1px solid; + background: #f1f1f1; + color: black +} + +span.preprocessor, span.preprocessor a +{ + color: darkblue; +} + +span.comment +{ + color: darkred; + font-style: italic +} + +span.string,span.char +{ + color: darkgreen; +} + +.title +{ + text-align: center +} + +.subtitle +{ + font-size: 0.8em +} + +.small-subtitle +{ + font-size: 0.65em +} diff --git a/doc/scxml.qdoc b/doc/scxml.qdoc new file mode 100644 index 0000000..d0211ba --- /dev/null +++ b/doc/scxml.qdoc @@ -0,0 +1,208 @@ +/*! + \page scxml.html + \title Using SCXML files in Qt + \ingroup sctools + \brief An overview of the sctools module, which allows loading scripted state charts with SCXML + + \tableofcontents + + The sctools module allows loading SCXML files into a QtScriptedStateMachine object. + + The files that the tool can load conform to the \l{State Chart XML: State Machine Notation for Control Abstraction}{State Chart XML (SCXML)} standard. + + \section1 Getting Started with Qt & SCXML + \list + \i First of all, make yourself familiar with the \l{State Chart XML: State Machine Notation for Control Abstraction}{SCXML specification}. + \i Read this document to understand how to enable SCXML files in your project, and how to load SCXML files in runtime/build-time. + \i Go over the blackjack, calc and mediaplayer examples for usage demonstration. + \endlist + + \section1 Enabling the QtScriptedStateMachine class + + The \l QtScriptedStateMachine class is enabled automatically when the script module is enabled. + + \section1 Using the QtScriptedStateMachine class + + QtScriptedStateMachine is a subclass of QtStateMachine. QtStateMachine actually includes most of the + "interesting" API, while QtScriptedStateMachine adds the missing parts to support SCXML. + + Most of the interaction with QtScriptedStateMachine occurs after the state-machine is loaded, + and before it's started. + The interesting functionalities of QtScriptedStateMachine are: + \section2 Working with the script engine + + The main feature of \l QtScriptedStateMachine is that it includes a single \a QScriptEngine object that's + shared between all state actions and transitions. That's what allows the states to rely on a single + data context for evaluating conditions and executing the entry/exit/transition actions. + + A very useful function is \l QtScriptedStateMachine::registerObject(), which allows you to add an object + (and optionally all its descendants) to the scripting context. + \l QtScriptedStateMachine::scriptEngine() allows you to manipulate the scripting context directly. + Use the mediaplayer example as a reference for using the registerObject function. + + + \section2 Connecting the state-machine to signals/slots + + A simpler way to interact with the state machine is through signals and slots. + The slot \l QtScriptedStateMachine::postNamedEvent() and the signal \l QtScriptedStateMachine::eventTriggered() + allow for a simple interaction with the state machine, as you can connect signals to postNamedEvent + and eventTriggered to and signal/slot. + + There are no entered/exited signals from states, as that would make the state-machines less deterministic + and would create results that are difficult to manage and predict (does the signal get emitted before, + after or during the normal execution list?) + + The calc example shows the usage of \l QtScriptedStateMachine::postNamedEvent(). + + \section2 Extending the state-machine with custom invokers + + A custom invoker allows you to write your own \l{http://www.w3.org/TR/scxml/#Invoke}{invoke} tags, and implement specific invoke types, + as described in the SCXML standard. + + To create a custom invoker, you must subclass from \l QtSsmInvoker, and implement at least: + \list + \i A constructor with \l QtScriptedEvent and \l QtStateMachine arguments + \i The \l QtSsmInvoker::activate() function + \i A static bool isTypeSupportedString(QString) function, conforms to the \l {http://www.w3.org/TR/scxml/#Invoke}{invoke} element's type attribute + \i A static void initInvokerFactory(QtScriptedStateMachine*) function, allows some initialization (like adding properties to the script engine) + \endlist + + + When these terms are met, you can create an invoke-factory, and register it to the state machine. + Example: + \code + #include <QtScriptedStateMachine> + + class MyInvoker : public QtSsmInvoker + { + Q_OBJECT + public: + MyInvoker(QtScriptedEvent* ievent, QtScriptedStateMachine* p) : QtSsmInvoker(ievent,p),menu(0) + { + } + static void initInvokerFactory(QtScriptedStateMachine* machine) + { + machine->scriptEngine()->globalObject().setProperty("some-name",someValue); + } + static bool isTypeSupported (const QString & s) { return s== "my-type"; } + public Q_SLOTS: + void activate () + { + doSomeStuff (); + } + }; + ... + static QSsmAutoInvokerFactory<MyInvoker> _s_factory; + myScriptedStateMachine->registerInvoker(&_s_factory); + + \endcode + + The initEvent protected member can be used to access the parameters + given to the invoker by the calling state machine. \l QtSsmInvoker::postParentEvent() + allows sending events back to the calling state machine. + + + + + + \section1 Loading SCXML files at runtime + + To load SCXML files in runtime, the static function \l QtScriptedStateMachine::load() must be used. + Note that this function requires the xmlpatterns and xml modules to be enabled. + \l QtScriptedStateMachine::load() it creates a new \l QtScriptedStateMachine object. + An example code would be: + +\code + #include "qscriptedstatemachine.h" + + // some code + QtScriptedStateMachine* stateMachine = QtScriptedStateMachine::load ("path-to-some-file.scxml"); + // ... register some objects, handle some stuff in the script engine... + stateMachine->start (); +\endcode + + + \section1 Supported SCXML tags and features + +Though most of the SCXML features are supported in this implementation, the support is incomplete, +partially because the spec itself is still evolving. This documentation tries to capture most of the +gaps and differences. + + \section2 Fully supported elements + The tags \l {http://www.w3.org/TR/scxml/#state}{state}, \l {http://www.w3.org/TR/scxml/#parallel}{parallel}, \l {http://www.w3.org/TR/scxml/#final}{final}, \l {http://www.w3.org/TR/scxml/#onentry}{onentry}, \l {http://www.w3.org/TR/scxml/#onexit}{onexit}, \l {http://www.w3.org/TR/scxml/#raise}{raise}, \l {http://www.w3.org/TR/scxml/#if}{if}, \l {http://www.w3.org/TR/scxml/#elseif}{elseif}, \l {http://www.w3.org/TR/scxml/#else}{else}, \l {http://www.w3.org/TR/scxml/#log}{log}, \l {http://www.w3.org/TR/scxml/#cancel}{cancel}, \l {http://www.w3.org/TR/scxml/#datamodel}{datamodel},\l {http://www.w3.org/TR/scxml/#data}{data}, \l {http://www.w3.org/TR/scxml/#assign}{assign}, \l {http://www.w3.org/TR/scxml/#param}{param}, ands \l {http://www.w3.org/TR/scxml/#anchor}{anchor} are fully supported according to the scxml spec. + + \section2 Partially supported elements + \list + \i \l {http://www.w3.org/TR/scxml/#scxml}{scxml}: The attributes version, profile and exmode are ignored. + \i \l {http://www.w3.org/TR/scxml/#initial}{initial}: Treated as a regular state that's marked as initial for the parent state. + \i \l {http://www.w3.org/TR/scxml/#history}{history}: Actions in the history's default transition are ignored. + \i \l {http://www.w3.org/TR/scxml/#content}{content}: Supports only JSON data, not XML. + \i \l {http://www.w3.org/TR/scxml/#send}{send}: only the scxml target type is supported. The id attribute is ignored. + \i \l {http://www.w3.org/TR/scxml/#invoke}{invoke}: the autoforward and id tags are ignored. + \endlist + + \section2 Unsupported elements + The elements \l {http://www.w3.org/TR/scxml/#Donedata}{donedata}, \l {http://www.w3.org/TR/scxml/#Finalize}{finalize} and \l {http://www.w3.org/TR/scxml/#Validate}{validate} are not supported. + Also, the local/global script scoping functionality is not implemented. + + \section2 Extras + \section3 Signal transitions + To declare a signal transition, use a transition tag with a q-signal uri scheme. + Example: + \code + <transition target="someState" event="q-signal:someObject.someSignal()" /> + \endcode + + \section3 Property binding + The q-binding invoker can be used to setup properties on entry, that are restored on exit. + Note that if the properties are changed externally while the state is active, the properties + would still be restored. + + The binding invoke element accepts a content tag with a JSON array, of which each element is a 3-item + array: [object, property-name, property-value]. + + Example: + + \code + <invoke type="q-bindings"><content> + [[myObject,"someProperty",someValue1 + someValue2], + [myObject,"text","hello"]] + </content></invoke> + \endcode + + \section3 Menus + A custom invoker added to the solution is the "q-menu" invoker. This invoker allows you to display a + QMenu and listen to its events. + The q-menu invoker should a content tag, which includes an expression evaluating to an ecmascript + object defining the menu. + Note that support for menus is currently experimental, and the mediaplayer example demonstrates its use. + + \section3 Message Boxes + Similar to q-menus, the "q-messagebox" invoker lets you show a QMessageBox and react to + the user interactions with it. + + The q-messagebox invoker accepts an ecmascript object that contains name/value pairs for the QMessageBox + properties. + + Example: + \code + <invoke type="q-messagebox"> + <content> + { + "parent" : myParentWidget, + "icon" : QMessageBox.Question, + "windowTitle" : "Would you like to exit?", + "text" : "Are you sure?", + "standardButtons" : QMessageBox.Yes|QMessageBox.No + } + </content> + </invoke> + \endcode + + See the blackjack example for reference. + + + + + + */ diff --git a/doc/scxml.qdocconf b/doc/scxml.qdocconf new file mode 100644 index 0000000..8fcf8fa --- /dev/null +++ b/doc/scxml.qdocconf @@ -0,0 +1,192 @@ +# Run qdoc from the directory that contains this file. + +project = qscxml +description = Qt SCXML + +headerdirs = ../src +sourcedirs = ../src +imagedirs = src/images +outputdir = html + +extraimages.HTML = qt-logo + +headers.fileextesnions = "*.h" +sources.fileextensions = "*.cpp *.qdoc" + + +# macros.qdocconf + +macro.aring.HTML = "å" +macro.Auml.HTML = "Ä" +macro.author = "\\bold{Author:}" +macro.br.HTML = "<br />" +macro.BR.HTML = "<br />" +macro.aacute.HTML = "á" +macro.eacute.HTML = "é" +macro.iacute.HTML = "í" +macro.gui = "\\bold" +macro.hr.HTML = "<hr />" +macro.key = "\\bold" +macro.menu = "\\bold" +macro.note = "\\bold{Note:}" +macro.oslash.HTML = "ø" +macro.ouml.HTML = "ö" +macro.QA = "\\e{Qt Assistant}" +macro.QD = "\\e{Qt Designer}" +macro.QL = "\\e{Qt Linguist}" +macro.param = "\\e" +macro.raisedaster.HTML = "<sup>*</sup>" +macro.reg.HTML = "<sup>®</sup>" +macro.return = "Returns" +macro.starslash = "\\c{*/}" +macro.uuml.HTML = "ü" +macro.mdash.HTML = "—" + +# compat.qdocconf + +alias.i = e +alias.include = input + +macro.0 = "\\\\0" +macro.b = "\\\\b" +macro.n = "\\\\n" +macro.r = "\\\\r" +macro.i = "\\o" +macro.i11 = "\\o{1,1}" +macro.i12 = "\\o{1,2}" +macro.i13 = "\\o{1,3}" +macro.i14 = "\\o{1,4}" +macro.i15 = "\\o{1,5}" +macro.i16 = "\\o{1,6}" +macro.i17 = "\\o{1,7}" +macro.i18 = "\\o{1,8}" +macro.i19 = "\\o{1,9}" +macro.i21 = "\\o{2,1}" +macro.i31 = "\\o{3,1}" +macro.i41 = "\\o{4,1}" +macro.i51 = "\\o{5,1}" +macro.i61 = "\\o{6,1}" +macro.i71 = "\\o{7,1}" +macro.i81 = "\\o{8,1}" +macro.i91 = "\\o{9,1}" +macro.img = "\\image" +macro.endquote = "\\endquotation" + +spurious = "Missing comma in .*" \ + "Missing pattern .*" + +# Doxygen compatibility commands + +macro.see = "\\sa" +macro.function = "\\fn" + +# qt-cpp-ignore.qdocconf + +Cpp.ignoretokens = QAXFACTORY_EXPORT \ + QDESIGNER_COMPONENTS_LIBRARY \ + QDESIGNER_EXTENSION_LIBRARY \ + QDESIGNER_SDK_LIBRARY \ + QDESIGNER_SHARED_LIBRARY \ + QDESIGNER_UILIB_LIBRARY \ + QM_EXPORT_CANVAS \ + QM_EXPORT_DNS \ + QM_EXPORT_DOM \ + QM_EXPORT_FTP \ + QM_EXPORT_HTTP \ + QM_EXPORT_ICONVIEW \ + QM_EXPORT_NETWORK \ + QM_EXPORT_OPENGL \ + QM_EXPORT_SQL \ + QM_EXPORT_TABLE \ + QM_EXPORT_WORKSPACE \ + QM_EXPORT_XML \ + QT_ASCII_CAST_WARN \ + QT_ASCII_CAST_WARN_CONSTRUCTOR \ + QT_BEGIN_HEADER \ + QT_DESIGNER_STATIC \ + QT_END_HEADER \ + QT_FASTCALL \ + QT_WIDGET_PLUGIN_EXPORT \ + Q_COMPAT_EXPORT \ + Q_CORE_EXPORT \ + Q_EXPLICIT \ + Q_EXPORT \ + Q_EXPORT_CODECS_CN \ + Q_EXPORT_CODECS_JP \ + Q_EXPORT_CODECS_KR \ + Q_EXPORT_PLUGIN \ + Q_GFX_INLINE \ + Q_GUI_EXPORT \ + Q_GUI_EXPORT_INLINE \ + Q_GUI_EXPORT_STYLE_CDE \ + Q_GUI_EXPORT_STYLE_COMPACT \ + Q_GUI_EXPORT_STYLE_MAC \ + Q_GUI_EXPORT_STYLE_MOTIF \ + Q_GUI_EXPORT_STYLE_MOTIFPLUS \ + Q_GUI_EXPORT_STYLE_PLATINUM \ + Q_GUI_EXPORT_STYLE_POCKETPC \ + Q_GUI_EXPORT_STYLE_SGI \ + Q_GUI_EXPORT_STYLE_WINDOWS \ + Q_GUI_EXPORT_STYLE_WINDOWSXP \ + QHELP_EXPORT \ + Q_INLINE_TEMPLATE \ + Q_INTERNAL_WIN_NO_THROW \ + Q_NETWORK_EXPORT \ + Q_OPENGL_EXPORT \ + Q_OUTOFLINE_TEMPLATE \ + Q_SQL_EXPORT \ + Q_SVG_EXPORT \ + Q_SCRIPT_EXPORT \ + Q_TESTLIB_EXPORT \ + Q_TYPENAME \ + Q_XML_EXPORT \ + Q_XMLSTREAM_EXPORT \ + Q_XMLPATTERNS_EXPORT \ + QDBUS_EXPORT \ + QT_BEGIN_NAMESPACE \ + QT_BEGIN_INCLUDE_NAMESPACE \ + QT_END_NAMESPACE \ + QT_END_INCLUDE_NAMESPACE \ + PHONON_EXPORT \ + EXTENSIONSYSTEM_EXPORT +Cpp.ignoredirectives = Q_DECLARE_HANDLE \ + Q_DECLARE_INTERFACE \ + Q_DECLARE_METATYPE \ + Q_DECLARE_OPERATORS_FOR_FLAGS \ + Q_DECLARE_PRIVATE \ + Q_DECLARE_PUBLIC \ + Q_DECLARE_SHARED \ + Q_DECLARE_TR_FUNCTIONS \ + Q_DECLARE_TYPEINFO \ + Q_DISABLE_COPY \ + QT_FORWARD_DECLARE_CLASS \ + Q_DUMMY_COMPARISON_OPERATOR \ + Q_ENUMS \ + Q_FLAGS \ + Q_INTERFACES \ + __attribute__ \ + K_DECLARE_PRIVATE \ + PHONON_OBJECT \ + PHONON_HEIR + + + +HTML.stylesheets = classic.css +HTML.postheader = "<table border=\"0\" cellpadding=\"0\" cellspacing=\"0\" width=\"100%\">\n" \ + "<tr>\n" \ + "<td align=\"left\" valign=\"top\" width=\"32\">" \ + "<img src=\"images/qt-logo.png\" align=\"left\" width=\"32\" height=\"32\" border=\"0\" />" \ + "</td>\n" \ + "<td width=\"1\"> </td>" \ + "<td class=\"postheader\" valign=\"center\">" \ + "<a href=\"qtcreator-manual.html\">" \ + "<font color=\"#004faf\">Home</font></a>" \ + "</td>\n" \ + "<td align=\"right\" valign=\"top\" width=\"230\"></td></tr></table><br>" + +HTML.footer = "<p /><address><hr /><div align=\"center\">\n" \ + "<table width=\"100%\" cellspacing=\"0\" border=\"0\"><tr class=\"address\">\n" \ + "<td width=\"30%\" align=\"left\">Copyright © 2009 Nokia</td>\n" \ + "<td width=\"40%\" align=\"center\"> </td>\n" \ + "<td width=\"30%\" align=\"right\"><div align=\"right\">Qt Creator 1.1.80</div></td>\n" \ + "</tr></table></div></address>" diff --git a/src/qscxml.cpp b/src/qscxml.cpp index 0651ade..675a0ae 100644 --- a/src/qscxml.cpp +++ b/src/qscxml.cpp @@ -40,12 +40,9 @@ ****************************************************************************/ /*! \class QScxml - \reentrant \brief The QScxml class provides a way to use scripting with the Qt State Machine Framework. - \ingroup sctools - Though can be used alone, QScxml is mainly a runtime helper to using the state-machine framework with SCXML files. @@ -352,7 +349,6 @@ static QScriptValue isInState(QScriptContext *context, QScriptEngine *engine) Encapsulates an event that conforms to the SCXML definition of events. - \ingroup sctools */ /*! \enum QScxmlEvent::MetaData::Kind @@ -421,8 +417,18 @@ QScxmlEvent::QScxmlEvent( \brief The QScxmlTransition class stands for a transition that responds to QScxmlEvent, and can be made conditional with a \l conditionExpression. Equivalent to the SCXML transition tag. - \ingroup sctools */ + +/*! +\fn QScxmlTransition::onTransition(QEvent* e) +Reimplements onTransition with even \a e, to activate the transition signal. +*/ + /*! +\fn QScxmlTransition::activated() +Emitted when the transition is activated, after exiting the old states before entering the new states. +*/ + + /*! \property QScxmlTransition::eventPrefix The event prefix to be used when testing if the transition needs to be invoked. Uses SCXML prefix matching. Use * to handle any event. @@ -591,6 +597,7 @@ class QScxmlBindingInvoker : public QScxmlInvoker } } }; + /*! \fn QScxmlInvoker::~QScxmlInvoker() @@ -790,7 +797,6 @@ void QScxml::registerInvokerFactory (QScxmlInvokerFactory* f) \brief The QScxmlInvoker class an invoker, which the state-machine context can activate or cancel with an <invoke> tag. - \ingroup sctools An invoker is a object that represents an external component that the state machine can activate when the encompassing state is entered, or cancel when the encompassing @@ -846,7 +852,9 @@ QScxml::~QScxml() { delete pvt; } - +/*! +returns the id for this invoker +*/ QString QScxmlInvoker::id () const { return initEvent->metaData.invokeID; |