The NetBeans Debugger Interface: Stack View

Contents:

Introduction

The Stack view is used to display information about the frames for a thread.
The user uses this information to identify where the current point of execution
in the code is, and to understand how it got there. This also serves as a convenient
way for the user to get at the source code corresponding to other frames on
the stack.

[Note: Discussion during the beta period of NB 3.4 suggests that the objects
here should perhaps have been "Call List" and "Call Row"
rather than "Frame {List|Row}"]

Frame List

The frame list provides a list of the stack frames associated with a thread.

Appearance

The thread list is a standard debugging list component.

The initial set of columns showing in the list will be the name column.

If there are one or more frames, then one of them is always the "current"
frame.

Behavior

The list has no special operations associated with it.

Frame Row

Appearance

Standard Properties

All debugger engines must provide at least two properties for each frame:

Name: An identifier of the function or method corresponding to the frame

Location: The file and line number of the source code corresponding to the
current instruction.

Name Column

There can be a small or a large amount of information associated with the name
of a frame. For example:

Different sets of users may wish to see this information differently. Therefore
the Stack View will provide some display settings which will allow the user
to change the default appearance. [not in 3.4]

The default appearance of the name will be a "partially qualified"
function/method name, and no arguments. This means a classname will be shown
when available along with the function/method name. Thus:

Hashtable.put

One display setting will allow the user to show the fully qualified name (java.util.Hashtable.put),
while another will allow the function/method arguments to be shown (java.util.Hashtable.put(key="blah",
value="blah))

The name column will have an icon that distinguishes the current frame from
the non-current frame. These icons may be badged by the individual debugging
engines, as well.

Note that this column is sorted by the order which the frames have been added
to the stack, not by an alphabetic ordering.

Location Column

This shows the filename and line number (separated by a colon) corresponding
to the current execution point in the source code.

[Optional for 3.4] This may be shown as a hyperlink.

Behavior

Required Actions

Make Current: Makes the frame the current one. This also shows the source
code, if available, corresponding to the frame.

Show Source: Shows the source code corresponding to the selected frame.
[Not in 3.4]

A double-click on any non-editable cell in the row should have the effect
of making the frame the current one.

Additional Actions

Debugging engines are encouraged to support these actions, if possible:

Pop to This Frame: If only a single frame is selected, and it isn't the
most recent frame, pops all frames from the most recent one to the frame immediately
before the selected frame. If the current frame was among those popped, then
the new "most recent" frame is made the current one. [In 3.4. the
name was made "Pop to Here"]

Pop Most Recent Frame: As long as there are more than one frame on the stack,
this will pop the most recently added frame. (this is equivalent to selecting
the second-to-last frame and choosing "Pop to This Frame"). [in
3.4, this was named "Pop Topmost Call"]

Contextual Menu

The contextual menu for a frame should look like the following (where actions
not supported by the debugger engine should not be shown):

Make Current
--------
Show Source
--------
Pop To This Frame
Pop Most Recent Frame
--------
List Options
--------
Properties

If multiple frames are selected, the "Make Current" and "Show Source"
items must be unavailable (disabled). The "Make Current" item should
always be drawn in bold since it is equivalent to a double-click on the row.

The "Column" submenu in "List Options" should have these
items appended to its end: [Not in 3.4]

[ ] Show Fully Qualified Name
[ ] Show Arguments

These should change how the contents of the Name column are displayed, as
discussed above.

Divider Rows

[This is not exposed in NB 3.4, and may not exist]

Sometimes it is useful to indicate that some frames are, in some way, special
or distinguished. For example, when debugging a native language program on a
*nix system, a signal may be received by the thread and the thread may start
executing signal handling functions. Alternately, the user may invoke a function
in the debugger, and the frames that result from the call to the debugger should
be distinguished from other frames.

Appearance

In these cases, a special "divider row" is used to indicate that
the more recent frames are not ordinary frames, and the recent frames are colored
in a different color [The frame coloring is optional for 3.4]. The following
illustration demonstrates this:

For this release, the divider only needs to be shown in the "name"
column.