org.netbeans.spi.debugger.ui

Class MethodChooser

java.lang.Object

org.netbeans.spi.debugger.ui.MethodChooser

public class MethodChooser
extends Object

Support for Step Into action implementations. It allows the user to select directly in a source file a method call the debugger should step into. A simple graphical interface is provided. The user can navigate among available method calls. The navigation can be done using a keyboard as well as a mouse.

The method chooser is initialized by an url (pointing to a source file), an array of MethodChooser.Segment elements (each of them corresponds typically to a method call name in the source file) and an index of the segment element which is displayed as the default selection.

Optionally, two sets of (additional) shortcuts that confirm, resp. cancel the selection mode can be specified. It is also possible to pass a text, which should be shown at the editor pane's status line after the selection mode has been activated. This text serves as a hint to the user how to make the method call selection.

Method chooser does not use any special highlighting for the background of the area where the selection takes place. If it is required it can be done by attaching instances of Annotation to the proper source file's lines. These annotation should be added before calling MethodChooser.showUI() and removed after calling MethodChooser.releaseUI(boolean).

To display the method chooser's ui correctly, it is required to register HighlightsLayerFactory created by MethodChooser.createHighlihgtsLayerFactory() in an xml layer. An example follows.

    <folder name="Editors">
        <folder name="text">
            <folder name="x-java">
                <file name="org.netbeans.spi.editor.highlighting.HighlightsLayerFactory.instance">
                    <attr name="instanceCreate" methodvalue="org.netbeans.spi.debugger.ui.MethodChooser.createHighlihgtsLayerFactory"/>
                </file>
            </folder>
        </folder>
    </folder>

"x-java" should be replaced by the targeted mime type.

Since:

2.22

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static interface	MethodChooser.ReleaseListener An instance of MethodChooser.ReleaseListener can be registered using MethodChooser.addReleaseListener(org.netbeans.spi.debugger.ui.MethodChooser.ReleaseListener).
static class	MethodChooser.Segment Represents an interval of offsets in a document.

Constructor Summary

Constructors

Constructor and Description
MethodChooser(String url, MethodChooser.Segment[] segments, int initialIndex) Creates an instance of MethodChooser.
MethodChooser(String url, MethodChooser.Segment[] segments, int initialIndex, String hintText, KeyStroke[] stopEvents, KeyStroke[] confirmEvents) Creates an instance of MethodChooser.

Method Summary

Modifier and Type	Method and Description
void	addReleaseListener(MethodChooser.ReleaseListener listener) Registers MethodChooser.ReleaseListener.
static HighlightsLayerFactory	createHighlihgtsLayerFactory() This method should be referenced in xml layer files.
int	getSelectedIndex() Returns index of MethodChooser.Segment that is currently selected.
boolean	isUIActive() Can be used to check whether the selection mode is activated.
void	releaseUI(boolean performAction) Ends the method selection mode, clears all used ui elements.
void	removeReleaseListener(MethodChooser.ReleaseListener listener) Unregisters MethodChooser.ReleaseListener.
boolean	showUI() Sets up and displays the method selection mode.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

MethodChooser

public MethodChooser(String url,
                     MethodChooser.Segment[] segments,
                     int initialIndex)

Creates an instance of MethodChooser.

Parameters:

url - Url of the source file.

segments - Array of segments where each of the segments represents one method call. The user traverses the calls in the order given by the array.

initialIndex - Index of a call that should be preselected when the method chooser is shown.

MethodChooser

public MethodChooser(String url,
                     MethodChooser.Segment[] segments,
                     int initialIndex,
                     String hintText,
                     KeyStroke[] stopEvents,
                     KeyStroke[] confirmEvents)

Creates an instance of MethodChooser. Supports optional parameters.

Parameters:

url - Url of the source file.

segments - Array of segments where each of the segments represents one method call. The user traverses the calls in the order given by the array.

initialIndex - Index of a call that should be preselected when the method chooser is shown.

hintText - Text which is displayed in the editor pane's status line. Serves as a hint informing briefly the user how to make a selection.

stopEvents - Custom key strokes which should stop the selection mode. For example, it is possible to pass a KeyStroke corresponding to the shortcut of Step Over action. Then, whenever the shorcut is pressed, the selection mode is cancelled. The generated KeyEvent is not consumed thus can be handled and invokes Step Over action. Note that a method chooser can be always cancelled by Esc or by clicking outside the visualized area in the source editor.

confirmEvents - Custom key strokes which confirm the current selection. By default, a selection can be confirmed by Enter or Space Bar. It is possible to extend this set of confirmation keys.

Method Detail

showUI

public boolean showUI()

Sets up and displays the method selection mode.

Returns:

true if a JEditorPane has been found and the selection mode has been properly displayed

releaseUI

public void releaseUI(boolean performAction)

Ends the method selection mode, clears all used ui elements. Notifies each registered MethodChooser.ReleaseListener.

Parameters:

performAction - true indicates that the current selection should be used to perform an action, false means that the selection mode has beencancelled

isUIActive

public boolean isUIActive()

Can be used to check whether the selection mode is activated.

Returns:

true if the method selection mode is currently displayed

getSelectedIndex

public int getSelectedIndex()

Returns index of MethodChooser.Segment that is currently selected. If the method chooser has been released, it corresponds to the final selection made by the user.

Returns:

index of currently selected method

addReleaseListener

public void addReleaseListener(MethodChooser.ReleaseListener listener)

Registers MethodChooser.ReleaseListener. The listener is notified when the selection mode finishes. This occurs whenever the user comfirms (or cancels) the current selection. It also occrus when MethodChooser.releaseUI(boolean) is called.

Parameters:

listener - an instance of MethodChooser.ReleaseListener to be registered

removeReleaseListener

public void removeReleaseListener(MethodChooser.ReleaseListener listener)

Unregisters MethodChooser.ReleaseListener.

Parameters:

listener - an instance of MethodChooser.ReleaseListener to be unregistered

createHighlihgtsLayerFactory

public static HighlightsLayerFactory createHighlihgtsLayerFactory()

This method should be referenced in xml layer files. To display the method chooser ui correctly, it is required to register an instance of HighlightsLayerFactory using the following pattern.

    <folder name="Editors">
        <folder name="text">
            <folder name="x-java">
                <file name="org.netbeans.spi.editor.highlighting.HighlightsLayerFactory.instance">
                    <attr name="instanceCreate" methodvalue="org.netbeans.spi.debugger.ui.MethodChooser.createHighlihgtsLayerFactory"/>
                </file>
            </folder>
        </folder>
    </folder>

"x-java" should be replaced by the targeted mime type

Returns:

highligts layer factory that handles method chooser ui visualization