IDE Window: Watch list: what changed

Revision 0 to 1. Removed lines have a minus sign; added lines have a plus sign.

Title: IDE Window: Watch list

New		Line
1	+	# Introduction
2	+
3	+	The Watches window is part of the Lazarus debugger.
4	+
5	+	It displays the values of variables and expressions while an application is paused by the debugger (e.g. at a breakpoint or during stepping).
6	+
7	+	# Navigation
8	+
9	+	The watches window can be opened via
10	+
11	+	- [[Main menu\|Main Menu]] \> [[Main menu\|View]] \> Debug Windows \> Watches
12	+	- `Ctrl`+`Alt`+`W`
13	+	- Adding a new watch:
14	+	- `Ctrl`+`F5` or [[Main menu\|Main Menu]] \> [[Main menu\|Run]] \> Add Watch
15	+	- "Add Watch" tool-button in * [[IDE Window: Evaluate/Modify\|Evaluate Window]] and [[IDE Window: Variable Inspector\|Debug Inspector]]
16	+
17	+	# Overview
18	+
19	+	![](/wiki-images/7/7a/WatchesWindow_3_0_FpDbg_minimum.png)
20	+
21	+	By default there are 2 columns in the watches Window.
22	+
23	+	- On the left side the "Expression" shows the name of the variable for which data should be shown.\
24	+	This can also be an expression containing multiple variables, operators, index access and more.
25	+	- On the right site the current value of the variable or expression is displayed.\
26	+	The display format depends on the value and can be refined in the "#Watch Properties" dialog.
27	+
28	+	Additional details can be enabled using the #Toolbar.\
29	+	The images below show:
30	+
31	+	- The "Data-Address" column
32	+	- The "Inspect-Pane" (on the right side, showing the current watch in more detail)\
33	+	(Example: Hex dump of a string)
34	+	- Expanded structured values (objects, classes, records)
35	+	- Expanded arrays
36	+
37	+	More detailed view (FpDebug)
38	+
39	+	![](/wiki-images/1/1a/WatchesWindow_3_0_FpDbg_expanded.png)
40	+
41	+	More detailed view (Gdb)
42	+
43	+	![](/wiki-images/8/81/WatchesWindow_3_0_Gdb_expanded.png)
44	+
45	+	# First steps - Add watches
46	+
47	+	When the debugger paused your app, you can add new values to the Watches window. Either
48	+
49	+	- Select a variable in the source and press `Ctrl`+`F5`
50	+	- Add a new watch from the menu [[Main menu\|Main Menu]] \> [[Main menu\|Run]] \> Add Watch
51	+	- Open the `Ctrl`+`Alt`+`W` and press ![](/wiki-images/2/2f/Laz_add.png) from the toolbar.
52	+
53	+	The new "watch" will be evaluated and the result shown.\
54	+	You can also add watches before you start the debugger, or while the app is running. In this case the values will be retrieved as soon as the app gets paused.
55	+
56	+	If you step through your code or run the app to the next breakpoint all your watches will be updated each time the app pauses at the next location.
57	+
58	+	Expressions can be local or global variables, ([[GDB Debugger Tips\|certain]]) properties, or pascal expressions (limited support, e.g. "a+1"). [[GDB Debugger Tips\|See here for more information]]
59	+
60	+	# Data - Values
61	+
62	+	The data is retrieved from the memory of the debugged app. The debugger then formats it according to the type or the variable.
63	+
64	+	## Resolving variable names (multiple var with same name) - Selected Scope
65	+
66	+	Variable/Identifier names are looked up according to Pascal scoping rules from the current line of code.
67	+
68	+	"Current line"
69	+	is the line at which the app is paused (or the line selected via thread and stack).
70	+
71	+	The "current line" scoping also applies, if a new watch is added. You may select a variable/identifier anywhere in the code and add it with `Ctrl`+`F5`. It will be resolved according to the current line, even if you selected it in another function (or even if it was a global variable).
72	+
73	+	### Scoping limitations and exceptions
74	+
75	+	The debug info does not always provide all scoping info.
76	+
77	+	- For global variables from other units the correct "lookup order" is not known.
78	+	- Global Identifiers in all other units will be visible, and can be found in a non-specified order.\
79	+	So if two units (other than the current unit) both have a variable "MyValue" (and there is no such variable in the current unit), then the debugger will display one of them, but it may not be the one the compiler would have picked. (see <https://gitlab.com/freepascal.org/lazarus/lazarus/-/issues/40173>)
80	+	- Local variables, fields of the object (including if inherited from a base class in another unit), and global variables in the current unit are not affected, but can be if type-casted using a global type declaration.
81	+	- Nested procedures: Local variables from the outer procedure(s) are shown, however this includes variables declared below the nested procedure, which should not be visible. Such an incorrectly show outer local variable may hide another var/field that should be shown instead.
82	+	- This may also depend on the debugger backend, for more information see notes on each debugger backend.
83	+
84	+	This also allows for more flexible type casting. In case of "Sender: TObject", the instance my be of class "TFooUnit.TMyFoo". Yet the current unit may not be using "TFooUnit". The debugger will still find TMyFoo, if you want to add a watch "TMyFoo(Sender)". The caveat is if you have several classes "TMyFoo" in different units, then (again) the debugger can't tell which one to use.
85	+
86	+	### Scope (Stackframe, Thread, History)
87	+
88	+	The values are evaluated according to the scope set in the [[IDE Window: Threads\|Thread]] and [[IDE Window: Call Stack\|Stack]] dialog. Default is the current Thread and top stack frame. Both (Stack and Frame) dialog offer to change the "current" Frame/Thread. The watch window will follow this selection.
89	+
90	+	It is also possible to select previously displayed values, using the [[IDE Window: Debug History\|History]] dialog.
91	+
92	+	## Values / Display
93	+
94	+	##### Expression
95	+
96	+	The Pascal expression that is evaluated. Usually the name of a variable.
97	+
98	+	Expressions are expected to have Pascal Syntax. However the extend to which this is understood depends on the backend (see each backend from the [[Debugger Status]] page).
99	+
100	+	- Note that some backends (like GdbMi) may accept some pascal operators, but have different operator precedence.
101	+	- FpDebug based backends also offer
102	+	- [[FpDebug-Watches-Intrinsic-Functions]]
103	+	- [[FpDebug-Watches-FunctionEval]]
104	+
105	+	When expanding structures/arrays, this is a short alias for the element within the expanded data.
106	+
107	+	##### Data Address
108	+
109	+	Some Pascal data types have an internal pointer. For example: Strings, dynamic arrays, instances (of classes). For those the data is not stored in the variable (The address of the variable "@MyVar" will point to the internal pointer, but not the the data in the type / not to the field of the object, or entries in the array).
110	+
111	+	Pascal code can access the internal pointer by type casting the variable "PtrUInt(MyVar)". In a way the internal pointer is part of the data, it is stored in the variable. This address can be used for testing equality. That is, if 2 variables refer to the same data (not just identical data).
112	+
113	+	The debugger shows this "data address" in the equally name column.
114	+
115	+	##### Value
116	+
117	+	The value of the variable (or result of the expression).
118	+
119	+	The format can be influenced by the Watch properties.
120	+
121	+	##### Detail pane
122	+
123	+	More detailed view of one watch. This field will show the selected/focused watch. It provides extra space so more data can be viewed.
124	+
125	+	It also supports line breaks in the data, so if the value is formatted with line breaks (structures/arrays, but not strings - they are escaped) then it will be shown accordingly. It may be worth changing the width of the pane so it does no add wrapping, if there are linebreaks already)
126	+
127	+	##### Viewing/Expanding Structures (classes/records)
128	+
129	+	Depends on the backend
130	+
131	+	- Structures can be expanded, so each field is shown on a single line.
132	+	- This can be repeated for nested structures (and array / see section on arrays)
133	+	- pointers to structures will automatically be dereferenced to allow expanding
134	+
135	+	The Expression column will only show the name of the field, rather than the full "variable.fieldname". If dereferenced, for each level of dereferencing a "^" will be added.
136	+
137	+	Individual expanded entries can be dragged and dropped to the main list (anywhere outside an expanded area). This will create a new (copy) watch for "variable.fieldname". So the particular field can be watched, even if the structure is collapsed again.
138	+
139	+	##### Viewing/Expanding Arrays
140	+
141	+	Depends on the backend
142	+
143	+	- Arrays can be expanded, so each field is shown on a single line.
144	+	- This can be repeated for nested arrays (and structures / see section on structures(
145	+	- pointers to arrays will automatically be dereferenced to allow expanding
146	+
147	+	The Expression column will only show the index of the entry, rather than the full "variable\[123\]". If dereferenced, for each level of dereferencing a "^" will be added.
148	+
149	+	Expanded Arrays are shown paginated. The embedded toolbar lets you change between pages. It also allows to increase the page size.
150	+
151	+	Individual expanded entries can be dragged and dropped to the main list (anywhere outside an expanded area). This will create a new (copy) watch for "variable\[123\]". So the particular field can be watched, even if the structure is collapsed again.
152	+
153	+	## Special Values
154	+
155	+	\<invalid\>
156	+	Value currently not available. Can be caused, if the debugger is not active or the debugged app not currently paused.
157	+
158	+	\<evaluating\>
159	+	Value is currently retrieved. A result will be show soon
160	+
161	+	\<disabled\>
162	+	The expression is excluded from evaluation. See Disable/Enable buttons (light bulbs)
163	+
164	+	Error...
165	+	The value could not be evaluated. (Error in Expression or Variable not available in selected scope.
166	+
167	+	# Interface
168	+
169	+	## Toolbar
170	+
171	+	![](/wiki-images/5/5d/Debugger_power.png) Power
172	+	Enables/Disables all updates. This does not affect the enabled/disabled state of individual watches. This will freeze the current display.
173	+
174	+	![](/wiki-images/2/2f/Laz_add.png) Add
175	+	Add a new expression. This will open the Watch property dialog. (It is also possible to double click an empty line in the list)
176	+
177	+	![](/wiki-images/4/42/Debugger_enable.png) Enable/![](/wiki-images/c/c6/Debugger_disable.png) Disable
178	+	Enables/Disables individual watches from evaluation. This can be used to prevent spending time on evaluation, if a watch is not available in the current scope.
179	+
180	+	![](/wiki-images/c/cc/Laz_delete.png) Remove
181	+	Deletes the selected Watch(es)
182	+
183	+	![](/wiki-images/5/5e/Debugger_enable_all.png) Enable all/![](/wiki-images/5/5c/Debugger_disable_all.png) Disable all
184	+	Enables/Disables all watches from evaluation.
185	+
186	+	![](/wiki-images/6/6b/Menu_clean.png) Delete all
187	+	Cleans the list
188	+
189	+	![](/wiki-images/e/ef/Debugger_inspect.png) Detail-Pane
190	+	Open the detail-pane.
191	+
192	+	![](/wiki-images/2/2f/Menu_environment_options.png) Properties
193	+	Change the expression or properties of the current/selected watch. (Also possible by double clicking the watch)
194	+
195	+	![](/wiki-images/3/3c/Ce_implementation.png) Data-Address
196	+	Show hide the data-address column
197	+
198	+	## Context menu
199	+
200	+	![](/wiki-images/4/4b/Watch_List_popup.png)
201	+
202	+	Additional to the above functionality the context menu allows to:
203	+
204	+	Inspect
205	+	Opens the current watch in the Debug-Inspector
206	+
207	+	Evaluate/Modify
208	+	Opens the current watch in the Evaluate/Modify window
209	+
210	+	Create Data/Watch Breakpoint
211	+	Opens the dialog to create a new watchpoint based on the current watch (stop if wachted value is changed or accessed)
212	+
213	+	Copy Name
214	+	Copies the expression to the clipboard
215	+
216	+	Copy Value (quoted)
217	+	Copies the value to the clipboard (strings will be quoted, so they can be pasted into pascal code)
218	+
219	+	Copy RAW Value
220	+	Copies the value to the clipboard (strings will not be quoted, so they have actual tabs,cr,lf when being pasted)
221	+
222	+	Copy Data Address
223	+	Copy the data address, if available
224	+
225	+	## Drag and Drop
226	+
227	+	Watches can be dragged and dropped to change their order in the list.
228	+
229	+	If a structure or array is expanded, individual entries can be copied to the main list of watches.
230	+
231	+	# Watch Properties Dialog
232	+
233	+	![](/wiki-images/2/28/Watch_Properties.png)
234	+
235	+	Entries can be double-clicked to edit them.
236	+
237	+	Expression
238	+	An expression for which the evaluated value should be shown. Expressions can be local or global variables, ([[GDB Debugger Tips\|certain]]) properties, or pascal expressions (limited support, e.g. "a+1").
239	+
240	+	Repeat Count
241	+	Can be used to get array slices. The watch specifies the first element of the array "A\[7\]" (must have an index). With a "Repeat count" of 20, this shows A\[7\] to A\[26\]. It can also be used with a dynamic array (no index given). Then it specifies haw many elements to show, beginning with Item\[0\].
242	+
243	+	Digits
244	+	Not implemented.
245	+
246	+	Enabled
247	+	See Enable/Disable above.
248	+
249	+	Allow function calls
250	+	Must also be enabled in the global options and supported by the backend. [[FpDebug-Watches-FunctionEval]]
251	+
252	+	Run all threads while evaluating
253	+	Normally only the function will run and all threads (current and others) keep being paused. If however the function may wait for a lock hold by another thread, then it would block. This will run the function, and let the other threads run freely during that time. The current thread will be kept paused (it runs the function).
254	+
255	+	Use Instance class type
256	+	Objects are normally shown according to the declaration of the watched expression. Watching "Sender: TObject" will only show you data that is declared on TObject. However object variables can contain objects of inherited classes. Sender may be a TForm. Using this the debugger will find the actual class of the object and display all data.
257	+
258	+	Converter
259	+	[[IDE Window: Ide Options - Backend Value Converter]]
260	+
261	+	Style
262	+	How to display the data. If a style can not be applied, default style will be used.
263	+
264	+	# See also
265	+
266	+	- [[Debugger Setup\|Setup the debugger]]
267	+	- Watch-Points (Data-[[IDE Window:Breakpoints\|Breakpoints]])
268	+	- [[IDE Window: Evaluate/Modify\|Evaluate Window]]
269	+	- [[IDE Window: Variable Inspector\|Debug Inspector]]
270	+	- [[IDE Window: Debug History\|Debug History]]
271	+
272	+	---
273	+	From the Free Pascal wiki, page "IDE Window: Watch list", as it stood on 2023-06-28 after a change by Martin, out of the wiki's dump of 2024-05-26. Copyright stays with the author who wrote it, according to the old wiki's [[Licensing]] page. If you have concerns about this material, [message the admin](/wiki-contact).

Back to history