[jdt-debug-dev] Details on how to better present/manipulate breakpoints

[Darin_Swanson@xxxxxxx]

(Please read and comment as you see fit)

The overall goal of this work is to make breakpoint properties easily discernible and manipulated by the user.  To reach this goal, we need to make it easier for plugin developers to manipulate breakpoint properties in a consistent manner in every location that breakpoints are presented.

Currently it is difficult to rapidly configure multiple attributes of a breakpoint.

Currently there is no support to enable plugin developers to contribute actions to manipulate breakpoints from the context menu of the editor ruler.

This is the proposal on how to address these key issues as well as others.

Breakpoint actions in context menus
I have coded a prototype action that is contributed via XML to the ruler of an abstract text editor.  Note that this prototype relies on resolution of bug 3578 http://bugs.eclipse.org/bugs/show_bug.cgi?id=3578

Using this as a proof of concept, I propose the creation of the following action hierarchy to be provided by the debug ui.
BreakpointAction 
        GoToFileAction
        RemoveAction
        ManageEnablementAction
        BreakpointPropertiesAction 

The  abstract  BreakpointAction will implement both IViewActionDelegate and IEditorActionDelegate.  This class will generically provide access to any selected breakpoint.  This will mean if the action was contributed as an IEditorActionDelegate, it will handle the interaction with the ruler of the text editor.  

Example XML contribution by JDT debug ui plugin
- <viewerContribution id="org.eclipse.jdt.debug.ui.CURulerPopupActions" targetID="#CompilationUnitRulerContext">
  <action id="org.eclipse.debug.ui.actions.ManageBreakpointEnablement"
 label="%manageBreakpointEnablementAction.label" menubarPath="additions"
 class="org.eclipse.debug.ui.actions.ManageBreakpointEnablementAction" /> 
  </viewerContribution>
Other plugin developers can use/extend these actions to provide the state manipulation of any breakpoint  from the context menu of the editor ruler.  The plugin specific actions can be contributed (as above) using the viewerContribution flavor of the popup menu extension point.

Other breakpoint state manipulation actions will be contributed to views using the objectContribution flavor of the popup menu extension point.  For example, the AccessWatchpointToggleAction will be contributed for IJavaWatchpoint by the jdt debug ui plugin.  This will remove the current problem of the breakpoints view context menu containing actions that are totally irrelevant to the currently selected breakpoint.  

I propose keeping the single operation actions for quick and easily manipulation of breakpoints.  If a single operation action needs to realize a dialog, a mechanism could be provided to realize the properties dialog and set focus to the correct portion of the dialog. The BreakpointPropertiesAction will provide the mechanism for easily changing multiple properties for a single breakpoint.

Breakpoint property page
The breakpoint property page will be realized as a dialog when the user invoked the BreakpointPropertiesAction . Other actions that need to realize a dialog to change a property (current example: setting the hit count) , could invoke the properties dialog and indicate which property should be given initial attention.

Three possibilities for the definition of the contents of the breakpoint properties dialog.

Classic property page
        Pros
                existing extension point and support from the framework
        Cons
                sparse layout.  The current set of breakpoints have attributes that can be presented/manipulated in a small area of page real estate.
                Most will look similar to the Launcher property page for a project.

Example definition:
<extension
        point="org.eclipse.ui.propertyPages">
        <page
                id="org.eclipse.jdt.debug.ui.propertyPages.HitCountPage" 
                name="Hit Count"
                objectClass="org.eclipse.jdt.debug.core.IJavaBreakpoint"
                class="org.eclipse.jdt.internal.debug.ui.HitCountPropertyPage">
    </page> 
</extension>

Breakpoint property dialog1
The debug ui would define a new breakpointPropertyControls extension point
        <extension-point name="Breakpoint Property Controls" id="breakpointPropertyControls"/>

Example definition:

 <extension
        point="org.eclipse.debug.ui.breakpointPropertyControls">
        <breakpointPropertyControl
                id="org.eclipse.jdt.debug.ui.breakpointPropertyControls.JavaHitCount"
                name="Hit Count"
                objectClass="org.eclipse.jdt.debug.core.IJavaBreakpoint"
                class="org.eclipse.jdt.internal.debug.core.breakpoints.JavaHitCountControl">
    </breakpointPropertyControl>
 </extension>

