QScriptEngineDebugger

Synopsis

Functions

• def action (action)
• def attachTo (engine)
• def autoShowStandardWindow ()
• def createStandardMenu ([parent=None])
• def createStandardToolBar ([parent=None])
• def setAutoShowStandardWindow (autoShow)
• def standardWindow ()
• def state ()
• def widget (widget)

Signals

• def evaluationResumed ()
• def evaluationSuspended ()

Detailed Description

The PySide.QtScriptTools.QScriptEngineDebugger class provides a PySide.QtScript.QScriptEngine debugger.

The PySide.QtScriptTools.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 PySide.QtScriptTools.QScriptEngineDebugger.attachTo() function.

engine = QScriptEngine()
debugger = QScriptEngineDebugger()
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 PySide.QtScript.QScriptEngine.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 PySide.QtScriptTools.QScriptEngineDebugger.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 QScriptEngineDebugger.DebuggerAction enum, and the widgets are identified by the QScriptEngineDebugger.DebuggerWidget enum.

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

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

The PySide.QtScriptTools.QScriptEngineDebugger.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 PySide.QtScriptTools.QScriptEngineDebugger.evaluationResumed() signal is emitted when script evaluation is resumed, i.e, when execution control is given back to the script engine. The PySide.QtScriptTools.QScriptEngineDebugger.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 PySide.QtGui.QWidget.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 QtScript 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.

See also

PySide.QtScript.QScriptEngine Context2D Example

class PySide.QtScriptTools.QScriptEngineDebugger([parent=None])

Parameters:parent – PySide.QtCore.QObject

Constructs a new PySide.QtScriptTools.QScriptEngineDebugger object with the given parent .

To attach a PySide.QtScript.QScriptEngine to the debugger, use PySide.QtScriptTools.QScriptEngineDebugger.attachTo() function.

PySide.QtScriptTools.QScriptEngineDebugger.DebuggerWidget

This enum decides the widget that the PySide.QtScriptTools.QScriptEngineDebugger.widget() function should retrieve. We treat these widgets in more detail in the Qt Script Debugger Manual .

Constant	Description
QScriptEngineDebugger.ConsoleWidget	Provides a command-line interface to the debugger.
QScriptEngineDebugger.StackWidget	Shows a backtrace of the script’s execution state.
QScriptEngineDebugger.ScriptsWidget	Displays a list of currently loaded scripts.
QScriptEngineDebugger.LocalsWidget	Shows the local variables of the current stack frame.
QScriptEngineDebugger.CodeWidget	Displays the code of the current script.
QScriptEngineDebugger.CodeFinderWidget	Provides a widget that can search for text in the script shown in the CodeWidget .
QScriptEngineDebugger.BreakpointsWidget	Shows breakpoints that have been set.
QScriptEngineDebugger.DebugOutputWidget	Contains output from the print() script function.
QScriptEngineDebugger.ErrorLogWidget	Shows error messages that have been generated.

PySide.QtScriptTools.QScriptEngineDebugger.DebuggerAction

This enum specifies the action that the PySide.QtScriptTools.QScriptEngineDebugger.action() function should retrieve. The actions retrieved can be connected to any slot and connected to any widget. Please see the Qt Script Debugger Manual ‘s Console Command Reference for a detailed description of these actions.

Constant	Description
QScriptEngineDebugger.InterruptAction	Suspends script execution as soon as the next script statement is reached.
QScriptEngineDebugger.ContinueAction	Gives the execution control back to the script engine.
QScriptEngineDebugger.StepIntoAction	Performs a step action.
QScriptEngineDebugger.StepOverAction	Performs a next action.
QScriptEngineDebugger.StepOutAction	Executes the script until the current function returns.
QScriptEngineDebugger.RunToCursorAction	Continues execution to the selected line (which contains the cursor) in the CodeWidget .
QScriptEngineDebugger.RunToNewScriptAction	Returns control to the script engine until a new script is executed.
QScriptEngineDebugger.ToggleBreakpointAction	Toggles a breakpoint at the selected line in the CodeWidget .
QScriptEngineDebugger.ClearDebugOutputAction	Clears the contents of the DebugOutputWidget .
QScriptEngineDebugger.ClearErrorLogAction	Clears the contents of the ErrorLogWidget .
QScriptEngineDebugger.ClearConsoleAction	Clears the contents of the ConsoleWidget .
QScriptEngineDebugger.FindInScriptAction	Displays the CodeFinderWidget .
QScriptEngineDebugger.FindNextInScriptAction	Finds next occurrence in the CodeWidget .
QScriptEngineDebugger.FindPreviousInScriptAction	Finds previous occurrence in the CodeWidget .
QScriptEngineDebugger.GoToLineAction	Shows the “Go to Line” dialog.

PySide.QtScriptTools.QScriptEngineDebugger.DebuggerState

This enum specifies the current state of the debugger.

Constant	Description
QScriptEngineDebugger.RunningState	The debugger is running. (Script evaluation is allowed.)
QScriptEngineDebugger.SuspendedState	The debugger has suspended script evaluation.

Note

This enum was introduced or modified in Qt 4.6

PySide.QtScriptTools.QScriptEngineDebugger.action(action)

