QScriptEngineDebugger Class

Detailed Description

The QScriptEngineDebugger class provides a debugger that can be embedded into Qt applications that use Qt Script. The debugger enables the application user to inspect the state of the script environment and control script execution.

To attach the debugger to a script engine, call the attachTo() function.

     QScriptEngine engine;
     QScriptEngineDebugger debugger;
     debugger.attachTo(&engine);

Once the debugger has been attached to a script engine, you can proceed to evaluate scripts as usual, e.g. by calling QScriptEngine::evaluate(). The debugger will be triggered when an uncaught exception occurs, or when a debugger statement is encountered in a script. It is also possible to interrupt script evaluation at an arbitrary time by triggering the InterruptAction. For instance, to start the debugger when script evaluation starts, you trigger the action before you begin to evaluate() the script.

      debugger->action(QScriptEngineDebugger::InterruptAction)->trigger();
      engine->evaluate(contents, fileName);

By default, the standard debugger window is shown when evaluation is suspended. This can be changed by calling the setAutoShowStandardWindow() function.

The debugger defines a set of actions that are available, such as stopping execution or printing the contents of a variable. It also provides a set of widgets (components) that display the information available from the debugger and that trigger the actions on request. The actions available are identified by the DebuggerAction enum, and the widgets are identified by the DebuggerWidget enum.

Access to the individual debugger widgets is provided by the widget() function. This makes it possible to arrange the widgets in a custom manner. Similarly, the action() function provides access to the various debugger actions.

The createStandardToolBar() function creates a standard toolbar, and the createStandardMenu() function creates a standard menu; these functions can be useful if you are creating a custom debugger configuration.

The evaluationSuspended() signal is emitted when the debugger has suspended script evaluation and entered interactive mode, i.e., the mode in which it accepts input from the user. The evaluationResumed() signal is emitted when script evaluation is resumed, i.e, when execution control is given back to the script engine. The state() function returns the debugger's current state.

When calling QScriptEngine::evaluate() it is useful to pass a descriptive script name (file name) as second argument, as this is the name that will be displayed by the debugger in the ScriptsWidget; if a name is not passed, the script will be labelled "anonymous".

When evaluation is suspended, the debugger will also suspend the event loop of the script. In the following snippet, the call to QScriptEngine::evaluate() causes the debugger to be triggered, and the function call does not return until the user has finished interacting with the debugger.

     engine.evaluate("debugger");

When the Qt Script debugger is running, the C++ application itself is not "frozen". This means that it is possible that more scripts are evaluated, even though the debugger has suspended evaluation of the current script evaluation. For example, a C++ timer might trigger that causes a script function to be called, or the user might click on a button in the main application user interface whose clicked() signal is connected to a script function. This kind of nested evaluation is permitted. The debugger will enter interactive mode for the new script if an exception is thrown or a breakpoint is reached. Note that it will not stop when encountering debugger statements.

Nested evaluation requires some thought when deciding how the debugger is presented to the user; for example, whether a modal dialog is suitable, or whether some parts of the main application user interface should be disabled while the debugger is running.

Debugging inside of a paintEvent() is currently not supported. If you need to debug painting-related script code, that code should be evaluated outside of the C++ paintEvent(), e.g. by rendering to an image, like the Context2D and Tetrix Qt Script examples do. This will make the code safe for debugging.

The debugger adds some special properties to the script engine: __FILE__ holds the name of the script in which the current evaluation occurs, and __LINE__ holds the current line number. These are useful when doing print()-style debugging (the messages appear in the debugger's debug output widget).

The Qt Script Debugger Manual describes how to use the debugger. The Context2D example shows how to integrate the debugger in applications.