The attribute class would be the fully qualified name of a class that implements IBreakpointPropertyControl.  
        public Control createPropertyControl(IBreakpointPropertyDialog dialog, Composite parent);
       
IBreakpointPropertyDialog definition:
        public void refreshStatus();
The breakpoint property dialog would be composed of two panes:
        a left pane that is a list of all of the property controls contributed for the breakpoint (e.g. enabled, hitcount, modification, access...)
        a right pane that would display the controls contributed by all plugins
Selecting in the left pane would set focus to the corresponding control in the right pane.  Both panes would be scrollable.
       
Pros
        better layout for breakpoint properties
        able to see all the properties at once (at least for "common" breakpoints)
Cons
        layout issues of contributed composites
        different presentation via the "Properties" menu item

Breakpoint property dialog2
Similar layout to the new launch configuration dialog.  Each breakpoint type could have a tab contributed by plugins.  The tab would allow manipulation of the properties of the breakpoint.

The debug ui would define a new breakpointPropertyTabs extension point
        <extension-point name="Breakpoint Property Tabs" id="breakpointPropertyTabs"/>

Example definition:
<extension point = "org.eclipse.debug.ui.breakpointPropertyTabs">
        <breakpointPropertyTab
                id="org.eclipse.jdt.debug.breakpointPropertyTab.IJavaBreakpointTab"
                objectClass ="org.eclipse.jdt.debug.IJavaBreakpoint"
                class="org.eclipse.jdt.internal.debug.ui.IJavaBreakpointTab"
                name="Java Breakpoint Properties">
        </breakpointPropertyTab>
</extension>

The attribute class would be the fully qualified name of a class that implements IBreakpointPropertyTab.  
        public Control createPropertyTab(IBreakpointPropertyDialog dialog, TabItem tab);

IBreakpointPropertyDialog
        public void refreshStatus();

Pros
        Possibly a better layout(?)
Cons
        Impossible to see all of the attributes at once
        Forces the user to associate the property with the breakpoint "type"

Other ideas that were considered
Making better use of the breakpoints view
        Control clicking a breakpoint in the breakpoints view would split pane the breakpoints view to show the properties pane for that                         breakpoint.  This was rejected as it did not address the requirement of equal representation for breakpoints presented in other locations such as         in editor rulers.


My current plan is to implement Breakpoint property dialog1.

Breakpoints view improvements
Improvements in breakpoint icons,
        breakpoints of different types will be distinguishable by overlay icons.
Context menu will only contain actions relevant to the currently selected breakpoint
No hard wired actions
Multi-select property manipulation
        All relevant actions are expected to work on multi-selection.  A toggle action (such as enable/disable) will be presented as two distinct actions in         multi-select situations.

Other
Hover properties mechanism
To quickly display the relevant properties of a breakpoint, I propose we could implement a hover properties mechanism in the                         breakpoints view.  Plugin developers could use the extension point to provide String descriptions of a breakpoint property, that would be                 presented to the user in a hover.
        Example definition:
        <extension point="org.eclipse.debug.ui.breakpointHovers">
                  <breakpointHover id="org.eclipse.jdt.internal.debug.ui.JavaDebugHover"
                          class="org.eclipse.jdt.internal.debug.ui.JavaBreakpointHoverContributor"
                        objectClass="org.eclipse.jdt.debug.core.IJavaBreakpoint">
                </breakpointHover>        
          </extension>

The attribute class would be the fully qualified name of a class that implements IBreakpointHoverContributor.  
        IBreakpointHoverContributor
                public String getBreakpointHoverInfo(IBreakpoint)
All registered hover contributors would be polled for info for a selected breakpoint.  The resulting string would be presented as the hover.  In the breakpoints view, this could work invoked from either an action (ShowBreakpointPropertiesAction ) or through the traditional hover mechanism.  For breakpoints in an editor ruler, the hover would need to be invoked from the ShowBreakpointPropertiesAction (I did not investigate the necessary work to have traditional hover work in the editor's ruler).  The ShowBreakpointPropertiesAction would be provided by the debug ui.