--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/src/scripting/qtscriptdebugger-manual.qdoc	Mon Jan 11 14:00:40 2010 +0000
@@ -0,0 +1,436 @@
+/****************************************************************************
+**
+** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).
+** All rights reserved.
+** Contact: Nokia Corporation (qt-info@nokia.com)
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:LGPL$
+** No Commercial Usage
+** This file contains pre-release code and may not be distributed.
+** You may use this file in accordance with the terms and conditions
+** contained in the Technology Preview License Agreement accompanying
+** this package.
+**
+** GNU Lesser General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU Lesser
+** General Public License version 2.1 as published by the Free Software
+** Foundation and appearing in the file LICENSE.LGPL included in the
+** packaging of this file.  Please review the following information to
+** ensure the GNU Lesser General Public License version 2.1 requirements
+** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
+**
+** In addition, as a special exception, Nokia gives you certain additional
+** rights.  These rights are described in the Nokia Qt LGPL Exception
+** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
+**
+** If you have questions regarding the use of this file, please contact
+** Nokia at qt-info@nokia.com.
+**
+**
+**
+**
+**
+**
+**
+**
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+    \page qtscriptdebugger-manual.html
+    \title Qt Script Debugger Manual
+    \brief A manual describing how to use the Qt Script debugger.
+
+  The Qt Script debugger is a tool for debugging script execution in
+  Qt applications that use Qt Script. Application developers can embed
+  the debugger into their application through the
+  QScriptEngineDebugger class. This manual describes how to use the
+  debugger. We assume that the reader is somewhat familiar with
+  general debugging concepts and existing debugging tools.
+
+  We assume that the debugger has been integrated into the application
+  through the QScriptEngineDebugger::standardWindow()
+  function, which provides the standard debugger configuration.
+
+  \tableofcontents
+
+  \section1 Getting Started
+
+  The following image shows the debugger as created with
+  \l{QScriptEngineDebugger::}{standardWindow()}:
+
+  \image qtscript-debugger.png Running a script under the Qt Script debugger.
+
+  The debugger will start, i.e., take control over the script's
+  execution when any of these conditions are met:
+
+  \list
+    \o The \c{debugger} statement is encountered in the script.
+    \o Clicking the \gui Interrupt menu item from the \gui Debug
+        menu in the main window.
+    \o A breakpoint is reached.
+    \o An uncaught script exception is thrown.
+  \endlist
+
+  Once the debugger is started, the execution state can be inspected,
+  e.g., the value of variables can be queried and the current program
+  stack shown. New breakpoints can be set.
+
+  The debugger will resume, i.e., give the control back to the script
+  engine, when the user clicks \gui Continue menu item from the \gui
+  Debug menu. It will be invoked again if one of the conditions
+  described in the list above is met.
+
+  \section1 Overview of Debugger Components
+
+  The debugger's functionality is divided into a series of components,
+  each being a widget that can be shown in the main window of the
+  debugger. The following table describes each component and how they
+  relate to each other.
+
+  \table
+    \header
+      \o Component
+      \o Description
+  \row
+  \o Console Widget 
+  \o The console widget provides a command-line interface to the
+  debugger's functionality, and also serves as an interactive script
+  interpreter. The set of commands and their syntax is inspired by
+  GDB, the GNU Debugger. Commands and script variables are
+  auto-completed through the TAB key.
+
+  Any console command that causes a change in the debugger or debugger
+  target's state will immediately be reflected in the other debugger
+  components (e.g. breakpoints or local variables changed).
+
+  The console provides a simple and powerful way of manipulating the
+  script environment. For example, typing "x" and hitting enter will
+  evaluate "x" in the current stack frame and display the result.
+  Typing "x = 123" will assign the value 123 to the variable \c{x} in
+  the current scope (or create a global variable \c{x} if there isn't
+  one -- scripts evaluated through the console can have arbitrary side
+  effects, so be careful).
+
+  \row
+  \o Stack Widget
+  \o The stack widget shows a backtrace of the script execution state.
+  Each row represents one frame in the stack. A row contains the
+  frame index (0 being the inner-most frame), the name of the script function,
+  and the location (file name and line number). To select a particular
+  stack frame to inspect, click on its row.
+
+  \row
+  \o Locals Widget
+  \o The locals widget shows the variables that are local to the
+  currently selected stack frame; that is, the properties of the
+  objects in the scope chain and the \c{this}-object. Objects can be
+  expanded, so that their properties can be examined, recursively.
+  Properties whose value has changed are shown in bold font.
+
+  Properties that are not read-only can be edited. Double-click on the
+  value and type in the new value; the value can be an arbitrary
+  expression. The expression will be evaluated in the associated stack
+  frame. While typing, you can press the TAB key to get possible
+  completions for the expression.
+
+  \row
+  \o Code Widget
+  \o The code widget shows the code of the currently selected script.
+    The widget displays an arrow in the left margin, marking the
+    code line that is being executed.
+    Clicking in the margin of a line will cause a breakpoint to be
+    toggled at that line. A breakpoint has to be set on a line that
+    contains an actual statement in order to be useful.When an uncaught script exception occurs, the
+    offending line will be shown with a red background.
+
+    The code widget is read-only; it cannot currently be used to edit
+    and (re)evaluate scripts. This is however possible from the
+    command-line interface, see \l{Console Command Reference}.
+
+  \row
+  \o Scripts Widget
+
+  \o The scripts widget shows the scripts that are currently loaded in
+  the script engine. Clicking on a script will cause its code to be
+  shown in the code widget. When a script is no longer referenced by
+  the debugger target it is removed from the scripts widget. Code
+  evaluated through QScriptEngine::evaluate() without a name specified, will be
+  displayed in the widget as Anonymous.
+
+  \row
+    \o Breakpoints Widget
+
+  \o The breakpoints widget shows all the breakpoints that are set.  A
+  breakpoint can be disabled or enabled by clicking the checkbox next
+  to the breakpoint's ID (the ID is provided so that the breakpoint
+  can be manipulated through the console widget as well).
+
+  A condition can be associated with the breakpoint; the condition can
+  be an arbitrary expression that should evaluate to true or
+  false. The breakpoint will only be triggered when its location is
+  reached \bold{and} the condition evaluates to true.
+
+  Similarly, if the breakpoint's ignore-count is set to N, the
+  breakpoint will be ignored the next N times it is hit.
+
+  A new breakpoint can be set by clicking the New Breakpoint button
+  and typing in a location of the form <filename>\bold{:}<linenumber>.
+  The breakpoint location can refer to an already loaded script, or
+  one that has not been loaded yet.
+
+  \row
+  \o Debug Output Widget
+  \o The debug output widget shows messages generated by the print()
+  script function. Scripts can use the special variables \c{__FILE__}
+  and \c{__LINE__} to include the current location information in the
+  messages.
+
+  \row
+  \o Error Log Widget
+  \o The error log widget shows error messages that have been generated.
+     All uncaught exceptions that occur in the engine will appear here.
+
+  \endtable
+
+  \section2 Resuming Script Evaluation
+
+  Script evaluation can be resumed in one of the following ways:
+
+  \list
+  \o \bold{Continue}: Evaluation will resume normally.
+  \o \bold{Step Into}: Evaluation will resume until the next statement is reached.
+  \o \bold{Step Over}: Evaluation will resume until the next statement is reached;
+                but if the current statement is a function call, the debugger
+                will treat it as a single statement.
+  \o \bold{Step Out}: Evaluation will resume until the current function exits and
+               the next statement is reached.
+  \o \bold{Run to Cursor}: Run until the statement at the cursor is reached.
+  \o \bold{Run to New Script}: Run until the first statement of a new script is reached.
+  \endlist
+
+  In any case, script evaluation can also be stopped due to either of the
+  following reasons:
+
+  \list
+  \o A \c{debugger} statement is encountered.
+  \o A breakpoint is hit.
+  \o An uncaught script exception occurs.
+  \endlist
+
+  \section2 Resuming After an Uncaught Exception
+
+  When an uncaught script exception occurs, it is not possible to
+  continue evaluating the current function normally. However, you can
+  use the console command \bold{return} to catch the exception and
+  return a value to the calling function.
+
+  \section1 Console Command Reference
+
+  Note that you can also get help on the available commands by typing
+  ".help" in the console.
+
+  \section2 Breakpoint-related Commands
+
+  Break points is set
+
+  \section3 break <location>
+
+  Sets a breakpoint at a given code line.
+
+  \code
+  .break foo.qs:123
+  \endcode
+
+  This command sets a breakpoint at \c{foo.qs}, line 123.
+
+  \code
+  .break 123
+  \endcode
+
+  This command sets a breakpoint at line 123 in the current script; the current script
+  is the script associated with the current stack frame.
+
+  Each breakpoint has a unique identifier (an integer) associated with it.
+  This identifier is needed by other breakpoint-related commands.
+
+  \section3 clear <location>
+
+  \code
+  .clear foo.qs:123
+  \endcode
+
+  clears (deletes) the breakpoint at \c{foo.qs}, line 123.
+
+  \code
+  clear 123
+  \endcode
+
+  clears (deletes) the breakpoint at line 123 in the current script;
+  the current script is the script associated with the current stack
+  frame.
+
+  \section3 condition <breakpoint-id> <expression>
+
+  Sets a condition for a breakpoint.
+
+  \code
+  .condition 1 i > 42
+  \endcode
+
+  specifies that breakpoint 1 should only be triggered if the variable \c{i}
+  is greater than 42.
+
+  The expression can be an arbitrary one, i.e. it can have
+  side-effects. It can be any valid QScript conditional
+  expression.
+
+  \section3 delete <breakpoint-id>
+
+  Deletes a breakpoint, i.e., removes it from the current debugging
+  session.
+
+  \section3 disable <breakpoint-id>
+
+  Disables a breakpoint. The breakpoint will continue to exist, but
+  will not stop program execution.
+
+  \section3 enable <breakpoint-id>
+
+  Enables a breakpoint. Breakpoints are enabled by default, so you
+  only need to use this command if you have disabled to breakpoint
+  previously.
+
+  \section3 ignore <breakpoint-id> <count>
+  
+  Sets the ignore-count of a breakpoint, i.e., the breakpoint will not
+  stop the program execution unless it have been reached \c count
+  times. This can, for instance, be useful in loops to stop at a
+  specific iteration.
+
+  \code
+  .ignore 1 5
+  \endcode
+
+  Specifies that breakpoint 1 should be ignored the next 5 times it is
+  hit.
+
+  \section3 info breakpoints
+
+  Lists the breakpoints that are set.
+
+  \code
+    .info breakpoints
+  \endcode
+
+  \section3 tbreak <location>
+
+  Sets a temporary breakpoint. This command is identical to the
+  \c{break} command, only the breakpoint will be automatically deleted
+  the first time it is hit.
+
+  \section2 File-related Commands
+
+  \section3 list <location>
+
+  Lists the contents of a script around a given location, where the
+  location is given as a line number and, optionally, the name of the
+  file from which you will print. If only a line number is given, \c
+  {.list} will use the file of the current stack frame.
+
+  \code
+    .list foo.qs:125
+  \endcode
+
+  When no arguments are given, \c{list} will incrementally list
+  sections of the current script.
+
+  \section3 info scripts
+
+  Lists the scripts that are currently loaded.
+
+  \section2 Execution-related Commands
+
+  \section3 advance <location>
+
+  Advances execution to a given location. The syntax of the location
+  is the same as for setting breakpoints. For example:
+
+  \code
+    .advance foo.qs:125
+  \endcode
+
+  \section3 continue
+
+  Continues execution normally, i.e, gives the execution control over
+  the script back to the QScriptEngine.
+
+  \section3 eval <program>
+
+  Evaluates a program. 
+
+  \section3 finish
+
+  Continues execution until the current function exits and the next
+  statement is reached (i.e., the statement after the call to the
+  function).
+
+  \section3 interrupt
+
+  Requests that execution should be interrupted. Interruption will
+  occur as soon as a new script statement is reached.
+
+  \section3 next <count = 1>
+
+  Continues execution until a new statement is reached; but if the
+  current statement is a function call, the function call will be
+  treated as a single statement. This will be done \c count times
+  before execution is stopped; the default is one.
+
+  \section3 return <expression>
+
+  Makes the current frame return to its caller. If \c expression is
+  given, it will sent as the result of the function (i.e., replacing
+  the functions return value). \c expression can be any valid QScript
+  expression.
+
+  \section3 step <count = 1>
+
+  Continues execution until a new statement is reached. If the number
+  \c count is given as argument, this will be done \c count times
+  before execution is stopped. As opposed to \l{next <count = 1>},  \c
+  step will enter functions when encountering a function call
+  statement.
+
+  \section2 Stack-related Commands
+
+  \section3 backtrace
+
+  Shows a backtrace of the current execution. The trace will list the
+  function name and its position in the script for each stack frame.
+
+  \section3 down
+
+  Selects the previous (inner) stack frame. The execution will not
+  return to this frame, but you will get access to its local
+  variables. 
+
+  \section3 frame <index>
+
+  This command moves to the stack frame with the given \c index. The
+  index of the frame on the top of the stack is 0. Previous frames are
+  numbered from 1 and upwards (the bottom frame in the stack has the
+  largest index).
+
+  \section3 info locals
+
+  Lists the variables that are in the scope of the current frame.
+
+  \section3 up
+
+  Selects the next (outer) stack frame.
+
+*/