Parameters:action – PySide.QtScriptTools.QScriptEngineDebugger.DebuggerAction Return type:PySide.QtGui.QAction

Returns a pointer to the specified action . The actions available are given by the QScriptEngineDebugger.DebuggerAction enum.

With this function, you can add the actions to your own widgets, toolbars, and menus. It is also convenient if you, for example, wish to spice things up with your own groovy icons. The code example below shows how to add actions to a PySide.QtGui.QToolBar .

continueAction = debugger.action(QScriptEngineDebugger.ContinueAction)
stepOverAction = debugger.action(QScriptEngineDebugger.StepOverAction)
stepIntoAction = debugger.action(QScriptEngineDebugger.StepIntoAction)

toolBar = QToolBar()
toolBar.addAction(continueAction)

Note that PySide.QtScriptTools.QScriptEngineDebugger has already added the actions to its standard widgets and standard window .

See also

PySide.QtScriptTools.QScriptEngineDebugger.widget() PySide.QtScriptTools.QScriptEngineDebugger.createStandardMenu() PySide.QtScriptTools.QScriptEngineDebugger.createStandardToolBar() PySide.QtScriptTools.QScriptEngineDebugger.standardWindow()

PySide.QtScriptTools.QScriptEngineDebugger.attachTo(engine)

Parameters:engine – PySide.QtScript.QScriptEngine

Attaches to the given engine .

The debugger will install a custom agent (using QScriptEngine.setAgent() ) to monitor the engine. While the debugger is attached, you should not change the agent; however, if you do have to perform additional monitoring, you must set a proxy agent that forwards all events to the debugger’s agent.

See also

detach()

PySide.QtScriptTools.QScriptEngineDebugger.autoShowStandardWindow()

Return type:PySide.QtCore.bool

Returns whether the standard debugger window is automatically shown when evaluation is suspended.

The default is true.

See also

PySide.QtScriptTools.QScriptEngineDebugger.setAutoShowStandardWindow()

PySide.QtScriptTools.QScriptEngineDebugger.createStandardMenu([parent=None])

Parameters:parent – PySide.QtGui.QWidget Return type:PySide.QtGui.QMenu

Creates a standard debugger menu with the given parent . Returns the new menu object.

See also

PySide.QtScriptTools.QScriptEngineDebugger.createStandardToolBar()

PySide.QtScriptTools.QScriptEngineDebugger.createStandardToolBar([parent=None])

Parameters:parent – PySide.QtGui.QWidget Return type:PySide.QtGui.QToolBar

Creates a standard debugger toolbar with the given parent . Returns the new toolbar object.

See also

PySide.QtScriptTools.QScriptEngineDebugger.createStandardMenu()

PySide.QtScriptTools.QScriptEngineDebugger.evaluationResumed()

PySide.QtScriptTools.QScriptEngineDebugger.evaluationSuspended()

PySide.QtScriptTools.QScriptEngineDebugger.setAutoShowStandardWindow(autoShow)

Parameters:autoShow – PySide.QtCore.bool

Sets whether the standard debugger window is automatically shown when evaluation is suspended. If autoShow is true, the window will be automatically shown, otherwise it will not.

See also

PySide.QtScriptTools.QScriptEngineDebugger.autoShowStandardWindow()

PySide.QtScriptTools.QScriptEngineDebugger.standardWindow()

Return type:PySide.QtGui.QMainWindow

Returns a main window with a standard configuration of the debugger’s components.

See also

PySide.QtScriptTools.QScriptEngineDebugger.createStandardMenu() PySide.QtScriptTools.QScriptEngineDebugger.createStandardToolBar()

PySide.QtScriptTools.QScriptEngineDebugger.state()

Return type:PySide.QtScriptTools.QScriptEngineDebugger.DebuggerState

Returns the current state of the debugger.

See also

PySide.QtScriptTools.QScriptEngineDebugger.evaluationResumed() PySide.QtScriptTools.QScriptEngineDebugger.evaluationSuspended()

PySide.QtScriptTools.QScriptEngineDebugger.widget(widget)

Parameters:widget – PySide.QtScriptTools.QScriptEngineDebugger.DebuggerWidget Return type:PySide.QtGui.QWidget

Returns a pointer to the instance of the specified standard widget . The widgets available are defined by the QScriptEngineDebugger.DebuggerWidget enum.

A main window containing all widgets is returned by PySide.QtScriptTools.QScriptEngineDebugger.standardWindow() . If you do not want to use this window, you can fetch the individual widgets with this function. For instance, the code example below shows how to set up a layout containing a code window and a stack widget .

codeWindow = debugger.widget(QScriptEngineDebugger.CodeWidget)
stackWidget = debugger.widget(QScriptEngineDebugger.StackWidget)

layout = QHBoxLayout()
layout.addWidget(codeWindow)
layout.addWidget(stackWidget)

Note that you need to set PySide.QtScriptTools.QScriptEngineDebugger.setAutoShowStandardWindow() to false; if not, the standard window will be shown regardless.

See also

PySide.QtScriptTools.QScriptEngineDebugger.action() PySide.QtScriptTools.QScriptEngineDebugger.standardWindow() PySide.QtScriptTools.QScriptEngineDebugger.setAutoShowStandardWindow()