<type>documentation</type>
<domain>debug</domain>
<id>setting-breakpoints</id>
<title>Setting Breakpoints</title>
<date>$Date$</date>
<version>$Revision$</version>
<product>all</product>

Breakpoints can be set on source code by opening the source file and clicking
on the breakpoint margin to the left of a line of source code. Right-clicking
on the breakpoint margin will display a context menu with additional
breakpoint operations and options. 
~~~if WINGPRO:
In Wing Pro, the
`Breakpoints <script:show_panel#panel_type="debug-breakpoints">`__ tool in 
the ``Tools`` menu can be used to view, modify, or
remove defined breakpoints.
~~~
Alternatively, the ``Debug`` menu or the toolbar's breakpoint icons can be used to set or
clear breakpoints at the current line of source (where the insertion caret or
selection is located).

~~~if WINGPRO:

Breakpoint Types
................

In Wing Pro, the following types of breakpoints are available:

**Regular** breakpoints will always cause the debugger to stop on a given line of code,
whenever that code is reached.

**Conditional** breakpoints contain an expression that is evaluated each time the
breakpoint is reached. The debugger will stop only if the condition evaluates to ``True``
(any non-zero, non-empty, non-``None`` value, as defined by Python). You may edit the
condition of any existing breakpoint with the ``Edit Breakpoint Condition...`` item in the
``Breakpoint Options`` group of the ``Debug`` menu, by right clicking on the breakpoint,
or in the ``Breakpoints`` tool.

**Temporary** breakpoints are removed automatically after the first time they are
encountered. No record of the breakpoint is retained for future debug sessions.

Breakpoint Attributes
.....................

Once breakpoints have been defined, you can operate on them in a number of ways to alter
their behavior. These operations are available in the ``Debug`` menu, in the breakpoint
margin's right-click context menu, and from the ``Breakpoints`` tool:
  
**Ignore Count** ignores a breakpoint a given number of times.  The debugger will only
stop if it is reached more often than that. The ignore count is reset to its original
value with each new debug run. Use the ``Breakpoint`` tool to monitor the remaining number
of times a breakpoint will be ignored.

**Disable/Enable** can be used to temporarily disable and subsequently re-enable
breakpoints. Any disabled breakpoint will be ignored until re-enabled.

Breakpoints Tool
................

The `Breakpoints <script:show_panel#panel_type="debug-breakpoints">`__ tool, available in
the ``Tools`` menu, displays a list of all currently defined breakpoints. The following
columns of data are provided:

**Enabled** is checked if the breakpoint is enabled.

**Location** gives the file and line number where the breakpoint is set.

**Condition** lists the conditional that must be true for the breakpoint to 
cause the debug process to stop.  This is blank if the breakpoint is not conditional.
  
**Temporary** is checked if the breakpoint is a temporary one-time breakpoint.

**Ignores** indicates the number of times the breakpoint should be ignored before it
causes the debugger to stop.

**Ignores Left** shows the number of ignores left for the breakpoint, for the
current debug process.

**Hits** shows the number of times the breakpoint has been reached in the current
debug process, if any.

Most of these values can be edited by clicking on the list. To delete the selected
breakpoints, press the ``Delete`` key.

To visit the file and line number where a breakpoint is located, double click on it in the
list or select ``Show Breakpoint`` from the right-click context menu. Additional editing
options are also available from this context menu.

Keyboard Modifiers for Breakpoint Margin
........................................

Clicking on the breakpoint margin will toggle to insert a regular
breakpoint or remove an existing breakpoint.  You can also shift-click 
to insert a conditional breakpoint, and control-click to insert a breakpoint 
and set an ignore count for it. 

When a breakpoint is already found on the 
line, shift-click will disable or enable it, control-click will set its 
ignore count, and shift-control-click will set or edit the breakpoint conditional.

~~~

