Debugger Visualizers and Formatters

From RAD Studio
Jump to: navigation, search

Go Up to Debugging Applications Index


Debuggers support two types of data visualizers that provide a custom view of your data. The visualizers are associated with a specific data type. For example, the TDateTime visualizer that is available in the product works only with TDate, TTime, and TDateTime data.

The video Debug Visualizer in RAD Studio shows more about the visualizers.

Tools API Supports Debugger Visualizers

You can write your own plug-in data visualizers in addition to the installed visualizers that are part of the product. When you develop your own visualizer, you can specify that the visualizer is to be applied to a specific data type and all descendent types. The following interfaces in Tools API support the two types of visualizers described here:

  • IOTADebuggerVisualizer
  • IOTADebuggerVisualizerValueReplacer
  • IOTADebuggerVisualizerExternalViewer

Types of Visualizers: Value Replacer and External Viewer

There are two types of debugger visualizer: Value replacers and External viewers.

Value-Replacer Visualizers

This type of visualizer replaces the value that is returned by the built-in evaluator with a more meaningful value.

Each data type can have only one value-replacer visualizer associated with it. Therefore, if a value-replacer visualizer exists for a data type, the data is automatically processed by the debugger visualizer. In such a case, the various Debug windows give no indication that the visualizer is involved. You can, however, enable/disable the visualizers on the Visualizers page in Tools > Options.

TDateTime Visualizer

The TDateTime visualizer for Delphi and C++ uses the DateTimeToStr function from SysUtils to replace the Double value that represents a TDateTime value. The following table shows several TDateTime values along with the output from the TDateTime visualizer. Note that the output is locale-dependent, and the data you see might vary based on your locale and your current ShortDateFormat and LongTimeFormat global variables.

Raw TDateTime Value    
(Double)
Value from TDateTime
Visualizer

2.75

1/1/1900 6:00 pm

-1.25

12/29/1899 6:00 am

10894.395833

10/28/1929 9:29:59 AM

std::string and std::wstring Visualizers

Two value-replacer visualizers are exclusively for C++ (std::string and std::wstring). These visualizers automatically display the actual strings, so that you do not have to examine the internals of the class to find the actual string values.

External-Viewer Visualizers

This type of visualizer displays a separate window or viewer to show the data. For example, the TStrings/TStringList visualizer displays a separate listview that shows the actual strings contained in the list. Without the visualizer, the debugger displays the internals of the data structure.

The ExternalVisualizer.png icon appears in windows where you can use visualizers when an external-viewer visualizer is available for the data in that field. Click the down-arrow on the ExternalVisualizer.png to display and select from the available external-viewer visualizers. In most cases, you can also right-click the data item and select Visualizers from the context menu.

Where to Interact with Debugger Visualizers

You can use any installed debugger visualizers when you are debugging your applications. When debugger visualizers are enabled:

  • The value-replacer type visualizers (such as TDateTime and c::string/wstring) automatically convert the raw data of a specific type into a different, more understandable format.
  • The external-viewer type visualizers typically display the ExternalVisualizer.png icon in the field containing data on which they can operate, and most windows also have a Visualizers context menu command.

These are the places in the IDE where debugger visualizers can be used:

  • Watch List Window
  • Local Variables Window
  • Debug Inspector
  • Evaluate/Modify dialog box - toolbar button
  • Evaluator Tooltips - When you hover the mouse over a variable during a Debug session, the tooltips display the data from the visualizer if visualizers are enabled and if one is available for that data type. This applies to both types of visualizers.

You can enable/disable specific visualizers on Tools > Options > Debugger Options > Visualizers.

LLDB

LLDB data formatters have a subsystem allowing users to customize the display options for their variables.

LLDB automatically selects how to display the results by type, as in the following example:

(lldb) frame variable
(uint8_t) x = 'a'
(intptr_t) y = 124752287


To add or modify variable formatting to the .lldbinit file directly (in ~bin\Windows\lldb), the Python changes must go into embt_formatters.py. These files are loaded at the start of each debugging session so changes can be performed without restarting the IDE. The formatters are Python functions and classes that make heavy use of the LLDB Python API; for more information, see:

See Also