Running the project

While working on your project, you are going to want to test it to make sure it works like you expect. You can do this by clicking the Run button on the toolbar, selecting Project > Run from the menu or pressing ⌘ R (Ctrl R on Windows and Linux). When you run your project like this, you are running it in debug mode. In this mode, Xojo is communicating in the background with your app. In the Workspace, a separate tab (containing the debugger) appears with the name of your app.

Tip

If you are developing a iOS application and want to test it in the iOS Simulator on a specific device, choose Project > Run On, then select the device you wish to use for testing.

When this tab is selected, the Debugger displays. In this tab, the Navigator displays the Run section and the name of the app being debugged.

If you are new to debugging, read the Introduction to Debugging and Debugger Usage pages.

Debugger

The debugger can be used to watch how your app runs. It is divided into three main areas:

Stack - Displays the order that the code in your application was called.
Variables - Displays variables and their current values.
Source Code - Displays the source code that is currently running with the current line highlighted when the debugger is paused.

To see the Stack, Variables and currently running source code, you can set a breakpoint in your source code or you can click the pause button on the toolbar.

Command bar

The debugger Command Bar has these commands:

Pause - Pauses the app at the currently running line of code. The debugger will display the line of code highlighted in gray.
Stop - Stops the running app, closing the debugger.
Step - When Paused, steps through the code one line at a time.
Step In - When Paused, if the current line of code is a method then this action steps you into the first line of code in the method.
Step Out - When Paused, if you are within a method, this action runs the rest of the code in the method and pauses debugging at the line of code after the method call.
View Source - Takes you to the project item and displays the source code so that you can edit it. Changes you make to the code do not take affect until you run the project again.

Using the Debugger

You have three ways to Pause the debugger so you can review running code:

Use the Pause button, which does not allow you to control where the code will pause.
Set a breakpoint in your code. (see below)
Use the Break command in your code.

Once you are in the debugger, you can view the source code but not make any changes to it. To edit code, use the View Source button to find the code in the project to edit. Any changes you make do not take affect until you run the project again.

To resume running your app after it has paused, click the Resume button on the toolbar, which appears in place of the Run button. You can also completely stop the running app by clicking the Stop button on the toolbar. This does not take you to the debugger since the app has been terminated, but it can be useful if you need to quickly stop the app because of an infinite loop or some other programming error.

If you are new to Xojo, check out the Introduction to Debugging and Using the Debugger pages.

Stack

The Stack area (lower left corner) displays the name of the objects in the order they were called with the current object at the top of the list. You can click on other items in the list to view the code that previously ran.

The PopupMenu in the Stack area usually just displays “Main Thread”. If you are specifically using Threading, you can use this popup to look at code that is running in other threads.

Variables

The Variables area (lower right corner) displays the variables that are local to the currently running method. The left column displays variable names and the right displays their values. You can click on values on the right side to display them in more detail. Some values (such as numbers and strings) can have their values edited so that you can affect the outcome of subsequent code.

As you click to view details of variables, the PopupMenu in the Variables section changes to display what is being viewed. You can use this popup to go back to the prior variables.

In addition, the “Globals” item in the Variables section will let you review global values in the app, such as modules and the contents of the App object.

To see just the variables/properties whose name matches a set of characters, use the Variables Filter.

To have the Debugger stop when a variable value changes (called a Watchpoint), right-click on the variable then choose Watch from the contextual menu. To stop watching a variable, right-click on the variable and chose Unwatch.

Setting breakpoints

In the Code Editor, the gutter in the left margin shows horizontal dashes for lines of code that can have their breakpoint set. To set the breakpoint, just click on the dash. This causes a red dot to appear indicating that a breakpoint is set. To turn off the breakpoint, click on the red circle. You can also set breakpoints using Project > Breakpoint > Turn on (⌘ \ on macOS, Ctrl \ on Windows and Linux).

To disable all the breakpoints in your app, use Project > Breakpoint > Clear All. To view all the breakpoints in your project, choose Project > Breakpoint > Show All, which displays the breakpoints in the Find panel.

You can also use the Break command to cause your application to pause. When your code reaches a Break command, the debugger pauses at that line. In a standalone app, the Break command is ignored. You can use the Break command to conditionally pause your app and activate the debugger based on specific situations.

For example, if your app is in a loop, you may only want to break into the debugger when a certain value is reached:

For i As Integer = 1 To 100
  If i = 50 Then Break
Next

Setting watchpoints

Sometimes you will not want to break into the Debugger on a specific line but instead when a variable's value changes. That's where Watchpoints are used. A Watchpoint monitors a variable as the project is running in the IDE and breaks into the Debugger when the value changes. Beyond just changing, you can set a criteria (an expression) that will be evaluated and then break into the Debugger only when the expression is true.

To begin watching a variable, you will need to be in the Debugger. Once there, right-click on it in the Variables list then choose Watch from the contextual menu that appears. The next time the variable changes, the Debugger will pause. The Watchpoints list will then be displayed allowing you to see the current and previous values

To set the expression for a variable that has a watchpoint, right-click the variable then choose Edit Watch Expression from the contextual menu.

There are five different types of expressions. The expression types available will change based upon the type of variable:

Change

The value of the variable has changed. This is the default type. If you simply set a watchpoint but do not edit the expression, this is the expression the watchpoint has by default.

Equals

The value is equal to the value you specify.

Greater Than

The value is greater than the value you specify.

Less Than

The value is less than the value you specify.

Range

The value is between the two values you specify.

Breaking on a watchpoint

When the Debugger encounters a watchpoint whose expression is true, it stops on that line following the line that changed the value just as if you'd put a breakpoint there. The Watchpoints pane is then automatically displayed instead of the Variables pane. You can use the popupmenu to switch back and forth between the two panes.

The Watchpoints pane shows the current value as well as the previous value for comparison.

The watchpoints pane showing a variable that is being watched, its current value and its previous value.

Watchpoint notes

For strings, an option is provided to specify that the comparison should be case-sensitive. All string comparisons are made by applying Xojo's standard string comparison rules.

For objects, the name of another variable that contains an object can be specified. In the case of the Equals comparison for example, this would mean that when the variable being watched is assigned the value of the other variable specified, the watchpoint expression will be true and the watchpoint will be triggered.

Arrays, computed properties and structures are not yet supported.

A watchpoint remain active until for the entire debugging session or until you unwatch it.

Note

Watchpoints are not currently supported for Android projects.