<type>documentation</type>
<domain>debug</domain>
<id>stack-data-view</id>
<title>Stack Data Tool</title>
<date>$Date$</date>
<version>$Revision$</version>
<product>all</product>

The `Stack Data <script:show_panel#panel_type="debug-data">`__ tool can be used to view
debug data for locals and globals. It contains a process, thread, and stack frame
selection area, an expandable tree area for viewing data, and a details area for
inspecting individual values as an array or in textual form.

**Process, Thread, and Stack Frame Selector**

The top part of the tool contains popup menus for selecting the current debug process,
thread, and stack frame to focus on.  The process selector is omitted in Wing 101
and Wing Personal, which do not support multi-process debugging.  The thread selector
is hidden unless there is more than one thread in the debug process.  

This area also contains the `Stack Data Options Menu <ref:debug/popup-menu-options>`__.

**Value Display**

The value display area is shown below the stack selector area, and will contain the values
for the currently selected process, thread, and stack frame. Each value or part of a value
is shown as one line in the tree.

Simple values, such as strings and numbers, and values with a short string representation,
are displayed in the ``Value`` column of the tree. Strings are always contained in ``""``
(double quotes). Any value outside of quotes is the ``repr`` of an instance, a number, or
a Python constant such as ``None`` or ``False``. Integers can be displayed as decimal,
hexadecimal, or octal, as controlled by the `Debugger > Data Display > Integer Display
Mode <script:show_preferences_gui#prefname="debug.default-integer-mode">`__ preference.

Complex values, such as instances, lists, and dictionaries, will be shown in a short form
containing type and (optionally) the memory address, for example ``<dict 0x80ce388>``.
These can expanded by clicking on the expansion indicator in the ``Variable`` column. The
memory address uniquely identifies the instance. If you see the same address in two
places, you are looking at two object references to the same instance. Memory addresses
may be hidden by toggling ``Show Memory Addresses`` in the tool's ``Options`` menu.

If a complex value is short enough to be displayed in its entirety, the ``<type address>``
form is replaced with its value, for example ``{'a': 'b'}`` for a small dictionary. These
values can still be expanded from the ``Variable`` column. The size threshold used for
this is set with the `Debugger > Line Threshold
<script:show_preferences_gui#prefname="debug.line-threshold">`__ preference. If you want 
all values to be shown uniformly, set this preference to ``0``.

**Expanding Values**

When a complex value is expanded, the position or name of each sub-value will be displayed
in the ``Variable`` column, and the value of each sub-value (possibly also complex values)
will be displayed in the ``Value`` column. Nested complex values can be expanded
indefinitely, even if this results in the traversal of cycles of object references.

Once you expand a value, the debugger will continue to present that entry expanded, even
after you step further or restart the debug session. Expansion state is saved and reused
in later debug sessions, until you quit Wing.

Selected values can be viewed as an array or text by right-clicking on the item and 
choosing ``Show Value as Array`` or ``Show Value as Text``.  The content of the detail 
area is updated when other items in the ``Stack Data`` tool are selected.  See `Array and 
Textual Data Views <ref:debug/details-view>`__ for details.

**Data Handling Errors**

Wing may fail to show some data values because they are too large or can't be inspected
safely. These are indicated in ``Stack Data`` in the following forms:

* ``<huge sometype; len=10000>`` -- indicates a value of type ``sometype`` with given 
  top-level length (if known) is too large to display because its overall size exceeds
  the `Debugger > Data Display > Huge List Threshold <script:show_preferences_gui#prefname="debug.huge-list-threshold">`__
  or `Huge String Threshold <script:show_preferences_gui#prefname="debug.huge-string-threshold">`__
  preferences.  This may occur also for values with a small top-level size but which appear
  to generate a representation that large enough to hang up the debugger during data inspection.
  
* ``<opaque sometype>`` -- indicates that a value of type ``sometype`` cannot be displayed
  because it is being filtered out by the `Debugger > Data Filters > Do Not Expand 
  <script:show_preferences_gui#prefname="debug.no-probe-type">`__ preference or because
  settings described in `Advanced Data Display <ref:debug/advanced-data-display>`__
  prevent extraction of the value.
  
* ``<verror sometype; code=xyz>`` -- indicates that a value of type ``sometype`` cannot 
  be displayed because the debugger could not extract a displayable
  representation of the value. These value errors often indicate bugs in the
  code that implements the values Wing is trying to inspect. However, please
  report these errors using ``Submit Bug Report`` in Wing's ``Help`` menu or
  by sending email to `support@wingware.com <mailto:support@wingware.com>`__.
  Your report may enable us to improve Wing's data inspection facility to better
  handle the case you are seeing.

Some values that are too large for display in the ``Stack Data`` tool may still be viewed as
arrays by right-clicking on the value and selecting ``Show Value as Array``. Arrays are
loaded incrementally according to what is visible on screen, and thus are less subject to
size thresholds.

~~~if WINGPRO:
In Wing Pro you may also be able to use the `Debug Console <ref:debug/debug-console>`__
to access large or opaque values (for example try typing ``dir(varname)``), or enter
expressions into the `Watch <ref:debug/evaluating-expressions>`__ tool.
~~~

For details, see `Problems Handling Values <ref:debug/problems-handling-values>`__.
